pico-cs/firmware

pico-cs firmware for the Raspberry Pi Pico

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.

firmware's Issues

Does not reconnect to wifi if disconnected.

Hi, glad to see the latest 0.8.0 release and improvements. I've noticed that if using the firmware without the mqtt gateway that due to a lack of traffic many wireless APs will disconnect the client. I had a look at the source and in loop_pico_w it doesn't appear to check if it's been disconnected, and reconnect. I tried adding the following to the loop

    if (cyw43_wifi_link_status(&cyw43_state, CYW43_ITF_STA) != CYW43_LINK_UP) {
        cyw43_arch_wifi_connect_timeout_ms(WIFI_SSID, WIFI_PASSWORD, CYW43_AUTH_WPA2_AES_PSK, 30000);
    }

But I'm no C coder and it doesn't appear to work either :D

Thanks for your efforts so far, this is a great solution for small layouts.

Feature, generate a push message if an input gpio changes state.

Again, great work so far! The last feature which would make pico-cs able to completely run a small layout is to have a push message (as per the protocol document) generated when a GPIO configured as an input changes state. This would allow control software to react to things like a block occupancy or position sensor without having to continually poll and potentially miss events.

Inverted signal output.

Hi, another feature idea! If you add a second inverted signal output that would enable a user to use a common H-bridge module as a booster without having to build a signal inverter.

Controller enable gpio output.

Hi, it would be very useful to control a gpio pin and not just the LED output when the controller is enabled. This will make it very simple for the pico-cs to be used with many H-bridge modules with an enable input as the booster. Without this some DCC locos when attached to DC power (no dcc signal) assume they're in DC mode and start to accelerate.
Again, this is great work! Thanks, Max.