HaKafakaNet, a library for writing Home Assistant automations in .NET, is now feature complete. I believe it is ready to be the primary method of creating automations, for anyone who writes in C#/.NET. In this post, I’ll say why.
Originally, I had set out to simply write automations in my favorite language C#, and unit test said automations. Some of the automations I wanted to write had moderately complex requirements. My initial goals were:
- ability to inspect and interact with all HA entities
- ability to respond to entity state changes
- make all automation code easily and independently unit testable
I achieved those goals relatively early in the development process. However, there were several features that I knew I wanted to make working with the system easy and stress-free. Those features are now implemented and described below.
Strongly Typed Entities
Obviously, if you are writing in C#, you want strongly typed access to entities. HA exposes nearly everything in what a C# developer might call anonymous typing. For example, if you want to get a number from an entity state, such as for a temperature, humidity, or luminosity sensor, you need to grab the string and parse it into your number. I wanted to make it so that, in one line of code, you could convert the anonymously typed object along with its attributes into a strongly typed one. HaKafkaNet offers two ways to do so. First, when calling the HA API, you can request the object in the type of your choice. Second, when a state change is passed to your automation, there are methods for converting into the type of your choice. There are several helper types provided for working with common entity types such as RGB lights or other.
Observability
Sometimes things go wrong. Devices can fail. Any number of things cause unexpected behavior in your smart home. When that happens, it’s important to be able to quickly troubleshoot what went wrong. HA offers a very generic tracing interface. It’s generic in the sense that it tries to track all the things for all types of actions in any automation. Because it is so generic, it can be difficult to parse what actually happened. Reading the logs in HA can offer some clues, but if they are discoverable, they are usually listed in a global context (not specific to an automation). There are “log book” entries for an automation, but they don’t always include related error logs.
I wanted a framework that filled in a lot of those blanks in terms of observability. HaKafkaNet does. It captures and records every time an automation runs, and it is discoverable in the UI. Additionally, with some very minor configuration at start-up, you can instruct the framework to capture all logs written with the standard ILogger interface. Logs are visible in the UI in one of 4 locations:
- Automation Specific - Inspecting an automation in the UI will display the 50 most recent traces of the automation. Each trace will include all logs from the context of that run.
- Entity Tracker - HaKafkaNet also offers an ability to proactively search for entities in a bad state through a thing called the entity tracker. Any logs captured during its search will be displayed here.
- Global - Any logs recorded outside the context of either an automation or the entity tracker will appear here.
- Error Log - In addition to appearing in any of the above 3 places, the Error log will show all logs of log level Warning or above.
Durability
One of the most common use cases in home automation is to take some action after a given amount of time has elapsed. Early in the development, I provided a mechanism for writing this kind of automation. However, I knew that a compacted Kafka topic offers the ability to capture state changes before start-up, meaning that I could write automations that survive reboots. This is something that is possible in HA natively. However, it cannot be done without extra effort of setting additional variables for each automation where you want this behavior. HaKafkaNet offers it without extra effort. Your automations will survive reboots of either Home Assistant or HaKafkaNet itself.
Final thoughts
I’ve made several small improvements to the UI recently. It is now much more streamlined and allows for quickly searching for the information you’re after. I have moved nearly all automations in my home to HaKafkaNet. The reason: they’re easier to write and inspect there. There are some other things I’d like to do with the framework such as making a Home Assistant addon, but for now, I think it’s ready for prime time for any .NET automator. Today, I’ll be spending some time updating the docs with all the latest features.
Happy Automating!