Merge pull request DCC-EX#177 from DCC-EX/sphinx

flash62au · web-flow · commit 4d7d33aad551 · 2025-03-23T08:40:55.000+10:00
catchup
diff --git a/docs/include/include-l0.rst b/docs/include/include-l0.rst
@@ -64,6 +64,10 @@
 
   <span class="ex-suffix">TrackManager</span>
 ..
+.. |DCC-EXP| raw:: html
+
+  <a href="./throttles/native-protocol-library.html"><span class="dccex-suffix">DCCEX</span><span class="dccex-prefix">Protocol</span></a>
+..
 .. ................................................
 ..
 .. |EX-CSB1-LOGO-SMALL| image:: /_static/images/logos/product-logo-ex-csb1.png
diff --git a/docs/include/include-l1.rst b/docs/include/include-l1.rst
@@ -64,6 +64,10 @@
 
   <span class="ex-suffix">TrackManager</span>
 ..
+.. |DCC-EXP| raw:: html
+
+  <a href="../throttles/native-protocol-library.html"><span class="dccex-suffix">DCCEX</span><span class="dccex-prefix">Protocol</span></a>
+..
 .. ................................................
 .. |EX-CSB1-LOGO-SMALL| image:: /_static/images/logos/product-logo-ex-csb1.png
       :alt: EX-CSB1 Logo
diff --git a/docs/include/include-l2.rst b/docs/include/include-l2.rst
@@ -64,6 +64,10 @@
 
   <span class="ex-suffix">TrackManager</span>
 ..
+.. |DCC-EXP| raw:: html
+
+  <a href="../../throttles/native-protocol-library.html"><span class="dccex-suffix">DCCEX</span><span class="dccex-prefix">Protocol</span></a>
+..
 .. ................................................
 ..
 .. |EX-CSB1-LOGO-SMALL| image:: /_static/images/logos/product-logo-ex-csb1.png
diff --git a/docs/include/include-l3.rst b/docs/include/include-l3.rst
@@ -64,6 +64,10 @@
 
   <span class="ex-suffix">TrackManager</span>
 ..
+.. |DCC-EXP| raw:: html
+
+  <a href="../../../throttles/native-protocol-library.html"><span class="dccex-suffix">DCCEX</span><span class="dccex-prefix">Protocol</span></a>
+..
 .. ................................................
 ..
 .. |EX-CSB1-LOGO-SMALL| image:: /_static/images/logos/product-logo-ex-csb1.png
diff --git a/docs/news/posts/20250313.rst b/docs/news/posts/20250313.rst
@@ -0,0 +1,62 @@
+.. include:: /include/include.rst
+.. include:: /include/include-l2.rst
+.. include:: /include/include-news.rst
+
+:blogpost: true
+:date: 13 March, 2025
+:author: peteGSX
+:category: News
+:tags: release, dcc-ex, news, dccexprotocol
+:image: 0
+
+.. image:: /_static/images/logos/product-logo-news.png
+  :alt: DCC-EX News
+  :scale: 40%
+  :class: image-product-logo-float-right
+
+|NATIVE-PROTOCOL_LIBRARY-LOGO|
+
+Announcing DCCEXProtocol Library 1.2.0
+======================================
+
+We've released the latest version of the |DCC-EXP| library version 1.2.0 today.
+
+This release adds the ability to read/write CVs on both the main and programming tracks:
+
+- handOffLoco(locoAddress, automationId)
+
+  - Use this to send a loco to an EXRAIL automation.
+  - You must enable retrieving routes, and the automationId must match a valid EXRAIL automation ID to work.
+
+- readCV(cv) and validateCV(cv, value)
+
+  - Read or validate a CV for a loco on the programming track.
+  - The associated delegate method to implement is receivedValidateCV(int cv, int value) as both return the same response.
+
+- writeLocoAddress(address)
+
+  - Write the provided address to a loco on the programming track.
+  - The associated delegate method to implement is receivedWriteLoco(int address).
+
+- validateCVBit(cv, bit, value)
+
+  - Validate the specified bit of a CV for a loco on the programming track.
+  - The associated delegate method to implement is receivedValidateCVBit(int cv, int bit, int value).
+
+- writeCV(cv, value)
+
+  - Write a CV to a loco on the programming track.
+  - The associated delegate method to implement is receivedWriteCV(int cv, int value).
+
+- writeCVBit(cv, bit, value)
+
+  - Write the specified value to the specified bit of a CV to a loco on the programming track.
+  - There is no delegate method to implement for the response for this due to parser limitations, and we recommend writing full CVs.
+
+- writeCVOnMain(address, cv, value)
+
+  - Write to the specified CV to the specified loco on the main track.
+
+- writeCVBitOnMain(address, cv, bit, value)
+
+  - Write to the specified bit and CV to the specified loco on the main track.
diff --git a/docs/reference/software/command-summary-consolidated.rst b/docs/reference/software/command-summary-consolidated.rst
@@ -1297,7 +1297,7 @@ Writing CVs - Program on the main
   |_| > **bit:** ???  |BR|
   |_| > **value:** The value to be written to the Configuration Variable memory location (0-255)
   
-  *Response:* ???
+  *Response:* N/A
 
 |hr-dashed|
 
@@ -1338,13 +1338,14 @@ By design, for safety reasons, the NMRA specification prevents locos from respon
   |_| > **cv:** CV number
 
   *Response:* |BR|
-  |_| ``<r cv value>`` |BR|
-  |_| > **cv:** The number of the Configuration Variable memory location in the decoder to write to (1-1024) |BR|
+  |_| ``<v cv value>`` |BR|
+  |_| > **cv:** The number of the Configuration Variable memory location in the decoder (1-1024) |BR|
   |_| > **value:** one of |BR|
   |_| |_| |_| |_| • value of the CV |BR|
   |_| |_| |_| |_| • -1: if the write failed
 
