TTNMQTT

Introduction

The TTNMQTT hardware module makes it possible to retrieve data from IoT devices that use LoRa radio technology to transmit/receive their data.

Using the network of gateways and backend infrastructure of The Things Network (TTN), this module connects to the MQTT gateway of TTN and collects the payloads from the configured connected devices.

All devices to retrieve data from, need to be part of an 'application' context within TTN and this is the application that has to be configured within the TTNMQTT module.

All devices should send their data using the CayenneLPP Dynamic Payload format.

NOTE: Since Stable release 2022.1 the TTNMQTT module now connects to the Community Edition (v3) of The Things Network and handles the new message format of v3.

Configuration

Using 'Setup' -> 'Hardware', add a new piece of Domoticz hardware.

Give the new Hardware a nice 'Name', for example 'myLoraDevices'

For 'Type' select 'The Things Network (MQTT/CayenneLPP) with LAN interface' from the drop-down list.

Now tell Domoticz where to connect to the correct TTN MQTT gateway that will be used by the application that holds the relevant devices.

The correct 'Remote Address' depends on your region (like 'eu' or 'us' or 'in'), for example 'eu.thethings.network'.

Standard MQTT 'Port' is '1883'

The following information comes from the TTN console and can be found under the 'Application Overview' tab of the selected application.

The 'Username' is the 'Application ID', usually a string for example 'myLoraApp'.

The 'Password' refers to the base-64 encoded key under 'Access Keys'. Often only a 'default key' exists and looks something like 'ttn-account-v2.<bunchofcharactorsandnumbers>'

Don't forget to press 'Add' to actually add the new hardware.

Once created, Domoticz will start the TTNMQTT module and tries to connect to the TTN MQTT gateway. The Log will show if it was successful or not.

If the connection was successful and once new messages come in, Domoticz will try to create the relevant devices. Don't forget to enable 'Accept new hardware devices' (or 'Allow for 5 Minutes' if that is enough time to see the devices) if that is not enabled, otherwise the module cannot add the new devices.

Enjoy your new LoRa devices and sensors in Domoticz :)

Device Payload: CayenneLPP

The module expects the device payload it gets from TTN's MQTT gateway to contain a raw payload which is encoded using the CayenneLPP (v2) Dynamic Payload Format.

It will try to decode the payload and look at the Data Channels and Data Types to determine which sensor the data comes from and what type of sensor the data is from.

Below the list of supported types within CayenneLPP at the moment:

(Data Types are based on the IPSO Alliance Smart Objects Guidelines, which identifies each data type with an “Object ID”.)

#define LPP_DIGITAL_INPUT       0       // 1 byte
#define LPP_DIGITAL_OUTPUT      1       // 1 byte
#define LPP_ANALOG_INPUT        2       // 2 bytes, 0.01 signed
#define LPP_ANALOG_OUTPUT       3       // 2 bytes, 0.01 signed
#define LPP_LUMINOSITY          101     // 2 bytes, 1 lux unsigned
#define LPP_PRESENCE            102     // 1 byte, 1
#define LPP_TEMPERATURE         103     // 2 bytes, 0.1°C signed
#define LPP_RELATIVE_HUMIDITY   104     // 1 byte, 0.5% unsigned
#define LPP_ACCELEROMETER       113     // 2 bytes per axis, 0.001G
#define LPP_BAROMETRIC_PRESSURE 115     // 2 bytes 0.1 hPa Unsigned
#define LPP_UNIXTIME 		133	// 4 bytes, unsigned uint_32_t
#define LPP_GYROMETER           134     // 2 bytes per axis, 0.01 °/s
#define LPP_GPS                 136     // 3 byte lon/lat 0.0001 °, 3 bytes alt 0.01 meter

Important:

Many IoT devices, especially the ones using Radio technology and/or batteries, are considered as 1 Device but often hold more than 1 type of sensor.

This means 1 single device can often send measurements coming from multiple connected sensors. These individual sensor should each have their own 'Data Channel' within the CayenneLPP payload.

The TTNMQTT modules tries to create a Domoticz device for each Data Channel from the received payload.

Note 1: Many encoder libraries often automatically assign a Data Channel, so if you have multiple sensors of the same type, for example if you have two different ANALOG INPUT sensors, they both should have their own Data Channel. Often encoder libraries re-use the same Data Channel effectively overwriting the previous value, so make sure a separate Data Channel is used for each sensor.

Note 2: For some sensor multiple measurements belong together and should be a single device within Domoticz. For example a Bosch BME280 sensor measures temperature, humidity and barometric pressure. If the individual measurements are in a single payload but each have their own Data Channel, these measurement will appear as 3 devices. But if they all use the same Data Channel, as long as they are different Data Types, the TTNMQTT module will create a single device that combine these 3 values.

More information on CayenneLPP can be found here and here and here.