You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/developer-reference/api.rst
+56-86Lines changed: 56 additions & 86 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,137 +12,107 @@ API syntax documentation
12
12
:depth: 1
13
13
:local:
14
14
15
-
This API syntax page defines the current defined syntax used by API commands. These have resulted from a mix of legacy inheritance from the original DCC++ code, in addition to newer commands.
16
-
17
-
Port and WiFi/Ethernet monitoring
18
-
==================================
19
-
20
-
The input collectors must monitor the serial ports on a byte by byte basis, look for a beginning "<" with ending ">", and ignore anything outside that before passing commands in for parsing.
21
-
22
-
The WiFI or ethernet collectors work on a per-transmission basis and the first byte of input determines whether the transmitted block gets sent for parsing as a command or WiThrottle.
23
-
24
-
Parameter parsing sequence
25
-
===========================
26
-
27
-
To obtain the parameters
28
-
29
-
The first level of parsing is to obtain the single character, case sensitive OPCODE which may be preceeded by any number of blanks or a "<" character.
30
-
31
-
The second level of parsing takes the next non-blank parameter along with each blank separated parameter and turns them into integers. There are no decimal point or float inputs. A prefix "-" may be used.
32
-
33
-
For example, sending the command ``<JT>`` to obtain the list of turnouts responds with something like ``<jT 1 17>``.
34
-
35
-
The OPCODE is "j", with the subsequent parameters being "T", "1", and "17".
36
-
37
-
Parameters containing "a-z", "A-Z", or "_" are hashed to create integers. Thus a command like <D WIFI ON> is internally identical to <D wifi on>.
38
-
39
-
* Some OPCODES are documented in a way that indicates they may have two characters, eg. <Jt ...>. This does not break the syntax rule, and in this example "J" is the OPCODE, with "t" as the first parameter.
40
-
41
-
The translation of parameters from text to integer is normally base10 but for two specific opcodes the parser is instructed to operate in hex. That's just history.
42
-
Parameters may be separated by any number of spaces but using more than one is wasting cs comms and cpu power and should be discouraged.
43
-
There is no need to put a space between the opcode and the first parameter although it is often more readable tjat way. ( I have described the J command as if it were a two character opcode but <JT> <Jt> and < J T > are all the same thing to the parser.
44
-
Memory prohibits fancy error messages for all the things that can be wrong.. a reply of <X> is commonly used
45
-
46
-
I think from the above, its best to only formalise the way it should work rather than rhe myriad of relaxed ways it might work.. eg one space between parameters.
47
-
Responses... are a separate issue.
48
-
Responses and broadcasts fall into several categories
49
-
- broadcast information sent to all throttles. There are a couple of issues here where we send the <> and withrottle responses together to all throttles in the knowledge that each will ignore the irrelevant one. We can choose the define the interface on the basis that throttles should ignore what's not for them or we could split the broadcast at the expense of processing time on the cs.
50
-
51
-
- direct responses to commands. Yes we should fix any that are not correctly wrapped.
52
-
53
-
- diagnostics sent to usb serial. If you connect the throttle to the USB serial... you will get these correctly wrapped but do not expect to understand them.
54
-
55
-
If, however, someone turns on wifi debug or uses the <+> command then the wrapping can no longer be guaranteed as the wifi traffic may contain "\*>".
56
-
57
-
58
-
It's also important to specify that the cs is not in position to maintain a conversation about which throttle supports which broadcasts... so it should be mandatory that a throttle accept and ignore a broadcast it doesn't understand.
59
-
15
+
This page documents the API syntax and usage for CommandStation-EX.
60
16
17
+
The current API has resulted from a mix of new commands and commands inherited from the original DCC++ code base, and therefore there are some noted exceptions to the syntax, however all new commands and responses must conform to the correct syntax.
61
18
19
+
If you are looking for information on the WiThrottle protocol, you will find that documented on the `JMRI website <https://www.jmri.org/help/en/package/jmri/jmrit/withrottle/Protocol.shtml>`_.
62
20
21
+
For detailed information on the various commands and responses available with DCC++ EX, refer to the :doc:`/reference/software/command-reference` page.
63
22
23
+
Serial port and WiFi/Ethernet monitoring
24
+
=========================================
64
25
26
+
The input collectors must monitor the serial ports on a byte by byte basis, look for a beginning "<" with ending ">", and ignore anything outside that before passing commands in for parsing.
65
27
28
+
The WiFI or ethernet collectors work on a per-transmission basis and the first byte of input determines whether the transmitted block gets sent for parsing as an API or WiThrottle command or response.
66
29
30
+
**Any input received that a throttle does not understand must be discarded and ignored.**
67
31
32
+
General API command usage and responses
33
+
========================================
68
34
35
+
API commands are sent using the message format outlined below, with responses conforming to the same format.
69
36
37
+
Due to the nature of DCC++ EX being able to be operated by multiple throttles concurrently combined with the fact there is no unique throttle identifier, there is no guarantee that a response received directly after a command is sent is related. Care must be taken to take this into account.
70
38
39
+
To repeat from above, any input received that a throttle does not understand should be discarded and ignored.
71
40
41
+
Command responses
42
+
__________________
72
43
44
+
Command responses should conform to the syntax standard to ensure they are processed correctly by throttles.
73
45
46
+
Broadcast responses
47
+
____________________
74
48
49
+
Broadcast information is sent to all throttles along with WiThrottle responses on the understanding that throttles will discard and ignore any responses they do not understand.
75
50
51
+
It is mandatory that a throttle accepts and ignores a broadcast it doesn't understand.
76
52
53
+
Diagnostics and other responses
54
+
________________________________
77
55
56
+
If diagnostic commands are enabled, these are sent to the USB serial port.
78
57
58
+
If you connect a throttle to the USB serial port, you will get these correctly wrapped but do not expect to understand them.
79
59
60
+
If, however, WiFi debug is enabled, or the <+> command is used, then the wrapping can no longer be guaranteed as the wifi traffic may contain "\*>".
80
61
81
-
3. General Message Format
82
-
==========================
62
+
General Message Format
63
+
=======================
83
64
84
65
A DCC++EX API message consists of a leading "<" symbol, a single character OPCODE, zero to n parameters separated by spaces, and a terminating ">" symbol:
85
66
86
67
``<OPCODE Param1 Param2 … ParamX>``
87
68
88
69
Messages cannot be nested, and a second "<" inside a message constitutes a syntax error.
89
70
90
-
Spaces between the leading "<" symbol and the OPCODE, between the OPCODE and the start of the first parameter, and between the end of the last parameter and the trailing ">" symbol are optional.
71
+
Error responses
72
+
================
91
73
92
-
Examples for valid formats for a <p1> return message:
74
+
A command sent that is invalid or returns an error has a response of ``<X>``.
93
75
94
-
.. code-block::
76
+
Memory limitations of prohibit more detailed error messages.
95
77
96
-
<p1>
97
-
<p 1>
98
-
< p1>
99
-
< p 1>
100
-
<p1 >
101
-
102
-
2. OPCODE Format
103
-
=================
104
-
105
-
OPCODEs are single, case sensitive characters immediately following the leading "<" symbol, or separated from it by one or more spaces. In other words: The first non-blank character after the leading "<" symbol is the OPCODE.
78
+
Parameter parsing sequence
79
+
===========================
106
80
107
-
2.1. Reserved OPCODEs
108
-
______________________
81
+
To obtain the parameters:
109
82
110
-
"*" is a reserved OPCODE for comment lines. The entire content of the message up to the closing ">" symbol is a comment and does not have to follow any rules.
83
+
Obtain the OPCODE
84
+
__________________
111
85
112
-
3. General Parameter Format
113
-
============================
86
+
The first level of parsing is to obtain the single character, case sensitive OPCODE which is preceeded by a "<" character.
114
87
115
-
A message parameter is a sequence of characters. Depending on the content, parameters can be of several data types as outlined below. A message can have any number of parameters separated by space symbols. The first parameter of the message may or may not be separated from the OPCODE by a space symbol.
88
+
Obtain the parameters
89
+
______________________
116
90
117
-
4. Parameter Data Types
118
-
========================
91
+
The second level of parsing takes the next non-blank parameter along with each blank separated parameter and turns them into integers. There are no decimal point or float inputs. A prefix "-" may be used.
119
92
120
-
4.1. Keyword Parameters
121
-
________________________
93
+
Example command and response
94
+
_____________________________
122
95
123
-
A sequence of characters without space symbol. The first character after the space separator must not be a ‘”’ symbol. Example: Keyword JOIN in <p1 JOIN>
96
+
A simple example is sending an API command to retrieve the list of defined turnouts.
124
97
125
-
4.2. Numerical Parameters
126
-
__________________________
98
+
The command to retrieve the list of defined turnouts is ``<JT>``.
127
99
128
-
Numerical values are a sequence of characters that represent a numerical value. Several formats are possible:
100
+
Using our syntax standard, "J" is the OPCODE, and "T" is the parameter.
129
101
130
-
4.2.1. Decimal integer
131
-
^^^^^^^^^^^^^^^^^^^^^^^
102
+
The response for this command will look something like ``<jT 1 17>``.
132
103
133
-
optional "-" symbol to indicate a negative value, followed by a sequence of decimal digits ("0".."9")
104
+
Using our parsing sequence, we obtain the OPCODE "j", with the subsequent parameters being "T", "1", and "17".
134
105
135
-
4.2.2. Hexadecimal integer
136
-
^^^^^^^^^^^^^^^^^^^^^^^^^^^
106
+
Parameter values
107
+
=================
137
108
138
-
"$" marker symbol , followed by a sequence of hex digits ("0".."9", "A".."F") forming a hexadecimal integer. Examples: $2367, $B5C2
109
+
Parameters containing "a-z", "A-Z", or "_" are hashed to create integers. Thus a command like <D WIFI ON> is internally identical to <D wifi on>.
139
110
140
-
4.2.3. Binary integer
141
-
^^^^^^^^^^^^^^^^^^^^^^
111
+
The translation of parameters from text to integer is base10.
142
112
143
-
"%" marker symbol followed by a sequence of binary digits ("0".."1") forming a hexadecimal integer. Examples: %01100011, %1100
113
+
Exceptions
114
+
___________
144
115
145
-
4.2.5. String Parameter
146
-
^^^^^^^^^^^^^^^^^^^^^^^^
116
+
Due to legacy code and backwards compatibility requirements, there are two OPCODES that expect hexadecimal parameter values.
147
117
148
-
A string parameter is sequence of characters starting and ending with a ‘”’ symbol. Between these symbols, any character, including "*" and Space, is acceptable, except for the ‘”’ itself.
118
+
These are the ``<M>`` and ``<P>`` commands documented in the :ref:`reference/software/command-reference:send packet to the track` section of the Command Reference.
Copy file name to clipboardExpand all lines: docs/reference/software/command-reference.rst
+6-14Lines changed: 6 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,12 @@
2
2
DCC++ EX Command Reference
3
3
****************************
4
4
5
+
.. sidebar:: On this page
6
+
7
+
.. contents::
8
+
:depth: 1
9
+
:local:
10
+
5
11
This is a detailed reference. For a summary version, please see :doc:`Command Summary <command-summary>`
6
12
7
13
`CommandStation-EX <https://github.com/DCC-EX/CommandStation-EX>`_ Provides an Application Programming Interface (API) that other applications use to send simple text commands that can operate your Command Station. Several "front end" controllers are available or you can easily create your own. Here are some examples:
@@ -20,18 +26,6 @@ This reference explains the available command structure, and for commands that p
20
26
21
27
You can view and edit this code in the `Arduino IDE <https://www.arduino.cc/en/Main/Software>`_ or in `PlatformIO <https://github.com/DCC-EX/CommandStation-EX/blob/master/CONTRIBUTING.md>`_ Software from `GitHub <https://github.com/DCC-EX>`_. If you are new to we suggest you start with the `DCC++ EX Webpage <https://dcc-ex.com>`_.
22
28
23
-
24
-
* :ref:`reference/software/command-reference:Track Power Commands`
0 commit comments