1. Terms of Use
Because of the variety of uses of the information described in this manual, the users of, and those responsible for applying this information must satisfy themselves as to the acceptability of each application and use of the information. In no event will SoftPLC Corporation be responsible or liable for its use, nor for any infringements of patents or other rights of third parties which may result from its use.
SOFTPLC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE.
SoftPLC Corporation reserves the right to change product specifications at any time without notice. No part of this document may be reproduced by any means, nor translated, nor transmitted to any magnetic medium without the written consent of SoftPLC Corporation.
SoftPLC, and TOPDOC are registered trademarks of SoftPLC Corporation.
© Copyright 2010-2025 SoftPLC Corporation ALL RIGHTS RESERVED
| First Printing |
May, 2010 |
| Latest Printing |
June, 2025 |
SoftPLC Corporation 25603 Red Brangus
Drive Spicewood, Texas 78669
USA Telephone: 1-800-SoftPLC
Fax: 512/264-8399
URL: http://softplc.com
Email: support@softplc.com
2. Overview
2.1. Introduction
The SendMail TLM (Cat. No SM-MSG) is an optional firmware add-on for SoftPLC version 4.x and later; available, with purchase, for systems requiring 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 given (1) the speed of the connection path to the SMTP server and (2) SMTP server speed.
A number of different SMTP authentication methods are supported; for example, the one used by Google’s well known Gmail. Provided you have a Gmail account, the Gmail SMTP server can be used to forward messages to your cell phone.
2.2. Definitions
-
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.
2.3. Concepts
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 used as a MODULE (not as a DRIVER) and it provides two Topdoc Loadable Instructions (TLI) called SENDMAIL and GROUPMAIL which are called from your ladder program. A new email is sent on any false to true rung condition edge. The SENDMAIL and GROUPMAIL TLI’s take a CONTROL datatable element as their first parameter and use 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.
2.4. Features
In order to use the SendMail TLM 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 drive. Optionally, a second file can be included as an attachment to the email. The attachment is another file on the runtime drive, 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.
2.5. Requirements
-
A working link to the Internet, using either ethernet, modem, or PPP.
-
A DNS server defined in your /etc/NETWORK(S).LST file.
-
A default gateway defined in your /etc/NETWORK(S).LST file.
-
Version 4.x SoftPLC of later.
3. Usage
To utilize the SENDMAIL TLM, the following procedure shall first be completed. Steps 1-3 are described in detail within this chapter.
-
TLM Installation - Ensure the TLM is installed in the SoftPLC
-
Enable TLM – Configure SoftPLC to load the TLM at startup
-
Configure TLM – Edit the configuration file for your desired communications
-
Configure other Device(s) – Following vendor instructions, set up the other device(s) to communicate with the SoftPLC (not described in this document)
3.1. Driver Installation
The SendMail TLM’s library file is named 'sendmail.tlm.so', and its configuration file is 'SENDMAIL.LST'. If the SendMail option was included when purchasing the SoftPLC, these files are already installed in the /SoftPLC/tlm directory. If they are not installed, please contact SoftPLC support.
3.2. Enable SendMail TLM
| The TOPDOC NexGen Manual and Help System describe using the Module Editor to enable and configure TLM’s. The following sections assume previous knowledge of TOPDOC NexGen’s Module Editor, and other SoftPLC configuration procedures. |
To use the SendMail TLM, navigate to TOPDOC NexGen’s PLC | MODULE editor. Then enable the TLM by filling the Use checkbox on the same row as the SENDMAIL.TLM entry (Save and Send after filling the checkbox). Next, click on the Configure button.
| It is good practice to both Save and Send the edits, this way both the development system and the SoftPLC get a copy. |
| Whenever a modified list of modules and/or configuration files is sent, the SoftPLC must be restarted (or power-cycled) prior to said changes to taking effect. |
3.3. Configure TLM
The configuration file for the SendMail TLM is a text file called SENDMAIL.LST.
3.3.1. SENDMAIL.LST Configuration Editor Usage
With the SENDMAIL.TLM line highlighted/selected, click the Configure button below the list of modules. This will load the Configuration Editor for the SENDMAIL.LST file.
A template file is included in the SoftPLC. When connected to the SoftPLC, use the Fetch to load the template file into the Configuration Editor.
After SENDMAIL.LST is configured for the application, execute a Save and Send. Finally, for the changes to take effect, there are three options:
-
Power cycle the SoftPLC.
-
Restart the SoftPLC via the PLC | Startup tab 'Restart SoftPLC Runtime…' button.
-
You may enter "Remote Program" mode using the ladder online editor, then select "Remote Program" a second time. This psuedo transition from Remote Program to Remote Program is a signal to the TLM that it should reload its configuration file. This way you can reconfigure without cycling power, although it does require you enter "Remote Program" mode (twice!).
3.3.2. SENDMAIL.LST Configuration File
The figure below shows the structure of the SENDMAIL.LST configuration file. Depending on your application, you will need to re-configure and/or de-activate certain elements of the template SENDMAIL.LST file.
| The recommended method of de-activating certain lines of the SENDMAIL.LST file is to add a “#” to the beginning of each line that should be interpreted as a comment. |
# Configuration file for SoftPLC SENDMAIL TLM.
# Anything from # to end of line is a comment.
# The debug flag comes first, set to 0 to turn off debugging.
#define DEBUG_SHOW_ARGS (1 << 0) //< print the TLI arguments
#define DEBUG_TRANSACTIONS (1 << 1) //< print transactions with mail server
debug = 3
#debug = 0
# Next comes one or more identities. An identity consists of
# identity = name
# and a number of trailing attribute/value pairs that follow on separate lines.
# The identity name must match your TLI "Identity" ladder instruction parameter.
# Then comes server, reverse_path, and optionally: username, password, starttls, helo.
#########################################################################
identity = birch.net
# server: set to the name and port number of the SMTP server. Be sure and
# provide the port number, either 25 or 587 after the server name.
server = mailserver.birch.net:25
# reverse_path: is tantamount to the "From:" email header, but is called
# reverse_path because of RFC 2821. Think of this as a from field for the
# email.
reverse_path = dick@softplc.com
# helo: set the hostname to be identify as when sending HELO or EHLO commands.
# This is a per identity option. It should be the name you are seen as
# from the answering server. If none given, then this machine's hostname
# is used (and that is usually sufficent).
helo = plc42
# username = plc42@factoryname.com
# password = secretsmyfriend
starttls = disabled
#########################################################################
identity = gmail
server = smtp.gmail.com:587
# helo = plc42
username = smtpuser@gmail.com
password = passWord4
starttls = required
reverse_path = plc42@factoryname.com
Configuration File Elements Explained
| debug |
See 'Debugging' chapter of this manual for greater detail. |
|||||||||
| identity |
Correlates with the 'Identity' parameter of the TLI which utilizes it. Allowing TLI’s to operate within specific SMTP identities; as opposed to, all defined SMTP identities. There may exist one, or more, identities. |
|||||||||
| server |
Name and port number of the SMTP server. Be sure and provide the port number, either 25 or 587 after the server name. Port 25 is the original port used for SMTP; however, it is often blocked by many ISPs. Port 587 is recommended in most cases. |
|||||||||
| reverse_path |
What email address should be entered into the 'From:' field of this email? (e.g., your email address.) |
|||||||||
| username (optional) |
The username for SMTP server login. This is an optional parameter which is determined by the SMTP server; i.e., not SENDMAIL TLM. |
|||||||||
| password (optional) |
The password for SMTP server login. This is an optional parameter which is determined by the SMTP server; i.e., not SENDMAIL TLM. The password may be entered in two separate styles as explained in the following table:
|
|||||||||
| starttls (optional) |
STARTTLS is a protocol command used to upgrade a plain-text connection to a secure, encypted one using Transport Layer Security (TLS). This setting determines how SendMail TLM shall behave if establishing an encrypted connection with the email server.
|
|||||||||
| helo (optional) |
Set the hostname to be identified as when sending HELO or EHLO commands. This is a per identity option. It should be the name you are seen as from the answering server. If none given, then this machine’s hostname is used (and that is usually sufficent). |
4. Ladder Instructions
This TLM implements two TOPDOC Loadable Instructions (TLIs); SENDMAIL & GROUPMAIL.
Both instructions are low to high edge triggered, and this edge will queue up another copy of an outbound email with the makeup given by the TLI parameters. Currently the queue size is arbitrarily set to 5 emails. A sixth attempt would not succeed until the first email was completely sent.
Upon completion, either the DN bit or ER bit will be set:
-
Success: The DN (done) bit is set within the CONTROL, the POS field of the CONTROL will increment by 1, and the email will have been sent OK.
-
Failure: The ER (error) bit will be set, the LEN field within the CONTROL will be set to a non-zero error code, and the Result: STRING will tell you what went wrong. The POS field of the CONTROL will increment by 1.
4.1. SENDMAIL
4.1.1. SENDMAIL Instruction Parameters
| Control |
A datatable CONTROL element ("R") consisting of 3 words. Used to keep track of the progress of the email. |
| Result |
A datatable STRING element ("ST") that will hold explanatory text about the status of the send operation at completion. |
| Identity |
A datatable STRING element which names a record in the SENDMAIL.LST file. The named file record will provide the SMTP server, SMTP account username and password, and Reverse-Path. Reverse-Path is a formal designation of the "From:" address.
|
| To |
A datatable STRING element ("ST") which holds a recipient list of email addresses, separated by a comma. No comma if only a single address. For example: "rbs@hme.com, another@hme.com" without the quotes. |
| Subject |
A datatable STRING element ("ST") holding text which will appear as the 'Subject:' field of the email. |
| File |
A datatable STRING element which holds the filename of the main body of the email message.
|
| Attachment |
A datatable STRING element ("ST") which holds the filename of the attachment to the email message. An empty STRING is interpreted as no attachment.
|
4.2. GROUPMAIL
GROUPMAIL TLI works identically as SENDMAIL with the added feature of the 'To Count:' parameter; therefore, only 'To Count:' is explained below.
4.2.1. GROUPMAIL Instruction Parameters
| To Count |
If your recipient list becomes longer than 82 characters; which is a single STRING element ("ST") maximum length. Than the next consecutive STRING elements can be designated to allow continuing the recipient list. For example, if the 'To:' parameter is ST11:2, and the 'To Count:' parameter is '1'; then, ST11:2 and ST11:3 will be concatenated as a single recipient list. |
5. Debugging
This section gives tips on debugging problems with the TLI.
|
Before you start debugging, you should use the configuration editor to Fetch and then Save your existing configuration. Then on your development system (Windows computer), temporarily copy the file \SoftPLC\plc\<PLCNAME>\SENDMAIL.LST to a safe place. Then you can edit the configuration file temporarily and experiment freely. Later restore by copying from the safe place back to \SoftPLC\plc\<PLCNAME>\SENDMAIL.LST. Then use the editor to Load then Send the file back down to SoftPLC. Remember that you have to restart SoftPLC after each configuration change (prior to the changes taking effect)! |
5.1. Using the Command Line Program mailtest
Run the program /SoftPLC/run/mailtest without any arguments and it will tell you how to send an email from the command line. Use this to hone your email components for the TLI.
5.2. Enable Debugging
The SoftPLC runtime engine constantly monitors its processes, and 'logs' these observations as process output. By default, these logs are minimal. However, for troubleshooting purposes, the logs can provide greater detail.
In the configuration file (SENDMAIL.LST), there is the top most element debug.
| Possible Values | Description |
|---|---|
0 |
Driver print statements are 'off' |
1 |
Print TLI arguments |
2 |
Print mail server transactions |
3 |
Print both TLI arguments and mail server transactions |
5.3. View Debugging
Viewing these logs shall be completed at the command prompt of the SoftPLC system. To access the command prompt, log into the SoftPLC by either:
-
(from Windows) use third-party 'PUTTY' application
-
(from Linux) use SSH from Terminal application
-
(TOPDOC 5.x) use Remote Console feature in the 'PLC' window
|
Default login credentials are as follows: user: root password: softplc |
Once logged in, the logs can be viewed by executing one of the following:
(the '#' represents the prompt, and is not typed)
-
For SoftPLC firmware 4.x
-
# logread
-
-
For SoftPLC firmware 5.x
-
# journalctl -u softplc
-
You may need to use the arrow keys to scroll down to the end of the logs. The last logs are the most recent.
-
To exit the "journalctl" viewer, press "q".
-
-
5.4. Direct Debugging to Text File
The previous sections have shown how to view the logs from the command prompt. However, recording the logs to text file format is, in the least, efficient for receiving support. Accomplishing this, much like viewing the logs, is firmware dependent (see following sections). Once the text file is created, it can be transferred via (S)FTP to the TOPDOC machine. A detailed explanation of (S)FTP transfers can be found in the TOPDOC User’s Guide.
5.4.1. Direct Debugging output into a text file (SoftPLC 4.x)
-
Log into SoftPLC using either a) PUTTY from Windows or b) using ssh from Linux or c) at the command prompt of the SoftPLC system.
-
Run this command:
# /etc/init.d/softplc.sh stop -
Change into the /SoftPLC/run directory:
# cd /SoftPLC/run -
You can run SoftPLC from the command prompt now and redirect its output to an arbitrary file (named out.txt here). We put that file into the RAM disk which is anchored in the /tmp directory.
# ./runsplc > /tmp/out.txt -
Let this run for 5-60 seconds, then press control-C. Now you have the output captured in file /tmp/out.txt, each request-response transaction will be captured in that file.
-
You can look at the file using the program named "less".
# less /tmp/out.txt
Press ESC when done. -
You can make configuration file changes and Send them down to SoftPLC. Then merely repeat the part of this process starting at step 4 above.
-
When done, remember to set debug back to "0", then you can start SoftPLC as a daemon either by a) power cycling the box or b) doing the following:
# /etc/init.d/softplc.sh start
5.4.2. Direct Debugging output into a text file (SoftPLC 5.x)
-
Log into SoftPLC using either a) the remote console feature in TOPDOC’s PLC window, b) PUTTY from Windows, or c) using ssh from Linux.
-
Run this command:
# systemctl stop softplc -
Change into the /SoftPLC/run directory:
# cd /SoftPLC/run -
You can run SoftPLC from the command prompt now and redirect its output to an arbitrary file (named out.txt here). We put that file into the RAM disk which is anchored in the /tmp directory.
# ./runsplc > /tmp/out.txt -
Let this run for 5-60 seconds, then press control-C. Now you have the output captured in file /tmp/out.txt, each request-response transaction will be captured in that file.
-
You can look at the file using the program named "less".
# less /tmp/out.txt
Press ESC when done. -
You can make configuration file changes and Send them down to SoftPLC. Then merely repeat the part of this process starting at step 4 above.
-
When done, remember to set debug back to "0", then you can start SoftPLC as a daemon either by a) power cycling the box or b) doing the following:
# systemctl start softplc