Doco updates done for now

CMakeLists.txt

@@ -19,7 +19,7 @@ find_package(Doxygen)
 if(DOXYGEN_FOUND)
   message("Found Doxygen")
   set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in)
-  set(DOXYGEN_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.out)
+  set(DOXYGEN_OUT ${CMAKE_CURRENT_SOURCE_DIR}/build/Doxyfile.out)
 
   # request to configure the file
   configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)

README.md

@@ -1,4 +1,8 @@
 
+# DCCEXProtocol
+
+For the full documentation, please refer to the [DCC-EX website](https://dcc-ex.com/DCCEXProtocol/index.html).
+
 # Credits
 
 The delegate and connection code in this library is taken directly from the WiThrottle library by **Copyright © 2018-2019 Blue Knobby Systems Inc.**
@@ -24,15 +28,15 @@ These patterns (Dependency Injection and Delegation) allow you to keep the diffe
 
 ### DCCEXProtocol Class
 
-Full documentation of the classes is available via the [DCC-EX website](file:///C:/Code/DCCEXProtocol/docs/_build/html/index.html).
+Full documentation of the classes is available via the [DCC-EX website](https://dcc-ex.com/DCCEXProtocol/index.html).
 
 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
+- Turnouts/Points
 - Turntables (noting that these objects are only available in development versions)
 
 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.
@@ -43,124 +47,6 @@ The DCCEXProtocolDelegate class enables the client software to respond to variou
 
 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.
 
-## Included examples
-
-Note that all included examples use WiFi, but the protocol is equally suited to other connection types utilising the Arduino Stream base class including Ethernet and Serial.
-
-### DCCEXProtocol_Basic
-
-Basic example to implement a DCCEXProtocol client and connect to a server (with static IP).
-
-Change the WiFi settings and enter the IP address of the Arduino running EX-CommandStation:
-
-``` cpp
-const char* ssid = "MySSID";
-const char* password =  "MyPWD";
-IPAddress serverAddress(192,168,1,1);
-```
-
-Compile and run, you should see the client connect in the Serial monitor.
-
-### DCCEX_Delegate
-
-Example to show how to implement a delegate class to handle callbacks.
-
-Compile and run, you should see in the Serial monitor the server version printed.
-
-### DCCEXProtocol_Roster_etc
-
-Example to show how to retrieve the Roster, Turnouts/Point list, Routes/Automations List, and Turntable List for the Server.
-
-Compile and run, you should see in the Serial monitor the lists printed.
-
-### DCCEXProtocol_Loco_Control
-
-Example to show how to acquire and control locos. The Example assumes that you have a Roster on the EX-CommandStation with at least two entries.
-
-Compile and run, you should see in the Serial monitor, after 20 second delays, two locos on two throttles change speed, and have functions randomly change.
-
-----
-
-# Usage
-
-## Throttles
-
-To simplify the handling of Consists/Multiple Unit Trains the library is implemented to behave in a similar manner to the WiThrottle(TM) protocol, in that it *requires* that locos are attached to a 'throttle'.
-
-The protocol provides for the throttle app to specify the number of throttles required ```DCCEXProtocol(int maxThrottles=6, bool server=false);```
-
-For simple applications controlling a single loco, this adds a small amount of overhead, but the cons of this small overhead are far outweighed by the benefits of being able to manage multiple locos as consists without needing to program CVs every time you wish to assemble a consist (although speed matching is still obviously required).
-
-To acquire a loco on throttle 0 (zero) (the first throttle), you must specify a DDC address or a loco from the roster.
-
-From a DCC Address:
-
-```dccexProtocol.throttle[0].addFromEntry(11, FacingForward);``` will add a loco with a DCC address of 11 on throttle 0, facing forward.
-
-From a Roster Entry:
-
-To add the loco to the throttle use ```dccexProtocol.throttle[0].addFromRoster(dccexProtocol.getRosterEntryNo(1), FacingForward);``` to add a loco to Throttle 0, facing forward.
-
-Control the speed and direction of all the locos on Throttle 0 with ```dccexProtocol.sendThrottleAction(0, speed, Forward);```
-
-## Rosters
-
-The Roster is stored as a Linked List.
-
-Retrieve the list with ```dccexProtocol.getRoster();```
-
-Or with ```dccexProtocol.getLists(bool rosterRequired, bool turnoutListRequired, bool routeListRequired, bool turntableListRequired);```
-
-The roster has been fully received when ```isRosterFullyReceived()``` is true.
-
-Retrieve the size of the list (number of locos) with ```dccexProtocol.getRosterCount()```
-
-Retrieve a ```Loco*``` object from the list with ```dccexProtocol.getRosterEntryNo(listEntryNumber)```
-
-## Turnouts/Points
-
-The List of defined Turnouts/Points is stored as a Linked List.
-
-Retrieve the list with ```dccexProtocol.getTurnouts();```
-
-Or with ```dccexProtocol.getLists(bool rosterRequired, bool turnoutListRequired, bool routeListRequired, bool turntableListRequired);```
-
-The list has been fully received when ```isTurnoutListFullyReceived()``` is true.
-
-Retrieve the size of the list with ```dccexProtocol.getTurnoutsCount()```
-
-Retrieve a ```Turnout*``` object from the list with ```dccexProtocol.getTurnoutsEntryNo(listEntryNumber)```
-
-## Routes/Automations
-
-The List of defined Routes/Automations is stored as a Linked List.
-
-Retrieve the list with ```dccexProtocol.getRoutes();```
-
-Or with ```dccexProtocol.getLists(bool rosterRequired, bool turnoutListRequired, bool routeListRequired, bool turntableListRequired);```
-
-The list has been fully received when ```isRouteListFullyReceived()``` is true.
-
-Retrieve the size of the list with ```dccexProtocol.getRoutesCount()```
-
-Retrieve a ```Route*``` object from the list with ```dccexProtocol.getRoutesEntryNo(listEntryNumber)```
-
-## Turntables
-
-The List of defined Turntables is stored as a Linked List.
-
-Retrieve the list with ```dccexProtocol.getTurntables();```
-
-Or with ```dccexProtocol.getLists(bool rosterRequired, bool turnoutListRequired, bool routeListRequired, bool turntableListRequired);```
-
-The list has been fully received when ```isTurntableListFullyReceived()``` is true.
-
-Retrieve the size of the list with ```dccexProtocol.getTurntablesCount()```
-
-Retrieve a ```Turntable*``` object from the list with ```dccexProtocol.getTurntablesEntryNo(listEntryNumber)```
-
-----
-
 # Documentation
 
 Documentation of the DCCEXProtocol library is available via the [DCC-EX website](file:///C:/Code/DCCEXProtocol/docs/_build/html/index.html).

docs/conf.py

@@ -3,9 +3,9 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-from sphinx.builders.html import StandaloneHTMLBuilder
+# from sphinx.builders.html import StandaloneHTMLBuilder
 import subprocess
-import os
+# import os
 
 # Doxygen
 subprocess.call('doxygen Doxyfile.in', shell=True)
@@ -21,7 +21,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-  # 'sphinx_sitemap',
+  'sphinx_sitemap',
   'sphinxcontrib.spelling',
   'sphinx_rtd_dark_mode',
   'breathe'
@@ -32,8 +32,8 @@
 # Don't make dark mode the user default
 default_dark_mode = False
 
-spelling_lang='en_UK'
-tokenizer_lang='en_UK'
+spelling_lang = 'en_UK'
+tokenizer_lang = 'en_UK'
 spelling_word_list_filename = ['spelling_wordlist.txt']
 
 templates_path = ['_templates']
@@ -63,10 +63,10 @@
     # 'titles_only': False,
     'titles_only': True,
     'collapse_navigation': False,
-    # 'navigation_depth': 3
-     'navigation_depth': -1 
+    # 'navigation_depth': 3,
+    'navigation_depth': -1,
 }
- 
+
 html_context = {
     'display_github': True,
     'github_user': 'DCC-EX',
@@ -79,10 +79,16 @@
     'css/sphinx_design_overrides.css',
 ]
 
+# Sphinx sitemap
+html_baseurl = 'https://dcc-ex.com/DCCEXProtocol/'
+html_extra_path = [
+  'robots.txt',
+]
+
 # -- Breathe configuration -------------------------------------------------
 
 breathe_projects = {
   "DCCEXProtocol": "_build/xml/"
 }
-breathe_default_project = "C++ Sphinx Doxygen Breathe"
-breathe_default_members = ('members', 'undoc-members')
+breathe_default_project = "DCCEXProtocol"
+breathe_default_members = ()

docs/documentation.rst

@@ -0,0 +1,19 @@
+Documentation
+=============
+
+This documentation is available via the `DCC-EX website <https://dcc-ex.com/DCCEXProtocol/index.html>`_.
+
+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 `MSYS2 C++ <https://code.visualstudio.com/docs/cpp/config-mingw#_prerequisites>`_ compilers
+- Install `CMake <https://cmake.org/download/>`_ and ensure you select the option to add to your user path
+- Install `Doxygen <https://www.doxygen.nl/download.html>`_ and once complete, add to your user path
+- Install the CMake Tools extension in VSCode
+- 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"
+
+Credit for how to do this to the following:
+
+- Oliver K Ernst on `Medium <https://medium.com/practical-coding/c-documentation-with-doxygen-cmake-sphinx-breathe-for-those-of-use-who-are-totally-lost-7d555386fe13>`_
+- Sy Brand in her `Microsoft Blog <https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/>`_

docs/examples.rst

@@ -0,0 +1,58 @@
+Examples
+========
+
+Several examples have been included to demonstrate functionality of the library.
+
+Note that all included examples use a WiFi connection, but the protocol is equally suited to other connections types utilising the Arduino Stream base class including Ethernet and Serial.
+
+To configure WiFi for your settings in all examples, you will need to copy the provided "config.example.h" to "config.h" and update the parameters to suit your environment:
+
+.. code-block:: cpp
+
+  const char* ssid = "YOUR_SSID_HERE";          // WiFi SSID name here
+  const char* password =  "YOUR_PASSWORD_HERE"; // WiFi password here
+  IPAddress serverAddress(192,168,4,1);         // IP address of your EX-CommandStation
+  int serverPort = 2560;                        // Network port of your EX-CommandStation
+
+DCCEXProtocol_Basic
+-------------------
+
+This example demonstrates the basics of creating a WiFi connection to your EX-CommandStation using the library, and monitoring for broadcasts and command responses.
+
+DCCEXProtocol_Delegate
+----------------------
+
+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.
+
+DCCEXProtocol_Roster_etc
+------------------------
+
+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.
+
+DCCEXProtocol_Loco_Control
+--------------------------
+
+This example demonstrates basic locomotive speed and function control using dummy DCC addresses, in addition to controlling track power and further use of the delegate to notify when updates to the locomotive have been received.
+
+DCCEXProtocol_Consist_Control
+-----------------------------
+
+This example demonstrates how to setup a software based consist (similar to how this is accomplished in Engine Driver), with basic speed and function control of the configured dummy locomotives. The delegate is also used to notify when updates to the configured locomotives have been received.
+
+DCCEXProtocol_Turnout_control
+-----------------------------
+
+This example demonstrates the basics of controlling turnouts (or points) with the library, including being notified via the delegate when turnout/point objects have been closed/thrown.
+
+DCCEXProtocol_Multi_Throttle_Control
+------------------------------------
+
+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.
+
+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.

docs/index.rst

@@ -1,23 +1,33 @@
-.. DCCEXProtocol documentation master file, created by
-   sphinx-quickstart on Thu Nov 30 15:09:50 2023.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to DCCEXProtocol's documentation!
-=========================================
+Documentation for the DCC-EX Native command library - DCCEXProtocol
+===================================================================
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+  :maxdepth: 4
+  :hidden:
+
+  self
+  overview
+  examples
+  library
+  documentation
+
+Credits
+-------
+
+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).
+
+DCC-EX Native command protocol library
+--------------------------------------
+
+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 with a serial connection.
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`search`
-
-Library
-=======
-
-.. doxygenindex:: 
-  :project: DCCEXProtocol

docs/library.rst

@@ -0,0 +1,5 @@
+Library
+=======
+
+.. doxygenindex:: 
+  :project: DCCEXProtocol