Definition of Sensors
energy2mqtt wants to be as flexible as possible when adding new sensors. A lot of options are given to the author of those definition files. The definition files are stored in defs/lorawan and should be written in a way that they work with all LoRaWAN Network Servers and cloud instances. This part of the documentation will not speak about downlinks but about how to find the correct mapping and how to interpret data.
Please see Defining Downlinks for information about Downlinks.
Informational part
Each definition file needs to contain a block about the vendor, the product name and a URI with information about that specific device. That information will be used by Home Assistant to build a view of the device. We want to allow other fields, e.g. hardware or software version of the Discovery API to be set using data provided by the parser but that will require reworking the path about how to add devices to Home Assistant in energy2mqtt.
Matching the right device
To send the right definition to Home Assistant we need to make sure to have the right information about the device. LoRaWAN does neither specify a fixed way of encoding payloads nor how to map device classes. Some vendors allow to identify the devices bases on the DevEUI using the first byte after the vendor part of the DevEUI as an identifier. For those devices the matching is quite easy and can be done using regular expressions using the !DevEUI YAML tag. For other sensors the type is included in the parsed payload or the parser knows it and we can use the !DataField YAML tag to verify the correctness. If you want to check for both use !DevAndData. To match against an internal or external product database you may use !ProductId.
A device can be matched using the data of any alias defined, it’s OR not AND. Also the first match wins, no further YAML files are evaluated.
Device Options
Some devices require quirks to be really usable with Home Assistant. The options provide a way to change some default behaviors to fit into the Smart Home ecosystem. The option block is a top level block inside the YAML file:
GPS coordinate handling
Some cloud platforms allow the user to set the position of a device that may help to find those devices again but it will not help for smart home applications and because of that normaly ignore every geo information sent from the platforms. Some devices like tracker have GPS or any other positioning system, for those devices please change has_gps to True.
Sensors sending historical data
Some devices only send data once in an hour or even once per day but include historical data in that transmission. As we are unable to put them into the right time slot in Home Assistant or any other smart home system, we need to ignore them. This setting does not change the behavior of the timing settings found later in this document; it extends them. The test for generated, historical data comes before the timing tests.
If you know a parser may send values from older transmissions, rebuild data or generate substitute values, then set ignore_generated_values to True for the device.
Sensors which allow downlinks
The last flag tells the system to register a callback for the downlink handling of that sensor. That may change in later versions if we can autodetect the need but for set has_command_topic to True for every sensors which is able to receive downlinks.
Required Timings
Timings in a LoRaWAN network can be tricky from time to time. Lots of devices trying to send their data in the same time slot may result in an interruption of the LNS functionality. Some platforms will recover and reparse the data. That is not what we want. We only want to have the latest value for our system.
Therefore we have two options to set the timings for a specific device:
Sensors may fetch their data at one point in time (like 0:00 for consumptions) and send them from 1:00 to 4:00 using a distribution curve to reduce interference with each other. Most platforms allow an eventtime to be set if so we check that one first. If it’s inside the range we allow the telegram even it was reparsed or resend.
The device time is the time from receiving the sensor on the gateway until it is handled by our system. That time defines how fast and powerful your backend is, it should never be greater than some minutes. If it does you may receive an old frame after a newer one. As we do not want check for the frame counter that may lead to wrong timelimes. Checking the frame counter is disabled because it would be the job of the LNS to do so and we do not want to reimplement a REJOIN logic.
Setting the data to be published
In the first part of the development we simply pushed the complete telegram to the MQTT topic but Home Assistant only reads 255 Bytes and fails if the JSON is bigger. Because of that only the values set in the configuration are published. Most implementations add valuable extra information like RSSI and SNR to the data for debugging and testing purposes.
data_fields is a top level option in the definition file. It needs to be present and a config will not be loaded if it’s missing. Each entry of the data_fields needs to include
- name which is the name of the JSON key in the data received from your LNS or cloud platform
- friendly_name which should be an english easy to understand name
The following elements have default values which will be used if you do not specify them:
- platform defaults to sensor, but it will work for binary_sensor, valve and so on
- state_class defaults to measurement, refer to How to choose state_class and last_reset in the Home Assistant documentation
More elements can be used for the different platforms, please refer to our documentation about the supported Home Assistant Platforms. Also lookup how to build Downlinks
The interface of energy2mqtt allows to more options to be set:
- e2m_map_key allows you to override the name of the key to be sent to Home Assistant. We introduced this because some parsers will not provide temperature but temp or use special keys like space in the names of the keys. That will not work with value templates and needed to be addressed. Only use this function if you really need it.
- e2m_persist defaults to True and allows keys which are used for automations to be excluded from the normal storage setup. Otherwise they might retrigger automations of the user.