Email Devices

Email Devices send and receive messages from email addresses (and text messaging devices). There are two kinds of Devices supported: TextMessagingPOP and WiredMessagingPOP Devices. Both use the POP messaging protocol for receiving messages and SMTP for sending messages.

The difference between the two kinds of Devices are TextMessaging Devices have a single input and output, and wired messaging Devices can have many. TextMessaging Devices create email messages with the values they see on their "in" terminal and update their "out" terminal with the contents of the emails they receive. WiredMessaging Devices can have multiple input and output terminals.

Systems which need only simple email capabilities typically use TextMessaging Devices. If you only need to control one Device or just require status messages, the single input and output terminals on a TextMessaging Device work well. Systems which need to monitor and control multiple Devices typically use WiredMessaging Devices. Wired messaging Devices can have as many input or output terminals as you have Devices, providing individual status and control of each Device.

WiredMessaging Devices begin with no input or output terminals. After they are created, they are assigned input and output terminals. When a WiredMessaging Device receives an email, it looks at the first word, and if the word is the same as an output terminal, it places the rest of the message on that output terminal. When a WiredMessaging Device receives a message on an input terminal, it appends the terminal name, a colon, a space, the terminal value, and sends the message. In this way, messages to and from WiredMessaging Device terminals are identified and assigned.

For example, an email with the message status: OK would be from from a terminal named "status" that got the value OK. If one wanted to send a message to a WiredMessaging Device, alarm reset would assign the value reset to the "alarm" terminal of the Device. Messages to unknown terminals are rejected.

More about How Email Messages are Received

When you wish your Device to receive an email message, you send it to the Device's email address.

If you sent the message hi there to a TextMessaging Device, you would see the value "hi there" on its output terminal (note the Device has double quoted your message).

WiredMessaging Devices are a little more sophisticated. If you sent the same message, hi there, to a WiredMessaging Device, it would look at the first word of the message, hi, and see if it had a terminal called hi. If it did, the Device would output the value "there" on its hi terminal (again, adding quotes). If it didn't have a hi terminal, it would email back an error message.

WiredMessaging Devices expect an email message whose first word is the name of a terminal. After the name, you should have a space or a colon (:), or a colon followed by a space. Any following text will appear at the named terminal. The Device will enclose the text in quotes, so there is no need to add them yourself.

The following are valid WiredMessaging messages to a Device with a terminal named "out":

out 1
out: this is a text message
out: "this is a quoted text message"

These are the values each of the above examples will generate on the "out" terminal:

"1"
"this is a text message"
"\"this is a quoted text message\""

Each time a Device receives a message, the Device will check the email's "from" address to be sure the address is valid. Only emails from valid "from" addresses will be processed. Emails from unknown addresses will be discarded. Valid addresses are defined when configuring the Device (by the email_address parameter and by the addEmailAddress Script).

When receiving email messages, TextMessaging and WiredMessaging Devices will ignore the subject line of the messages - you can have any subject you wish.

Make sure your email application isn't appending footers to your emails. They may become an unintended part of your messages.

Creating a TextMessagingPOP Device

TextMessagingPOP Devices are created by running the TextMessagingPOP Script. The parameters for the TextMessagingPOP Script are:

host :

• the host address of the POP server

user_name :

• the user name for logging in to the server

password :

• the password for logging in to the server

These parameters are optional:

email_address :

• the email address that will use the EmailDevice. This address will receive all emails created by the EmailDevice, and only emails from this address will be used by the EmailDevice. If you need more than 1 email address, see the addEmailAddress section below.

smtp_host :

• the host address of the SMTP server (often different from the POP server)

smtp_port :

• SMTP port number (the default is usually OK here)

ssl_enable :

• enable secure sockets(true/false). (Usually SSL is not necessary, but gmail requires it)

poll_interval :

• length of time (in seconds) to wait between POP polls. Generally 300 seconds or more is OK. If this value is set to nil, no polling will be done

mail_subject :

• string to put in the email subject header

gmail_polling :

• (true/false). Gmail supports a form of polling which uses a CHAT protocol, so POP polling can be done whenever messages arrive. When using gmail_polling, message latencies are tiny. Only works with gmail accounts.

Running the TextMessagingPOP Script with the parameters listed below creates a TextMessagingPOP Device.

id: "text_messenger"
host: "pop.host.com"
user_name: "user@host.com"
password: "password"
email_address: "5555551212@phone_company.com"
smtp_host: "smtp.host.com"
smtp_port: 587
ssl_enable: false
poll_interval: 300
mail_subject: "Text Messenger Message"

It sends and receives messages using an account "user@host.com" at a host called "host.com" with a password of "password". It receives messages using the POP protocol from "pop.host.com" polling every 300 seconds, and it puts them on its "out" terminal. Any messages it receives from its "in" terminal will be sent as text messages to phone number (555)555-1212 at "phone_company.com". It sends messages using SMTP to "smtp.host.com" at port number 587 without using SSL. Any messages it sends will have the subject "Text Messenger Message".

To see some real email addresses for the various phone company text messaging services (i.e. something better than 5555551212@phone_company.com), see the Email Addresses for Texting section.

Creating a WiredMessagingPOP Device

WiredMessagingPOP Devices are created by running the WiredMessagingPOP Script. The parameters for the WiredMessagingPOP Script are a superset of the TextMessagingPOP Script parameters. The additional parameters are optional and they are:

inputs :

• a comma separated string of terminal input names. These will become terminals on the Device and email whatever values they encounter.

outputs :

• a comma separated string of terminal output names. These will become terminals on the Device and generate terminal values when the Email Device receives messages for these terminals.

