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)

Option	Default	Description
EnableResilience	true	Enables retry (+ circuit breaker if enabled).
HttpRetryCount	3	Retry attempts (exponential backoff).
HttpRetryBaseDelay	200ms	Base delay for first retry.
EnableCircuitBreaker	true	Adds circuit breaker.
CircuitBreakerFailures	5	Failures to open circuit.
CircuitBreakerDuration	30s	Open duration.
EnableMetrics	true	Emits Meter instruments.
EnableTracing	true	Emits ActivitySource spans.
SharedMeter	null	Inject external Meter.
SharedActivitySource	null	Use external ActivitySource.

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)