cleanup
This commit is contained in:
@@ -1,317 +0,0 @@
|
||||
# Home Automation API Interface Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
This document specifies the expected endpoints for a home automation abstraction layer in core-api. These endpoints will be consumed by the Tatlock Housekeeper agent and potentially other projects (scheduler, dashboards).
|
||||
|
||||
The goal is to provide a simplified, domain-specific interface for home automation that abstracts away the underlying platform (initially Home Assistant, but swappable).
|
||||
|
||||
---
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Device Discovery
|
||||
|
||||
#### `GET /housekeeping/devices`
|
||||
|
||||
List available devices.
|
||||
|
||||
**Query Parameters:**
|
||||
- `domain` (optional): Filter by device type (e.g., `light`, `switch`, `climate`, `media_player`)
|
||||
- `area` (optional): Filter by area/room name
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"devices": [
|
||||
{
|
||||
"entity_id": "light.living_room",
|
||||
"name": "Living Room Light",
|
||||
"domain": "light",
|
||||
"area": "Living Room",
|
||||
"state": "on",
|
||||
"attributes": {
|
||||
"brightness": 255,
|
||||
"color_temp": 370
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `GET /housekeeping/devices/{entity_id}`
|
||||
|
||||
Get detailed state of a specific device.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"entity_id": "light.living_room",
|
||||
"name": "Living Room Light",
|
||||
"domain": "light",
|
||||
"area": "Living Room",
|
||||
"state": "on",
|
||||
"attributes": {
|
||||
"brightness": 255,
|
||||
"color_temp": 370,
|
||||
"supported_features": ["brightness", "color_temp"]
|
||||
},
|
||||
"last_changed": "2025-12-16T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `GET /housekeeping/areas`
|
||||
|
||||
List all areas/rooms.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"areas": [
|
||||
{"id": "living_room", "name": "Living Room"},
|
||||
{"id": "bedroom", "name": "Bedroom"},
|
||||
{"id": "kitchen", "name": "Kitchen"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Device Control
|
||||
|
||||
#### `POST /housekeeping/devices/{entity_id}/control`
|
||||
|
||||
Control a device (turn on, turn off, toggle, or set attributes).
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"action": "turn_on",
|
||||
"brightness": 128,
|
||||
"color_temp": 400
|
||||
}
|
||||
```
|
||||
|
||||
- `action` (required): One of `turn_on`, `turn_off`, `toggle`
|
||||
- Additional attributes vary by device type (brightness, color_temp, rgb_color, etc.)
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"entity_id": "light.living_room",
|
||||
"new_state": "on",
|
||||
"message": "Light turned on"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Scenes
|
||||
|
||||
#### `GET /housekeeping/scenes`
|
||||
|
||||
List available scenes.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"scenes": [
|
||||
{"id": "scene.movie_night", "name": "Movie Night"},
|
||||
{"id": "scene.good_morning", "name": "Good Morning"},
|
||||
{"id": "scene.all_off", "name": "All Off"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `POST /housekeeping/scenes/{scene_id}/activate`
|
||||
|
||||
Activate a scene.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"scene_id": "scene.movie_night",
|
||||
"message": "Scene activated"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Scripts
|
||||
|
||||
#### `GET /housekeeping/scripts`
|
||||
|
||||
List available scripts/sequences.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"scripts": [
|
||||
{"id": "script.bedtime_routine", "name": "Bedtime Routine"},
|
||||
{"id": "script.welcome_home", "name": "Welcome Home"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `POST /housekeeping/scripts/{script_id}/run`
|
||||
|
||||
Execute a script with optional variables.
|
||||
|
||||
**Request Body (optional):**
|
||||
```json
|
||||
{
|
||||
"variables": {
|
||||
"brightness_level": 50,
|
||||
"target_room": "bedroom"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"script_id": "script.bedtime_routine",
|
||||
"message": "Script executed"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Automations
|
||||
|
||||
#### `GET /housekeeping/automations`
|
||||
|
||||
List automations and their enabled/disabled status.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"automations": [
|
||||
{
|
||||
"id": "automation.motion_lights",
|
||||
"name": "Motion Lights",
|
||||
"enabled": true
|
||||
},
|
||||
{
|
||||
"id": "automation.night_mode",
|
||||
"name": "Night Mode",
|
||||
"enabled": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `POST /housekeeping/automations/{automation_id}/toggle`
|
||||
|
||||
Enable or disable an automation.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"automation_id": "automation.motion_lights",
|
||||
"enabled": true,
|
||||
"message": "Automation enabled"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Utility
|
||||
|
||||
#### `GET /housekeeping/history`
|
||||
|
||||
Get state history for a device.
|
||||
|
||||
**Query Parameters:**
|
||||
- `entity_id` (required): Device to get history for
|
||||
- `hours` (optional, default 24): Hours of history to retrieve
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"entity_id": "light.living_room",
|
||||
"history": [
|
||||
{
|
||||
"state": "on",
|
||||
"timestamp": "2025-12-16T10:30:00Z",
|
||||
"attributes": {"brightness": 255}
|
||||
},
|
||||
{
|
||||
"state": "off",
|
||||
"timestamp": "2025-12-16T08:00:00Z",
|
||||
"attributes": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `GET /housekeeping/health`
|
||||
|
||||
Health check for home automation connection.
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"connected": true,
|
||||
"platform": "home_assistant",
|
||||
"version": "2024.12.0"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
All endpoints should return consistent error responses:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": true,
|
||||
"code": "DEVICE_NOT_FOUND",
|
||||
"message": "Device light.nonexistent not found"
|
||||
}
|
||||
```
|
||||
|
||||
Common error codes:
|
||||
- `DEVICE_NOT_FOUND` - Entity ID doesn't exist
|
||||
- `INVALID_ACTION` - Unsupported action for device type
|
||||
- `CONNECTION_ERROR` - Cannot reach home automation platform
|
||||
- `UNAUTHORIZED` - Invalid or missing credentials
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
All endpoints require authentication via Bearer token in the `Authorization` header.
|
||||
|
||||
---
|
||||
|
||||
## Consuming Client
|
||||
|
||||
The Tatlock project has an existing client (`src/agents/housekeeper/client.py`) that expects these endpoints. No changes to Tatlock are needed once these endpoints are available.
|
||||
|
||||
Reference: `CoreAPIClient` class in Tatlock expects these exact endpoint patterns.
|
||||
Reference in New Issue
Block a user