3diy
/
klipper
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Add an example to the description of the message block contents 

Use a more real-world example to improve the description of message
block contents. Make it more clear that the data dictionary contains
and utilizes the full command descriptions.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>
This commit is contained in:
Kevin O'Connor 2016-12-22 13:25:58 -05:00
parent 189ac86b06
commit 9894348e12
1 changed files with 33 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
docs/Protocol.md
View File

@ -152,23 +152,34 @@ Message Block Contents
Each message block sent from host to firmware contains a series of Each message block sent from host to firmware contains a series of
zero or more message commands in its contents. Each command starts zero or more message commands in its contents. Each command starts
with a Variable Length Quantity (VLQ) encoded integer command-id with a Variable Length Quantity (VLQ) encoded integer command-id
followed by zero or more VLQ parameters for the given command. So, the followed by zero or more VLQ parameters for the given command.
contents of an example message block might look like:
As an example, the following four commands might be placed in a single
message block:
``` ```
<id_cmd_a><param1><id_cmd_b><param1><param2><id_cmd_c><id_cmd_d> set_digital_out pin=86 value=1
set_digital_out pin=85 value=0
get_config
get_status
```
and encoded into the following eight VLQ integers:
```
<id_set_digital_out><86><1><id_set_digital_out><85><0><id_get_config><id_get_status>
``` ```
In order to encode and parse the message contents, both the host and In order to encode and parse the message contents, both the host and
firmware must agree on the number of parameters each command has. So, firmware must agree on the command ids and the number of parameters
in the above example, both the host and firmware would know that each command has. So, in the above example, both the host and firmware
"id_cmd_a" is always followed by exactly one parameter, "id_cmd_b" two would know that "id_set_digital_out" is always followed by two
parameters, and "id_cmd_c" / "id_cmd_d" zero parameters. The host and parameters, and "id_get_config" and "id_get_status" have zero
firmware share a "data dictionary" that associates high-level commands parameters. The host and firmware share a "data dictionary" that maps
with specific integer command-ids along with the number of parameters the command descriptions (eg, "set_digital_out pin=%u value=%c") to
that the command takes. When processing the data, the parser will know their integer command-ids. When processing the data, the parser will
to expect a specific number of VLQ encoded parameters following a know to expect a specific number of VLQ encoded parameters following a
given command. given command id.
The message contents for blocks sent from firmware to host follow the The message contents for blocks sent from firmware to host follow the
same format. The identifiers in these messages are "response ids", but same format. The identifiers in these messages are "response ids", but
@ -205,9 +216,9 @@ the length as a VLQ encoded integer followed by the contents itself:
<VLQ encoded length><n-byte contents> <VLQ encoded length><n-byte contents>
``` ```
The data dictionary includes information on each parameter so that The command descriptions found in the data dictionary allow both the
both the host and firmware know which command parameters use simple host and firmware to know which command parameters use simple VLQ
VLQ encoding and which parameters use string encoding. encoding and which parameters use string encoding.
Data Dictionary Data Dictionary
=============== ===============
@ -215,16 +226,14 @@ Data Dictionary
In order for meaningful communications to be established between In order for meaningful communications to be established between
firmware and host, both sides must agree on a "data dictionary". This firmware and host, both sides must agree on a "data dictionary". This
data dictionary contains the integer identifiers for commands and data dictionary contains the integer identifiers for commands and
responses along with the number of parameters and the types of responses along with their descriptions.
parameters for each command/response.
At compile time the firmware build uses the contents of DECL_COMMAND() At compile time the firmware build uses the contents of DECL_COMMAND()
and sendf() macros to generate the data dictionary. The build and sendf() macros to generate the data dictionary. The build
automatically assigns unique identifiers to each command and automatically assigns unique identifiers to each command and
response. The data dictionary maps the high-level names (eg, response. This system allows both the host and firmware code to
"get_status") to the integer command ids. This allows the host and seamlessly use descriptive human-readable names while still using
firmware to use descriptive ASCII names while still using minimal minimal bandwidth.
bandwidth.
The host queries the data dictionary when it first connects to the The host queries the data dictionary when it first connects to the
firmware. Once the host downloads the data dictionary from the firmware. Once the host downloads the data dictionary from the
@ -267,9 +276,9 @@ from firmware to host. For example, if the firmware were to run:
shutdown("Unable to handle command"); shutdown("Unable to handle command");
``` ```
The error message can be encoded and sent using a single VLQ. The host The error message would be encoded and sent using a single VLQ. The
uses the data dictionary to resolve the VLQ encoded static string id host uses the data dictionary to resolve VLQ encoded static string ids
to the associated message in the data dictionary. to their associated human-readable strings.
Message flow Message flow
============ ============