Harmony.HomeAssistant 0.1.3

Harmony.HomeAssistant

Nowoczesna / modern .NET 8 library for Home Assistant (WebSocket + REST + Streaming).

Features

• WebSocket: authentication, full state snapshot, individual & all-event subscriptions, call_service, fire_event, config flows, ping keep-alive, reconnect
• REST: states CRUD, services, events, config, history, logbook, template, intent, calendars, system health, registries (area/device/entity/zone/person), config entries, statistics, energy, camera snapshot & MJPEG
• SSE: /api/stream event stream alternative
• Camera: MJPEG streaming (IAsyncEnumerable<byte[]>)
• Typed registry model helpers (Area, Device, Entity, Zone, Person)

Instalacja

Install-Package Harmony.HomeAssistant

Quick start

var parameters = new ConnectionParameters
{
    WebSocketEndpoint = new Uri("ws://homeassistant.local:8123/api/websocket"),
    AccessToken = "LONG_LIVED_TOKEN"
};
var services = new ServiceCollection()
    .AddLogging(b => b.AddConsole())
    .AddHomeAssistant(parameters)
    .BuildServiceProvider();
var client = services.GetRequiredService<IHomeAssistantClient>();
await client.ConnectAsync();
await client.CallServiceAsync("light", "turn_on", new JsonObject { ["entity_id"] = "light.kitchen" });

Streaming (MJPEG)

await foreach (var frame in rest.GetCameraStreamAsync("camera.front")) { /* handle frame */ }

SSE

var stream = services.GetRequiredService<IHomeAssistantEventStream>();
await foreach (var evt in stream.ReadEventsAsync()) Console.WriteLine(evt.Type);

Typed registries

var zones = (await rest.ListZonesAsync()).ToZones();

Documentation

Additional focused docs:

• Configuration: docs/configuration.md
• Resilience: docs/resilience.md
• Observability: docs/observability.md
• Testing: docs/testing.md

Roadmap (summary)

• Typed History / Logbook / Statistics helpers
• Service invocation documentation & examples

Optional: Resilience + metrics

Enable retry + metrics:

services.AddHomeAssistantClient(p =>
{
    p.WebSocketEndpoint = new Uri("ws://homeassistant.local:8123/api/websocket");
    p.AccessToken = token;
}, opts =>
{
    opts.EnableResilience = true;      // domyślnie true
    opts.HttpRetryCount = 5;           // exponential backoff (2^n * base)
    opts.HttpRetryBaseDelay = TimeSpan.FromMilliseconds(150);
    opts.EnableMetrics = true;         // domyślnie true
});

Metrics (System.Diagnostics.Metrics):

• ha_rest_calls (Counter) tags: endpoint, method, status
• ha_rest_call_latency_ms (Histogram)
• ha_service_calls (Counter) tags: domain, service
• ha_service_call_latency_ms (Histogram)

OpenTelemetry integration example:

services.AddOpenTelemetry()
    .WithMetrics(b => b
    .AddMeter("Harmony.HomeAssistant")
        .AddPrometheusExporter());

Tracing (ActivitySource / OpenTelemetry)

Default enabled unless you set EnableTracing = false. Spans:

• ha.rest (Client) – tags: http.method, ha.endpoint, ha.result.size (optional), status
• ha.service.call (Client) – tags: ha.domain, ha.service, ha.result.success

Register source in OTEL:

services.AddOpenTelemetry()
  .WithTracing(b => b
    .AddSource("Harmony.HomeAssistant")
      .AddConsoleExporter());

Default options (HomeAssistantClientOptions)

You can override only what you need via the configureOptions delegate.

Versioning (SemVer)

• 0.1.0 Public preview
• 0.1.x Bugfix + minor typed models / docs
• 0.2.0 Additional typed layers / enhancements

Changelog

See CHANGELOG for detailed version history.

Contributing

See CONTRIBUTING.md:

• Fork + branch
• dotnet test must pass
• Tag vX.Y.Z triggers publish workflow (requires NUGET_API_KEY secret)

License

MIT (see LICENSE)