Skip to content

MQTT Persistence

Greg EVA edited this page May 11, 2015 · 6 revisions

Documentation of the MQTT Persistence Service


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.


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.


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.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: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.

feature overview


Setup intro

Linux and OS X





User Interfaces



(link to openHAB forum)



Application Integration



A good source of inspiration and tips from users gathered over the years. Be aware that things may have changed since they were written and some examples might not work correctly.

Please update the wiki if you do come across any out of date information.

Binding configurations

Use case examples

Item definition examples

Sitemap definition examples

Collections of Rules on a single page

Single Rules


Syntax highlighting for external editors

Release Notes

Clone this wiki locally
You can’t perform that action at this time.