Device

class ledsign.LEDSign

Returned by LEDSign.open(), represents a handle to an LED sign device.

ACCESS_MODE_NONE: int: Access mode representing a device handle without read or write access. At the moment only used by closed device handles.

ACCESS_MODE_READ: int: Access mode representing a device handle with only read permissions.

ACCESS_MODE_READ_WRITE: int: Access mode representing a device handle with both read and write permissions.

static enumerate() → list[str]: Returns a list of available device paths detected by the OS.

static open(path: str | None = None) → LEDSign

Opens the device pointed to by path (or the default device if no path is provided), and returns its corresponding LEDSign object. The device path must have been returned by a previous call to enumerate().

If the device is not found, a LEDSignDeviceNotFoundError will be raised. Additionally, if the device protocol version is incompatible, or if the Python API was disabled in device settings, a LEDSignUnsupportedProtocolError or LEDSignProtocolError exception will be returned respectively. If a proxy connection cannot be established, or if the proxy server is not running, a LEDSignProxyError will be returned (see Proxy server for documentation on how to start the server).

Note

Due to the internal USB-level configuration, this library can be used alongside the UI without unintended protocol side effects. This feature allows the UI to be kept open while writing new programs to ease the debugging / visualization process.

close() → None: Closes the underlying device handle. After a call to this function, all methods except for get_path() and get_access_mode() will raise a LEDSignAccessError exception.

get_access_mode() → int

Returns the access mode (permissions) granted by the device. Possible return values are:

ACCESS_MODE_NONE: No access; device handle was closed
ACCESS_MODE_READ: Read-only access; program uploads will be rejected
ACCESS_MODE_READ_WRITE: Full read-write access

get_access_mode_str() → str: Same as get_access_mode(), but returns a stringified versions of the access mode. Possible values are: "none", "read-only", or "read-write".

get_driver_brightness() → float: Returns the current device brightness setting, normalized between 0.0 and 1.0.

Note

If the overcurrent flag was tripped (see get_psu_current() for details), the returned brightness setting may not reflect the real-world conditions.

get_driver_current_usage() → float

Returns the current being drawn by the device hardware from the power supply. Internally, this same value is used in the overcurrent protection circuit (see get_psu_current() for more details).

The current usage is fetched periodically from the device, at an interval specified by get_driver_status_reload_time().

get_driver_load() → float

Returns the current driver CPU load, normalized between 0.0 and 1.0. The returned value represents the frame render duration, measured as a fraction of the overall frame time.

The driver load is fetched periodically from the device, at an interval specified by get_driver_status_reload_time().

get_driver_program_time() → float

Returns the current program timestamp. The timestamp wraps around to zero at program duration, ie. timestamp %= self.get_program().get_duration().

The timestamp is fetched periodically from the device, at an interval specified by get_driver_status_reload_time().

get_driver_status_reload_time() → float: Returns the current refresh interval (in seconds) used for fetching driver data, or -1 if caching is disabled. Can be modified using set_driver_status_reload_time().

get_driver_temperature() → float

Returns the current temperature of the LED driver, in degrees Celsius.

The temperature is fetched periodically from the device, at an interval specified by get_driver_status_reload_time().

get_firmware() → str: Returns a 40-character hex string uniquely identifying the current firmware versions of the device.

get_hardware() → LEDSignHardware: Returns a read-only LEDSignHardware object representing the current external hardware configuration of the device.

get_path() → str | None: Returns the underlying OS path of the device, or None if the device was closed.

get_program() → LEDSignProgram: Returns a read-only LEDSignProgram object containing the current device program. For performance reasons, the program is lazily loaded only when its keypoints are accessed to prevent significant start-up delays.

get_psu_current() → float: Returns the configured theoretical current limit of the power supply, in amps. As only 5V power supplies are supported, no explicit voltage getter method is provided.

Danger

If the device draws more current than this limit, a device-internal overcurrent safety flag will be raised. Whenever this flag is active, no changes made to the device will be visible.

For safety reasons, this flag can only be cleared from the UI menu, or through device reboots.

get_serial_number() → int: Returns the unique 64-bit serial number of the device.

get_serial_number_str() → str: Same as get_serial_number(), but formats the serial number as a 16-hex-digit string.

get_storage_size() → int: Returns the storage capacity of the device allocated for program storage, in bytes.

is_driver_paused() → bool: Returns True if the LED driver is in a paused state (ie. the program playback is frozen), and False otherwise.

Note

For internal protocol reasons, this flag is not periodically synchronized with the device.

set_driver_status_reload_time(interval: float) → float: Sets interval as the new driver data refresh interval (in seconds), and returns the previous value. Negative values for interval disable caching and fetch data whenever it is requested.

upload_program(program: LEDSignCompiledProgram, callback: Callable[[float, bool], None] | None = None) → None

Uploads the given program to the device. If the device was opened in read-only mode, a LEDSignAccessError exception will be raised.

The optional callback argument is periodically called throughout the upload process with arguments (progress, is_first_stage).

exception ledsign.LEDSignAccessError: Raised when the device access mode was violated.

exception ledsign.LEDSignDeviceNotFoundError: Raised by LEDSign.open() when no device was found.

exception ledsign.LEDSignProtocolError: Raised during any encountered protocol error.

exception ledsign.LEDSignProxyError: Raised when any proxy-related exception is encountered.

exception ledsign.LEDSignUnsupportedProtocolError: Raised when the device responds with an unimplemented protocol version.