xevion/go-ha
1
0
Fork 0
mirror of https://github.com/Xevion/go-ha.git synced 2025-12-06 13:15:14 -06:00
Code Issues Packages Projects Releases Wiki Activity

fix event listener documentation

Browse Source
This commit is contained in:
Sam Lewis
2025-06-02 20:13:10 -04:00
parent b72b494a15
commit b275a9c107
1 changed files with 28 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
README.md
View File

@@ -188,39 +188,45 @@ func myFunc(se *ga.Service, st *ga.State, e ga.EntityData) {
} }
``` ```
### Event Listener ### Event Listeners
Event Listeners are used to respond to entities changing state. The simplest event listener looks like: Event listeners allow you to respond to Home Assistant events in real-time. You can create an event listener using the builder pattern:
```go ```go
evl := ga.NewEntityListener().EntityIds("binary_sensor.front_door").Call(myFunc).Build() 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. Event listeners support several additional functions to customize the listener:
| Function | Info | | Method | Description |
| --------------------------------------- | ----------------------------------------------------------------------------------- | |--------|-------------|
| Throttle("30s") | Minimum time between function calls. | | `OnlyBetween(start, end string)` | Only trigger between specific times of day |
| OnlyAfter("03:00") | Only run after a specified time of day. | | `OnlyAfter(start string)` | Only trigger after a specific time of day |
| OnlyBefore("03:00") | Only run before a specified time of day. | | `OnlyBefore(end string)` | Only trigger before a specific time of day |
| OnlyBetween("03:00", "14:00") | Only run between two specified times of day. | | `Throttle(duration DurationString)` | Limit how frequently the listener can trigger |
| ExceptionDates(time.Time, ...time.Time) | A one time exception on the given date. Time is ignored, applies to whole day. | | `ExceptionDates(dates ...time.Time)` | Specify dates when the listener should not run |
| ExceptionRange(time.Time, time.Time) | A one time exception between the two date/times. Both date and time are considered. | | `ExceptionRange(start, end time.Time)` | Specify date ranges when the listener should not run |
#### Event 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.EventData` containing the event data that triggered the listener
The callback function receives three parameters:
```go ```go
func myFunc(se *ga.Service, st *ga.State, ed ga.EventData) { 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 gome-assistant with a PR.
### Interval ### Interval
Intervals are used to run a function on an interval. Intervals are used to run a function on an interval.