CommandStation-EX/Release_Notes/TM1638.md

## TM1638 ##

The TM1638 board provides a very cheap way of implementing 8 buttons, 8 leds and an 8 digit 7segment display in a package requiring just 5 Dupont wires (vcc, gnd + 3 GPIO pins) from the command station without soldering.


This is ideal for prototyping and testing, simulating sensors and signals, displaying states etc. For a built layout, this could provide a control for things that are not particularly suited to throttle 'route' buttons, perhaps lineside automations or fiddle yard lane selection.  

By adding a simple HAL statement to myAutomation.h it creates 8 buttons/sensors and 8 leds.

`HAL(TM1638,500,29,31,33)`
Creates VPINs 500-507 And desscribes the GPIO pins used to connect the clk,dio,stb pins on the TM1638 board. 

Setting each of the VPINs will control the associated LED (using for example SET, RESET or BLINK in Exrail or `<z 500> <z -501>  from a command).

Unlike most pins, you can also read the same pin number and get the button state, using Exrail IF/AT/ONBUTTON etc.

For example:
`
HAL(TM1638,500,29,31,33)
`
All the folowing examples assume you are using VPIN 500 as the first, leftmost,  led/button on the TM1638 board.

 
`ONBUTTON(500) 
  SET(500)     // light the first led
  BLINK(501,500,500) // blink the second led
  SETLOCO(3) FWD(50) // set a loco going   
  AT(501) STOP // press second button to stop
  RESET(500) RESET(501)  // turn leds off
  DONE
`

Buttons behave like any other sensor, so using `<S 500 500 1>`  will cause the command station to issue `<Q 500>` and `<q 500>` messages when the first button is pressed or released.

Exrail `JMRI_SENSOR(500,8)` will create `<S` commands for all 8 buttons.  

## Using the 7 Segment display ##

The 8 digit display can be treated as 8 separate digits (left most being the same VPIN as the leftmost button and led) or be written to in sections of any length. Writing uses the existing analogue interface to the common HAL but is awkward to use directly.  To make this easier from Exrail, a SEG7 macro provides a remapping to the ANOUT facility that makes more sense. 

SEG7(vpin,value,format)

The vpin determins which digit to start writing at. 
The value can be a 32bit unsigned integer but is interpreted differentlky according to the format.

Format values:
 1..8  give the length (number of display digits) to fill, and defaults to decimal number with leading zeros.

 1X..8X give the length but display in hex.

 1R..4R treats each byte of the value as raw 7-segment patterns so that it can write letters and symbols using any compination of the 7segments and deciml point.

 There is a useful description here:
 https://jetpackacademy.com/wp-content/uploads/2018/06/TM1638_cheat_sheet_download.pdf


 e.g.  SEG7(500,3,4)
        writes 0003 to first 4 digits of the display
       SEG7(504,0xcafe,4X)
        writes CAFE to the last 4 digits
       SEG7(500,0xdeadbeef,8X) 
        writes dEAdbEEF to all 8 digits. 

    Writing raw segment patters requires knowledge of the bit pattern to segment relationship:
`      0
    == 0 ==
   5|     | 1
    == 6 ==
  4 |     | 2
    == 3 ==  
            7=decimal point

            Thus Letter A is segments  6 5 4 2 1 0, in bits  that is (0 bit on right)          
               0b01110111  or 0x77
    This is not easy to do my hand and thus a new string type suffix has been introduced to make simple text messages. Note that the HAL interface only has width for 32 bits which is only 4 symbols so writing 8 digits requires two calls.

    e.g.  SEG7(500,"Hell"_s7,4R) SEG7(504,"o"_s7,4R)
          DELAY(1000)
          SEG7(500,"Worl"_s7,4R) SEG7(504,"d"_s7,4R)

    Note that some letters like k,m,v,x do not have particularly readable 7-segment representations. 
                     
    Credit to https://github.com/dvarrel/TM1638 for the basic formulae.