|
| 1 | +************************* |
| 2 | +API syntax documentation |
| 3 | +************************* |
| 4 | + |
| 5 | +.. image:: ../_static/images/engineer-level.png |
| 6 | + :alt: Engineer Level |
| 7 | + :scale: 50% |
| 8 | + |
| 9 | +.. sidebar:: On this page |
| 10 | + |
| 11 | + .. contents:: |
| 12 | + :depth: 1 |
| 13 | + :local: |
| 14 | + |
| 15 | +This page documents the API syntax and usage for CommandStation-EX. |
| 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. |
| 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>`_. |
| 20 | + |
| 21 | +For detailed information on the various commands and responses available with DCC++ EX, refer to the :doc:`/reference/software/command-reference` page. |
| 22 | + |
| 23 | +Serial port and WiFi/Ethernet monitoring |
| 24 | +========================================= |
| 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. |
| 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. |
| 29 | + |
| 30 | +**Any input received that a throttle does not understand must be discarded and ignored.** |
| 31 | + |
| 32 | +General API command usage and responses |
| 33 | +======================================== |
| 34 | + |
| 35 | +API commands are sent using the message format outlined below, with responses conforming to the same format. |
| 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. |
| 38 | + |
| 39 | +To repeat from above, any input received that a throttle does not understand should be discarded and ignored. |
| 40 | + |
| 41 | +Command responses |
| 42 | +__________________ |
| 43 | + |
| 44 | +Command responses should conform to the syntax standard to ensure they are processed correctly by throttles. |
| 45 | + |
| 46 | +Broadcast responses |
| 47 | +____________________ |
| 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. |
| 50 | + |
| 51 | +It is mandatory that a throttle accepts and ignores a broadcast it doesn't understand. |
| 52 | + |
| 53 | +Diagnostics and other responses |
| 54 | +________________________________ |
| 55 | + |
| 56 | +If diagnostic commands are enabled, these are sent to the USB serial port. |
| 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. |
| 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 "\*>". |
| 61 | + |
| 62 | +General Message Format |
| 63 | +======================= |
| 64 | + |
| 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: |
| 66 | + |
| 67 | +``<OPCODE Param1 Param2 … ParamX>`` |
| 68 | + |
| 69 | +Messages cannot be nested, and a second "<" inside a message constitutes a syntax error. |
| 70 | + |
| 71 | +Error responses |
| 72 | +================ |
| 73 | + |
| 74 | +A command sent that is invalid or returns an error has a response of ``<X>``. |
| 75 | + |
| 76 | +Memory limitations of prohibit more detailed error messages. |
| 77 | + |
| 78 | +Parameter parsing sequence |
| 79 | +=========================== |
| 80 | + |
| 81 | +To obtain the parameters: |
| 82 | + |
| 83 | +Obtain the OPCODE |
| 84 | +__________________ |
| 85 | + |
| 86 | +The first level of parsing is to obtain the single character, case sensitive OPCODE which is preceeded by a "<" character. |
| 87 | + |
| 88 | +Obtain the parameters |
| 89 | +______________________ |
| 90 | + |
| 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. |
| 92 | + |
| 93 | +Example command and response |
| 94 | +_____________________________ |
| 95 | + |
| 96 | +A simple example is sending an API command to retrieve the list of defined turnouts. |
| 97 | + |
| 98 | +The command to retrieve the list of defined turnouts is ``<JT>``. |
| 99 | + |
| 100 | +Using our syntax standard, "J" is the OPCODE, and "T" is the parameter. |
| 101 | + |
| 102 | +The response for this command will look something like ``<jT 1 17>``. |
| 103 | + |
| 104 | +Using our parsing sequence, we obtain the OPCODE "j", with the subsequent parameters being "T", "1", and "17". |
| 105 | + |
| 106 | +Parameter values |
| 107 | +================= |
| 108 | + |
| 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>. |
| 110 | + |
| 111 | +The translation of parameters from text to integer is base10. |
| 112 | + |
| 113 | +Exceptions |
| 114 | +___________ |
| 115 | + |
| 116 | +Due to legacy code and backwards compatibility requirements, there are two OPCODES that expect hexadecimal parameter values. |
| 117 | + |
| 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. |
0 commit comments