ferenchome_lib

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 16, 2026 License: MIT Imports: 22 Imported by: 0

README

ferenchome_lib

A Go library and code generator for writing Zigbee2MQTT home automations whose device capabilities are checked by the compiler.

cmd/generate connects to your MQTT broker, reads Zigbee2MQTT's retained device list, and emits a typed Go package: one type per device, one accessor per documented parameter. A capability a device does not document — Set on a read-only sensor value, Toggle on something that cannot toggle, an enum value outside the documented set — is a compile error in your automation code, never a runtime refusal.

Using it through the ferenchome CLI

The ferenchome command from the Homebrew tap scaffolds automation projects, regenerates their device types, and runs the selected project as a macOS service. Projects it creates depend on this module; if that is how you arrived here, the tap's README is the place to start.

Standalone usage

The library works without the CLI. In a Go module, with a config.toml describing your broker:

[mqtt_server]
host = "192.168.1.10"
port = 1883
base_topic = "zigbee2mqtt"

fetch the library and generate the typed device package:

go get github.com/ferenchome/ferenchome_lib
go run github.com/ferenchome/ferenchome_lib/cmd/generate --config config.toml --target ferenchome_types

Because the generator runs through your module's go.mod, it is always built from the exact library version your project compiles against. Then write automations against the generated types:

package main

import (
	"log"

	types "myautomation/ferenchome_types"
)

func main() {
	devices, err := types.NewDevices("config.toml")
	if err != nil {
		log.Fatal(err)
	}
	devices.KitchenLight.Brightness().OnChange(func(v float64) {
		log.Printf("kitchen brightness: %v", v)
	})
	err = devices.Run(func() {
		devices.KitchenLight.State().Set(true)
	})
	if err != nil {
		log.Fatal(err)
	}
}

What the runtime provides

  • A single-goroutine event loop. All callbacks run on it, so automation code needs no locking; Set is additionally safe from any goroutine.
  • Two listener kinds. OnChange fires on effective-value changes and coalesces bursts; OnReport fires once per device report — repeats included — for event-style parameters such as button actions.
  • Coalesced, optimistic writes. Sets deduplicate against the effective value, batch into one /set per device per cycle, and Get answers with the requested value until the device confirms or a short window expires.
  • Timers. Do posts work to the loop; Every runs it periodically, with Stop/Start for one-shot and debounce idioms.
  • HTTP integration. Client.Serve runs an HTTP server tied to the automation's lifetime; handlers reach device state through Do and Ask.
  • Per-project data. DataDir/OpenData store files under the project's data/ directory, owned by the project's owner even when the automation runs as a root service.

Development records

  • DESIGN.md — the concept and the stage-by-stage development record, findings included.
  • TESTING.md — what has been verified per stage, and how.
  • DECISIONS.md — the decision record of packaging Zigbee2MQTT for Homebrew, which predates this library and travels with it.

License

MIT — see LICENSE.

Documentation

Index

Constants

View Source
const (
	NoMin = -math.MaxFloat64
	NoMax = math.MaxFloat64
)

NoMin and NoMax mark the range of numeric parameters whose exposes don't document one; the range is then wide enough to never clamp anything.

Variables

This section is empty.

Functions

func Ask

func Ask[T any](c *Client, f func() T) (result T, ok bool)

Ask runs f on the event loop and returns its result — the synchronous complement of Do for off-loop code (an HTTP handler, for example) that needs a value computed from parameter state. It blocks the calling goroutine until the result is available. Never call Ask from the event loop itself: it would block the loop waiting on its own result; on the loop, read state directly. After Stop, Ask returns the zero value and ok=false instead of blocking.

func DataDir

func DataDir() (string, error)

DataDir returns the project's data directory, creating it if needed with ownership matching the project directory.

func OpenData

func OpenData(name string, flag int) (*os.File, error)

OpenData opens the named file inside DataDir, creating it if needed with ownership matching the project directory. flag is as in os.OpenFile (os.O_CREATE is implied); the caller closes the file.

func ParamAs

func ParamAs[P any](d *Device, property string) (P, bool)

