Inspiration

In a quest to safeguard my home and inject a bit of fun into my daily life, I embarked on a journey of home automation that led to the creation of spring. It all started when my husband and I moved into our house. One of the first items on our house to-do list was to install a Ring doorbell that we received from our realtor Sara Hyson as a house-warming gift. We installed the Ring app on our phones and checked this item off of our list. The next item on our house to-do list was to get the sprinkler system turned on since it was early spring. When the sprinkler technician was out, he told us that our particular sprinkler system was a “smart” sprinkler system and there was a Rachio app for our phones. Subsequently, we installed the Rachio app on our phones and checked this item off of our list as well. As time progressed, we noticed that neighbors kept crossing through our backyard to get to the street behind ours instead of walking around on the sidewalk. This led to the addition of more Ring cameras, but this time in our backyard. At this point, a light bulb went off in my brain as I realized the potential for a unique integration… Could I combine the Ring cameras’ vigilant watch with the precise control of the sprinklers to create a humorous yet effective solution? Thus, spring was born.

Overview

To make this integration a reality, I started by gathering initial requirements.

First, I explored the possibility of accessing Ring’s public API, but unfortunately, it is not available. However, my research did uncover several open-source projects offering unofficial APIs. Among these, I discovered tsightler’s ring-mqtt project, which utilizes MQTT – a lightweight publish/subscribe messaging protocol designed for IoT. In MQTT, a broker, like Mosquitto, acts as an intermediary between publishers and subscribers; it receives messages from publishers and forwards them to the relevant subscribers. In this case, the Ring camera publishers send messages to the Mosquitto broker, which, in turn, forward them to the spring subscriber. The spring subscriber only focuses on the relevant Ring camera topic, which pertains to the ring/{location_id}/camera/{device_id}/motion/attributes path. The messages from this topic contain information regarding the Ring cameras’ motion detection features, specifically the person detection feature. This information allowed me to ensure that my programmtic response would only be triggered if there was a person on my property.

Second, I explored the possibility of accessing Rachio’s public API. To my delight, I discovered rfverbruggen’s rachiopy, which is a Python package that provides an interface to the Rachio public API. Leveraging this package, I identified the Rachio sprinker zones corresponding the the Ring cameras of interest. Then, I created functions to activate the sprinklers when a person was detected. During testing, I noticed some weird behavior with the sprinklers activating in succession, even when no one was within range of the cameras. Inspecting the ring-mqtt messages, I noticed that the same person detected message was being repeated. I decided to carefully examine the ring-mqtt code to get a better understanding of how the messages were being generated. This revealed that Ring camera devices utilize a base class in base-polled-device.js that communicates via a polling interface. This fetches the latest state after a set time interval, resulting in repeated messages. Therefore, I added in some checks to prevent the sprinklers from reactivating unless the latest message timestamp differed by at least 30 seconds from the last message.

After developing the initial prototype, my focus shifted to making the project more user-friendly. I refactored the code into reusable functions and organized these functions into a Python package named spring. Then, I created a docker-compose.yml, leveraging the official Mosquitto and ring-mqtt Docker images from Docker Hub and my own custom spring Dockerfile that utilizes the spring Python package. This enabled the set up of the individual components as separate containers that would interact with each other. Therefore, to run spring, all you need to do is clone the spring respository, configure your Ring cameras and Rachio sprinker zones using the instructions provided in the README.md, and then run docker compose up -d, which runs the containers in detached mode, ensuring that they persist even when the terminal is closed. The code for spring can be found here.

Example

My husband didn’t really know that I was working on this project… When he was out doing some yard work in the backyard one day, I decided it was the perfect time to put spring to the test… Enjoy the video below!