SplHAsh

An MQTT based sprinkler controller running on ESP3266

SplHAsh allows for controlling of your sprinkler system using your MQTT based home automation system.

SplHAsh should be controllable via any home automation software that can configure an MQTT switch or send commands over MQTT, including Home Assistant and OpenHAB.

Sample Home Assistant configuration snippets are provided in this repository to get your sprinklers connected to Home Assistant including sample scripts and automation.

SplHAsh has both hardware and software components. The required hardware components include an ESP8266-based microcontroller (such as the NodeMCU), a shift register, and a relay module. The software component is found in this repo.

One of the benefits of this system is it does not matter if you have 4 sprinkler zones or 100. Using the shift registers allows for virtually limitless zones.

Table of Contents

• SplHAsh
  • How SplHAsh works...
  • Hardware
    • Bill of Materials
    • Building SplHAsh
  • Software
    • 1. Set up the Arduino IDE
    • 2. Load the sketch in the Arduino IDE and modify the user parameters in config.h
      • Wifi Parameters
      • Static IP Parameters
      • MQTT Parameters
      • Relay Parameters
      • Sprinkler Zone Parameters
      • Shift Register Parameters
    • 3. Upload the sketch to your NodeMCU / microcontroller
    • 4. Check the Arduino IDE Serial Monitor
  • Installing SplHAsh
  • Configuring Home Assistant
    • Example MQTT Switch Configuration
    • Example Script
    • Example Automation
  • Contributing
  • Issues/Bug Reports/Feature Requests
  • Credits
  • License

How SplHAsh works...

SplHAsh subscribes to an MQTT topic for each of the zones configured (by default yard/sprinkler/X/action where X is the corresponding zone).

When the ON payload is received for any of these topics, SplHAsh activates a relay connected to the relevant shift register and pin to activate the sprinkler zone.

When the OFF payload is received for any of these topics, SplHAsh deactivates a relay connected to the relevant shift register and pin to deactivate the sprinkler zone.

When the ON or OFF payload is received for the Zone0 topic (by default yard/sprinkler/0/action), SplHAsh will deactivate all zones.

When a payload to activate/deactivate a zone is received SplHAsh publishes the current status of the zones based on it's memory of the zones. These messages are published with the "retain" flag set.

SplHAsh also publishes a "birth" message on connection to your MQTT broker, and a "last-will-and-testament" message on disconnection from the broker, so that your home automation software can respond appropriately to SplHAsh being online or offline.

SplHAsh also allows for designating a zone as a 'PUMP' zone that will be activated regardless of what zone is called for. (See the Sprinkler Zone Parameters section of this documentation.)

Hardware

Bill of Materials

Building SplHAsh to control up to 8 zones requires:

| No. | Qty | Part | Link | Approx Price | | --- | --- | ---- | ---- | ------------ | | 1. | 1 | ESP8266-based microcontroller (e.g. NodeMCU) | Link | $ 7.00 | | 2. | 1 | 8 channel relay module | Link | $ 9.00 | | 3. | 1 | 74HC595 Shift Register | Link | $ 6.00 | | 4. | 1 | 24v AC power adapter | Link | $ 14.00 | | 5. | 1 | AC to DC converter | Link | $ 13.00 | | 6. | 1 | Mini solderless breadboard (400 tie-point) | Link | $ 10.00 | | 7. | | Male-to-female breadboard jumper wires | Link | $ 6.00 | | 8. | | Male-to-male breadboard jumper wires | | | | 9. | | Project box or case | | |

Approximate total cost for major components: $ 59.00, even less if you are replacing an existing controller (you should be able to reuse the current power adapter).

Note: You will need 1 shift register for every 8 zones in your setup.

Building SplHAsh

Connect the breadboard according to this diagram:

Done!

Software

1. Set up the Arduino IDE

You will modify the configuration parameters and upload the sketch to the NodeMCU with the Arduino IDE.

1. Download the Arduino IDE for your platform from here and install it.
2. Add support for the ESP8266 to the Arduino IDE by following the instructions under "Installing with Boards Manager" here.
3. Add the "PubSubClient" library to the Arduino IDE: follow the instructions for using the Library Manager here, and search for and install the PubSubClient library.
4. You may need to install a driver for the NodeMCU for your OS - Google for instructions for your specific microcontroller and platform, install the driver if necessary, and restart the Arduino IDE.
5. Select your board from Tools -> Boards in the Arduino IDE (e.g. "NodeMCU 1.0 (ESP-12E Module)").