ParamAs looks up a device parameter by its Zigbee2MQTT property name and type-asserts it to P — a concrete parameter type, or a capability interface such as interface{ Set(bool) }, which matches every settable binary variant. Use it to iterate devices and act on whichever ones carry a given capability. A property the device doesn't have returns false; using the returned value is fully type-checked.

Types

type BinaryParam

type BinaryParam struct {
	// contains filtered or unexported fields
}

BinaryParam is a read-only on/off value reported by a device. valueOn and valueOff hold the wire representations Zigbee2MQTT uses, e.g. "ON"/"OFF".

func NewBinaryParam

func NewBinaryParam(h ParamHost, property string, valueOn, valueOff json.RawMessage) *BinaryParam

NewBinaryParam is called by generated code.

func (*BinaryParam) Get

func (p *BinaryParam) Get() (value T, ok bool)

Get returns the last value the device reported. ok is false until the device has reported one. (Settable variants shadow this with the effective-value Get.)

func (*BinaryParam) OnChange

func (p *BinaryParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*BinaryParam) OnReport

func (p *BinaryParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client owns the MQTT connection and the event loop. All parameter callbacks and the onReady callback run on the event loop goroutine, so automation code never needs its own locking.

func NewClient

func NewClient(configPath string) (*Client, error)

NewClient loads the config and prepares (but does not open) the connection. Generated code calls this from NewDevices.

func (*Client) All

func (c *Client) All() []*Device

All returns every device sorted by friendly name — the iteration surface for capability-based automation via ParamAs. The device set is fixed at construction, so this is safe from any goroutine.

func (*Client) Config

func (c *Client) Config() *Config

Config returns the loaded configuration.

func (*Client) Do

func (c *Client) Do(f func())

Do posts f to the event loop, where all parameter state is owned — inside f, Get/Set/Query/OnChange registration are all safe. Safe to call from any goroutine; it is the primitive under Timer and the escape hatch for off-loop event sources. After Stop, f is silently dropped.

func (*Client) Every

func (c *Client) Every(period time.Duration, f func()) *Timer

Every runs f on the event loop repeatedly; the first run happens one period after the call. Start timers in the Run callback or in parameter callbacks. period must be positive.

func (*Client) Run

func (c *Client) Run(onReady func()) error

Run connects to the broker, subscribes to the device state topics and runs the event loop until SIGINT/SIGTERM or Stop. onReady runs on the event loop once the connection is up; note that device states reported before Run may not have arrived yet at that point, so Get can still return ok=false.

func (*Client) Serve

func (c *Client) Serve(addr string, handler http.Handler) error

Serve starts an HTTP server on addr serving handler, tied to the client's lifetime: when Run returns — on a signal or after Stop — the server shuts down, briefly draining in-flight requests. The listener is bound before Serve returns, so an unavailable address is an ordinary error at the call site rather than a background log line.

Handlers run on their own goroutines, like any net/http server; use Do and Ask to reach parameter state. May be called before Run or from the Run callback, and more than once for multiple servers.

func (*Client) Stop

func (c *Client) Stop()

Stop makes Run return. Safe to call from any goroutine, more than once.

type Composite

type Composite struct {
	// contains filtered or unexported fields
}

Composite is the runtime core of generated composite parameters — a parameter whose value is a JSON object of sub-parameters, like a light's color_xy. It is both a parameter of its host (state objects route into it) and a ParamHost for its sub-parameters (their set requests are wrapped into the nested shape Zigbee2MQTT expects, e.g. {"color": {"x": 0.3}}). Composites nest recursively.

func NewComposite

func NewComposite(h ParamHost, property string) *Composite

NewComposite is called by generated code.

func (*Composite) Property

func (c *Composite) Property() string

Property returns the Zigbee2MQTT property name, e.g. "color".

type Config

type Config struct {
	Host      string
	Port      int
	BaseTopic string
}

Config holds the contents of a project's config.toml.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig reads a config.toml. Only the TOML subset the documented config file uses is accepted: comments, a single [mqtt_server] section, quoted strings and integers. Unknown sections and keys are errors so that typos fail loudly instead of being ignored.

func (*Config) BrokerURL

func (c *Config) BrokerURL() string

BrokerURL returns the broker address in the form paho expects.

type Device

type Device struct {
	FriendlyName string
	// contains filtered or unexported fields
}

Device is the runtime core of every generated device type: it ties the device's parameters to its Zigbee2MQTT topics. It implements ParamHost.

func NewDevice

func NewDevice(c *Client, friendlyName string) *Device

NewDevice is called by generated code.

func (*Device) Param

func (d *Device) Param(property string) any

Param returns the full-capability parameter value registered under the given Zigbee2MQTT property name, or nil. Usually used through ParamAs.

type EnumParam

type EnumParam[T comparable] struct {
	// contains filtered or unexported fields
}

EnumParam is a read-only parameter whose value comes from a fixed set. T is an enum type generated per value set: an opaque struct whose values can only be named through the generated package-level constants, so automation code cannot produce an invalid value — the compiler rejects strings and everything else. The one value Go cannot exclude at compile time is T's zero value; Set refuses it at runtime with a log message.

func NewEnumParam

func NewEnumParam[T comparable](h ParamHost, property string, wires []string, values []T) *EnumParam[T]

NewEnumParam is called by generated code. wires and values run parallel: wires[i] is the Zigbee2MQTT string for values[i].

func (*EnumParam) Get

func (p *EnumParam) Get() (value T, ok bool)

Get returns the last value the device reported. ok is false until the device has reported one. (Settable variants shadow this with the effective-value Get.)

func (*EnumParam) OnChange

func (p *EnumParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*EnumParam) OnReport

func (p *EnumParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*EnumParam[T]) Values

func (p *EnumParam[T]) Values() []T

Values returns all values the device documents, in the device's order.

type NumericParam

type NumericParam struct {
	// contains filtered or unexported fields
}

NumericParam is a read-only numeric value reported by a device. Writable numeric parameters are generated as SettableNumericParam.

func NewNumericParam

func NewNumericParam(h ParamHost, property string, min, max float64) *NumericParam

NewNumericParam is called by generated code.

func (*NumericParam) Get

func (p *NumericParam) Get() (value T, ok bool)

Get returns the last value the device reported. ok is false until the device has reported one. (Settable variants shadow this with the effective-value Get.)

func (*NumericParam) Max

func (p *NumericParam) Max() float64

Max returns the upper end (inclusive) of the documented range, or NoMax.

func (*NumericParam) Min

func (p *NumericParam) Min() float64

Min returns the lower end (inclusive) of the documented range, or NoMin.

func (*NumericParam) OnChange

func (p *NumericParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*NumericParam) OnReport

func (p *NumericParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

type ParamHost

type ParamHost interface {
	// contains filtered or unexported methods
}

ParamHost is implemented by Device and Composite: anything that owns parameters, routes state updates to them and stages their set and get requests toward the device topics. The interface is sealed — its methods are unexported on purpose, only ferenchome_lib types implement it.

type QueryableBinaryParam

type QueryableBinaryParam struct {
	BinaryParam
}

QueryableBinaryParam is a BinaryParam that can be queried.

func NewQueryableBinaryParam

func NewQueryableBinaryParam(h ParamHost, property string, valueOn, valueOff json.RawMessage) *QueryableBinaryParam

NewQueryableBinaryParam is called by generated code.

func (*QueryableBinaryParam) Get

func (p *QueryableBinaryParam) Get() (value T, ok bool)

Get returns the last value the device reported. ok is false until the device has reported one. (Settable variants shadow this with the effective-value Get.)

func (*QueryableBinaryParam) OnChange

func (p *QueryableBinaryParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*QueryableBinaryParam) OnReport

func (p *QueryableBinaryParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*QueryableBinaryParam) Query

func (p *QueryableBinaryParam) Query()

Query asks the device to report the current value. The response arrives like any state update: Get returns it and OnChange callbacks fire.

type QueryableEnumParam

type QueryableEnumParam[T comparable] struct {
	EnumParam[T]
}

QueryableEnumParam is an EnumParam that can be queried.

func NewQueryableEnumParam

func NewQueryableEnumParam[T comparable](h ParamHost, property string, wires []string, values []T) *QueryableEnumParam[T]

NewQueryableEnumParam is called by generated code.

func (*QueryableEnumParam) Get

func (p *QueryableEnumParam) Get() (value T, ok bool)

Get returns the last value the device reported. ok is false until the device has reported one. (Settable variants shadow this with the effective-value Get.)

func (*QueryableEnumParam) OnChange

func (p *QueryableEnumParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*QueryableEnumParam) OnReport

func (p *QueryableEnumParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*QueryableEnumParam[T]) Query

func (p *QueryableEnumParam[T]) Query()

Query asks the device to report the current value. The response arrives like any state update: Get returns it and OnChange callbacks fire.

type QueryableNumericParam

type QueryableNumericParam struct {
	NumericParam
}

QueryableNumericParam is a NumericParam whose device can be asked for the current value (Zigbee2MQTT access bit 4). Generated code uses the Queryable types only for parameters that document that bit — on any other parameter, Query doesn't exist and calling it is a compile error.

func NewQueryableNumericParam

func NewQueryableNumericParam(h ParamHost, property string, min, max float64) *QueryableNumericParam

NewQueryableNumericParam is called by generated code.

func (*QueryableNumericParam) Get

func (p *QueryableNumericParam) Get() (value T, ok bool)

Get returns the last value the device reported. ok is false until the device has reported one. (Settable variants shadow this with the effective-value Get.)

func (*QueryableNumericParam) OnChange

func (p *QueryableNumericParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*QueryableNumericParam) OnReport

func (p *QueryableNumericParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*QueryableNumericParam) Query

func (p *QueryableNumericParam) Query()

Query asks the device to report the current value. The response arrives like any state update: Get returns it and OnChange callbacks fire.

type QueryableToggleableBinaryParam

type QueryableToggleableBinaryParam struct {
	ToggleableBinaryParam
}

QueryableToggleableBinaryParam is a ToggleableBinaryParam that can also be queried.

func NewQueryableToggleableBinaryParam

func NewQueryableToggleableBinaryParam(h ParamHost, property string, valueOn, valueOff, valueToggle json.RawMessage) *QueryableToggleableBinaryParam

NewQueryableToggleableBinaryParam is called by generated code.

func (*QueryableToggleableBinaryParam) OnChange

func (p *QueryableToggleableBinaryParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*QueryableToggleableBinaryParam) OnReport

func (p *QueryableToggleableBinaryParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*QueryableToggleableBinaryParam) Query

func (p *QueryableToggleableBinaryParam) Query()

Query asks the device to report the current value. The response arrives like any state update: Get returns it and OnChange callbacks fire.

type SettableBinaryParam

type SettableBinaryParam struct {
	BinaryParam
}

SettableBinaryParam is a BinaryParam that can also be written.

func NewSettableBinaryParam

func NewSettableBinaryParam(h ParamHost, property string, valueOn, valueOff json.RawMessage) *SettableBinaryParam

NewSettableBinaryParam is called by generated code.

func (*SettableBinaryParam) Get

func (p *SettableBinaryParam) Get() (value bool, ok bool)

Get returns the effective value: a fresh requested value until the device answers (or the optimism window expires), the reported value otherwise.

func (*SettableBinaryParam) Invalidate

func (p *SettableBinaryParam) Invalidate()

Invalidate discards the requested state so the next Set publishes unconditionally — for device quirks where a parameter changes without a report.

func (*SettableBinaryParam) OnChange

func (p *SettableBinaryParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*SettableBinaryParam) OnReport

func (p *SettableBinaryParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*SettableBinaryParam) Reported

func (p *SettableBinaryParam) Reported() (value bool, ok bool)

Reported returns the strictly-observed view: what the device last said, never a requested value.

func (*SettableBinaryParam) Set

func (p *SettableBinaryParam) Set(on bool)

Set asks the device to change the value. Sets are deduplicated against the effective value, coalesced within a callback and batched per device.

type SettableEnumParam

type SettableEnumParam[T comparable] struct {
	EnumParam[T]
}

SettableEnumParam is an EnumParam that can also be written.

func NewSettableEnumParam

func NewSettableEnumParam[T comparable](h ParamHost, property string, wires []string, values []T) *SettableEnumParam[T]

NewSettableEnumParam is called by generated code.

func (*SettableEnumParam[T]) Get

func (p *SettableEnumParam[T]) Get() (value T, ok bool)

Get returns the effective value: a fresh requested value until the device answers (or the optimism window expires), the reported value otherwise.

func (*SettableEnumParam[T]) Invalidate

func (p *SettableEnumParam[T]) Invalidate()

Invalidate discards the requested state so the next Set publishes unconditionally — for device quirks where a parameter changes without a report.

func (*SettableEnumParam) OnChange

func (p *SettableEnumParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*SettableEnumParam) OnReport

func (p *SettableEnumParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*SettableEnumParam[T]) Reported

func (p *SettableEnumParam[T]) Reported() (value T, ok bool)

Reported returns the strictly-observed view: what the device last said, never a requested value.

func (*SettableEnumParam[T]) Set

func (p *SettableEnumParam[T]) Set(v T)

Set asks the device to change the value. The type of v makes invalid values a compile error; the only runtime refusal left is T's zero value, which Go cannot exclude at compile time. Sets are deduplicated against the effective value, coalesced within a callback and batched per device.

type SettableNumericParam

type SettableNumericParam struct {
	NumericParam
}

SettableNumericParam is a NumericParam that can also be written.

func NewSettableNumericParam

func NewSettableNumericParam(h ParamHost, property string, min, max float64) *SettableNumericParam

NewSettableNumericParam is called by generated code.

func (*SettableNumericParam) Get

func (p *SettableNumericParam) Get() (value float64, ok bool)

Get returns the effective value: a fresh requested value until the device answers (or the optimism window expires), the reported value otherwise. This is what makes fan-out control immediate — a follower reading a just-Set master sees the new value without a Zigbee round-trip.

func (*SettableNumericParam) Invalidate

func (p *SettableNumericParam) Invalidate()

Invalidate discards the requested state so the next Set publishes unconditionally — for device quirks where a parameter changes without a report.

func (*SettableNumericParam) OnChange

func (p *SettableNumericParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*SettableNumericParam) OnReport

func (p *SettableNumericParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*SettableNumericParam) Reported

func (p *SettableNumericParam) Reported() (value float64, ok bool)

Reported returns the strictly-observed view: what the device last said, never a requested value.

func (*SettableNumericParam) Set

func (p *SettableNumericParam) Set(v float64)

Set asks the device to change the value, clamped to the documented range. Sets are deduplicated against the effective value, coalesced within a callback and batched per device — identical re-Sets cost nothing.

type SettableQueryableBinaryParam

type SettableQueryableBinaryParam struct {
	SettableBinaryParam
}

SettableQueryableBinaryParam is a SettableBinaryParam that can also be queried.

func NewSettableQueryableBinaryParam

func NewSettableQueryableBinaryParam(h ParamHost, property string, valueOn, valueOff json.RawMessage) *SettableQueryableBinaryParam

NewSettableQueryableBinaryParam is called by generated code.

func (*SettableQueryableBinaryParam) OnChange

func (p *SettableQueryableBinaryParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*SettableQueryableBinaryParam) OnReport

func (p *SettableQueryableBinaryParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*SettableQueryableBinaryParam) Query

func (p *SettableQueryableBinaryParam) Query()

Query asks the device to report the current value. The response arrives like any state update: Get returns it and OnChange callbacks fire.

type SettableQueryableEnumParam

type SettableQueryableEnumParam[T comparable] struct {
	SettableEnumParam[T]
}

SettableQueryableEnumParam is a SettableEnumParam that can also be queried.

func NewSettableQueryableEnumParam

func NewSettableQueryableEnumParam[T comparable](h ParamHost, property string, wires []string, values []T) *SettableQueryableEnumParam[T]

NewSettableQueryableEnumParam is called by generated code.

func (*SettableQueryableEnumParam) OnChange

func (p *SettableQueryableEnumParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*SettableQueryableEnumParam) OnReport

func (p *SettableQueryableEnumParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*SettableQueryableEnumParam[T]) Query

func (p *SettableQueryableEnumParam[T]) Query()

Query asks the device to report the current value. The response arrives like any state update: Get returns it and OnChange callbacks fire.

type SettableQueryableNumericParam

type SettableQueryableNumericParam struct {
	SettableNumericParam
}

SettableQueryableNumericParam is a SettableNumericParam that can also be queried.

func NewSettableQueryableNumericParam

func NewSettableQueryableNumericParam(h ParamHost, property string, min, max float64) *SettableQueryableNumericParam

NewSettableQueryableNumericParam is called by generated code.

func (*SettableQueryableNumericParam) OnChange

func (p *SettableQueryableNumericParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*SettableQueryableNumericParam) OnReport

func (p *SettableQueryableNumericParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*SettableQueryableNumericParam) Query

func (p *SettableQueryableNumericParam) Query()

Query asks the device to report the current value. The response arrives like any state update: Get returns it and OnChange callbacks fire.

type Timer

type Timer struct {
	// contains filtered or unexported fields
}

Timer runs a function periodically on the event loop, so timed automation code can call Get and Set like any callback. Create one with Client.Every; Stop and Start may be called from any goroutine.

func (*Timer) Start

func (t *Timer) Start(period time.Duration)

Start (re)starts the timer with the given period, replacing any previous schedule — restarting on every trigger is the debounce idiom.

func (*Timer) Stop

func (t *Timer) Stop()

Stop stops the timer. Idempotent. A callback that was already posted to the event loop may still run once after Stop returns.

type ToggleableBinaryParam

type ToggleableBinaryParam struct {
	SettableBinaryParam
	// contains filtered or unexported fields
}

ToggleableBinaryParam is a SettableBinaryParam whose device also documents a toggle command (e.g. "TOGGLE"). The device flips the value itself, so Toggle works even before the first state report arrives. Generated code uses this type only when the device documents value_toggle — on a device that can't toggle, the method doesn't exist and calling it is a compile error.

func NewToggleableBinaryParam

func NewToggleableBinaryParam(h ParamHost, property string, valueOn, valueOff, valueToggle json.RawMessage) *ToggleableBinaryParam

NewToggleableBinaryParam is called by generated code.

func (*ToggleableBinaryParam) OnChange

func (p *ToggleableBinaryParam) OnChange(f func(T))

OnChange registers f to run on the event loop whenever the effective value changes — whether a device report or a local Set caused it (local Sets fire coalesced, at flush, with the final value; a suppressed Set fires nothing, which is what makes feedback patterns terminate at their fixpoint). OnChange makes no promise about transient values; use OnReport for event-style parameters. Register callbacks before Run.

func (*ToggleableBinaryParam) OnReport

func (p *ToggleableBinaryParam) OnReport(f func(T))

OnReport registers f to run on the event loop for every device report, changed or not, never coalesced — the right listener for event-style parameters like a remote's action, where pressing the same button twice must be observed twice. On a changing report, OnChange callbacks run first. Register callbacks before Run.

func (*ToggleableBinaryParam) Toggle

func (p *ToggleableBinaryParam) Toggle()

Toggle asks the device to flip the value. It joins the per-device batch but bypasses deduplication — its outcome is unknowable — and marks the parameter stale, so a following Set publishes regardless.

Directories

Path Synopsis
cmd
generate command
generate connects to the MQTT broker from config.toml, waits for Zigbee2MQTT's retained <base_topic>/bridge/devices message and writes the ferenchome_types package into the target directory.
generate connects to the MQTT broker from config.toml, waits for Zigbee2MQTT's retained <base_topic>/bridge/devices message and writes the ferenchome_types package into the target directory.
internal
codegen
Package codegen turns a Zigbee2MQTT bridge/devices payload into the source of a ferenchome_types package.
Package codegen turns a Zigbee2MQTT bridge/devices payload into the source of a ferenchome_types package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL