diff --git a/README.md b/README.md index 0834787..b40730e 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,6 @@ Golang ↔ī¸ Home Assistant Write your [Home Assistant](https://www.home-assistant.io/) automations with a strongly-typed Golang library! -## Why? - -My Home Assistant automation journey started with [Node-RED](https://nodered.org/). Since I already know how to write javascript, I started stuffing all my logic into code nodes in Node-RED. - -Then one day I stumbled on [Appdaemon](https://appdaemon.readthedocs.io/en/latest/), which lets you write automations entirely in Python. I switched all my automations over because of the flexibility I gained from writing my automations in code. - -While autocomplete in your IDE seems trivial, it's an important feature many developers take for granted. Python isn't great at it. - -I wanted to learn Golang, and had the idea to wrap the Home Assistant websocket API with a Go library. Go's strong typing means I don't have to remember the API because my IDE will fill in the blanks for me. So anyway, here's my first Go project, I hope you find it useful 😁 - ## Quick Start ### Installation @@ -24,16 +14,68 @@ go get github.com/saml-dev/gome-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 our yourself to see how autocomplete guides you through the setup using a builder pattern. You can also check out some of the other options you see in the autocomplete. +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 whole environment or docker container to run Gome-Assistant. It's just a binary like any other Go code you would write. So once you have your automations, you can run it however you like — using `screen` or `tmux`, a cron job, or wrap it up in a docker container if you just can't get enough docker! +Keeping with the simplicity that Go is famous for, you don't need a specific environment or docker container to run Gome-Assistant. You just write your code like any other Go binary you would write. So once you have your automations, you can run it however you like — using `screen` or `tmux`, a cron job, or wrap it up in a docker container if you just can't get enough docker! -_Note: I may provide a Docker image in the future with file watching to restart gome-assistant, to make it easier to use gome-assistant on a fully managed Home Assistant installation._ +> _❗ No promises, but I may provide a Docker image with file watching to automatically restart gome-assistant, to make it easier to use gome-assistant on a fully managed Home Assistant installation._ ## Disclaimer Gome-Assistant is a new library, and I'm opening it up early to get some user feedback on the API and help shape the direction. I plan for it to grow to cover all Home Assistant use cases, services, and event types. So it's possible — maybe likely — that breaking changes will happen before v1.0.0! -## API Reference (TODO) +## gome-assistant Concepts (TODO) + +First, you'll need to create your app. + +```go +import ga "github.com/saml-dev/gome-assistant" + +// replace with IP and port of your Home Assistant installation if needed +app := ga.App("0.0.0.0:8123") +``` + +A full reference is available on [pkg.go.dev](https://pkg.go.dev/github.com/saml-dev/gome-assistant), but all you need to know to get started are the three types of automations in gome-assistant. + +### Schedules + +Schedules are as you expect, a way to run a function on a schedule. The most common schedule will be once a day. + +```go +_7pm := ga.NewSchedule().Call(myFunc).Daily().At("19:00").Build() +``` + +Schedules can also be run at sunrise or sunset, with an optional [offset](https://pkg.go.dev/time#ParseDuration). + +```go +// 30 mins before sunrise +sunrise := ga.NewSchedule().Call(myFunc).Daily().Sunrise(app, "-30m").Build() +``` + +Schedules are also used to run a function on a certain interval. Offset is used to offset the first run of a schedule from midnight. + +```go +// run every hour at the 30-minute mark +interval := ga.NewSchedule().Call(a).Every("1h").Offset("30m").Build() +``` + +All schedules must be registered with your app. This will panic if there are any issues with the schedule. + +```go +app.RegisterSchedules(_7pm, sunrise, interval) +``` + +#### 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 + +### Entity Listeners + +### Event Listeners