docs: expand documentation with comprehensive tools and development guides
- Add detailed documentation for various tools and management interfaces - Create development best practices and interface documentation - Expand tools section with device management, automation, and event subscription guides - Include configuration, usage examples, and error handling for each tool - Update MkDocs navigation to reflect new documentation structure
This commit is contained in:
jango-blockchained
167
docs/tools/history-state/history.md
Normal file
167
docs/tools/history-state/history.md
Normal file
@@ -0,0 +1,167 @@
|
||||
# Device History Tool
|
||||
|
||||
The Device History tool allows you to retrieve historical state information for devices in your Home Assistant instance.
|
||||
|
||||
## Features
|
||||
|
||||
- Fetch device state history
|
||||
- Filter by time range
|
||||
- Get significant changes
|
||||
- Aggregate data by time periods
|
||||
- Export historical data
|
||||
|
||||
## Usage
|
||||
|
||||
### REST API
|
||||
|
||||
```typescript
|
||||
GET /api/history/{device_id}
|
||||
GET /api/history/{device_id}/period/{start_time}
|
||||
GET /api/history/{device_id}/period/{start_time}/{end_time}
|
||||
```
|
||||
|
||||
### WebSocket
|
||||
|
||||
```typescript
|
||||
{
|
||||
"type": "get_history",
|
||||
"device_id": "required_device_id",
|
||||
"start_time": "optional_iso_timestamp",
|
||||
"end_time": "optional_iso_timestamp",
|
||||
"significant_changes_only": false
|
||||
}
|
||||
```
|
||||
|
||||
## Query Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `start_time` | ISO timestamp | Start of the period to fetch history for |
|
||||
| `end_time` | ISO timestamp | End of the period to fetch history for |
|
||||
| `significant_changes_only` | boolean | Only return significant state changes |
|
||||
| `minimal_response` | boolean | Return minimal state information |
|
||||
| `no_attributes` | boolean | Exclude attribute data from response |
|
||||
|
||||
## Examples
|
||||
|
||||
### Get Recent History
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/history/light.living_room', {
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token'
|
||||
}
|
||||
});
|
||||
const history = await response.json();
|
||||
```
|
||||
|
||||
### Get History for Specific Period
|
||||
|
||||
```typescript
|
||||
const startTime = '2024-02-01T00:00:00Z';
|
||||
const endTime = '2024-02-02T00:00:00Z';
|
||||
const response = await fetch(
|
||||
`http://your-ha-mcp/api/history/light.living_room/period/${startTime}/${endTime}`,
|
||||
{
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token'
|
||||
}
|
||||
}
|
||||
);
|
||||
const history = await response.json();
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
### History Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"history": [
|
||||
{
|
||||
"state": "on",
|
||||
"attributes": {
|
||||
"brightness": 255
|
||||
},
|
||||
"last_changed": "2024-02-05T12:00:00Z",
|
||||
"last_updated": "2024-02-05T12:00:00Z"
|
||||
},
|
||||
{
|
||||
"state": "off",
|
||||
"last_changed": "2024-02-05T13:00:00Z",
|
||||
"last_updated": "2024-02-05T13:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Aggregated History Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"aggregates": {
|
||||
"daily": [
|
||||
{
|
||||
"date": "2024-02-05",
|
||||
"on_time": "PT5H30M",
|
||||
"off_time": "PT18H30M",
|
||||
"changes": 10
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Error Codes
|
||||
|
||||
- `404`: Device not found
|
||||
- `401`: Unauthorized
|
||||
- `400`: Invalid parameters
|
||||
- `416`: Time range too large
|
||||
|
||||
### Error Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Error description",
|
||||
"error_code": "ERROR_CODE"
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
- Default limit: 50 requests per 15 minutes
|
||||
- Configurable through environment variables:
|
||||
- `HISTORY_RATE_LIMIT`
|
||||
- `HISTORY_RATE_WINDOW`
|
||||
|
||||
## Data Retention
|
||||
|
||||
- Default retention period: 30 days
|
||||
- Configurable through environment variables:
|
||||
- `HISTORY_RETENTION_DAYS`
|
||||
- Older data may be automatically aggregated
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Use appropriate time ranges to avoid large responses
|
||||
2. Enable `significant_changes_only` for better performance
|
||||
3. Use `minimal_response` when full state data isn't needed
|
||||
4. Implement proper error handling
|
||||
5. Cache frequently accessed historical data
|
||||
6. Handle rate limiting gracefully
|
||||
|
||||
## See Also
|
||||
|
||||
- [List Devices](../device-management/list-devices.md)
|
||||
- [Device Control](../device-management/control.md)
|
||||
- [Scene Management](scene.md)
|
||||
215
docs/tools/history-state/scene.md
Normal file
215
docs/tools/history-state/scene.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Scene Management Tool
|
||||
|
||||
The Scene Management tool provides functionality to manage and control scenes in your Home Assistant instance.
|
||||
|
||||
## Features
|
||||
|
||||
- List available scenes
|
||||
- Activate scenes
|
||||
- Create new scenes
|
||||
- Update existing scenes
|
||||
- Delete scenes
|
||||
- Get scene state information
|
||||
|
||||
## Usage
|
||||
|
||||
### REST API
|
||||
|
||||
```typescript
|
||||
GET /api/scenes
|
||||
GET /api/scenes/{scene_id}
|
||||
POST /api/scenes/{scene_id}/activate
|
||||
POST /api/scenes
|
||||
PUT /api/scenes/{scene_id}
|
||||
DELETE /api/scenes/{scene_id}
|
||||
```
|
||||
|
||||
### WebSocket
|
||||
|
||||
```typescript
|
||||
// List scenes
|
||||
{
|
||||
"type": "get_scenes"
|
||||
}
|
||||
|
||||
// Activate scene
|
||||
{
|
||||
"type": "activate_scene",
|
||||
"scene_id": "required_scene_id"
|
||||
}
|
||||
|
||||
// Create/Update scene
|
||||
{
|
||||
"type": "create_scene",
|
||||
"scene": {
|
||||
"name": "required_scene_name",
|
||||
"entities": {
|
||||
// Entity states
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Scene Configuration
|
||||
|
||||
### Scene Definition
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Movie Night",
|
||||
"entities": {
|
||||
"light.living_room": {
|
||||
"state": "on",
|
||||
"brightness": 50,
|
||||
"color_temp": 2700
|
||||
},
|
||||
"cover.living_room": {
|
||||
"state": "closed"
|
||||
},
|
||||
"media_player.tv": {
|
||||
"state": "on",
|
||||
"source": "HDMI 1"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### List All Scenes
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/scenes', {
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token'
|
||||
}
|
||||
});
|
||||
const scenes = await response.json();
|
||||
```
|
||||
|
||||
### Activate a Scene
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/scenes/movie_night/activate', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Create a New Scene
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/scenes', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
"name": "Movie Night",
|
||||
"entities": {
|
||||
"light.living_room": {
|
||||
"state": "on",
|
||||
"brightness": 50
|
||||
},
|
||||
"cover.living_room": {
|
||||
"state": "closed"
|
||||
}
|
||||
}
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
### Scene List Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"scenes": [
|
||||
{
|
||||
"id": "scene_id",
|
||||
"name": "Scene Name",
|
||||
"entities": {
|
||||
// Entity configurations
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Scene Activation Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"scene_id": "activated_scene_id",
|
||||
"status": "activated",
|
||||
"timestamp": "2024-02-05T12:00:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Error Codes
|
||||
|
||||
- `404`: Scene not found
|
||||
- `401`: Unauthorized
|
||||
- `400`: Invalid scene configuration
|
||||
- `409`: Scene activation failed
|
||||
|
||||
### Error Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Error description",
|
||||
"error_code": "ERROR_CODE"
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
- Default limit: 50 requests per 15 minutes
|
||||
- Configurable through environment variables:
|
||||
- `SCENE_RATE_LIMIT`
|
||||
- `SCENE_RATE_WINDOW`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Validate entity availability before creating scenes
|
||||
2. Use meaningful scene names
|
||||
3. Group related entities in scenes
|
||||
4. Implement proper error handling
|
||||
5. Cache scene configurations when possible
|
||||
6. Handle rate limiting gracefully
|
||||
|
||||
## Scene Transitions
|
||||
|
||||
Scenes can include transition settings for smooth state changes:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Sunset Mode",
|
||||
"entities": {
|
||||
"light.living_room": {
|
||||
"state": "on",
|
||||
"brightness": 128,
|
||||
"transition": 5 // 5 seconds
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Device Control](../device-management/control.md)
|
||||
- [Device History](history.md)
|
||||
- [Automation Management](../automation/automation.md)
|
||||
Reference in New Issue
Block a user