Email Configuration

See also: Networking and Communications

See also: GSM Configuration

 

Topic Menu

 

Email Overview

An electronic mail message consists of two components, the message header, and the message body, which is the email's content. The message header contains control information, including, an originator's email address and one or more recipient addresses. Usually additional information is added, such as a subject header field. This feature is designed to send email messages embedding real time data of the controllers and can be configured using Cscape.

 

Note:  

  • The user needs to do Ethernet Module Enhanced Configuration from Hardware Configuration to use for Email over Ethernet. See Ethernet Configuration Overview.

  • The Email over Ethernet feature requires Cscape 9.0 or higher.

  • Email over GPRS configuration can be configured through Home > Messaging > GPRS.

  • User can add maximum of 32 contacts in the Directory list and can configure up to 128 outgoing messages.

 

Email Configuration

To open the Email Configuration dialog, Home > Program > Messaging > Email

 

The following dialog will open, select Enable Email Configuration.

Email Status Register Configuration:

  • Address: Enter the starting register location to indicate the Email Status Register Details communication.

  • Name: Enter (or select) an I/O Name.

 

Selecting Additional E-Mail Configuration opens the following dialog:

Note: If the device has GPRS communication option board, emails can be sent over GPRS. For this, GPRS should be selected in the above dialog. See GPRS Configuration for more details.

To setup email configuration through registers, Get Settings from Register checkbox can be enabled. In this case the entire configuration data is taken from registers as shown below:

Email Address: The Email address of the controller can be configured here. If the user wants to provide email address through register, the Get Settings from Register checkbox can be clicked and register reference can be provided in E-mail Address edit-box. The register mentioned here should contain the email address followed by null terminationClosed Null Termination - To place a NULL character (character code 0) at the end of ASCII data. Some functions require NULL Termination to be able to determine the end point of the ASCII data since that data may vary in length from one time to the next. or space.

SMTP Server:

  • SMTP Server IP:The SMTP Server IP address of the email service provider needs to be provided here. In case SMTP server IP needs to be obtained from DNS server, select Obtain SMTP Server IP Address from DNS Server checkbox. This will enable DNS Server IP and SMTP Server Name edit-boxes. Configure these with the information provided by email service provider.

  • Port: The default port for email configuration is set to 25 but can be changed by the user if required.

  • Get Settings from Register: DNS Server IP and SMTP Server IP needs to be provided in 32-bit IP format in the defined register location. Port number needs to be provided in 16-bit numeric format at the defined register location. SMTP Server Name (if required) needs to be provided at the register mentioned followed by null termination or space.

SMTP Authentication:

  • The firmware for E-Mail also supports Login type of SMTP authentication. To use this feature, the Authentication SMTP checkbox should be checked. The user name and password for authentication needs to be provided here.

  • If Get Settings from Register: Username and Password needs to be provided at the register location mentioned followed by null termination or space.

 

Options for Configuring Email

OPTION A: Click on Email Server Configuration to configure email address, server address, and authentication.

 

OPTION B: If the user wants to provide the email configuration through registers, Get Settings from Register checkbox should be checked. In this case the entire configuration data is taken from logic registers.

Following considerations must be made when using registers for configuration.

 

Once email server is configured, click OK, and return to the email

 

SSL / TLS Support

From Firmware 14.04 onwards, SSL / TLS support has been added. Email servers which support the following cipher suite can be configured in Cscape to send emails via Ethernet or GPRS.

Cipher Suite: TLS_RSA_WITH_RC4_128_SHA (0x0005)

Example: Gmail, Yahoo supports the above-mentioned cipher suite.

 

Email Server Configuration for SSL support in Cscape

In Cscape, select Programs > Messaging > Email, and the Email configuration window opens. Select Enable Email Configuration, configure email status register and select Email Server Configuration. Currently not all the Horner OCS units have a secure protocol for sending Email on an SSL/TLS mail server. There is also a misconception that the OCS with TLS 1.2 implemented can send securely on a Gmail account. The fact is it needs the TLS1.2 to be able to negotiate a connection with the server, but it still needs to send the message through a less secure means. This requires that the account security setting be set to enable (Turn On) less secure. This document will show how to setup a Gmail account to be able to utilize the mail function on the OCS. This is not an all-inclusive list of the OCS units.

 

Gmail on TLS 1.2

For Gmail

Server Name – smtp.gmail.com

Port: 465 (SSL required) or 587 (TLS required)

DNS Server IP: 8.8.8.8

 

Gmail Account Setup

