diff options
| -rw-r--r-- | protocol.md | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/protocol.md b/protocol.md new file mode 100644 index 0000000..0317d05 --- /dev/null +++ b/protocol.md @@ -0,0 +1,163 @@ +# protocol specs + +under construction! + +## client/robot + +the included wixel is used for bidirectional wireless serial data transfer. it +has built-in error correction and other features that make sure data gets to +the robot losslessly, so data loss is not accounted for. + +### important constants + +|property|value|unit| +|-|-|-| +|baud rate|9600|bit s⁻¹| +|max byte timeout|5|ms| +|byte order|big-endian|-| + +### commands + +each command consists of an opcode, and then a payload. each opcode defines +logic to handle payload length, so certain commands might expect a fixed-length +payload, a variable-length payload, or none at all. + +opcodes are picked sequentially, but bit 0 is reserved to indicate a transfer +from robot to client. this means that the opcode for a sensor data request +would be `0x14`, but the response opcode would be `0x15`. a c header is +provided that contains consts of these opcodes for code readability. + +|code|name|implemented|directions|full name| +|--:|---|:-:|:-:|---| +|`0x00`|[BOMD](#bomd)|no|`r <=> c`|<u>b</u>ack<u>o</u>rder <u>m</u>o<u>d</u>ify +|`0x00`|[CORD](#cord)|no|`r <=> c`|<u>co</u>o<u>rd</u>inate +|`0x00`|[EXFL](#exfl)|no|`r <-- c`|<u>ex</u>ecution <u>fl</u>ow +|`0x00`|[SRES](#sres)|no|`r <-- c`|<u>s</u>oft <u>res</u>et +|`0x00`|[EXPT](#expt)|no|`r --> c`|<u>ex</u>ce<u>pt</u>ion +|`0x00`|[SPED](#sped)|no|`r <-- c`|<u>spe</u>e<u>d</u> +|`0x00`|[DIRC](#dirc)|no|`r <-- c`|<u>dir</u>ect <u>c</u>ontrol +|`0x00`|[DISP](#disp)|no|`r <-- c`|<u>disp</u>lay control +|`0x00`|[SENS](#sens)|no|`r <=> c`|<u>sens</u>or data +|`0x00`|[MAPS](#maps)|no|`r <-- c`|<u>map</u> <u>s</u>end +|`0x00`|[PING](#ping)|no|`r <=> c`|<u>ping</u> +|`0x00`|[PLAY](#play)|no|`r <-- c`|<u>play</u> midi +|`0x00`|[CLED](#cled)|no|`r <-- c`|<u>c</u>ontrol <u>led</u>s + +#### BOMD + +##### backorder append + +- length: 2 bytes +- client to robot + +|type|description| +|-:|-| +|`uint8_t`|opcode (`0x00 + 0`)| +|`uint8_t`|action| + +_action_ is a byte containing `0bXXXXXXYY` where X+1 is the amount of times +action Y gets repeated. Y can be: +- 0: move 1 tile forward +- 1: move 1 tile backward +- 2: turn right 90° +- 3: turn left 90° + +examples: +- move forward 4 tiles: `0b00001100` (`0x10`) +- turn 180°: `0b00000110` (`0x06`) or `0b00000111` (`0x07`) + +##### backorder index + +- length: 9 bytes +- robot to client + +|type|description| +|-:|-| +|`uint8_t`|opcode (`0x00 + 1`)| +|`uint32_t`|backorder buffer length| +|`uint32_t`|backorder buffer index| + +#### CORD + +##### set position + +- length: 6 bytes +- client to robot + +|type|description| +|-:|-| +|`uint8_t`|opcode (`0x00 + 0`)| +|`uint32_t`|position| +|`uint8_t`|orientation| + +_position_ = y * width + x +_orientation_: +- 0: west +- 1: north +- 2: east +- 3: south + +##### get position + +- length: 6 bytes +- robot to client + +|type|description| +|-:|-| +|`uint8_t`|opcode (`0x00 + 1`)| +|`uint32_t`|position| +|`uint8_t`|orientation| + +_position_ = y * width + x +_orientation_: +- 0: west +- 1: north +- 2: east +- 3: south + +#### EXFL + +##### set execution flow + +- length: 2 bytes +- client to robot + +|type|description| +|-:|-| +|`uint8_t`|opcode (`0x00 + 0`)| +|`uint8_t`|action| + +_action_ is: +- 0: suspend all operation +- 1: resume operation + +#### SRES + +##### soft reset + +- length: 1 byte +- client to robot + +|type|description| +|-:|-| +|`uint8_t`|opcode (`0x00 + 0`)| + +#### EXPT +#### SPED +#### DIRC +#### DISP +DCLR display clear +DPOS display cursor position +DWSR display write string +DWBM display write bitmap +#### SENS +#### MAPS +#### PING +#### PLAY +#### CLED + + +## client/websocket + +TBD + |