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


Introduction: From firmware 2.2.1, the MQTT feature has been expanded by adding support for subscribing as well as customizing topics. As before, the 'publish' feature allows you to publish controller information to a MQTT broker, you can then use a MQTT client to subscribe to the topics to receive such information. The newly added 'subscribe' feature allows you to subscribe to a MQTT broker in order to receive and act upon certain commands from a MQTT client, such as manually starting a zone, starting a program, and rebooting the controller etc. The features explained in this article require a minimum firmware version of 2.2.1, and minimum app / UI version of 2.4.1.

MQTT Configurations


At the controller's homepage, go to Edit Options, then click on the Integration tab, you can configure MQTT settings, as shown below:


  • Broker/server: either the IP address or DNS name of your 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.
  • Publish Topic: the topic that OpenSprinkler publishes notifications to. For backward compatibility reasons, this topic is by default opensprinkler. We recommend you to change it to a more unique name so you can distinguish between multiple controllers.
  • Subscribe Topic: the topic that OpenSprinkler receives messages / commands from. By default this topic is a unique name composed from your controller's MAC address. If you leave it empty, your controller will disable subscription and therefore will NOT act upon received commands.

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 Raspberry Pi) you can easily set up a MQTT broker by installing mosquitto. A broker is a server that multiple publishers and subscribers connect to and communicate with each other with. 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 grouped in a hierarchy of topics separated by slash '/'.  For example, a publisher (such as an OpenSprinkler) can send data / message to the topic my_opensprinkler/station/0, which contains status data about the first station (index 0) of the controller named my_opensprinkler. Any client subscribing to this topic will receive the data. Similarly the publisher can send message to topic my_opensprinkler/sensor1, which contains status data about sensor1 of that controller. A subscriber can subscribe to a specific topic, or it can subscribe to wildcard topics, allowing it to receive information about all topics underneath the root topic. For example, subscribing to my_opensprinkler/# allows it to receive all topics prefixed my_opensprinkler (i.e. published by the controller named my_opensprinkler),  and subscribing to # allows it to receive all topics published by all controllers!

Topics Published by firmware 2.2.1


The messages published by OpenSprinkler to the MQTT broker are largely in line with IFTTT and Email notifications. The root topic for publishing is opensprinkler by default, but can be customized, including it may contain a sequence of subtopics, such as MA_home/lawn/sprinkler. Due to the firmware storage limit, the maximum length of the publish topic is 24 letters. Below we use publish_topic to denote this name. Here is a specific list of the topics that firmware 2.2.1 publishes:

  • publish_topic/system: sends the {"state":"started"} message when the controller boots.
  • publish_topic/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 sends {"state":1,"duration":ss} message when station/zone x starts running (with ss being the scheduled run time, in unit of seconds), and {"state":0,"duration":rs} message when that zone closes (with rs being the actual run time, in unit of seconds). To receive messages for all stations, you can subscribe to wildcard publish_topic/station/#. Firmware 2.2.1 also publishes {"state":1} on a master/pump zone when that zone opens, but it will not carry the duration data as a master zone's run time cannot be predicted (rather, its status is determined dynamically based on what zones are currently running).
  • publish_topic/sensor1: sends {"state":1} when sensor 1 activates and {"state":0} when sensor 1 deactivates.
  • publish_topic/sensor2: similar to the above but for sensor 2.
  • publish_topic/raindelay: similar to the above but for rain delay.
  • publish_topic/sensor/flow: sends {"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.
  • publish_topic/weather: sends {"water level":pp%} when the watering percentage (e.g. from automatic weather adjustment method) has changed.

Topics Subscribed by firmware 2.2.1:


Firmware 2.2.1 can subscribe to a user-selected topic in order to receive messages (i.e. commands) from the MQTT broker. This allows a MQTT client to send command to your controller to trigger certain actions. To do so you must provide a valid Subscribe Topic in the MQTT configuration (see above). The default is a unique named composed from the MAC address of your controller, for example, OS-112233AABBCC. You may customize it, but generally each controller should have a unique name. Also, due to the firmware storage limit, the maximum length of the subscribe topic name is 24 letters. Below we use subscribe_topic to denote this name. NOTE that the Subscribe Topic is optional: you can leave it empty if you do not want your controller to respond to / act upon received commands. 


Using a MQTT client, you can send a command to OpenSprinkler by specifying the subscribe_topic, and also a 'payload' which carries the command message. The messages accepted by this firmware are the same as the HTTP API, the details of which can be found in the HTTP API document. Only a subset of commands are supported currently, explained below. The payload message will begin with the two-letter endpoint name (excluding the slash /), followed by a question mark ? and necessary parameters separated by &. The supported commands are:

  • Change Controller Variables (endpoint: cv). Only the following parameters are supported:
    • rsn: reset all stations (including those waiting to run).
    • rbt: reboot controller.
    • en: operation enable/disable.
    • rd: set rain delay time (in hours).
  • Manual Station Run (endpoint: cm)
  • Manually Start a Program (endpoint: mp)
  • Start Run-Once Program (endpoint: cr)


For example, to reset all stations, the payload message would be:

cv?pw=xxx&rsn=1

where pw=xxx is the device password in MD5 checksum. To use mosquitto_pub to send this command, you may run:

  •  mosquitto_pub -h your_mqtt_broker -p 1883 -t subcribe_topic -m "cv?pw=xxx&rsn=1"

Again, subscribe_topic is the Subscribe Topic name defined in MQTT settings.


As another example, to manually start zone 1 for 2 minute and 45 seconds (i.e. a total of 165 seconds), the payload message would be:

cm?pw=xxx&sid=0&t=165&en=1


Again, please refer to the HTTP API document for the complete command format of each supported endpoint above.