ha-kafka-net

HaKafkaNet

Kafka ensures automations are durable and state is restored between restarts.

It has been a while since there have been any updates, but rest assured, the author has this framework running stable in his home and actively uses it :)

Version 11, is released and uses .NET 9. It also introduces integration testing. See special release statement for details.

Featured on an episode of On .NET Live !

It was created with the following goals:

• Create Home Assistant automations in .NET / C# with abilities to:
  • track/retrieve states of all entities in Home Assistant
  • respond to Home Assistant state changes
  • call Home Assistant RESTful services
• Enable all automation code to be fully unit testable

Example

Example of multiple durable automations. See Tutorial for more examples.

registrar.TryRegister(
    _factory.SunRiseAutomation(
        cancelToken => _api.TurnOff("light.night_light", cancelToken)),
    _factory.SunSetAutomation(
        cancelToken => _api.TurnOn("light.night_light", cancelToken),
        TimeSpan.FromMinutes(-10))
);

Resources

• Documentation
• Nuget package
• Join the Discord Server

Why ha-kafka-net ?

• Strongly typed access to entities
• Durable - Automations that survive restarts. See also Event Timings
• Fast - Automations run in parallel and asynchronously.
• UI to manage your automations and inspect Kafka consumers.
• Observability through
  • ISystemMonitor
  • Tracing with log capturing
  • Open Telemetry Instrumentation
• Pre-built automations
• Extensible framework - create your own reusable automations
  • Extend automation factory with extension methods
  • Create your own automations from scratch
• Automation builder with fluent syntax for quickly creating automations.
• Full unit testability for custom automations and integration testing for all registered automations.
• MIT license

What others have said:

All in all, I'm really happy HaKafkaNet is a thing! It's a really ergonomic way of writing automations that make sense.

I converted the automations for 3 rooms from Home Assistant automations to C#, and those work good! So I'm really satisfied with the project.

Dashboard

This is an image of the dashboard from the example app. See UI for additional details.

How it works

• State changes are sent from Home Assistant to a Kafka topic
• HaKafkaNet reads all state changes
• States for every entity are cached allowing for faster retrieval later.
  • It also allows us to have some knowledge about which events were not handled between restarts and which ones were. The framework will tell your automation about such timings to allow you to handle messages appropriately.
• It then looks for automations which want to be notified.
  • If the entity id of the state change matches any of the TriggerEntityIds exposed by your automation, and the timing of the event matches your specified timings, then the Execute method of your automation will be called with a new Task.
  • All of your automations will be called asynchronously and in parallel.

More examples

I have made my personal repository public so that users can see working examples of some moderately complex automations.

If you have some examples you would like to share, please start a discussion. I'd be happy to link it here.

Happy Automating!