Utility classes

This page describes several built-in utility classes and enumerations for you to use in your automations.

Bytes

Several of the service calls exposed by Home Assistant want values between 0 - 255. This class is for when you want to develop with percent values and don't want to do the byte conversion. Here is a psuedo representation of the class.

public static class Bytes
{
    public const byte 
        Zero = 0,
        One = 1,
        _5pct = 12,
        _10pct = 25,
        // ... all values in increments of 5% and 33% and 67%
        _95pct = 242,
        _100pct = 255,
        Max = 255;
    
    public static byte PercentToByte(int percent) {/* conversion code*/}
    public static byte PercentToByte(float percent) {/* conversion code*/}
    public static byte PercentToByte(double percent) {/* conversion code*/}
}

There are several constants defined for percentages and three methods for converting numbers. The method accepting an int accepts values between 0 and 100 inclusively. While the float and double overloads accept values between 0 and 1 inclusively.

Light models

HaKafkaNet gives you three built-in models for working with lights.

• LightTurnOnModel - For setting light values of a color light via the IHaApiProvider
• LightModel - For retrieving the state of a white light
• ColorLightModel - For retrieving the state of a color light

Several of the properties for both the LightTurnOnModel and ColorLightModel are of a built-in type for accessing color properties. These include:

• HsColor - Hue/Saturation - float values
• RgbTuple - Red, Green, Blue - byte values
• RgbwTuple - Red, Green, Blue, White - byte values
• RgbwwTuple - Red, Green, Blue, White, Warm White - byte values
• XyColor - X and Y - float values

Each of these tuples are not built on the .NET Tuple, but the behave similarly and have an implicit operator defined so you can write code like the following:

LightTurnOnModel lightSettings = new()
{
    EntityId = ["light.my_light"],
    Brightness = Bytes._75pct,
    RgbColor = (255, 127, 200)
};

Geolocation models

HaKafkaNet exposes several Geolocation models for you to use including:

• ZoneModel
• DeviceTrackerModel
• PersonModel

The above models implement the most common properties you will need. However, some integrations may expose additional properties. If you need them, you can create a model derived from one of these models to suit your needs.

Sun

Home assistant has a sun.sun entity. The SunAttributes model is used by all the prebuilt sun-based automations. You can of course register your own automation to listen for sun events and use this model.

Enumerations

For entities where the State property is always a select set of values, HaKafkaNet provides a few common enumerations.

public enum OnOff
{
    On, Off, Unknown, Unavailable
}

public enum BatteryState
{
    Charging, Discharging, Not_Charging, Unknown, Unavailable
}

public enum SunState
{
    Above_Horizon, Below_Horizon
}

public enum KeyPress
{
    KeyHeldDown, KeyPressed, KeyPressed2x, KeyPressed3x, KeyPressed4x, KeyPressed5x, KeyReleased
}

Note: The HaEntityStateChange extension method that converts incoming state changes for a scene controller does not expose the key press as a KeyPress. Instead it exposes a string and provides an extension method for converting it to an KeyPress enumeration. That way, if your scene controller is non-standard, you can still get the value.

There is one more enumeration for sending commands to a remote. It was built specifically based on Roku documentation, but may work for other devices as well. Here is a partial representaion:

public enum RokuCommands
{
    back, down, enter, find_remote, forward, home,
    info, left, play, power, reverse, right, search,
    select, up, volume_down, volume_mute, volume_up
    // several more values omitted for brevity
}

Scene controllers

There are a few utility methods/classes for working with scene controllers. See Scene Controllers for more information.