From 9894348e12d78b62defbbb4be606b839cfe3a818 Mon Sep 17 00:00:00 2001 From: Kevin O'Connor Date: Thu, 22 Dec 2016 13:25:58 -0500 Subject: [PATCH] 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 --- docs/Protocol.md | 57 ++++++++++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/docs/Protocol.md b/docs/Protocol.md index 7df66131..12d5e1ce 100644 --- a/docs/Protocol.md +++ b/docs/Protocol.md @@ -152,23 +152,34 @@ Message Block Contents Each message block sent from host to firmware contains a series of zero or more message commands in its contents. Each command starts with a Variable Length Quantity (VLQ) encoded integer command-id -followed by zero or more VLQ parameters for the given command. So, the -contents of an example message block might look like: +followed by zero or more VLQ parameters for the given command. + +As an example, the following four commands might be placed in a single +message block: ``` - +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: + +``` +<86><1><85><0> ``` 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, -in the above example, both the host and firmware would know that -"id_cmd_a" is always followed by exactly one parameter, "id_cmd_b" two -parameters, and "id_cmd_c" / "id_cmd_d" zero parameters. The host and -firmware share a "data dictionary" that associates high-level commands -with specific integer command-ids along with the number of parameters -that the command takes. When processing the data, the parser will know -to expect a specific number of VLQ encoded parameters following a -given command. +firmware must agree on the command ids and the number of parameters +each command has. So, in the above example, both the host and firmware +would know that "id_set_digital_out" is always followed by two +parameters, and "id_get_config" and "id_get_status" have zero +parameters. The host and firmware share a "data dictionary" that maps +the command descriptions (eg, "set_digital_out pin=%u value=%c") to +their integer command-ids. When processing the data, the parser will +know to expect a specific number of VLQ encoded parameters following a +given command id. The message contents for blocks sent from firmware to host follow the 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: ``` -The data dictionary includes information on each parameter so that -both the host and firmware know which command parameters use simple -VLQ encoding and which parameters use string encoding. +The command descriptions found in the data dictionary allow both the +host and firmware to know which command parameters use simple VLQ +encoding and which parameters use string encoding. Data Dictionary =============== @@ -215,16 +226,14 @@ Data Dictionary In order for meaningful communications to be established between firmware and host, both sides must agree on a "data dictionary". This data dictionary contains the integer identifiers for commands and -responses along with the number of parameters and the types of -parameters for each command/response. +responses along with their descriptions. At compile time the firmware build uses the contents of DECL_COMMAND() and sendf() macros to generate the data dictionary. The build automatically assigns unique identifiers to each command and -response. The data dictionary maps the high-level names (eg, -"get_status") to the integer command ids. This allows the host and -firmware to use descriptive ASCII names while still using minimal -bandwidth. +response. This system allows both the host and firmware code to +seamlessly use descriptive human-readable names while still using +minimal bandwidth. The host queries the data dictionary when it first connects to 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"); ``` -The error message can be encoded and sent using a single VLQ. The host -uses the data dictionary to resolve the VLQ encoded static string id -to the associated message in the data dictionary. +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. Message flow ============