MQTT Persistence

Documentation of the MQTT Persistence Service

Introduction

This service allows you to feed item states to an MQTT broker using the openHAB persistence strategies. The destination broker, topic and messages are configurable.

Note: The service only supports sending information, not retrieving information.

Installation

For installation of this persistence package please follow the same steps as you would Bindings.

Additionally, create a persistence file 'mqtt.persist' in the ${openhab.home}/configuration/persistence folder. The file should follow the regular openHAB persistence format.

Configuration

This persistence service can be configured in the "MQTT Persistence Service" section in openhab.cfg.

The MQTT persistence can be configured with the following properties:

Property	Description
mqtt-persistence:broker	The name of the broker as defined in the mqtt:<broker>.url. See the [MQTTBinding] for more information on how to configure MQTT broker connections.
mqtt-persistence:topic	The MQTT topic to which the persistence messages should be sent. This string may include parameters, see table below.
mqtt-persistence:message	A string representing the persistence message content. This string may include parameters, see table below.

Both the topic and message values are reformatted using String.format at the time of publishing. During this reformat, the following parameters are provided to the format function:

Parameter	Description
1$	Item name.
2$	Item alias as defined in the mqtt.persist file.
3$	Item state. A string representation of the item state. ON/OFF, OPEN/CLOSED and UP/DOWN states are transformed to 1/0 values respectively.
4$	Current DateTime in long format.

All item and timing related configuration is done in the mqtt.persist file using the standard Persistence.

Example Configuration for Xively

The following is an example configuration that can be used to persist item states with Xively using the csv format. The messages sent to Xively will have the format <openhab_item>, For example: light_office, 1

First, we need to define the MQTT broker connection in the openhab.cfg file:

    mqtt:xively.url=tcp://api.xively.com:1883
    mqtt:xively.user=<device key>
    mqtt:xively.pwd=<device key>

As <device key>, use the device/API key you get from Xively.

Next, we need to configure the MQTT persistence service. To do this add the following entries to openhab.cfg:

    mqtt-persistence:broker=xively
    mqtt-persistence:topic=/v2/feeds/<feed id>.csv
    mqtt-persistence:message=%1$s, %3$s

where <feed id> is your Xively feed id.

And finally, add a persistence strategy in the mqtt.persist file:

Strategies {
        everyHour : "0 0 * * * ?"
        default = everyChange
}
Items {
        // persist all items every hour and on every change
        * : strategy = everyChange, everyHour
}

With this configuration, all items will persisted whenever their state changes and once per hour.