Recipe for Controlling an XBee Smart Plug Using Text/Email Messages

This Recipe demonstrates how to control an XBee Smart Plug using text/email messages. Each time a message is sent, it will be acknowledged with a return message, so the sender knows what happened.

Ingredients

For this Recipe, you will need:

• an XBee Smart Plug
• an XBee Coordinator (XStick)
• a dedicated email account

Before installing the Smart Plug, inspect the Smart Plug case until you find its serial number label. It often has a bar code at the top, and 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 Smart Plug into an electrical socket where you wish to control a light or appliance, and plug the XStick into a USB port on your host computer. Keep the XStick and the Smart Plug 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:

# Control a Smart Plug using email/text messages.
# Returns a status message for each control message.
# Requires an XBee Smart Plug and Coordinator.

# get the XBee address of the Smart Plug
script_parameters("plug_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
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 smart switch
run_script("Scripts/Device/XBee/SmartPlug", address:plug_address, id:"smart_plug", 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:"smart_plug_status", mail_subject:"Virtual Wired Text Messenger", outputs:"smart_plug", password:password, poll_interval:240, smtp_host:smtp_host, smtp_port:smtp_port, ssl_enable:ssl_enable, user_name:user)

# don't add quotes to what comes from our output terminals
run_script("", text:"define_avoid_quotes_terminals(\"smart_plug\")", on_device:"wired_messenger")


# wire things together
wire("wired_messenger:smart_plug", "smart_plug:1")
wire("smart_plug:1S", "wired_messenger:smart_plug_status")

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

The plug_address parameter is the serial number of the Smart Plug. To convert the serial number to the plug_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 controlling the Smart Plug.

As an example, for a Coordinator at USB port "/dev/cu.usbserial-00002006" and a Smart Plug 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"
plug_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 Smart Plug's "1" terminal, and enter on. The Smart Plug should turn on. Next check the device you are using for messaging. You should receive a message that looks like this:

smart_plug_status: on

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 turn the Smart Plug off, send a message back to the device that looks like this:

smart_plug off

Depending on your polling interval (4 minutes in this Script), it may take a few minutes for this command to take effect.

Email Devices, by default, quote their output values. In this Recipe, we don't want quoted values, we want unquoted on and off values - the only values the "smart_plug" understands. To make the "smart_plug" values be unquoted, we call the "define_avoid_quotes_terminals" method (see Script above).

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

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

Enjoy controlling your Smart Plug with your email/texting device.