Homie.lua

• Index

Contents

• Functions
• Fields

Modules

• homie.controller
• homie.device
• homie.utils

Topics

• LICENSE
• README

Examples

• example.lua

Module homie.device

Homie device implementation.

This consists of a Device instance which can contain Node instances, which in turn can hold Property instances.

The device implementation will take care of homie related specifics.

Functions

Device.new (opts)	Instantiate a new Homie device.
Device:__init ()	Initializer, called upon instantiation.
Device:send_property_update (topic, pvalue[, retained])	Send an MQTT message with the value update.
Device:set_state (newstate[, timeout=30])	Sets a device state.
Device:start ()	Starts the device.
Device:stop ()	Stops the device cleanly.
Device:verify_initial_values ()	Method to verify initial values.
Property:get ()	Gets the current value.
Property:pack (value)	Serializes a value to send over MQTT.
Property:rset (pvalue)	Called when remotely setting the value, through the MQTT topic.
Property:set (value[, remote=false])	Local application code can set a value through this method.
Property:unpack (value)	Deserializes a value received over MQTT.
Property:update (value[, force=false])	Validates the value and updates Property.value.
Property:validate (value)	Checks an (unpacked) value.
Property:values_same (value1, value2)	Compares 2 (unpacked) values for equality.

Fields

Device.base_topic	The device base-topic; domain + device id (string, read-only).
Device.broadcast	Hash-table with broadcast handler functions, indexed by their broadcast topic (read-only).
Device.broker_state	Recover device state from the broker?
Device.domain	The homie domain to use (string, read-only).
Device.extensions	The homie extensions supported by the device (string, read-only).
Device.homie	Homie version implemented by Device (string, read-only).
Device.id	The device id, as it appears in the MQTT topic (string, read-only).
Device.implementation	The homie implementation identifier (string, read-only).
Device.mqtt	The underlying luamqtt device used for the MQTT communications (read-only).
Device.name	The name of the device (string, read-only).
Device.nodes	Hash-table with the Device's nodes indexed by Node.id (read-only).
Device.state	Current device status, see Device.states (string, read-only).
Device.states	Enum table with possible values for Device.state.
Device.uri	The mqtt-broker uri to connect to (string, read-only).
Node.device	The owning Device of the Node (read-only).
Node.id	The node id, as it appears in the MQTT topic (string, read-only).
Node.name	The name of the Node (string, read-only).
Node.properties	Hash-table with the Node's properties indexed by Property.id (read-only).
Node.super	The ancestor class (read-only).
Node.type	The type of the Node (string, read-only).
Property.datatype	The property datatype (string, read-only).
Property.device	The owning Device of the property (read-only).
Property.format	The property format (string, read-only).
Property.id	The property id, as it appears in the MQTT topic (string, read-only).
Property.name	The name of the property (string, read-only).
Property.node	The owning Node of the property (read-only).
Property.retained	Is the property a retained value?
Property.settable	Is the property a settable value?
Property.super	The ancestor class (read-only).
Property.topic	The MQTT topic for the property (string, read-only).
Property.unit	The property unit (string, read-only).
Property.value	The value of the property, do not use.

Functions

Device.new (opts)

Instantiate a new Homie device.

Parameters:

• opts Options table to create the instance from.
  • domain string base domain (default "homie/")
  • id string device id. Defaults to homie-lua-xxxxxxx randomized. (optional)

Returns:

new device object.

Device:__init ()

Initializer, called upon instantiation.

Device:send_property_update (topic, pvalue[, retained])

Send an MQTT message with the value update.

Parameters:

• topic string to post to
• pvalue string the packed/serialized value to send over the wire
• retained boolean the retain flag to use when sending (optional)

Returns:

truthy, or falsy+error

Device:set_state (newstate[, timeout=30])

Sets a device state. Waits for confirmation.

Parameters:

• newstate string any of the Device.states constants.
• timeout number timeout in seconds. (default 30)

Returns:

success+err

Device:start ()

Starts the device. Publishes the homie description topics and subscriptions, recovers state from the broker if set to do so, and sets status to ready. The device will set up keepalives, and will automatically reconnect if there is a failure.

Device:stop ()

Stops the device cleanly. Sets device state to disconnected.

Device:verify_initial_values ()

Method to verify initial values. Can be used to verify values received from broker, or to just initialize values. When this returns the values must be in a consistent state. This is only called on device start, not on reconnects. Default behaviour is to keep existing state

Property:get ()

Gets the current value.

NOTE: during initialization of a device this can return nil!

