# tm1637

Library for the TM1637 LED drive control special circuit.

Author | Rob Jansen, Copyright © 2020..2022, all rights reserved.
Adapted-by |
Compiler | 2.5r6

Description

    Libray for use of the TM1637 LED drive control special circuit.
                 It provides functions to write data to the LED displays and a
                 function to read the keyboard.

Sources

    Inspired by: https://github.com/avishorp/TM1637
             Also see the TM1637 datasheet of Titan Micro Electronics

Notes

    The following pins must be defined by the main program before
             including this library:
             -) alias tm1637_clk            -- To CLK of the TM1637
             -) alias tm1637_clk_direction
             -) alias tm1637_dio            -- To DIO of the TM1637
             -) alias tm1637_dio_direction
             Note that modules with 7-segement displays often have capacitors on
             the clk and dio line. These should be removed.

Dependencies

No dependency found

## Summary

### Global variables/contants

- `const byte TM1637_MAX_KEY = 16`
- `const byte _TM1637_COMMAND_DISPLAY = 0x80`
- `const byte _TM1637_COMMAND_KEY_DATA = 0x42`
- `const byte TM1637_MAX_BRIGHTNESS = 7`
- `const byte TM1637_SEGMENT_B = 0b0000_0010`
- `const byte _TM1637_COMMAND_ADDRESS = 0xC0`
- `const byte TM1637_SEGMENT_OFF = 0b0000_0000`
- `const byte _TM1637_KEY_VALUE_TO_KEY_NUMBER[TM1637_MAX_KEY] =`
- `const byte TM1637_SEGMENT_ALL = 0b1111_1111`
- `var byte _tm1637_brightness`
- `const byte _TM1637_DIGIT_TO_SEGMENT[16] =`
- `var byte tm1637_display_data[TM1637_WIDTH]`
- `const byte TM1637_SEGMENT_G = 0b0100_0000`
- `const byte _TM1637_COMMAND_DATA = 0x40`
- `const byte TM1637_MIN_BRIGHTNESS = 0`
- `const byte TM1637_SEGMENT_A = 0b0000_0001`
- `const byte TM1637_SEGMENT_MIN = 0b0100_0000`
- `const byte TM1637_SEGMENT_F = 0b0010_0000`
- `const byte TM1637_SEGMENT_C = 0b0000_0100`
- `const byte TM1637_MIN_KEY = 1`
- `const byte TM1637_SEGMENT_D = 0b0000_1000`
- `const byte TM1637_SEGMENT_DP = 0b1000_0000`
- `const byte TM1637_NO_KEY = 0`
- `const byte TM1637_SEGMENT_E = 0b0001_0000`

### Procedures

- `tm1637_display_off()`
- `tm1637_display_nibble_hex(byte in value, byte in display_number)`
- `tm1637_display_clear()`
- `tm1637_init()`
- `tm1637_display_on()`
- `tm1637_set_brightness(byte in brightness)`
- `tm1637_set_display(byte in segment_data, byte in display_number)`
- `tm1637_display_byte_hex(byte in value, byte in display_number)`
- `tm1637_display_update()`
- `tm1637_display_word_hex(word in value, byte in display_number)`
- `tm1637_set_dot(bit in dot_on, byte in display_number)`

Private

- `_tm1637_acknowlege_transmission()`
- `_tm1637_stop_transmission()`
- `_tm1637_write_byte(byte in data)`
- `_tm1673_clock_delay()`
- `_tm1637_start_transmission()`

### Functions

- `tm1637_scan_key() return byte`
- `tm1637_digit_to_segment(byte in value) return byte`

Private

- `_tm1637_read_byte() return byte`

## API details

### Global variables/contants

- `const byte TM1637_MAX_KEY = 16`

  No documentation found

- `const byte _TM1637_COMMAND_DISPLAY = 0x80`

  No documentation found

- `const byte _TM1637_COMMAND_KEY_DATA = 0x42`

  No documentation found

- `const byte TM1637_MAX_BRIGHTNESS = 7`

  No documentation found

- `const byte TM1637_SEGMENT_B = 0b0000_0010`

  No documentation found

- `const byte _TM1637_COMMAND_ADDRESS = 0xC0`

  No documentation found

- `const byte TM1637_SEGMENT_OFF = 0b0000_0000`

  No documentation found

- `const byte _TM1637_KEY_VALUE_TO_KEY_NUMBER[TM1637_MAX_KEY] =`

      Translation table for converting key data to key numbers

- `const byte TM1637_SEGMENT_ALL = 0b1111_1111`

  No documentation found

- `var byte _tm1637_brightness`

      Variable to keep track of the display brightness and display on/off.

- `const byte _TM1637_DIGIT_TO_SEGMENT[16] =`

      Translation table for converting 0..F to the 7-segment display.

