locodoco

locodoco Release status: experimental [box doku]
Description	An open source model railroad control infrastructure.
Author(s)	Soeren
Platform	AVR Microcontrollers
License	GPL
Download	[Trac] [SVN]

Locodoco is an open source (Soft- and Hardware) project that lets you control model trains and automate train movements. The Project consist of several Hard- and Software components. In the first stage of this project's development a "loco decoder" was built. This piece of hardware lets you control motor throttle, lights and other functions of a loco via data transmissions.

Motivation

There simply wasn't an open implementation that suited my needs. There is a well-developed open source project that implements DCC (Open DCC). Unfortunately DCC doesn't provide features like sending transmissions from locos to the controller - well, actually it does, but DCC's feedback functions are quite limited due to DDC's nature.

First prototype of the loco decoder installed into LGB 2033

Another goal I want to achieve is simplicity. A typical use case for this system is a plug-and-play setup where you simply stick all the track pieces together and plug in the power. In current implementations this works as well - turnouts get their signal from the track just like the locos do. The only disadvantage is that you'll have to remember or note turnout numbers in your control panel. The ability I wanted to add to model railroading is to make the process of switching a turnout more intuitive. Once this system is fully implemented you'll be able to select the next turnout on the way of a loco.

Features

Waypoints & Positioning information

Waypoints along the track (beacons) transmit an unique ID via infrared diodes to bypassing locos. This allows locos to transmit their position, direction and speed to the controlling devices. It may also be possible to utilize an accelerometer for more precise acceleration, deceleration information and positioning.

Independent power supply

Unlike usual systems, locos equipped with a locodoco controller can run on any track that provides between 8 and 30 Volts power AC and DC. It is possible to mix usual DCC systems with this system and have locodoco equipped locos run on DCC powered track. The only disadvantage is that you can't control DCC locos with controllers for the locodoco system. It should be possible to let locodoco Trains accept commands from DCC, though this is a question of software development - the hardware is ready for it ;-)

Speed calibration

With two position beacons in a known distance in between one can easily distinguish the speed of a running train. It is possible to "calibrate" speed levels and control locos by setting their _real_ speed (in contrast to a percentage level as it is the case with current systems).

This feature also allows for implementing beacons that send commands to throttle or halt locos - for example a signal sending the command "stop 1 meter ahead" - a beacon sending "speed limit 1cm/s for the next 3 meters" in front of a sharp curve...

Fully automated setup

With position information and the possibility to control actual speeds, one can build compeletely automated model train setups. All one needs is a set of simple decisions (i.e. "if loco x is at position y, switch turnout 7 to right") and a controlling unit that sends commands to the locos accordingly.

Loco decoder

The loco decoder consists of an AVR Microcontroller (Atmega32), a RFM12 radio transceiver, an L6202 Motor controller and several other Parts. Due to its size (3x5cm), it currently only fits into rather large scale Trains (i.e. G-Scale locos). At the moment the parts used are mostly SMD and the copper layout is designed for a one-sided board. It may be possible to shrink the entire size to 1/2 of the current, but that'll be pretty much the end of the scale and could fit into normal-sized H0 locos at most.

Waypoint transmitter

A waypoint transmitter consists of a tiny AVR microcontroller that continuously transmits the same sequence of bits while it is turned on. An infrared LED connected to one of the AVR's output drivers can be installed in turnouts and normal track to mark a position.

Turnout controller

The turnout controller is a piece of hardware that... well, controls turnouts. There will be several different versions available - some with RFM12 modules, some with infrared transistors to receive commands. Both with different amounts of outputs (for driving more than one turnout or n-way turnouts).

Protocol

Each message starts with a start header. Multiple commands to or from a device with a specific Address may be concatenated into one single Message. Subsequent Headers in the message to follow solely contain a TYPE field.

Start Header

Byte  0    1    2    3
    +----+----·----+----+ ...
    |TYPE|  ADDR   |XOR |
    +----+----·----+----+ ...

The Header is 32 Bits long and consists of 3 Fields:

TYPE: The Message Type
ADDR: Destination or Source Address (depending on the message type)
XOR: All Bytes of the Message XOR'ed together (payload, including header fields TYPE and DSTADDR). When the XOR sum is built over the header fields, the XOR field itself is set to 0x00 (therefore ignored)

Follow-up Header

Each subsequent header just contains a single TYPE field. The Address field is not repeated, since the source- or destination Address is the same.

Types

Bit #	7	6	5	4	3	2	1	0
Name	(res.)	(res.)	CONCAT	ACKRQ	Type Bit 3	Type Bit 2	Type Bit 1	Type Bit 0

Bits 6 & 7 are reserved for future use.
The concat Bit marks that another header/payload follows after the current one.
If the ackrq Bit is set, a client must acknowledge the receipt of the message (see acknowledgement messages)

Type Messages (Bits 0..3)

0x00	Speed control	0x01	Function Control
0x02	Acknowledgement/Pong	0x03	Ping
0x04	State inquiry	0x05	Function inquiry
0x06	Special Decoder functions

Speed control: Numerical signed int8_t (-127..+127)
Function control
Pong
Ping
State inquiry
Function inquiry:
Special functions:
- Assign secondary Address: For 2 or more locos driving in traction.
- Invert direction on secondary Address: This function inverts the direction of speed commands coming for the 2nd Address.
- Reboot
- Calibration: This instruction initiates the calibration function.

State of the Project

Done so far

Loco decoder Prototype board built & tested in LGB 2033 and 2060
First decoders installed and proven to be working stable
First pieces of software tested and run
Finished work bootloader to wirelessly update the firmware of the controller

To be done

Basic stuff

Implement above protocol
Develop a turnout controller (Hard- and Software)
Develop track nodes (for positioning information)
Develop a controlling device (currently a simple piece of software on a pc)

Nifty stuff

Implement automatic track setup detection (i.e. let a loco drive along the track and scan all waypoints). This is necessary to enable the selection of the next turnout stage.
Experiment with accelerometer track recognition and 3D stuff (i.e. having live position data in opengl)

Related work

opendcc is a project implementing an open source dcc stack and various hardware devices.