Introduction


Starting from firmware 2.2.1, the MQTT feature has been expanded to include subscription support and customizable topics.

Key Features:

  • Publish: As before, the controller can publish its status and information to an MQTT broker. A MQTT client can then subscribe to these topics to receive real-time updates.
  • Subscribe (New in 2.2.1): The controller can now subscribe to an MQTT broker, allowing it to receive and act upon specific commands from an MQTT client. This enables actions such as:
    • Manually starting a zone
    • Running a program
    • Rebooting the controller

To use these features, ensure your system meets the minimum requirements:

  • Firmware Version: 2.2.1 or later
  • App/UI Version: 2.4.1 or later

MQTT Configurations


To configure MQTT settings in OpenSprinkler: on the controller's homepage, go to Edit Options --> Integration tab, you can adjust MQTT settings, as described below:


  • Broker/Server: Enter either the IP address or DNS name of your MQTT broker/server.
  • Port: The default MQTT broker port  is 1883. Modify this if your broker uses a different port.
  • Username/Password (Optional): provide credentials only if your broker requires authentication.
  • Publish Topic: The topic where OpenSprinkler publishes notifications.
    Default: opensprinkler (for backward compatibility).
    Recommended: Change this to a unique name to distinguish between multiple controllers.
  • Subscribe Topic: The topic OpenSprinkler listens to for messages/commands. By default, this is a unique name based on your controller’s MAC address. If left empty, subscription is disabled, and the controller won’t respond to MQTT commands.

Understanding MQTT Broker and Client:


If you're new to MQTT, you may want to look up MQTT tutorials or guides for a deeper understanding.

  • In Linux or Raspberry Pi, you can set up an MQTT broker using Mosquitto:
    sudo apt install mosquitto mosquitto-clients
  • MQTT follows a publisher/subscriber model:
    • The MQTT broker manages multiple publishers and subscribers.
    • A publisher sends messages to the MQTT broker.
    • A subscriber receives messages from the MQTT broker.
  • You can use these command-line tools:
    • Publish a message:
      mosquitto_pub -h <broker_ip> -t "my_topic" -m "message_content"
    • Subscribe to a topic:
      mosquitto_sub -h <broker_ip> -t "my_topic"
  • Mobile apps are also available for publishing and subscribing to MQTT topics.

Understanding MQTT Topics:


MQTT data is structured in a hierarchy of topics, separated by /.


Example: Publishing Data from OpenSprinkler

  • The OpenSprinkler firmware can publish status data to:

    my_opensprinkler/station/0
    • Contains status information for station 0 (first station) of the my_opensprinkler controller.

  • Or send sensor data to:

    my_opensprinkler/sensor1
    • Contains data for sensor1 of that controller.

Subscribing to Topics

  • A subscriber can:
    • Listen to a specific topic:
      my_opensprinkler/station/0
    • Use wildcards to subscribe to multiple topics:
      • Receive all topics under my_opensprinkler/:
        my_opensprinkler/#
      • Receive ALL topics from ALL controllers:
        #

With these configurations, OpenSprinkler can effectively integrate with MQTT, enabling seamless automation and real-time updates.

Topics Published by firmware 2.2.1


OpenSprinkler publishes messages to the MQTT broker in a format similar to IFTTT and Email notifications.

  • The default root topic is opensprinkler, but can be customized in the settings.
  • The publish topic itself can contain subtopics, such as MA_home/lawn/sprinkler.
  • Due to the firmware storage limit, the maximum topics length is 24 letters.
  • Below we use publish_topic to denote this name.


Here is the list of topics that firmware 2.2.1 publishes:

  • Reboot: publish_topic/system sends the {"state":"started"} message when the controller boots.
  • Zone Activity: publish_topic/station/x: where x is the index (starting from 0 for the first zone). This topic sends {"state":1,"duration":ss} message when zone x starts (with ss being the scheduled run time, in unit of seconds), and {"state":0,"duration":rs} when that zone closes (with rs being the actual run time, in unit of seconds).
    • To receive messages for all zones, 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 the duration is omitted as a master zone runs dynamically based on other zones.
  • Sensor Events: 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.
  • Rain Delay Events: publish_topic/raindelay: similar to the above but for rain delay.
  • Flow Sensor Data: 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.
  • Weather Adjustment Updates: publish_topic/weather: sends {"water level":pp%} when the watering percentage (e.g. from automatic weather adjustment method) has changed.
  • Flow Alert: publish_topic/alert/flow: sends the flow alert notification (available from 2.2.1(1) onward)


IMPORTANT NOTICE: starting from 2.2.1(1), MQTT notifications are managed through the Notification Events setting, just like IFTTT and Email notifications. To receive MQTT messages, you must enable specific Notification Events. If no events are selected, the controller won't publish any MQTT message.

Topics Subscribed by firmware 2.2.1


Firmware 2.2.1 allows OpenSprinkler to subscribe to a user-defined MQTT topic, enabling it to receive commands from an MQTT broker. This means a MQTT client can send commands to control OpenSprinkler's operations.

To enable this feature:

  • Set a valid Subscribe Topic in the MQTT configuration (see previous section). By default, the topic is a unique name based on the controller’s MAC address (e.g., OS-112233AABBCC).
  • Customization is allowed, but each controller should have a unique subscribe topic.
  • Due to firmware storage limitations, the maximum length of a subscribe topic is 24 characters.
  • The Subscribe Topic is optional—if left empty, the controller will not respond to MQTT commands.


To control OpenSprinkler, a MQTT client must:

  1. Publish a command message to the subscribe_topic.
  2. Include a payload that specifies the command and parameters.


The commands follow the same format as OpenSprinkler’s HTTP API (see HTTP API document). Specifically:

  • Payload structure:
    <endpoint>?<parameter1>=<value>&<parameter2>=<value>
  • The endpoint is a two-letter code (without a leading /) as in the HTTP API.
  • Parameters are separated by &.
  • The device password (pw) must be included in MD5 checksum format.


Only a subset of the HTTP API commands are supported currently:

  • Change Controller Variables (endpoint: cv), with the following parameters:
    • 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 MD5 hash of the device password.


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"

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.