Leave the Water Running? 💧 Build an IoT Smart Leak Detector

In a survey, 77% of homebuyers face unexpected repair costs in the first year of ownership, and over 2/3 of those people paid over $1, 000 for the repairs. Many of those expensive home repairs have a habit of cropping up when they're least convenient, as well.

Hottest weekend of the year so far? The air conditioning goes out Friday night. Family coming into town for the holidays? The oven refuses to heat up. Heading out the door on vacation? The water heater / dishwasher / refrigerator starts leaking.

While I can't help you with the first two scenarios, I can help you with the last one: catching those pesky leaks soon after they've begun - not hours (or days) later after your hardwood floors have been ruined or your basement's totally flooded.

This project is inspired by my own true story. Earlier this summer the air conditioning unit had a pretty serious leak that my husband noticed while changing the air filters. If he hadn't caught it when he did, it could have soon overflowed the drip pan underneath the unit and resulted in serious water damage to our attic and upstairs floor.

We got lucky this time, but why gamble on something like that when I can build my own leak detection device? I do work for Internet of Things (IoT) startup Blues Wireless after all, and the company's whole mission is to make wireless IoT simple. How about making my own IoT leak detector?

So you can rest easier in your own home, I'll walk you through building a simple, low-cost leak detector that uses a water sensor, a cellular module, and instant SMS alerts powered by Twilio, whenever water is detected.

Here's a quick video of what the finished product will do.

Build the Leak Detector 💦

I think you'll be surprised at how little hardware is actually required to make this leak detector work - I know I was when I first built it.

To start, we'll use a Blues Wireless Cellular Notecard, attached to a Blues Wireless Notecarrier-A, and a Songhe water sensor attached to the Notecarrier's header pins with 3 male-to-female jumper wires.

We'll also need a small LiPo battery with a JST connector to power the whole shebang.

Why Cellular? And why the Notecard?

Depending on where your leak detector is going to be located, Wi-Fi service might not be the most reliable (or even an option, in some cases), which is why I decided to go with a cellular Blues Wireless Notecard, and bypass the chance that the local Internet's down too when things spring a leak.

The Notecard comes in both Wi-Fi and Cellular varieties, and the cellular modules work globally on LTE-M, NB-IoT and Cat-1 protocols, and come prepaid with 500MB of data and 10 years of global cellular service.

Once the Notecard is powered on, it already knows how to connect through private VPN tunnels with the Blues Wireless cloud service, Notehub.io. Then, Notehub.io can securely route data to literally any cloud service you like, but we'll get to that in more detail in the next section.

Why Notecarrier-A?

The Notecarrier-A is one of the development boards that allow you to easily prototype an IoT solution with the Notecard. It provides onboard antennas, JST connectors, Qwiic ports, pre-soldered female pin headers for easy access, and more.

The part that really sealed the deal for me, was the pre-soldered edge connector pins, which I'll elaborate on shortly.

Look Ma, No MCU Required!

It might surprise you to know that although we're using an analog water sensor in this project, we don't actually need a microcontroller to handle decoding the readings from the sensor.

The sensor only has two readings: LOW if water's not detected, and HIGH if water is detected, and thanks to a newly-released Notecard firmware feature, autonomous reporting of GPIO state changes without a host microcontroller is now possible.

What this means is: we'll be able to monitor the AUX pins on the Notecarrier and if the pin connected to our water sensor via the jumper wire changes value, that change can trigger an alert for us. No MCU needed!

After we've set up our hardware and project, we'll get to programming our Notecard to know how to report on these sorts of situations.

Now with the hardware considerations out of the way, let's put this detector together.

1. Attach Notecard to Notecarrier

To begin simply slot the Notecard into the M.2 edge connector on the Notecarrier-A, and connect the MAIN u.fl connector on the Notecarrier-A to the MAIN u.fl on the Notecard. This allows use of the onboard cellular antennas on the Notecarrier.

Do the same for the GPS u.fl connector wire. Although it's not necessary for this particular project, it lets you utilize the GPS module on the cellular Notecard.

2. Attach Jumper Wires to Notecarrier-A's Edge Pins

Next, we're going to add the jumper wires to the Notecarrier that will attach to the water sensor.

Add male jumper wires to the following pins on the Notecarrier:

• VIO
• GND
• AUX1

3. Attach Jumper Wires to Sensor

Take the female ends of those same jumper wires and attach them to the water sensor.

Here's what each wire on the Notecarrier should connect to on the sensor:

• VIO - +
• GND - -
• AUX1 - S

4. Attach LiPo Battery

Finally plug the LiPo battery into the JST connector labelled LIPO.

If you got all the jumper wires plugged in correctly, the red light on the water sensor should light up now - it's purely there to indicate the sensor's getting power. It won't flash or blink or anything like the Notecard will once we've programmed it.

Set Up a Notecard Project

Before we can tell the Notecard what to do, we need to create a new project in the Notehub.io cloud that the Notecard will send all of its data to.

