aqara-open-api

Files (6)

• README-CLAWHUB.md
• SKILL.md
• _meta.json
• examples.md · references/
• trait-codes.md · references/
• fetch_all_devices.sh · scripts/

SKILL.md (first lines)

# Aqara Open API Skill

This skill equips the agent to operate Aqara/Lumi Studio smart home devices via HTTPS requests to the Aqara Open Platform API. **All operations are performed exclusively through `curl` commands**, except `GetAllDevicesWithSpaceRequest`, which must be executed through `bash scripts/fetch_all_devices.sh` to refresh the local cache file `data/devices.json`.

This skill supports only:
- device discovery and device type lookup
- device state queries from cache
- device control
- space listing, creation, update, and device assignment

## Configuration
The following environment variables are required:
- `AQARA_ENDPOINT_URL`: The base URL
- `AQARA_OPEN_API_TOKEN`: Your Long-Lived Access Token.

## AI Quick Navigation (Read This First)

> This section is a navigation and execution summary only. It **does not add new rules** or change existing constraints.

### What This Skill Can Do

- **Device discovery**: load all devices, space mappings, endpoints, functions, traits, and current values
- **Device type catalog**: query all device types in the project with code and display name
- **Device queries**: filter by type, name, room/space, or online status; read current trait values
- **Device control**: send control requests using real `deviceId`, `endpointId`, `functionCode`, and `traitCode` from cache
- **Space management**: list spaces, create spaces, update spaces, and assign devices to spaces

### Intent to Fastest Path

- **List all devices / devices by type / devices in a room / device state**
  - Check `data/devices.json`
  - If cache exists: read the file
  - If cache is missing: run `bash scripts/fetch_all_devices.sh`
- **Control a device**
  - Ensure `data/devices.json` exists
  - Read `deviceId + endpointId + functionCode + traitCode` from cache
  - Then use bash + `curl` for `ExecuteTraitRequest`
- **What device types are there?**
  - Use bash + `curl` for `GetDeviceTypeInfosRequest`
- **Refresh all device data**
  - Only run `bash scripts/fetch_all_devices.sh`
- **List spaces**
  - Use bash + `curl` for `GetSpacesRequest`
- **Create or update a space**
  - First get the real `spaceId` from `GetSpacesRequest`
  - Then call `CreateSpaceRequest` or `UpdateSpaceRequest`
- **Assign devices to a space**
  - First get the real `spaceId` from `GetSpacesRequest`
  - Read real `deviceId` values from `data/devices.json`
  - Then call `AssociateDevicesToSpaceRequest`

### Six Highest-Priority Rules

1. **All-device loading only goes through the script**: `GetAllDevicesWithSpaceRequest` may only be executed via `bash scripts/fetch_all_devices.sh`.
2. **All other requests only go through curl**: except for the refresh script above, every other API call must use bash + `curl`.
3. **Request bodies may only contain four fields**: `type`, `version`, `msgId`, and `data`; **`version` must always be `"v1"`**.
4. **`type` is whitelist-only**: use only the exact request types listed in this document; never test guessed alternatives such as `GetAllSpacesRequest`, `GetSpaceListRequest`, or `QuerySpaceListRequest`.
5. **All IDs and codes must come from real API data**: never guess `deviceId`, `endpointId`, `functionCode`, `traitCode`, or `spaceId`.

### Required Preconditions

- **Before listing devices, reading state, or filtering by room/type**: check whether `data/devices.json` exists
- **Before controlling a device**: obtain the real `deviceId`, `endpointId`, `functionCode`, and `traitCode` from the cache file
- **Before creating or updating a space**: if `spaceId` is needed, call `GetSpacesRequest` first
- **Before assigning devices to a space**: get `spaceId` from `GetSpacesRequest` and `deviceId` values from `data/devices.json`

### Terms and Field Reference

- **Cache file**: `data/devices.json`, which stores the `data` array from `GetAllDevicesWithSpaceRequest`
- **deviceId**: device identifier used for control and space assignment
- **endpointId**: endpoint identifier, only from cached `endpoints[].endpointId`
- **functionCode / traitCode**: capability identifiers from cache
- **spaceId**: space identifier from `GetSpacesRequest` or cached `space.spaceId`

### Section Index

- **Protocol and four-field request body**: see `## API Protocol`
- **Script vs curl execution rules**: see `### Execution Model`
- **Cache file rules**: see `### File Cache Model (Cache-First Data Model)`
- **Device APIs**: see `## API Commands` under `### Device Management`
- **Space APIs**: see `### Space Management`
- **Standard workflows**: see `## Standard Operating Procedures (SOP)`
- **Decision trees**: see `## Cache Decision Tree` and `## API Call Decision Tree`
- **Forbidden behavior**: see `## Forbidden Behavior`
- **Trait code reference**: see `references/trait-codes.md`

## 1. Role and Core Philosophy

**Role**: You are a strict hardware interface controller. Never infer or guess IDs or capability fields.

## 2. Hard Safety Rules

### 2.1 Valid Value Rule

Any operation involving live device state, such as power, brightness, or temperature, must follow this rule:

| Power status | Valid interpretation | Response style |
|-------------|----------------------|----------------|
| `Switch == "false"` | Brightness / color temperature / power should be treated as 0 or "off" | "The device is currently off" |
| `Switch == "true"` | Use the actual returned value | "Brightness is X%" |

**Never** produce logically inconsistent output such as "the light is off but brightness is 100%".

## Quick Start (Operator)

1. Set environment variables:
- `AQARA_OPEN_API_TOKEN`: your Aqara Open API Bearer token (JWT)
- `AQARA_ENDPOINT_URL`: the API base URL

**Real environment value rule**: `AQARA_ENDPOINT_URL` and `AQARA_OPEN_API_TOKEN` **must be read from the runtime environment** (via `$AQARA_ENDPOINT_URL` and `$AQARA_OPEN_API_TOKEN`). **Do not guess, fabricate, or use example placeholders** as real request values. If either variable is missing or empty, tell the user to configure it first.

2. Test connectivity:

```bash
curl -s -X POST "$AQARA_ENDPOINT_URL" \
  -H "Authorization: Bearer $AQARA_OPEN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"GetAllDevicesWithSpaceRequest","version":"v1","msgId":"test-1"}'
```

From LeoYeAI/openclaw-master-skills, MIT.

More from LeoYeAI/openclaw-master-skills