API

Device

class Device(*args, startup: Optional[str] = None, attempts: int = 0, **kwargs)

Belay interface into a micropython device.

Can be used as a context manager; calls self.close on exit.

Uses the autoregistry.RegistryMeta metaclass for easy-to-access subclasses.

implementation

Implementation details of device.

Type: Implementation

MAX_CMD_HISTORY_LEN = 1000

close() → None

Close the connection to device.

Automatically called on context manager exit.

proxy(name: str) → belay.proxy_object.ProxyObject

Create a ProxyObject that uses this Device.

Parameters: name (str) -- Name of the remote object for the proxy-object to interact with.

reconnect(attempts: Optional[int] = None) → None

Reconnect to the device and replay the command history.

Parameters: attempts (int) -- Number of times to attempt to connect to board with a 1 second delay in-between. If None, defaults to whatever value was supplied to init. If init value is 0, then defaults to 1.

static setup() → Callable[[P], belay.device.R]

static setup(*, implementation: str = "''", **kwargs) → Callable[[Callable[[P], belay.device.R]], Callable[[P], belay.device.R]]

Execute decorated function's body in a global-context on-device when called.

Function arguments are also set in the global context.

Can either be used as a staticmethod @Device.setup for marking methods in a subclass of Device, or as a standard method @device.setup for marking functions to a specific Device instance.

Parameters

f (Callable) -- Function to decorate. Can only accept and return python literals.
minify (bool) -- Minify cmd code prior to sending. Defaults to True.
register (bool) -- Assign an attribute to self.setup with same name as f. Defaults to True.
record (bool) -- Each invocation of the executer is recorded for playback upon reconnect. Defaults to True.
autoinit (bool) -- Automatically invokes decorated functions at the end of object __init__. Methods will be executed in order-registered. Defaults to False.
ignore_errors (bool) -- Discard any device-side uncaught exception. Defaults to False.
implementation (str) -- If supplied, the provided method will only be used if the board's implementation name matches. Several methods of the same name can be overloaded that support different implementations. Common values include "micropython", and "circuitpython". Defaults to an empty string, which all implementations will match to.

soft_reset(): Reset device, executing main.py if available.

sync(folder: Union[str, pathlib.Path], dst: str = '/', keep: Union[None, list, str, bool] = None, ignore: Union[None, list, str] = None, minify: bool = True, mpy_cross_binary: Optional[Union[str, pathlib.Path]] = None, progress_update=None) → None

Sync a local directory to the remote filesystem.