Terminal names must begin with a letter and be composed of only letters, numbers and underscores.

Running the WiredMessagingPOP Script with the parameters listed below creates a WiredMessagingPOP Device.

id: "wired_messenger"
host: "pop.host.com"
user_name: "user@host.com"
password: "password"
email_address: "5555551212@phone_company.com"
smtp_host: "smtp.host.com"
smtp_port: 587
ssl_enable: false
poll_interval: 300
mail_subject: "Wired Messenger Message"
inputs: "light_status"
outputs: "light"

The WiredMessagingPOP Device uses the same user and host parameters as the TextMessagingPOP Device above. Instead of using a default "in" and "out" terminal, it has user defined "light_status" and "light" terminals.

A Helper Script - addEmailAddress

The "addEmailAddress" Script can add additional emailing addresses to EmailDevices. When there is a need for more than one address, run this Script to add additional addresses. All added email addresses will get messages created by the EmailDevice, and all of the added addresses can send messages to the EmailDevice (messages from un-added addresses are ignored). The "addEmailAddress" Script parameters are:

email_device_id :

• the ID given to the Email Device. The ID tells the Script which Device to add addresses.

The following 2 parameters are optional, though if you want to add an address, you will need to specify one of them (or both).

address :

• the email address of the added user, e.g "me@myhost.com"

file_name :

• a file name of a YAML file containing a list of users.

If you choose to supply a YAML file with a list of users, the list should be formatted like this (the "addresses" tag is required):

addresses: [
  my_address1@xyz.com,
  my_address2@abc.com
]

Unquoting Output Text

Email Device outputs, by default, output quoted strings. When connecting to smart Devices, such as the "command" terminal of an Alarm Device, quoted output strings are what the Device expects. However, some Devices, such as simple switches, expect method calls, such as calls to their "on" and "off" methods.

To output unquoted strings, one calls the "define_avoid_quotes_terminals" and "avoid_quotes" methods on the WiredMessagingPop and TextMessagingPop Devices (respectively). The "define_avoid_quotes_terminals" method takes a string of terminals, one for each output terminal that should not be quoted. The "avoid_quotes" method takes no arguments, because there is only one output on the TextMessagingPop Device, which makes the desired output terminal clear.

As examples, assume we have a TexMessagingPOP Device with ID "tmpd", and a WiredMessagingPOP Device with ID "wmpd" and output terminals "1", "2", "3". To output unquoted strings on the TextMessagingPOP Device, we write:

run_script("", text:"avoid_quotes()", on_device:"tmpd")

To output unquoted strings on the WiredMessagingPOP Device on terminals "2" and "3" we write:

run_script("", text:"define_avoid_quotes_terminals(\"2,3\")", on_device:"wmpd")

Sharing Email Accounts

If you plan on using more than one Email Device, you may want to share an email account between your Devices. In general, this is not possible. When two or more Email Devices check for email from the same account, only one of them will get the messages (and the others will get nothing). So sharing will not work when 2 or more Email Devices are trying to receive mail from the same account.

However, if you only wish receive email for one (or none) of the Email Devices, then a single email account can be shared. Since only one (or no) Email Device is receiving email from the account, all received emails will go to that Device. When sending email, multiple Email Devices can share the same account without issues. So you can share an account between Email Devices, as long as no more than one of them is receiving emails.

If you wish an Email Device to only send and not receive email, set the poll_interval parameter to nil and gmail_polling to false.

Email Addresses for Texting

If one uses the right email address, EmailDevices will send and receive messages from texting Devices. Possible email addresses for texting are:

• AT&T: #@txt.att.net (SMS), #@mms.att.net (MMS)
• Cingular: #@cingular.com, #@mobile.mycingular.com
• MetroPCS: #@mymetropcs.com
• Qwest: #@qwestmp.com
• Sprint: #@messaging.sprintpcs.com (SMS), #@pm.sprint.com (MMS)
• T-Mobile: #@tmomail.net (MMS or SMS)
• Verizon: #@vtext.com (SMS), #@vzwpix.com (MMS)
• Virgin Mobile: #@vmobl.com (SMS), #@vmpix.com (MMS)

# is a ten digit cell phone number
SMS is "Short Messaging Service" for text messaging
MMS is "Multimedia Messaging Service" for email, photos and movies (smart phones may use this and not SMS)

So to send a text message to the AT&T cell phone with number (555)555-1212, use the email address 5555551212@text.att.net

For more information on email addresses for texting, try googling "List of SMS gateways"

Problems

• Seeing repeated messages coming from the host

  Some email hosts will keep all emails, even after an Email Device has POP polled the host and received all the available email. If the host keeps all email, it may cause the Email Device to see the same messages each time it polls. If you are seeing repeated email messages, check your host's settings and make sure they are set to delete messages after the host is POP polled.

• Host is not receiving any messages from the Email Device

  If your email host seems to be ignoring the messages your Email Device is sending, it may need SSL to be enabled. When creating your Device, try setting the ssl_enable parameter to true.

• The email Device is ignoring messages

  An email Device will only display messages that come from its recipients. Messages from other sources will be discarded (silently).

• Other strange behaviors

  Email Device not working properly? Check your Console Log to see if there are any warning or error messages. Log messages may identify the problem.

• Email Device is unable to login to Gmail

  Is your email Device unable to login to Gmail, even though it has the correct user name and password? Gmail modified its default email login procedure so it's different from the traditional login procedure used by email providers. Tell Gmail to use the traditional login procedure by visiting this page in your browser:

  https://www.google.com/settings/security/lesssecureapps

  Login with your email user name and password and turn on access for "less secure apps".