Generic - Homie receiver

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

Plugin details

Type: Generic

Name: Homie receiver

Status: TESTING

GitHub: P086_Homie.ino

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