-  *Example:* ``<r 3450>`` shows that Loco with ID **3450** is on the programming track.
+  *Example:* ``<v 1 3>`` shows that the value ``3`` is stored in CV ``1``. |BR|
+  *Example:* ``<v 1 -1>`` shows that reading the value stored in CV ``1`` failed.
 
 |hr-dashed|
 
@@ -1384,9 +1385,17 @@ By design, for safety reasons, the NMRA specification prevents locos from respon
   |_| |_| |_| |_| • 0=off
  
   *Response:* |BR|
-  |_| Response (successful): **0 | 1** |BR|
-  |_| Response (fail): **<V -1>**
+  |_| ``<v cv bit onOff>`` |BR|
+  |_| > **cv:** CV number |BR|
+  |_| > **bit:** bit to verify in the CV |BR|
+  |_| > **onOff:** one of |BR|
+  |_| |_| |_| |_| • 1=on  |BR|
+  |_| |_| |_| |_| • 0=off |BR|
+  |_| |_| |_| |_| • -1=error
 
+  *Example:* ``<v 1 3 1>`` shows that the value ``1`` is stored in bit ``3`` of CV ``1``. |BR|
+  *Example:* ``<v 1 3 -1>`` shows verifying the value stored in bit ``3`` of CV ``1`` failed.
+  
   *Notes:*
 
     This command is designed to offer faster verification of the value held in a CV and can be used instead of the ``<R>`` commands. Instead of reading a bit value, it compares the bit to an expected value. It will attempt to verify the value first, an if it is successful, will return the value as if it was simply “read”. If the verify fails, it will perform a read bit command (see above) and return the value read.
@@ -1408,7 +1417,10 @@ By design, for safety reasons, the NMRA specification prevents locos from respon
   |_| > **cv:** CV number |BR|
   |_| > **value:** one of |BR|
   |_| |_| |_| |_| • actual value of the CV |BR|
-  |_| |_| |_| |_| • -1: if the write failed
+  |_| |_| |_| |_| • -1: if the verify failed
+
+  *Example:* ``<v 1 3>`` shows that the value ``3`` is stored in CV ``1``. |BR|
+  *Example:* ``<v 1 -1>`` shows verifying the value stored in CV ``1`` failed.
 
   *Notes:*
 
@@ -1428,7 +1440,20 @@ By design, for safety reasons, the NMRA specification prevents locos from respon
   |_| |_| |_| |_| • 1=on  |BR|
   |_| |_| |_| |_| • 0=off
   
-  *Response:* ???
+  *Response:* |BR|
+  |_| ``<r0|0|cv bit onOff>`` |BR|
+  |_| > **cv:** CV number |BR|
+  |_| > **bit:** bit changed |BR|
+  |_| > **onOff:** one of |BR|
+  |_| |_| |_| |_| • 0|1 |BR|
+  |_| |_| |_| |_| • -1: if the write failed
+
+  *Example:* ``<r0|0|1 3 1>`` shows that the value ``1`` was written to bit ``3`` of CV ``1``. |BR|
+  *Example:* ``<r0|0|1 3 -1>`` shows that writing to bit ``3`` of CV ``1`` failed.
+
+  *Notes:*
+
+    The response is a legacy DCC++ formatted response that is hard to parse, and it is recommended to write full CVs where possible.
 
 |hr-dashed|
 
@@ -1442,12 +1467,15 @@ By design, for safety reasons, the NMRA specification prevents locos from respon
   |_| > **value:** value to change the CV to
 
   *Response:* |BR|
-  |_| ``<w cv value>`` |BR|
+  |_| ``<r cv value>`` |BR|
   |_| > **cv:** CV number |BR|
   |_| > **value:** one of |BR|
   |_| |_| |_| |_| • value CV was changed to |BR|
   |_| |_| |_| |_| • -1: if the write failed
 
+  *Example:* ``<r 1 3>`` shows that the value ``3`` was written to CV ``1``. |BR|
+  *Example:* ``<r 1 -1>`` shows writing a value to CV ``1`` failed.
+
 |hr-dashed|
 
 .. _native-command-w-address:
diff --git a/docs/throttles/native-protocol-library.rst b/docs/throttles/native-protocol-library.rst
@@ -13,4 +13,4 @@ A DCC-EX Native command protocol library is available to help develop throttle a
 
 The library implements the DCC-EX Native command protocol (as used in the |DCC-EX| |EX-CS| ONLY), allowing a device to connect to the server and act as a client (such as a hardware based throttle).
 
-Details of the library, including instructions and examples, `is available here <https://dcc-ex.com/DCCEXProtocol/index.html>`_ |EXTERNAL-LINK|.
+Details of the library, including instructions and examples, `is available here <https://dcc-ex.com/DCCEXProtocol/index.html>`__ |EXTERNAL-LINK|.

Original file line number	Diff line number	Diff line change
`@@ -13,4 +13,4 @@ A DCC-EX Native command protocol library is available to help develop throttle a`
`13`	`13`
`14`	`14`	`The library implements the DCC-EX Native command protocol (as used in the \|DCC-EX\| \|EX-CS\| ONLY), allowing a device to connect to the server and act as a client (such as a hardware based throttle).`
`15`	`15`
`16`		-Details of the library, including instructions and examples, `is available here <https://dcc-ex.com/DCCEXProtocol/index.html>`_ \|EXTERNAL-LINK\|.
	`16`	+Details of the library, including instructions and examples, `is available here <https://dcc-ex.com/DCCEXProtocol/index.html>`__ \|EXTERNAL-LINK\|.