HADotNet.Core
1.6.0
dotnet add package HADotNet.Core --version 1.6.0
NuGet\Install-Package HADotNet.Core -Version 1.6.0
<PackageReference Include="HADotNet.Core" Version="1.6.0" />
paket add HADotNet.Core --version 1.6.0
#r "nuget: HADotNet.Core, 1.6.0"
// Install HADotNet.Core as a Cake Addin #addin nuget:?package=HADotNet.Core&version=1.6.0 // Install HADotNet.Core as a Cake Tool #tool nuget:?package=HADotNet.Core&version=1.6.0
HADotNet
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
Supported Home Assistant APIs
- Root API (Verifies the HA API is responding)
- Automation API
- Google Calendar API (Unofficial)
- Discovery API
- Config API
- Camera Proxy API
- Entity API
- Error Log API
- Events API
- History API
- Logbook API
- Services API
- States API
- Supervisor API (Supervisor-based installations only)
- Template API
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...");
Integrating into an ASP.NET Core Site
First, call ClientFactory.Initialize(...);
to ensure that your Home Assistant
instance is connected. You can do this in ConfigureServices
, or using middleware.
Just be sure that the client factory has been initialized before any page/controller requests are made.
You can add individual clients to the DI container like so:
services.AddScoped(_ => ClientFactory.GetClient<EntityClient>());
services.AddScoped(_ => ClientFactory.GetClient<StatesClient>());
services.AddScoped(_ => ClientFactory.GetClient<ServiceClient>());
services.AddScoped(_ => ClientFactory.GetClient<DiscoveryClient>());
Since there are no interfaces, simply add the instance(s) directly into the container. Add as few or as many clients as you need, and then simply retrieve each client via the DI container as-needed.
public class MyController : Controller
{
private IOtherService SampleService { get; }
private EntityClient EntityClient { get; }
public MyController(IOtherService sampleService, EntityClient entityClient)
{
SampleService = sampleService;
EntityClient = entityClient;
}
// ...
}
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("domainName")
:
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
Retrieving a Camera Image
Get a CameraProxyClient
and then call GetCameraImage
, or for a ready-to-go HTML Base64 string, GetCameraImageAsBase64
:
var cameraClient = ClientFactory.GetClient<CameraProxyClient>();
var myCameraImage = await cameraClient.GetCameraImageAsBase64("camera.my_camera");
// myCameraImage: "data:image/jpg;base64,AAAAAAAAA..."
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.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Newtonsoft.Json (>= 12.0.3)
NuGet packages (1)
Showing the top 1 NuGet packages that depend on HADotNet.Core:
Package | Downloads |
---|---|
HADotNet.Entities
A Home Assistant library for .NET Standard to make use of strongly typed Home Assistant entities. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated | |
---|---|---|---|
1.6.0 | 1,604 | 8/14/2021 | |
1.5.1 | 1,373 | 2/1/2021 | |
1.5.0 | 310 | 1/31/2021 | |
1.4.1 | 375 | 1/25/2021 | |
1.4.0 | 434 | 1/23/2021 | |
1.3.2 | 668 | 8/9/2020 | |
1.3.1 | 509 | 8/9/2020 | |
1.3.0 | 567 | 5/9/2020 | |
1.2.2 | 502 | 4/12/2020 | |
1.2.1 | 809 | 1/9/2020 | |
1.2.0 | 531 | 10/5/2019 | |
1.1.0 | 592 | 9/4/2019 | |
1.0.0 | 579 | 8/17/2019 | |
0.2.0 | 517 | 8/7/2019 | |
0.1.1-beta | 383 | 8/7/2019 | |
0.1.0-beta | 366 | 7/24/2019 |
Removed RestSharp, refactored for HttpClient, and added new clients/methods