8000 GitHub - xeodou/odelic-cli: ODELIC lights control for AI agents like OpenClaw / OpenClawのようなAIエージェント向けODELIC照明制御 · GitHub
[go: up one dir, main page]

Skip to content

About

ODELIC lights control for AI agents like OpenClaw / OpenClawのようなAIエージェント向けODELIC照明制御

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

13 Commits

Folders and files

Repository files navigation

ODELIC CLI

Local reverse-engineered ODELIC light controller for Raspberry Pi.

The project ships a single self-contained binary:

  • odelic

(An optional libodelic.so shared library can be built with make shlib for external consumers, but the CLI does not require it.)

Platform Support

  • 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 (device scan / onboarding)
  • native L2CAP ATT socket (default BLE transport)

gatttool is only needed if you explicitly select the legacy transport backend (make TRANSPORT=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.

Layout

odelic-cli/
  Makefile
  README.md
  examples/
  include/          public headers, one per module
  skills/           repo-local agent skill
  src/              implementation (see below)
  tests/            unit + CLI smoke tests

Source modules (split by responsibility):

file responsibility
src/main.c CLI arg parsing + command dispatch
src/config.c device profiles (INI load/save/validate/dedupe)
src/state.c per-device state cache (JSON load/save)
src/discovery.c bluetoothctl scan + adv decode + onboarding
src/transport_att.c native L2CAP ATT BLE transport (default)
src/transport_gatttool.c legacy gatttool PTY transport backend
src/bridge.c in-process AES session crypto (login/event keys)
src/session.c login handshake + vaddr discovery + packet send
src/actions.c on/off/set/... packet builders
src/odelic_protocol.c packet encode/decode
src/odelic_aes.c AES-128 ECB
src/util.c shared helpers (hex/time/path/logging/JSON)

src/transport_att.c is the default transport backend; the rest of the code only talks to the odelic_transport.h interface.

Why native ATT and not BlueZ D-Bus? A D-Bus BlueZ backend was prototyped (2026) and works for discovery, Device1.Connect, and GattCharacteristic1.WriteValue, but GattCharacteristic1.StartNotify() returns success without actually enabling the CCCD on ODELIC lights (the CCCD descriptor reads back 0x0000 and no PropertiesChanged notifications arrive). Direct CCCD writes are rejected with org.bluez.Error.NotPermitted. The lights require raw ATT CCCD writes (char-write-req 0x0206 0100), which BlueZ's D-Bus API does not expose. transport_att.c performs those writes directly over an AF_BLUETOOTH L2CAP socket to the ATT fixed channel (CID 4), with no external dependency.

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

  • ../odelic-research

Repo-local agent skills live under:

  • skills/odelic-light-control/

Build

cd <repo-root>
make

This builds:

  • odelic: standalone self-contained C CLI

Useful targets:

make
make TRANSPORT=gatttool   # legacy gatttool subprocess backend
make debug
make check
make dist
make clean
make distclean
make install PREFIX=/usr/local

make dist creates release archives under dist/.

The default BLE transport is a native L2CAP ATT client (transport_att.c). make TRANSPORT=gatttool selects the legacy gatttool PTY backend.

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

Install into a user-local prefix:

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

That installs:

  • $HOME/.local/bin/odelic

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

odelic --help

Linux runtime note:

  • bluetoothctl is needed for scanning and onboarding. The default BLE transport (transport_att.c) needs no external binary. If you build with make TRANSPORT=gatttool, install gatttool and pass a custom path with --gatttool or ODELIC_GATTTOOL.

Multiple Lights

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

How ODELIC Onboarding Works

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.

Using With Codex Or Claude

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

Agent skill sources in this repo:

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.

Use

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

Flags

./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_BLUETOOTHCTL
  • ODELIC_GATTTOOL
  • ODELIC_VERBOSE

Release

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

About

ODELIC lights control for AI agents like OpenClaw / OpenClawのようなAIエージェント向けODELIC照明制御

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0