MQTT

From ago control wiki
Jump to: navigation, search

Contents

MQTT

About

MQTT (Wikipedia, MQTT.org) is a publisher/subscriber architecture centred around a message broker (e.g. mosquitto). Data is exchanged on so called topics. Clients can publish data to a topic, and also subscribe to a topic to be notified when new information is available.

It is very lightweight and thus suited well for embedded clients. A popular application sports the ESP8266 as sensor, publishing its sensor data to the broker.

Support

ago control supports MQTT via the agomqtt plug-in.

You can specify a topic (covering multiple sensors using wild-cards) in the configuration file. ago control will subscribe to that topic and tries to match the topic string for respective sensor values. Values are assumed to be SI units of type float.

The default configuration supports temperature, humidity and pressure (which are also the strings matched). See the configuration for a detailed explanation.

Configuration settings

The default configuration found in conf.d/mqtt.conf is as follows:

[mqtt]
broker = 127.0.0.1
port = 1883

# quoting hash character does not work with the augeas version shipped on wheezy
#topic = "sensors/#"

# user defined topic mappings
# SYNTAX: mapping = topic:sensortype:event:unit[;topic:sensortype:event:unit[;...]]
#mapping = supply:energysensor:event.environment.energychanged:V

broker sets the address of the broker to connect to. If the broker is running on the same machine the address of 127.0.0.1 (localhost) is an acceptable choice.

port sets the port the MQTT daemon is listening on. The default port is 1883 for MQTT.

topic is the MQTT topic to subscribe to. Some topic examples can be found on this mosquitto manual page. The default configuration subscribe to the sensors/# topic. So every node below sensors is subscribed to. Please read on, how topic data is acquired.

mapping allows additional mappings between topics and sensor types. As MQTT provides no information on the content of its information, it is inferred by the topic name. As stated at the beginning, temperature, humidity and pressure sensors are supported. By 'supported', any topic containing the text temperature, humidity and pressure will be assumed to be of the type (in ago control terms) temperaturesensor, humiditysensor and barometersensor.

User defined topic mappings

If you want to connect e.g. a voltage sensor, you need to specify the match manually as it is not supported out of the box. This is were the mapping setting comes into play. The example shown in the configuration (for a voltage sensor) can be read as follows (parts are separated by a colon ':'):

# topic:sensortype:event:unit[;topic:sensortype:event:unit[;...]]
mapping = supply:energysensor:event.environment.energychanged:V

topic is the match string for the topic. So every topic containing the string supply will be matched like:

/sensors/node/supply
/sensors/node/supply_voltage

sensortype denotes the type of sensor. Pick one of the supported sensors which matches your needs. A good place to look for a list of supported sensor is /opt/agocontrol/html/templates/devices. This example is using the energysensor type, which displays a nice gauge.

event is the event to send internally. The example emits an event of type event.environment.energychanged.

unit is the unit to be used for the sensor values. As a voltage sensor shall be configured, the unit to be used is V ('Volts', just in case).

Multiple mappings can be listed by separating them by a semi-colon ';'.

Limitations

As MQTT clients can publish any time and the plug-in can only be aware of nodes which have published to the subscribed topic after the plug-in was started, nodes become only visible after they have published. This may be confusing when using the plug-in the first time, as sensors become only visible later on.

This is also true if sensors are already configured in ago control and have not yet reported after the system was restarted.

In order to improve the situation on already configured sensors, the plug-in keeps tracks of sensors which have published via MQTT. The list is stored on plug-in exit in the ago control state directory (e.g. located at /var/opt/agocontrol) as mqtt_devices.json. On plug-in start, the list is read and all devices are announced to ago control in a stale state. Once a new value is published the device will resume.

Example trace output

2015-03-25 13:47:19,032 AgoMQTT    DEBUG Paho log: 16 Received PUBLISH (d0, q0, r0, m0, 'sensors/ESP8266-10202889/temperature', ...  (4 bytes)
2015-03-25 13:47:19,033 AgoMQTT    INFO  Received MQTT message on topic sensors/ESP8266-10202889/temperature: 24.9
2015-03-25 13:47:19,033 AgoConnection TRACE Sending message [sub=event.device.announce]: {'instance': 'mqtt', 'handled-by': 'mqtt', 'devicetype': 'temperaturesensor', 'uuid': 'b7a94873-4656-4572-b337-284a871f8056', 'internalid': 'sensors/ESP8266-10202889/temperature'}

Further plans

  • Add out-of the box support for more device types
  • Implement regular expression matching for topic and value
  • Implement publishing to topics (e.g. for switches)
Personal tools