Note: this is an ongoing support article that's subject to changes as we add more MQTT features to the firmware.

Introduction: From firmware 2.1.9(4), OpenSprinkler has added initial support for MQTT. At the moment of this writing, this feature only supports publishing information to a MQTT broker. You can then use a MQTT client to subscribe to the topics (explained below) to receive such information. Work is under way to enable the firmware to subscribe to a MQTT broker as well, in order to receive commands from a MQTT client.

MQTT Configurations: using the MQTT feature requires mobile app / UI version 2.2.0 or above. in the Edit Options -> Integration tab, you can configure MQTT settings, as shown in the screenshot below:

  • Broker/server: either the IP address or DNS name of the MQTT broker/server.
  • Port: by default, MQTT broker uses port 1883. You can change it according to your specific broker setting.
  • Username/Password: these two fields are optional and only needed if your MQTT broker requires authentication.

MQTT Broker and Client: if you are new to MQTT, you may want to search online for MQTT tutorials/guide. In particular, in Linux (or using a Raspberry Pi) you can easily set up a MQTT broker by installing mosquitto. MQTT uses a publisher / subscriber model, where a publisher sends information to the broker, and a subscriber receives information from the broker. You can use commands mosquitto_pub and mosquitto_sub to act as publisher and subscriber respectively. You can also install MQTT mobile apps as publisher and subscriber.

Topics: The information carried by MQTT is usually in JSON format and is grouped in a hierarchy of topics. For example, a publisher (such as OpenSprinkler controller) can send data to topic opensprinkler/station/0, which contains status data about the first station (index 0). Similarly it can send data to topic opensprinkler/sensor1, which contains status data about sensor1. Subscribers to these topics will receive the corresponding data. Using mosquitto_sub command, you can also subscribe to wildcard topics (e.g. subscribe to the root topic using opensprinkler/#), thus receiving information about all topics under the root hierarchy.

Firmware 2.1.9(4) Topics:

At the moment of this writing, the OpenSprinkler firmware only supports publishing data to the broke. You can use a subscriber client (e.g. the mosquitto_sub command, or a mobile MQTT client, or a home automation hub that supports MQTT) to receive the data. A list of currently supported topics are detailed below:

  • The root topic name is always opensprinkler. In future firmware, we will allow users to customize the root topic, in order to provide better support for multiple OpenSprinkler devices you may have.
  • opensprinkler/system: this topic receives {"state":"started"} message when the controller boots.
  • opensprinkler/station/x: where x is the index (starting from 0) of the station/zone. For example, the first zone is 0, the second zone is 1 and so on. This topic receives {"state":1} message when station/zone x starts running, and {"state":0,"duration":ss} message when the zone finishes running, where ss is the number of seconds that it ran. To receive data for all stations, you can subscribe to wildcard topic opensprinkler/station/#
  • opensprinkler/sensor1: this topic receives {"state":1} when sensor 1 activates and {"state":0} when sensor 1 deactivates.
  • opensprinkler/sensor2: similar to above but for sensor 2.
  • opensprinkler/raindelay: similar to above but for rain delay.
  • opensprinkler/sensor/flow: this topic receives {"count":cc,"volume":vv} when the flow sensor generates data (usually when a zone finishes running), where cc is the flow count, and vv is the amount of volume.