HADotNet.Core 1.2.0

A Home Assistant library for .NET Standard that allows access to the Home Assistant external API.

Supports core config, states, services, events, error log, and more.

Install-Package HADotNet.Core -Version 1.2.0
dotnet add package HADotNet.Core --version 1.2.0
<PackageReference Include="HADotNet.Core" Version="1.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add HADotNet.Core --version 1.2.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

HADotNet

ci-badge

A simple, straighforward .NET Standard library for the Home Assistant API.

Features

  • .NET Standard 2.0 cross-platform library
  • DI-friendly client initialization (suitable for ASP.NET Core)
  • Home Assistant data is represented by strongly-typed, commented model classes

Getting Started

From NuGet (Recommended)

Install HADotNet.Core from NuGet:

Install-Package HADotNet.Core

From Source

Clone this repo and either include the HADotNet.Core library in your project,
or build the project and include the DLL as a reference.

Examples

Initializing The Client Factory

The ClientFactory class is reponsible for initializing all other clients in a
reusable way, so you only have to define your instance URL and API key once.

To initialize the ClientFactory, pass in your base Home Assistant URL and a
long-lived access token that you created on your profile page.

ClientFactory.Initialize("https://my-home-assistant-url/", "AbCdEf0123456789...");

Getting Home Assistant's Current Configuration

Get a ConfigClient and then call GetConfiguration():

var configClient = ClientFactory.GetClient<ConfigClient>();
var config = await configClient.GetConfiguration();
// config.LocationName: "Home"
// config.Version: 0.96.1

Retrieving All Entities

Get an EntityClient and then call GetEntities():

var entityClient = ClientFactory.GetClient<EntityClient>();
var entityList = await entityClient.GetEntities();

Retrieving Entities By Domain

Get an EntityClient and then call GetEntities(&quot;domainName&quot;):

var entityClient = ClientFactory.GetClient<EntityClient>();
var filteredEntityList = await entityClient.GetEntities("light");

Retrieving All Entity States

Get a StatesClient and then call GetStates():

var statesClient = ClientFactory.GetClient<StatesClient>();
var allMyStates = await statesClient.GetStates();

Retrieving State By Entity

Get a StatesClient and then call GetState(entity):

var statesClient = ClientFactory.GetClient<StatesClient>();
var state = await statesClient.GetState("sun.sun");
// state.EntityId: "sun.sun"
// state.State: "below_horizon"

Retrieving All Service Definitions

Get a ServiceClient and then call GetServices():

var serviceClient = ClientFactory.GetClient<ServiceClient>();
var services = await serviceClient.GetServices();

Retrieving Calendar Events

Get a CalendarClient and then call GetEvents(calEntity):

var calClient = ClientFactory.GetClient<CalendarClient>();
var myEvents = await calClient.GetEvents("calendar.my_calendar");

Calling a Service

Get a ServiceClient and then call CallService():

var serviceClient = ClientFactory.GetClient<ServiceClient>();

var resultingState = await serviceClient.CallService("homeassistant", "restart");
// Or
var resultingState = await serviceClient.CallService("light", "turn_on", new { entity_id = "light.my_light" });
// Or
var resultingState = await serviceClient.CallService("light.turn_on", new { entity_id = "light.my_light" });
// Or
var resultingState = await serviceClient.CallService("light.turn_on", @"{""entity_id"":""light.my_light""}");

Retrieving History for an Entity

Get a HistoryClient and then call GetHistory(entityId):

var historyClient = ClientFactory.GetClient<HistoryClient>();
var historyList = await historyClient.GetHistory("sun.sun");

// historyList.EntityId: "sun.sun"
// historyList[0].State: "above_horizon"
// historyList[0].LastUpdated: 2019-07-25 07:25:00
// historyList[1].State: "below_horizon"
// historyList[1].LastUpdated: 2019-07-25 20:06:00

Rendering a Template

Get a TemplateClient and then call RenderTemplate(templateBody):

var templateClient = ClientFactory.GetClient<TemplateClient>();
var myRenderedTemplate = await templateClient.RenderTemplate("The sun is {{ states('sun.sun') }}");

// myRenderedTemplate: The sun is above_horizon

Testing

To run the unit tests, you must first set two environment variables:

  • HADotNet:Tests:Instance = https://my-home-assistant-url/
  • HADotNet:Tests:ApiKey = AbCdEf0123456789...

Collaborating

Fork the project, make some changes, and submit a pull request!

Be sure to follow the same coding style (generally, the standard Microsoft C# coding
guidelines) and comment all publicly-visible types and members with XMLDoc comments.

