Skip to content

Latest commit

 

History

History
364 lines (295 loc) · 9.34 KB

SSE_API.md

File metadata and controls

364 lines (295 loc) · 9.34 KB

Home Assistant MCP Server-Sent Events (SSE) API Documentation

Overview

The SSE API provides real-time updates from Home Assistant through a persistent connection. This allows clients to receive instant notifications about state changes, events, and other activities without polling.

Quick Reference

Available Endpoints

Endpoint Method Description Authentication
/subscribe_events POST Subscribe to real-time events and state changes Required
/get_sse_stats POST Get statistics about current SSE connections Required

Event Types Available

Event Type Description Example Subscription
state_changed Entity state changes events=state_changed
service_called Service call events events=service_called
automation_triggered Automation trigger events events=automation_triggered
script_executed Script execution events events=script_executed
ping Connection keepalive (system) Automatic
error Error notifications (system) Automatic

Subscription Options

Option Description Example
entity_id Subscribe to specific entity entity_id=light.living_room
domain Subscribe to entire domain domain=light
events Subscribe to event types events=state_changed,automation_triggered

Authentication

All SSE connections require authentication using your Home Assistant token.

const token = 'YOUR_HASS_TOKEN';

Endpoints

Subscribe to Events

POST /subscribe_events

Subscribe to Home Assistant events and state changes.

Parameters

Parameter Type Required Description
token string Yes Your Home Assistant authentication token
events string[] No Array of event types to subscribe to
entity_id string No Specific entity ID to monitor
domain string No Domain to monitor (e.g., "light", "switch")

Example Request

const eventSource = new EventSource(`http://localhost:3000/subscribe_events?token=${token}&entity_id=light.living_room&domain=switch&events=state_changed,automation_triggered`);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

eventSource.onerror = (error) => {
  console.error('SSE Error:', error);
  eventSource.close();
};

Get SSE Statistics

POST /get_sse_stats

Get current statistics about SSE connections and subscriptions.

Parameters

Parameter Type Required Description
token string Yes Your Home Assistant authentication token

Example Request

curl -X POST http://localhost:3000/get_sse_stats \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_HASS_TOKEN"}'

Event Types

Standard Events

  1. connection

    • Sent when a client connects successfully
    {
  "type": "connection",
  "status": "connected",
  "id": "client_uuid",
  "authenticated": true,
  "timestamp": "2024-02-10T12:00:00.000Z"
}

  2. state_changed

    • Sent when an entity's state changes
    {
  "type": "state_changed",
  "data": {
    "entity_id": "light.living_room",
    "state": "on",
    "attributes": {
      "brightness": 255,
      "color_temp": 370
    },
    "last_changed": "2024-02-10T12:00:00.000Z",
    "last_updated": "2024-02-10T12:00:00.000Z"
  },
  "timestamp": "2024-02-10T12:00:00.000Z"
}

  3. service_called

    • Sent when a Home Assistant service is called
    {
  "type": "service_called",
  "data": {
    "domain": "light",
    "service": "turn_on",
    "service_data": {
      "entity_id": "light.living_room",
      "brightness": 255
    }
  },
  "timestamp": "2024-02-10T12:00:00.000Z"
}

  4. automation_triggered

    • Sent when an automation is triggered
    {
  "type": "automation_triggered",
  "data": {
    "automation_id": "automation.morning_routine",
    "trigger": {
      "platform": "time",
      "at": "07:00:00"
    }
  },
  "timestamp": "2024-02-10T12:00:00.000Z"
}

  5. script_executed

    • Sent when a script is executed
    {
  "type": "script_executed",
  "data": {
    "script_id": "script.welcome_home",
    "execution_data": {
      "status": "completed"
    }
  },
  "timestamp": "2024-02-10T12:00:00.000Z"
}

System Events

  1. ping

    • Sent every 30 seconds to keep the connection alive
    {
  "type": "ping",
  "timestamp": "2024-02-10T12:00:00.000Z"
}

  2. error

    • Sent when an error occurs
    {
  "type": "error",
  "error": "rate_limit_exceeded",
  "message": "Too many requests, please try again later",
  "timestamp": "2024-02-10T12:00:00.000Z"
}

