Reduino

Write friendly Python. Get Arduino-ready C++. Upload Easily to MCUs.

Overview

Reduino lets you write high-level Python that compiles into clean Arduino C++, then optionally uploads it to your board via PlatformIO.

Quick start

pip install Reduino
pip install platformio  # required for automatic uploads

Note

PlatformIO is only required for automatic build & upload. You can still transpile without it.

The `target()` function (Required)

Place target() at the very top of your script, immediately after imports. This is the entry point that tells Reduino to parse your entire file, transpile it to Arduino C++, and (optionally) upload it.

Parameter	Type	Default	Description
`port`	`str`	—	Serial port, e.g. `"COM3"` or `"/dev/ttyACM0"`.
`upload`	`bool`	`True`	If `True`, compile & upload via PlatformIO. If `False`, only transpile.
`platform`	`str`	`"atmelavr"`	PlatformIO platform ID. Reduino currently supports `atmelavr` and `atmelmegaavr`.
`board`	`str`	`"uno"`	PlatformIO board ID. Must be compatible with `platform`.

Returns: str of the generated Arduino C++ source.

Minimal example (top-of-file target)

from Reduino import target
target("COM3")  # upload=True by default

# Your Reduino code below...

Example: Reduino structure explained

Reduino automatically splits your Python code into Arduino sections.

from Reduino import target
target("COM3")

from Reduino.Actuators import Led
led = Led(13)

while True:
    led.toggle()          # repeated code -> goes into void loop()

Generated Arduino structure (conceptually):

void setup() {
  pinMode(13, OUTPUT);
}

void loop() {
  digitalWrite(13, !digitalRead(13));
  delay(500);
}

Everything before while True: (declarations, prints, sensor setup, etc.) is placed inside setup(), and everything inside the while True loop is placed in loop().

Transpile only (no upload)

from Reduino import target
cpp = target("COM3", upload=False)
print(cpp)

# Your Reduino code below...

Targeting different platforms & boards

Reduino validates that the requested PlatformIO platform/board pair is supported. At the moment two PlatformIO platforms are available:

atmelavr – classic AVR-based boards (Uno, Nano, Leonardo, etc.).
atmelmegaavr – newer megaAVR devices (Nano Every, Uno WiFi Rev2, Curiosity Nano kits, ...).

Every board listed in the PlatformIO board registry for all platforms can be targeted. If you choose an unsupported board, or one that does not belong to the selected platform, target() raises a ValueError with a helpful message.

from Reduino import target

# Build for an Arduino Nano Every without uploading automatically.
target(
    "COM9",
    upload=False,
    platform="atmelmegaavr",
    board="nano_every",
)

# Build for a classic Arduino Uno and upload immediately.
target("/dev/ttyUSB0", platform="atmelavr", board="uno")

Important

target() reads the whole file text and generates code for everything below it. If upload=True, it also builds and flashes using a temporary PlatformIO project.

API reference

Actuators

LED

Method	Description
`Led(pin=13)`	Bind an LED to a digital/PWM pin.
`on()` / `off()`	Turn fully on/off.
`toggle()`	Flip state.
`get_state()`	`True` if on.
`get_brightness()` / `set_brightness(v)`	PWM 0–255.
`blink(duration_ms, times=1)`	Blink helper.
`fade_in(step=5, delay_ms=10)` / `fade_out(step=5, delay_ms=10)`	Smooth ramp.
`flash_pattern(pattern, delay_ms=200)`	Run pattern of 0 & 1s eg: `[1,0,0,1,1,1]`.

Example

from Reduino import target
target("COM3")

from Reduino.Actuators import Led
from Reduino.Utils import sleep

led = Led(9)
led.set_brightness(128)
led.blink(200, times=3)
sleep(500)
led.off()

RGB LED

Method	Description
`RGBLed(r_pin, g_pin, b_pin)`	Bind RGB to three PWM pins.
`set_color(r,g,b)`	Set color (0–255 each).
`on(r=255,g=255,b=255)` / `off()`	White / off.
`fade(r,g,b,duration_ms=1000,steps=50)`	Transition to target color.
`blink(r,g,b,times=1,delay_ms=200)`	Blink with color.

Example

from Reduino import target
target("COM3")

from Reduino.Actuators import RGBLed
from Reduino.Utils import sleep

rgb = RGBLed(9, 10, 11)
rgb.set_color(0, 128, 255)
rgb.fade(255, 0, 0, duration_ms=1500)
sleep(300)
rgb.off()

Buzzer

Method	Description
`Buzzer(pin=8, default_frequency=440.0)`	Create buzzer.
`play_tone(frequency, duration_ms=None)`	Play tone.
`stop()`	Stop sound.
`beep(frequency=None, on_ms=100, off_ms=100, times=1)`	Repeated tone.
`sweep(start_hz, end_hz, duration_ms, steps=10)`	Sweep frequencies.
`melody(name, tempo=None)`	Play built-in melody.

