DCCEXProtocol

For the full documentation, please refer to the DCC-EX website.

The delegate and connection code in this library is taken directly from the WiThrottle library by Copyright © 2018-2019 Blue Knobby Systems Inc. The rest of the code has been developed by Peter Akers (Flash62au), Peter Cole (peteGSX), and Chris Harlow (UKBloke).

This library implements the DCC-EX Native command protocol (as used in EX-CommandStation ONLY), allowing a device to connect to the server and act as a client (such as a hardware based throttle).

The implementation of this library is tested on ESP32 based devices running the Arduino framework. There's nothing in here that's specific to the ESP32, and little of Arduino that couldn't be replaced as needed.

There has also been limited testing on STM32F103C8 Bluepill.

First of all, this library implements the DCC-EX Native protocol in a non-blocking fashion. After creating a DCCEXProtocol object, you set up various necessities such as the network connection and a debug console (see Dependency Injection).

Then, you call the check() method as often as you can (ideally, once per invocation of the loop() method) and the library will manage the I/O stream, reading in/parsing commands and calling methods on the delegate as information is available.

These patterns (Dependency Injection and Delegation) allow you to keep the different parts of your sketch from becoming too intertwined with each other. Nothing in the code that manages the pushbuttons or speed knobs needs to have any detailed knowledge of the DCC-EX native protocol.

Full documentation of the classes is available via the DCC-EX website.

The DCCEXProtocol class manages all relevant objects advertised by a DCC-EX EX-CommandStation and exposes simple methods to control these objects from the client software.

These objects include:

• Roster entries
• Route entries
• Turnouts/Points
• Turntables (noting that these objects are only available in development versions)
• Command Station Consist (CSConsist) entries

This means the client software does not need to explicitly manage the state of these objects whilever the check() method mentioned above is called appropriately.

The DCCEXProtocolDelegate class enables the client software to respond to various events generated by a DCC-EX EX-CommandStation as either broadcasts or responses to commands.

The events able to be managed via this class are over and above those managed by the DCCEXProtocol class and are entirely customisable by the client software to provide dynamic user experience updates such as displaying status changes to objects as they are broadcast from the DCC-EX EX-CommandStation.

Documentation of the DCCEXProtocol library is available via the DCC-EX website.

For contributors wishing to build local copies of the documentation while updating the library, here is the very high level process of the requirements to make this work on Windows:

• Install Doxygen and once complete, add to your user path
• Setup a Python virtual environment with "virtualenv venv" and activate with "venv\scripts\activate"
• Install required Python modules with "pip3 install -r requirements.txt"
• Change to the docs directory and run "make html"

The library has a comprehensive test suite written using GoogleTest, which is run automatically on every push and pull request via the GitHub "PlatformIO Testing" workflow (see tests.yml in the repository).

As of version 1.2.1, the tests have been migrated from cmake across to PlatformIO's native test environment, which simplifies the dependencies and process of running the tests. To run them, you will need PlatformIO installed, either through the VSCode IDE or installed within a Linux/macOS environment directly. PlatformIO Core should be all that is required to be installed.

The recommendation to run the tests on Linux or macOS remains due to the ability to check for memory leaks and invalid pointers:

pio test -e native_test

If you do run on Windows, run this command instead, note that it disables the relevant sanitiser checks:

pio test -e native_test_windows

If you are running on macOS, use this environment instead, which removes the GCC-specific coverage flags that are not supported by the Apple clang toolchain:

pio test -e native_test_macos

To generate test coverage, use the generate_test_coverage.py script. The environment is auto-selected based on the platform (native_test_macos on macOS, native_test elsewhere) and can be overridden with -e:

python3 generate_test_coverage.py
python3 generate_test_coverage.py -e native_test_macos

For full details, including how to monitor test coverage, see the Library Tests documentation.

Creative Commons CC-BY-SA 4.0

Free Software, Oh Yeah!