ODELIC CLI

Local reverse-engineered ODELIC light controller for Raspberry Pi.

The project ships three runtime artifacts:

• odelic
• odelic-bridge
• libodelic.so

• Linux: build, test, onboarding, and live light control are supported.
• macOS: the codebase builds and passes make check, but live Bluetooth control is not implemented yet.

Current runtime BLE support is tied to the Linux BlueZ toolchain:

• bluetoothctl
• gatttool

So the current state is:

• Linux is the supported runtime target.
• macOS is a supported build/test target for protocol and packaging work.
• Full macOS runtime support needs a non-BlueZ backend.

odelic-cli/
  Makefile
  README.md
  examples/
  include/
  skills/
  src/

Older reverse-engineering leftovers and compatibility binaries were moved to:

• ../odelic-research

Repo-local agent skills live under:

• skills/odelic-light-control/

cd <repo-root>
make

This builds:

• odelic: standalone C CLI
• odelic-bridge: pure C session/crypto bridge
• libodelic.so: packet/state helper library

Useful targets:

make
make debug
make check
make dist
make clean
make distclean
make install PREFIX=/usr/local

make dist creates release archives under dist/.

On Linux, runtime control expects BlueZ userland tools to be available. On macOS, make and make check are supported, but live BLE control commands will not work until a macOS Bluetooth backend is added.

Install into a user-local prefix:

cd <repo-root>
make install PREFIX="$HOME/.local"

That installs:

• $HOME/.local/bin/odelic
• $HOME/.local/bin/odelic-bridge
• $HOME/.local/lib/libodelic.so

If ~/.local/bin is on your PATH, the CLI is available as:

odelic --help

Linux runtime note:

• make sure bluetoothctl and gatttool are installed or pass custom paths with --bluetoothctl, --gatttool, ODELIC_BLUETOOTHCTL, or ODELIC_GATTTOOL

Device profiles are loaded from:

~/.config/odelic/devices.conf

or from an override file:

./odelic --device-file /path/to/devices.conf devices

Example config:

[default]
mac = AA:BB:CC:DD:EE:FF
homeid = 34120000
password = 1234

[living-room]
mac = 11:22:33:44:55:66
homeid = 78560000
password = 5678

Reference file:

• examples/devices.conf.example

odelic currently controls lights that are already enrolled in an ODELIC mesh. First-time onboarding still follows ODELIC's controller-assisted flow.

The observed onboarding model is:

1. On an authorized setup, pressing the controller's + button together with warm white exposes the 8-digit user ID.
2. A second Android device can enter that user ID to copy the authorized mesh identity locally.
3. When the app tells you to put the target light into connecting mode, the app provisions it into that mesh and then auto-connects it.

That user ID is not a cloud lookup. In the reverse-engineered Android flow it maps to the mesh credentials used locally for BLE onboarding and control.

For odelic, that means a new light still needs:

• BLE MAC address
• homeid
• password

Once those are known, add the device to devices.conf and control it from the CLI.

You can add devices from the CLI in either of these forms:

./odelic add office AA:BB:CC:DD:EE:FF 12341234
./odelic add --listen-id office
./odelic devices add office AA:BB:CC:DD:EE:FF 12341234
./odelic devices add "Living Room" AA:BB:CC:DD:EE:FF 12341234
./odelic devices add office AA:BB:CC:DD:EE:FF 34120000 1234
./odelic devices add --listen-id office
./odelic devices add --listen-id office auto 60
./odelic devices add --listen-id office AA:BB:CC:DD:EE:FF

If the device name contains spaces, quote it in the shell, for example "Living Room".

--listen-id is the interactive onboarding path. It prompts you to press + and warm white on the controller, captures the share advertisement carrying homeid + password, then prompts you to put the light into connecting mode and auto-detects the light MAC from ODELIC advertisements. The default listen window is 60 seconds. You can still pass a manual MAC to override that step.

The cleanest integration is to let the agent run the local odelic CLI directly.

Agent skill sources in this repo:

• skills/odelic-light-control/SKILL.md

Recommended setup:

1. Install odelic into $HOME/.local/bin.
2. Keep your lights defined in ~/.config/odelic/devices.conf.
3. Tell the agent to use the CLI instead of inventing BLE packets from scratch unless you explicitly want protocol work.

Typical commands an agent can run:

odelic devices
odelic --device "Living Room" status
odelic --device "Living Room" on
odelic --device "Living Room" off
odelic --device "Living Room" set 60 20
odelic add --listen-id "Living Room" auto 60

Prompt examples:

• Use odelic to turn on the Living Room light.
• Use odelic to set Living Room to brightness 60 and color 20.
• Use odelic to read the status of Living Room first, then turn it off.
• Use odelic add --listen-id to onboard a new light called Bedroom.

Install for Codex:

mkdir -p "$HOME/.codex/skills"
ln -s "<repo-root>/skills/odelic-light-control" "$HOME/.codex/skills/odelic-light-control"

If you prefer copies instead of symlinks:

mkdir -p "$HOME/.codex/skills"
cp -R "<repo-root>/skills/odelic-light-control" "$HOME/.codex/skills/"

For Claude or OpenClaw:

• keep the repo checked out locally
• point the agent at the files under skills/
• tell it to read the relevant skill before running odelic
• use the same command examples shown above

The shared idea is the same for all three agents: the skill files provide the operating instructions, and odelic is the command surface that actually controls the light.

cd <repo-root>
./odelic devices
./odelic devices add office AA:BB:CC:DD:EE:FF 12341234
./odelic devices add --listen-id office
./odelic --device default status
./odelic --device office on
./odelic status
./odelic on
./odelic off
./odelic bright-up 5
./odelic bright-down 5
./odelic warmer 5
./odelic cooler 5
./odelic set 20 0

./odelic --help
./odelic --version
./odelic -v status
./odelic -vv status
./odelic --state-file /tmp/odelic-state.json status

Environment overrides:

• ODELIC_DEVICE
• ODELIC_DEVICE_FILE
• ODELIC_STATE_FILE
• ODELIC_BRIDGE_BIN
• ODELIC_BLUETOOTHCTL
• ODELIC_GATTTOOL
• ODELIC_VERBOSE

Local release archives are produced with:

make dist

Current archive layout:

• dist/odelic-<version>-<os>-<arch>.tar.gz
• dist/odelic-<version>-<os>-<arch>.zip

GitHub automation:

• .github/workflows/ci.yml runs make check on Linux and macOS to keep the codebase buildable on both
• .github/workflows/release.yml builds archives on tags matching v* and publishes them to a GitHub release