DECUP is an acronym for Decoder Update, a protocol for ZPP and ZSU updates over the track. The protocol is currently supported by the following products:

• Command stations
  • ZIMO KLUG
  • ZIMO MXULF
  • ZIMO MXDECUP
  • ROCO Z21
  • Open|Remise S3Main
  • RTB
• Decoders
  • ZIMO small- and large-scale MX decoders
  • ZIMO accessory decoders

The protocol was developed for the MXDECUP, an update device without a microprocessor. The device placed a UART signal (at that time ±12V) more or less directly on the tracks. The connection itself uses LSB first 38400 baud 8N2, i.e. 8 data bits, no parity and 2 stop bits.

A special feature is that the RTS line is used to switch the track voltage on and off.

In principle, the receiver (decoder) has the option of responding with one or two short-circuit pulses after a transmission in the time window provided for this purpose. These pulses are <8µs long and, if two pulses are made, come at an interval of 150-160µs. The duration of the entire time window can unfortunately vary, which is why in the following it is explicitly stated for each transmission how long, if at all, to wait for a response.

In its original version, the protocol was intended exclusively for ZSU updates. For this reason, the decoder update procedure does not have any meaningfully segmented packets, but simply sends a bunch of raw data whose meaning is determined solely by the sequence.

The following two bytes represent the entry sequence for a ZSU firmware update. The two bytes must be sent alternately at least 20 times, with a pause of at least 300µs between each byte.

After entry, the decoder IDs (e.g. 221 for MX645) are sent one by one to determine which decoder is connected. A connected decoder responds with a double pulse.

Next, the page count is transmitted.

The page count is directly proportional to the number of update blocks actually transmitted and is calculated as follows.

uint8_t page_count = (firmware_size + bootloader_size) / 256u - 1u; 

The block count followed by the transmission of two security bytes, first 0x55, then 0xAA.

Then the transfer of the actual firmware blocks can finally begin.

For feedback, a double pulse counts as ack and a single pulse as nak. If a decoder only responds with a single pulse, the block can be repeated.

When the first generation of ZIMO sound decoders (MX) was developed, the DECUP protocol was extended to include ZPP updates. Fortunately, the meaning of the transmitted data no longer depends only on the order, but command codes have been defined.

In contrast to the ZSU update, the entry sequence has been extended by another 0xEF byte. The 300µs pause between each individual byte must also be observed here.

CV Read reads a single CV value from a decoder. Since a single CV value naturally has 8 bits, the receiver is offered 8 feedback windows within the packet, in each of which one bit must be reported back as set or cleared.

CV Write writes a single CV value to a decoder.

CV Write writes a single CV value to a decoder.

Flash Erase erases the entire flash memory. Please note that deleting a NOR flash can take up to 60s depending on the manufacturer and type.

Flash Write writes to flash memory.

Flash Write writes to flash memory.

Decoder ID reads a single byte decoder ID. Just like the CV Read command, this one contains 8 feedback windows.

Queries a decoder wether it support a CRC8 checksum. Just like the CV Read command, this one contains 8 feedback windows. A returned value of 1 indicates that CRC8 checksums are supported.

Sub-command controlled operations for CV-Set manipulation. Changes or queries attributes of CV-Sets.

Writes a single CV in a CV-Set

Queries decoder support for CvSets and its capabilities. Just like the CV Read command, this one contains 8 feedback windows. The following table provides an overview on possible responses and their meaning.

1. Entry to enter ZSU firmware updates
2. Decoder ID to find connected decoder type
3. Page Count
4. Security Bytes
5. Blocks to transmit ZSU firmware data

1. Entry to enter ZPP sound updates
2. CV Read to read CV8 (2x)
3. Decoder ID to read decoder ID (2x)
4. CV Read to read CV7 (2x)
5. Flash Erase to erase ZPP sound flash
6. Flash Write to write ZPP sound flash
7. CV Write to write CVs

• C++23 compatible compiler
• CMake ( >= 3.25 )
• Optional
  • for building ESP32 RMT encoder example
    • ESP-IDF ( >= 5.0.3 )

This library is meant to be consumed with CMake,

# Either by including it with CPM
cpmaddpackage("gh:ZIMO-Elektronik/DECUP@0.2.1")

# or the FetchContent module
FetchContent_Declare(
  DECUP
  GIT_REPOSITORY "https://github.com/ZIMO-Elektronik/DECUP"
  GIT_TAG v0.2.1)

target_link_libraries(YourTarget PRIVATE DECUP::DECUP)

or, on ESP32 platforms, with the IDF Component Manager by adding it to a idf_component.yml file.

dependencies:
  zimo-elektronik/decup:
    version: "0.2.1"

🚧

On ESP32 platforms examples from the examples subfolder can be built directly using the IDF Frontend.

idf.py create-project-from-example "zimo-elektronik/decup^0.2.1:esp32"

🚧