The Send Email TLM (Cat No SM-MSG) is an add-on firmware option for SoftPLC version 4.x and later, which can be purchased for each system needing the capability to send emails or text messages. This capability is implemented as a TOPDOC Loadable Module (TLM), written in C++ and implements a ladder instruction (TLI) which sends email using the well known SMTP protocol. This document describes the installation, usage, and functionality of the sendmail TLM.
This TLM may be used to send email by way of a ladder logic instruction, giving the user full programatic control over the trigger conditions. Queuing is implemented. Therefore a number of outbound emails can be triggered within a very small window of time and the TLM will queue up the requests on a first in first out basis in the same way that an alarm annunciator would. The queued emails will be sent out as fast as possible, depending on the speed of the connection path to the SMTP server and SMTP server speed.
A number of different SMTP authentication methods are supported, include the one used by Google's well known gmail. Providing you have a gmail account, the GMail SMTP server can be used to forward messages to your cell phone. (Gmail accounts are readily attainable for free, making this capability available to all SoftPLC users with Internet access.)
- An email message consists of the following parts: recipient list, sender identity, message body, and optional attachment.
- An SMTP server is provided by your Internet Service Provider, or you may use any for which you can provide authentication information such as a username and password. This TLM must be given authenticated access to an SMTP server. That is, all email is sent through an SMTP server on the Internet or in house.
The SoftPLC runtime engine software supports TLMs, which are shared library extensions to SoftPLC. A TLM may be loaded either as a DRIVER or as a MODULE. The difference between a DRIVER and a MODULE is that a DRIVER is called once per SoftPLC scan, and optionally an additional number of times per scan. A MODULE is only called when the control program decides to call it and not as an inherent part of the scan. TLMs are made known to SoftPLC in the MODULES.LST file which may be edited by TOPDOC NexGen by traversing to: PLC | Modules.
This SENDMAIL TLM is to be used as a MODULE, not as a DRIVER, and it provides a Topdoc Loadable Instruction (TLI) called SENDMAIL that you call from your ladder program. A new email is sent on any false to true rung condition edge. The SENDMAIL TLI takes a CONTROL datatable element as its first parameter and uses this to keep track of edge triggering and email sending progress. Each TLI used in your ladder program must have its own dedicated unique CONTROL element.
In order to use the SENDMAIL TLI you need a working ethernet connection, DNS server, and default gateway. This TLM takes a configuration file named SENDMAIL.LST which holds information about one or more SMTP servers that you intend to use, and about your SMTP account on each identified server.
Up to 5 email messages may be queued at one time in RAM before the SENDMAIL TLI begins to report that the queue is full. As soon as the first queued up email message has been sent, this frees up another slot and then the TLI is ready for another rising edge trigger condition. (The limit of 5 is arbitrary. If you have enough RAM relative to the size of your email messages, this limit can be expanded upon special request.)
An email message can consist of a text file that you prepare in advance on a SoftPLC runtime disk. Optionally, a second file can be included as an attachment to the email. The attachment is another disk file, and if provided, can be either text or binary in nature.
A few different levels of verbosity are supported regarding debug logging of the SMTP transactions.
A command line program is provided allowing you to debug your configuration and SMTP client setup outside of the SoftPLC runtime, yet on the same box using the Linux command prompt.
- A working link to the Internet, using either ethernet, modem, or PPP.
- A DNS server defined in your /etc/NETWORK.LST file.
- A default gateway defined in your /etc/NETWORK.LST file.
- Version 4.x SoftPLC or later.