Python code to issue TMCC1 and Legacy Commands

Sounds like an exciting project Dave!

One thing that I've asked Lionel for and suggested previously on this Forum, is some provision for RANDOMNESS.  As far as I know, the built-in macro recording capability of the Legacy base, and even Lionel's LCS lack any such provision, and that's a shame!

To my way of thinking: if you build a layout with multiple routes, passing sidings or hidden staging that has the ability to store and stage trains, adding random selection of trains and routes turns the whole thing into a kind of "mechanical fish tank" that visitors could watch for several minutes without seeing the same train on the same track twice.  Code for semi-autonomous operation might make train layouts a fixture in doctors' offices, hotel lobbies, even store windows!  When you take into account the ongoing costs of maintenance, a train display would probably cost less than an ACTUAL fish tank!

One thing I am picky about is realistic starting and stopping.  Smooth starts and stops are also much easier on rubber tires and gears.  So the code should contain provisions for gradual stops and starts, perhaps by sending multiple speed commands.  I'm not sure how you're sensing train position, but to make it reliable and repeatable, care has to be taken to make sure the train stops within a staging block, not fouling other routes / trains.

Can't wait to see what comes of your efforts!  Please keep us posted (and a video demo would be great!)  Thanks for sharing!

I’ve made some progress over the weekend and now have Python code working to control switches, operate accessories, fire routes and run engines and trains. The code supports both TMCC1 and TMCC2. (Legacy) syntax, and provides a means to specify the command format you want from the command line.

The code can be found on GitHub here:https://github.com/cdswindell/PyLegacy.

TMCC2 provides far more options for engine/train control than does the older TMCC1 syntax. I have about 50% of the TMCC1 engine commands implemented, along with their corresponding TMCC2 counterparts. Of course, this means I’ve only implemented about 10-15% of the TMCC2 engine commands. However, as in TMCC2 land, engine and train commands are the same, except for the first byte of the command, this means I also have a bunch of train commands working!

The CLI layer calls into a set of command generation classes that construct the byte sequences to send to the SER2. This layer is relatively clean and uses a set of Python enums that use the bit patterns associated with each Lionel command to uniquely define them. The address of the entity being controlled can then be logically ORed to this bit string to build the command bytes. Frankly, the hard part is working out a sensible CLI command syntax for the TMCC2 engine/train commands. The Python library ArgParser is definitely my friend!

After I complete the implementation of the TMCC1 and 3-byte TMCC2 engine commands, I will turn to writing unit tests and packaging the code. Then, I’ll move on to connecting physical button presses on my Raspberry Pi to my command architecture.

  — Dave

You're really cruising along Dave, sounds like a great project!

Dave....Thanks for sharing. Following

Richard

It was gratifying to see the code up and working on my little Pi this morning. There were some surprises:

• The 'Ring Bell' commands (both TMCC1 and 2) actually turn the bell ringing on and off (like sliding and holding the bell slider on the Cab 2 remote)
• Unclear why the "Bell Slider Command [2 - 5]" didn't seem to do anything
• For the "Bell One-shot Ding [0 - 3]" command, the numeric argument controls the bells volume
• The TMCC1 engine commands work on Legacy (tmcc2) engines and carry out the corresponding functionality.
• Not sure what "Blow Horn 2" does; none of my engines responded to it. Is this reserved for the Vision Line series?
• Seems to be a slight difference between the TMCC1 and TMCC2 Halt commands. Both stop all engines dead on their tracks (pun intended), but the TMCC1 command shuts down enabled power districts on my LCS BP2 whereas the TMCC2 command left the power districts on.

I still have several commands left to implement, but as I said in my last message, I want to get some unit tests in place before I go too much further. Everything is checked in, and the README.md file contains instructions on how to grab my code and get it to compile. Although that said, if you are not familiar with Python, it will be a challenge...

  -- Dave

FYI, I've implemented most all of the TMCC1 and TMCC2 commands on pages 4, 5, 6, 8, and 9 of the LCS Partner Documentation Legacy Command Protocol, rev 1.21. The commands I've omitted are those that add/remove engines and rail sounds cars from consists/trains.

The Python code is checked in at github.com/cdswindell/PyLegacy. There are a series of command line tools (CLI) you can use to control an engine from a shell window of a Linux/Mac/Windows PC, as well as a series of classes to issue commands programatically. With respect to the cli commands, the engine command was the most challenging, because there are so many options!! Typing the command:

(legacyEnv) davids@Sprucewood-iMac PyLegacy (master) % src/cli/engine.py -h         

usage: Control specified engine/train (1 - 99) [-h] [-a | -s | -fwd | -rev | -t | -fc | -rc | -r | -b |
                                               -boost | -bl [0 - 7] | -brake | -kl [0 - 7] |
                                               -tb [0 - 7] | -sui | -sud | -sdi | -sdd] [-tr]
                                      [-tmcc | -legacy]
                                      [-baud BAUDRATE] [-p PORT]
                                      Engine/Train {speed,sp,bell,be,horn,ho,momentum,mo,sound,so}

