pico-cs firmware

pico-cs is a proof-of-concept for a model railway command station talking DCC (Digital Command Control) defined by the NMRA DCC working group and using the Raspberry Pi Pico as DCC signal generator.

pico-cs is intended for skilled users with expert levels of model railway electronics and protocol knowledge.

Why Raspberry Pi Pico / Pico W

Its support of programmable IO (PIO) enables implementing the core DCC protocol within a few lines of assembler code
Due to its dual cores the DCC signal generation and the command interface are implemented using different cores being run in parallel
Its small form factor and cost effectiveness allows and supports multiple command stations to be used as part of the model railroad layout
Its great ducumentation
The Pico W WiFi capabilities to operate the command station remotely via a TCP/IP connection
And last but not least the fun using it

Hardware

Raspberry Pi Pico / Pico W
A PC, Laptop, Raspberry Pi or any suitable device with an USB interface to flash the firmware and operate the command station via serial over USB and / or WiFi
A model railway booster
A model railroad locomotive roller test stand
A DCC decoder equiped test locomotive

Booster

As there is a lot of booster alternatives (motor shield, H-bridge, commercial booster, ...) the selection and connection options to the Pico goes beyond the scope of this document. You might find potential solutions searching the internet.

Voltage levels:

Pico DCC signal output is on GP2 with 3.3V level
As most digital booster DCC inputs would not work with 3.3V (please consult booster documentation) one need to choose a safe and reliable solution for level conversion
Example with SN74HCT125N as level shifter (Fritzing circuit diagram)

DCC decoder

Please be aware that not all DCC decoders do support all of the DCC commands. The pico-cs command station is using the DCC commands which most standard compliant DCC decoders should be able to understand. Nonetheless some decoders

do have issues with main track programming
do behave weird in case functions are used not supported by the decoder or writing CVs in general

Please be cautious and test all loco decoders on a roller test stand before using on track.

To mitigate some of the function setting issues the pico-cs command station is only refreshing functions which were explicitly used via the protocol.

Quick Start

Connect the Raspberry Pi Pico to your PC via an USB cable
Build the pico-cs firmware
Install firmware (Pico: cs.uf2, Pico W: cs_w.uf2) via BOOTSEL mode (see Raspberry Pi Pico documentation)
On macOS Ventura copying via drag&drop in Finder was broken but seems to work again with version 13.1 - anyway, copying the file via the command line is always an option:

cp -X cs.uf2 /Volumes/RPI-RP2/
cp -X cs_w.uf2 /Volumes/RPI-RP2/

Use a terminal emulation tool supporting serial over USB communication like
- the Serial Monotor of the Arduino IDE or
- the Serial Monitor extension of Visual Studio Code
Set the baud rate to 115200 and <CR> (Carriage Return) as command / message ending character
The firmware uses the following Raspberry Pi Pico GPIOs:
- GP2: DCC signal output
- GP3: DCC signal output (inverted)
- GP4: DCC signal power
- GP5: DCC signal power (inverted)

Build

For building there is two options available:

local build: install the toolchain and build on your local machine
docker build: no toolchain installation but a running docker environment on your local machine is required

Local

To build the firmware the Raspberry Pi Pico C/C++ SDK and toolchain needs to be installed. For details please consult the Raspberry Pi Pico documentation.

As the binary for the Pico W including the WiFi and network capabilities is significant larger and the WiFi SSID and a WiFi password is needed two firmware versions are build:

git clone https://github.com/pico-cs/firmware.git
cd firmware/src

Pico:

mkdir pico_build
cd pico_build
cmake .. -DPICO_BOARD=pico
make

firmware: cs.uf2

Pico W:

export PICO_CS_WIFI_SSID="MyWifiName"
export PICO_CS_WIFI_PASSWORD="MyPassword"
export PICO_CS_TCP_PORT= 4242
mkdir pico_w_build
cd pico_w_build
cmake .. -DPICO_BOARD=pico_w
make

if the TCP_PORT environment varible (PICO_CS_TCP_PORT) is not set the default port 4242 is used.
firmware: cs_w.uf2

Inspect the firmware binaries

With the help of the picotool the firmware binaries can be inspected:

./picotool info -a <path to firmware>/firmware/src/pico_build/cs.uf2 

File <path to firmware>/firmware/src/pico_build/cs.uf2:

Program Information
 name:          cs
 version:       <firmware version>
 web site:      https://github.com/pico-cs
 description:   pico-cs DCC command station
 features:      Refresh buffer size 128
                double reset -> BOOTSEL
                UART stdin / stdout
                USB stdin / stdout
 binary start:  <start address>
 binary end:    <end address>

Fixed Pin Information
 0:   UART0 TX
 1:   UART0 RX
 2:   Main track: DCC signal output
 3:   Main track: DCC signal output (inverted)
 4:   Main track: DCC signal power
 5:   Main track: DCC signal power  (inverted)
 25:  On-board LED

Build Information
 sdk version:       <sdk version>
 pico_board:        pico
 boot2_name:        boot2_w25q080
 build date:        <build date>
 build attributes:  Release

./picotool info -a <path to firmware>/firmware/src/pico_w_build/cs_w.uf2

File  <path to firmware>/firmware/src/pico_w_build/cs_w.uf2:

Program Information
 name:          cs_w
 version:       <firmware version>
 web site:      https://github.com/pico-cs
 description:   pico-cs DCC command station
 features:      WiFi SSID MyWiFiSSID password MyWiFiPassword
                TCP port 4242
                Refresh buffer size 128
                double reset -> BOOTSEL
                UART stdin / stdout
                USB stdin / stdout
 binary start:  <start address>
 binary end:    <end address>

Fixed Pin Information
 0:  CYW43 LED, UART0 TX
 1:  UART0 RX
 2:  Main track: DCC signal output
 3:  Main track: DCC signal output (inverted)
 4:  Main track: DCC signal power
 5:  Main track: DCC signal power  (inverted)

Build Information
 sdk version:       <sdk version>
 pico_board:        pico_w
 boot2_name:        boot2_w25q080
 build date:        <build date>
 build attributes:  Release

Protocol

Please see protocol for information about the implemented text protocol.

Features

Pico firmware implementing DCC commands to control model railway locomotives
Simple command human readable and debug friendly text protocol
- which can be used directly via serial terminal programs supporting serial over USB
- and easily integrated into any programming language or tool supporting serial over USB communication
Pico W WiFi support
Go Client library
MQTT gateway
- combined with a MQTT message broker like mosquitto the command station can be easily controlled by other tools as for example Node-RED

Licensing

Copyright 2021-2023 Stefan Miller and pico-cs contributers. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.

pico-cs / firmware