HassClient
A Home Assistant .NET client using Web Socket API.
Sample Usage
HassWSApi
provides access to Web Socket communication and a multitude of common operations:
Connection
To start using the Web Socket API client, it should be connected to a Home Assistant instance.
The method ConnectAsync
with ConnectionParameters
will be used:
- Using Instance base URL: Connects using the Home Assistant instance base address (e.g. "http://localhost:8123") and a valid token. You can obtain a token ("Long-Lived Access Token") by logging into the frontend using a web browser, and going to your profile
http://IP_ADDRESS:8123/profile
.
var hassWSApi = new HassWSApi();
var connectionParameters = ConnectionParameters.CreateFromInstanceBaseUrl("http://localhost:8123", HASS_TOKEN);
await hassWSApi.ConnectAsync(connectionParameters);
- Within an Add-on: Connects to a Home Assistant instance using the add-ons internal proxy.
var hassWSApi = new HassWSApi();
var connectionParameters = ConnectionParameters.CreateForAddonConnection();
await hassWSApi.ConnectAsync(connectionParameters);
Services
The KnownDomains
and KnownServices
enums are available to reduce the use of strings.
// Fetch all available services in the Home Assistant instance.
IEnumerable<ServiceDomain> serviceDomains = await hassWSApi.GetServicesAsync();
// This will call a service from the Home Assistant instance.
await hassWSApi.CallServiceAsync("homeassistant", "check_config");
// Optional data can be passed to the call operation.
await hassWSApi.CallServiceAsync(KnownDomains.Light, KnownServices.TurnOn, data: new { entity_id = "light.my_light", brightness_pct = 20});
// When only entity_id is needed for the invocation this overload can be used.
await hassWSApi.CallServiceForEntitiesAsync(KnownDomains.Light, KnownServices.Toggle, "light.my_light1", "light.my_light2");
Fetching states
# Gets a collection with the state of every registered entity in the Home Assistant instance.
IEnumerable<StateModel> states = await hassWSApi.GetStatesAsync();
An event is produced by the Home Assistant instance every time a change_state
occurs. To simplify the subscription to these events the StateChagedEventListener
can be used:
// Subscribe to changes of a specific entity.
hassWSApi.StateChagedEventListener.SubscribeEntityStatusChanged("light.my_light1", this.my_light1_StateChanged);
[...]
private void my_light1_StateChanged(object sender, StateChangedEvent stateChangedArgs)
{
Debug.WriteLine($"my_light1_StateChanged {stateChangedArgs.EntityId} is now {stateChangedArgs.NewState.State}");
}
// Subscribe to changes by domain.
hassWSApi.StateChagedEventListener.SubscribeDomainStatusChanged("switch", this.Switch_StateChanged);
[...]
private void Switch_StateChanged(object sender, StateChangedEvent stateChangedArgs)
{
Debug.WriteLine($"Switch_StateChanged {stateChangedArgs.EntityId} is now {stateChangedArgs.NewState.State}");
}
Fetching other data
// Fetch current Home Assistant instance configuration.
Configuration config = await hassWSApi.GetConfigurationAsync();
// Fetch current registered panels in Home Assistant instance.
IEnumerable<PanelInfo> panels = await hassWSApi.GetPanelsAsync();
Event subscription
The WS Client provides some methods to subscribe and unsubscribe to Home Assistant events.
Even any eventType
can be specified as a string. The KnownEventTypes enum is available to reduce the use of strings.
// Subscribe to every event type
await hassWSApi.AddEventHandlerSubscriptionAsync(this.WS_OnEvent);
// Subscribe to specific event type
await hassWSApi.AddEventHandlerSubscriptionAsync(this.WS_OnEvent, KnownEventTypes.PanelsUpdated);
// Unsubscribe using the same event type from subscription
await hassWSApi.RemoveEventHandlerSubscriptionAsync(this.WS_OnEvent, KnownEventTypes.PanelsUpdated);
[...]
private void WS_OnEvent(object sender, EventResultInfo eventResultInfo)
{
Debug.WriteLine($"WS_OnEvent {eventResultInfo} => {eventResultInfo.Data}");
}
Render Template
Render a Home Assistant template. See template docs for more information.
string result = await hassWSApi.RenderTemplateAsync("Paulus is at {{ states('sun.sun') }} {{ states('binary_sensor.is_rainy') }}!");
RegistryEntry Collections
Home Assistant defines a Registry Collection
as a registry of items identified by a unique id. Some common operations like list
, create
, update
and delete
are exposed through the Web Socket API and can be consumed using this client.
At the moment only Area
, Device
, RegistryEntry
, and User
entries are defined.
// List
IEnumerable<Area> areas = await hassWSApi.GetAreasAsync();
// Create
var hallArea = new Area("Hall");
bool createResult = await this.hassWSApi.CreateAreaAsync(hallArea);
// Update
hallArea.Name = "Hall_1";
bool updateResult = await hassWSApi.UpdateArea(hallArea);
// Delete
bool deleteResult = await hassWSApi.DeleteAreaAsync(hallArea);
Storage Collections
A Storage Collection
contains a special registry entry type to store entities. The Web Socket API exposes four methods to list
, create
, update
and delete
these types of entries.
At the moment only InputBoolean
, Person
, and Zone
entity models are defined.
// List
IEnumerable<InputBoolean> inputBooleans = await hassWSApi.GetStorageEntityRegistryEntriesAsync<InputBoolean>();
// Create
var alarmInputBoolean = new InputBoolean("Alarm");
bool createResult = await this.hassWSApi.CreateStorageEntityRegistryEntryAsync(alarmInputBoolean);
// Update
alarmInputBoolean.Name = "Alarm_1";
bool updateResult = await hassWSApi.UpdateArea(alarmInputBoolean);
// Delete
bool deleteResult = await hassWSApi.DeleteAreaAsync(alarmInputBoolean);
Search related
All data stored in Home Assistant is interconnected, making it a graph. The client allows searching related items for a given ItemTypes
and itemId
.
SearchRelatedResponse result = await hassWSApi.SearchRelated(ItemTypes.Entity, "weather.home");
Raw Commands
Even though many commands are implemented natively by this API client, some may not. For this purpose, a raw command API is available to send custom commands and receive raw results.
// Send raw command message with raw result
RawCommandResult rawResult = await hassWSApi.SendRawCommandWithResultAsync(new RawCommandMessage("get_config"));
// Send raw command message with success result
bool success = await hassWSApi.SendRawCommandWithSuccessAsync(new RawCommandMessage("get_config"));