Files

jango-blockchained e3256682ba 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

2025-02-05 03:02:17 +01:00

3.8 KiB

Raw Blame History

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

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

// 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

{
    "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

const response = await fetch('http://your-ha-mcp/api/scenes', {
    headers: {
        'Authorization': 'Bearer your_access_token'
    }
});
const scenes = await response.json();

Activate a Scene

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

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

{
    "success": true,
    "data": {
        "scenes": [
            {
                "id": "scene_id",
                "name": "Scene Name",
                "entities": {
                    // Entity configurations
                }
            }
        ]
    }
}

Scene Activation Response

{
    "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

{
    "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

Validate entity availability before creating scenes
Use meaningful scene names
Group related entities in scenes
Implement proper error handling
Cache scene configurations when possible
Handle rate limiting gracefully

Scene Transitions

Scenes can include transition settings for smooth state changes:

{
    "name": "Sunset Mode",
    "entities": {
        "light.living_room": {
            "state": "on",
            "brightness": 128,
            "transition": 5  // 5 seconds
        }
    }
}

3.8 KiB Raw Blame History