ChristophCaina / Tinkerforge_MQTT

script that send tinkerforge sensor data in HomeAssistants AutoDiscovery Format to an MQTT Broker
0 stars 0 forks source link

TinkerForge_MQTT

this project is currently at a very early stage of development!

the idea

The idea for this poject came up, when I wanted to integrate some of my older Tinkerforge Hardware into HomeAssistant, for example to Monitor temperature, humidity or air-pressure values.
In combination with the NCF / RFID Tag Reader I have from them, I thought it would be nice to access these things with HomeAssistant - and maybe trigger some other automations or similar with this information.

During the research on how I could implement Tinkerforge into HomeAssistant, I found that Tinkerforge does provide some MQTT Bindings. These bindings are based on the Pyhton bindings, and more or less - a script will be triggered that writes the data to a given MQTT Topic structure.

So, basically you have to setup a System, where these MQTT Bindings can be installed, need to create a Cron job that executes the script, you have to write a configuration for each "sensor" - and, especially, you have to know each individual UID of the device for this configuration

So, at all, you still have to do a lot of work... and then, you also need to configure each sensor or actor in your HomeAssistant MQTT configuration.

I don't want to have this amount of configuration effort in HomeAssistant.
Especially not, when a Tinkerforge Stack could contain different Bricklets - and I don't know their UIDs - or, if I need to change one of the Sensors in the future.

So I came up with the Idea, that I would like to use the HomeAssistants MQTT-Autodiscovery function.
This means, that the MQTT Messages should follow a very specific pattern. And, this should work "dynamically" - meaning, the Software should do everything without the need to know each connected Brick or Bricklet and their UIDs.

Topic structure of the Tinkerforge MQTT bindings:

tinkerforge/response/barometer_bricklet/vNB/get_air_pressure {"air_pressure": 970609}
tinkerforge/response/barometer_bricklet/vNB/get_altitude {"altitude": 49438}

as you can see, the MQTT topics do follow a very "basic" rule - we have the root-topic "tinkerforge".
Followed by the topic "response" - because we receive something from the Brick / Bricklet. The next information is the type of Brick or Bricklet - in this case, it is a barometer bricklet.
If multiple Barometer Bricklets are available, we can identify them by the UID, also given in the topic - and then, finally, we're getting the "function" that was called...

and then, the payload does only include the current value.

This requires a lot of configuration effort in HomeAssistant. Compared to the above, the "expected" MQTT structure for the Auto-discovery from HomeAssistant:

<discovery_prefix>/<component>/[<node_id>/]<object_id>/config

if we apply this to the information we know, the Tinkerforge MQTT Message should be something like that:

homeassistant/sensor/tinkerforge/UID/config

The Payload should then look similar to this:

  {"
     availability_topic":"homeassistant/sensor/tinkerforge/UID/availability",
     "icon":"mdi:icon_to_be_selected",
     "unique_id":"UID+ConnectedUID",
     "unit_of_measurement":"%",
     "device":
     {"
       identifiers":"tinkerforge.barometer_bricklet
       "manufacturer":"tinkerforge",
       "model":"",
       "name":"Barometer Bricklet",
       "sw_version":"2.0.1"
       "hw_version":"2.0"
     },
     "name":"AirPressure",
     "state_topic":"homeassistant/sensor/tinkerforge/UID/state"
   }

the above is just a rough estimation how it could look like and is not yet finallized.

how does it work?

Basically, the Software is enumerating through each connected device to get the UIDs and some other information, like Device Type, Hardware Revision and Firmware version.
Then, it is calling at least some of the documented callbacks - to receive sensors information in a periodic way.
All the information will be then formated and sent over MQTT in a way the Autodetect functionallity from HomeAssistant should detect them and directly creating the corresponding sensors out of the received information.

limitations

at the moment, the software is still on an very early stage.
While it is already possible to collect some of the sensor values (especially some older ones that I own and can test) - it is not yet possible to send them to an MQTT Broker.
Also, it is not yet possible (and I am not sure IF this will possible at all) to send commands to the Bricklets - to controll the device.
For this, I might have to adapt more from the default MQTT bindings - and it is probably related to refactor large parts of the current code.

maybe, this can be added at some point in the future.

requirements

you can install all requirements by using:

$ pip install -r requirements.txt

installation