How to make a request
Tell the Agent to use gclight-control, then provide the target serial port, the state to read or change, and every explicit parameter required for a change. The Skill is the unified entry point for GC Light device families; the current gcli release supports Mini only. Windows ports commonly look like COM3, while Linux ports may look like /dev/ttyACM0; use the port actually assigned by the operating system.
Read-only examples:
Use gclight-control to show the serial number and current output state of the Mini on COM3.
Use gclight-control to read actual current, temperature, and Bluetooth state from the Mini on /dev/ttyACM0.
State-changing examples:
Use gclight-control to set the Mini on /dev/ttyACM1 to 120 mA, enable output, and verify the state.
Immediately disable laser output on the Mini at COM3 and confirm that output_enabled is false.
Supported operations
| Intent | gcli operation used by the Agent |
|---|---|
| Probe known candidate ports | mini discover <PORT> [...] |
| Read identity | mini -p <PORT> info |
| Read output state and actual current | mini -p <PORT> state |
| Read all or selected status fields | mini -p <PORT> status [FIELD ...] |
| Set current and enable output | mini -p <PORT> laser-on --current-ma <MA> |
| Disable output | mini -p <PORT> laser-off |
| Change current setting only | mini -p <PORT> set-current --current-ma <MA> |
| Read or change Bluetooth state | `mini -p |
| Run the device self-test | mini -p <PORT> self-test |
| Read a bounded number of reports | mini -p <PORT> events --count <N> --event-timeout <SECONDS> |
Available status fields are output-state, actual-current, actual-voltage, temperature-1, pd-data, current-setting, and bluetooth-state. Current uses mA, voltage uses mV, and temperature uses degrees Celsius.
See the gcli command reference if you want to run these commands yourself.
How the Skill changes device state
laser-on, laser-off, set-current, Bluetooth changes, and self-test all change device state. The Skill runs one only when the request explicitly authorizes that operation.
Enabling output
Before enabling output, the Agent should query info and state so the serial number and pre-command output state are visible. It executes the mutation once, then queries state again to confirm the observable output_enabled value.
Disabling output
For an emergency or explicit laser-off request, the Agent should send laser-off before optional diagnostic reads, then query state and confirm that output_enabled is false.
Setting current or changing Bluetooth
After setting current, the Agent queries current-setting and output-state. After a Bluetooth change, it runs bluetooth get. A successful command exit without follow-up state evidence is not enough to establish that the change took effect.
Timeouts, failures, and ambiguous results
- A successful device command normally writes one compact JSON value to stdout. The Agent parses or reports it only after an exit code of
0. - Argument parsing errors return exit code
2; device, transport, and runtime errors return exit code1. The Agent should preserve the specific error text. - A state-changing command that times out or returns an ambiguous result may already have taken effect. The Agent does not retry blindly: it queries current state first and asks before another mutation when the intended state remains uncertain.
- An
eventsrequest must include a finite count and per-event timeout so the Agent cannot wait indefinitely. - Exiting the AI client or
gcli, or disconnecting the serial port, is not equivalent to disabling laser output.
The final report should include the selected port, the device serial number when known, the command outcome, and the follow-up query used to confirm state. Command construction, the presence of a receipt, or a zero-looking measurement is not sufficient evidence on its own.