HADotNet

ci-badge

A simple, straighforward .NET Standard library for the Home Assistant API.

Features

  • .NET Standard 2.0 cross-platform library
  • DI-friendly client initialization (suitable for ASP.NET Core)
  • Home Assistant data is represented by strongly-typed, commented model classes

Getting Started

From NuGet (Recommended)

Install HADotNet.Core from NuGet:

Install-Package HADotNet.Core

From Source

Clone this repo and either include the HADotNet.Core library in your project,
or build the project and include the DLL as a reference.

Examples

Initializing The Client Factory

The ClientFactory class is reponsible for initializing all other clients in a
reusable way, so you only have to define your instance URL and API key once.

To initialize the ClientFactory, pass in your base Home Assistant URL and a
long-lived access token that you created on your profile page.

ClientFactory.Initialize("https://my-home-assistant-url/", "AbCdEf0123456789...");

Getting Home Assistant's Current Configuration

Get a ConfigClient and then call GetConfiguration():

var configClient = ClientFactory.GetClient<ConfigClient>();
var config = await configClient.GetConfiguration();
// config.LocationName: "Home"
// config.Version: 0.96.1

Retrieving All Entities

Get an EntityClient and then call GetEntities():

var entityClient = ClientFactory.GetClient<EntityClient>();
var entityList = await entityClient.GetEntities();

Retrieving Entities By Domain

Get an EntityClient and then call GetEntities(&quot;domainName&quot;):

var entityClient = ClientFactory.GetClient<EntityClient>();
var filteredEntityList = await entityClient.GetEntities("light");

Retrieving All Entity States

Get a StatesClient and then call GetStates():

var statesClient = ClientFactory.GetClient<StatesClient>();
var allMyStates = await statesClient.GetStates();

Retrieving State By Entity

Get a StatesClient and then call GetState(entity):

var statesClient = ClientFactory.GetClient<StatesClient>();
var state = await statesClient.GetState("sun.sun");
// state.EntityId: "sun.sun"
// state.State: "below_horizon"

Retrieving All Service Definitions

Get a ServiceClient and then call GetServices():

var serviceClient = ClientFactory.GetClient<ServiceClient>();
var services = await serviceClient.GetServices();

Retrieving Calendar Events

Get a CalendarClient and then call GetEvents(calEntity):

var calClient = ClientFactory.GetClient<CalendarClient>();
var myEvents = await calClient.GetEvents("calendar.my_calendar");

Calling a Service

Get a ServiceClient and then call CallService():

var serviceClient = ClientFactory.GetClient<ServiceClient>();

var resultingState = await serviceClient.CallService("homeassistant", "restart");
// Or
var resultingState = await serviceClient.CallService("light", "turn_on", new { entity_id = "light.my_light" });
// Or
var resultingState = await serviceClient.CallService("light.turn_on", new { entity_id = "light.my_light" });
// Or
var resultingState = await serviceClient.CallService("light.turn_on", @"{""entity_id"":""light.my_light""}");

Retrieving History for an Entity

Get a HistoryClient and then call GetHistory(entityId):

var historyClient = ClientFactory.GetClient<HistoryClient>();
var historyList = await historyClient.GetHistory("sun.sun");

// historyList.EntityId: "sun.sun"
// historyList[0].State: "above_horizon"
// historyList[0].LastUpdated: 2019-07-25 07:25:00
// historyList[1].State: "below_horizon"
// historyList[1].LastUpdated: 2019-07-25 20:06:00

Rendering a Template

Get a TemplateClient and then call RenderTemplate(templateBody):

var templateClient = ClientFactory.GetClient<TemplateClient>();
var myRenderedTemplate = await templateClient.RenderTemplate("The sun is {{ states('sun.sun') }}");

// myRenderedTemplate: The sun is above_horizon

Testing

To run the unit tests, you must first set two environment variables:

  • HADotNet:Tests:Instance = https://my-home-assistant-url/
  • HADotNet:Tests:ApiKey = AbCdEf0123456789...

Collaborating

Fork the project, make some changes, and submit a pull request!

Be sure to follow the same coding style (generally, the standard Microsoft C# coding
guidelines) and comment all publicly-visible types and members with XMLDoc comments.

Release Notes

Add calendar API support.

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
1.2.0 56 10/5/2019
1.1.0 134 9/4/2019
1.0.0 150 8/17/2019
0.2.0 68 8/7/2019
0.1.1-beta 62 8/7/2019
0.1.0-beta 56 7/24/2019