PyBoardX

PyBoardX is a C++ compiler core and Python-facing framework for writing simple Python-like IoT programs and lowering them to board-specific code.

from pyboardx import LED
import time

while True:
    led = LED(2)
    led.on()
    time.sleep(1)
    led.off()
    time.sleep(1)

MVP targets:

• arduino_uno
• esp32

Designed targets:

• Raspberry Pi Pico
• Raspberry Pi Linux
• STM32

Build

cmake -S . -B build -DPYBOARDX_BUILD_PYTHON=OFF
cmake --build build
ctest --test-dir build

Enable PYBOARDX_BUILD_PYTHON=ON when pybind11 is installed.

For local CLI development, build the native extension and install the Python package in editable mode using a virtual environment created with the same Python interpreter CMake selected:

cmake -S . -B build-py
cmake --build build-py
/opt/homebrew/Frameworks/Python.framework/Versions/3.14/bin/python3.14 -m venv .venv
.venv/bin/python -m pip install -e .
source .venv/bin/activate

After activation, the pyboardx command is available on PATH for that shell.

CLI

pyboardx build examples/blink.py --target esp32
pyboardx flash --target esp32 --port /dev/ttyUSB0 --fqbn esp32:esp32:esp32
pyboardx run examples/blink.py --target arduino_uno --port /dev/ttyACM0 --fqbn arduino:avr:uno

Development Roadmap

PyBoardX is currently an MVP compiler. The next development work should grow it in small, testable layers.

Implemented

• C++20 compiler core with CMake.
• Python package and CLI entry point.
• pybind11 native compiler bindings.
• Diagnostics with line and column reporting.
• IR for components, method calls, delay, and forever loops.
• Parser support for:
  • LED(pin).on()
  • LED(pin).off()
  • led = LED(pin)
  • led.on()
  • Button(pin).is_pressed()
  • while True:
  • time.sleep(seconds)
• Arduino-compatible generators for:
  • arduino_uno
  • esp32
• C++ unit tests for parser, diagnostics, and generated code.

Next Features

• Add a real lexer and AST before IR lowering.
• Support Python comments, inline comments, and clearer syntax errors.
• Add scoped symbol tables for loops and future functions.
• Add setup() and loop() Python functions as an alternative to top-level code.
• Add more components:
  • PWM
  • Servo
  • Buzzer
  • AnalogInput
  • DigitalOutput
  • I2CDevice
  • Serial
• Add more methods:
  • LED(pin).toggle()
  • PWM(pin).write(value)
  • AnalogInput(pin).read()
  • Serial.println(value)
• Add package-aware integrations for common Python libraries:
  • requests for HTTP and REST APIs.
  • Firebase clients for realtime database, Firestore, authentication, and cloud messaging workflows.
  • MQTT clients for IoT messaging.
  • JSON helpers for API payloads.
• Generate board project files automatically:
  • Arduino CLI sketch folders
  • ESP32 board profiles
  • per-target build metadata
• Improve pyboardx flash:
  • auto-detect serial ports
  • validate FQBN values
  • show friendly upload errors
• Add Python tests for the CLI and package API.
• Add CI for macOS, Linux, and Windows.

Target Roadmap

• Python Package Support:
  • ESP32 and Arduino-class targets should compile supported package calls into native C++ libraries where possible, such as WiFi, HTTP client, Firebase, MQTT, and JSON libraries.
  • Raspberry Pi Linux can run real Python packages directly when generating Python output.
  • Unsupported packages should produce clear compiler diagnostics instead of failing during firmware build.
• Raspberry Pi Pico:
  • generate Pico SDK or Arduino-Pico C++
  • support GPIO, PWM, and sleep
• Raspberry Pi Linux:
  • generate Python or C++ using Linux GPIO backends
  • support dry-run execution on development machines
• STM32:
  • generate Arduino STM32 or STM32Cube-compatible code
  • add pin capability validation

Compiler Quality Goals

• Keep the parser independent from target code generation.
• Keep IR target-neutral and easy to inspect in tests.
• Add validation passes before generation.
• Add target capability checks, such as unsupported pins or missing PWM support.
• Emit deterministic generated code for stable tests and reviews.
• Keep every new language feature covered by both parser and generator tests.

Architecture

Python API
  -> Python source frontend
  -> C++ compiler core
  -> IR
  -> Target generators
  -> Arduino/ESP32 code
  -> Build and flash orchestration

The compiler core is intentionally independent from Python and board toolchains. That keeps parsing, IR validation, and code generation testable in plain C++.