Welcome to Belay's documentation!

Belay is a library that enables the rapid development of projects that interact with hardware via a micropython-compatible board.

Belay works by interacting with the REPL interface of a micropython board from Python code running on PC.

Quick Video of Belay in 22 seconds.

See the documentation for usage and other details.

Who is Belay For?

Belay is for people creating a software project that needs to interact with hardware. Examples include:

  • Control a motor so a webcam is always pointing at a person.

  • Turn on an LED when you receive a notification.

  • Read a potentiometer to control system volume.

If you have no need to run Python code on PC, then Belay is not for you.

What Problems Does Belay Solve?

Typically, having a python script interact with hardware involves 3 major challenges:

  1. On-device firmware (usually C or MicroPython) for directly handling hardware interactions. Typically this is developed, compiled, and uploaded as a (nearly) independent project.

  2. A program on your computer that performs the tasks specified and interacts with the device.

  3. Computer-to-device communication protocol. How are commands and results transferred? How does the device execute those commands?

This is lot of work if you just want your computer to do something simple like turn on an LED. Belay simplifies all of this by merging steps 1 and 2 into the same codebase, and manages step 3 for you. Code is automatically synced at the beginning of script execution.


Belay requires Python >=3.8 and can be installed via:

pip install belay

The micropython-compatible board only needs micropython installed; no additional preparation is required.


Turning on an LED with Belay takes only 6 lines of code. Functions decorated with the task decorator are sent to the device and interpreted by the MicroPython interpreter. Calling the decorated function on-host sends a command to the device to execute the actual function.

import belay

device = belay.Device("/dev/ttyUSB0")

def set_led(state):
    Pin(25, Pin.OUT).value(state)


For more examples, see the examples folder.

Indices and tables