feat(arduino): add ArduinoModule with full arduino sim (and real arduino) support

[jeff-hykin]

EXPERIMENTAL / TOY / FUN

Problem

We don't have arduino support :(

Solution

Arduino support. Just like a native module, there's an Arduino module, but you give it an .ino file instead of a C++ file.

• Includes: Full Arduino simulator (all via nix of course)

• How does it work?

  • put the entire arduino toolchain in a nix flake
  • 1. we build the .ino file for an Arduino based on python config values (which one to target)
  • 2. we try to push the payload to the Arduino (auto scan ports and use python config)
  • 3. we (hidden) auto code-gen a C++ module (very very very similar to a native module)
  • 4. we start the C++ native module (as normal)
  • 5. messages passing
    • So ... LCM has C support ... but it uses malloc, which the arduino doesn't (really) support
    • solution: we make a crappier version of most LCM messages, but they are fixed size and dont use malloc for encode/decode
    • So: an LCM message arrives at the C++ module (normal native module stuff)
    • it encodes the message into this crappier LCM version (it strips the 64 bit hash, which is sketchy I know but this is experimental. We should add a checksum later.)
    • that data is sent over serial to the arduino
    • the arduino code uses a dimos-provided header
      • the header patches the serial.print (because we overloaded the serial line for data and printing)
    • the message arrives on the arduino program through serial, it gets parsed, float64's are read as float32 (because Arduino doesn't support float64)
    • the Arduino does whatever it wants
    • the Arduino lcm_crappy encodes a message and publishes it on serial
    • the C++ reads the serial message, creates the 64bit header for the message, then publishes that as-is to the rest of the dimos system
• Tested on real Arduino hardware

%%{init: {'theme':'base', 'themeVariables': {'fontSize': '40px', 'fontFamily': 'Inter, sans-serif'}}}%%
flowchart LR
    subgraph Dimos["🖥️ dimos"]
        direction TB
        SrcModule["Some dimos module"]
        DstModule["Some other dimos module"]
        Terminal["📟 Terminalprintouts"]
    end

    subgraph Host["C++ Native Module"]
        direction TB
        Encode["Strip 64-bit LCM checksum"]
        Decode["Recreate 64-bit LCM checksum"]
        PrintHandler["Print handlerforward to terminal"]
    end

    subgraph Arduino["Arduino"]
        direction TB
        Parse["read serial, lcm_crappy decode (fixed size only)"]
        Logic["Arduino does its thing"]
        Emit["lcm_crappy encode and publish"]
        Printf["Serial.printpatched by dimos header"]
        Parse --> Logic --> Emit
        Logic -.-> Printf
    end

    SrcModule -->|"LCM message"| Encode
    Encode -->|"serial (data)"| Parse
    Emit -->|"serial (data)"| Decode
    Decode -->|"LCM message"| DstModule

    Printf -->|"serial (printout)"| PrintHandler
    PrintHandler -->|"stdout"| Terminal

    classDef dimos fill:#ede9fe,stroke:#6d28d9,stroke-width:2px,color:#1e1b4b
    classDef host fill:#d1fae5,stroke:#047857,stroke-width:2px,color:#064e3b
    classDef arduino fill:#1e3a8a,stroke:#1e40af,stroke-width:2px,color:#ffffff
    classDef terminal fill:#fef3c7,stroke:#b45309,stroke-width:2px,color:#78350f

    class Dimos,SrcModule,DstModule dimos
    class Terminal terminal
    class Host,Encode,Decode,PrintHandler host
    class Arduino,Parse,Logic,Emit,Printf arduino

Loading

Breaking Changes

Caveats

• A lot
• We should test if float64 round trip doesn't mangle the data (is 64->32 is handled as a special case, but need to make sure its handled correctly)
• There isn't a way to get config data from the python side to arduino
• all the normal caveats of native modules (rpc calls and whatnot)

How to Test

# On real hardware
uv run examples/arduino_led_echo/demo_led_blink.py

# Unit tests
uv run pytest dimos/core/tests/test_arduino_module.py -v

# Wire-compat C++ tests (requires nix)
cd dimos/hardware/arduino/test && nix develop --command bash -c "cmake -B build && cmake --build build && ./build/test_wire_compat"

# Virtual end-to-end (requires nix for QEMU + avr toolchain)
uv run pytest dimos/hardware/arduino/examples/arduino_twist_echo/test_e2e_virtual.py -v

# Or run the virtual blueprint directly
dimos run arduino-twist-echo-virtual

Contributor License Agreement

• I have read and approved the CLA.

[greptile-apps]

Greptile Summary