Built-in melodies: success, error, startup, notify, alarm, scale_c, siren

Example

from Reduino import target
target("COM3")

from Reduino.Actuators import Buzzer
from Reduino.Utils import sleep

bz = Buzzer(8)
bz.melody("startup")
sleep(500)
bz.beep(frequency=880, on_ms=100, off_ms=100, times=3)
bz.stop()

Servo

Method	Description
`Servo(pin=9, min_angle=0, max_angle=180, min_pulse_us=544, max_pulse_us=2400)`	Create servo.
`write(angle)`	Move to degrees (clamped).
`write_us(pulse)`	Move by pulse width (clamped).

Example

from Reduino import target
target("COM3")

from Reduino.Actuators import Servo
from Reduino.Utils import sleep

s = Servo(9)
s.write(90)
sleep(500)
s.write(0)

DC Motor

Method	Description
`DCMotor(in1, in2, enable)`	Control a motor driver with two direction pins and a PWM enable.
`set_speed(value)`	Drive with normalized speed `-1.0` (full reverse) to `1.0` (full forward).
`backward(speed=1.0)`	Convenience helper for negative speeds.
`stop()` / `coast()`	Active brake the motor or let it spin freely.
`invert()`	Toggle the wiring direction without rewiring.
`ramp(target_speed, duration_ms)`	Linearly change speed over a duration.
`run_for(duration_ms, speed)`	Drive at `speed` for `duration_ms` then stop.
`get_speed()` / `get_applied_speed()` / `is_inverted()` / `get_mode()`	Inspect the requested speed, final direction, wiring inversion and current drive mode (`"drive"`, `"coast"`, `"brake"`).

Example

from Reduino import target
target("COM3")

from Reduino.Actuators import DCMotor
from Reduino.Utils import sleep

motor = DCMotor(4, 5, 6)
motor.set_speed(0.4)
motor.run_for(1500, speed=1.0)
motor.ramp(-1.0, duration_ms=800)
sleep(250)
motor.stop()

Displays

LCD

Method	Description
`LCD(rs, en, d4, d5, d6, d7, cols=16, rows=2, rw=None, backlight_pin=None)`	4-bit parallel wiring with optional RW and PWM backlight pin. Constructor automatically calls `begin()` and clears the display.
`LCD(i2c_addr, cols=16, rows=2)`	PCF8574-style I²C backpack wiring. Constructor calls `init()`/`backlight()` for you.
`write(col, row, text, clear_row=True, align="left")`	Position text anywhere; optional row clearing and alignment (`"left"`, `"center"`, `"right"`).
`line(row, text, align="left", clear_row=True)`	Replace an entire row with aligned text.
`message(top=None, bottom=None, top_align="left", bottom_align="left", clear_rows=True)`	Convenience helper for two-line messages.
`clear()` / `display(on)` / `backlight(on)`	Clear the screen and toggle the LCD/backlight power.
`brightness(level)`	Set PWM backlight brightness (parallel mode with `backlight_pin`).
`glyph(slot, bitmap)`	Upload a custom 5×8 glyph (`bitmap` = 8 integers).
`progress(row, value, max_value=100, width=None, label=None, style="block")`	Render a progress bar (`style` = `"block"`, `"hash"`, `"pipe"`, or `"dot"`).
`animate(style, row, text, speed_ms=200, loop=False)`	Start a non-blocking animation (`style` = `"scroll"`, `"blink"`, `"typewriter"`, or `"bounce"`); the transpiler injects the required loop `tick()`.

Note

brightness() is available only when a parallel display is created with backlight_pin. All alignment parameters accept "left", "center", or "right" (case-insensitive).

Available animation styles:

scroll – marquee-style horizontal scrolling.
blink – toggles the text on and off without blocking.
typewriter – reveals the message one character at a time.
bounce – slides the text from edge to edge before reversing.

Parallel wiring example (PWM backlight + progress bar)

from Reduino import target
target("COM3")

from Reduino.Displays import LCD

lcd = LCD(rs=12, en=11, d4=5, d5=4, d6=3, d7=2, backlight_pin=9)
lcd.message("Setup complete", bottom="Waiting…", top_align="center")
lcd.progress(1, 30, max_value=100, width=12, label="Load")
lcd.brightness(200)

I²C backpack example (custom glyph + marquee animation)

from Reduino.Displays import LCD

panel = LCD(i2c_addr=0x27, cols=20, rows=4)
panel.glyph(0, [0, 2, 5, 8, 8, 5, 2, 0])
panel.line(0, "Ready to scroll", align="center")
panel.animate("scroll", 2, "This text scrolls without blocking!", speed_ms=150, loop=True)

Sensors

Button

Method	Description
`Button(pin, on_click=None, state_provider=None)`	Digital input w/ optional callback/provider.
`is_pressed()`	`1` if pressed else `0`.

Example

from Reduino import target
from Reduino.Actuators import Led
from Reduino.Sensors import Button

