Entity & Type Reference

This reference documents the core entity schemas used in the HOS driver protocol: deviceType values, tag conventions, the target object, and the properties schema.

For domain-specific state fields and commands, see Domain Reference.

---

deviceType Values

A complete table of known deviceType strings organized by domain:

deviceType	Domain	Description
light	Lighting	Smart bulb, LED strip
switch	Lighting	On/off switch (no dimming)
dimmer	Lighting	Dimmable switch/controller
tv	AV/Media	Television
receiver	AV/Media	Audio/video receiver
speaker	AV/Media	Smart speaker, soundbar
media_player	AV/Media	Streaming device, set-top box
thermostat	Climate	Temperature controller
hvac	Climate	HVAC system
fan	Climate	Fan, ventilation
lock	Security	Door lock, smart lock
sensor	Security	Motion sensor, door/window sensor
camera	Security	Security camera
alarm	Security	Alarm panel
robot_vacuum	Robot Vacuums	Robot vacuum cleaner

Note: deviceType is a free-form string. The values above are conventions used by the standard domains. Custom drivers may define additional types.

---

Tag Conventions

The tags field is an optional string[] on the DEVICE_DISCOVERED payload.

• Tags are free-form strings used for grouping and filtering devices
• Common conventions: use lowercase, hyphen-separated strings (e.g. "living-room", "floor-2", "outdoor")
• Tags do not affect protocol behavior — they are metadata for organization
• Multiple tags can be applied to a single device

Example:

driver.sendEvent('DEVICE_DISCOVERED', {
    device_id: 'my-light-001',
    data: {
        name: 'Living Room Lamp',
        deviceType: 'light',
        tags: ['living-room', 'floor-1', 'ambient'],
    },
});

---

target Object

The target object carries connection details for the physical device. It appears on DEVICE_DISCOVERED and DEVICE_UPDATED payloads.

target?: {
    host?: string;
    port?: number;
    [key: string]: unknown;
};

Fields:

• host — IP address or hostname of the physical device (e.g. "192.168.1.100")
• port — Network port for device communication
• Additional fields — Allowed via index signature. Drivers can add protocol-specific connection details such as macAddress, serialNumber, apiKey, etc.

target is stored by HOS but not used for routing — it is metadata the driver can read back later. The driver itself is responsible for maintaining the device connection.

Example:

driver.sendEvent('DEVICE_DISCOVERED', {
    device_id: 'my-bulb-001',
    data: {
        name: 'Bedroom Bulb',
        deviceType: 'light',
        target: {
            host: '192.168.1.42',
            port: 80,
            macAddress: 'AA:BB:CC:DD:EE:FF',
        },
    },
});

---

properties Object

The properties object carries capability metadata for the device. It appears on DEVICE_DISCOVERED and DEVICE_UPDATED payloads.

properties?: {
    commandCatalog?: CommandCatalogEntry[];
    [key: string]: unknown;
};

The key field is commandCatalog — an array advertising the commands this device supports. Additional fields are allowed via index signature for driver-specific metadata.

commandCatalog

The command catalog advertises what commands a device accepts. HOS uses this to build control interfaces.

interface CommandCatalogEntry {
    key: string;          // Command identifier (e.g. 'turn_on')
    label?: string;       // Human-readable label (e.g. 'Turn On')
    description?: string; // Longer description of what the command does
    payloadSchema?: Record<string, unknown>;  // JSON schema for command payload
    resultSchema?: Record<string, unknown>;   // JSON schema for action result
}

Fields:

• key (required) — The string used in ACTION messages as data.action. Must match exactly.
• label — Display name for UIs and dashboards
• description — Longer explanation of what the command does
• payloadSchema — Optional JSON Schema object describing the expected command payload
• resultSchema — Optional JSON Schema object describing the action result shape

Example:

commandCatalog: [
    { key: 'turn_on', label: 'Turn On' },
    { key: 'turn_off', label: 'Turn Off' },
]

A more detailed catalog entry with schemas:

commandCatalog: [
    {
        key: 'set_brightness',
        label: 'Set Brightness',
        description: 'Set the brightness level (0-100)',
        payloadSchema: {
            type: 'object',
            properties: {
                level: { type: 'number', minimum: 0, maximum: 100 },
            },
            required: ['level'],
        },
    },
]

---

State Data

STATE_UPDATE events carry a data field typed as Record<string, unknown>. There is no enforced schema — drivers send whatever key-value pairs describe the current device state.

driver.sendEvent('STATE_UPDATE', {
    device_id: 'my-light-001',
    data: {
        power: true,
        brightness: 75,
        colorTemperature: 4000,
    },
});

Domain conventions: State field names are domain conventions. See Domain Reference for the standard fields per domain.

Common cross-domain fields:

Field	Type	Description
power	boolean	Whether the device is on or off
online	boolean	Whether the device is reachable
connected	boolean	Whether the driver has an active connection to the device

Custom fields: Drivers can include any key-value pairs — HOS stores them as-is and broadcasts them to connected clients.

For the full device discovery flow including when to send state updates, see Driver Lifecycle.

---

What's Next

• Driver Manifest — Package your driver as an OS-local ZIP upload
• Troubleshooting — Common errors and solutions