- `var byte tm1637_display_data[TM1637_WIDTH]`

      Global array that keeps the display data in segment format. It can be
      used to set segment data directly from the main program.
      Note: Use function tm1637_digit_to_segment() to translate a digit (0..F) to
      the correct segment value for the display. A segment data of '0' will clear
      all segments of that display. When this array is used, always call
      tm1637_display_update() afterwards to send the data to the display.
      The first byte in the array contains the data for the display connected to
      Grid 1, the seconds to Grid 2, etc.

- `const byte TM1637_SEGMENT_G = 0b0100_0000`

  No documentation found

- `const byte _TM1637_COMMAND_DATA = 0x40`

      TM1637 commands.

- `const byte TM1637_MIN_BRIGHTNESS = 0`

      Brightness values to control the brightness of the LED displays.

- `const byte TM1637_SEGMENT_A = 0b0000_0001`

      Definition of the 7 segment display of the TM1637:
      A

      F |   | B
      G-
      E |   | C

      D   dp

- `const byte TM1637_SEGMENT_MIN = 0b0100_0000`

  No documentation found

- `const byte TM1637_SEGMENT_F = 0b0010_0000`

  No documentation found

- `const byte TM1637_SEGMENT_C = 0b0000_0100`

  No documentation found

- `const byte TM1637_MIN_KEY = 1`

  No documentation found

- `const byte TM1637_SEGMENT_D = 0b0000_1000`

  No documentation found

- `const byte TM1637_SEGMENT_DP = 0b1000_0000`

  No documentation found

- `const byte TM1637_NO_KEY = 0`

      Keyboard constants. The numbering follows the numbering shown in the datasheet.

- `const byte TM1637_SEGMENT_E = 0b0001_0000`

  No documentation found

### Procedures

- `tm1637_display_off()`

      Turn all displays off.

- `tm1637_display_nibble_hex(byte in value, byte in display_number)`

      Display a hexadecimal nibble on a specific display. The display_number must
      be in range 0 (most right) to TM1637_WIDTH - 1 (most left)

- `tm1637_display_clear()`

      Switch all segments off.

- `tm1637_init()`

      Initialize and clear the display. The display is on but all segments are off.

- `tm1637_display_on()`

      Turn all displays on.

- `tm1637_set_brightness(byte in brightness)`

      Set the brightness of the displays. Brightness is in range 0..7.

- `tm1637_set_display(byte in segment_data, byte in display_number)`

      Set the segments for the given display with the given segment data.
      Note: Use function tm1637_digit_to_segment() to translate a digit (0..F) to
      the correct segment value for the display.
      A segment data of TM1637_SEGMENT_OFF will clear all segments of that display.
      Display number must be in range 0 (most right) to TM1637_WIDTH - 1 (most left)

- `tm1637_display_byte_hex(byte in value, byte in display_number)`

      Display a hexadecimal byte on a specific display. The display_number must
      be in range 0 (most right) to TM1637_WIDTH - 2 (most left)

- `tm1637_display_update()`

      Send the data stored in the global array tm1637_display_data to the displays.
      The order in which the data from tm1637_display_data is written is defined by
      TM1637_DISPLAY_ORDER. This function only needs to be called by the user when
      the user writes data directly into the global display data buffer.

- `tm1637_display_word_hex(word in value, byte in display_number)`

      Display a hexadecimal word on a specific display. The display_number must
      be in range 0 (most right) to TM1637_WIDTH - 4 (most left)

- `tm1637_set_dot(bit in dot_on, byte in display_number)`

      Set or clear the dot of the given display determined by the dot value.
      A value of 'dot_on' TRUE will turn the dot on, FALSE will turn it off.
      Display number must be in range 0 (most right) to TM1637_WIDTH - 1 (most left)

Private

- `_tm1637_acknowlege_transmission()`

      Acknowledge a data transmission.

- `_tm1637_stop_transmission()`

      Stop a data transmission.

- `_tm1637_write_byte(byte in data)`

      Write one byte to the TM1673. Transmission must have been started.

- `_tm1673_clock_delay()`

      Lower the clock to the TM1673.

- `_tm1637_start_transmission()`

      Start a data transmission.

### Functions

- `tm1637_scan_key() return byte`

      Check if a key was pressed and if so return the key number. The number is
      between TM1637_MIN_KEY and TM1637_MAX_KEY or TM1637_NO_KEY if no key was
      pressed.

- `tm1637_digit_to_segment(byte in value) return byte`

      Encode the given digit to the correct display segments.

Private

- `_tm1637_read_byte() return byte`

      Read one byte to the TM1673 and return it. Transmission must have been started.

## Related samples

Here are the list of samples which use this library:

16f1823 | 16f1823_tm1637_6_displays_keyboard.jal
16f1823 | 16f1823_tm1637_4_displays_no_keyboard.jal