e3256682ba
- 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
3.3 KiB
3.3 KiB
Device Control Tool
The Device Control tool provides functionality to control various types of devices in your Home Assistant instance.
Supported Device Types
- Lights
- Switches
- Covers
- Climate devices
- Media players
- And more...
Usage
REST API
POST /api/devices/{device_id}/control
WebSocket
{
"type": "control_device",
"device_id": "required_device_id",
"domain": "required_domain",
"service": "required_service",
"data": {
// Service-specific data
}
}
Domain-Specific Commands
Lights
// Turn on/off
POST /api/devices/light/{device_id}/control
{
"service": "turn_on", // or "turn_off"
}
// Set brightness
{
"service": "turn_on",
"data": {
"brightness": 255 // 0-255
}
}
// Set color
{
"service": "turn_on",
"data": {
"rgb_color": [255, 0, 0] // Red
}
}
Covers
// Open/close
POST /api/devices/cover/{device_id}/control
{
"service": "open_cover", // or "close_cover"
}
// Set position
{
"service": "set_cover_position",
"data": {
"position": 50 // 0-100
}
}
Climate
// Set temperature
POST /api/devices/climate/{device_id}/control
{
"service": "set_temperature",
"data": {
"temperature": 22.5
}
}
// Set mode
{
"service": "set_hvac_mode",
"data": {
"hvac_mode": "heat" // heat, cool, auto, off
}
}
Examples
Control Light Brightness
const response = await fetch('http://your-ha-mcp/api/devices/light/living_room/control', {
method: 'POST',
headers: {
'Authorization': 'Bearer your_access_token',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"service": "turn_on",
"data": {
"brightness": 128
}
})
});
Control Cover Position
const response = await fetch('http://your-ha-mcp/api/devices/cover/bedroom/control', {
method: 'POST',
headers: {
'Authorization': 'Bearer your_access_token',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"service": "set_cover_position",
"data": {
"position": 75
}
})
});
Response Format
Success Response
{
"success": true,
"data": {
"state": "on",
"attributes": {
// Updated device attributes
}
}
}
Error Response
{
"success": false,
"message": "Error description",
"error_code": "ERROR_CODE"
}
Error Handling
Common Error Codes
404: Device not found401: Unauthorized400: Invalid service or parameters409: Device unavailable or offline
Rate Limiting
- Default limit: 100 requests per 15 minutes
- Configurable through environment variables:
DEVICE_CONTROL_RATE_LIMITDEVICE_CONTROL_RATE_WINDOW
Best Practices
- Validate device availability before sending commands
- Implement proper error handling
- Use appropriate retry strategies for failed commands
- Cache device capabilities when possible
- Handle rate limiting gracefully