positional arguments:
  Engine/Train          Engine/Train to control
  {speed,sp,bell,be,horn,ho,momentum,mo,sound,so}

  Engine/train sub-commands
    speed (sp)                    Speed of engine/train
    bell (be)                       Bell operations
    horn (ho)                     Horn operations
    momentum (mo)       Momentum operations
    sound (so)                   Sound operations

options:

-h, --help            show this help message and exit

-a, --set_address     Set engine address

-s, --stop_immediate Stop immediate

-fwd, --forward_direction

                        Set forward direction

-rev, --reverse_direction

                        Set reverse direction

-t, --toggle_direction

                        Toggle direction

-fc, --front_coupler Open front coupler

-rc, --rear_coupler Open rear coupler

-r, --ring_bell       Ring bell

-b, --blow_horn       Blow horn

-boost, --boost_speed

                        Brake speed

-bl [0 - 7], --boost_level [0 - 7]

                        Boost level

-brake, --brake_speed

                        Boost speed

-kl [0 - 7], --brake_level [0 - 7]

                        Brake level

-tb [0 - 7], --train_brake [0 - 7]

                        Train brake

-sui, --start_up_immediate

                        Start up immediate

-sud, --start_up_delayed

                        Start up delayed (prime mover)

-sdi, --shutdown_immediate

                        Shutdown Immediate

-sdd, --shutdown_delayed

                        Shutdown delayed with announcement

-tr, --train          Direct command to addressed train rather than engine (for TMCC2 commands)

-tmcc, --tmcc1        Use TMCC1 command syntax.

-legacy, --tmcc2      Use TMCC2/Legacy command syntax.

-baud BAUDRATE, --baudrate BAUDRATE

                        Baud Rate (9600)

-p PORT, --port PORT Serial Port (/dev/ttyUSB0)

provides a list of command options that can be applied to the specified option. For example the command:

src/cli/engine.py 71 speed 65

sets the absolute speed of the Legacy engine with the Engine ID of 71 to 65.

The command:

src/cli/engine.py 71 -r

turns the bell on (or off) on Engine #71.

I've added tests for the TMCC1 commands. I need to think a bit about how to test the TMCC2 commands, as it is tedious to code the bit patterns from the Lionel doc into source code, but that is most likely what I need to do...

Next up is to implement a serial communications module that allows a single instance to take commands from multiple threads and meter them out to the serial input of the LCS SER2 (so its buffer doesn't overflow).

To follow are implementing the multi-word Legacy commands, the Raspberry Pi code to respond to button presses, complete unit tests, better documentation, and packaging the project into a downloadable project on PyPi.

    -- Dave

That's really cool. Could be the beginning to a lot of possibilities

This is certainly an ambitious project Dave, following along closely.

Just checked in the code for Effects and Lighting controls. No CLI for these yet. Any of you guys have the Lionel stock cars that have effects? Who/what is Fred?

Today's checkins include support for a comms buffer that sends command bytes to the LCS SER2 with buffering and throttling. The buffer can hold up to 2,048 commands (3 or 9 byte packets) and then sends them to the SER2 no faster than one every 50ms. This behavior is transparent to the client command code, meaning programmers just have to think about what they want their trains to do.

I also added support for the Lionel's "official railroad speeds". For example:

davids@Sprucewood-iMac PyLegacy (master *) % src/cli/engine.py 10 sp limited

sets the speed of the Legacy/TMCC2 engine with TMCC ID#10 to "Limited", which corresponds to[ponds to the absolute speed step of 118. Appropriate speed tables have been implemented for TMCC1 as well (where only speed steps of 0 - 31 are supported)

I've also added a repetition option, which sends the same command multiple times. For example:

davids@Sprucewood-iMac PyLegacy (master *) % src/cli/engine.py 12 -re 10 -boost

sends the "boost" command 12 times to Engine # 10. Why you may ask? Because this is essentially what happens when you press/roll up repeatedly on the multi-controller wheel on the Cab 2. Sending the command multiple times corresponds to holding the "boost" function wheel for a period of time. You could also use the -(re)peat option to ring the bell, say, 5 times or blow the whistle 3 times, etc.

I have been a bit surprised to find that the "Train Brake" functionality actually sends along absolute speed commands as you move the slider control on a Cab 2. In add-on to sending the bytes for the train brake command, the Cab 2 sends multiple decreasing absolute speed commands along as well. It appears that it is these speed commands that actually slow the train down. When you push the slider back up (no brake), a series of increasing speed commands are sent as well. Huh.

Tests are coming along as well. Tests have been added for all of the TMCC1 and TMCC2 3 byte commands. I've done this by entering them in my constants file as hex digits. The test classes use binary representation ("1"'s and "0"'s) taken directly from the documentation and compare values. Not perfect, but it means I had to make the same transcription mistake twice in two different formats.

Here is a summary of the CLI commands that exist today:

• src/cli/acc.py: issue accessory commands
• src/cli/engine.py: issue engine/train commands
• src/cli/halt.py: issue an emergency stop/halt command
• src/cli/route.py: fire routes
• src/cli/switch.py: throw switches

The engine, halt, and route commands can issue either TMCC1 or TMCC2 command sequences. Python classes have been developed (and are in /src/protocol) that are used by the CLI and can be incorporated into other python programs to build up more elaborate command flows (start up a train, ramp up speed over time, ring bells and blow horns, fire routes, etc.)

I will next add the remaining sound effects controls that are defined for the TMCC2 multi-word commands and then on to physical buttons.

  -- Dave

I had a really productive day today with the project. Using the gpiozero library by Ben Nuttall and Dave Jones, I connected the command generation and sending code I've developed to physical button presses on a Raspberry Pi (4)! For example, by writing this one line of code:

GpioHandler.when_button_pressed(21, TMCC2RouteOption.ROUTE, 10)

I can fire Route 10 (using  TMCC2/Legacy command syntax) when I press a button connected to my Pi's GPIO pin 21!

The gpiozero library really made the integration easy. For example, with these two lines:

from gpiozero import Button

button = Button(21)

you create a "Button" object tied to GPIO pin 21.

Then, with this line:

button.when_pressed = CommandReq.as_action(TMCC2RouteOption.ROUTE, 10)

you assign a callback function to call whenever the button is pressed.

Here's a picture of the setup:

The red wire is attached to one of the Pi's Gnd (ground) pins, and the brown wire is attached to GPIO pin 21. You push the big red button and the byte string 0xFA14FD is sent to my LCS SER2 and route #10 is fired!!

  -- Dave

It is exciting to see your progress.  Thanks for making the project available on github.

For me, I'd love to implement this on a microcontroller running circuit python.  Think of the possibilities if it could also receive and interpret commands on the serial bus.  Very nice to have this as an alternative to the whole LCS partner shebang.

I don't know how many Python fans there are in our community, but it is definitely a +1 from me.

I've been busy the last few days on doing a fairly major restructuring of the code. The end result is that all of the logic to apply address and data values to the TMCC1, TMCC2, and a good portion of the TMCC2 Parameter commands. I've also unit tested all of this code (which isn't as fun as building new features, but, alas, it is critical to producing production-quality software).

The CLI and the classes that back end it (and implement the command syntax to make things happen on a layout) all now use this new code and benefit from the unit testing of the underlying subsystem. These classes are CommandReq and ParameterCommandReq. They can be used directly, are used by the CLI, and support several class methods to issue directives to a layout (via the LCS SER2) without creating intermediate CommandReq objects.

I've also implemented a command buffer which receives byte strings from the CommandReq fire or send methods and queues them for dispatch to the LCS SER2. Per other posts I've read on this forum, output to the SER2 is throttled so no more than one byte sequence is sent every 40 milliseconds (configurable, of course).

For others to be able to use this code, I really need to write more documentation and to use a python package manager to bundle everything up. Doing the packaging is a little new to me, but the gpiozero package I'm using to connect my work to physical button presses gives me some ideas on how to do that. The packaging will probably be my next step.

I've also signed up for the Lionel Partner Program and am looking forward to participating there as well.

  -- Dave

p.s. I do, on occasion run trains too. Below is a picture of the layout I'm building.

Just checked in code to issue Legacy/TMCC2 Lighting Effects commands, as documented on page 18 of the Lionel Partner Program documentation. These are part of the 3-word commands, and use 9 bytes to express a command. The Lighting control effects include support for:

• Dog house lights (on/off)
• Hazard lights (on/off/auto)
• Ditch lights (on/on pulse off with horn/off pulse on with horn/off)
• Loco/engine marker lights (on/off)
• Tender marker lights (on/off)
• Ground lights (on/off/auto)
• Strobe lights (on/double flash/off
• Mars lights (on/off)
• Cab lights (on/off/auto)
• Rule 17 (on/off/auto)
• Car cabin lights (on/off/auto)

Support includes the cli script lighting.py, and a command class.

I also built a cli that reads requests from the command line and, using the parsers developed for each of the cli commands, parses the input and sends the appropriate command to the LCS SER2. The program continues to process your input until you enter "q" or hit <ctrl-c>.

Here is an example:

(legacyEnv) davids@Sprucewood-iMac PyLegacy (master) % src/cli/control.py 
PyLegacy train controller, Ver 0.1
>> eng 88 speed 50            # sets the absolute speed of engine 88 to 50
>> li 88 ditch -on            # turns ditch lights on
>> eng 88 -b -re 4 -de 0.5    # blow horn 4 times w/delay of 0.5 seconds between

You can also get help on command options like so:

>> eng 1 sp -h
usage: control.py Engine/Train speed [-h] [-a | -r]
      Engine/Train speed: 0 - 199 (Legacy) or 0 - 31 (TMCC) or roll, restricted,
      slow, medium, limited, normal, or highball

positional arguments:
      Engine/Train speed: 0 - 199 (Legacy) or 0 - 31 (TMCC) or roll, restricted,
      slow, medium, limited, normal, or highball

options:
    -h, --help          show this help message and exit
    -a, --absolute      Set absolute speed
    -r, --relative      Set relative speed speed (-5 to 5)
>>

The Effects controls are next up (smoke on/off, stock car options, pantograph control, etc).

Enjoy!

  -- Dave

I'm liking this project, you're making real progress on filling out the command capability!