Frontend data
The frontend passes a single hass object around. This object contains the latest state, allows you to send commands back to the server and provides helpers to format entity state.
Whenever a state changes, a new version of the objects that changed are created. So you can easily see if something has changed by doing a strict equality check:
const changed = newVal !== oldVal;
In order to see the data available in the hass object, visit your HomeAssistant frontend in your favorite browser and open the browser's developer tools. On the elements panel, select the <home-assistant> element, or any other element that has the hass property, and then run the following command in the console panel:
$0.hass
This method of reading the hass object should only be used as a reference. In order to interact with hass in your code, make sure it is passed to your code correctly.
Data
Context
The recommended way to get data from Home Assistant is to consume the available contexts. The most common context is the states context, which contains the states of all entities in Home Assistant. You can also create your own local contexts to pass data around.
To consume a context you fire a custom event with a callback to get registered at the context provider. The context provider sends you initial data and if you have subscribed to updates it will also send you updates whenever the data changes.
Available contexts
connection: hass connection information objectstates: states of all entities in Home Assistantentities: entities in Home AssistantextendedEntities: entities of Home Assistant with extended contextdevices: devices in Home Assistantareas: areas in Home Assistantfloors: floors in Home Assistantlabels: labels in Home AssistantconfigEntries: config entries of Home Assistantauth: authentication information of Home Assistantlocalize: function to localize a stringlocale: Locale informationsconfig: System configuration of Home Assistantthemes: Themes of Home AssistantselectedTheme: Currently selected themeuser: The logged in useruserData: CoreFrontendUserData of the logged in userpanels: available panels of Home Assistant
Consume a context in lit
@consume({ context: labelsContext, subscribe: true })
@state()
private _labels?: LabelRegistryEntry[];
hass.states
An object containing the states of all entities in Home Assistant. The key is the entity_id, the value is the state object.
{
"sun.sun": {
"entity_id": "sun.sun",
"state": "above_horizon",
"attributes": {
"next_dawn": "2018-08-18T05:39:19+00:00",
"next_dusk": "2018-08-17T18:28:52+00:00",
"next_midnight": "2018-08-18T00:03:51+00:00",
"next_noon": "2018-08-18T12:03:58+00:00",
"next_rising": "2018-08-18T06:00:33+00:00",
"next_setting": "2018-08-17T18:07:37+00:00",
"elevation": 60.74,
"azimuth": 297.69,
"friendly_name": "Sun"
},
"last_changed": "2018-08-17T13:46:59.083836+00:00",
"last_updated": "2018-08-17T13:49:30.378101+00:00",
"context": {
"id": "74c2b3b429c844f18e59669e4b41ec6f",
"user_id": null
},
},
"light.ceiling_lights": {
"entity_id": "light.ceiling_lights",
"state": "on",
"attributes": {
"min_mireds": 153,
"max_mireds": 500,
"brightness": 180,
"color_temp": 380,
"hs_color": [
56,
86
],
"rgb_color": [
255,
240,
35
],
"xy_color": [
0.459,
0.496
],
"white_value": 200,
"friendly_name": "Ceiling Lights",
"supported_features": 151
},
"last_changed": "2018-08-17T13:46:59.129248+00:00",
"last_updated": "2018-08-17T13:46:59.129248+00:00",
"context": {
"id": "2c6bbbbb66a84a9dae097b6ed6c93383",
"user_id": null
},
}
}
hass.user
The logged in user.
{
"id": "758186e6a1854ee2896efbd593cb542c",
"name": "Paulus",
"is_owner": true,
"is_admin": true,
"credentials": [
{
"auth_provider_type": "homeassistant",
"auth_provider_id": null
}
]
}
Methods
All methods starting with call are async methods. This means that they will return a Promise that will resolve with the result of the call.
hass.callService(domain, service, data)
Call a service action on the backend.
hass.callService('light', 'turn_on', {
entity_id: 'light.kitchen'
});
hass.callWS(message)
Call a WebSocket command on the backend.
this.hass.callWS({
type: 'config/auth/create',
name: 'Paulus',
}).then(userResponse =>
console.log("Created user", userResponse.user.id));
hass.callApi(method, path, data)
Call an API on the Home Assistant server. For example, if you want to fetch all Home Assistant backups by issuing a GET request to /api/hassio/backups:
hass.callApi('get', 'hassio/backups')
.then(backups => console.log('Received backups!', backups));
If you need to pass in data, pass a third argument:
hass.callApi('delete', 'notify.html5', { subscription: 'abcdefgh' });
We're moving away from API calls and are migrating everything to hass.callWS(message) calls.
Entity state formatting
These methods allow you to format the state and attributes of an entity. The value will be localized using user profile settings (language, number format, date format, timezone) and unit of measurement.
hass.formatEntityState(stateObj, state)
Format the state of an entity. You need to pass the entity state object.
hass.formatEntityState(hass.states["light.my_light"]); // "On"
You can force the state value using the second optional parameter.
hass.formatEntityState(hass.states["light.my_light"], 'off'); // "Off"
hass.formatEntityAttributeValue(stateObj, attribute, value)
Format the attribute value of an entity. You need to pass the entity state object and the attribute name.
hass.formatEntityAttributeValue(hass.states["climate.thermostat"], "current_temperature"); // "20.5 °C"
You can force the state value using the third optional parameter.
hass.formatEntityAttributeValue(hass.states["climate.thermostat"], "current_temperature", 18); // "18 °C"
hass.formatEntityAttributeName(stateObj, attribute)
Format the attribute name of an entity. You need to pass the entity state object and the attribute name.
hass.formatEntityAttributeName(hass.states["climate.thermostat"], "current_temperature"); // "Current temperature"