{"id":15667040,"url":"https://github.com/saml-dev/gome-assistant","last_synced_at":"2026-04-06T06:02:07.218Z","repository":{"id":61147694,"uuid":"543861110","full_name":"saml-dev/gome-assistant","owner":"saml-dev","description":"A library that lets you write all of your Home Assistant automations in Go!","archived":false,"fork":false,"pushed_at":"2025-01-23T04:01:05.000Z","size":168,"stargazers_count":100,"open_issues_count":7,"forks_count":17,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-02T02:12:19.485Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/saml.dev/gome-assistant","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saml-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-01T02:23:44.000Z","updated_at":"2025-03-24T18:22:43.000Z","dependencies_parsed_at":"2023-02-17T13:31:16.545Z","dependency_job_id":"80a23603-18fc-4748-b5b1-4db3d390d495","html_url":"https://github.com/saml-dev/gome-assistant","commit_stats":{"total_commits":108,"total_committers":6,"mean_commits":18.0,"dds":0.2314814814814815,"last_synced_commit":"066441762b358a395a8bc3f299c6b52a493205c6"},"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saml-dev%2Fgome-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saml-dev%2Fgome-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saml-dev%2Fgome-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saml-dev%2Fgome-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saml-dev","download_url":"https://codeload.github.com/saml-dev/gome-assistant/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247987285,"owners_count":21028895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T14:01:33.471Z","updated_at":"2026-04-06T06:02:07.212Z","avatar_url":"https://github.com/saml-dev.png","language":"Go","readme":"# Gome-Assistant\n\nWrite strongly typed [Home Assistant](https://www.home-assistant.io/) automations in Go!\n\n## Disclaimer\n\nGome-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 that breaking changes will happen before v1.0.0!\n\n## Quick Start\n\n### Installation\n\n```\ngo get saml.dev/gome-assistant\n```\n\n### Generate Entity Constants\n\nYou can generate type-safe constants for all your Home Assistant entities using `go generate`. This makes it easier to reference entities in your code.\n\n1. Create a `gen.yaml` file in your project root:\n\n```yaml\n# Required: insert the URL of your Home Assistant here\nurl: \"http://192.168.1.123:8123\"\n\n# Insert your auth token here, or set the HA_AUTH_TOKEN env var\nha_auth_token: \"\"\n\n# Optional: defaults to zone.home\nhome_zone_entity_id: \"zone.home\"\n\n# Optional: List of domains to include when generating constants\n# If provided, only these domains will be processed\n#include_domains: [\"zone\", \"binary_sensor\", \"light\"]\n\n# Optional: List of domains to exclude when generating constants\n# Only used if include_domains is empty\n#exclude_domains: [\"device_tracker\", \"person\"]\n```\n\n2. Add a `//go:generate` comment in your project:\n\n```go\n//go:generate go run saml.dev/gome-assistant/cmd/generate\n```\n\nOptionally use the `-config` flag to customize the file path of the config file.\n\n3. Run the generator:\n\n```\ngo generate\n```\n\nThis will create an `entities` package with type-safe constants for all your Home Assistant entities, organized by domain. For example:\n\n```go\nimport \"your_project/entities\"\n\n// Instead of writing \"light.living_room\" as a string:\nentities.Light.LivingRoom // Type-safe constant\n\n// All your entities are organized by domain\nentities.Switch.Kitchen\nentities.Climate.Bedroom\nentities.MediaPlayer.TVRoom\n```\n\nThe constants are based on the entity ID itself, not the name of the entity in Home Assistant.\n\n### Write your automations\n\nCheck out [`cmd/example/example.go`](./cmd/example/example.go) for an example of the 3 types of automations — schedules, entity listeners, and event listeners.\n\n\u003e ℹ️ Instead of copying and pasting, try typing it yourself to see how autocomplete guides you through the setup using a builder pattern.\n\n### Run your code\n\nKeeping 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 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!\n\n\u003e _❗ 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._\n\n## gome-assistant Concepts\n\n### Overview\n\nThe general flow is\n\n1. Create your app\n2. Register automations\n3. Start app\n\n```go\nimport ga \"saml.dev/gome-assistant\"\n\n// replace with IP and port of your Home Assistant installation\napp, err := ga.NewApp(ga.NewAppRequest{\n\tURL:              \"http://192.168.1.123:8123\",\n\tHAAuthToken:      os.Getenv(\"HA_AUTH_TOKEN\"),\n\tHomeZoneEntityID: \"zone.home\",\n})\n\n// create automations here (see next sections)\n\n// register automations\napp.RegisterSchedules(...)\napp.RegisterEntityListeners(...)\napp.RegisterEventListeners(...)\napp.RegisterIntervals(...)\n\napp.Start()\n```\n\nA full reference is available on [pkg.go.dev](https://pkg.go.dev/saml.dev/gome-assistant), but all you need to know to get started are the four types of automations in gome-assistant.\n\n- [Daily Schedules](#daily-schedule)\n- [Entity Listeners](#entity-listener)\n- [Event Listeners](#event-listener)\n- [Intervals](#interval)\n\n### Daily Schedule\n\nDaily Schedules run at a specific time each day.\n\n```go\n_7pm := ga.NewDailySchedule().Call(myFunc).At(\"19:00\").Build()\n```\n\nSchedules can also be run at sunrise or sunset, with an optional [offset](https://pkg.go.dev/time#ParseDuration).\n\n```go\n// 30 mins before sunrise\nsunrise := ga.NewDailySchedule().Call(myFunc).Sunrise(app, \"-30m\").Build()\n// at sunset\nsunset := ga.NewDailySchedule().Call(myFunc).Sunset().Build()\n```\n\nDaily schedules have other functions to change the behavior.\n\n| Function                                  | Info                                                                                                     |\n| ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |\n| ExceptionDates(t time.Time, ...time.Time) | Skip the schedule on the given date(s). Functions like a blocklist. Cannot be combined with OnlyOnDates. |\n| OnlyOnDates(t time.Time, ...time.Time)    | Run only on the given date(s). Functions like an allowlist. Cannot be combined with ExceptionDates.      |\n\n#### Schedule Callback function\n\nThe function passed to `.Call()` must take\n\n- `*ga.Service` used to call home assistant services\n- `*ga.State` used to retrieve state from home assistant\n\n```go\nfunc myFunc(se *ga.Service, st *ga.State) {\n  // ...\n}\n```\n\n### Entity Listener\n\nEntity Listeners are used to respond to entities changing state. The simplest entity listener looks like:\n\n```go\netl := ga.NewEntityListener().EntityIDs(\"binary_sensor.front_door\").Call(myFunc).Build()\n```\n\nEntity listeners have other functions to change the behavior.\n\n| Function                                | Info                                                                                                              |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| ToState(\"on\")                           | Function only called if new state matches argument.                                                               |\n| FromState(\"on\")                         | Function only called if old state matches argument.                                                               |\n| Throttle(\"30s\")                         | Minimum time between function calls.                                                                              |\n| Duration(\"30s\")                         | Requires ToState(). Sets how long the entity must be in the state before running your function.                   |\n| OnlyAfter(\"03:00\")                      | Only run your function after a specified time of day.                                                             |\n| OnlyBefore(\"03:00\")                     | Only run your function before a specified time of day.                                                            |\n| OnlyBetween(\"03:00\", \"14:00\")           | Only run your function between two specified times of day.                                                        |\n| ExceptionDates(time.Time, ...time.Time) | A one time exception on the given date. Time is ignored, applies to whole day. Functions like a \"blocklist\".      |\n| ExceptionRange(time.Time, time.Time)    | A one time exception between the two date/times. Both date and time are considered. Functions like a \"blocklist\". |\n| RunOnStartup()                          | Run your callback during `App.Start()`.                                                                           |\n\n#### Entity Listener Callback function\n\nThe function passed to `.Call()` must take\n\n- `*ga.Service` used to call home assistant services\n- `*ga.State` used to retrieve state from home assistant\n- `ga.EntityData` which is the entity that triggered the listener\n\n```go\nfunc myFunc(se *ga.Service, st *ga.State, e ga.EntityData) {\n  // ...\n}\n```\n\n### Event Listeners\n\nEvent listeners allow you to respond to Home Assistant events in real-time. You can create an event listener using the builder pattern:\n\n```go\neventListener := ga.\n    NewEventListener().\n    EventTypes(\"zwave_js_value_notification\"). // Specify one or more event types\n    Call(myCallbackFunc).                     // Specify the callback function\n    Build()\n\n// Register the listener with your app\napp.RegisterEventListeners(eventListener)\n```\n\nEvent listeners have other functions to change the behavior.\n\n| Function                                | Info                                                                                                              |\n| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |\n| OnlyBetween(\"03:00\", \"14:00\")           | Only run your function between two specified times of day                                                         |\n| OnlyAfter(\"03:00\")                      | Only run your function after a specified time of day                                                              |\n| OnlyBefore(\"03:00\")                     | Only run your function before a specified time of day                                                             |\n| Throttle(\"30s\")                         | Minimum time between function calls                                                                               |\n| ExceptionDates(time.Time, ...time.Time) | A one time exception on the given date. Time is ignored, applies to whole day. Functions like a \"blocklist\"      |\n| ExceptionRange(time.Time, time.Time)    | A one time exception between the two date/times. Both date and time are considered. Functions like a \"blocklist\" |\n\nThe callback function receives three parameters:\n```go\nfunc myCallback(service *ga.Service, state ga.State, data ga.EventData) {\n    // You can unmarshal the raw JSON into a type-safe struct\n    ev := ga.EventZWaveJSValueNotification{}\n    json.Unmarshal(data.RawEventJSON, \u0026ev)\n    \n    // Handle the event...\n}\n```\n\n\u003e 💡 Check `eventTypes.go` for pre-defined event types, or create your own struct type for custom events and contribute them back to gome-assistant with a PR.\n\n### Interval\n\nIntervals are used to run a function on an interval.\n\n```go\n// run every hour at the 30-minute mark\ninterval := ga.NewInterval().Call(myFunc).Every(\"1h\").StartingAt(\"00:30\").Build()\n// run every 5 minutes between 10am and 5pm\ninterval = ga.NewInterval().Call(myFunc).Every(\"5m\").StartingAt(\"10:00\").EndingAt(\"17:00\").Build()\n```\n\nIntervals have other functions to change the behavior.\n\n| Function                                | Info                                                                                |\n| --------------------------------------- | ----------------------------------------------------------------------------------- |\n| StartingAt(TimeString)                  | What time the interval begins to run each day.                                      |\n| EndingAt(TimeString)                    | What time the interval stops running each day.                                      |\n| ExceptionDates(time.Time, ...time.Time) | A one time exception on the given date. Time is ignored, applies to whole day.      |\n| ExceptionRange(time.Time, time.Time)    | A one time exception between the two date/times. Both date and time are considered. |\n\n#### Interval Callback function\n\nThe function passed to `.Call()` must take\n\n- `*ga.Service` used to call home assistant services\n- `*ga.State` used to retrieve state from home assistant\n\n```go\nfunc myFunc(se *ga.Service, st *ga.State) {\n  // ...\n}\n```\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaml-dev%2Fgome-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaml-dev%2Fgome-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaml-dev%2Fgome-assistant/lists"}