2. Load the sketch in the Arduino IDE and modify the user parameters in config.h

SplHAsh's configuration parameters are found in config.h. After loading SplHAsh.ino, select the config.h tab in the Arduino IDE. This section describes the configuration parameters and their permitted values.

IMPORTANT: No modification of the sketch code in SplHAsh.ino is necessary.

Wifi Parameters

WIFI_SSID "your-wifi-ssid" The wifi ssid SplHAsh will connect to. Must be placed within quotation marks.

WIFI_PASSWORD "your-wifi-password" The wifi ssid's password. Must be placed within quotation marks.

Static IP Parameters

STATIC_IP false Set to true to use the IP / GATEWAY / SUBNET parameters that follow. Set to false to use DHCP. (Default: false)

IP 192,168,1,100 The static IP you want to assign to SplHAsh. (Default: 192.168.1.100)

GATEWAY 192,168,1,1 The gateway you want to use. (Default: 192.168.1.1)

SUBNET 255,255,255,0 The subnet mask you want to use. (Default: 255.255.255.0)

Note: There are commas (,) not periods (.) in the IP / GATEWAY / SUBNET parameters above!

MQTT Parameters

MQTT_BROKER "w.x.y.z" The IP address of your MQTT broker. Must be placed within quotation marks.

MQTT_CLIENTID "SplHAsh" The Client ID you want SplHAsh to use. Should be unique among all the devices connected to your broker. Must be placed within quotation marks. (Default: SplHAsh)

MQTT_USERNAME "your-mqtt-username" The username required to authenticate to your MQTT broker. Must be placed within quotation marks. Use "" (i.e. a pair of quotation marks) if your broker does not require authentication.

MQTT_PASSWORD "your-mqtt-password" The password required to authenticate to your MQTT broker. Must be placed within quotation marks. Use "" (i.e. a pair of quotation marks) if your broker does not require authentication.

MQTT_TOPIC_BASE "yard/sprinkler/" The base string used for the action and status topics. (Default: yard/sprinkler/)

Relay Parameters

RELAY_ACTIVE HIGH Set to LOW if using an active-low relay module. Set to HIGH if using an active-high relay module. (Default: HIGH)

Sprinkler Zone Parameters

MAX_ZONE 8 The maximum number of zones configured. This will tell the code how many shift registers are used. (Default: 8)

PUMP_ZONE -1 The zone that is used for a pump. This allows for designating a zone that will be activated regardless of what zone is called for. If no pump is used leave as default. (Default: -1)

Shift Register Parameters

SR_DATA_PIN D6 The GPIO pin connected to the data pin of the shift register. (Default: NodeMCU D6)

SR_LATCH_PIN D7 The GPIO pin connected to the latch pin of the shift register. (Default: NodeMCU D7)

SR_CLOCK_PIN D5 The GPIO pin connected to the clock pin of the shift register. (Default: NodeMCU D8)

3. Upload the sketch to your NodeMCU / microcontroller

If using the NodeMCU, connect it to your computer via MicroUSB. Select Sketch -> Upload in the Arduino IDE.

If using a different ESP8266 microcontroller, follow that device's instructions for putting it into flashing/programming mode.

4. Check the Arduino IDE Serial Monitor

Open the Serial Monitor via Tools -> Serial Monitor. Reset your microcontroller. If all is working correctly, you should see something similar to the following messages:

Starting SplHAsh...
Relay mode: Active-High

Connecting to your-wifi-ssid.. WiFi connected - IP address: 192.168.1.100
Attempting MQTT connection...Connected!
Publishing birth message "online" to SplHAsh/availability...
Subscribing to yard/sprinkler/0/action...
Subscribing to yard/sprinkler/1/action...
Subscribing to yard/sprinkler/2/action...
Subscribing to yard/sprinkler/3/action...
Subscribing to yard/sprinkler/4/action...
Subscribing to yard/sprinkler/5/action...
Subscribing to yard/sprinkler/6/action...
Subscribing to yard/sprinkler/7/action...
Subscribing to yard/sprinkler/8/action...

If you receive these (or similar) messages, all appears to be working correctly. Disconnect the controller from your computer and prepare to install.

Installing SplHAsh

1. In