Python SDK API Reference

GCLight Python SDKDeveloper guide

This reference covers gclight==0.1.0 (Alpha). Import the public device API, models, and exceptions from gclight.v1.mini. Only Mini protocol v1 over a serial connection is implemented. See the quick start for installation.

Connection and discovery

from gclight.v1.mini import Mini, discover_minis

device = Mini("COM3", baudrate=115200, command_timeout=2.0)
report = device.connect()
try:
    print(report.info.serial_number)
    print(device.query_state())
finally:
    device.close()

# Probe only supplied candidates, without enumerating system ports.
for found in discover_minis(["COM3", "COM4"], command_timeout=2.0):
    print(found.port, found.serial_number, found.software_version)

Interface	Behavior
`Mini(port, *, baudrate=115200, command_timeout=2.0, transport=None)`	Construction performs no I/O; `port` must be a non-empty string. Serial is the default. You can pass a custom transport implementation through `transport`, but the SDK has no built-in Bluetooth transport.
`connect() -> ConnectionReport`	Opens the specified port, handshakes, identifies the device, and synchronizes output state and actual current. Returns `info`, `connected_at_ms`, and session `state`.
`close() -> None`	Ends the session and closes transport. It is not `laser_off()`.
`with Mini(port) as device`	Calls `connect()` on entry and `close()` on exit.
`discover_minis(candidates, *, baudrate=115200, command_timeout=2.0)`	Probes supplied candidates only, closes every probe connection, and returns a tuple of `DiscoveredMini`. No matches does not prove there are no devices on the system.

command_timeout is a positive finite number of seconds, not an overall program deadline. Connecting an already connected object raises an error; close it before reconnecting.

Identity, state, and queries

Interface	Result and behavior
`device.info`	`DeviceInfo`: `protocol_version`, `serial_number`, `software_version`.
`device.state`	Local `MiniState` snapshot: `timestamp_ms`, `output_enabled`, `actual_current_ma`, `source`. Access does not issue a fresh query.
`query_state()`	Queries output state and actual current, updating and returning `MiniState`.
`query_status(fields)`	Takes a non-empty tuple of unique `MiniQuery` members; returns `MiniStatusSnapshot` with an enum-keyed `values` mapping.
`query_bluetooth_enabled()`	Returns the device Bluetooth switch as a `bool`, still using the serial connection.

The actual current in state comes from synchronization or explicit queries. Status reports can update its output switch; do not treat this snapshot as a complete live telemetry stream. source describes the state origin; consume telemetry through the event API.

from gclight.v1.mini import Mini, MiniQuery

with Mini("COM3") as device:
    snapshot = device.query_status((
        MiniQuery.ACTUAL_CURRENT,
        MiniQuery.TEMPERATURE_1,
    ))
    print(snapshot.values[MiniQuery.ACTUAL_CURRENT])
    print(snapshot.values[MiniQuery.TEMPERATURE_1])

`MiniQuery`	Value
`OUTPUT_STATE`	Output switch, `bool`
`ACTUAL_CURRENT`	Actual current, mA
`ACTUAL_VOLTAGE`	Actual voltage, mV
`TEMPERATURE_1`	Temperature, °C
`PD_DATA`	PD value scaled by the device profile; do not assume an optical-power unit
`CURRENT_SETTING`	Current setting, mA
`BLUETOOTH_STATE`	Bluetooth switch, `bool`

Control and receipts

Method	Behavior
`laser_on(*, current_ma)`	Requires an explicit current. Sets current before requesting laser-on in the same frame.
`laser_off()`	Explicitly requests output disable.
`set_current(current_ma)`	Sets current without changing the output switch.
`set_bluetooth_enabled(enabled)`	Requires a `bool`; changes the device Bluetooth switch over serial, without establishing a Bluetooth connection.
`run_self_test()`	Starts a device self-test and waits with a 10-second command deadline. Returns `SelfTestResult(timestamp_ms, success)`. This is not a read-only query.

The first four methods return CommandReceipt, with timestamp_ms, outcomes, and the computed success property. Each CommandOutcome includes command_type, success, and individual field results. Rejected commands raise CommandRejectedError; do not expect only a returned success=False.

Current accepts int / float, rejecting bool, negative values, NaN, infinity, and more than two decimal places. The identified device profile also imposes a current range. Do not assume one maximum applies to every model.

Device events and queue capacity

next_event(timeout=None) -> DeviceEvent: reads one event from the local queue. None waits indefinitely, 0 does not wait, and a finite non-negative number sets the maximum wait in seconds. Expiry raises EventTimeoutError; it is unrelated to a device-command timeout.
iter_events(): continuously reads events and waits indefinitely; it has no timeout argument. To limit the number or duration of waits, call next_event(timeout=...) in a loop with a fixed iteration count.
event_stats: returns dropped_telemetry_count and coalesced_state_count. If events arrive faster than the application reads them, a full queue can drop telemetry or combine state reports. The event API does not guarantee delivery of every device report.

Event type	Fields
`TelemetryReport`	`timestamp_ms`, plus nullable `current_ma`, `voltage_mv`, `pd_data`, `temperature_1_celsius`, and `current_setting_ma`.
`StatusReport`	`timestamp_ms`, `output_enabled`.
`ExceptionReport`	`timestamp_ms`, `error_bits`. Error information reported by the device, not a raised Python exception.

Reports also retain raw_fields. If the queue is full and cannot store an exception report, the SDK raises EventBufferOverflowError. Do not ignore this error: stop the normal control flow, check event consumption speed and device safety, then reconnect.

Errors and recovery

GCLightError is the common base for SDK errors. Invalid arguments can also raise Python ValueError or TypeError.

Exception	Response
`ConnectionError` / `HandshakeError`	Check port, contention, drivers, and cable. Call `close()` before retrying a failed connection.
`UnsupportedDeviceError` / `UnsupportedProtocolVersionError`	Check for supported Mini hardware using Mini protocol v1 over serial; do not bypass identification.
`DeviceDisconnectedError` / `TransportError`	Check connectivity and device safety. An initial send failure raises `TransportError`; the SDK may reject later commands because it can no longer confirm the session state.
`CommandRejectedError`	Inspect rejected commands and fields. Do not assume every operation in the same protocol frame was left unapplied.
`DeviceBusyError`	Another command is pending on this session; do not issue concurrent commands on the same session.
`CommandTimeoutError` / `SessionDesynchronizedError`	The SDK may be unable to confirm whether the device executed the command. Establish hardware safety, close and reconnect, then query state. Do not resend controls automatically.
`ProtocolError` (including `FrameError`, `CrcError`, `TlvError`, `MessageValidationError`)	Diagnose protocol/data issues and re-establish a known connection; do not assume the session remains usable.
`EventTimeoutError`	Local event wait expired. Waiting again is valid; this alone does not require reconnecting.
`EventBufferOverflowError`	The event queue filled and some events were not retained. Account for the missing data and verify device safety before reconnecting.

After a command timeout, send failure, or invalid command response, the SDK may no longer know the current session state. New commands are then rejected, but device reports remain available through the event API unless the connection has terminated. Recovery requires close(), then connect(), then query_state(). The SDK does not automatically retry or resend control commands. A laser-off command can also fail when the session state is unknown, so software cleanup is not a substitute for hardware safety.