From 885d24580c55b837070af81e1a26c6d952711890 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Tue, 6 Jan 2026 15:34:42 -0500 Subject: [PATCH 01/16] ci: trigger CI pipeline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 From 86da1dfd24381c99e225480f9dee4d2e8a5e9eb1 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:45:36 -0500 Subject: [PATCH 02/16] feat: add Claude Code plugin manifest for bondhome --- .claude-plugin/plugin.json | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 .claude-plugin/plugin.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..74a368a --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "bondhome", + "description": "Control Bond Home smart devices - ceiling fans, shades, lights, fireplaces - via natural language", + "version": "1.0.0", + "author": { + "name": "Bond Home", + "email": "support@bondhome.io" + }, + "homepage": "https://bondhome.io", + "repository": "https://github.com/bondhome/bond-cli", + "license": "MIT", + "keywords": ["bond", "smart-home", "ceiling-fan", "shades", "automation", "iot"] +} From 68b53bc7ad9eadd9fff26c3076fc5c32f341c135 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:46:29 -0500 Subject: [PATCH 03/16] feat: add bondhome:assistant core skill --- skills/assistant/SKILL.md | 202 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 skills/assistant/SKILL.md diff --git a/skills/assistant/SKILL.md b/skills/assistant/SKILL.md new file mode 100644 index 0000000..3f29e79 --- /dev/null +++ b/skills/assistant/SKILL.md @@ -0,0 +1,202 @@ +--- +name: assistant +description: Control Bond Home smart devices - ceiling fans, shades, lights, fireplaces. Use when user wants to control smart home devices, check device status, turn on/off fans or lights, open/close shades, or adjust device settings. +--- + +# Bond Home Assistant + +Control Bond Home smart devices via the Local API. + +## Quick Reference + +| Operation | Endpoint | Method | +|-----------|----------|--------| +| List devices | `/v2/devices` | GET | +| Device info | `/v2/devices/{id}` | GET | +| Device state | `/v2/devices/{id}/state` | GET | +| Execute action | `/v2/devices/{id}/actions/{action}` | PUT | +| Device properties | `/v2/devices/{id}/properties` | GET | + +## Database Location + +Bond CLI stores discovered Bonds at `~/.bond/db.json`: + +```json +{ + "bonds": { + "BONDID12345": { + "ip": "192.168.1.100", + "port": 80, + "token": "abc123def456" + } + }, + "selected": "BONDID12345" +} +``` + +Read this file to get Bond IPs and tokens. If empty or missing, guide user to run `bond discover`. + +## API Pattern + +All requests (except `/v2/sys/version` and `/v2/token`) require the token header: + +```bash +curl -H "BOND-Token: {token}" http://{ip}:{port}/v2/... +``` + +## Common Operations + +### List All Devices + +```bash +curl -H "BOND-Token: {token}" http://{ip}:{port}/v2/devices +``` + +Response contains device IDs as keys. Fetch each device for details. + +### Get Device Details + +```bash +curl -H "BOND-Token: {token}" http://{ip}:{port}/v2/devices/{device_id} +``` + +Returns: +```json +{ + "name": "Living Room Fan", + "type": "CF", + "location": "Living Room", + "actions": ["TurnOn", "TurnOff", "SetSpeed", ...], + "_": "hash" +} +``` + +### Check Device State + +```bash +curl -H "BOND-Token: {token}" http://{ip}:{port}/v2/devices/{device_id}/state +``` + +Returns current state (power, speed, light, position, etc.). + +### Turn On / Turn Off + +```bash +# Turn on +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}:{port}/v2/devices/{device_id}/actions/TurnOn + +# Turn off +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}:{port}/v2/devices/{device_id}/actions/TurnOff +``` + +### Set Fan Speed + +```bash +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 3}' \ + http://{ip}:{port}/v2/devices/{device_id}/actions/SetSpeed +``` + +Speed is 1 to max_speed (check device properties). + +### Open / Close Shades + +```bash +# Open +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}:{port}/v2/devices/{device_id}/actions/Open + +# Close +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}:{port}/v2/devices/{device_id}/actions/Close + +# Set position (0=open, 100=closed) +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 50}' \ + http://{ip}:{port}/v2/devices/{device_id}/actions/SetPosition +``` + +### Control Lights + +```bash +# Turn light on/off (for fans with lights) +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}:{port}/v2/devices/{device_id}/actions/TurnLightOn + +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}:{port}/v2/devices/{device_id}/actions/TurnLightOff + +# Set brightness (1-100) +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 75}' \ + http://{ip}:{port}/v2/devices/{device_id}/actions/SetBrightness +``` + +## Device Types + +| Code | Type | Common Actions | +|------|------|----------------| +| CF | Ceiling Fan | TurnOn, TurnOff, SetSpeed, TurnLightOn, TurnLightOff | +| MS | Motorized Shades | Open, Close, SetPosition, Hold | +| LT | Light | TurnOn, TurnOff, SetBrightness | +| FP | Fireplace | TurnOn, TurnOff, SetFlame | +| HT | Heater | TurnOn, TurnOff, SetHeat | + +## Device Matching + +When user refers to a device by name or location: + +1. **List all devices** across all known Bonds +2. **Match by name** (case-insensitive, partial match OK) +3. **Match by location** if name doesn't match +4. **Match by type** if user says "fan", "light", "shade" +5. **Ask user** if multiple devices match or none match + +Example: "turn on the bedroom fan" +- Search for devices where `name` or `location` contains "bedroom" +- Filter by `type: "CF"` for fans +- If one match, execute. If multiple, ask which one. + +## Safety Model + +**Liberal for actions:** Execute device controls (TurnOn, SetSpeed, Open, etc.) without confirmation. + +**Careful for destructive operations:** +- Factory reset +- Firmware upgrade +- Deleting devices + +Always confirm these with the user first. + +## Reference Documents + +For advanced operations, see the reference documents in `references/`: + +| Document | Domain | +|----------|--------| +| [discovery-auth.md](references/discovery-auth.md) | mDNS discovery, token retrieval, PIN unlock | +| [actions-fan.md](references/actions-fan.md) | Ceiling fan: breeze, direction, up/down lights | +| [actions-shades.md](references/actions-shades.md) | Shades: position, tilt, TDBU, sheer/blackout | +| [actions-light.md](references/actions-light.md) | Lights: color, colorTemp, RGB, HSV | +| [actions-fireplace.md](references/actions-fireplace.md) | Fireplace/heater: flame, heat, timer | +| [device-types.md](references/device-types.md) | Full type/capability matrix | +| [groups-scenes.md](references/groups-scenes.md) | Multi-device control | +| [schedules.md](references/schedules.md) | Time-based automation | +| [mate-channels.md](references/mate-channels.md) | MT-1500 motor controller | +| [system.md](references/system.md) | Reboot, upgrade, wifi, backup | +| [signals.md](references/signals.md) | RF/IR transmission (Bridge only) | +| [troubleshooting.md](references/troubleshooting.md) | Common errors | + +## Workflow + +1. **Read database** at `~/.bond/db.json` to get Bond IPs and tokens +2. **List devices** on each Bond +3. **Match device** to user's request +4. **Execute action** via PUT to actions endpoint +5. **Verify state** if needed via GET to state endpoint +6. **Report result** to user From 708668e647813576978e404ee961da3d69e5d24e Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:46:58 -0500 Subject: [PATCH 04/16] docs: add discovery and authentication reference --- skills/assistant/references/discovery-auth.md | 210 ++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 skills/assistant/references/discovery-auth.md diff --git a/skills/assistant/references/discovery-auth.md b/skills/assistant/references/discovery-auth.md new file mode 100644 index 0000000..9fffa57 --- /dev/null +++ b/skills/assistant/references/discovery-auth.md @@ -0,0 +1,210 @@ +# Discovery & Authentication + +## mDNS Discovery + +Bond devices advertise via mDNS service type `_bond._tcp.local.`. + +### Using Python (zeroconf) + +```python +from zeroconf import ServiceBrowser, Zeroconf +import socket + +class BondListener: + def add_service(self, zc, type_, name): + info = zc.get_service_info(type_, name) + if info: + ip = socket.inet_ntoa(info.addresses[0]) + bond_id = name.split('.')[0] + print(f"Found Bond: {bond_id} at {ip}:{info.port}") + +zc = Zeroconf() +browser = ServiceBrowser(zc, "_bond._tcp.local.", BondListener()) +# Keep running to discover... +``` + +### Using Command Line + +**macOS:** +```bash +dns-sd -B _bond._tcp . +# Then resolve specific Bond: +dns-sd -L BONDID12345 _bond._tcp . +``` + +**Linux:** +```bash +avahi-browse -a | grep bond +``` + +### Using bond-cli + +```bash +bond discover +``` + +This populates `~/.bond/db.json` with found Bonds. + +## Database Structure + +Bond CLI stores data in `~/.bond/db.json`: + +```json +{ + "bonds": { + "ZZBL12345": { + "ip": "192.168.1.100", + "port": 80, + "token": "f074b61f628018fd", + "name": "Living Room Bridge" + }, + "KSMJWCE12345": { + "ip": "192.168.1.101", + "port": 80, + "token": "a1b2c3d4e5f67890", + "name": "Master Bedroom Fan" + } + }, + "selected": "ZZBL12345" +} +``` + +Key fields: +- `ip`: IP address on local network +- `port`: HTTP port (default 80) +- `token`: Authentication token (16 hex chars) +- `selected`: Currently active Bond for CLI commands + +## Token Retrieval + +Tokens are required for all API endpoints except: +- `GET /v2/sys/version` +- `GET /v2/token` + +### Method 1: Power Cycle Window (10 minutes) + +After power cycling a Bond, the token is accessible for 10 minutes: + +```bash +curl http://{ip}/v2/token +``` + +Response: +```json +{ + "locked": 0, + "token": "f074b61f628018fd", + "pin_attempts_left": 10 +} +``` + +### Method 2: PIN Unlock + +Use the 4-digit PIN from the product label: + +```bash +curl -X PATCH http://{ip}/v2/token \ + -H "Content-Type: application/json" \ + -d '{"pin": "1234"}' +``` + +Response: +```json +{ + "locked": 0, + "token": "f074b61f628018fd" +} +``` + +After retrieving the token, re-lock: + +```bash +curl -X PATCH http://{ip}/v2/token \ + -H "Content-Type: application/json" \ + -d '{"locked": 1}' +``` + +### Method 3: Using bond-cli + +```bash +# Set token manually (if you know it) +bond token --set f074b61f628018fd + +# Unlock with PIN +bond token --unlock 1234 +``` + +## Token Header Format + +All authenticated requests require the `BOND-Token` header: + +```bash +curl -H "BOND-Token: f074b61f628018fd" http://{ip}/v2/devices +``` + +Alternative: Embed token in request body (since v2.6.23): + +```bash +curl http://{ip}/v2/devices -X GET \ + -d '{"_token": "f074b61f628018fd"}' +``` + +## Common Auth Errors + +### 401 Unauthorized + +**Missing token:** +```bash +curl http://{ip}/v2/devices +# Returns 401 +``` +Solution: Add `BOND-Token` header. + +**Invalid token:** +```bash +curl -H "BOND-Token: wrongtoken" http://{ip}/v2/devices +# Returns 401 +``` +Solution: Retrieve correct token via power cycle or PIN unlock. + +### Token Locked + +If `GET /v2/token` returns `"locked": 1`: + +1. Power cycle the Bond and retry within 10 minutes, OR +2. Use PIN unlock with `PATCH /v2/token` + +### PIN Attempts Exhausted + +If `pin_attempts_left` reaches 0, wait 30 minutes or power cycle the Bond. + +## Bond ID Prefixes + +Bond IDs indicate device type: + +| Prefix | Device Type | +|--------|-------------| +| ZZ | Bond Bridge (original) | +| BD | Bond Bridge Pro | +| K | Smart by Bond (SBB) device | + +## Version Check (No Auth Required) + +Always works without token: + +```bash +curl http://{ip}/v2/sys/version +``` + +Response: +```json +{ + "target": "snowbird", + "fw_ver": "v3.0.0", + "make": "Olibra", + "model": "BD1000", + "bondid": "ZZBL12345" +} +``` + +Use this to verify connectivity before attempting authenticated requests. From f1000a43c841573e2cc699221824f118b06ffd88 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:48:51 -0500 Subject: [PATCH 05/16] docs: add ceiling fan actions reference --- skills/assistant/references/actions-fan.md | 300 +++++++++++++++++++++ 1 file changed, 300 insertions(+) create mode 100644 skills/assistant/references/actions-fan.md diff --git a/skills/assistant/references/actions-fan.md b/skills/assistant/references/actions-fan.md new file mode 100644 index 0000000..c47e939 --- /dev/null +++ b/skills/assistant/references/actions-fan.md @@ -0,0 +1,300 @@ +# Ceiling Fan Actions + +Device type: `CF` (Ceiling Fan) + +## Power + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| TurnOn | Turn fan on (resumes previous speed) | None | +| TurnOff | Turn fan off | None | +| TogglePower | Toggle fan on/off | None | + +### State Variables + +- `power`: 1 = on, 0 = off + +### Examples + +```bash +# Turn on +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnOn + +# Turn off +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnOff +``` + +## Speed + +### Properties + +- `max_speed`: Maximum speed number (read-only) + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| SetSpeed | Set fan speed and turn on | 1 to max_speed | +| IncreaseSpeed | Increase speed by N | Number of steps | +| DecreaseSpeed | Decrease speed by N (won't go below 1) | Number of steps | + +### State Variables + +- `speed`: Current speed (1 to max_speed). If power=0, represents last speed. + +### Examples + +```bash +# Set speed to 3 +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 3}' \ + http://{ip}/v2/devices/{id}/actions/SetSpeed + +# Increase speed by 1 +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 1}' \ + http://{ip}/v2/devices/{id}/actions/IncreaseSpeed + +# Check max_speed +curl -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/properties +``` + +## Breeze + +Randomized breeze mode that varies fan speed over time. + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| BreezeOn | Enable breeze with remembered params | None | +| BreezeOff | Disable breeze (fan stays at current speed) | None | +| SetBreeze | Enable breeze with specific params | [mode, mean, var] | + +### State Variables + +- `breeze`: Array `[mode, mean, var]` + - `mode`: 0 = disabled, 1 = enabled + - `mean`: Average speed (0-100, where 0=calm, 100=storm) + - `var`: Variability (0-100, where 0=steady, 100=gusty) + +### Examples + +```bash +# Enable breeze +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/BreezeOn + +# Set custom breeze (mode=1, mean=30, var=80) +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": [1, 30, 80]}' \ + http://{ip}/v2/devices/{id}/actions/SetBreeze + +# Disable breeze +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/BreezeOff +``` + +## Direction + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| SetDirection | Set fan direction | 1 (forward/summer) or -1 (reverse/winter) | +| ToggleDirection | Reverse current direction | None | + +### State Variables + +- `direction`: 1 = forward (summer), -1 = reverse (winter) + +### Examples + +```bash +# Set to reverse (winter mode) +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": -1}' \ + http://{ip}/v2/devices/{id}/actions/SetDirection + +# Toggle direction +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/ToggleDirection +``` + +## Light + +Basic light on/off control for fans with integrated lights. + +### Properties + +- `feature_light`: true/false - whether light feature is enabled + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| TurnLightOn | Turn light on | None | +| TurnLightOff | Turn light off | None | +| ToggleLight | Toggle light on/off | None | + +### State Variables + +- `light`: 1 = on, 0 = off + +### Examples + +```bash +# Turn light on +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnLightOn + +# Turn light off +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnLightOff +``` + +## Up/Down Light + +For fans with separate upward-facing and downward-facing lights. + +### Properties + +- `feature_up_down_light`: true/false - whether up/down light feature is enabled + +### Actions + +| Action | Description | +|--------|-------------| +| TurnUpLightOn | Turn up light on | +| TurnUpLightOff | Turn up light off | +| TurnDownLightOn | Turn down light on | +| TurnDownLightOff | Turn down light off | +| ToggleUpLight | Toggle up light | +| ToggleDownLight | Toggle down light | + +### State Variables + +- `up_light`: 1 = enabled, 0 = disabled +- `down_light`: 1 = enabled, 0 = disabled + +The physical light is on when both `light=1` AND the respective `up_light`/`down_light=1`. + +### Examples + +```bash +# Turn on only down light +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnUpLightOff +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnDownLightOn +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnLightOn +``` + +## Brightness + +For dimmable fan lights. + +### Properties + +- `feature_brightness`: true/false - whether brightness control is available + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| SetBrightness | Set brightness level | 1-100 (percent) | +| IncreaseBrightness | Increase brightness | Amount (percent) | +| DecreaseBrightness | Decrease brightness | Amount (percent) | + +### State Variables + +- `brightness`: 1-100 (percent). If light=0, represents remembered brightness. + +### Examples + +```bash +# Set brightness to 75% +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 75}' \ + http://{ip}/v2/devices/{id}/actions/SetBrightness + +# Increase brightness by 10% +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 10}' \ + http://{ip}/v2/devices/{id}/actions/IncreaseBrightness +``` + +## Up/Down Brightness + +For fans with separately dimmable up and down lights. + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| SetUpLightBrightness | Set up light brightness | 1-100 | +| SetDownLightBrightness | Set down light brightness | 1-100 | +| IncreaseUpLightBrightness | Increase up light brightness | Amount | +| IncreaseDownLightBrightness | Increase down light brightness | Amount | +| DecreaseUpLightBrightness | Decrease up light brightness | Amount | +| DecreaseDownLightBrightness | Decrease down light brightness | Amount | + +### State Variables + +- `up_light_brightness`: 1-100 +- `down_light_brightness`: 1-100 + +## Timer + +Auto-off timer for fans. + +### Properties + +- `default_auto_timer_s`: For heater devices, auto-timer duration in seconds + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| SetTimer | Start timer (turns on if off) | Seconds (0 to cancel) | + +### State Variables + +- `timer`: Seconds remaining, or 0 if no timer + +### Examples + +```bash +# Set 30 minute timer +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 1800}' \ + http://{ip}/v2/devices/{id}/actions/SetTimer + +# Cancel timer +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 0}' \ + http://{ip}/v2/devices/{id}/actions/SetTimer +``` + +## Checking Properties + +To see what features a fan supports: + +```bash +curl -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/properties +``` + +Returns properties like `max_speed`, `feature_light`, `feature_brightness`, etc. From 0cd888eec19b4f215de8deb712c03f99fd24c729 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:50:32 -0500 Subject: [PATCH 06/16] docs: document Claude Code plugin usage --- CLAUDE.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index b8d0688..88c01e2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -74,3 +74,38 @@ Uses `MutableMapping` interface with thread-safe RLock. - Tests run on Python 3.7, 3.8, 3.9 - Releases: bump version in `setup.py`, create annotated git tag (`git tag -a "vX.Y.Z"`), push to trigger PyPI deployment + +## Claude Code Plugin + +This repository is also a Claude Code plugin for natural language control of Bond Home devices. + +### Installation + +``` +/plugin add bondhome/bond-cli +``` + +### Usage + +After installation, use natural language to control devices: + +- "Turn on the bedroom fan" +- "Set living room fan to speed 3" +- "Open the office shades" +- "Turn off all lights" +- "What's the status of my devices?" + +### Skill Structure + +- `skills/assistant/SKILL.md` - Core skill with common operations +- `skills/assistant/references/` - Detailed reference documents for specific domains: + - `discovery-auth.md` - mDNS discovery, token retrieval + - `actions-fan.md` - Ceiling fan actions + - `actions-shades.md` - Motorized shade actions + - `actions-light.md` - Light actions + - `actions-fireplace.md` - Fireplace/heater actions + - `device-types.md` - Device type reference + - `groups-scenes.md` - Multi-device control + - `schedules.md` - Time-based automation + - `system.md` - System operations + - `troubleshooting.md` - Error diagnosis From 557f64d071bcc832983911384d5596530b2dfd04 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:50:47 -0500 Subject: [PATCH 07/16] docs: add schedules reference Co-Authored-By: Claude Opus 4.5 --- skills/assistant/references/schedules.md | 184 +++++++++++++++++++++++ 1 file changed, 184 insertions(+) create mode 100644 skills/assistant/references/schedules.md diff --git a/skills/assistant/references/schedules.md b/skills/assistant/references/schedules.md new file mode 100644 index 0000000..7b36975 --- /dev/null +++ b/skills/assistant/references/schedules.md @@ -0,0 +1,184 @@ +# Bond Schedules (Skeds) API Reference + +## Endpoints + +### Device Schedules +- `GET /v2/devices/{device_id}/skeds` - List all schedules for a device +- `POST /v2/devices/{device_id}/skeds` - Create a new schedule for a device +- `GET /v2/devices/{device_id}/skeds/{sked_id}` - Get a specific schedule +- `PATCH /v2/devices/{device_id}/skeds/{sked_id}` - Modify an existing schedule +- `DELETE /v2/devices/{device_id}/skeds/{sked_id}` - Delete a schedule + +### Group Schedules +- `GET /v2/groups/{group_id}/skeds` - List all schedules for a group +- `POST /v2/groups/{group_id}/skeds` - Create a new schedule for a group + +### Scene Schedules +- `GET /v2/scenes/{scene_id}/skeds` - List all schedules for a scene +- `POST /v2/scenes/{scene_id}/skeds` - Create a new schedule for a scene + +Note: For scenes, the `action` field must not be set (the scene itself defines the action). + +## Schedule Structure + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `action` | string | Yes* | Action to execute (e.g., `TurnOn`, `SetBrightness`). *Not set for scene schedules. | +| `argument` | any | No | Argument for the action, if needed (e.g., brightness level 80) | +| `mark` | string | Yes | Time reference: `midnight`, `sunrise`, `sunset`, `dawn`, `dusk` | +| `seconds` | integer | Yes | Offset from mark in seconds. Negative = before, positive = after. | +| `days_of_week` | array | Yes | 7-element boolean array `[Sun, Mon, Tue, Wed, Thu, Fri, Sat]` | +| `enabled` | boolean | No | Whether schedule is active. Defaults to `true`. | + +### Mark Values + +- **midnight**: `seconds` is time since midnight in local timezone +- **sunrise**: `seconds` is offset from calculated local sunrise +- **sunset**: `seconds` is offset from calculated local sunset +- **dawn**: `seconds` is offset from civil dawn (sun 6 degrees below horizon, before sunrise) +- **dusk**: `seconds` is offset from civil dusk (sun 6 degrees below horizon, after sunset) + +### Days of Week + +Array of 7 booleans: `[Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday]` + +Examples: +- Every day: `[true, true, true, true, true, true, true]` +- Weekdays only: `[false, true, true, true, true, true, false]` +- Weekends only: `[true, false, false, false, false, false, true]` + +## Requirements for Solar Events + +Solar-based marks (`sunrise`, `sunset`, `dawn`, `dusk`) require timezone and location to be configured. + +### Setting Time and Location + +```bash +# Set timezone and grid locator for solar calculations +curl -X PATCH "http://$BOND_IP/v2/sys/time" \ + -H "BOND-Token: $TOKEN" \ + -d '{"tz": "America/New_York", "grid": "FN31pr"}' +``` + +The `grid` field uses the Maidenhead Locator System (ham radio grid squares) for latitude/longitude. + +### Error Conditions + +A 400 error will result if: +- `mark` is `midnight` but `sys/time.tz` is `null` +- `mark` is `dawn`, `dusk`, `sunrise`, or `sunset` but `sys/time.grid` or `sys/time.tz` is `null` + +## One-Shot Schedules + +Setting all `days_of_week` to `false` creates a one-shot schedule that: +1. Executes exactly once at the next occurrence +2. Automatically sets `enabled` to `false` after executing + +This is useful for "run once" operations like delayed actions. + +## Curl Examples + +### List Schedules for a Device + +```bash +curl "http://$BOND_IP/v2/devices/$DEVICE_ID/skeds" \ + -H "BOND-Token: $TOKEN" +``` + +### Create a Schedule (Turn on at sunset) + +```bash +curl -X POST "http://$BOND_IP/v2/devices/$DEVICE_ID/skeds" \ + -H "BOND-Token: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "action": "TurnOn", + "mark": "sunset", + "seconds": 0, + "days_of_week": [true, true, true, true, true, true, true] + }' +``` + +### Create a Schedule (Turn off at 11 PM) + +```bash +# 11 PM = 23 * 3600 = 82800 seconds after midnight +curl -X POST "http://$BOND_IP/v2/devices/$DEVICE_ID/skeds" \ + -H "BOND-Token: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "action": "TurnOff", + "mark": "midnight", + "seconds": 82800, + "days_of_week": [true, true, true, true, true, true, true] + }' +``` + +### Create a Schedule (Dim to 50% at dusk, weekdays only) + +```bash +curl -X POST "http://$BOND_IP/v2/devices/$DEVICE_ID/skeds" \ + -H "BOND-Token: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "action": "SetBrightness", + "argument": 50, + "mark": "dusk", + "seconds": 0, + "days_of_week": [false, true, true, true, true, true, false] + }' +``` + +### Create a One-Shot Schedule (Turn on in 30 minutes) + +```bash +# Calculate seconds from current time to desired time +# For a one-shot, you need to calculate seconds from midnight to desired time +curl -X POST "http://$BOND_IP/v2/devices/$DEVICE_ID/skeds" \ + -H "BOND-Token: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "action": "TurnOn", + "mark": "midnight", + "seconds": 54000, + "days_of_week": [false, false, false, false, false, false, false] + }' +``` + +### Get a Specific Schedule + +```bash +curl "http://$BOND_IP/v2/devices/$DEVICE_ID/skeds/$SKED_ID" \ + -H "BOND-Token: $TOKEN" +``` + +### Update a Schedule (Disable it) + +```bash +curl -X PATCH "http://$BOND_IP/v2/devices/$DEVICE_ID/skeds/$SKED_ID" \ + -H "BOND-Token: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"enabled": false}' +``` + +### Update a Schedule (Change time to 30 minutes before sunset) + +```bash +curl -X PATCH "http://$BOND_IP/v2/devices/$DEVICE_ID/skeds/$SKED_ID" \ + -H "BOND-Token: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"seconds": -1800}' +``` + +### Delete a Schedule + +```bash +curl -X DELETE "http://$BOND_IP/v2/devices/$DEVICE_ID/skeds/$SKED_ID" \ + -H "BOND-Token: $TOKEN" +``` + +## Notes + +- Arctic Circle users: Solar-based schedules may not execute during periods around the solstices when sunrise/sunset do not occur. +- Schedule list responses use hash trees for efficient synchronization (see Hash Tree documentation). +- For Channel schedules (MT-1500), common actions include: `Raise`, `Lower`, `Stop`, `SetPosition`, `Preset`, `TurnLightOn`, `TurnLightOff`, `SetBrightness`. Note that `Open`/`Close` are not available for channel schedules. From b1e2ba3b17ea32b922cea5b911b29c743911910b Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:50:48 -0500 Subject: [PATCH 08/16] docs: add fireplace and heater actions reference Co-Authored-By: Claude Opus 4.5 --- .../assistant/references/actions-fireplace.md | 221 ++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 skills/assistant/references/actions-fireplace.md diff --git a/skills/assistant/references/actions-fireplace.md b/skills/assistant/references/actions-fireplace.md new file mode 100644 index 0000000..3e27318 --- /dev/null +++ b/skills/assistant/references/actions-fireplace.md @@ -0,0 +1,221 @@ +# Fireplace and Heater Actions + +Device types: `FP` (Fireplace), `HT` (Heater) + +## Power + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| TurnOn | Turn device on (resumes previous flame/heat level) | None | +| TurnOff | Turn device off | None | +| TogglePower | Toggle device on/off | None | + +### State Variables + +- `power`: 1 = on, 0 = off + +### Examples + +```bash +# Turn on +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnOn + +# Turn off +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnOff +``` + +## Flame + +Controls the flame level for fireplaces. + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| SetFlame | Set flame level and turn on | 1-100 | +| IncreaseFlame | Increase flame level | Amount | +| DecreaseFlame | Decrease flame level (won't go below 1) | Amount | + +### State Variables + +- `flame`: 1-100. If power=0, represents last flame setting. + +### Examples + +```bash +# Set flame to 75% +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 75}' \ + http://{ip}/v2/devices/{id}/actions/SetFlame + +# Increase flame by 10 +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 10}' \ + http://{ip}/v2/devices/{id}/actions/IncreaseFlame + +# Decrease flame by 10 +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 10}' \ + http://{ip}/v2/devices/{id}/actions/DecreaseFlame +``` + +## Heat + +Controls the heat level for heaters and some fireplaces. + +### Properties + +- `feature_heat`: true/false - whether heat control is enabled (PATCH-able) + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| SetHeat | Set heat level and turn on | 1-100 | +| IncreaseHeat | Increase heat level | Amount | +| DecreaseHeat | Decrease heat level (won't go below 1) | Amount | +| HeatPresetNext | Jump to next preset heat value | None | +| HeatPresetPrev | Jump to previous preset heat value | None | + +### State Variables + +- `heat`: 1-100. If power=0, represents last heat setting. + +### Examples + +```bash +# Set heat to 50% +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 50}' \ + http://{ip}/v2/devices/{id}/actions/SetHeat + +# Increase heat by 20 +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 20}' \ + http://{ip}/v2/devices/{id}/actions/IncreaseHeat + +# Decrease heat by 20 +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 20}' \ + http://{ip}/v2/devices/{id}/actions/DecreaseHeat + +# Cycle to next preset +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/HeatPresetNext + +# Cycle to previous preset +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/HeatPresetPrev +``` + +## Fireplace Fan (FpFan) + +Controls a fireplace's built-in fan. This is independent of the Power feature (which controls the flame). + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| TurnFpFanOn | Turn fireplace fan on (restores previous speed) | None | +| TurnFpFanOff | Turn fireplace fan off | None | +| SetFpFan | Set fireplace fan speed | 1-100 | + +### State Variables + +- `fpfan_power`: 1 = on, 0 = off +- `fpfan_speed`: 1-100 + +### Examples + +```bash +# Turn fireplace fan on +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnFpFanOn + +# Turn fireplace fan off +curl -X PUT -H "BOND-Token: {token}" \ + http://{ip}/v2/devices/{id}/actions/TurnFpFanOff + +# Set fireplace fan speed to 60% +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 60}' \ + http://{ip}/v2/devices/{id}/actions/SetFpFan +``` + +## Timer + +Auto-off timer for fireplaces and heaters. + +### Properties + +- `default_auto_timer_s`: (Heaters only) Auto-timer duration in seconds. When present, the timer starts automatically whenever Power is activated and resets on any state-changing action. The timer cannot exceed this value. This ensures fire code compliance (commonly 2 hours for heaters). + +### Actions + +| Action | Description | Argument | +|--------|-------------|----------| +| SetTimer | Start timer (turns on if off) | Seconds (0 to cancel) | + +### State Variables + +- `timer`: Seconds remaining, or 0 if no timer + +### Examples + +```bash +# Set 1 hour timer +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 3600}' \ + http://{ip}/v2/devices/{id}/actions/SetTimer + +# Set 30 minute timer +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 1800}' \ + http://{ip}/v2/devices/{id}/actions/SetTimer + +# Cancel timer (device stays on) +curl -X PUT -H "BOND-Token: {token}" \ + -H "Content-Type: application/json" \ + -d '{"argument": 0}' \ + http://{ip}/v2/devices/{id}/actions/SetTimer +``` + +### Timer Notes + +- Timer is canceled by most Power/Speed actions (except TurnOn) +- When timer reaches zero, device turns off automatically +- For heaters with `default_auto_timer_s`, the timer auto-starts on power-on and resets on any state change + +## Checking Properties + +To see what features a fireplace or heater supports: + +```bash +curl -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/properties +``` + +Returns properties like `feature_heat`, `default_auto_timer_s`, etc. + +## State Variables Summary + +| Variable | Description | +|----------|-------------| +| `power` | 1 = on, 0 = off | +| `flame` | Flame level 1-100 (Fireplace) | +| `heat` | Heat level 1-100 (Heater) | +| `fpfan_power` | Fireplace fan: 1 = on, 0 = off | +| `fpfan_speed` | Fireplace fan speed 1-100 | +| `timer` | Seconds remaining on timer, 0 = no timer | From a7c990ca4c63efe439310c693e05ee8d19d080cc Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:50:48 -0500 Subject: [PATCH 09/16] docs: add RF/IR signals reference --- skills/assistant/references/signals.md | 169 +++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 skills/assistant/references/signals.md diff --git a/skills/assistant/references/signals.md b/skills/assistant/references/signals.md new file mode 100644 index 0000000..3b3cd78 --- /dev/null +++ b/skills/assistant/references/signals.md @@ -0,0 +1,169 @@ +# RF/IR Signals Reference + +> **Bridge-only feature**: Signal transmission and scanning are only available on Bond Bridge devices. + +> **Note**: This is advanced/developer territory. Most users will not need to interact with signals directly. + +## Signal Schema + +A signal object contains the following fields: + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `freq` | number | Yes | Frequency in kHz | +| `modulation` | string | No | `OOK` (on-off keying) or `GFSK` (gaussian frequency-shift keying). Default: `OOK` | +| `encoding` | string | Yes | Data encoding: `cq` or `hex` | +| `bps` | number | Yes | Bitrate (100-40000) | +| `data` | string | Yes | Encoded signal data (max 6144 bytes) | +| `reps` | number | No | Number of repetitions. Default: `1` | + +## Frequency + +The `freq` field determines whether the signal is RF or IR: + +- **RF**: `freq >= 1000` (e.g., `434000` for 434 MHz, `350000` for 350 MHz) +- **IR**: `freq < 1000` (e.g., `38` for 38 kHz infrared) + +Bond Bridge receives and transmits IR signals at 38 kHz. + +## Encoding Types + +### CQ Encoding (`"cq"`) + +A simple encoding where bits are represented using characters: + +- `0` - single zero bit +- `1` - single one bit +- `C` through `Q` - 2^0 (1) through 2^14 (16384) zero bits +- `c` through `q` - 2^0 (1) through 2^14 (16384) one bits +- `A` - the three bits `110` +- `B` - the three bits `011` + +### Hex Encoding (`"hex"`) + +Each hex byte represents 8 bits of data. Currently limited to 40000 bps only. + +This is the default encoding for scan results. + +## API Endpoints + +### Transmit a Signal + +```bash +curl -X PUT "http:///v2/signal/tx" \ + -H "BOND-Token: " \ + -H "Content-Type: application/json" \ + -d '{ + "freq": 434000, + "modulation": "OOK", + "encoding": "cq", + "bps": 1000, + "data": "110100110110H", + "reps": 12 + }' +``` + +### Scan for Signals + +Start a scan on a specific frequency: + +```bash +curl -X PUT "http:///v2/signal/scan" \ + -H "BOND-Token: " \ + -H "Content-Type: application/json" \ + -d '{"freq": 434000}' +``` + +To scan IR instead: + +```bash +curl -X PUT "http:///v2/signal/scan" \ + -H "BOND-Token: " \ + -H "Content-Type: application/json" \ + -d '{"freq": 38}' +``` + +### Get Scan Result + +Retrieve the signal captured by the most recent scan: + +```bash +curl -X GET "http:///v2/signal/scan/signal" \ + -H "BOND-Token: " +``` + +### Transmit Last Scanned Signal + +Transmit the signal that was just scanned: + +```bash +curl -X PUT "http:///v2/signal/tx" \ + -H "BOND-Token: " \ + -H "Content-Type: application/json" \ + -d '{"use_scan": true}' +``` + +### Cancel Transmission + +```bash +curl -X DELETE "http:///v2/signal/tx" \ + -H "BOND-Token: " +``` + +## Command Signals + +Signals can be associated with device commands. + +### Get Command Signal + +```bash +curl -X GET "http:///v2/devices//commands//signal" \ + -H "BOND-Token: " +``` + +### Set Command Signal + +```bash +curl -X PUT "http:///v2/devices//commands//signal" \ + -H "BOND-Token: " \ + -H "Content-Type: application/json" \ + -d '{ + "freq": 434000, + "encoding": "cq", + "bps": 1000, + "data": "110100110110H" + }' +``` + +### Transmit Command Signal + +Transmit the signal associated with a command (does not execute the action or update device state): + +```bash +curl -X PUT "http:///v2/devices//commands//tx" \ + -H "BOND-Token: " \ + -H "Content-Type: application/json" \ + -d '{}' +``` + +## RSSI Sweep + +Get Receive Signal Strength Indication across the frequency range (useful for antenna tuning): + +```bash +curl -X GET "http:///v2/signal/rssi" \ + -H "BOND-Token: " +``` + +Response format: + +```json +{ + "format": ["freq", "rssi"], + "results": [ + [350000, 80], + [351000, 87], + [352000, 92] + ] +} +``` From 031df675c9c83bd2aaff026a8834684c8af9925d Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:50:51 -0500 Subject: [PATCH 10/16] docs: add motorized shades actions reference Co-Authored-By: Claude Opus 4.5 --- skills/assistant/references/actions-shades.md | 304 ++++++++++++++++++ 1 file changed, 304 insertions(+) create mode 100644 skills/assistant/references/actions-shades.md diff --git a/skills/assistant/references/actions-shades.md b/skills/assistant/references/actions-shades.md new file mode 100644 index 0000000..a2d3e25 --- /dev/null +++ b/skills/assistant/references/actions-shades.md @@ -0,0 +1,304 @@ +# Motorized Shades Actions Reference + +## Device Type + +- **Type**: `MS` (Motorized Shades) +- **Subtypes**: `ROLLER`, `SHEER`, `AWNING` + +## Features Overview + +Motorized shades can support various combinations of the following features: +- **Open**: Basic open/close control +- **Position**: Percentage-based positioning (0=open, 100=closed) +- **Hold**: Stop motion mid-travel +- **Preset**: Go to saved favorite position +- **TiltPosition**: Tilt control for venetian blinds +- **TDBU**: Top-Down Bottom-Up dual rail control +- **SheerBlackoutDuo**: Dual-layer sheer and blackout fabric control + +--- + +## Open/Close Feature + +Basic open and close control for motorized shades. + +### State Variables + +| Variable | Type | Description | +|----------|------|-------------| +| `open` | integer | 1 = open, 0 = closed | + +### Actions + +#### Open +Open the shade completely. + +```bash +curl -X PUT -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/actions/Open +``` + +#### Close +Close the shade completely. + +```bash +curl -X PUT -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/actions/Close +``` + +#### ToggleOpen +Toggle between open and closed states. + +```bash +curl -X PUT -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/actions/ToggleOpen +``` + +--- + +## Position Feature + +Percentage-based position control. Requires the Open feature. + +### Properties + +| Property | Type | Description | +|----------|------|-------------| +| `feature_position` | boolean | Enable/disable position feature (PATCH-able) | +| `course_time` | integer | Time in milliseconds for full open/close travel. Required for dead-reckoning position on shades without native position support. Defaults to -1 (unconfigured). | + +### State Variables + +| Variable | Type | Description | +|----------|------|-------------| +| `position` | integer | 0 = fully open, 100 = fully closed | + +### Actions + +#### SetPosition +Set shade to a specific position percentage. + +```bash +curl -X PUT -H "BOND-Token: {token}" \ + -d '{"argument": 50}' \ + http://{ip}/v2/devices/{id}/actions/SetPosition +``` + +#### IncreasePosition +Close the shade by a specified percentage of the full range. + +```bash +curl -X PUT -H "BOND-Token: {token}" \ + -d '{"argument": 10}' \ + http://{ip}/v2/devices/{id}/actions/IncreasePosition +``` + +#### DecreasePosition +Open the shade by a specified percentage of the full range. + +```bash +curl -X PUT -H "BOND-Token: {token}" \ + -d '{"argument": 10}' \ + http://{ip}/v2/devices/{id}/actions/DecreasePosition +``` + +--- + +## Hold Feature + +Stop shade motion mid-travel. + +### Actions + +#### Hold +Stop the motion of the shade. The shade will be in an unknown position state and will show as open. + +**Note**: For Somfy RTS shades, the same command is used for both Hold and Preset (My), so calling Hold while the shade is not moving will send it to the preset position instead. + +```bash +curl -X PUT -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/actions/Hold +``` + +--- + +## Preset Feature + +Move shade to a saved favorite position. + +### Actions + +#### Preset +Move the shade to the preset position (also known as "My" or "Favorite" position). + +**Note**: Bond Bridge does not know the percentage of the preset position, so position will report as -1 (unknown) after this action unless the shade has two-way communication. + +```bash +curl -X PUT -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/actions/Preset +``` + +--- + +## TiltPosition Feature + +Tilt control for venetian blinds and similar slat-based shades. + +### Properties + +| Property | Type | Description | +|----------|------|-------------| +| `min_tilt` | integer | Minimum tilt position in degrees (default 0). Traditional wooden blinds tilt approximately 180 degrees (-90 to 90), with 0 being horizontal. | +| `max_tilt` | integer | Maximum tilt position in degrees (default 90). | + +### State Variables + +| Variable | Type | Description | +|----------|------|-------------| +| `tilt_position` | integer | Angle of slats in degrees | + +### Actions + +#### SetTiltPosition +Set slats to a specific tilt position in degrees. + +```bash +curl -X PUT -H "BOND-Token: {token}" \ + -d '{"argument": 45}' \ + http://{ip}/v2/devices/{id}/actions/SetTiltPosition +``` + +#### ToggleTilt +Toggle slats between open and closed positions. + +```bash +curl -X PUT -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/actions/ToggleTilt +``` + +--- + +## TDBU Feature (Top-Down Bottom-Up) + +Dual rail control for top-down bottom-up shades. Requires the Position feature. + +### State Variables + +| Variable | Type | Description | +|----------|------|-------------| +| `upper_rail_position` | integer | 0 = open (at top), 100 = closed (lowered) | +| `lower_rail_position` | integer | 0 = open (raised), 100 = closed (at bottom) | + +### Actions + +#### SetUpperRailPosition +Set the position of the upper rail (top-down). + +```bash +curl -X PUT -H "BOND-Token: {token}" \ + -d '{"argument": 30}' \ + http://{ip}/v2/devices/{id}/actions/SetUpperRailPosition +``` + +#### SetLowerRailPosition +Set the position of the lower rail (bottom-up). + +```bash +curl -X PUT -H "BOND-Token: {token}" \ + -d '{"argument": 70}' \ + http://{ip}/v2/devices/{id}/actions/SetLowerRailPosition +``` + +### Notes + +- The `SetPosition` action sets the upper rail to 0% and the lower rail to the requested position. +- If an action requests a position that would cause the rails to cross, the other rail is automatically adjusted to the minimum distance necessary. For example, if upper rail is at 50% and lower rail is at 75%, requesting upper rail at 80% will "push" the lower rail to 80% as well. +- To change both rails, call both actions in any order. Rail motions may be slightly staggered. + +--- + +## SheerBlackoutDuo Feature + +Dual-layer control for shades with both sheer and blackout fabric layers. + +### State Variables + +| Variable | Type | Description | +|----------|------|-------------| +| `blackout_position` | integer | 0 = open, 100 = closed | +| `sheer_position` | integer | 0 = open, 100 = closed | + +### Actions + +#### SetBlackoutPosition +Set the position of the blackout (opaque) layer. + +```bash +curl -X PUT -H "BOND-Token: {token}" \ + -d '{"argument": 100}' \ + http://{ip}/v2/devices/{id}/actions/SetBlackoutPosition +``` + +#### SetSheerPosition +Set the position of the sheer (translucent) layer. + +```bash +curl -X PUT -H "BOND-Token: {token}" \ + -d '{"argument": 50}' \ + http://{ip}/v2/devices/{id}/actions/SetSheerPosition +``` + +### Notes + +- The `SetPosition` action sets the sheer layer to the requested position and the blackout layer to 0%. +- The two layers can often be positioned independently, but there may be constraints such as: + - The blackout layer cannot be positioned below the sheer layer + - The sheer layer must be fully extended before the blackout layer can extend +- These constraints are enforced by Bond Bridge automatically. If an impossible position is requested, the other layer is adjusted to the minimum necessary. +- To change both layers, call both actions in any order. Layer motions may be slightly staggered. + +--- + +## State Variables Summary + +| Variable | Feature | Type | Description | +|----------|---------|------|-------------| +| `open` | Open | integer | 1 = open, 0 = closed | +| `position` | Position | integer | 0 = open, 100 = closed | +| `tilt_position` | TiltPosition | integer | Angle in degrees | +| `upper_rail_position` | TDBU | integer | 0 = open, 100 = closed | +| `lower_rail_position` | TDBU | integer | 0 = open, 100 = closed | +| `blackout_position` | SheerBlackoutDuo | integer | 0 = open, 100 = closed | +| `sheer_position` | SheerBlackoutDuo | integer | 0 = open, 100 = closed | + +--- + +## Properties Summary + +| Property | Feature | Type | Description | +|----------|---------|------|-------------| +| `feature_position` | Position | boolean | Enable/disable position feature | +| `course_time` | CourseTime | integer | Travel time in ms for dead-reckoning | +| `min_tilt` | TiltPosition | integer | Minimum tilt angle (default 0) | +| `max_tilt` | TiltPosition | integer | Maximum tilt angle (default 90) | + +--- + +## Pairing Actions + +Most shade devices use pairing rather than remote cloning. + +### Pair +Pair the Bond Bridge with a shade motor. Requires manually putting the shade into pairing mode first. + +```bash +curl -X PUT -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/actions/Pair +``` + +### Unpair +Unpair the Bond Bridge from a shade motor. Requires manually putting the shade into pairing mode first. + +```bash +curl -X PUT -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/actions/Unpair +``` + +### UnpairSelf +Unpair the Bond Bridge from all shades in range. Does not require pairing mode. + +```bash +curl -X PUT -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/actions/UnpairSelf +``` From ade5151c88b2f0391f40013982544ab7ef06fb91 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:50:57 -0500 Subject: [PATCH 11/16] docs: add light actions reference Co-Authored-By: Claude Opus 4.5 --- skills/assistant/references/actions-light.md | 247 +++++++++++++++++++ 1 file changed, 247 insertions(+) create mode 100644 skills/assistant/references/actions-light.md diff --git a/skills/assistant/references/actions-light.md b/skills/assistant/references/actions-light.md new file mode 100644 index 0000000..cbd50c9 --- /dev/null +++ b/skills/assistant/references/actions-light.md @@ -0,0 +1,247 @@ +# Light Actions Reference + +Device type: `LT` (Light) + +This document covers standalone light devices. For fan lights (using TurnLightOn, TurnLightOff, etc.), see `actions-fan.md`. + +## Power Feature + +Controls the basic on/off state of the light. + +### State Variables + +- **power**: (integer) 1 = on, 0 = off + +### Actions + +| Action | Description | +|--------|-------------| +| TurnOn | Turn the light on | +| TurnOff | Turn the light off | +| TogglePower | Toggle power state (on to off, or off to on) | + +### Curl Examples + +```bash +# Turn on +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + http://{ip}/v2/devices/{id}/actions/TurnOn + +# Turn off +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + http://{ip}/v2/devices/{id}/actions/TurnOff + +# Toggle power +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + http://{ip}/v2/devices/{id}/actions/TogglePower +``` + +## Brightness Feature + +Controls dimmable lights with adjustable brightness levels. + +### State Variables + +- **brightness**: (integer) Percentage value 1-100. When light is off, represents the last brightness setting and the brightness to resume when turned on. + +### Actions + +| Action | Argument | Description | +|--------|----------|-------------| +| SetBrightness | 1-100 | Set brightness to specified percentage. Value of 0 is ignored; use TurnOff instead. | +| IncreaseBrightness | amount | Increase brightness by specified percentage. Turns on light if off. | +| DecreaseBrightness | amount | Decrease brightness by specified percentage. Minimum is 1%. Light remains off if already off. | + +### Curl Examples + +```bash +# Set brightness to 75% +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": 75}' \ + http://{ip}/v2/devices/{id}/actions/SetBrightness + +# Increase brightness by 10% +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": 10}' \ + http://{ip}/v2/devices/{id}/actions/IncreaseBrightness + +# Decrease brightness by 10% +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": 10}' \ + http://{ip}/v2/devices/{id}/actions/DecreaseBrightness +``` + +## ColorTemp Feature + +Controls correlated color temperature (CCT) of lights that support it. + +Color temperature works in 100 Kelvin (K) steps. Non-multiples of 100 K will be rounded. + +### Properties + +- **min_color_temp**: (integer) Minimum color temperature in Kelvin +- **max_color_temp**: (integer) Maximum color temperature in Kelvin + +### State Variables + +- **color_temp**: (integer) Color temperature in Kelvin (resolution: 100 K) + +### Actions + +| Action | Argument | Description | +|--------|----------|-------------| +| SetColorTemp | Kelvin value | Set color temperature. Implicitly turns light on. | +| IncreaseColorTemp | degrees K | Increase color temperature by specified degrees. Implicitly turns light on. | +| DecreaseColorTemp | degrees K | Decrease color temperature by specified degrees. Implicitly turns light on. | + +### Curl Examples + +```bash +# Set color temperature to 4000K (neutral white) +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": 4000}' \ + http://{ip}/v2/devices/{id}/actions/SetColorTemp + +# Increase color temperature by 500K (cooler/bluer) +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": 500}' \ + http://{ip}/v2/devices/{id}/actions/IncreaseColorTemp + +# Decrease color temperature by 500K (warmer/yellower) +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": 500}' \ + http://{ip}/v2/devices/{id}/actions/DecreaseColorTemp +``` + +## Color Feature (RGB) + +Controls full color lighting products using RGB color space. + +### State Variables + +- **rgb**: (object) Apparent color with keys: + - `r`: (0-255) Red value + - `g`: (0-255) Green value + - `b`: (0-255) Blue value + +### Actions + +| Action | Argument | Description | +|--------|----------|-------------| +| SetRGB | {r, g, b} | Set color by RGB values (0-255 each). Partial specification allowed. Implicitly turns light on. | + +### Curl Examples + +```bash +# Set color to red +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": {"r": 255, "g": 0, "b": 0}}' \ + http://{ip}/v2/devices/{id}/actions/SetRGB + +# Set color to purple +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": {"r": 128, "g": 0, "b": 255}}' \ + http://{ip}/v2/devices/{id}/actions/SetRGB + +# Adjust only red channel (leaves g and b unchanged) +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": {"r": 200}}' \ + http://{ip}/v2/devices/{id}/actions/SetRGB +``` + +## Color Feature (HSV) + +Controls full color lighting products using HSV color space. + +### State Variables + +- **hsv**: (object) Apparent color with keys: + - `h`: (0-359) Hue in degrees + - `s`: (0-100) Saturation percentage + - `v`: (0-100) Value/brightness percentage (same as `brightness` state variable) + +### Actions + +| Action | Argument | Description | +|--------|----------|-------------| +| SetHSV | {h, s, v} | Set color by HSV values. Partial specification allowed. Implicitly turns light on. | + +### Curl Examples + +```bash +# Set to fully saturated blue (hue 240) +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": {"h": 240, "s": 100, "v": 100}}' \ + http://{ip}/v2/devices/{id}/actions/SetHSV + +# Set hue and saturation only (leave brightness unchanged) +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": {"h": 120, "s": 80}}' \ + http://{ip}/v2/devices/{id}/actions/SetHSV + +# Set hue only (for color wheel interface) +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": {"h": 60}}' \ + http://{ip}/v2/devices/{id}/actions/SetHSV +``` + +## RGBW Feature + +For lights with four-channel LEDs (separate white channel). + +When saturation (S) is zero, only the W channel is used. When S is non-zero, only RGB channels are used. + +### State Variables + +- **rgbw**: (object) Low-level LED channel values: + - `r`: (0-255) Red channel + - `g`: (0-255) Green channel + - `b`: (0-255) Blue channel + - `w`: (0-255) White channel + +### Actions + +| Action | Argument | Description | +|--------|----------|-------------| +| SetRGBW | {r, g, b, w} | Set low-level LED channel values (0-255 each). Allows combinations unreachable with SetRGB. Implicitly turns light on. | + +### Curl Examples + +```bash +# Set warm white only +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": {"r": 0, "g": 0, "b": 0, "w": 255}}' \ + http://{ip}/v2/devices/{id}/actions/SetRGBW + +# Mix red with white for warm red +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": {"r": 200, "g": 0, "b": 0, "w": 100}}' \ + http://{ip}/v2/devices/{id}/actions/SetRGBW + +# Full RGBW combination +curl -X PUT -H "BOND-Token: {token}" -H "Content-Type: application/json" \ + -d '{"argument": {"r": 100, "g": 50, "b": 150, "w": 75}}' \ + http://{ip}/v2/devices/{id}/actions/SetRGBW +``` + +## Reading Device State + +To read the current state of any light: + +```bash +curl -H "BOND-Token: {token}" http://{ip}/v2/devices/{id}/state +``` + +Example response for an RGBW light: + +```json +{ + "power": 1, + "brightness": 75, + "color_temp": 4000, + "rgb": {"r": 255, "g": 200, "b": 150}, + "hsv": {"h": 30, "s": 41, "v": 100}, + "rgbw": {"r": 255, "g": 200, "b": 150, "w": 0}, + "_": "abcd1234" +} +``` From 05d99fe6f92237d3a5727ba574d7ffbef9c63f64 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:50:58 -0500 Subject: [PATCH 12/16] docs: add device types reference Co-Authored-By: Claude Opus 4.5 --- skills/assistant/references/device-types.md | 232 ++++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 skills/assistant/references/device-types.md diff --git a/skills/assistant/references/device-types.md b/skills/assistant/references/device-types.md new file mode 100644 index 0000000..513a95e --- /dev/null +++ b/skills/assistant/references/device-types.md @@ -0,0 +1,232 @@ +# Bond Device Types Reference + +## Device Type Codes + +| Code | Name | Description | +|------|------|-------------| +| `CF` | Ceiling Fan | Multi-speed ceiling fans with optional light and direction control | +| `MS` | Motorized Shades | Motorized window coverings including shades, screens, drapes, and awnings | +| `LT` | Light | Standalone lighting devices | +| `FP` | Fireplace | Gas or electric fireplaces with flame control | +| `BD` | Bidet | Smart bidet devices | +| `GX` | Generic | Generic device type for devices that don't fit other categories | +| `HT` | Heater | Heating devices with heat level control | + +The `type` field does not impact device functionality. It is used by API clients to improve user experience (e.g., selecting appropriate icons) and by integrations to determine device categories for platforms like Google Assistant or Alexa. + +## Subtypes + +### Motorized Shades (MS) Subtypes + +| Subtype | Description | +|---------|-------------| +| `ROLLER` | Roller blackout shade which blocks light and provides privacy | +| `SHEER` | Shade which permits light to pass and does not provide privacy | +| `AWNING` | Outdoor patio covering | + +**Note:** The `subtype` field is for analytics and aesthetics only. New subtypes may be introduced without notice. API clients should always fall back to a reasonable default based on the device `type`. + +## Capabilities Matrix + +| Feature | CF | MS | LT | FP | BD | GX | HT | +|---------|----|----|----|----|----|----|-----| +| Power | Yes | - | Yes | Yes | Yes | Yes | Yes | +| Speed | Yes | - | - | - | - | - | - | +| Breeze | Yes | - | - | - | - | - | - | +| Direction | Yes | - | - | - | - | - | - | +| Light | Yes | - | Yes | Yes | - | - | - | +| Brightness | Yes | - | Yes | Yes | - | - | - | +| UpDownLight | Yes | - | - | - | - | - | - | +| ColorTemp | - | - | Yes | - | - | - | - | +| Color (RGB) | - | - | Yes | - | - | - | - | +| Open | - | Yes | - | - | - | - | - | +| Position | - | Yes | - | - | - | - | - | +| TiltPosition | - | Yes | - | - | - | - | - | +| TDBU | - | Yes | - | - | - | - | - | +| Flame | - | - | - | Yes | - | - | - | +| FpFan | - | - | - | Yes | - | - | - | +| Heat | - | - | - | - | - | - | Yes | +| Timer | Yes | - | - | - | - | - | Yes | +| Pair | - | Yes | - | - | - | - | - | +| Hold | - | Yes | - | - | - | - | - | +| Preset | - | Yes | - | - | - | - | - | + +## Common Properties by Type + +### Ceiling Fan (CF) +- `max_speed`: (integer, read-only) Highest speed available +- `feature_light`: (boolean) Enable/disable light feature +- `feature_brightness`: (boolean) Enable/disable brightness control +- `feature_up_down_light`: (boolean) Enable/disable separate up/down light control + +### Motorized Shades (MS) +- `feature_position`: (boolean) Enable/disable position control +- `course_time`: (integer) Time in milliseconds for shade to fully open/close (for dead reckoning position emulation) +- `min_tilt`: (integer) Minimum tilt position in degrees (default 0) +- `max_tilt`: (integer) Maximum tilt position in degrees (default 90) + +### Heater (HT) +- `feature_heat`: (boolean) Enable/disable heat level control +- `default_auto_timer_s`: (integer) Auto-timer duration in seconds for fire code compliance (commonly 2 hours) + +### Light (LT) +- `feature_brightness`: (boolean) Enable/disable brightness control +- `max_color_temp`: (integer) Maximum color temperature in Kelvin +- `min_color_temp`: (integer) Minimum color temperature in Kelvin + +### Fireplace (FP) +- `feature_light`: (boolean) Enable/disable light feature (many fireplaces have separate lights) + +### Bridge Properties (RF Devices) +- `addr`: (string, read-only) Device address +- `freq`: (integer, read-only) RF frequency in Hz +- `bps`: (integer, read-only) Bits per second +- `zero_gap`: (integer, read-only) Length of zeros between repetitions +- `trust_state`: (boolean) Whether Bond should trust its toggleable state belief + +## Template Codes + +Templates define the protocol and default controls for a device. When POSTing a new device with a valid `template` string, the device self-populates its panel with default controls, initializes state, and loads the appropriate behavior script. + +Common template parameters: +- `addr`: Device address +- `freq`: RF frequency +- `bps`: Bits per second +- `zero_gap`: Gap between transmissions + +Example template: `"A1"` (specific templates vary by device manufacturer and protocol) + +## API Endpoints + +### Get Device Information + +```bash +# List all devices +curl -H "BOND-Token: " http:///v2/devices + +# Get specific device details +curl -H "BOND-Token: " http:///v2/devices/ +``` + +**Response example:** +```json +{ + "name": "My Fan", + "type": "CF", + "location": "Living Room", + "actions": ["TurnOn", "TurnOff", "SetSpeed", "IncreaseSpeed", "DecreaseSpeed"], + "properties": {"_": "84cd8a43"}, + "state": {"_": "ad9bcde4"}, + "commands": {"_": "be8e1896"}, + "_": "599b0fc5" +} +``` + +### Get Device State + +```bash +curl -H "BOND-Token: " http:///v2/devices//state +``` + +**Response example (Ceiling Fan):** +```json +{ + "power": 1, + "speed": 3, + "light": 1, + "brightness": 75, + "direction": 1, + "breeze": [1, 50, 50], + "timer": 0, + "_": "ab9284ef" +} +``` + +**Response example (Motorized Shade):** +```json +{ + "open": 1, + "position": 50, + "_": "cd1234ef" +} +``` + +### Get Device Properties + +```bash +curl -H "BOND-Token: " http:///v2/devices//properties +``` + +**Response example (Ceiling Fan):** +```json +{ + "max_speed": 6, + "feature_light": true, + "feature_brightness": true, + "trust_state": false, + "addr": "10101", + "freq": 434300, + "bps": 3000, + "_": "84cd8a43" +} +``` + +### Execute Device Action + +```bash +# Turn on device +curl -H "BOND-Token: " -X PUT \ + http:///v2/devices//actions/TurnOn + +# Set speed with argument +curl -H "BOND-Token: " -X PUT \ + -d '{"argument": 3}' \ + http:///v2/devices//actions/SetSpeed + +# Set brightness +curl -H "BOND-Token: " -X PUT \ + -d '{"argument": 75}' \ + http:///v2/devices//actions/SetBrightness +``` + +## State Variables by Feature + +### Power Feature +- `power`: (integer) 1 = on, 0 = off + +### Speed Feature +- `speed`: (integer) 1 to max_speed + +### Breeze Feature +- `breeze`: (array) `[mode, mean, var]` where mode is 0/1, mean and var are 0-100 + +### Direction Feature +- `direction`: (integer) 1 = forward, -1 = reverse + +### Light Feature +- `light`: (integer) 1 = on, 0 = off + +### Brightness Feature +- `brightness`: (integer) 1-100 percent + +### Open Feature +- `open`: (integer) 1 = open, 0 = closed + +### Position Feature +- `position`: (integer) 0-100 where 0 = open, 100 = closed + +### Flame Feature +- `flame`: (integer) 1-100 + +### Heat Feature +- `heat`: (integer) 1-100 + +### Timer Feature +- `timer`: (integer) seconds remaining, 0 = no timer + +### ColorTemp Feature +- `color_temp`: (integer) color temperature in Kelvin + +### Color Feature +- `rgb`: (object) `{r: 0-255, g: 0-255, b: 0-255}` +- `hsv`: (object) `{h: 0-359, s: 0-100, v: 0-100}` From 7bf67a46ee552d3dc6cc5fd0d80956acd592dd5c Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:51:07 -0500 Subject: [PATCH 13/16] docs: add Mate channels reference --- skills/assistant/references/mate-channels.md | 213 +++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 skills/assistant/references/mate-channels.md diff --git a/skills/assistant/references/mate-channels.md b/skills/assistant/references/mate-channels.md new file mode 100644 index 0000000..e7bd4d1 --- /dev/null +++ b/skills/assistant/references/mate-channels.md @@ -0,0 +1,213 @@ +# Mate (MT-1500) Channels API Reference + +## Overview + +The MT-1500 (Mate Pro) is a motor controller that supports 16 channels for controlling motorized window coverings and other devices via RF protocols. Channels allow independent configuration of different technologies (RF protocols) for controlling motors. + +### Channel Structure + +- **Channel 0**: Broadcast channel ("All") - sends commands to all paired motors +- **Channels 1-15**: Individual channels for specific motors or motor groups + +Each channel can be configured with: +- Custom name and label (label shown on device LED matrix) +- Technology template (R-number identifier for RF protocol) +- Technology-specific properties (addresses, frequencies, etc.) +- Enabled/disabled state for visibility + +## Endpoints + +### List All Channels + +``` +GET /v2/channels +``` + +Returns a hash tree of all channels (0-15). The hash values indicate when channel metadata has changed. + +**Example Response:** +```json +{ + "_": "7fc1e84b", + "0": { "_": "a1b2c3d4" }, + "1": { "_": "84819a9f" }, + "2": { "_": "23141efa" }, + ... + "15": { "_": "2425a8bc" } +} +``` + +**curl Example:** +```bash +curl -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/channels +``` + +### Get Specific Channel + +``` +GET /v2/channels/{channel_id} +``` + +- `channel_id`: "0" for All channel, or "1" through "15" for individual channels + +**Example Response:** +```json +{ + "name": "North Screen", + "label": "N Screen", + "template": "RMS12", + "type": "MS", + "enabled": true, + "actions": ["Raise", "Lower", "Stop", "SetPosition"], + "properties": { + "mfg": 0, + "pairing_assets_key": "" + } +} +``` + +**curl Example:** +```bash +curl -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/channels/1 +``` + +### Configure Channel + +``` +PATCH /v2/channels/{channel_id} +``` + +Modifies channel metadata including name, label, technology assignment, and visibility. + +**Configurable Fields:** +- `name`: User-facing name (max 64 bytes UTF-8) +- `label`: LED matrix display label (max 20 chars, A-Z, a-z, 0-9, space, "-") +- `template`: Technology template (R-number identifier) +- `enabled`: Visibility toggle (true/false) +- `properties`: Technology-specific parameters + +**Note:** Channel 0 (All) only supports `name`, `label`, and `enabled` fields. + +**curl Examples:** +```bash +# Set channel name and label +curl -X PATCH -H "BOND-Token: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name": "Living Room Shade", "label": "LR Shade"}' \ + http://$BOND_IP/v2/channels/1 + +# Assign a technology template +curl -X PATCH -H "BOND-Token: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"template": "RMS12"}' \ + http://$BOND_IP/v2/channels/2 + +# Disable a channel +curl -X PATCH -H "BOND-Token: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"enabled": false}' \ + http://$BOND_IP/v2/channels/3 +``` + +### Execute Channel Action + +``` +PUT /v2/channels/{channel_id}/actions/{action_name} +``` + +Executes an action on a channel by transmitting via the configured RF technology. + +**Note:** This endpoint is intended for development and testing purposes. Mate is not designed to act as a bridge. + +**Parameters:** +- `channel_id`: "0" through "15" +- `action_name`: Action from the channel's `actions` list + +**Request Body (optional):** +```json +{ + "argument": 50 +} +``` + +**curl Examples:** +```bash +# Raise shade +curl -X PUT -H "BOND-Token: $TOKEN" \ + http://$BOND_IP/v2/channels/1/actions/Raise + +# Lower shade +curl -X PUT -H "BOND-Token: $TOKEN" \ + http://$BOND_IP/v2/channels/1/actions/Lower + +# Set position to 50% +curl -X PUT -H "BOND-Token: $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"argument": 50}' \ + http://$BOND_IP/v2/channels/1/actions/SetPosition + +# Stop/Hold shade +curl -X PUT -H "BOND-Token: $TOKEN" \ + http://$BOND_IP/v2/channels/1/actions/Hold +``` + +## Channel Types + +Channel type is automatically inferred from the configured technology template: + +| Type | Description | +|------|-------------| +| `MS` | Motorized Window Coverings (Shades, Screens, Drapes, Awnings) | +| `LT` | Light | +| `CF` | Ceiling Fan | +| `GX` | Generic device | +| `FP` | Fireplace | +| `BD` | Bidet | + +Channels configured for Relay mode have type `MS`. + +## Common Actions + +### Motorized Shades (MS) + +| Action | Description | +|--------|-------------| +| `Raise` | Open the shade (move up) | +| `Lower` | Close the shade (move down) | +| `Stop` | Stop shade movement | +| `Hold` | Stop shade movement (alias for Stop) | +| `SetPosition` | Set shade to specific position (0-100, requires `argument`) | +| `Preset` | Move to preset/favorite position | + +### Lights (LT) + +| Action | Description | +|--------|-------------| +| `TurnLightOn` | Turn light on | +| `TurnLightOff` | Turn light off | +| `SetBrightness` | Set brightness level (requires `argument`) | + +## Technology Templates + +Technology templates use R-number identifiers (same format as the devices API). Example: `RMS12` + +Common shade templates configure the RF protocol used for motor control. The template determines: +- RF protocol and frequency +- Available pairing procedures +- Required properties (addresses, etc.) +- Compatible motors and devices +- Available actions + +## Channel Visibility + +When a channel is disabled (`enabled: false`): +- Skipped during physical button cycling (Channel +/- buttons) +- Appears grayed out in the app +- Configuration is preserved (name, technology, schedules) +- Schedules for disabled channels will not execute +- For bitmap protocols (ARC, Gaposa, etc.), disabled channels are masked from channel 0 bitmap + +## Requirements + +- Firmware version: v4.24+ +- Hardware: Mate Pro (MT-1500), also supported on Sidekick Blue (SKS-500-B) From 122110d73d71ff2a94d4e64dc8b7799ad13cde67 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:51:07 -0500 Subject: [PATCH 14/16] docs: add troubleshooting reference Co-Authored-By: Claude Opus 4.5 --- .../assistant/references/troubleshooting.md | 126 ++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 skills/assistant/references/troubleshooting.md diff --git a/skills/assistant/references/troubleshooting.md b/skills/assistant/references/troubleshooting.md new file mode 100644 index 0000000..3fab268 --- /dev/null +++ b/skills/assistant/references/troubleshooting.md @@ -0,0 +1,126 @@ +# Troubleshooting Guide + +## Connection Issues + +### Bond Not Responding + +1. **Check IP address** - Verify the Bond's IP hasn't changed (DHCP lease renewal) +2. **Ping the Bond** - `ping {ip}` to verify network connectivity +3. **Check power** - Ensure the Bond is powered on (LEDs should be visible) +4. **Check version (no auth required)** - `curl http://{ip}/v2/sys/version` + +## Authentication Errors + +### 401 Unauthorized + +- **Invalid or missing token** - The `BOND-Token` header is required for most endpoints +- **Token retrieval options:** + - Power cycle the Bond and use the temporary unlock window + - Use PIN unlock if configured + - See [discovery-auth.md](discovery-auth.md) for detailed authentication procedures + +## Device Not Found + +- **Re-run discovery** - `bond discover` to find Bonds on the network +- **Check device assignment** - Verify the device is on the correct Bond +- **Device may have been deleted** - Check the Bond's device list + +## Action Errors + +### 400 Bad Request + +- **Device doesn't support action** - Check the device type and its capabilities +- **Invalid argument** - Verify action argument requirements match the device type +- **Check device properties** - Some actions require specific device configurations + +## State Not Updating + +- **RF devices are "fire and forget"** - There is no confirmation from the physical device +- **Use `trust_state` property** - Enable state tracking for devices that support it +- **State is best-effort** - The Bond tracks what it believes the state to be, but cannot verify + +## Network Issues + +- **Bond on different subnet** - Ensure your client is on the same network segment +- **Firewall blocking mDNS** - Port 5353 UDP must be open for discovery +- **Firewall blocking HTTP** - Port 80 TCP must be open for API access +- **Router isolation** - Some routers isolate wireless clients; check AP settings + +## Debug Endpoints (Bridge-Only) + +These endpoints are available only on Bond Bridge hardware for advanced debugging. + +### LiveLog - Real-time Log Output + +``` +GET /v2/debug/livelog +PUT /v2/debug/livelog +DELETE /v2/debug/livelog +``` + +Configure the Bond to send UDP log packets to a specified IP and port. Every log message is sent in a separate UDP packet. Note: High log verbosity may cause performance problems. + +Settings do not persist past reboot. + +### WiFi Diagnostics + +``` +GET /v2/debug/wifi +PATCH /v2/debug/wifi +``` + +Get or set Wi-Fi power settings. The `shutdown` field controls radio power: +- `0`: Normal operation +- `1`: Low-power shutdown mode + +Settings do not persist past reboot. + +### RF Manager Status + +``` +GET /v2/debug/rfman +PATCH /v2/debug/rfman +DELETE /v2/debug/rfman +``` + +Debug RF signal generation: +- `silence_tx`: Stop Bond from transmitting (LEDs still flash, state changes) +- `log_signals`: Send all signals to BPUP listeners on topic `debug/rfman/signal` + +All values are false by default. Settings do not persist past reboot. + +### LED Control + +``` +GET /v2/debug/leds +PATCH /v2/debug/leds +``` + +Manually control LEDs for testing: +- `manual`: Set to `1` to disable automatic LED control +- `value`: Concatenated 24-bit RGB hex values for each LED + +### Database Statistics + +``` +GET /v2/debug/beau/{partition} +``` + +Get statistics about Bond databases. Partitions: +- `db`: Main read-write database (devices and settings) +- `id`: Read-only partition (Bond ID and certificates) +- `state`: Device state storage (Bridges only) + +## HTTP Status Codes Reference + +| Code | Meaning | Common Causes | +|------|---------|---------------| +| 200 | OK | Request successful | +| 201 | Created | Resource created successfully | +| 204 | No Content | Request successful, no response body | +| 400 | Bad Request | Invalid JSON, unsupported action, invalid arguments | +| 401 | Unauthorized | Missing or invalid `BOND-Token` header | +| 404 | Not Found | Device, Bond, or endpoint doesn't exist | +| 409 | Conflict | Resource conflict (e.g., duplicate ID) | +| 423 | Locked | Resource is locked | +| 500 | Internal Server Error | Unexpected server-side error | From a5fab58ea91fafb4c4b0c3dd284ded76c184da83 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:51:11 -0500 Subject: [PATCH 15/16] docs: add groups and scenes reference --- skills/assistant/references/groups-scenes.md | 358 +++++++++++++++++++ 1 file changed, 358 insertions(+) create mode 100644 skills/assistant/references/groups-scenes.md diff --git a/skills/assistant/references/groups-scenes.md b/skills/assistant/references/groups-scenes.md new file mode 100644 index 0000000..d667451 --- /dev/null +++ b/skills/assistant/references/groups-scenes.md @@ -0,0 +1,358 @@ +# Groups and Scenes API Reference + +## Overview + +Groups and Scenes allow you to control multiple devices with a single command. Groups aggregate devices for simultaneous control, while Scenes define sequences of actions across devices and groups. + +Both Groups and Scenes can span multiple Bonds (Bridges and SBB devices) by using the same ID (`_id` field) on each Bond. + +--- + +## Groups + +Groups are collections of Devices that can be controlled together. The available Actions on a Group are the intersection of Actions available on all member Devices. + +### List Groups + +```bash +curl -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/groups +``` + +Response: +```json +{ + "_": "7fc1e84b", + "3b20f300": { "_": "9a5e1136" }, + "4caf6472": { "_": "409d124b" } +} +``` + +### Create Group + +```bash +curl -X POST -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/groups \ + -d '{"name": "Kitchen Shades", "devices": ["aabbccdd", "11223344", "deadbeef"]}' +``` + +**Notes:** +- All devices must be compatible (have at least one common action) +- `types` and `locations` are auto-calculated from member devices +- For cross-Bond groups, provide a 64-bit `_id` field to use the same ID on each Bond + +### Get Group + +```bash +curl -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/groups/{group_id} +``` + +Response: +```json +{ + "name": "Kitchen Shades", + "devices": ["aabbccdd", "11223344", "deadbeef"], + "types": ["MS"], + "locations": ["Kitchen"], + "actions": ["Open", "Close", "Preset"], + "state": { "_": "ad9bcde4" } +} +``` + +### Update Group + +```bash +curl -X PATCH -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/groups/{group_id} \ + -d '{"name": "All Kitchen Shades"}' +``` + +Update device membership: +```bash +curl -X PATCH -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/groups/{group_id} \ + -d '{"devices": ["aabbccdd", "11223344"]}' +``` + +**Note:** If the `devices` list is PATCHed to empty, the group is deleted. + +### Delete Group + +```bash +curl -X DELETE -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/groups/{group_id} +``` + +### Execute Group Action + +```bash +curl -X PUT -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/groups/{group_id}/actions/{action_name} \ + -d '{}' +``` + +With argument: +```bash +curl -X PUT -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/groups/{group_id}/actions/SetPosition \ + -d '{"argument": 50}' +``` + +**Notes:** +- Blocks until all member devices have executed (timeout max 7 seconds) +- Available actions come from the `actions` list in the Group response + +### Get Group State + +```bash +curl -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/groups/{group_id}/state +``` + +Response: +```json +{ + "open": 1 +} +``` + +### State Aggregation Behavior + +Group State lists state variables common to all member Devices: +- If all members have the same value for a state variable, the Group shows that value +- If members differ, the Group variable shows `null` + +Example: If 3 shades are in a group and 2 are open (`open: 1`) and 1 is closed (`open: 0`), the group state will be `{"open": null}`. + +### Group Properties + +Get properties common to all member devices: +```bash +curl -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/groups/{group_id}/properties +``` + +Update properties on all members at once: +```bash +curl -X PATCH -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/groups/{group_id}/properties \ + -d '{"feature_position": true}' +``` + +--- + +## Scenes + +Scenes are sets of actions to run on Devices and/or Groups with a single request. + +### List Scenes + +```bash +curl -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/scenes +``` + +Response: +```json +{ + "_": "7fc1e84b", + "3b20f300": { "_": "9a5e1136" }, + "4caf6472": { "_": "409d124b" } +} +``` + +### Create Scene + +```bash +curl -X POST -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/scenes \ + -d '{ + "name": "Movie Mode", + "actors": [ + {"device": "aabbccdd", "action": "TurnOff"}, + {"device": "11223344", "action": "SetBrightness", "argument": 20}, + {"group": "deadbeef", "action": "Close"} + ] + }' +``` + +### Actor Format + +Each actor in the `actors` array specifies: + +```json +{ + "device": "device_id", // OR "group": "group_id" + "action": "ActionName", + "argument": // For actions that take arguments +} +``` + +Examples: +```json +{"device": "aabbccdd", "action": "TurnOn"} +{"device": "11223344", "action": "SetSpeed", "argument": 3} +{"group": "deadbeef", "action": "SetBrightness", "argument": 50} +{"device": "cafebabe", "action": "SetPosition", "argument": 75} +``` + +### Get Scene + +```bash +curl -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/scenes/{scene_id} +``` + +Response: +```json +{ + "name": "Movie Mode", + "actors": [ + {"device": "aabbccdd", "action": "TurnOff"}, + {"device": "11223344", "action": "SetBrightness", "argument": 20} + ], + "types": ["CF", "LT"], + "locations": ["Living Room"] +} +``` + +### Update Scene + +```bash +curl -X PATCH -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/scenes/{scene_id} \ + -d '{"name": "Movie Night"}' +``` + +Update actors: +```bash +curl -X PATCH -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/scenes/{scene_id} \ + -d '{ + "actors": [ + {"device": "aabbccdd", "action": "TurnOff"}, + {"device": "11223344", "action": "SetBrightness", "argument": 10} + ] + }' +``` + +**Note:** If the `actors` list is PATCHed to empty, the scene is deleted. + +### Delete Scene + +```bash +curl -X DELETE -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/scenes/{scene_id} +``` + +### Run Scene + +```bash +curl -X PUT -H "BOND-Token: $TOKEN" http://$BOND_IP/v2/scenes/{scene_id}/run +``` + +Each actor is executed individually when the scene runs. + +--- + +## Cross-Bond Groups and Scenes + +To create a Group or Scene that spans multiple Bonds: + +1. Generate a unique 64-bit ID +2. Include the same `_id` field in each POST request to each Bond + +```bash +# On Bond 1 +curl -X POST -H "BOND-Token: $TOKEN1" -H "Content-Type: application/json" \ + http://$BOND1_IP/v2/groups \ + -d '{"_id": "mygroup123", "name": "All Shades", "devices": ["dev1", "dev2"]}' + +# On Bond 2 +curl -X POST -H "BOND-Token: $TOKEN2" -H "Content-Type: application/json" \ + http://$BOND2_IP/v2/groups \ + -d '{"_id": "mygroup123", "name": "All Shades", "devices": ["dev3", "dev4"]}' +``` + +--- + +## Use Case Examples + +### Movie Mode + +Dim lights, close shades, and turn on the TV backlight: + +```bash +curl -X POST -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/scenes \ + -d '{ + "name": "Movie Mode", + "actors": [ + {"device": "living_light", "action": "SetBrightness", "argument": 10}, + {"group": "all_shades", "action": "Close"}, + {"device": "backlight", "action": "TurnOn"} + ] + }' +``` + +### Goodnight Scene + +Turn off all lights and fans: + +```bash +curl -X POST -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/scenes \ + -d '{ + "name": "Goodnight", + "actors": [ + {"group": "all_lights", "action": "TurnOff"}, + {"group": "all_fans", "action": "TurnOff"} + ] + }' +``` + +### All Off + +Create a group of all controllable devices and turn them off: + +```bash +# First create a group (if devices are compatible) +curl -X POST -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/groups \ + -d '{"name": "Everything", "devices": ["dev1", "dev2", "dev3"]}' + +# Execute TurnOff on the group +curl -X PUT -H "BOND-Token: $TOKEN" \ + http://$BOND_IP/v2/groups/{group_id}/actions/TurnOff \ + -d '{}' +``` + +Or use a scene for heterogeneous devices: + +```bash +curl -X POST -H "BOND-Token: $TOKEN" -H "Content-Type: application/json" \ + http://$BOND_IP/v2/scenes \ + -d '{ + "name": "All Off", + "actors": [ + {"device": "fan1", "action": "TurnOff"}, + {"device": "light1", "action": "TurnOff"}, + {"device": "shade1", "action": "Close"} + ] + }' +``` + +--- + +## API Summary + +| Operation | Method | Endpoint | +|-----------|--------|----------| +| List groups | GET | `/v2/groups` | +| Create group | POST | `/v2/groups` | +| Get group | GET | `/v2/groups/{id}` | +| Update group | PATCH | `/v2/groups/{id}` | +| Delete group | DELETE | `/v2/groups/{id}` | +| Execute group action | PUT | `/v2/groups/{id}/actions/{action}` | +| Get group state | GET | `/v2/groups/{id}/state` | +| Get group properties | GET | `/v2/groups/{id}/properties` | +| Update group properties | PATCH | `/v2/groups/{id}/properties` | +| List scenes | GET | `/v2/scenes` | +| Create scene | POST | `/v2/scenes` | +| Get scene | GET | `/v2/scenes/{id}` | +| Update scene | PATCH | `/v2/scenes/{id}` | +| Delete scene | DELETE | `/v2/scenes/{id}` | +| Run scene | PUT | `/v2/scenes/{id}/run` | From 30d5260ba5025b55b6ab6b7d17da038ee39899a4 Mon Sep 17 00:00:00 2001 From: Chris Merck Date: Wed, 28 Jan 2026 10:51:23 -0500 Subject: [PATCH 16/16] docs: add system operations reference Co-Authored-By: Claude Opus 4.5 --- skills/assistant/references/system.md | 302 ++++++++++++++++++++++++++ 1 file changed, 302 insertions(+) create mode 100644 skills/assistant/references/system.md diff --git a/skills/assistant/references/system.md b/skills/assistant/references/system.md new file mode 100644 index 0000000..aeedaa7 --- /dev/null +++ b/skills/assistant/references/system.md @@ -0,0 +1,302 @@ +# System Operations Reference + +Bond Local API system-level endpoints for device management, diagnostics, and configuration. + +## Version Information + +**Endpoint:** `GET /v2/sys/version` + +No token required. Returns hardware and firmware details. + +```bash +curl http:///v2/sys/version +``` + +**Response fields:** +- `bondid`: Serial number (unique identifier) +- `target`: Firmware target (e.g., `zermatt`, `breck`) +- `fw_ver`: Firmware version (e.g., `v2.9`, `v2.9.1-beta`) +- `fw_date`: Build date (human-readable) +- `model`: Device model number (e.g., `BD-1000`) +- `make`: Manufacturer (e.g., `Olibra LLC`) +- `api`: API version number +- `upgrade_http`: If true, use HTTP instead of HTTPS for upgrades + +## Time and Location + +**Endpoint:** `GET /v2/sys/time` | `PATCH /v2/sys/time` + +Manage system time, timezone, and location for schedules. + +```bash +# Get current time settings +curl -H "BOND-Token: " http:///v2/sys/time + +# Set timezone and grid location +curl -X PATCH -H "BOND-Token: " \ + -d '{"tz": "America/New_York", "grid": "FN30aw"}' \ + http:///v2/sys/time +``` + +**Fields:** +- `unix_time`: Seconds since UNIX epoch +- `time_set`: Boolean - true if time has been set via NTP +- `tz`: Timezone string (e.g., `America/Sao_Paulo`). See [supported timezones](https://bond-updates.s3.amazonaws.com/tz_meta.json) +- `grid`: 6-character Maidenhead Grid Locator for sunrise/sunset calculations (e.g., `FN30aw`) + +**Note:** Setting `tz` to `null` disables midnight-based schedules. Setting `grid` to `null` disables solar-based schedules. + +## Reboot + +**Endpoint:** `PUT /v2/sys/reboot` + +Reboot the Bond. No settings are modified. + +```bash +curl -X PUT -H "BOND-Token: " http:///v2/sys/reboot +``` + +## Reset + +**Endpoint:** `PUT /v2/sys/reset` + +Perform a setup or factory reset. + +```bash +# Setup reset (allows re-pairing without data loss) +curl -X PUT -H "BOND-Token: " \ + -d '{"type": "setup"}' \ + http:///v2/sys/reset + +# Factory reset (ERASES ALL DATA) +curl -X PUT -H "BOND-Token: " \ + -d '{"type": "factory"}' \ + http:///v2/sys/reset +``` + +**Reset types:** +- `setup`: Re-enables Config AP and allows new Wi-Fi/account setup. Devices preserved. No reboot. +- `factory`: **ERASES ALL devices and settings.** Bond reboots. Firmware version preserved. + +**WARNING:** Factory reset is irreversible. All devices, schedules, and configurations will be permanently deleted. Ensure you have a backup before proceeding. + +## Firmware Upgrade + +### Start Upgrade + +**Endpoint:** `PUT /v2/sys/upgrade` + +```bash +curl -X PUT -H "BOND-Token: " \ + -d '{ + "host": "s3.amazonaws.com", + "port": "443", + "http_port": "80", + "path": "/bond-updates/zermatt-v2.10.bin", + "info": "::", + "sig": "", + "reboot": 1 + }' \ + http:///v2/sys/upgrade +``` + +**Required fields:** +- `host`: FQDN or IP of download server +- `port`: HTTPS port (used unless `upgrade_http` is true in version) +- `path`: Path to firmware binary (must start with `/`) +- `info`: Format: `::` +- `sig`: Base64-encoded signature of `info` string + +**Optional fields:** +- `http_port`: HTTP port (used if `upgrade_http` is true) +- `reboot`: Set to `1` for automatic reboot after upgrade; `0` requires manual reboot via `/v2/sys/reboot` + +### Check Progress + +**Endpoint:** `GET /v2/sys/upgrade` + +```bash +curl -H "BOND-Token: " http:///v2/sys/upgrade +``` + +**Response:** +- `204 No Content`: No upgrade in progress +- `200 OK`: Returns progress object + +**Progress values:** +- `1-999`: Progress in tenths of a percent (e.g., 500 = 50%) +- `1000`: Upgrade complete, waiting for reboot +- `-1`: Error (see `error_msg`) + +### Cancel Upgrade + +**Endpoint:** `DELETE /v2/sys/upgrade` + +```bash +curl -X DELETE -H "BOND-Token: " http:///v2/sys/upgrade +``` + +Canceling is always safe. **WARNING:** Do not power cycle during an upgrade. + +## Backup and Restore + +**Endpoint:** `PUT /v2/sys/backup` | `GET /v2/sys/backup` | `DELETE /v2/sys/backup` + +Backup/restore devices to/from a local HTTP server. + +```bash +# Start backup +curl -X PUT -H "BOND-Token: " \ + -d '{ + "host": "192.168.1.107", + "http_port": "8080", + "path": "/snapshots", + "timestamp": "1618599782" + }' \ + http:///v2/sys/backup + +# Start restore +curl -X PUT -H "BOND-Token: " \ + -d '{ + "host": "192.168.1.107", + "http_port": "8080", + "path": "/snapshots", + "filename": "/ZZDE12345_v2.18.4_1618599782_0f8d01fa.bsnap" + }' \ + http:///v2/sys/backup + +# Check status +curl -H "BOND-Token: " http:///v2/sys/backup + +# Clear status after completion +curl -X DELETE -H "BOND-Token: " http:///v2/sys/backup +``` + +**Status fields:** +- `backup`/`restore`: `0` = idle, `1` = running, `2` = success, `-1` = failure +- `progress`: 0-1000 (1000 = complete) +- `error_msg`: Present on failure + +**Note:** Backup includes devices, commands, properties, state, and schedules. Network settings and bridge name/location are NOT included. Restore is additive (updates existing, creates new). + +## Wi-Fi Configuration + +### Scan for Networks + +**Endpoint:** `GET /v2/sys/wifi/scan` + +```bash +curl -H "BOND-Token: " http:///v2/sys/wifi/scan +``` + +Returns `204` if no scan completed yet. Initiates a new scan on each request. + +**Response format:** +- `format`: Column names for results array (ssid, bssid, auth, ch, signal) +- `results`: 2D array of network data +- `hidden_requires_bssid`: If true, hidden networks need BSSID to connect + +**Auth types:** 0=Open, 1=WEP, 2=WPA, 3=WPA2, 4=WPA/WPA2, 5=Enterprise (unsupported) + +**Note:** `ssid` values are base64-encoded. + +### Station Configuration + +**Endpoint:** `GET /v2/sys/wifi/sta` | `PATCH /v2/sys/wifi/sta` | `DELETE /v2/sys/wifi/sta` + +```bash +# Get current Wi-Fi status +curl -H "BOND-Token: " http:///v2/sys/wifi/sta + +# Connect to network (ssid and password are base64-encoded) +curl -X PATCH -H "BOND-Token: " \ + -d '{"ssid": "bXluZXR3b3Jr", "password": "bXlwYXNzd29yZA=="}' \ + http:///v2/sys/wifi/sta + +# Disconnect (forgets network) +curl -X DELETE -H "BOND-Token: " http:///v2/sys/wifi/sta +``` + +**Status codes:** +- `-4`: Wi-Fi not configured +- `-3`: Disabled (Ethernet selected) +- `-2`: Authentication failure +- `-1`: Network not found +- `0`: Connecting +- `1`: Connected, no IP +- `2`: Connected with IP +- `3`: Connected to cloud (MQTT) + +**Optional fields for static IP:** +- `static_ip_set`: true + `ip`, `gw`, `netmask` +- `dns_set`: true + `dns`, `dns_alt` + +## Bridge Information + +**Endpoint:** `GET /v2/bridge` | `PATCH /v2/bridge` + +```bash +# Get bridge info +curl -H "BOND-Token: " http:///v2/bridge + +# Update bridge settings +curl -X PATCH -H "BOND-Token: " \ + -d '{"name": "Living Room Bridge", "location": "Living Room", "bluelight": 50}' \ + http:///v2/bridge +``` + +**Fields:** +- `name`: User-assigned bridge name +- `location`: User-assigned location +- `bluelight`: LED brightness when idle (0-255, where 0=off, 255=max) +- `frequencies`: (read-only) Supported RF/IR frequency ranges in kHz + +## LED Indication + +**Endpoint:** `GET /v2/sys/indicate` | `PATCH /v2/sys/indicate` + +Trigger visual indication on supported devices (Mate Pro MT-1500, v4.26+). + +```bash +# Trigger identify animation for 10 seconds +curl -X PATCH -H "BOND-Token: " \ + -d '{"identify": 10}' \ + http:///v2/sys/indicate + +# Trigger commit animation for 3 seconds +curl -X PATCH -H "BOND-Token: " \ + -d '{"commit": 3}' \ + http:///v2/sys/indicate + +# Cancel animation +curl -X PATCH -H "BOND-Token: " \ + -d '{"identify": 0}' \ + http:///v2/sys/indicate +``` + +**Animation types:** +- `identify`: Radar/sonar expanding circles (1-30 seconds) +- `commit`: Checkmark confirmation (1-30 seconds) +- Set to `0` to cancel + +Animations are mutually exclusive and can be dismissed by pressing any device button. + +--- + +## Safety Warnings + +**Reset operations:** +- `factory` reset is **IRREVERSIBLE** and deletes all devices and configurations +- Always create a backup before factory reset +- `setup` reset is safe and preserves device data + +**Upgrade operations:** +- **NEVER power cycle during firmware upgrade** - may brick the device +- Canceling an upgrade via `DELETE` is always safe +- Allow up to 7 minutes for slow networks before declaring timeout +- After upgrade, verify success by checking `/v2/sys/version` + +**Wi-Fi operations:** +- `DELETE /v2/sys/wifi/sta` disconnects and forgets the network +- Bond will not reconnect until reconfigured +- Keep the Bond accessible (Config AP or Ethernet) when changing Wi-Fi settings