ha

go-ha

Write strongly typed Home Assistant automations in Go!

go get github.com/Xevion/go-ha

or in go.mod:

require github.com/Xevion/go-ha

Generate Entity Constants

You can generate type-safe constants for all your Home Assistant entities using go generate. This makes it easier to reference entities in your code.

1. Create a gen.yaml file in your project root:

url: "http://192.168.1.123:8123"
ha_auth_token: "your_auth_token" # Or set HA_AUTH_TOKEN env var
home_zone_entity_id: "zone.home" # Optional: defaults to zone.home

# Optional: List of domains to include when generating constants
# If provided, only these domains will be processed
include_domains: ["light", "switch", "climate"]

# Optional: List of domains to exclude when generating constants
# Only used if include_domains is empty
exclude_domains: ["device_tracker", "person"]

1. Add a //go:generate comment in your project:

//go:generate go run github.com/Xevion/go-ha/cmd/generate

Optionally use the -config flag to customize the file path of the config file.

1. Run the generator:

go generate

This will create an entities package with type-safe constants for all your Home Assistant entities, organized by domain. For example:

import "your_project/entities"

// Instead of writing "light.living_room" as a string:
entities.Light.LivingRoom // Type-safe constant

// All your entities are organized by domain
entities.Switch.Kitchen
entities.Climate.Bedroom
entities.MediaPlayer.TVRoom

The constants are based on the entity ID itself, not the name of the entity in Home Assistant.

Write your automations

Check out example/example.go for an example of the 3 types of automations — schedules, entity listeners, and event listeners.

ℹ️ Instead of copying and pasting, try typing it yourself to see how autocomplete guides you through the setup using a builder pattern.

Run your code

Keeping with the simplicity that Go is famous for, you don't need a specific environment or docker container to run go-ha. You just write and run your code like any other Go binary. So once you build your code, you can run it however you like — using screen or tmux, a cron job, a linux service, or wrap it up in a docker container if you like!

❗ No promises, but I may provide a Docker image with file watching to automatically restart go-ha, to make it easier to use go-ha on a fully managed Home Assistant installation.

go-ha Concepts

Overview

The general flow is

1. Create your app
2. Register automations
3. Start app

import (
 ha "github.com/Xevion/go-ha"
 "github.com/Xevion/go-ha/types"
)

// replace with IP and port of your Home Assistant installation
app, err := ha.NewApp(types.NewAppRequest{
 URL:              "http://192.168.1.123:8123",
 HAAuthToken:      os.Getenv("HA_AUTH_TOKEN"),
 HomeZoneEntityId: "zone.home",
})

// create automations here (see next sections)

// register automations
app.RegisterSchedules(...)
app.RegisterEntityListeners(...)
app.RegisterEventListeners(...)
app.RegisterIntervals(...)

app.Start()

Connection handling

The connection to Home Assistant looks after itself, and the behaviour is worth knowing because it decides what happens to your automations during an outage.

Reconnection. A dropped connection is re-established automatically, with an exponential backoff that starts at one second, caps at a minute, and is jittered so a fleet of clients does not retry in lockstep. Every subscription is re-sent afterwards: Home Assistant replays nothing on its own, and the message ids from the old connection mean nothing on the new one.

Liveness. While idle, go-ha sends the protocol's own ping every 30 seconds. An unanswered ping drops the connection and triggers a reconnect. This catches a Home Assistant whose event loop has stopped responding while its HTTP server still accepts traffic, which a TCP-level check reports as perfectly healthy.

A refused token is fatal. If Home Assistant rejects your token, go-ha stops rather than reconnecting forever, and app.Start() returns. Retrying a revoked token only produces the same answer more slowly.

Backpressure. Incoming events cross a bounded queue to a pool of workers, and your callbacks run on those workers. If the queue fills, further events are dropped and counted. This is deliberate: Home Assistant disconnects a client that stops draining its socket for five seconds, so shedding a burst is survivable where stalling is not. If you see the warning, the fix is usually a callback that returns faster rather than a bigger queue.

Both the queue size and the worker count are tunable:

app, err := ha.NewApp(types.NewAppRequest{
 URL:         "http://192.168.1.123:8123",
 HAAuthToken: os.Getenv("HA_AUTH_TOKEN"),
 Connection: types.ConnectionOptions{
  QueueSize: 1024,
  Workers:   8,
 },
})

A full reference is available on pkg.go.dev, but all you need to know to get started are the four types of automations in go-ha.

• Daily Schedules
• Entity Listeners
• Event Listeners
• Intervals

Daily Schedule

Daily Schedules run at a specific time each day.

_7pm := ga.NewDailySchedule().Call(myFunc).At("19:00").Build()

Schedules can also be run at sunrise or sunset, with an optional offset.

// 30 mins before sunrise
sunrise := ga.NewDailySchedule().Call(myFunc).Sunrise(app, "-30m").Build()
// at sunset
sunset := ga.NewDailySchedule().Call(myFunc).Sunset().Build()

Daily schedules have other functions to change the behavior.

Schedule Callback function

The function passed to .Call() must take

• *ga.Service used to call home assistant services
• *ga.State used to retrieve state from home assistant

func myFunc(se *ga.Service, st *ga.State) {
  // ...
}

Entity Listener

Entity Listeners are used to respond to entities changing state. The simplest entity listener looks like:

etl := ga.NewEntityListener().EntityIds("binary_sensor.front_door").Call(myFunc).Build()

Entity listeners have other functions to change the behavior.

Entity Listener Callback function

The function passed to .Call() must take

• *ga.Service used to call home assistant services
• *ga.State used to retrieve state from home assistant
• ga.EntityData which is the entity that triggered the listener

func myFunc(se *ga.Service, st *ga.State, e ga.EntityData) {
  // ...
}

Event Listeners

Event listeners allow you to respond to Home Assistant events in real-time. You can create an event listener using the builder pattern:

eventListener := ga.
    NewEventListener().
    EventTypes("zwave_js_value_notification"). // Specify one or more event types
    Call(myCallbackFunc).                     // Specify the callback function
    Build()

// Register the listener with your app
app.RegisterEventListeners(eventListener)

Event listeners have other functions to change the behavior.

The callback function receives three parameters:

func myCallback(service *ga.Service, state ga.State, data ga.EventData) {
    // You can unmarshal the raw JSON into a type-safe struct
    ev := ga.EventZWaveJSValueNotification{}
    json.Unmarshal(data.RawEventJSON, &ev)

    // Handle the event...
}

💡 Check eventTypes.go for pre-defined event types, or create your own struct type for custom events and contribute them back to go-ha with a PR.

Interval

Intervals are used to run a function on an interval.

// run every hour at the 30-minute mark
interval := ga.NewInterval().Call(myFunc).Every("1h").StartingAt("00:30").Build()
// run every 5 minutes between 10am and 5pm
interval = ga.NewInterval().Call(myFunc).Every("5m").StartingAt("10:00").EndingAt("17:00").Build()

Intervals have other functions to change the behavior.

Interval Callback function

The function passed to .Call() must take

• *ga.Service used to call home assistant services
• *ga.State used to retrieve state from home assistant

func myFunc(se *ga.Service, st *ga.State) {
  // ...
}