Quick start

Supported scope

gclight is a synchronous, typed Python SDK. This guide covers 0.1.0, classified as Alpha in the package metadata. It is not a promise of production support for every device or operating system.

• Requires Python 3.10 or later and an accessible serial port. Upstream lists Windows and Ubuntu as operating environments.
• No Bluetooth transport is provided. Bluetooth methods only query or change the device's Bluetooth switch through an existing serial connection.
• The SDK does not scan system ports automatically. Close Studio or other programs using the same port, and supply the actual assigned port, such as COM3 or /dev/ttyACM0.

Want commands without writing Python? See the standalone CLI downloads and quick start.

Install with uv

Install uv using the official installation guide. In an existing Python project, run:

uv add gclight

For a new project:

uv init --python 3.10 mini-demo
cd mini-demo
uv add gclight

These commands install the available package release; this guide describes 0.1.0. To reproduce that version, use uv add gclight==0.1.0.

First connection: read only

Save this as read_mini.py and replace COM3 with your actual port:

from gclight.v1.mini import Mini

# Construction does not open the port or perform device I/O.
device = Mini("COM3", baudrate=115200, command_timeout=2.0)

# Entering the context connects, handshakes, and synchronizes initial state.
with device:
    print(device.info.serial_number)
    print(device.info.software_version)
    state = device.query_state()
    print(state.output_enabled, state.actual_current_ma)

uv run read_mini.py

info is an identity snapshot; state is a local state snapshot. Call query_state() for a fresh query. Connecting reads the initial state; it does not turn off output that is already enabled. Accessing info before connection or state before synchronization raises DeviceDisconnectedError.

Read device events

A background reader continuously receives device events. next_event() reads one event from a fixed-capacity local queue; it neither polls the device nor enables laser output. A timeout is normal when the device sends no reports.

from gclight.v1.mini import (
    EventTimeoutError,
    ExceptionReport,
    Mini,
    StatusReport,
    TelemetryReport,
)

with Mini("COM3") as device:
    try:
        event = device.next_event(timeout=1.0)
    except EventTimeoutError:
        print("No report within one second")
    else:
        if isinstance(event, TelemetryReport):
            print(event.current_ma, event.pd_data)
        elif isinstance(event, StatusReport):
            print(event.output_enabled)
        elif isinstance(event, ExceptionReport):
            print(f"Device error bits: 0x{event.error_bits:04X}")
    print(device.event_stats)

Save this as events.py and run uv run events.py. Telemetry fields may be None. See the API reference for what happens when the queue fills and how to recover from errors.

Before controlling output

The finally block attempts an explicit laser-off command. That command can also fail if the connection is lost or the SDK can no longer confirm the session state. An independent hardware shutdown procedure is required.

from gclight.v1.mini import Mini

with Mini("COM3") as device:
    try:
        # Set current before requesting output enable in the same frame.
        device.laser_on(current_ma=120.00)
        print(device.query_state())
    finally:
        device.laser_off()

set_current() changes current without switching output state. If output is already on, changing current affects real output. Current must be finite, non-negative, have at most two decimal places, and fall within the identified device's limits.

Troubleshooting and recovery

• Port cannot open: check the assigned port, data-capable USB cable, serial driver, and access permissions. Close other programs using the port. Ubuntu commonly requires membership in dialout; log in again after changing group membership.
• Handshake or protocol mismatch: confirm the device is a supported Mini using Mini protocol v1 over serial. Do not identify unknown devices by repeatedly sending control commands.
• Command timeout or send failure: the device may already have executed the command. An error does not mean “the laser never turned on.” The SDK may no longer know the session state and does not automatically resend control commands.
• Recovery order: establish safe output using your site's safety procedure, call close() then connect(), and query state again before deciding what to do next. Never unconditionally replay laser_on().

Continue with the API reference or the gcli command reference.