target("COM3")

led = Led(6)
btn = Button(7)
if btn.is_pressed():
    led.toggle()

Potentiometer

Method	Description
`Potentiometer(pin="A0", value_provider=None)`	Analog helper.
`read()`	0–1023 integer.

Example

from Reduino import target
from Reduino.Communication import SerialMonitor
target("COM3")

from Reduino.Sensors import Potentiometer

mon = SerialMonitor(9600 , "COM3")
pot = Potentiometer("A0")

while True:
    value = pot.read()
    mon.write(value)

Ultrasonic

Method	Description
`Ultrasonic(trig, echo, sensor="HC-SR04", distance_provider=None, default_distance=0.0)`	HC-SR04 factory.
`measure_distance()`	Distance in cm (handles timeouts/backoff).

Example

from Reduino import target
target("COM3")

from Reduino.Sensors import Ultrasonic
from Reduino.Utils import sleep

u = Ultrasonic(trig=9, echo=10)
d = u.measure_distance()
print(d)
sleep(60)

Communication

SerialMonitor

Method	Description
`SerialMonitor(baud_rate=9600, port=None, timeout=1.0)`	Host-side serial console.
`connect(port)`	Open serial (requires `pyserial`).
`close()`	Close port.
`write(value)`	Send text.
`read()`	Read text.

Example (host-side)

from Reduino import target
target("COM3")

from Reduino.Communication import SerialMonitor

mon = SerialMonitor(baud_rate=115200, port="COM4")

while True:
    mon.write("hello")
    mon.read()
    mon.close()

Note

pyserial is optional; only needed if you call connect().

Utilities

sleep

from Reduino import target
target("COM3")

from Reduino.Utils import sleep
sleep(250)  # ms

map

from Reduino import target
target("COM3")

from Reduino.Utils import map
mapped = map(512, 0, 1023, 0.0, 5.0)  # 2.5-ish
print(mapped)

Core

The Core module exposes low-level helpers that map directly to the Arduino API. Use these when you need to configure a pin or interact with a sensor that doesn't yet have a dedicated Reduino abstraction.

Helper	Description
`pin_mode(pin, mode)`	Configure a pin for `INPUT`, `INPUT_PULLUP`, or `OUTPUT`.
`digital_write(pin, value)`	Write `HIGH`/`LOW` to a digital pin.
`analog_write(pin, value)`	Output a PWM value (0–255).
`digital_read(pin)`	Read a digital pin (returns `0` or `1`).
`analog_read(pin)`	Read an analogue value (0–1023 on most boards).

Constants INPUT, OUTPUT, INPUT_PULLUP, HIGH, and LOW mirror the Arduino macros so your code matches what you would write in C++.

from Reduino import target
target("COM3")

from Reduino.Core import pin_mode, digital_write, digital_read, OUTPUT, HIGH, LOW

pin_mode(7, OUTPUT)
digital_write(7, HIGH)

if digital_read(2) == HIGH:
    digital_write(7, LOW)

Supported Python features

Reduino implements a pragmatic subset of Python that cleanly lowers to Arduino C++.

Control flow

while True: ➜ Arduino loop()
for x in range(...), including range(start, stop, step)
if / elif / else, break, continue, try/except (mapped to C++ try/catch where used)

Variables & assignment

Standard assignment and pythonic swap:
```
a, b = b, a
```
Multiple assignment & tuple unpacking
Augmented ops (+=, -=, *=, etc.)

Collections

Lists ([]), tuples (()), and membership checks (x in items)
List comprehensions:
```
squares = [i for i in range(10)]
```
len() on strings, lists, and internal list type

Built-ins

len(), abs(), max(), min()
print() maps to serial printing in emitted code when serial is configured

Tip

Many constant expressions are folded at transpile time for smaller, faster C++.

License

Reduino is distributed under the GNU General Public License v3.0 (GPLv3).
You are free to use, modify, and distribute this software for personal or educational purposes,
as long as derivative works remain open-source and licensed under the same terms.

For commercial usage, redistribution, or integration into closed-source systems,
please contact me at [email protected] for alternative licensing options.

See LICENSE for full details.

Name		Name	Last commit message	Last commit date
Latest commit History 105 Commits
.github/workflows		.github/workflows
src/Reduino		src/Reduino
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt

License

Jackhammer9/Reduino

Folders and files

Latest commit

History

Repository files navigation

Reduino

Table of contents

Overview

Quick start

The target() function (Required)

Example: Reduino structure explained

Targeting different platforms & boards

API reference

Actuators

LED

RGB LED

Buzzer

Servo

DC Motor

Displays

LCD

Sensors

Button

Potentiometer

Ultrasonic

Communication

SerialMonitor

Utilities

sleep

map

Core

Supported Python features

Control flow

Variables & assignment

Collections

Built-ins

License

Star History

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 5

Uh oh!

Languages

The `target()` function (Required)