aqara-open-api

What this skill does

# 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"}'
```

## API Protocol

Base URL: `$AQARA_ENDPOINT_URL`

All requests use a **single unified POST endpoint**. Routing is determined by the `type` field in the JSON body.

### Request Envelope

The request-body JSON may contain **exactly these 4 fields**. Do not add, remove, or replace fields:

```json
{
  "type": "<RequestType>",
  "version": "v1",
  "msgId": "<unique-id>",
  "data": { ... }
}
```

| Field | Required | Meaning | Forbidden behavior |
|------|----------|---------|--------------------|
| `type` | Yes | API method name, such as `ExecuteTraitRequest` or `GetSpacesRequest` | Do not modify, abbreviate, or replace it with a value not listed in this document |
| `version` | Yes | **Must be the string `"v1"`** | Do not omit it; do not use `"v2"`, `"1.0"`, or any other value |
| `msgId` | Yes | Unique request identifier, such as `"msg-1234567890"` | None |
| `data` | Yes | Payload for the selected `type` (`null`, object, array, or string depending on the request) | Only use structures defined in this document or `references/` |

**Strict request-body constraints**

1. **Do not omit `version`**: every curl request body must include `"version":"v1"`.
2. **Do not add undefined fields**: the request body may contain **only** these 4 keys. Do not add `senderId`, `source`, `timestamp`, or any field not defined in this document.
3. **Do not invent field names or structures**: neither the top-level body nor `data` may contain made-up fields or undocumented shapes.
4. **Do not invent or trial-run alternate `type` values**: if this document says the request type is `GetSpacesRequest`, then `type` must be exactly `GetSpacesRequest`.
5. **Do not use synonym or variant guessing for `type`**: names such as `GetAllSpacesRequest`, `GetSpaceListRequest`, `QueryS