Wire protocol
=============

The Python side speaks a compact integer-command protocol to the
PARROTard Arduino firmware.  All commands are ASCII-encoded integers;
some commands are followed by a second integer or float parameter.

Magic prefix
------------

Most command IDs follow the pattern ``1337XYZ``, where ``1337`` is a
magic prefix and ``XYZ`` selects the subsystem:

================ =================== =================================
Range            Subsystem            Examples
================ =================== =================================
``1337``         comm test            ``1337`` ↔ ``50 1337``
``1337000X``     write-out / clock    ``13370001``, ``13379999``
``1337100X``     LED control          ``13371000``, ``13371200``
``1337200X``     experiment flow      ``13372000``, ``13372001``
``1337222X``     cameras              ``13372222``, ``13372223``
``1337333X``     bottom strip         ``13373333``, ``13373334``
================ =================== =================================

Comm-test handshake
-------------------

* Python sends the integer ``1337``.
* Arduino replies with the line ``50 1337``.
* :meth:`cuewire.ArduinoSerial.comm_test` returns ``True`` on success
  and raises :class:`cuewire.CommTestError` on failure.

Parameter-readout frame
-----------------------

In response to ``EXPgetParameter_return`` (``13372999``) the firmware
emits a single ``>>...<< `` frame with seven comma-separated fields::

   >>pre_exp,exp,led_pattern,led_mode,led_free_period,led_sin_period,led_hall_factor<<

This is parsed into a :class:`cuewire.ExpParameters` by
:func:`cuewire.huepfburg.parse_exp_parameters`.

Continuous serial output
------------------------

When write-out is enabled (``13370001``) the firmware emits one line
per 10-ms tick with the columns documented in the experiment-script
header.  Toggle write-out off (``13370000``) before sending a
command-with-follow pair, to avoid races between the two streams.