/*
SevenSegmentTM1637 - class to control a 4 digit seven segment display with a TM1636 or TM1637 driver IC
Created by Bram Harmsen, September 25, 2015
Released into the public domain.
Licence: GNU GENERAL PUBLIC LICENSE V2.0
# Changelog
v1.0 25-10-2015
* First release
*/
#ifndef SevenSegmentTM1637_H
#define SevenSegmentTM1637_H
#if ARDUINO >= 100
#include <Arduino.h>
#else
#include <WProgram.h>
#endif
#if (defined(__AVR__))
#include <avr/pgmspace.h> // Used for PROGMEM (arduino)
#else
#include <pgmspace.h> // Used for PROGMEM (esp8266)
#endif
// COMPILE TIME USER CONFIG ////////////////////////////////////////////////////
#define TM1637_DEBUG false // true for serial debugging
#define TM1637_BEGIN_DELAY 500 // ms
#define TM1637_PRINT_BUFFER_SIZE 128 // lower if you don't need it
// Default values //////////////////////////////////////////////////////////////
#define TM1637_DEFAULT_PRINT_DELAY 300 // 300 ms delay between characters
#define TM1637_DEFAULT_BLINK_DELAY 50 // ms
#define TM1637_DEFAULT_BLINK_REPEAT 10
#define TM1637_DEFAULT_CURSOR_POS 0 // 0-MAX-1 (e.g 3)
#define TM1637_DEFAULT_COLON_ON false //
#define TM1637_DEFAULT_BACKLIGHT 100 // 0..100
#define TM1637_MAX_LINES 1 // number of display lines
#define TM1637_MAX_COLOM 4 // number of coloms (digits)
#define TM1637_MAX_CHARS 128
// PROGRAM CONFIG (ONLY CHANGE WHEN YOU KNOW WHAT YOU RE DOING:)////////////////
#define TM1637_CLK_DELAY_US 5 // clock delay for communication
// mine works with 1us, perhaps increase if display does not function ( tested upto 1ms)
// COMMANDS ////////////////////////////////////////////////////////////////////
#define TM1637_COM_SET_DATA B01000000 // 0x40 (1) Data set
#define TM1637_COM_SET_ADR B11000000 // 0xC0 (2) Address command set
#define TM1637_COM_SET_DISPLAY B10000000 // 0x80 (3) Display control command set
// Data set (1) (use logical OR to contruct complete command)
#define TM1637_SET_DATA_WRITE B00000000 // Write data to the display register
#define TM1637_SET_DATA_READ B00000010 // Read the key scan data
#define TM1637_SET_DATA_A_ADDR B00000000 // Automatic address increment
#define TM1637_SET_DATA_F_ADDR B00000100 // Fixed address
#define TM1637_SET_DATA_M_NORM B00000000 // Normal mode
#define TM1637_SET_DATA_M_TEST B00100000 // Test mode
// Address settings (2) (use logical OR to contruct complete command)
#define TM1637_SET_ADR_00H B0000000 // addr 00
#define TM1637_SET_ADR_01H B0000001 // addr 01
#define TM1637_SET_ADR_02H B0000010 // addr 02
#define TM1637_SET_ADR_03H B0000011 // addr 03
#define TM1637_SET_ADR_04H B0000100 // addr 04 (only TM1637)
#define TM1637_SET_ADR_05H B0000101 // addr 05 (only TM1637)
// The command is used to set the display register address; if the address is set to 0C4H or higher, the data is ignored, until the effective address is set; when the power is on, the default is set to 00H address.
// Display control command set (use logical OR to consruct complete command)
#define TM1637_SET_DISPLAY_1 B0000000 // Pulse width 1/16 (0.0625) (0)
#define TM1637_SET_DISPLAY_2 B0000001 // Pulse width 2/16 (0.0625) (1)
#define TM1637_SET_DISPLAY_4 B0000010 // Pulse width 4/16 (0.0625) (2)
#define TM1637_SET_DISPLAY_10 B0000011 // Pulse width 10/16 (0.0625) (3)
#define TM1637_SET_DISPLAY_11 B0000100 // Pulse width 11/16 (0.0625) (4)
#define TM1637_SET_DISPLAY_12 B0000101 // Pulse width 12/16 (0.0625) (5)
#define TM1637_SET_DISPLAY_13 B0000110 // Pulse width 13/16 (0.0625) (6)
#define TM1637_SET_DISPLAY_14 B0000111 // Pulse width 14/16 (0.0625) (7)
#define TM1637_SET_DISPLAY_OFF B0000000 // OFF
#define TM1637_SET_DISPLAY_ON B0001000 // ON
// there are a total of 8 brighness values, plus off
// PROTOCOL SPECIFICATION
/*
* Structure
* START COMMAND ACK STOP set config or display
* START ADR_CMD DATA ACK STOP sets single digit
* START ADR_CMD DATA0 .. DATAN ACK STOP sets multiple digits when in auto mode
*
* There are basicly three things you can do:
* 1. Set some configuration values
* - read/write mode, auto/manual address, normal/test mode
* 2. Set a (starting) address followed by 1 or N data bytes
* 3. Set the display brightness (pwm) 0-7 and on or off
*
* From the datasheet it might seem that you always have to perform all three commands; setting configuration, setting address and data bytes and display. I'v tested this and this is not true. You can just set only one of these three. But ofcourse you have to make sure that your configuration is set properly. For example if you haven't set the configuration to automatic addresses, you can't just send out 4 data bytes, it won't work. Simlilair, if your display is off and you write some data to it, it won't display. On the other hand most default setting are what you want most of the time.
*/
class SevenSegmentTM1637 : public Print {
public:
// LIQUID CRISTAL API ///////////////////////////////////////////////////////
/* See http://playground.arduino.cc/Code/LCDAPI for more details.
/* Constructor
@param [in] pinClk clock pin (any digital pin)
@param [in] pinDIO digital output pin (any digital pin)
*/
SevenSegmentTM1637(uint8_t pinClk, uint8_t pinDIO);
/* Initializes the display
* Initializes the display, sets some text and blinks the display
@param [in] cols optional: number of coloms (digits)
@param [in] rows optional: number of rows
*/
void init(uint8_t cols = TM1637_MAX_COLOM, uint8_t rows = TM1637_MAX_LINES);
/* Implemented for compatibility, see begin() above */
void begin(uint8_t cols = TM1637_MAX_COLOM, uint8_t rows = TM1637_MAX_LINES);
// Print class inheritance ///////////////////////////////////////////////////
/* See https://github.com/arduino/Arduino/blob/master/hardware/arduino/avr/cores/arduino/Print.h for more details
/* This library inherent the Print class, this means that all regular print function can be used. For example:
* printing a number: print(78)
* printint a number in BIN, OCT, HEX..: print(78, BIN)
* printing a float: print(2.85)
* printing a PROGMEM c string: print(F("Arduino"))
*
* Also the more low level write() function can be used. (Actually all print function eventually call one of these write methods, every class that wants to inherent from the Print class needs to implement these)
*/
size_t write(uint8_t byte);
size_t write(const char* str);
size_t write(const uint8_t* buffer, size_t size);
/* Clears the display
* Writes zero to all digits and segments, display off.
*/
void clear(void);
/* Sets the cursor position to zero
*/
void home(void);
/* Sets the cursor position to a specfic position
*
@param [in] col colomn (position)
*/
void setCursor(uint8_t row, uint8_t col);
// Liquid cristal optional //////////////////////////////////////////////////
/* Sets the display backlight
* The display has 8 PWM modes and an off mode. The function accepts a value from 0 to 100, where 80-100 are the same; full brighness.
@param [in] value brightness value (0..80(100))
*/
void setBacklight(uint8_t value);
/* Sets the display contrast (identical to brightness)
* This function is mainly for compatibility with the LCD API
*/
void setContrast(uint8_t value);
/* Turns the display ON
* Identical to setting the brightness to the default value.
*/
void on(void);
/* Turns the display ON
* Identical to setting the brightness to zero and clearing the display.
*/
void off(void);
// SevenSegmentTM1637 METHODS ///////////////////////////////////////////////
/* Blink the last printed text
*
@param [in] blinkDelay optional: blink delay in ms
@param [in] repeats optional: number of blink repeats
*/
void blink(uint8_t blinkDelay = TM1637_DEFAULT_BLINK_DELAY, uint8_t repeats = TM1637_DEFAULT_BLINK_REPEAT, uint8_t maxBacklight=100, uint8_t minBacklight=0);
// getters and setters ///////////////////////////////////////////////////////
/* Turn the colon on or off
* When turing the colon on, the next displayed text/numbers will have a colon
@param [in] setToOn sets the colon to on or off
*/
void setColonOn(bool setToOn);
/* Get the currrent colon setting
*/
bool getColonOn(void);
/* Sets the delay for scrolling text
* When printing more than four characters/ the display will scroll, this setting determines the scrolling speed in ms
@param [in] printDelay the print delay in ms
*/
void setPrintDelay(uint16_t printDelay);
// helpers //////////////////////////////////////////////////////////////////
/* Encodes a character to sevensegment binairy
*
@param [in] c a character to encode
*/
uint8_t encode(char c);
/* Encodes a single digit to sevensegment binairy
*
@param [in] d a digit to encode
*/
uint8_t encode(int16_t d);
/* Encodes a null terminated c string (char array) to sevensegment binairy
*
@param [out] buffer holds the encodes char array
@param [in] str the c string to encode
@param [in] bufferSize the size/length of the buffer
*/
size_t encode(uint8_t* buffer, const char* str, size_t bufferSize);
/* Encodes a byte array to sevensegment binairy
*
@param [out] buffer holds the encodes char array
@param [in] byteArr the byte array to encode
@param [in] bufferSize the size/length of the buffer
*/
size_t encode(uint8_t* buffer, const uint8_t* byteArr, size_t arrSize);
/* Shift an array one position to the left
@param [out] buffer the buffer to be shifted
@param [in] length the length to the buffer
*/
void shiftLeft(uint8_t* buffer, size_t length);
// SevenSegmentTM1637 low level methods (use when you know what you're doing)
/* Prints raw (encoded) bytes to the display
* A
* ___
* * F | | B
* X -G-
* * E | | C
* ___
* D
* Bit: 76543210
* Segment: XGFEDCBA
*
* For example to print an H, you would set bits BCEFG, this gives B01110110 in binary or 118 in decimal or 0x76 in HEX.
* Bit 7 (X) only applies to the second digit and sets the colon
*
/* Print raw (binary encodes) bytes to the display
@param [in] rawBytes Array of raw bytes
@param [in] length optional: length to print to display
@param [in] position optional: Start position
*/
void printRaw(const uint8_t* rawBytes, size_t length = 4, uint8_t position = 0);
/* Print raw (binary encodes) bytes to the display
@param [in] rawByte Raw byte
@param [in] position optional: Start position
*/
void printRaw(uint8_t rawByte, uint8_t position);
/* Write command to IC TM1637
@param [in] cmd command to send
@return acknowledged? command was (successful) acknowledged
*/
bool command(uint8_t cmd) const;
bool command(const uint8_t* command, uint8_t length) const;
/* Read bytes from IC TM1637
* The IC also can read the state of a keypad? TODO untested
*/
uint8_t comReadByte(void) const;
/* Write a single command to the display
@param [in] cmd command to send
*/
void comWriteByte(uint8_t command) const;
/* Send start signal
* Send the start signal for serial communication
*/
void comStart(void) const;
/* Send stop signal
* Send the stop signal for serial communication
*/
void comStop(void) const;
/* Get command acknowledged
* Get acknowledge signal (command was succesful received)
*/
bool comAck(void) const;
/* Static version of low level function
* If using more than one display, this saves some space since these methods will be shared among all instances/objects of the class
*/
static bool command(uint8_t pinClk, uint8_t pinDIO, uint8_t cmd);
static bool command(uint8_t pinClk, uint8_t pinDIO, const uint8_t* command, uint8_t length);
static void comStart(uint8_t pinClk, uint8_t pinDIO);
static void comWriteByte(uint8_t pinClk, uint8_t pinDIO, uint8_t command);
static bool comAck(uint8_t pinClk, uint8_t pinDIO);
static void comStop(uint8_t pinClk, uint8_t pinDIO);
protected:
const uint8_t _pinClk; // clock pin
const uint8_t _pinDIO; // digital out pin
uint8_t _numCols; // number of columns
uint8_t _numRows; // number of rows
uint8_t _backLightValue; // brightness of the display (0..100)
uint8_t _cursorPos; // current cursor position
uint16_t _printDelay; // print delay in ms (multiple chars)
uint8_t _colonOn; // colon bit if set
uint8_t _rawBuffer[TM1637_MAX_COLOM];// hold the last chars printed to display
};
#define TM1637_COLON_BIT B10000000
// ASCII MAPPINGS
#define TM1637_CHAR_SPACE B00000000 // 32 (ASCII)
#define TM1637_CHAR_EXC B00000110
#define TM1637_CHAR_D_QUOTE B00100010
#define TM1637_CHAR_POUND B01110110
#define TM1637_CHAR_DOLLAR B01101101
#define TM1637_CHAR_PERC B00100100
#define TM1637_CHAR_AMP B01111111
#define TM1637_CHAR_S_QUOTE B00100000
#define TM1637_CHAR_L_BRACKET B00111001
#define TM1637_CHAR_R_BRACKET B00001111
#define TM1637_CHAR_STAR B01011100
#define TM1637_CHAR_PLUS B01010000
#define TM1637_CHAR_COMMA B00010000
#define TM1637_CHAR_MIN B01000000
#define TM1637_CHAR_DOT B00001000
#define TM1637_CHAR_F_SLASH B00000110
#define TM1637_CHAR_0 B00111111 // 48
#define TM1637_CHAR_1 B00000110
#define TM1637_CHAR_2 B01011011
#define TM1637_CHAR_3 B01001111
#define TM1637_CHAR_4 B01100110
#define TM1637_CHAR_5 B01101101
#define TM1637_CHAR_6 B01111101
#define TM1637_CHAR_7 B00000111
#define TM1637_CHAR_8 B01111111
#define TM1637_CHAR_9 B01101111
#define TM1637_CHAR_COLON B00110000
#define TM1637_CHAR_S_COLON B00110000
#define TM1637_CHAR_LESS B01011000
#define TM1637_CHAR_EQUAL B01001000
#define TM1637_CHAR_GREAT B01001100
#define TM1637_CHAR_QUEST B01010011
#define TM1637_CHAR_AT B01011111
#define TM1637_CHAR_A B01110111 // 65 (ASCII)
#define TM1637_CHAR_B B01111111
#define TM1637_CHAR_C B00111001
#define TM1637_CHAR_D TM1637_CHAR_d
#define TM1637_CHAR_E B01111001
#define TM1637_CHAR_F B01110001
#define TM1637_CHAR_G B00111101
#define TM1637_CHAR_H B01110110
#define TM1637_CHAR_I B00000110
#define TM1637_CHAR_J B00001110
#define TM1637_CHAR_K B01110101
#define TM1637_CHAR_L B00111000
#define TM1637_CHAR_M B00010101
#define TM1637_CHAR_N B00110111
#define TM1637_CHAR_O B00111111
#define TM1637_CHAR_P B01110011
#define TM1637_CHAR_Q B01100111
#define TM1637_CHAR_R B00110011
#define TM1637_CHAR_S B01101101
#define TM1637_CHAR_T TM1637_CHAR_t
#define TM1637_CHAR_U B00111110
#define TM1637_CHAR_V B00011100
#define TM1637_CHAR_W B00101010
#define TM1637_CHAR_X TM1637_CHAR_H
#define TM1637_CHAR_Y B01101110
#define TM1637_CHAR_Z B01011011
#define TM1637_CHAR_L_S_BRACKET B00111001 // 91 (ASCII)
#define TM1637_CHAR_B_SLASH B00110000
#define TM1637_CHAR_R_S_BRACKET B00001111
#define TM1637_CHAR_A_CIRCUM B00010011
#define TM1637_CHAR_UNDERSCORE B00001000
#define TM1637_CHAR_A_GRAVE B00010000
#define TM1637_CHAR_a B01011111 // 97 (ASCII)
#define TM1637_CHAR_b B01111100
#define TM1637_CHAR_c B01011000
#define TM1637_CHAR_d B01011110
#define TM1637_CHAR_e B01111011
#define TM1637_CHAR_f TM1637_CHAR_F
#define TM1637_CHAR_g B01101111
#define TM1637_CHAR_h B01110100
#define TM1637_CHAR_i B00000100
#define TM1637_CHAR_j B00001100
#define TM1637_CHAR_k TM1637_CHAR_K
#define TM1637_CHAR_l B00110000
#define TM1637_CHAR_m TM1637_CHAR_M
#define TM1637_CHAR_n B01010100
#define TM1637_CHAR_o B01011100
#define TM1637_CHAR_p TM1637_CHAR_P
#define TM1637_CHAR_q TM1637_CHAR_Q
#define TM1637_CHAR_r B01010000
#define TM1637_CHAR_s TM1637_CHAR_S
#define TM1637_CHAR_t B01111000
#define TM1637_CHAR_u B00011100
#define TM1637_CHAR_v B00011100
#define TM1637_CHAR_w TM1637_CHAR_W
#define TM1637_CHAR_x TM1637_CHAR_X
#define TM1637_CHAR_y B01100110
#define TM1637_CHAR_z TM1637_CHAR_Z
#define TM1637_CHAR_L_ACCON B01111001 // 123 (ASCII)
#define TM1637_CHAR_BAR B00000110
#define TM1637_CHAR_R_ACCON B01001111
#define TM1637_CHAR_TILDE B01000000 // 126 (ASCII)
// debug macros for debugging
#if TM1637_DEBUG
#define TM1637_DEBUG_BEGIN(x) Serial.begin(x)
#define TM1637_DEBUG_PRINT(...) Serial.print(__VA_ARGS__)
#define TM1637_DEBUG_PRINTLN(...) Serial.println(__VA_ARGS__)
#define TM1637_DEBUG_WRITE(x) Serial.write(x)
#define TM1637_DEBUG_MESSAGE(...) \
Serial.print(millis()); \
Serial.print(F("\t")); \
Serial.print(__VA_ARGS__);
#define TM1637_DEBUG_MESSAGELN(...) \
TM1637_DEBUG_MESSAGE(__VA_ARGS__) \
Serial.println();
#else
#define TM1637_DEBUG_BEGIN(x)
#define TM1637_DEBUG_PRINT(...)
#define TM1637_DEBUG_PRINTLN(...)
#define TM1637_DEBUG_WRITE(x)
#define TM1637_DEBUG_MESSAGE(x)
#define TM1637_DEBUG_MESSAGELN(x)
#endif
// arduino:standard variant direct port access macros for more speed ( communication is ~us)
#if defined(__AVR_ATmega8__) || defined(__AVR_ATmega8A__) || defined(__AVR_ATmega168__) || defined(__AVR_ATmega168A__) || defined(__AVR_ATmega168P__) || defined(__AVR_ATmega168PA__) || defined(__AVR_ATmega328__) || defined(__AVR_ATmega328P__)
#define portOfPin(P) \
( ((P) >= 0 && (P) < 8)? &PORTD:( ((P) > 7 && (P) < 14) ? &PORTB: &PORTC ) )
#define ddrOfPin(P) \
( ((P) >= 0 && (P) < 8)? &DDRD: ( ((P) > 7 && (P) < 14) ? &DDRB: &DDRC ) )
#define pinOfPin(P) \
( ((P) >= 0 && (P) < 8)? &PIND: ( ((P) > 7 && (P) < 14) ? &PINB: &PINC ) )
#define pinIndex(P) ( (uint8_t)( P > 13 ? P-14: P&7 ) )
#define pinMask(P) ( (uint8_t)( 1 << pinIndex(P) ) )
#define pinAsInput(P) *(ddrOfPin(P) ) &= ~pinMask(P)
#define pinAsInputPullUp(P) *(ddrOfPin(P) ) &= ~pinMask(P);digitalHigh(P)
#define pinAsOutput(P) *(ddrOfPin(P) ) |= pinMask(P)
#define digitalLow(P) *(portOfPin(P)) &= ~pinMask(P)
#define digitalHigh(P) *(portOfPin(P)) |= pinMask(P)
#define isHigh(P) ( ( *( pinOfPin(P) ) & pinMask(P) ) > 0 )
#define isLow(P) ( ( *( pinOfPin(P) ) & pinMask(P) ) == 0 )
#define digitalState(P) ((uint8_t)isHigh(P))
#else
#define pinAsOutput(P) pinMode(P, OUTPUT)
#define pinAsInput(P) pinMode(P, INPUT)
#define pinAsInputPullUp(P) pinMode(P, INPUT_PULLUP)
#define digitalLow(P) digitalWrite(P, LOW)
#define digitalHigh(P) digitalWrite(P, HIGH)
#define isHigh(P) (digitalRead(P) == 1)
#define isLow(P) (digitalRead(P) == 0)
#define digitalState(P) digitalRead(P)
#endif
#endif
