API Documentation

Low-level library for Bluetooth LE connection to Brilliant Labs Frame

class frame_ble.FrameBle

Bases: object

Frame bluetooth class for managing a connection and transferring data to and from the device.

async connect(name=None, timeout=10, print_response_handler=<function FrameBle.<lambda>>, data_response_handler=<function FrameBle.<lambda>>, disconnect_handler=<function FrameBle.<lambda>>)

Connects to the first Frame device discovered, optionally matching a specified name e.g. “Frame AB”, or throws an Exception if a matching Frame is not found within timeout seconds.

name can optionally be provided as the local name containing the 2 digit ID shown on Frame, in order to only connect to that specific device. The value should be a string, for example “Frame 4F”

print_response_handler and data_response_handler can be provided and will be called whenever data arrives from the device asynchronously.

disconnect_handler can be provided to be called to run upon a disconnect.

async disconnect()

Disconnects from the device.

is_connected()

Returns True if the device is connected. False otherwise.

max_lua_payload()

Returns the maximum length of a Lua string which may be transmitted.

max_data_payload()

Returns the maximum length of a raw bytearray which may be transmitted.

async send_lua(string: str, show_me=False, await_print=False)

Sends a Lua string to the device. The string length must be less than or equal to max_lua_payload().

If await_print=True, the function will block until a Lua print() occurs, or a timeout.

If show_me=True, the exact bytes send to the device will be printed.

async send_data(data: bytearray, show_me=False, await_data=False)

Sends raw data to the device. The payload length must be less than or equal to max_data_payload().

If await_data=True, the function will block until a data response occurs, or a timeout.

If show_me=True, the exact bytes send to the device will be printed.

async send_reset_signal(show_me=False)

Sends a reset signal to the device which will reset the Lua virtual machine.

If show_me=True, the exact bytes send to the device will be printed.

async send_break_signal(show_me=False)

Sends a break signal to the device which will break any currently executing Lua script.

If show_me=True, the exact bytes send to the device will be printed.

async upload_file_from_string(content: str, frame_file_path='main.lua')

Uploads a string as frame_file_path. If the file exists, it will be overwritten.

Parameters:

• content (str) – The string content to upload

• frame_file_path (str) – Target file path on the frame

async upload_file(local_file_path: str, frame_file_path='main.lua')

Uploads a local file to the frame. If the target file exists, it will be overwritten.

Parameters:

• local_file_path (str) – Path to the local file to upload. Must exist.

• frame_file_path (str) – Target file path on the frame

Raises:

FileNotFoundError – If local_file_path doesn’t exist

async send_message(msg_code: int, payload: bytes, show_me: bool = False) → None

Send a large payload in chunks determined by BLE MTU size.

Parameters:

• msg_code (int) – Message type identifier (0-255)

• payload (bytes) – Data to be sent

• show_me (bool) – If True, the exact bytes send to the device will be printed

Raises:

ValueError – If msg_code is not in range 0-255 or payload size exceeds 65535

Note

First packet format: [msg_code(1), size_high(1), size_low(1), data(…)] Other packets format: [msg_code(1), data(…)]