Skip to content
GitHub
Specification version v0.1

homeassistant

tested on simulator

Tier Tier 1
Protocol Home Assistant REST API, Home Assistant WebSocket API
Covers lights, switches and smart plugs, fans, number and select helpers, sensors and binary sensors, Zigbee, Z-Wave, Matter and Wi-Fi devices that Home Assistant integrates
Hazard default low
Conformance control
Tested with Home Assistant simulator over an HTTP mock transport and a real local WebSocket server

Estimated reach. Tens of thousands of device models, through more than two thousand integrations. Home Assistant lists over two thousand integrations, and each brand integration covers many models. Every device Home Assistant shows as a light, switch, fan, number, select, sensor or binary sensor entity works through this bridge with no extra code. Zigbee, Z-Wave and Matter devices are reached the same way.

The homeassistant driver exposes the Home Assistant entities a device file selects as one OpenHAL device, under the safety kernel's limits. The rest of Home Assistant stays out of reach.

Which entities are exposed

  • entity names one entity and entities lists several, and every map.entity must be one of the selected entities. With neither key, the entities in channel maps are the selection.
  • Every selected entity must match the match.homeassistant glob.
  • Home Assistant's own min, max and step appear only as describe() suggestions.

Channel roles

A channel's role comes from the entity's domain and the channel name or map.attribute. With several entities, end each channel name with the role, such as lamp_brightness.

DomainChannel name or attributeTypeReadsWrites
lightpower or any other nameboolstate on or offlight.turn_on, light.turn_off
lightbrightnessnumber, percentbrightness 0 to 255, 0 % when offlight.turn_on with brightness_pct
lightcolor_temp or color_temp_kelvinnumber, Kcolor_temp_kelvinlight.turn_on with color_temp_kelvin
switch, input_booleanpowerboolstateturn_on, turn_off
fanpowerboolstatefan.turn_on, fan.turn_off
fanspeed or percentagenumber, percentpercentagefan.set_percentage
fanpreset or preset_modeenumpreset_modefan.set_preset_mode
number, input_numbervaluenumberstate, converted from unit_of_measurementset_value, converted back
select, input_selectoptionenumstateselect_option
sensoranynumber or stringstate, converted from unit_of_measurementread-only
binary_sensoranyboolstateread-only
anymap: { attribute: name }anythat attributeread-only

Home Assistant units convert to the channel unit. An unavailable entity fails reads and marks the device disconnected, and unknown reads as no value.

Transports

rest, the default, sends GET /api/states/<entity_id> per read and POST /api/services/<domain>/<service> per write. websocket reads from a subscribe_entities cache and writes with call_service.

Setup

  1. Install with uv tool install --compile-bytecode "halkit[homeassistant] @ git+https://github.com/sohan-bhat/OpenHAL".
  2. Create a long-lived access token under your profile, Security, ideally for a non-admin user, and export HA_TOKEN=... where the hub runs.
  3. Start from openhal/drivers/homeassistant/examples/office-climate.hal.yaml or describe().
KeyDefaultMeaning
hostrequiredHost name or address
port8123Port
schemehttphttp or https, and ws or wss
token_envHA_TOKENVariable holding the access token
entitynoneThe one selected entity
entitiesnoneThe selected entities, up to 64
transportrestrest or websocket
timeout5 sPer request

Known limitations

  • Climate, cover, lock, vacuum, media player and other domains are read-only through map.attribute for now.
  • health() follows Home Assistant's availability flags.
  • Home Assistant automations and wall switches bypass OpenHAL's limits.

Hazard defaults

low, with safe_state from the device file only. A switch powering a heater or a pump needs medium or high.

Sources

OpenHAL is an open protocol, released under Apache 2.0.

OpenHAL is not affiliated with Anthropic or MHS.

Source on GitHub

Specification v0.1