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
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
WiredMessaging Devices are a little more sophisticated. If you sent the same 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":
These are the values each of the above examples will generate on the "out" terminal:
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
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:
These parameters are optional:
Running the TextMessagingPOP Script with the parameters listed below creates a TextMessagingPOP Device.
It sends and receives messages using an account "firstname.lastname@example.org" 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
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:
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.
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:
The following 2 parameters are optional, though if you want to add an address, you will need to specify one of them (or both).
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):
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:
To output unquoted strings on the WiredMessagingPOP Device on terminals "2" and "3" we write:
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
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:
# is a ten digit cell phone number
So to send a text message to the AT&T cell phone with number (555)555-1212, use the email address
For more information on email addresses for texting, try googling "List of SMS gateways"