xevion/go-ha
1
0
Fork 0
mirror of https://github.com/Xevion/go-ha.git synced 2025-12-05 23:15:07 -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
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 |
| --------------------------------------- | ----------------------------------------------------------------------------------- |
| Throttle("30s") | Minimum time between function calls. |
| OnlyAfter("03:00") | Only run after a specified time of day. |
| OnlyBefore("03:00") | Only run before a specified time of day. |
| OnlyBetween("03:00", "14:00") | Only run between two specified times of day. |
| ExceptionDates(time.Time, ...time.Time) | A one time exception on the given date. Time is ignored, applies to whole day. |
| ExceptionRange(time.Time, time.Time) | A one time exception between the two date/times. Both date and time are considered. |
#### 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
| Method | Description |
|--------|-------------|
| `OnlyBetween(start, end string)` | Only trigger between specific times of day |
| `OnlyAfter(start string)` | Only trigger after a specific time of day |
| `OnlyBefore(end string)` | Only trigger before a specific time of day |
| `Throttle(duration DurationString)` | Limit how frequently the listener can trigger |
| `ExceptionDates(dates ...time.Time)` | Specify dates when the listener should not run |
| `ExceptionRange(start, end time.Time)` | Specify date ranges when the listener should not run |
The callback function receives three parameters:
```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
Intervals are used to run a function on an interval.