The DCC-EX team welcomes contributions to the DCCEXProtocol library.
-The best way to get involved is to reach out to the DCC-EX team via our Discord server.
+The DCC-EX team welcomes contributions to the DCCEXProtocol library.
+The best way to get involved is to reach out to the DCC-EX team via our Discord server.
You can also try the other methods outlined on our Contact Us page.
This example demonstrates the basics of creating a WiFi connection to your EX‑CommandStation using the library, and monitoring for broadcasts and command responses.
+This example demonstrates the basics of creating a WiFi connection to your EX‑CommandStation using the library, and monitoring for broadcasts and command responses.
This example builds on the basic example and, in addition, demonstrates how to implement a custom DCCEXProtocolDelegate` class to respond to broadcasts and command responses received from EX‑CommandStation.
+This example builds on the basic example and, in addition, demonstrates how to implement a custom DCCEXProtocolDelegate` class to respond to broadcasts and command responses received from EX‑CommandStation.
This example demonstrates how to retrieve the object types from EX‑CommandStation, and further demonstrates how to use the delegate to display these object lists when received.
+This example demonstrates how to retrieve the object types from EX‑CommandStation, and further demonstrates how to use the delegate to display these object lists when received.
This example demonstrates how client throttle software may be written to control multiple locomotives (or consists for that matter) concurrently.
What can’t be demonstrated in this example is the control of speed and direction, which would typically be accomplished with the use of rotary encoders or similar.
-Note when setting speed and direction, these should be sent to the EX‑CommandStation via the DCCEXProtocol library, and any local references to these should be set based on the response received, not directly by the input method in use.
+Note when setting speed and direction, these should be sent to the EX‑CommandStation via the DCCEXProtocol library, and any local references to these should be set based on the response received, not directly by the input method in use.
For example, when setting the speed based on the position of a rotary encoder, send that value via the protocol’s setThrottle() method, but do not display that speed directly. Instead, utlise the delegate’s receivedLocoUpdate() method to update the displayed speed.
This ensures that the user of the throttle sees the accurate results of what the throttle is doing, and provides validation that the EX-CommandStation is responding to the user input.
The following examples are not strictly related to the DCCEXProtocol library, but hopefully will be useful for anyone developing a throttle to use with any EX‑CommandStation.
+The following examples are not strictly related to the DCCEXProtocol library, but hopefully will be useful for anyone developing a throttle to use with any EX‑CommandStation.
This example demonstrates how client throttle software may be written to find all the SSIDs (networks) that are available.
This example demonstrates how client throttle software may be written to find all the EX‑CommandStation and WiThrottle servers that are advertising via mDNS.
-Note that DCC-EX EX‑CommandStation only advertise as wiThrottle servers, but will use and respond with either the WiThrottle protocol or the DCC-EX
+
This example demonstrates how client throttle software may be written to find all the EX‑CommandStation and WiThrottle servers that are advertising via mDNS.
+Note that DCC-EX EX‑CommandStation only advertise as wiThrottle servers, but will use and respond with either the WiThrottle protocol or the DCC-EX
native command protocol depending the type of command it first receives from the client (throttle).
This library implements the DCC-EX - native command protocol (as used in the DCC-EX EX‑CommandStation ONLY), allowing a device to connect to the server and act as a client (such as a hardware based throttle).
+ native command protocol (as used in the DCC-EX 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 with a serial connection.
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.
+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
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.
+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.
Whilst this library extrapolates the need for understanding the specific DCC-EX native commands from a throttle developer, it is highly recommended to familiarise yourself with the concepts outlined in the https://dcc-ex.com/throttles/tech-reference.html.
+Whilst this library extrapolates the need for understanding the specific DCC-EX native commands from a throttle developer, it is highly recommended to familiarise yourself with the concepts outlined in the https://dcc-ex.com/throttles/tech-reference.html.
Once the DCCEXProtocol object is instantiated, a connection must be made to the EX‑CommandStation using the connect(&stream) method and providing a suitable Arduino Stream, such as a WiFi client or serial connection.
+Once the DCCEXProtocol object is instantiated, a connection must be made to the EX‑CommandStation using the connect(&stream) method and providing a suitable Arduino Stream, such as a WiFi client or serial connection.
It is also recommended to enable logging to an Arduino Stream using the setLogStream(&stream) method.
As covered in the design principles above, you must include the check() method as often as possible to receive command responses and broadcasts and have these processed by the library and any event handlers defined in your custom DCCEXProtocolDelegate class.
Refer to the Examples to see how this may be implemented.
@@ -525,7 +525,7 @@To retrieve the various objects lists from EX‑CommandStation, use the getLists(bool rosterRequired, bool turnoutListRequired, bool routeListRequired, bool turntableListRequired) method within your loop() function to ensure these are retrieved successfully.
+To retrieve the various objects lists from EX‑CommandStation, use the getLists(bool rosterRequired, bool turnoutListRequired, bool routeListRequired, bool turntableListRequired) method within your loop() function to ensure these are retrieved successfully.
All objects are contained within linked lists and can be access via for loops:
for (Loco* loco=dccexProtocol.roster->getFirst(); loco; loco=loco->getNext()) {
// loco methods are available here