As I mentioned earlier, Notecards don't live on the public Internet, they only send data to Notehub (Blues' private cloud) through secure VPN tunnels, and once Notehub has the data, it can instantly route it out to the cloud provider of your choice (AWS, Azure, Google Cloud, or any IoT-optimized service like Ubidots, Datacake, Losant, and others).

1. So if you haven't done so already, sign up for a Notehub account. It's free for up to the first 5, 000 routed events per month (routed event = data transmissions from Notehub to your cloud endpoint of choice). This will be way more than what's needed for this leak detector.

2. And after you've signed in to the dashboard, click the "Create Project" button in the top right of the Notehub screen and fill in the project details like Project Name and Billing Account.

Don't worry too much about the billing account - that applies to projects that will be using over the 5, 000 free events per month.

After the project's created, copy the project UID - we'll need it when configuring the Notecard just a little later on in this tutorial.

Sign Up for a Free Twilio Starter Account

One more step to take is signing up for a free Twilio account, because Twilio is what we'll be using for the SMS alerts when water is detected.

I set up my test account following the Blues Twilio documentation, and I would recommend starting there.

NOTE: If you click the Twilio link the in the "Prerequisites" section of the documentation, you'll get some extra Twilio starter credits via a Blues Wireless referral link. 💰

Once the account is set up, verify a caller ID (probably your own cell phone number for testing purposes) and assign a Twilio phone number to your account (this is the number that the SMS notifications will come from).

Here's my account with a Twilio phone number associated with it.

With the accounts set and the project made, we can get on with coding our Notecard.

Program the Notecard

It's time to program this Notecard, and lucky for us Blues aims to make this step easy too. The Notecard speaks one language: JSON.

All Notecard API commands are in JSON, which also means that any programming language that can read and write strings can also communicate with the Notecard. If you're working with an MCU or single-board computer, there are Blues Wireless-supported SDKs for Python, C/C++, Arduino, and Go (and community-supported SDKs for Rust and even .NET).

Using the in-browser terminal provided at dev.blues.io, we can connect directly to our Notecard via the magic of Web Serial (and the micro USB to USB-A cable included in the Things portion of this tutorial) and issue JSON-based API commands.

Once you've connected your Notecard issue the following commands:

1. Factory reset the Notecard for a fresh start.

This resets the Notecard to a clean slate - any previous configurations it may have had are eliminated so it's ready for a new project.

{"req":"card.restore","delete":true}

2. Connect the Notecard to the new Notehub project we just made.

{
  "req":"hub.set",
  "product":"com.blues.pniedringhaus:leak_detector",
  "mode":"periodic",
  "outbound":1440, 
  "inbound":1440
}

Setting the mode to periodic will only send any un-synced outbound notes to Notehub every 1440 minutes (once per day), and it will always sync on the inbound interval every 1440 minutes as well, in order to process any new notes and environment variables from Notehub.

Since we don't anticipate any changing environment variables or regular Notecard activity long intervals between syncs are fine. This will also help to preserve battery life as the most power intensive activities this device will experience is transmitting data of a change in its AUX1 pin to Notehub.

NOTE: Don't be fooled by the outbound time - in the next step, we'll set it up so the Notecard reacts as soon as the water sensor detects a change.

3. Use the brand new card.aux API feature to watch input pin status

{
  "req":"card.aux",
  "mode":"gpio",
  "usage":[
    "input",
    "",
    "",
    ""
  ], 
  "file": "leak.qo", 
  "sync": true
}

This is the really cool part: in this request we're taking advantage of the new card.aux API feature which allows for autonomous reporting of state changes on the AUX pins.

By default, all four pins (AUX1 - AUX4) are off, and the Notecard reports their state as LOW in a state array. When we set the first pin in this usage array to "input", we're telling the Notecard to set the AUX1 pin as an input that can sense the value from the water sensor (which also happens to be a binary of LOW - no water detected or HIGH - water detected).

Since the rest of pins won't be in use we leave the pin mode unchanged by using "" for the next three pins in the usage array.

To make our leak detection events easy to find in Notehub amongst our other note types, we'll give them a unique file name with "file": "leak.qo" (this will also come in handy later when setting up Twilio SMS alerts).

"sync":true tells our Notecard to immediately communicate any state changes to our Notehub project as soon as they occur. Remember when I said not to be fooled by the outbound time we set on the project? This is what I meant.

And with that, we should be ready to give this device a test run.

Test Out our Water Sensor and Notehub

Our Notecard is programmed, so let's test out that it's sending GPIO state changes correctly to Notehub. Once that's confirmed, we'll get on with the final step of SMS alerts with Twilio.

