Recipe for a Water Warning System Using Text/Email Messages

This Recipe demonstrates how to use an XBee Digital I/O adapter and a moisture sensor to create a water warning system. The system sends alerts using text/email messages and responds to text/email messages. Each time a message is sent to the system, it will be acknowledged with a return message, so the sender knows what happened.

Ingredients

For this Recipe, you will need:

• an XBee DIO
• an XBee Coordinator (XStick)
• a 4 wire, 12 volt moisture sensor
• a dedicated email account

This Recipe uses a 4 wire, 12 volt moisture sensor. One which we've used and tested with good results is the Winland WaterBug WB-200.

The moisture sensor is monitored by an XBee Digital I/O device. The Digital I/O, or DIO for short, is a general purpose wireless device which can both monitor digital inputs and generate digital outputs under radio control. It also can supply 12 volts of power, which comes in very handy. Many sensors are designed to run from 12 volt supplies.

The moisture sensor will receive its 12 volt supply voltage from the 12V power supply terminals of the DIO. The moisture sensor's sense output will be monitored by a DIO input terminal. Most of the DIO configuration will be done by the Script in this Recipe, but the DIO's 12V output terminal and its moisture sensor input terminal need some manual configuration. On the back of the DIO there is a set of DIP switches. In the XBEE DIO documentation, there is a description of the function of these DIP switches. Set the switches so the 12 volt output function is enabled, and input terminal 1's pullup resistor is activated.

Once you have set the DIO's DIP switches, you need to wire the moisture sensor to the DIO. Using a 4 wire cable, connect the DIO's 12 volt and ground pins to the power and ground pins of the moisture sensor. Next connect the moisture sensor's normally closed (NC) switch pins (2 signals), to the ground and pin 1 (a sensing pin) of the DIO. Electrically, this will make the moisture sensor normally ground pin 1 and let it pull up high when the sensor senses water. It also has the handy side effect of signaling an alarm condition if the sense wires are disconnected for some reason. The photo below shows a DIO wired to a WaterBug sensor.

Before installing the DIO, inspect the DIO case until you find its serial number label. It often has a barcode on the back, and the barcode has a string underneath that begins with "SN:(S)". The serial number follows the "SN:(S)" and is a string with the digits 0-9 and the letters A-F. The serial number is a 16 digit (64 bit) hexadecimal number (a number in base 16). Write the serial number down, as you will need it for this Recipe.

Plug the DIO power supply into an electrical socket where you wish to sense moisture and plug the power supply's power plug into the DIO. Plug the XStick into a USB port on your host computer. Keep the XStick and the DIO less then a few tens of feet apart to begin with, as the two are wireless devices and can get out of range. Once you have things working, you can experiment over greater distances.

You need an email account to which you can send messages to via SMTP and receive from using POP. Most email accounts support SMTP and POP interfaces. If you look on your provider's support page, you should find addresses for sending and receiving messages such as "smtp.provider.com" and "pop.provider.com". Once you know these addresses, you can use your account name and password to send and receive messages.

The address where your messages will be sent can be any email address. It can also be an email address for a text message (see the Email Addresses for Texting section). You can add additional addresses using the addEmailAddress Script.

Unlike configurations which only send messages, this Recipe can receive and respond to messages as well. Receiving requires that the Recipe poll your email account for email. Don't use an email account which has email you wish to keep, or which is receiving email you wish to read. When this Recipe picks up the mail, it cleans out the mailbox. It will act upon messages from users it recognizes, but all the messages it receives will be deleted.

Script

Here is the Script you need to run for this Recipe:

# An alarm system triggered by a moisture sensor using email/text messages.
# Returns a status message for each control message.
# Requires an XBee DIO, a moisture sensor, and a Coordinator.

# get the XBee address of the DIO
script_parameters("dio_address")
# get Coordinator's USB port
script_parameters("coordinator_port")

# parameters for the Wired Messaging Device
# messaging_address is the text/email address to which and from where messages
# will be sent and received
# pop_host is the host name for POP polling - e.g. "pop.example.com"
# smtp_host is host name for SMTP - e.g. "smtp.example.com"
# user is the user's email address on the host - e.g. "user@example.com"
# password is the user's password for the email account - e.g. "secret" 
script_parameters("messaging_address", "pop_host", "smtp_host", "password", "user")
optional_script_parameters(ssl_enable:true, smtp_port:587, gmail_polling:false)


