A Python package for talking to Lizard

[falkoschindler]

Every host that talks to Lizard reimplements the same things: the @xx line checksum, writing a startup script with !-, !+ and !., reading the startup checksum, waiting for an answer to a command, flashing. Soon the telemetry decoder from #343 joins them. Some of this lives as scripts in this repo, some in RoSys, and other users would have to copy it again.

The idea is a Python package, published on PyPI and maintained here, that holds everything Lizard-specific on the host side. RoSys and other hosts would import it instead of carrying their own copy.

What could go in

From this repo:

• monitor.py, the interactive console, including the frame display from Decoder telemetry.py and frames in monitor.py #343.
• configure.py, which writes a startup script, also to a serial bus peer with --serial-bus.
• espresso.py, flashing and resetting over GPIO, locally or via SSH.
• otb_update.py, firmware updates for serial bus peers.
• telemetry.py, the decoder from Decoder telemetry.py and frames in monitor.py #343.

From RoSys (rosys/hardware/robot_brain.py and lizard_firmware.py), the parts that are about Lizard rather than about robots:

• augment() and check() for the line checksum.
• Writing and verifying the startup script: !-, !+ line by line, compare core.startup_checksum(), !., restart, verify again.
• send_and_await(), sending a command and waiting for a line with a given prefix.
• Parsing core lines and deriving the clock offset from core.millis.
• Reading and parsing core.version().

The scripts would become console entry points of the package, so pip install gives monitor, configure and friends without cloning the repo.

Open questions

• Name. lizard is taken on PyPI, and also as an import name by a popular code complexity tool, so the import name matters as much as the distribution name. Free as of 2026-10-22: lizard-host, lizard-tools, lizard-serial, lizard-link, lizard-cli, pylizard. Taken: lizard, lizard-sdk, lizard-connector.
• Firmware versions. A host is installed once, but robots run different firmware versions. The package has to handle older firmware, or at least recognize it via core.version() and refuse clearly. Which range of versions does it support, and how does it say so?
• Release cycle. Same version numbers as the firmware, or its own? The telemetry format carries its own version in the layout lines, which helps.
• Async or not. RoSys is async, the scripts are synchronous. Is there one core with two thin front ends, or does the package pick one?
• Scope towards RoSys. Where is the line between "Lizard host library" and "RoSys hardware layer"? A rule of thumb could be: everything that needs knowledge of Lizard's line protocol goes here, everything that knows about robots, wheels or UIs stays in RoSys.
• Bundling startup scripts. A host could hand the package one script per microcontroller and let it write each to the right device, the core directly and bus peers via the coordinator. That would make multi-device setups easier to configure; see also Port expanders as serial bus peers #348.

Nothing here is urgent. It becomes more pressing once #343 exists and RoSys needs the decoder. ※