Testing should be relatively straightforward. I would recommend filling a small glass or shallow bowl with an inch or two of water, double check all your jumper wires are secured in the Notecarrier pins and the water sensor pins, then lower the sensor down into the water about half an inch (the sensor's not the most sensitive so it needs a good bit of water to recognize it needs to change state).

If everything goes according to plan, when you check your Notehub project's Events tab, you should see something like this in there within a few minutes of the submersion.

Notice the first event in this state array: {"high": true} - that's what we're looking for!

Troubleshooting the Leak Detector

If you're not seeing the same thing in your own Notehub project try the following things:

• Double check that all the jumper wires are correctly configured in the Notecarrier and the sensor.
• Make sure the wires are pushed down into the pins on the Notecarrier as far as they'll go and securely on the sensor's pins too.
• Try plugging the Notecarrier in and powering it off the micro-USB port.
• Wipe down the sensor in between dunks in the water to make sure it realizes it's dry before dunking again.

Enable SMS Messaging with Twilio

We're ready to get Twilio SMS's alerts into the mix now.As I mentioned above, Notehub has this unique ability to send events it receives out to a variety of public clouds and low-code dashboards. It can also send events to Twilio, and not just all events, but specific types of events and (using JSONata syntax) very specific pieces of those particular events.

Ready to get started?

1. Create a new Twilio route in Notehub that looks for leak.qo files

Follow the Twilio starter guide on the Blues Wireless developer experience site to get the basics of setting up a route from Notehub to Twilio, until you reach step 8.

Instead of selecting note files labeled twilio.qo, we're going to be looking for files with the name of leak.qo.

2. Use JSONata in the Transform Data section to format the code for Twilio

The Twilio starter guide instructions briefly cover using JSONata (a lightweight query and transformation language for JSON) to filter down and format the data from a note before sending it to Twilio.

Twilio requires very specific syntax, and luckily we can do all the data formatting right inside the Notehub Route page we're working with.

( $from := "+1706XXXXXXX";
  $to := "+1404XXXXXXX";
  $body := function(){
    (
      $join([
        "Leak detected by ",
         best_id ? best_id : device,
        " at ",
        $fromMillis(when * 1000,
        "[M01]/[D01]/[Y0001] [h#1]:[m01][P]",
        "-0500"),
        " EST! 💧🪣 "
      ])
    )
  };
$result := (body.state[0] = {"high": true}) ? "&Body=" & $body() & "&From=" & $from & "&To=" & $to & "&" : $doNotRoute();
)

There's plenty happening in this code snippet, so let's unpack it before we go any further.

In this expression, five variables are defined:

• $from - the Twilio phone number the SMS will come from.
• $to - the phone number receiving the SMS (probably your own phone).
• $body - a JSONata function that joins strings of text together, that lets us know which Notecard is detecting a leak (defined either by the Notecard's best_id value - its serial number, falling back to its device ID if that value's not there), and what time it detected the leak (when).
• $result - a ternary operation to check if the body of the note being transformed has the first aux pin set to the value of HIGH. If it is, proceed with sending the info to Twilio.
• $doNotRoute - custom Blues JSONata command that will conditionally route events out of Notehub. If the $result ternary operation above evaluates to false, command variable will prevent the data from being sent to Twilio.

Each variable or function is separated from the next by a semicolon, and to use multiple variables and functions together like this example, requires they all be wrapped up inside of parentheses.

To make the SMS alert easier to read, the $body function that puts the message text together looks first for the sn (serial number that can be set by users in Notehub - something like "Garage water heater"), and if it's not set falls back to the device ID (the Notecard's unique ID). It also includes a helpful, formatted timestamp using the when variable from the original note and the $fromMillis JSONata expression.

Finally, the $result expression checks if the leak.qo note it's transforming has its first GPIO pin set to HIGH. If it does, there's a leak and we need Twilio to sound the alarm 🚨!

If the leak.qo's GPIO pin is set to LOW - which happens once the sensor's removed from water, there's no need to send the data to Twilio, in which case the Blues Wireless custom JSONata command $doNotRoute kicks in. It exists just for occasions like these where we want to conditionally route events based on a variable or calculation.

Here's what your final JSONata expression should resemble in Notehub.

Then click the Apply Changes button, and you should be ready to test out your whole leak detection and alerting system.

Oh no! A Leak's Been Detected! 💧

If you're like me, you'll want to re-test your leak detector with a glass of water first before setting it up for duty wherever expensive leaks could begin.

Submerge your sensor in some water, wait momentarily for the Notecard to recognize the state change of the GPIO pin, and if everything goes according to plan... voilà! Leak detected!

After confirming our detector works, let's go set it up for active duty.

Here's a photo of mine snuggly nestled in the drip pan for our air conditioning unit - all ready to detect leaks and drips.

Notice I've made sure to place the Notecarrier and battery outside of the drip tray on the plywood. Keeping them away from the water and on a non-conductive surface like wood is always recommended.

You could also put them in some sort of enclosure as well, if that suits your use case better.

Conclusion

Homeownership is great, but can also be a real pain when unexpected repairs happen.

I narrowly avoided one of those costly repairs in the form of an air conditioning unit with a leak, but luckily, building a small, inexpensive, and long-lasting leak detector complete with SMS alerts when leaks do happen is possible.

With a Notecard, Notecarrier-A, analog water sensor, and Twilio, you too can have one less thing to worry about while you're away from home.

If you're looking for next steps to get started...

• Get your own Blues Wireless Notecard and Notecarrier-A
• Browse our other Hackster projects that use the Notecard in edge scenarios
• Share what you build with us on social!

Happy hacking! 💦👨‍💻🪣