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
321
docs/tools/automation/automation-config.md
Normal file
321
docs/tools/automation/automation-config.md
Normal file
@@ -0,0 +1,321 @@
|
||||
# Automation Configuration Tool
|
||||
|
||||
The Automation Configuration tool provides functionality to create, update, and manage Home Assistant automation configurations.
|
||||
|
||||
## Features
|
||||
|
||||
- Create new automations
|
||||
- Update existing automations
|
||||
- Delete automations
|
||||
- Duplicate automations
|
||||
- Import/Export automation configurations
|
||||
- Validate automation configurations
|
||||
|
||||
## Usage
|
||||
|
||||
### REST API
|
||||
|
||||
```typescript
|
||||
POST /api/automations
|
||||
PUT /api/automations/{automation_id}
|
||||
DELETE /api/automations/{automation_id}
|
||||
POST /api/automations/{automation_id}/duplicate
|
||||
POST /api/automations/validate
|
||||
```
|
||||
|
||||
### WebSocket
|
||||
|
||||
```typescript
|
||||
// Create automation
|
||||
{
|
||||
"type": "create_automation",
|
||||
"automation": {
|
||||
// Automation configuration
|
||||
}
|
||||
}
|
||||
|
||||
// Update automation
|
||||
{
|
||||
"type": "update_automation",
|
||||
"automation_id": "required_automation_id",
|
||||
"automation": {
|
||||
// Updated configuration
|
||||
}
|
||||
}
|
||||
|
||||
// Delete automation
|
||||
{
|
||||
"type": "delete_automation",
|
||||
"automation_id": "required_automation_id"
|
||||
}
|
||||
```
|
||||
|
||||
## Automation Configuration
|
||||
|
||||
### Basic Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "morning_routine",
|
||||
"alias": "Morning Routine",
|
||||
"description": "Turn on lights and adjust temperature in the morning",
|
||||
"trigger": [
|
||||
{
|
||||
"platform": "time",
|
||||
"at": "07:00:00"
|
||||
}
|
||||
],
|
||||
"condition": [
|
||||
{
|
||||
"condition": "time",
|
||||
"weekday": ["mon", "tue", "wed", "thu", "fri"]
|
||||
}
|
||||
],
|
||||
"action": [
|
||||
{
|
||||
"service": "light.turn_on",
|
||||
"target": {
|
||||
"entity_id": "light.bedroom"
|
||||
},
|
||||
"data": {
|
||||
"brightness": 255,
|
||||
"transition": 300
|
||||
}
|
||||
}
|
||||
],
|
||||
"mode": "single"
|
||||
}
|
||||
```
|
||||
|
||||
### Trigger Types
|
||||
|
||||
```json
|
||||
// Time-based trigger
|
||||
{
|
||||
"platform": "time",
|
||||
"at": "07:00:00"
|
||||
}
|
||||
|
||||
// State-based trigger
|
||||
{
|
||||
"platform": "state",
|
||||
"entity_id": "binary_sensor.motion",
|
||||
"to": "on"
|
||||
}
|
||||
|
||||
// Event-based trigger
|
||||
{
|
||||
"platform": "event",
|
||||
"event_type": "custom_event"
|
||||
}
|
||||
|
||||
// Numeric state trigger
|
||||
{
|
||||
"platform": "numeric_state",
|
||||
"entity_id": "sensor.temperature",
|
||||
"above": 25
|
||||
}
|
||||
```
|
||||
|
||||
### Condition Types
|
||||
|
||||
```json
|
||||
// Time condition
|
||||
{
|
||||
"condition": "time",
|
||||
"after": "07:00:00",
|
||||
"before": "22:00:00"
|
||||
}
|
||||
|
||||
// State condition
|
||||
{
|
||||
"condition": "state",
|
||||
"entity_id": "device_tracker.phone",
|
||||
"state": "home"
|
||||
}
|
||||
|
||||
// Numeric state condition
|
||||
{
|
||||
"condition": "numeric_state",
|
||||
"entity_id": "sensor.temperature",
|
||||
"below": 25
|
||||
}
|
||||
```
|
||||
|
||||
### Action Types
|
||||
|
||||
```json
|
||||
// Service call action
|
||||
{
|
||||
"service": "light.turn_on",
|
||||
"target": {
|
||||
"entity_id": "light.bedroom"
|
||||
}
|
||||
}
|
||||
|
||||
// Delay action
|
||||
{
|
||||
"delay": "00:00:30"
|
||||
}
|
||||
|
||||
// Scene activation
|
||||
{
|
||||
"scene": "scene.evening_mode"
|
||||
}
|
||||
|
||||
// Conditional action
|
||||
{
|
||||
"choose": [
|
||||
{
|
||||
"conditions": [
|
||||
{
|
||||
"condition": "state",
|
||||
"entity_id": "sun.sun",
|
||||
"state": "below_horizon"
|
||||
}
|
||||
],
|
||||
"sequence": [
|
||||
{
|
||||
"service": "light.turn_on",
|
||||
"target": {
|
||||
"entity_id": "light.living_room"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Create New Automation
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/automations', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
"alias": "Morning Routine",
|
||||
"description": "Turn on lights in the morning",
|
||||
"trigger": [
|
||||
{
|
||||
"platform": "time",
|
||||
"at": "07:00:00"
|
||||
}
|
||||
],
|
||||
"action": [
|
||||
{
|
||||
"service": "light.turn_on",
|
||||
"target": {
|
||||
"entity_id": "light.bedroom"
|
||||
}
|
||||
}
|
||||
]
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
### Update Existing Automation
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/automations/morning_routine', {
|
||||
method: 'PUT',
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
"alias": "Morning Routine",
|
||||
"trigger": [
|
||||
{
|
||||
"platform": "time",
|
||||
"at": "07:30:00" // Updated time
|
||||
}
|
||||
],
|
||||
"action": [
|
||||
{
|
||||
"service": "light.turn_on",
|
||||
"target": {
|
||||
"entity_id": "light.bedroom"
|
||||
}
|
||||
}
|
||||
]
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
### Success Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"automation": {
|
||||
"id": "created_automation_id",
|
||||
// Full automation configuration
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Validation Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"valid": true,
|
||||
"warnings": [
|
||||
"No conditions specified"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Error Codes
|
||||
|
||||
- `404`: Automation not found
|
||||
- `401`: Unauthorized
|
||||
- `400`: Invalid configuration
|
||||
- `409`: Automation creation/update failed
|
||||
|
||||
### Error Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Error description",
|
||||
"error_code": "ERROR_CODE",
|
||||
"validation_errors": [
|
||||
{
|
||||
"path": "trigger[0].platform",
|
||||
"message": "Invalid trigger platform"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Always validate configurations before saving
|
||||
2. Use descriptive aliases and descriptions
|
||||
3. Group related automations
|
||||
4. Test automations in a safe environment
|
||||
5. Document automation dependencies
|
||||
6. Use variables for reusable values
|
||||
7. Implement proper error handling
|
||||
8. Consider automation modes carefully
|
||||
|
||||
## See Also
|
||||
|
||||
- [Automation Management](automation.md)
|
||||
- [Event Subscription](../events/subscribe-events.md)
|
||||
- [Scene Management](../history-state/scene.md)
|
||||
211
docs/tools/automation/automation.md
Normal file
211
docs/tools/automation/automation.md
Normal file
@@ -0,0 +1,211 @@
|
||||
# Automation Management Tool
|
||||
|
||||
The Automation Management tool provides functionality to manage and control Home Assistant automations.
|
||||
|
||||
## Features
|
||||
|
||||
- List all automations
|
||||
- Get automation details
|
||||
- Toggle automation state (enable/disable)
|
||||
- Trigger automations manually
|
||||
- Monitor automation execution
|
||||
- View automation history
|
||||
|
||||
## Usage
|
||||
|
||||
### REST API
|
||||
|
||||
```typescript
|
||||
GET /api/automations
|
||||
GET /api/automations/{automation_id}
|
||||
POST /api/automations/{automation_id}/toggle
|
||||
POST /api/automations/{automation_id}/trigger
|
||||
GET /api/automations/{automation_id}/history
|
||||
```
|
||||
|
||||
### WebSocket
|
||||
|
||||
```typescript
|
||||
// List automations
|
||||
{
|
||||
"type": "get_automations"
|
||||
}
|
||||
|
||||
// Toggle automation
|
||||
{
|
||||
"type": "toggle_automation",
|
||||
"automation_id": "required_automation_id"
|
||||
}
|
||||
|
||||
// Trigger automation
|
||||
{
|
||||
"type": "trigger_automation",
|
||||
"automation_id": "required_automation_id",
|
||||
"variables": {
|
||||
// Optional variables
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### List All Automations
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/automations', {
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token'
|
||||
}
|
||||
});
|
||||
const automations = await response.json();
|
||||
```
|
||||
|
||||
### Toggle Automation State
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/automations/morning_routine/toggle', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token'
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
### Trigger Automation Manually
|
||||
|
||||
```typescript
|
||||
const response = await fetch('http://your-ha-mcp/api/automations/morning_routine/trigger', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Authorization': 'Bearer your_access_token',
|
||||
'Content-Type': 'application/json'
|
||||
},
|
||||
body: JSON.stringify({
|
||||
"variables": {
|
||||
"brightness": 100,
|
||||
"temperature": 22
|
||||
}
|
||||
})
|
||||
});
|
||||
```
|
||||
|
||||
## Response Format
|
||||
|
||||
### Automation List Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"automations": [
|
||||
{
|
||||
"id": "automation_id",
|
||||
"name": "Automation Name",
|
||||
"enabled": true,
|
||||
"last_triggered": "2024-02-05T12:00:00Z",
|
||||
"trigger_count": 42
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Automation Details Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"automation": {
|
||||
"id": "automation_id",
|
||||
"name": "Automation Name",
|
||||
"enabled": true,
|
||||
"triggers": [
|
||||
{
|
||||
"platform": "time",
|
||||
"at": "07:00:00"
|
||||
}
|
||||
],
|
||||
"conditions": [],
|
||||
"actions": [
|
||||
{
|
||||
"service": "light.turn_on",
|
||||
"target": {
|
||||
"entity_id": "light.bedroom"
|
||||
}
|
||||
}
|
||||
],
|
||||
"mode": "single",
|
||||
"max": 10,
|
||||
"last_triggered": "2024-02-05T12:00:00Z",
|
||||
"trigger_count": 42
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Automation History Response
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"history": [
|
||||
{
|
||||
"timestamp": "2024-02-05T12:00:00Z",
|
||||
"trigger": {
|
||||
"platform": "time",
|
||||
"at": "07:00:00"
|
||||
},
|
||||
"context": {
|
||||
"user_id": "user_123",
|
||||
"variables": {}
|
||||
},
|
||||
"result": "success"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Error Codes
|
||||
|
||||
- `404`: Automation not found
|
||||
- `401`: Unauthorized
|
||||
- `400`: Invalid request
|
||||
- `409`: Automation execution 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:
|
||||
- `AUTOMATION_RATE_LIMIT`
|
||||
- `AUTOMATION_RATE_WINDOW`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Monitor automation execution history
|
||||
2. Use descriptive automation names
|
||||
3. Implement proper error handling
|
||||
4. Cache automation configurations when possible
|
||||
5. Handle rate limiting gracefully
|
||||
6. Test automations before enabling
|
||||
7. Use variables for flexible automation behavior
|
||||
|
||||
## See Also
|
||||
|
||||
- [Automation Configuration](automation-config.md)
|
||||
- [Event Subscription](../events/subscribe-events.md)
|
||||
- [Device Control](../device-management/control.md)
|
||||
Reference in New Issue
Block a user