diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/MCU_Commands.md | 14 | ||||
| -rw-r--r-- | docs/Protocol.md | 52 |
2 files changed, 38 insertions, 28 deletions
diff --git a/docs/MCU_Commands.md b/docs/MCU_Commands.md index f5019814..c576ad88 100644 --- a/docs/MCU_Commands.md +++ b/docs/MCU_Commands.md @@ -12,7 +12,11 @@ format of commands and their transmission. The commands here are described using their "printf" style syntax - for those unfamiliar with that format, just note that where a '%...' sequence is seen it should be replaced with an actual integer. For example, a description -with "count=%c" could be replaced with the text "count=10". +with "count=%c" could be replaced with the text "count=10". Note that +parameters that are considered "enumerations" (see the above protocol +document) actually take a string value which is automatically +converted to an integer value for the micro-controller. This is common +with parameters named "pin" (or that have a suffix of "_pin"). Startup Commands ================ @@ -23,14 +27,6 @@ commands available for that purpose. Unlike most micro-controller commands, these commands run as soon as they are received and they do not require any particular setup. -Several of these commands will take a "pin=%u" parameter. The -low-level micro-controller software uses integer encodings of the -hardware pin numbers, but to make things more readable the host will -translate human readable pin names (eg, "PA3") to their equivalent -integer encodings. By convention, any parameter named "pin" or that -has a "_pin" suffix will use pin name translation by the -host. - Common startup commands: * `set_digital_out pin=%u value=%c` : This command immediately diff --git a/docs/Protocol.md b/docs/Protocol.md index f73a195a..d10a1186 100644 --- a/docs/Protocol.md +++ b/docs/Protocol.md @@ -109,6 +109,30 @@ output("The value of %u is %s with size %u.", x, buf, buf_len); The output() function is similar in usage to printf() - it is intended to generate and format arbitrary messages for human consumption. +Declaring enumerations +---------------------- + +Enumerations allow the host code to use string identifiers for +parameters that the micro-controller handles as integers. They are +declared in the micro-controller code - for example: + +``` +DECL_ENUMERATION("spi_bus", "spi", 0); + +DECL_ENUMERATION_RANGE("pin", "PC0", 16, 8); +``` + +If the first example, the DECL_ENUMERATION() macro defines an +enumeration for any command/response message with a parameter name of +"spi_bus" or parameter name with a suffix of "_spi_bus". For those +parameters the string "spi" is a valid value and it will be +transmitted with an integer value of zero. + +It's also possible to declare an enumeration range. In the second +example, a "pin" parameter (or any parameter with a suffix of "_pin") +would accept PC0, PC1, PC2, ..., PC7 as valid values. The strings will +be transmitted with integers 16, 17, 18, ..., 23. + Declaring constants ------------------- @@ -119,7 +143,12 @@ DECL_CONSTANT("SERIAL_BAUD", 250000); ``` would export a constant named "SERIAL_BAUD" with a value of 250000 -from the micro-controller to the host. +from the micro-controller to the host. It is also possible to declare +a constant that is a string - for example: + +``` +DECL_CONSTANT_STR("MCU", "pru"); +``` Low-level message encoding ========================== @@ -277,24 +306,9 @@ dictionary. Once all chunks are obtained the host will assemble the chunks, uncompress the data, and parse the contents. In addition to information on the communication protocol, the data -dictionary also contains the software version, constants (as defined -by DECL_CONSTANT), and static strings. - -Static Strings --------------- - -To reduce bandwidth the data dictionary also contains a set of static -strings known to the micro-controller. This is useful when sending -messages from micro-controller to host. For example, if the -micro-controller were to run: - -``` -shutdown("Unable to handle command"); -``` - -The error message would be encoded and sent using a single VLQ. The -host uses the data dictionary to resolve VLQ encoded static string ids -to their associated human-readable strings. +dictionary also contains the software version, enumerations (as +defined by DECL_ENUMERATION), and constants (as defined by +DECL_CONSTANT). Message flow ============ |