Configuration can be setup as shown or through registers. Once you have the program configured for Email it can be downloaded to the OCS. To use the Email, you will need to go to the Gmail account and turn “On” the security feature for “Less Secure App Access”, as shown below:

Once this is changed, Google will send a message to your Gmail account that needs your response that this is a change made by you. Once you have confirmed this change to Google, the controller should be able to send email. NOTE: As stated in Google security, Google will turn this feature off automatically if it’s not being used.

 

Yahoo Account Setup

Server Name – smtp.mail.yahoo.com

Port: 465 (SSL required) or 587 (TLS required)

DNS Server IP: 67.195.1.92

Click OK.

 

NOTE: For SSL / TLS email servers, default port is 587 and for other non-SSL servers it is 25.

 

Return to the Top: Email Configuration

 

Target Directory Settings

Home > Program > Messaging > Email > Email Configuration > Enable Email Configuration

 

Before creating Send Emails, a directory of email addresses needs to be created. Click on E-Mail Directory button to configure email addresses.

Note: The “Enable Email Configuration box must be checked. See below:

 

Email address configuration is very similar to SMS Address configuration with email addresses replacing phone numbers.

  • Add Contact: To add a contact. See the following screen Email Directory.

  • Modify Contact: If a contact is already added in the directory. (The user will see information about the contacts in the above screen.) To modify the contact, either double-click the row or highlight the row and click Modify Contact. The Modify Contact Information screen appears, where the contact can be modified.

  • Delete Contact:  To remove a listing after highlighting the row.

 

New Contact Information

Group Name: Enter or select a Group Name.

  1. It can contain characters A-Z, a-z, 0-9, and the _ underscore character.

  2. The first character must be A-Z, a-z, or the _ underscore character.

  3. Do not use spaces or special characters.

  4. Do not use two consecutive underscore characters.

Email ID:

Mail ID Name:If the Email ID is provided through register, the IP name also can be provided here.

Comments:Add description/comments for the email address here.

Click OK to see the contacts in the directory.

The following screen shows examples of contacts added to the directory:

With the directory being created, the users are now ready to begin creating send email message formats.

 

Return to the Top: Email Configuration

 

Outgoing Emails Settings (SEND)

Emails sent from the controller to Groups

Home > Program > Messaging > Email > Email Configuration > Outgoing Messages

Once a Group Name and email address are added to the Email Target Directory, Outgoing Messages can be sent.

Note: Before creating send Emails, an Target Directory Settings needs to be completed.

Step 1: After creating the Email Target Directory, check the Enable Email Configuration box. Then select Outgoing Messages:

Step 2: Select Add Message.

  • Add New Message: To add a new Email message format (i.e. email body).

  • Modify Message: To edit a message that is already in the list. Either double-click the row or highlight the row and click Modify Message.

  • Delete Message: To remove a message after highlighting the row.

Step 3: Select Add New Message to open Message/Email configuration dialog.

  • Trigger Variable Settings: An event is needed to trigger an Email communication from the controller to the member(s) of a Group. Enter a bit reference in the Address field that (when set to HIGH) causes the Email message associated with the trigger to be sent to the specified Group member(s). An I/O name can be entered or selected in the Name field. On successful transmission of email, the trigger bit is made low by firmware. In case of error in transmission, the status register is updated, and firmware keeps on trying to send email till trigger bit is made low by the user.

  • Message/Email Attributes: Enter or select the group that the Email message is sent to.

  • Message/Email Configuration: Messages can contain text and register data values, which approved group members can read from the controller's data registers at runtime.

    • Enter the subject of the email communication.

    • Enter the body of email.

    • In order to edit/add register data values, click F2 = Insert Field button and configure the Insert Value Field screen shown below:

 

Insert Value Field

Value Variable Settings: 

  • Enter a register reference where the data embedded in the email to send will be stored. An I/O name can be entered or selected in the Name field. Select Register Width also.

  • Up to 32 register value fields can be added to an email message.

Other Settings:

  • Select the Display Format from the dropdown. In the Decimal Position field, enter the position of the decimal point. Enter the number of digits in the Number of Digits.

  • For example: xx.xx shows that the decimal is in the 3rd position and the total number of digits (including the decimal) is 5.

  • Click the Fill Zeroes box and the Left Justified or Right Justified box if desired.

 

Insert Character in Email

Click F3 = Insert Char button or press F3 to place a character to be place in email body.

 

The following screen will appear:

 

Click OK to return to the Email Configuration screen.

 

Return to the Top: Email Configuration

 

Attach File in Email

