Generic - Homie receiver¶

Triggers configurable events when data is received form the Homie controller (C014).

Plugin details¶

Type: Generic

Name: Homie receiver

Status: TESTING

Maintainer: .

Introduction¶

This generic Device work together with the Homie controller (C014) Controller - Homie MQTT convention and helps to handle incoming data. According to the Homie convention every value can be announced as “setable” when the $setable flag is true.

ESPEasy initially designed as a sensor firmware receive data via commands. If you need to send data from your controller to a device you have to prepare the command in your controller software and send it to ESPEasy via cmd= or trigger rules by event= and send the command from there. To send values directly this plug-in can be used. It “only” defines the necessary parameters and the Homie controller sends the auto-discover information to the MQTT broker. To translate and direct this information to one or several commands a rule is used.

Setup¶

The Controller - Homie MQTT convention must be installed and enabled. Multiple instances of the plug-in are possible. One instance of the plug-in can define 4 different values / events.

Parameter	Description	used by	3.0.1 & 4.0.0
event name	Name of the event which should be triggered as soon as a value arrives on the `.../%eventName%/set` topic	all	required
minimum	Minimum limits of the value. Suitable for sliders and gauges. If min and max both are 0 no limits will be send.	integer float	optional
maximum	Maximum limits of the value. Suitable for sliders and gauges. If min and max both are 0 no limits will be send.	integer float	optional
decimals	As every data is sent over MQTT is sent as string a number of valid decimals can be specified	integer float	optional
enum values	Comma separated list of possible states, or default text for string values	enum	required for enum

After reboot the controller should receive auto-discover information. Depending on the controller software used correct settings should be selected by default.

Define a rule for every value defined. Every rule should end with the HomieValueSet command to acknowledge the value back to the controller. The value must not necessarily be the same as the sent value (i.e. after extra limit checks). Numeric values are stored in the device. Due to RAM limitations String values are not saved. For some controllers or dataset types it is not necessary to acknowledge the new value. They simply assume that the value arrived and processed correctly. Sometimes it could be useful not to acknowledge the value i.e. for slides sending updates frequently. The value can already be renewed when the acknowledgement arrives causing undesirable results or only to process values faster. For Switches it is essential to acknowledge the set state to keep the user aware of the real state and not the assumed state.

Example Rules for every value / event type¶

// The "homie controller" schedules the event defined in the plug-in.
// Does NOT store string values or arrays in the "homie receiver" plug-in.
// Use homieValueSet to save numeric value in the plugin.
// This will also acknowledge the value back to the controller to get out of "predicted" state.
// Adjust device and event number according to your configuration

On eventInteger do
 // insert your code here
 homieValueSet,1,1,%eventvalue1%
endon

On eventFloat do
 // insert your code here
 homieValueSet,1,2,%eventvalue1%
endon

On eventBoolean do
 // insert your code here
 homieValueSet,1,3,%eventvalue1% // true or false (0/1 is stored in uservar)
endon

On eventString do
 // insert your code here
 homieValueSet,1,4,"%eventvalue%" // quotation requited for Strings!
endon

On eventEnum do
 // insert your code here
 homieValueSet,2,1,%eventvalue2% // name of picked item (number in %eventvalue1% and stored in uservar)
endon

On eventRGB do
 // insert your code here
 NeoPixelAll,%eventvalue1%,%eventvalue2%,%eventvalue3% // example for NeoPixel
 homieValueSet,2,2,%eventvalue1%,%eventvalue2%,%eventvalue3%
endon

On eventHSV do
 // insert your code here
 NeoPixelAllHSV,%eventvalue1%,%eventvalue2%,%eventvalue3% // example for NeoPixel
 homieValueSet,2,3,%eventvalue1%,%eventvalue2%,%eventvalue3%
endon

Examples (coming soon)¶

A sprinkler system switches 8 valves via relays. The relays are connected by PCF8574 port expander.
Color LED using NeoPixel RGB & RGBW (WS2812B or SK6812)

Under the hood¶

The Homie convention defines several value types and some parameters for every value to enable the controller software to send standardized values to Homie enabled devices. Therefore the device has to send $datatype and $format attributes to describe the value type, format and range. This is all done for you by the Controller - Homie MQTT convention according to the settings in this plug-in.

When a message arrives to the .../%deviceName%/%eventName%/set topic an event is triggered. From there commands can be used to perform certain actions. The parameters are passed by %eventvalue% variables:

%eventvalue1% holds the numeric values for float and integer
%eventvalue1% holds the string value for string datatypes
%eventvalue1% holds the number of the selected item of a enumerating list where %eventvalue2% holds the item name
%eventvalue1%, %eventvalue2%, %eventvalue3% holds the intensity values of rgb or hsv color datatypes

Use the command homieValueSet,deviceNr,eventNr,value similar to TaskValueSet or DummieValueSet to acknowledge the received or new value back to the controller.

Datatypes (`$datatype` defaults to `string`)¶

Parameter	Description	UI Element	value example	3.0.1 & 4.0.0
`integer`	Hole numbers (positive or negative). Minimum and maximum limits can be set.	Number Box	1234	required
`float`	Floating point values. Minimum and maximum limits can be set.	Slider / Dimmer	1.123	required
`boolean`	Boolean true or false	switch	true,false	required
`string`	Textual value	text box	display this!	default
`enum`	One item out of a comma seperated list	drop down list	option 1,option 2,option 3	required
`color`	Color value defined by rgb or hsv values. `$fomat` attribute required defining if `rgb` or `hsv` values are expected.	color picker	255,255,255	required

format (`$format` required for color values)¶

Parameter	Description	UI Element	Example	3.0.1 & 4.0.0
`min:max`	Range from min to max for numeric vaues.	gauges and sliders	0:100	optional
`rgb`	Colour value defined by red, green and blue values. Good to have direct control over each LED intensity of an RGB light.	colour picker	255,255,255	required
`hsv`	Color value defined by hue, saturation and value / intensity. Intuitive description of colours independent of the technology producing the colour. Good to drive RGBW LEDs	colour picker	360,100,100	required