Returns:

the (unpacked) value

See also:

Property:unpack

Property:pack (value)

Serializes a value to send over MQTT. Override in case of (de)serialization needs. Since this method is only called after Property:validate, it should always succeed. Any reason for not succeeding should be handled when validating.

Parameters:

• value the unpacked value to be serialized into a string

Returns:

packed value (string), or nil+err on failure

See also:

Property:unpack

Property:rset (pvalue)

Called when remotely setting the value, through the MQTT topic. There should be no need to override this method. This executes: Property:unpack, Property:validate, Property:set, in that order. Logs an error if something is wrong, and doesn't change the value in that case.

Parameters:

• pvalue string string, the packed value as received.

Returns:

true or nil+err

See also:

Property:set

Property:set (value[, remote=false])

Local application code can set a value through this method. Default just calls Property:update. Implement actual changing device behaviour here by overriding. When overriding, it should always end by calling Property:update.

Parameters:

• value the (unpacked) value to set
• remote bool if truthy, the change came in over MQTT (via Property:rset) (default false)

Returns:

truthy on success or falsy+error

Property:unpack (value)

Deserializes a value received over MQTT. Override in case of (de)serialization needs.

NOTE: check return values!! nil is a valid value, so check 2nd return value for errors.

Parameters:

• value string string value to unpack/deserialize

Returns:

any type of value (including nil), returns an error string as second value in case of errors.

See also:

Property:unpack

Property:update (value[, force=false])

Validates the value and updates Property.value. Will send the MQTT update message. No need to override.

NOTE: if the property is NOT 'retained', then force will always be set to true.

Parameters:

• value the new (unpacked) value to set
• force bool set to truthy to always send an update, even if unchanged. (default false)

Returns:

true, or nil+error

Property:validate (value)

Checks an (unpacked) value. Base implementation only checks format. Override for more validation checks.

Parameters:

• value the (unpacked) value to validate

Returns:

true if ok, nil+err if not.

Property:values_same (value1, value2)

Compares 2 (unpacked) values for equality. If old and new values are equal, no updates need to be transmitted. If values are unpacked into complex structures override this to check for equality.

Parameters:

• value1 the (unpacked) value to compare with the 2nd
• value2 the (unpacked) value to compare with the 1st

Returns:

boolean

Fields

Device.base_topic

The device base-topic; domain + device id (string, read-only).

Device.broadcast

Hash-table with broadcast handler functions, indexed by their broadcast topic (read-only). The keys (broadcast-topic) will be updated to be fully qualified.

Device.broker_state

Recover device state from the broker? (false|number, read-only). If a number then it is the time (in seconds) to wait for all state to be returned by the broker (start-up delay).

Device.domain

The homie domain to use (string, read-only).

Device.extensions

The homie extensions supported by the device (string, read-only).

Device.homie

Homie version implemented by Device (string, read-only).

Device.id

The device id, as it appears in the MQTT topic (string, read-only).

Device.implementation

The homie implementation identifier (string, read-only).

Device.mqtt

The underlying luamqtt device used for the MQTT communications (read-only).

Device.name

The name of the device (string, read-only).

Device.nodes

Hash-table with the Device's nodes indexed by Node.id (read-only).

Device.state

Current device status, see Device.states (string, read-only). Use Device:set_state to change the value.

Device.states

Enum table with possible values for Device.state.

Device.uri

The mqtt-broker uri to connect to (string, read-only).

Node.device

The owning Device of the Node (read-only).

Node.id

The node id, as it appears in the MQTT topic (string, read-only).

Node.name

The name of the Node (string, read-only).

Node.properties

Hash-table with the Node's properties indexed by Property.id (read-only).

Node.super

The ancestor class (read-only). Usefull when overriding methods, and needing access to the original methods.

Node.type

The type of the Node (string, read-only).

Property.datatype

The property datatype (string, read-only).

Property.device

The owning Device of the property (read-only).

Property.format

The property format (string, read-only).

Property.id

The property id, as it appears in the MQTT topic (string, read-only).

Property.name

The name of the property (string, read-only).

Property.node

The owning Node of the property (read-only).

Property.retained

Is the property a retained value? (boolean, read-only)

Property.settable

Is the property a settable value? (boolean, read-only)

Property.super

The ancestor class (read-only). Usefull when overriding methods, and needing access to the original methods.

Property.topic

The MQTT topic for the property (string, read-only).

Property.unit

The property unit (string, read-only).

Property.value

The value of the property, do not use. Please use Property:get and Property:set to read/write the value.