Welcome to TrainThing’s software documentation!


There are lots of things to do


This is the software for the Raspberry Pi, part (3), of the TrainThing


command All function are just stubs This should be close to next

Module command

This module manages configuration of data retained by the RPi and all access to the information. Classes Sensor and Signal

All DCC++ commands (and addon commands) processed by the RPi are processed by the Command class using other assets to implement the command or obtain requested data.

class command.Command

This class processes all commands from the TrainThing laptop (4) intended for the Raspberry Pi (3) Traffic.from_LP uses function command.check to identify which instruction go where. If intended for the RPi command.process is pass the command


Uses the one letter command to deturman where the command is sent

Parameters:msg – command message from the LapTop
Returns:0 - Arduino only, 1 - both, 2 RPI only
static process(self, msg)

Processes all commands to be handled by the RPi

Parameters:msg – command from the Laptop
class command.Sensor

All methods to access stored sensor data

static process(self, msg)

Processes commands to define/maintain/report status of all turnout sensors

Pram msg:Command from the LapTop
class command.Signal

All methods to access stored signal data

static process(self, msg)

Process all commands to define/maintain/set the aspect of all signals

Pram msg:Command sent from the LapTop

Module signals

This module directly controls all the signals on the TrainThing layout. A command to change the aspect of a signal is sent from the LapTop (4) received by module traffic, passed to module command, combined with stored information and sent to module signals (this module) witch changes the aspect of a semaphore or LED signal.

A procedure is called to change the aspect of a semaphore so that the change is not “instantaneous.” A thread is created for each procedure call.

class signals.LED

This class defines the hardware interface to the four tri-color LED signals in the parking lot and sets the aspect of the LED signals.

static set(self, signal, aspect)

Set the LED signal aspect

Pram signal:33-36 which signal
Pram aspect:0-3, off, red, yellow, green
class signals.Signals

This class defines the interface to the semaphore signal hardware and sets the aspect of each semaphore.

static set(self, row, col, old, new)

Set the semaphore aspect

Pram row:0-4 which PWM HAT/Bonnet
Pram col:0-15 which output of the row
Pram old:0-180 current servo setting
Pram new:0-180 new servo setting


traffic Rework from_BS as a thread

Module traffic

This module provides: 1. A socket server for the WiFi connection to the Laptop running JMRI DCC++ software 2. A serial link to the Arduino running the DCC++ Base Station and 3. Blinks the 4 LEDs representing traffic to and from each. By default the serial link is: EIGHTBITS = 8, PARITY_NONE = N, STOPBITS_ONE = 1

class traffic.Monitor

This class is used to blink each of the 4 traffic monitoring LEDs in relationship to the traffic Out from the laptop (Orange) and Back to the laptop (Blue). Output to the Base Station (Orange) and Back from the Base Station (Blue).

Should be called only be Traffic

DIV = 30

Common routine to blink a LED number of blinks = 1 + num // DIV (integer divide).

Pram LED:output pin on IOPi bus2
Pram num:number of bytes in the message i.e. len(message)
static from_BS(self, num)

Creates a thread to Blink the BLUE LED for traffic from the Base Station.

Pram num:length of message received from the Base Station
static from_LT(self, num)

Creates a thread to Blink the ORANGE LED for traffic from the Laptop.

Pram num:length of the message received i.e. len(message)
static to_BS(self, num)

Creates a thread to Blink the ORANGE LED for traffic to the Base Station.

Pram num:length of message sent to the Base Station
static to_LT(self, num)

Creates a thread to Blink the BLUE LED for traffic to the Laptop.

pram num: length of message sent to the laptop

class traffic.Traffic

This class handles all TrainThing communication wirelessly to/from the Laptop and wired to/from the Arduino. read_LT() returns commands from the Laptop NOT intended for the Arduino Base Station. Calls to write_LT() are used to return status from the Raspberry Pi to the Laptop.

BAUDRATE = 115200
DEVICE_NAME = '/dev/ttyACM0'
FORMAT = 'utf-8'
PORT = 2560
static buffer_to_LT(self)
clientsocket = None
static read_BS(self, fake)

This method is a thread started by __init__ to reads strings from the Arduino each ending with “>” Strings from the Arduino are passes it to write_LT()

static read_LT(self)

This method is a thread started by __init__ to reads strings from the laptop each ending with “>” command.check is used to see if instruction is for the Arduino. RPi or both pass input to write_BS for the Arduino, pass input to command.process for the RPi or both Loop till shutdown

static stop_servers(self)
static write_BS(self, message)

Writes to the Arduino the string passed as a parameter from read_LT().

Pram message:String to be sent
static write_LT(self, message)

Writes to the Laptop the string passed as a parameter.

Pram message:String to be sent

Module unicorn

This module provides: an interface to the two Unicorn HAT HD 16x16 displays used to show the TrainThing signal aspects in place of/ or in addition to, the actual semaphores and display the state of the Raspberry Pi cooling fan.

Functions are provided to simplify, for TrainThing, the interface with the UnicornHATHD2 library.

class unicorn.TT_Display(color='BLUE')

Procedure to display: Aspect of all TrainThing signals Status of the Raspberry Pi fan

OFF = 0
RED = 1
static off()

Clears the unicorn buffer and display

static set_fan(self, x, y, r, g, b)

We will see

set_signal(x, y, aspect)

Update the displayed aspect of a signal at location {x,y}

Pram x:coordinate of the pixel 0-31
Pram y:coordinate of the pixel 0-15
Pram aspect:0-3 ~ OFF|RED|YELLOW|GREEN


wabbitFB Change reponse from “print” to <Q x> or <q x> sent to Laptop

Module wabbitFB

This module provides the interface between Wabbit optic-isolators, providing status of the TrainThing turnouts, the IOPi HAT and the Raspberry Pi which reports status of the turnouts to the Laptop. Class WabbitFB Method Interrupt is called when any of the 24 optic-isolators/IOPi bits change.

class wabbitFB.WabbitFB

This class defines and handles the interrupts generated by the IOPi HAT in response to turnout status changes reported by the 6 Wabbit decoder boards part of TrainThing.

Defines a method to report the status of all defined IOPi pins.

Each of 6 Wabbit controls 2 turnouts reporting the CLEAR and THROWN status to (4) input pins on the IOPi HAT. In response the IOPi generates one of three hardware interrupt connected to Raspberry Pi GPIO pins 4, 0 or 1. The Pi generates interrupts in response to the GPIO pin changes calling method interrupt within this class. The method reports the change in sensor status to the laptop.


This method: 1. Initializes the IOPi bus1, port 0 & 1 and bus2 port 0 as inputs from the Wabbits. (bus2 port 1 is used in the traffic module.) 2. Initializes output interrupts for the 3 ports connected to GPIO pins 3. Initializes 3 GPIO pins as input interrupts

__module__ = 'wabbitFB'

Fix wiring error on Wabbit Feedback board, IOPi bus 1, port 1, bits 10 and 12 switched

Pram old:byte read from bus 1 port 1 xxxx AxBx
Returns:byte with bits switched xxxx BxAx

Function called when GPIO 0,1,4 goes low. Identifies sensors that changed

Pram interrupt_pin:
 which GPIO pin caused the interrupt

Passes to output the interrupt_pin, which bits changed and the current value of the byte causing the interrupt.

static output(self, port, changed, value, delay=True)

Called by interrupt() and tell_all() to Report which sensors/bits changed. If bit goes high, call delayed() to report

Pram port:which GPIO pin caused the interrupt i.e. which port
Pram changed:byte 1 if bit changed else 0
Pram value:New value of the reporting port
Pram delay:delay reporting going high or not
static tell_all(self)

Report status of all sensors

Module fan

This module runs the Raspberry Pi cooling fan. Low lever hardware functions are called from FanLib and status is displayed by calls to module unicorn.

class fan.Run

Class Fan runs in the background as long as TrainThing is running. Using FanLib functions to monitor the cooling fan status and update the status displayed on the unicorns.


something something

__module__ = 'fan'

Module FanLib

This library provides low level funciton to manage the cooling fan for the Raspberry Pi. The Pimoroni FanShim FanLib.py library was modified for the TrainThing implementation. As build the FanShim uses GPIO pins used for the I2C interface which are also used by TrainThing.

class FanLib.Fan(pin_button=19, button_poll_delay=0.05)
__init__(pin_button=19, button_poll_delay=0.05)
  • pin_button – BCM pin for button
  • button_poll_delay – Delay between polling of button
__module__ = 'FanLib'

Get current fan state.


Attach function to button hold event.


Attach function to button press event.


Attach function to button release event.


Set the fan on/off.

Parameters:fan_state – True/False for on/off

Set the button hold time in seconds.

Parameters:hold_time – Time button must be held to trigger on_hold

Start button polling.


Stop button polling.


Toggle fan state.

Indices and tables