diff options
Diffstat (limited to 'content/posts/serial-protocols')
| -rw-r--r-- | content/posts/serial-protocols/index.rst | 48 |
1 files changed, 24 insertions, 24 deletions
diff --git a/content/posts/serial-protocols/index.rst b/content/posts/serial-protocols/index.rst index 5797947..2f9bb2d 100644 --- a/content/posts/serial-protocols/index.rst +++ b/content/posts/serial-protocols/index.rst @@ -10,13 +10,13 @@ summarize some points on how to design a serial protocol that is simple to imple conditions. If you have done low-level microcontroller firmware you will regularly have had to stuff some data up a serial port to -another microcontroller or to a computer. In the age of USB, a serial port is still the simplest and quickest way to get -communication to a control computer up and running. Integrating a ten thousand-line USB stack into your firmware and -writing the necessary low-level drivers on the host side might take days. Poking a few registers to set up your UART to -talk to an external hardware USB to serial converter is a matter of minutes. +another microcontroller or to a computer. In the age of USB, an old-school serial port is still the simplest and +quickest way to get communication to a control computer up and running. Integrating a ten thousand-line USB stack into +your firmware and writing the necessary low-level drivers on the host side might take days. Poking a few registers to +set up your UART to talk to an external hardware USB to serial converter is a matter of minutes. This simplicity is treacherous, though. Oftentimes, you start writing your serial protocol as needs arise. Things might -start harmless with something like ``SET_LED ON\n``, but unless you proceed it is easy to end up in a hot mess of command +start harmless with something like ``SET_LED ON\n``, but as the code grows it is easy to end up in a hot mess of command modes, protocol states that breaks under stress. The ways in which serial protocols break are manifold. The simplest one is that at some point a character is mangled, leading to both ends of the conversation ending up in misaligned protocol states. With a fragile protocol, you might end up in a state that is hard to recover from. In extreme cases, this leads @@ -24,7 +24,7 @@ to code such as `this gem`_ performing some sort of arcane ritual to get back to someone did not do their homework. Below we'll embark on a journey through the lands of protocol design, exploring the facets of this deceptively simple problem. -.. _`this gem`: https://github.com/juhasch/pyBusPirateLite/blob/master/pyBusPirateLite/BBIO_base.py#L68 +.. _`this gem`: https://github.com/juhasch/pyBusPirateLite/blob/dece35f6e421d4f6a007d1db98d148e2f2126ebb/pyBusPirateLite/base.py#L113 Text-based serial protocols =========================== @@ -45,10 +45,10 @@ Low information density ~~~~~~~~~~~~~~~~~~~~~~~ Generally, you won't be able to stuff much more than four or five bit of information down a serial port using a -human-readable protocol. In many cases you will get much less. If you have 10 commands that are only issued a couple -times a second nobody cares that you spend maybe ten bytes per command on nice, verbose strings such as ``SET LED``. But -if you're trying to squeeze a half-kilobyte framebuffer down the line you might start to notice the difference between -hex and base-64 encoding, and a binary protocol might really be more up to the job. +single byte of a human-readable protocol. In many cases you will get much less. If you have 10 commands that are only +issued a couple times a second nobody cares that you spend maybe ten bytes per command on nice, verbose strings such as +``SET LED``. But if you're trying to squeeze a half-kilobyte framebuffer down the line you might start to notice the +difference between hex and base-64 encoding, and a binary protocol might really be more up to the job. Complex parsing code ~~~~~~~~~~~~~~~~~~~~ @@ -60,7 +60,7 @@ an entirely different beast. On a small microcontroller, printf_ alone will eat microcontrollers, you just won't get a regex library even though it would make parsing textual commands *so much simpler*. Lacking these resources, you might end up hand-knitting a lot of low-level C code to do something seemingly simple such as parsing ``set_channel (13, 1.1333)\n``. These issues have to be taken into account in the protocol design -from the beginning. If you don't really need matching parentheses, don't use them. +from the beginning. For example, you don't really need matching parentheses, don't use them. Fragile protocol state ~~~~~~~~~~~~~~~~~~~~~~ @@ -80,7 +80,7 @@ Timeouts don't work You might try to solve the problem of your protocol state machine tangling up with a timeout. "If I don't get a valid command for more than 200ms I go back to default state." But consider the above example. Say, your control computer sends a ``SET_DISPLAY`` command every 100ms. If in one of them the state machine tangles up, the parser hangs since the -timeout is never hit, a new line of text arriving every 100ms. +timeout is never hit, because a new line of text is arriving every 100ms. Framing is hard ~~~~~~~~~~~~~~~ @@ -96,9 +96,9 @@ Solutions Keep the state machine simple ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Always use a single line of text to represent a single command. Don't do protocol states or modes where you can toggle -between different interpretations for a line. If you have to send human-readable text as part of a command (such as -``SET_DISPLAY``) escape it so it doesn't contain any newlines. +In a text-based protocol, always use a single line of text to represent a single command. Don't do protocol states or +modes where you can toggle between different interpretations for a line. If you have to send human-readable text as part +of a command (such as ``SET_DISPLAY``), escape it so it doesn't contain any newlines. This way, you keep your protocol state machine simple. If at any time your serial trips and flips a bit or looses a byte your protocol will recover on the next newline character, returning to its base state. @@ -229,19 +229,19 @@ Conclusion Here's your five-step guide to serial bliss: 1. Unless you have super-special requirements, always use the slowest you can get away with from 9600Bd, 115200Bd or - 1MBd. 8N1 framing if you're talking to anything but another microcontroller on the same board. These settings are - the most common and cover any use case. You'll inevitably have to guess these at some point in the future. + 1MBd. 8N1 framing if you're talking to anything but another microcontroller on the same board. Using common values + like these makes it easier when you'll inevitably have to guess these at some point in the future ;) 2. If you're doing something simple and speed is not a particular concern, use a human-readable text-based protocol. Use - one command/reply per line, begin each line with some sort of command word and format numbers in hexadecimal. You get - bonus points if the device replies to unknown commands with a human-readable status message and prints a brief - protocol overview on boot. + one command/reply per line, begin each line with some sort of command word and format numbers in hexadecimal. Bonus + points for the device replying to unknown commands with a human-readable status message and printing a brief protocol + overview on boot. 3. If you're doing something even slightly nontrivial or need moderate throughput (>1k commands per second or >20 byte of - data per command) use a COBS-based protocol. If you don't have a better idea, go for an ``[target MAC][command - ID][command arguments]`` packet format for multidrop busses. For single-drop you may decide to drop the MAC address. + data per command) use a COBS-based protocol. A good starting point is a ``[target MAC][command ID][command + arguments]`` packet format for multidrop busses. For single-drop you may decide to drop the MAC address. 4. Always include some sort of "status" command that prints life stats such as VCC, temperature, serial framing errors - and uptime. You'll need some sort of ping command anyway and that one might as well do something useful. + and uptime. You'll need some sort of ping command anyway and that command might as well do something useful. 5. If at all possible, keep your protocol context-free across packets/lines. That is, a certain command should always be - self-contained, and no command should change the meaning of the next packet or line that is sent. This is really + self-contained, and no command should change the meaning of the next packet/line/command that is sent. This is really important to allow for self-synchronization. If you really need to break up something into multiple commands, say you want to set a large framebuffer in pieces, do it in a idempotent_ way: Instead of sending something like ``FRAMEBUFFER INCOMING:\n[byte 0-16]\n[byte 17-32]\n[...]\nEND OF FRAME`` rather send ``FRAMEBUFFER DATA FOR OFFSET 0: [byte |