This PR adds ArduinoModule, a new NativeModule subclass that auto-generates a typed C header, compiles and flashes an Arduino sketch via arduino-cli, and runs a generic C++ serial↔LCM bridge. It also adds a QEMU-based virtual mode for CI use, a Nix flake for reproducible toolchain resolution, and two end-to-end examples. The implementation is well-structured with solid test coverage, careful QEMU lifecycle management, and a shared DSP framing protocol between the Arduino and host sides.

Confidence Score: 5/5

Safe to merge; all findings are P2 style/polish suggestions with no impact on correctness or runtime behaviour.

The implementation is thorough — shared DSP parser, file-locked bridge builds, proper QEMU teardown, typed-channel validation, AVR SRAM payload guards, and a three-way registry sync test. No P0/P1 bugs were found. The four P2 items (fcntl import guard, silent unconnected-stream skip, substring core-check, stale doc comment) and the committed generated file are all non-blocking improvements.

dimos/core/arduino_module.py (fcntl import, unconnected-stream warning, core substring check), dimos/hardware/arduino/common/dsp_protocol.h (stale doc), examples/arduino_led_echo/sketch/dimos_arduino.h (generated file in repo)

Important Files Changed

Filename	Overview
dimos/core/arduino_module.py	Core ArduinoModule: header generation, sketch compilation, QEMU lifecycle, and bridge launch; well-implemented but import fcntl is unconditional and will raise ImportError on Windows, and unconnected streams are silently skipped in start() without a diagnostic.
dimos/core/native_module.py	Adds _auto_emit_topic_cli_args class variable to let ArduinoModule opt out of the generic CLI topic arg loop; clean and minimal change.
dimos/hardware/arduino/cpp/main.cpp	C++ bridge: robust serial reconnect loop, thread-safe LCM↔serial relay, proper DSP frame construction and CRC, clean signal handling; well-structured.
dimos/hardware/arduino/common/dsp_protocol.h	Shared DSP framing protocol (Arduino+host): CRC-8/MAXIM table, unified state-machine parser, USART abstraction; header's "This file provides" block lists non-existent dimos_poll() and dimos_on_receive() APIs (stale from earlier design).
dimos/core/tests/test_arduino_module.py	Good unit test coverage: topic enum, header generation, port detection, QEMU cleanup, and registry sync; uses bypass constructors appropriately to avoid spinning up RPC machinery.
examples/arduino_led_echo/sketch/dimos_arduino.h	Generated file committed to the repository; the .gitignore only covers dimos/hardware/arduino/examples/*/sketch/dimos_arduino.h, not this path at the repo root, risking drift if streams change.
dimos/hardware/arduino/examples/arduino_twist_echo/test_e2e_virtual.py	End-to-end virtual test that exercises the full pipeline (nix build → compile → QEMU → bridge → LCM round-trip); properly gated on nix availability and marked slow+tool.
dimos/robot/all_blueprints.py	Auto-generated registry updated to include arduino-twist-echo-virtual blueprint and twist-echo module; straightforward addition.

Sequence Diagram

sequenceDiagram
    participant User as User Code
    participant AM as ArduinoModule.build()
    participant CLI as arduino-cli
    participant Nix as nix build
    participant AM2 as ArduinoModule.start()
    participant QEMU as qemu-system-avr
    participant Bridge as arduino_bridge (C++)
    participant LCM as LCM Bus

    User->>AM: build()
    AM->>AM: _generate_header() → dimos_arduino.h
    AM->>CLI: compile sketch (--build-path)
    CLI-->>AM: ELF binary
    AM->>Nix: nix build .#arduino_bridge (file-locked)
    Nix-->>AM: result/bin/arduino_bridge
    AM->>CLI: upload (physical) or skip (virtual)

    User->>AM2: start()
    AM2->>AM2: _resolve_topics() (validate # suffix)
    AM2->>AM2: _build_topic_enum() (alphabetical IDs)

    alt virtual=True
        AM2->>QEMU: Popen(qemu-system-avr -machine uno -bios sketch.elf -serial pty)
        QEMU-->>AM2: char device redirected to /dev/pts/N
        AM2->>Bridge: Popen(arduino_bridge --serial_port /dev/pts/N --topic_out 1 ch#type ...)
    else virtual=False
        AM2->>Bridge: Popen(arduino_bridge --serial_port /dev/ttyACM0 ...)
    end

    Bridge->>LCM: subscribe(ch#type) for each In stream
    LCM-->>Bridge: LCM message received
    Bridge->>QEMU: DSP frame (START|TOPIC|LEN|PAYLOAD|CRC8)
    QEMU->>Bridge: DSP frame (echo/sensor data)
    Bridge->>LCM: publish(ch#type, fingerprint+payload)

Loading

_{Reviews (1): Last reviewed commit: "add arduino example (tested on hardware!..." | Re-trigger Greptile}

[greptile-apps]

Unconditional fcntl import breaks Windows

fcntl is a POSIX-only module. Any Windows machine that imports this file (directly or via a transitive import) will get ModuleNotFoundError: No module named 'fcntl', even if it never creates an ArduinoModule. Since arduino_module.py may end up on a broad import path, guarding the import (or deferring it to the method body) prevents surprising failures on non-target platforms.

Or move the import fcntl inside _build_bridge so the error is deferred to the call site with a meaningful context.

[greptile-apps]

Silently skipped unconnected streams produce confusing bridge errors

When a stream has no LCM transport (not wired in the blueprint), it is absent from topics and silently omitted from the bridge's --topic_in/--topic_out args. The Arduino sketch will still send DSP frames on that topic ID (since the generated dimos_arduino.h always includes all topic IDs), so the bridge will log "Unknown outbound topic: N" at runtime — a confusing error with no explanation at build time.

A logger.warning for streams in topic_enum but not in topics would make the mismatch obvious during start():

for stream_name, topic_id in topic_enum.items():
    if stream_name not in topics:
        logger.warning(
            "Stream has no LCM transport and will not be relayed by the bridge",
            stream=stream_name,
            topic_id=topic_id,
        )
        continue

[greptile-apps]

core_id in stdout substring check can produce false positives

core_id in list_result.stdout matches the string anywhere in the output, including as a prefix of a different core name (e.g., "arduino:avr" would match if "arduino:avr-plus" is installed). This could cause the install step to be skipped when the required core is absent, leading to a confusing compile failure later.

A line-aware check is more precise:

Suggested change

	)
	if list_result.returncode == 0 and core_id in list_result.stdout:
	if list_result.returncode == 0 and any(
	line.split()[0] == core_id
	for line in list_result.stdout.splitlines()
	if line.strip()
	):

[greptile-apps]

Stale API listing in header doc comment

The "This file provides" block lists dimos_poll() and dimos_on_receive(topic, handler) which do not exist in the file. The actual public API is dimos_check_message(), dimos_message_topic(), dimos_message_data(), and dimos_message_len().

Suggested change

	*
	* This file provides:
	* - CRC-8/MAXIM table + computation
	* - dimos_init(baud)
	* - dimos_send(topic, data, len)
	* - dimos_poll()
	* This file provides:
	* - CRC-8/MAXIM table + computation
	* - dimos_init(baud)
	* - dimos_send(topic, data, len)
	* - dimos_check_message() / dimos_message_topic() / dimos_message_data() / dimos_message_len()
	* - DimosSerial class (Serial.print shim → debug frames)

[greptile-apps]

Generated file committed outside the gitignore scope

The dimos/hardware/arduino/.gitignore entry covers examples/*/sketch/dimos_arduino.h (relative to dimos/hardware/arduino/), but this file lives at examples/arduino_led_echo/sketch/dimos_arduino.h at the repo root — a different path not covered by that rule. If the LedEcho module's streams or config change, this committed file will drift from what ArduinoModule._generate_header() would actually produce.