For each local file, check the remote file's hash, and transfer if they differ. If a file/folder exists on the remote filesystem that doesn't exist in the local folder, then delete it (unless it's in keep).

Parameters

folder (str, Path) -- Single file or directory of files to sync to the root of the board's filesystem.
dst (str) -- Destination directory on device. Defaults to unpacking folder to root.
keep (None | str | list | bool) -- Do NOT delete these file(s) on-device if not present in folder. If true, don't delete any files on device. If false, delete all unsynced files (same as passing []). If dst is None, defaults to ["boot.py", "webrepl_cfg.py", "lib"].
ignore (None | str | list) -- Git's wildmatch patterns to NOT sync to the device. Defaults to ["*.pyc", "__pycache__", ".DS_Store", ".pytest_cache"].
minify (bool) -- Minify python files prior to syncing. Defaults to True.
mpy_cross_binary (Union[str, Path, None]) -- Path to mpy-cross binary. If provided, .py will automatically be compiled. Takes precedence over minifying.
progress_update -- Partial for rich.progress.Progress.update(task_id,...) to update with sync status.

sync_dependencies(package: Union[module, str], *subfolders: Union[str, pathlib.Path], dst='/lib', **kwargs)

Convenience method for syncing dependencies bundled with package.

If using Belay's package manager feature, set dependencies_path to a folder inside your python package (e.g. dependencies_path="mypackage/dependencies").

The following example will sync all the files/folders in mypackage/dependencies/main to device's /lib.

import mypackage

device.sync_package(mypackage, "dependencies/main")

For intended use, sync_dependencies should be only be called once. Multiple invocations overwrite/delete previous calls' contents.

# Good
device.sync_package(mypackage, "dependencies/main", "dependencies/dev")

# Bad (deletes on-device files from "dependencies/main")
device.sync_package(mypackage, "dependencies/main")
device.sync_package(mypackage, "dependencies/dev")

Parameters

package (Union[ModuleType, str]) -- Either the imported package or the name of a package that contains the data we would like to sync.
*subfolders -- Subfolder(s) to combine and then sync to dst. Typically something like "dependencies/main"
dst (Union[str, Path]) -- On-device destination directory. Defaults to /lib.
**kwargs -- Passed along to Device.sync.

static task() → Callable[[P], belay.device.R]

static task(**kwargs) → Callable[[Callable[[P], belay.device.R]], Callable[[P], belay.device.R]]

Execute decorated function on-device.

Sends source code to device at decoration time. Execution sends involves much smaller overhead.

Can either be used as a staticmethod @Device.task for marking methods in a subclass of Device, or as a standard method @device.task for marking functions to a specific Device instance.

Parameters

f (Callable) -- Function to decorate. Can only accept and return python literals.
minify (bool) -- Minify cmd code prior to sending. Defaults to True.
register (bool) -- Assign an attribute to self.task with same name as f. Defaults to True.
record (bool) -- Each invocation of the executer is recorded for playback upon reconnect. Only recommended to be set to True for a setup-like function. Defaults to False.
implementation (str) -- If supplied, the provided method will only be used if the board's implementation name matches. Several methods of the same name can be overloaded that support different implementations. Common values include "micropython", and "circuitpython". Defaults to an empty string, which all implementations will match to.
trusted (bool) -- Fully trust remote device. When set to False, only [None, bool, bytes, int, float, str, List, Dict, Set] return values can be parsed. When set to True, any value who's repr can be evaluated to create a python object can be returned. However, this also allows the remote device to execute arbitrary code on host. Defaults to False.

static teardown() → Callable[[P], belay.device.R]

static teardown(**kwargs) → Callable[[Callable[[P], belay.device.R]], Callable[[P], belay.device.R]]

Executes decorated function's body in a global-context on-device when device.close() is called.

Function arguments are also set in the global context.

Can either be used as a staticmethod @Device.teardown for marking methods in a subclass of Device, or as a standard method @device.teardown for marking functions to a specific Device instance.

Parameters

f (Callable) -- Function to decorate. Can only accept and return python literals.
minify (bool) -- Minify cmd code prior to sending. Defaults to True.
register (bool) -- Assign an attribute to self.teardown with same name as f. Defaults to True.
record (bool) -- Each invocation of the executer is recorded for playback upon reconnect. Defaults to True.
ignore_errors (bool) -- Discard any device-side uncaught exception. Defaults to False.
implementation (str) -- If supplied, the provided method will only be used if the board's implementation name matches. Several methods of the same name can be overloaded that support different implementations. Common values include "micropython", and "circuitpython". Defaults to an empty string, which all implementations will match to.

terminal(*, exit_char='\x1d'): Start a blocking interactive terminal over the serial port.

static thread() → Callable[[P], belay.device.R]

static thread(**kwargs) → Callable[[Callable[[P], belay.device.R]], Callable[[P], belay.device.R]]

Spawn on-device thread that executes decorated function.

Can either be used as a staticmethod @Device.thread for marking methods in a subclass of Device, or as a standard method @device.thread for marking functions to a specific Device instance.

Parameters

f (Callable) -- Function to decorate. Can only accept python literals as arguments.
minify (bool) -- Minify cmd code prior to sending. Defaults to True.
register (bool) -- Assign an attribute to self.thread with same name as f. Defaults to True.
record (bool) -- Each invocation of the executer is recorded for playback upon reconnect. Defaults to True.
implementation (str) -- If supplied, the provided method will only be used if the board's implementation name matches. Several methods of the same name can be overloaded that support different implementations. Common values include "micropython", and "circuitpython". Defaults to an empty string, which all implementations will match to.

class ProxyObject(device: Device, name: str)

Proxy object for interacting/mimicking a remote micropython object.

If subclassing ProxyObject:

Be sure to call super().__init__(device, name) first.
Use object.__setattr__(self, "some_attribute_name", value) to create/set a local attribute. Attributes created this way will only be stored locally in CPython and will not interact with the micropython board. Subsequent writes to this attribute can be done "normally" (without object.__setattr__).

class Implementation(name: str, version: Tuple[int, int, int] = (0, 0, 0), platform: str = '', emitters: Tuple[str] = ())

Implementation dataclass detailing the device.

Parameters

name (str) -- Type of python running on device. One of {"micropython", "circuitpython"}.
version (Tuple[int, int, int]) -- (major, minor, patch) Semantic versioning of device's firmware.
platform (str) -- Board identifier. May not be consistent from MicroPython to CircuitPython. e.g. The Pi Pico is "rp2" in MicroPython, but "RP2040" in CircuitPython.
emitters (tuple[str]) -- Tuple of available emitters on-device {"native", "viper"}.