Golang Websocket Client for Homeassistant

This library can be used to commiunicate with Homeassistant via websocket API to send and receive events.

⚠️ This client is in a very early stage of development. The API will change!

⚠️ This client does not yet support all features of the websocket API nor is it fully tested!

Installation

go get github.com/exceptionfault/hass-golang-ws

Usage

Connect to Homeassistant

Create a client instance and connect with a long-living token:

import (
    hass "github.com/exceptionfault/hass-golang-ws/client"
)

func main() {
    host := "homeassistant.local:8123"
    api_token := "DHJ)DFIK...." // get a long-living token from the UI

    client := hass.CreateHassClient(host, api_token)
    err := client.Connect()
    if err != nil {
        panic(err)
    }
    defer client.Disconnect()
}

Secure Websocket

To use a secure connection to Homeassistant over TLS ( wss:// scheme ), you can use the builder method on the client before establishing a connection:

client := hass.CreateHassClient(host, api_token).WithEncryption(true)

Subscribe to Events with Callback

To subscribe to events there are two options which differentiate in the way you get notified about new events. First method allows you to provide a callback function which get's called on every received event.

To specify a filter which events you are looking for, you can use predefined constants like hass.EVT_STATE_CHANGED.

client.SubscribeEvent(hass.EVT_STATE_CHANGED, 
    // This function get's called on every event
    func(evt hass.Event) {
		log.Printf("Got Event %s at %s: %v", evt.EventType, evt.TimeFired, evt.Data)
    }
)

Get a list of all Services

You can get a list of all Services. The example below prints all services by domain and technical name, including all parameters of the Service.

client.GetServices(func(services []*hass.Service, err error) {
    if err != nil {
        panic(err)
    }
    for _, s := range services {
        fmt.Println(s.Domain, s.Id)
        for name, field := range s.Fields {
            fmt.Printf("    %s: %s\n", name, field.Description)
        }
    }
})

// Example Output:
// light turn_off
//     transition: Duration it takes to get to next state.
//     flash: If the light should flash.
// light toggle
//     transition: Duration it takes to get to next state.
//     rgb_color: Color for the light in RGB-format.
//     color_name: A human readable color name.
//     effect: Light effect.
//     xy_color: Color for the light in XY-format.
//     color_temp: Color temperature for the light in mireds.
//     brightness: Number indicating brightness, where 0 turns ...

Call a service

You can call a Service including parameters. The example below should create a new logbook entry in your HA instance, but of course you could use this to restart your HA server, turn on the media player or tell your vacuum robot to start cleaning the house. When calling CallService, keep in mind that services in Homeassistant are named like <domain>.<service>. That means you have to split the name into those two parameters

params := &map[string]string{
    "name":    "hass-golang-ws",
    "message": "sent this log",
    "domain":  "text",
}
client.CallService("logbook", "log", params, func(sr hass.ServerResult) {
    fmt.Println("Result of calling service logbook.log:", sr)
})

Running the sample

The main.go contains an example how to connect and do certain actions with the client. To run the samples make sure to set the following environment variables:

export HASS_API_TOKEN=<your-long-living-token>
export HASS_URL=<address-of-homeassistant:8123>

Then run go run main.go