Consider adding examples/arduino_led_echo/sketch/dimos_arduino.h to the root .gitignore and removing the file, or adding a comment explaining why the committed copy is intentional for the hardware-tested demo.

[leshy]

pasting comment from Discord here:

Will chat on this in person first, I think it's really cool to auto-build and deploy onto a microcontroller when your blueprint runs, we can even have a small version control protocol to not write firmware every time.

I'd start with just establishing good comms, then do autobuilds etc separately.

I see a bunch of messages are redefined here by hand due to malloc, but I think we should just write a small arduino compatible encoder/decoder on our dimos-lcm cpp side and not merge 6000 lines of mirrored messages into main repo. LCM proto also gives you pubsub out of the box (topic encoding, packets etc, super helpful for serial) we can disable hashing or change the algo if this is an issue - actually pretty important for serial comms

on arduino side ideally we have the exact same cpp API, why can't I do something like (I'm completely vibing)

dimos = dimos_start(serial_port)
# msg parsing needs to be tied to a hardware interrupt not a stupid loop
# due to high CPU constraints - partial decoding of a topic name first and not decoding the rest if no active sub
dimos.subscribe('/twist' ...)

[jeff-hykin]

this shouldnt be here

[jeff-hykin]

should be named different

[jeff-hykin]

shouldnt be here