Rate Limiting

  • Maximum 1000 requests per minute per client
  • Rate limits are reset every minute
  • Exceeding the rate limit will result in an error event

Connection Management

  • Maximum 100 concurrent clients
  • Connections timeout after 5 minutes of inactivity
  • Ping messages are sent every 30 seconds
  • Clients should handle reconnection on connection loss

Example Implementation

class HomeAssistantSSE {
  constructor(baseUrl, token) {
    this.baseUrl = baseUrl;
    this.token = token;
    this.eventSource = null;
    this.reconnectAttempts = 0;
    this.maxReconnectAttempts = 5;
    this.reconnectDelay = 1000;
  }

  connect(options = {}) {
    const params = new URLSearchParams({
      token: this.token,
      ...(options.events && { events: options.events.join(',') }),
      ...(options.entity_id && { entity_id: options.entity_id }),
      ...(options.domain && { domain: options.domain })
    });

    this.eventSource = new EventSource(`${this.baseUrl}/subscribe_events?${params}`);

    this.eventSource.onmessage = (event) => {
      const data = JSON.parse(event.data);
      this.handleEvent(data);
    };

    this.eventSource.onerror = (error) => {
      console.error('SSE Error:', error);
      this.handleError(error);
    };
  }

  handleEvent(data) {
    switch (data.type) {
      case 'connection':
        this.reconnectAttempts = 0;
        console.log('Connected:', data);
        break;
      case 'ping':
        // Connection is alive
        break;
      case 'error':
        console.error('Server Error:', data);
        break;
      default:
        // Handle other event types
        console.log('Event:', data);
    }
  }

  handleError(error) {
    this.eventSource?.close();
    
    if (this.reconnectAttempts < this.maxReconnectAttempts) {
      this.reconnectAttempts++;
      const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
      console.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
      setTimeout(() => this.connect(), delay);
    } else {
      console.error('Max reconnection attempts reached');
    }
  }

  disconnect() {
    this.eventSource?.close();
    this.eventSource = null;
  }
}

// Usage example
const client = new HomeAssistantSSE('http://localhost:3000', 'YOUR_HASS_TOKEN');
client.connect({
  events: ['state_changed', 'automation_triggered'],
  domain: 'light'
});

Best Practices

  1. Error Handling

    • Implement exponential backoff for reconnection attempts
    • Handle connection timeouts gracefully
    • Monitor for rate limit errors

  2. Resource Management

    • Close EventSource when no longer needed
    • Limit subscriptions to necessary events/entities
    • Handle cleanup on page unload

  3. Security

    • Never expose the authentication token in client-side code
    • Use HTTPS in production
    • Validate all incoming data

  4. Performance

    • Subscribe only to needed events
    • Implement client-side event filtering
    • Monitor memory usage for long-running connections

Troubleshooting

Common Issues

  1. Connection Failures

    • Verify your authentication token is valid
    • Check server URL is accessible
    • Ensure proper network connectivity
    • Verify SSL/TLS configuration if using HTTPS

  2. Missing Events

    • Confirm subscription parameters are correct
    • Check rate limiting status
    • Verify entity/domain exists
    • Monitor client-side event handlers

  3. Performance Issues

    • Reduce number of subscriptions
    • Implement client-side filtering
    • Monitor memory usage
    • Check network latency

Debugging Tips

  1. Enable console logging:
const client = new HomeAssistantSSE('http://localhost:3000', 'YOUR_HASS_TOKEN');
client.debug = true; // Enables detailed logging
  1. Monitor network traffic:
// Add event listeners for connection states
eventSource.addEventListener('open', () => {
  console.log('Connection opened');
});

eventSource.addEventListener('error', (e) => {
  console.log('Connection error:', e);
});
  1. Track subscription status:
// Get current subscriptions
const stats = await fetch('/get_sse_stats', {
  headers: { 'Authorization': `Bearer ${token}` }
}).then(r => r.json());

console.log('Current subscriptions:', stats);