Home > Program > Messaging > Email > Email Configuration > Outgoing Messages > Add New Message

 

Attach File option in Email Configuration allows the user to attach files that are present in the removable media of the controller.

Type:

  • All Files: All the files present in the Removable Media folder specified in "File Path" are attached to the mail sent.

  • Latest File: The most recently created file in the Removable Media folder specified in "File Path" is attached to the mail sent.

  • Oldest File: The least recently created file in the Removable Media folder specified in "File Path" is attached to the mail sent.

  • One previous to the latest file: The second most recently created file in the Removable Media folder specified in "File Path" is attached to the mail sent.

  • Specified File: The file that is specified in "File Path" is attached to the mail sent. (Wildcards are not supported for "Specified File" type.)

 

File Path:

  • The path of full filename of the file to be attached in the format.

  • {Device}\{Path}\{Filename}

  • {Device} may be

  • The removable media (microSD or USB) or

  • If omitted the removable media card (A:) defaults.

  • {Path}

  • Specifies the path to use.

  • {Filename}

  • Applicable only to the specified file type. Specifies the filename to use.

 

Any error in the attachment will be sent with the mail as "Attachment Error: Error Code". NOTE: The number of entries (files and sub folders) in any folder should not go beyond 255 for attachments to work properly

 

See System Registers used with Removable Media in Removable Media in Advanced Ladder for Error code description of Email attachment.

 

Return to the Top: Email Configuration

 

Email Status Register Details

Home > Program > Messaging > Email

 

Bit # Error Reason Remedy
1 Invalid Configuration Error

The user downloaded Cscape

configuration is invalid.

 Check and re-download Email configuration.
2 Invalid IP or Port address

Configured Email Server IP

or Port address is incorrect.

 Verify configured Email server IP Port address
3 Socket Error Internal TCP Resource Error Reduce number of TCP connection in use by device and retry
4 Bind Error Internal TCP Resource Error Reduce number of TCP connection in use by device and retry
5 Connection Timeout Error

Device is not able to connect specified

Email server within 30sec of timeout value

 Check configured Email server name (or IP address) and Port address
6 Transmit Buffer Error Internal Memory Resource Error Reset the device and retry
7 Transmit Error

Internal resource or connection break

can cause this error

 Check configured Email server name (or IP address) and Port address
8 UDPClosed UDP - User Datagram Protocol - An alternative communications protocol to Transmission Control Protocol (TCP) used primarily for establishing low-latency and loss-tolerating connections between applications on the internet. Resource Error Internal Resource Error Reduce number of UDP connection in use by device and retry
9 DNS Error Response Erroneous response received from DNS server Check configured DNS server IP address and Email Server Name
10 DNS Response Timeout No response received from DNS server Check configured DNS server IP address
11 SMTP Command Timeout

No response received from Email server

for Email command sent

Check configured Email server name (or IP address),

Port address, Email address (To and From), Username and Password
12 SMTP Error Response

Error response received from Email Server

for Email command sent

Check configured Email server name (or IP address),

Port address, Email address (To and From), Username and Password
From Firmware 15.20 onwards:
13 to 20 SMTP Error State code This field provides SMTP State (or command) code where Error occurred

1= DNS Query State

2= DNS Response State

3=Establish Connection State

4=SSL Init

5=SSL Wait HandshakeClosed Handshaking is an automated process that sets parameters for communication between two different devices before normal communication begins. Much like the way a human handshake sets the stage for the communication to follow, the computing handshake provides both devices with the basic rules for the way data is to be shared between them. These rules can include transfer rate, coding alphabet, parity, and interrupt procedure.

6=SSL Done Handshake

7=SSL Wait Write

8=SSL Handshake

9= HELO Command State

10= Authentication State

11= Username State

12= Password State

13= Sender Mail Address State

14= Receiver Mail Address State

15= Data Command State

16= Send Data State

17= Attachment

18= Send Data State

19= End Data State

20= Quit State

21=Waiting for Response

21 to 32 SMTP Server Error Response code

This field provides SMTP Error

response code received from SMTP server

Details of different error codes can be found in RFC 821

and RFC 2554 documents. For example: ‘500’ Syntax error,

command unrecognized.

NOTE: When using the Email feature, the transmit trigger bit will typically be reset by the unit within 30 seconds of being set. If this does not occur the Error status will update to indicate the error which has occurred. If there is no status then either the Device is not in RUN mode, the Email feature is not configured, or an invalid Email configuration is downloaded.

 

Return to the Top: Email Configuration