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)
|
||||
Reference in New Issue
Block a user