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

docs: Update Protocol.md to use enumerations for pins 

Now that pins use enumerations, update the set_digital_out command
examples.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>
This commit is contained in:
Kevin O'Connor 2019-07-09 14:17:28 -04:00
parent e7dd313a96
commit ea6f30bd99
1 changed files with 23 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs/Protocol.md
View File

@ -6,8 +6,8 @@ then processed at the receiving side. An example series of commands in
uncompressed human-readable format might look like: uncompressed human-readable format might look like:
``` ```
set_digital_out pin=86 value=1 set_digital_out pin=PA3 value=1
set_digital_out pin=85 value=1 set_digital_out pin=PA7 value=1
schedule_digital_out oid=8 clock=4000000 value=0 schedule_digital_out oid=8 clock=4000000 value=0
queue_step oid=7 interval=7458 count=10 add=331 queue_step oid=7 interval=7458 count=10 add=331
queue_step oid=7 interval=11717 count=4 add=1281 queue_step oid=7 interval=11717 count=4 add=1281
@ -44,26 +44,26 @@ The micro-controller software declares a "command" by using the
DECL_COMMAND() macro in the C code. For example: DECL_COMMAND() macro in the C code. For example:
``` ```
DECL_COMMAND(command_set_digital_out, "set_digital_out pin=%u value=%c"); DECL_COMMAND(command_update_digital_out, "update_digital_out oid=%c value=%c");
``` ```
The above declares a command named "set_digital_out". This allows the The above declares a command named "update_digital_out". This allows
host to "invoke" this command which would cause the the host to "invoke" this command which would cause the
command_set_digital_out() C function to be executed in the command_update_digital_out() C function to be executed in the
micro-controller. The above also indicates that the command takes two micro-controller. The above also indicates that the command takes two
integer parameters. When the command_set_digital_out() C code is integer parameters. When the command_update_digital_out() C code is
executed, it will be passed an array containing these two integers - executed, it will be passed an array containing these two integers -
the first corresponding to the 'pin' and the second corresponding to the first corresponding to the 'oid' and the second corresponding to
the 'value'. the 'value'.
In general, the parameters are described with printf() style syntax In general, the parameters are described with printf() style syntax
(eg, "%u"). The formatting directly corresponds to the human-readable (eg, "%u"). The formatting directly corresponds to the human-readable
view of commands (eg, "set_digital_out pin=86 value=1"). In the above view of commands (eg, "update_digital_out oid=7 value=1"). In the
example, "value=" is a parameter name and "%c" indicates the parameter above example, "value=" is a parameter name and "%c" indicates the
is an integer. Internally, the parameter name is only used as parameter is an integer. Internally, the parameter name is only used
documentation. In this example, the "%c" is also used as documentation as documentation. In this example, the "%c" is also used as
to indicate the expected integer is 1 byte in size (the declared documentation to indicate the expected integer is 1 byte in size (the
integer size does not impact the parsing or encoding). declared integer size does not impact the parsing or encoding).
The micro-controller build will collect all commands declared with The micro-controller build will collect all commands declared with
DECL_COMMAND(), determine their parameters, and arrange for them to be DECL_COMMAND(), determine their parameters, and arrange for them to be
@ -200,8 +200,8 @@ As an example, the following four commands might be placed in a single
message block: message block:
``` ```
set_digital_out pin=86 value=1 update_digital_out oid=6 value=1
set_digital_out pin=85 value=0 update_digital_out oid=5 value=0
get_config get_config
get_clock get_clock
``` ```
@ -209,19 +209,20 @@ get_clock
and encoded into the following eight VLQ integers: 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_clock> <id_update_digital_out><6><1><id_update_digital_out><5><0><id_get_config><id_get_clock>
``` ```
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
micro-controller must agree on the command ids and the number of micro-controller must agree on the command ids and the number of
parameters each command has. So, in the above example, both the host parameters each command has. So, in the above example, both the host
and micro-controller would know that "id_set_digital_out" is always and micro-controller would know that "id_update_digital_out" is always
followed by two parameters, and "id_get_config" and "id_get_clock" followed by two parameters, and "id_get_config" and "id_get_clock"
have zero parameters. The host and micro-controller share a "data have zero parameters. The host and micro-controller share a "data
dictionary" that maps the command descriptions (eg, "set_digital_out dictionary" that maps the command descriptions (eg,
pin=%u value=%c") to their integer command-ids. When processing the "update_digital_out oid=%c value=%c") to their integer
data, the parser will know to expect a specific number of VLQ encoded command-ids. When processing the data, the parser will know to expect
parameters following a given command id. a specific number of VLQ encoded parameters following a given command
id.
The message contents for blocks sent from micro-controller to host The message contents for blocks sent from micro-controller to host
follow the same format. The identifiers in these messages are follow the same format. The identifiers in these messages are