API

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

Belay interface into a micropython device.

implementation

Implementation details of device.

Type

Implementation

task(f: Optional[Callable[..., None]] = None, /, minify: bool = True, register: bool = True)

Decorator that send code to device that executes when decorated function is called on-host.

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.

thread(f: Optional[Callable[..., None]] = None, /, minify: bool = True, register: bool = True)

Decorator that send code to device that spawns a thread when executed.

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.

__call__(cmd: str, minify: bool = True, stream_out: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, record=True) → Union[Generator[Union[None, bool, bytes, int, float, str, List, Dict, Set], None, None], None, bool, bytes, int, float, str, List, Dict, Set]

Execute code on-device.

Parameters

  • cmd (str) -- Python code to execute.

  • minify (bool) -- Minify cmd code prior to sending. Reduces the number of characters that need to be transmitted. Defaults to True.

  • record (bool) -- Record the call for state-reconstruction if device is accidentally reset. Defaults to True.

Return type

Return value from executing code on-device.

close() → None

Close the connection to device.

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.

sync(folder: Union[str, Path], minify: bool = True, keep: Union[None, list, str] = None, progress_update=None) → None

Sync a local directory to the root of 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.

Parameters

  • folder (str, Path) -- Directory of files to sync to the root of the board's filesystem.

  • minify (bool) -- Minify python files prior to syncing. Defaults to True.

  • keep (str or list) -- Do NOT delete these file(s) on-device if not present in folder. Defaults to ["boot.py", "webrepl_cfg.py"].

  • progress -- Partial for rich.progress.Progress.update(task_id,...) to update with sync status.

exception AuthenticationError

Bases: BelayException

Invalid password or similar.

exception FeatureUnavailableError

Bases: BelayException

Feature unavailable for your board's implementation.

class Implementation(name: str, version: Tuple[int, int, int], platform: str)

Bases: object

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.

name: str
platform: str
version: Tuple[int, int, int]
exception PyboardException

Bases: Exception

Uncaught exception from the device.

exception SpecialFunctionNameError

Bases: BelayException

Reserved function name that may impact Belay functionality.

Currently limited to:

  • Names that start and end with double underscore, __.

  • Names that start with _belay or __belay

minify(code: str) → str

Minify python code.

Naive code minifying that preserves names and linenos. Performs the following:

  • Removes docstrings.

  • Removes comments.

  • Removes unnecessary whitespace.

Parameters

code (str) -- Python code to minify.

Returns

Minified code.

Return type

str