# Add a Coordinator
run_script("Scripts/Device/XBee/Coordinator", id:"coordinator", port_location:coordinator_port)


# Add the DIO
# enable its 12 power supply and sensitize its 1S input terminal
run_script("Scripts/Device/XBee/DigitalIO", address:dio_address, change_detect:"1S", enable_12V:true, id:"dio", port_location:coordinator_port)


# create a wired messaging device
# Poll every 240 seconds (4 minutes)
run_script("Scripts/Device/EMail/WiredMessagingPOP", email_address:messaging_address, gmail_polling:gmail_polling, host:pop_host, id:"wired_messenger", inputs:"alarm_message", mail_subject:"Virtual Wired Text Messenger", outputs:"alarm", password:password, poll_interval:240, smtp_host:smtp_host, smtp_port:smtp_port, ssl_enable:ssl_enable, user_name:user)

# add an alarm generator (which self resets after an hour)
run_script("Scripts/Device/Virtual/Alarm/Alarm", duration:3600, id:"alarm")

# give the alarm generator an input which looks for a moisture alarm
run_script("Scripts/Device/Virtual/Alarm/InputTypes/Equal", alarm_id:"alarm", input_name:"moisture", value:"on")



# wire things together
wire("wired_messenger:alarm", "alarm:command")
wire("alarm:messages", "wired_messenger:alarm_message")
wire("dio:1S", "alarm:moisture")

To run this Script, you need 9 parameters: coordinator_port, dio_address, pop_host, smtp_host, smtp_port, ssl_enable, user, password, and messaging_address.

The dio_address parameter is the serial number of the Digital I/O. To convert the serial number to the dio_address parameter, strip any leading zeros from the serial number and replace them with "0x". The coordinator_port parameter is the name of the USB port of the Coordinator. On *nix hosts, the USB port name is in the "/dev" directory. To see the devices in order of their creation, type "ls -lrt /dev" at a shell prompt and look near the bottom of the list for your Coordinator's USB port.

The pop_host is the name of the POP server hosting the email account, and the smtp_host and smtp_port are the name and port of the SMTP server hosting the email account. ssl_enable determines whether SSL will be used when talking to the server. The user parameter is the user name of the email account on the server and the password parameter is the password for the email account. The messaging_address is the email/texting address of the device that will be receiving alert messages and controlling the system (typically a text messaging device or the email address of a smart phone).

As an example, for a Coordinator at USB port "/dev/cu.usbserial-00002006" and a Digital I/O with serial number "0013A200406B0263", an email server using SSL with name "email_server" with an email account of "user" and a password of "secret", and a controlling device which is a Verizon cell phone with phone number 111-555-1212, the Script parameters are:

coordinator_port: "/dev/cu.usbserial-00002006"
dio_address: 0x13A200406B0263
pop_host: "pop.email_server"
smtp_host: "smtp.email_server"
smtp_port: 587
ssl_enable: true
user: "user"
password: "secret"
messaging_address: "1115551212@vtext.com"

Running the Script

Run the Script above with your own parameters (remember, if you make a mistake, you can edit what you've done on the Console page). Go to the Device Explorer, click on the DIO's "1S" terminal, and enter on. The alarm Device's "alarm" terminal should turn on and its "messages" output should have a alarm message. Next check the device you are using for messaging. You should receive a message that looks like this:

alarm_message: Alarm is on

moisture: ALARM!

This Recipe uses a Wired Messaging POP Device. The Wired Messaging Device supports multiple outputs and inputs, so we can control multiple devices with it. In order to tell the Device which output terminal we are addressing, messages to the Device have 2 values - a terminal name and a value. To reset the alarm, send a message back to the device that looks like this:

alarm reset

Depending on your polling interval (4 minutes in this Script), it may take a few minutes for this command to take effect. You should get a message that looks like this:

alarm_message: Resetting Alarm

The alarm Device will also self reset after 1 hour (3600 seconds) as defined by the Script.

Try sending something to a nonsensical output terminal. For example, send the message: xx off. You should get back a message:

Error, unknown destination in command: "xx off"
Possible destinations are: alarm

Enjoy using your alarm system with your email/texting device.