Difference between revisions of "Plugin:MQTT"

Revision as of 00:53, 22 January 2016

The MQTT plugin transmits or receives values collected by collectd via the MQTT protocol. MQTT is a "light weight" publish-subscribe messaging protocol for use on top of the TCP/IP protocol. Data is sent to or received from a MQTT Server, also known as a message broker. The values are encoded and parsed in the plain text protocol. It is possible to use three different levels of Quality of Service (QoS), which offer different levels of assurance that the message will be delivered.

Synopsis

<Plugin "mqtt">
  # Send values to an MQTT server
  <Publish "some_name">
    Host "localhost"
#   Port "1883"
#   User "mqttuser"
#   Password "password"
#   ClientId "collectd-hostname"
#   QoS 0
#   Prefix "collectd"
#   Retain true
#   StoreRates false
  </Publish>
  
  # Receive values from an MQTT server
  <Subscribe "some_name">
    Host "localhost"
#   Port "1883"
#   User "mqttuser"
#   Password "password"
#   ClientId "collectd-hostname"
#   QoS 0
#   CleanSession false
#   Topic "subscribetopic"
  </Subscribe>
</Plugin>

The plugin's configuration is in Publish and/or Subscribe blocks, configuring the sending and receiving direction respectively. The plugin will register a write callback named "mqtt/name" where name is the string argument given to the Publish block. Both types of blocks share many but not all of the following options. If an option is valid in only one of the blocks, it will be mentioned explicitly.

Options

Host Hostname

Hostname of the MQTT broker to connect to.

Port Service

Port number or service name of the MQTT broker to connect to.

User UserName

Username used when authenticating to the MQTT broker.

Password Password

Password used when authenticating to the MQTT broker.

ClientId ClientId

MQTT client ID to use. Defaults to the hostname used by collectd.

QoS [0-2]

Sets the Quality of Service, with the values 0, 1 and 2 meaning:

0 At most once

1 At least once

2 Exactly once

In Publish blocks, this option determines the QoS flag set on outgoing messages and defaults to 0. In Subscribe blocks,

determines the maximum QoS setting the client is going to accept and defaults to 2. If the QoS flag on a message is larger

than the maximum accepted QoS of a subscriber, the message's QoS will be downgraded.

Prefix Prefix (Publish only)

This plugin will use one topic per value list which will looks like a path. Prefix is used as the first path element and defaults to collectd.

An example topic name would be:

collectd/cpu-0/cpu-user

Retain false|true (Publish only)

Controls whether the MQTT broker will retain (keep a copy of) the last message sent to each topic and deliver it to new subscribers. Defaults to false.

StoreRates true|false (Publish only)

Controls whether "DERIVE" and "COUNTER" metrics are converted to a rate before sending. Defaults to true.

CleanSession true|false (Subscribe only)

Controls whether the MQTT "cleans" the session up after the subscriber disconnects or if it maintains the subscriber's

subscriptions and all messages that arrive while the subscriber is disconnected. Defaults to true.

Topic TopicName (Subscribe only)

Configures the topic(s) to subscribe to. You can use the single level "+" and multi level "#" wildcards. Defaults to

collectd/#, i.e. all topics beneath the collectd branch.

Publish Example

This is an example of publishing from collectd and then subscribing using the mosquitto command line tools.

Add the following configuration to collectd.conf:

<Plugin "mqtt">
   <Publish "name1">
     Host "localhost"
     Prefix "collectd"
     Retain true
   </Publish>
</Plugin>

Start a MQTT server (such as mosquitto) on the same machine.

Then subscribe using mosquitto_sub and you should start seeing pairs of topic names and MQTT payloads, separated by a space:

 $ mosquitto_sub -t 'collectd/#' -v
 collectd/bob/memory/memory-wired 1448840558.555:1714962432
 collectd/bob/memory/memory-active 1448840558.555:9526575104
 collectd/bob/memory/memory-inactive 1448840558.555:4316172288
 collectd/bob/memory/memory-free 1448840558.555:871038976
 collectd/bob/memory/memory-wired 1448840568.206:1888133120
 collectd/bob/memory/memory-inactive 1448840568.206:4315336704
 collectd/bob/memory/memory-free 1448840568.206:853004288
 collectd/bob/memory/memory-active 1448840568.206:9373102080

The payload is a serialised Value list of one or more values separated by colons, depending on the Type. The first number is always the UNIX timestamp for the value(s).

See Plain Text Protocol for more detailed information.

Subscribe Example

This is an example of publishing from mosquitto_pub command line tool and then subscribing using to it using collectd.

Add the following configuration to collectd.conf:

<Plugin "mqtt">
   <Subscribe "name2">
     Host "localhost"
     Topic "incoming/#"
     CleanSession true
   </Publish>
</Plugin>

Start a MQTT server (such as mosquitto) on the same machine.

Then publish using mosquitto_pub and you collectd should receive and persist the values.

 $ mosquitto_pub -t 'incoming/localhost/mqtt/temperature-kitchen' -m 'N:21.5'

The payload is a serialised Value list of one or more values separated by colons, depending on the Type. Values are always prefixed with a Unix timestamp but you can use 'N' instead of a timestamp, which is interpreted as 'now'. You can submit an undefined GAUGE value by using 'U'. See Plain Text Protocol for more information.

The topic name (after the prefix) follows the following format:

 <host>/<plugin>-<plugin_instance>/<type>-<type_instance>

• <host> can be the name of the device the data is from
• <plugin> can be anything, but should probably be the name of the source
• <plugin_instance> the instance name of the source (optional)
• <type> the name of the data type - must be listed in types.db(5)
• <type_instance> a qualifier for the type - free text (optional)

See Naming schema for more details about the path structure.

Dependencies

• libmosquitto
• A MQTT Server

See also

• The Mosquitto homepage