aukctl is an unofficial, local Bluetooth LE command-line controller for the Auk Mini 2 grow light. It communicates directly with the lamp and does not require an Auk cloud account or expose a network service.
The current release has been validated with:
- Linux and BlueZ
- Auk Mini 2
- observed firmware/software
1.0.0 - observed hardware revision
Rev G - Python 3.10 or newer
Windows and macOS have not been validated. BLE identifiers and host integration differ across operating systems, so they are not currently claimed as supported.
You need a working Bluetooth LE adapter, BlueZ/D-Bus access, physical Bluetooth range to the lamp, and Git for installation from the GitHub URL. Close the official Auk app before scanning or controlling the lamp because it may accept only one BLE connection at a time.
The recommended installation uses uv:
uv tool install git+https://github.com/xraysight/aukctl.git
aukctl --versionIf the command is not on PATH, run uv tool update-shell and open a new shell.
Alternatively, use pipx:
pipx install git+https://github.com/xraysight/aukctl.gitUpdate or remove the tool with the same installer:
uv tool upgrade aukctl
uv tool uninstall aukctlor:
pipx upgrade aukctl
pipx uninstall aukctlClose the official Auk app, then discover nearby devices:
aukctl discover --timeout 20Discovery performs an advertisement-only scan. It does not connect or write to nearby devices. Select the device number and assign a friendly name such as kitchen.
Saved devices are stored in:
~/.config/aukctl/devices.json
XDG_CONFIG_HOME changes the base directory. Every applicable command also accepts --config FILE.
List saved devices:
aukctl devices
aukctl devices --jsonIf one device is saved, it is selected automatically. If several are saved, use its friendly name:
aukctl status --device kitchen
aukctl off --device living-roomA direct address can be used without saved configuration:
aukctl status --address AA:BB:CC:DD:EE:FFaukctl status
aukctl on
aukctl dim
aukctl offstatus connects, requests the current state, waits for an exact state response, and disconnects. State-changing commands (on, dim, and off) additionally reconnect and perform an independent status readback. They report success only when that readback matches the requested state.
Preview a command without connecting or sending anything:
aukctl on --device kitchen --dry-run
aukctl dim --device kitchen --dry-run --jsonThe Auk Mini 2 stores and executes a fixed daily cycle:
- 16 hours on
- 8 hours off
aukctl configures the lamp's native schedule. It does not leave a daemon, cron job, or background process running.
Read the daily light-on time without changing the lamp's clock or schedule:
aukctl schedule get --device kitchen
aukctl schedule get --device kitchen --jsonThis is read-only at the application-protocol level. Like the other response-bearing commands, it temporarily subscribes to the notification characteristic, which writes the BLE Client Characteristic Configuration Descriptor (CCCD), and then disconnects.
Set the daily light-on time with a 24-hour time and an explicit IANA time zone:
aukctl schedule set 07:00 --device kitchen --timezone Europe/WarsawThe host uses the time zone to encode its current local wall clock. The time-zone name is not transmitted to or stored by the lamp. The lamp has no IANA time-zone or daylight-saving rules. Reapply the schedule after a daylight-saving transition or after moving the lamp to another time zone.
The setter performs this fail-stop sequence:
- synchronize the lamp's local wall clock,
- write the daily light-on time,
- read it back and require an exact match,
- disconnect, reconnect, and independently read it back again to verify persistence.
A failure after an earlier confirmed step does not roll that step back.
Preview the exact native BLE commands without connecting:
aukctl schedule get --device kitchen --dry-run
aukctl schedule set 07:00 --device kitchen --timezone Europe/Warsaw --dry-run --jsonCommands that return results support --json:
aukctl status --device kitchen --json
aukctl devices --json
aukctl schedule get --device kitchen --jsonInteractive discovery writes prompts and candidate information to stderr when --json is selected, leaving one JSON object on stdout after a device is saved.
Options belong after the final subcommand, for example:
aukctl status --device kitchen --timeout 20 --json
aukctl schedule get --device kitchen --timeout 20 --jsonThe CLI exposes only tested, explicitly allowlisted operations:
- read the light state,
- select normal, dimmed, or off state,
- read or set the native 16/8 schedule.
It cannot send arbitrary BLE payloads, reset the lamp, update firmware, or change unsupported growing modes.
- Confirm that
systemctl is-active bluetoothreportsactive. - Confirm that
bluetoothctl showlists a powered controller. - Move the host closer to the lamp.
- Close or force-stop the official Auk app.
- Power-cycle the lamp and scan again with a longer timeout.
Another BLE client may own the connection. Close the official app and avoid overlapping aukctl processes. Retry after the lamp is advertising again.
Fix access to BlueZ/D-Bus for the user running aukctl. Do not run permanent automations as root merely to bypass a host permission problem.
Use an IANA identifier such as Europe/Warsaw, not an abbreviation such as CET. The package includes Python time-zone data as a fallback.
See CONTRIBUTING.md for development setup, verification commands, privacy requirements, and compatibility-testing guidelines.
This is an early, independently developed interoperability project for personally owned hardware. It is not affiliated with, endorsed by, or supported by Auk Eco AS. Product names belong to their respective owners.
See CHANGELOG.md, SECURITY.md, and the MIT license.