Beckhoff TF6350 User manual

Manual | EN
TF6350
TwinCAT 3 | SMS/SMTP
2022-08-17 | Version: 1.4

Table of contents
TF6350 3Version: 1.4
Table of contents
1 Foreword....................................................................................................................................................5
1.1 Notes on the documentation .............................................................................................................5
1.2 Safety instructions.............................................................................................................................6
1.3 Notes on information security............................................................................................................7
2 Overview ....................................................................................................................................................8
3 Installation .................................................................................................................................................9
3.1 System requirements ........................................................................................................................9
3.2 Installation .........................................................................................................................................9
3.3 Installation Windows CE .................................................................................................................12
3.4 Licensing .........................................................................................................................................14
4 TwinCAT SMTP........................................................................................................................................17
4.1 Configuration...................................................................................................................................17
4.2 PLC API ..........................................................................................................................................18
4.2.1 Function blocks ................................................................................................................19
4.3 Samples ..........................................................................................................................................31
4.3.1 Mail dispatch ....................................................................................................................31
4.3.2 SmtpFull sample with features ......................................................................................... 32
4.4 Appendix .........................................................................................................................................33
4.4.1 Trouble-Shooting.............................................................................................................. 33
4.4.2 Error Codes...................................................................................................................... 34
4.4.3 Windows Socket Error Codes ..........................................................................................35
5 TwinCAT SMS..........................................................................................................................................40
5.1 PLC API ..........................................................................................................................................40
5.1.1 Function blocks ................................................................................................................40
5.1.2 Functions.......................................................................................................................... 42
5.1.3 Global constants .............................................................................................................. 42
5.2 Samples ..........................................................................................................................................43
5.2.1 Sending an SMS via the Beckhoff 4G stick...................................................................... 43
5.3 Appendix .........................................................................................................................................44
5.3.1 Fault Finding .................................................................................................................... 44
6 Appendix..................................................................................................................................................46
6.1 ADS Return Codes..........................................................................................................................46
6.2 Support and Service........................................................................................................................50

Table of contents
TF63504 Version: 1.4

Foreword
TF6350 5Version: 1.4
1 Foreword
1.1 Notes on the documentation
This description is only intended for the use of trained specialists in control and automation engineering who
are familiar with applicable national standards.
It is essential that the documentation and the following notes and explanations are followed when installing
and commissioning the components.
It is the duty of the technical personnel to use the documentation published at the respective time of each
installation and commissioning.
The responsible staff must ensure that the application or use of the products described satisfy all the
requirements for safety, including all the relevant laws, regulations, guidelines and standards.
Disclaimer
The documentation has been prepared with care. The products described are, however, constantly under
development.
We reserve the right to revise and change the documentation at any time and without prior announcement.
No claims for the modification of products that have already been supplied may be made on the basis of the
data, diagrams and descriptions in this documentation.
Trademarks
Beckhoff®, TwinCAT®, TwinCAT/BSD®, TC/BSD®, EtherCAT®, EtherCAT G®, EtherCAT G10®, EtherCAT P®,
Safety over EtherCAT®, TwinSAFE®, XFC®, XTS® and XPlanar® are registered trademarks of and licensed by
Beckhoff Automation GmbH.
Other designations used in this publication may be trademarks whose use by third parties for their own
purposes could violate the rights of the owners.
Patent Pending
The EtherCAT Technology is covered, including but not limited to the following patent applications and
patents:
EP1590927, EP1789857, EP1456722, EP2137893, DE102015105702
with corresponding applications or registrations in various other countries.
EtherCAT® is a registered trademark and patented technology, licensed by Beckhoff Automation GmbH,
Germany
Copyright
© Beckhoff Automation GmbH & Co. KG, Germany.
The reproduction, distribution and utilization of this document as well as the communication of its contents to
others without express authorization are prohibited.
Offenders will be held liable for the payment of damages. All rights reserved in the event of the grant of a
patent, utility model or design.

Foreword
TF63506 Version: 1.4
1.2 Safety instructions
Safety regulations
Please note the following safety instructions and explanations!
Product-specific safety instructions can be found on following pages or in the areas mounting, wiring,
commissioning etc.
Exclusion of liability
All the components are supplied in particular hardware and software configurations appropriate for the
application. Modifications to hardware or software configurations other than those described in the
documentation are not permitted, and nullify the liability of Beckhoff Automation GmbH & Co. KG.
Personnel qualification
This description is only intended for trained specialists in control, automation and drive engineering who are
familiar with the applicable national standards.
Description of symbols
In this documentation the following symbols are used with an accompanying safety instruction or note. The
safety instructions must be read carefully and followed without fail!
DANGER
Serious risk of injury!
Failure to follow the safety instructions associated with this symbol directly endangers the life and health of
persons.
WARNING
Risk of injury!
Failure to follow the safety instructions associated with this symbol endangers the life and health of per-
sons.
CAUTION
Personal injuries!
Failure to follow the safety instructions associated with this symbol can lead to injuries to persons.
NOTE
Damage to the environment or devices
Failure to follow the instructions associated with this symbol can lead to damage to the environment or
equipment.
Tip or pointer
This symbol indicates information that contributes to better understanding.

Foreword
TF6350 7Version: 1.4
1.3 Notes on information security
The products of Beckhoff Automation GmbH & Co. KG (Beckhoff), insofar as they can be accessed online,
are equipped with security functions that support the secure operation of plants, systems, machines and
networks. Despite the security functions, the creation, implementation and constant updating of a holistic
security concept for the operation are necessary to protect the respective plant, system, machine and
networks against cyber threats. The products sold by Beckhoff are only part of the overall security concept.
The customer is responsible for preventing unauthorized access by third parties to its equipment, systems,
machines and networks. The latter should be connected to the corporate network or the Internet only if
appropriate protective measures have been set up.
In addition, the recommendations from Beckhoff regarding appropriate protective measures should be
observed. Further information regarding information security and industrial security can be found in our
https://www.beckhoff.com/secguide.
Beckhoff products and solutions undergo continuous further development. This also applies to security
functions. In light of this continuous further development, Beckhoff expressly recommends that the products
are kept up to date at all times and that updates are installed for the products once they have been made
available. Using outdated or unsupported product versions can increase the risk of cyber threats.
To stay informed about information security for Beckhoff products, subscribe to the RSS feed at https://
www.beckhoff.com/secinfo.

Overview
TF63508 Version: 1.4
2 Overview
This functionality enables alarm and status messages to be sent directly from TwinCAT. With this function,
emails or SMS can be sent according to self-defined conditions.
SMTP server:
The TwinCAT SMTP Server is used to send emails with TwinCAT via ADS.
TwinCAT SMTP Overview [}17]
SMS library:
The TwinCAT SMS library is used to send SMS messages from TwinCAT via GSM modem.
TwinCAT SMS Overview [}40]

Installation
TF6350 9Version: 1.4
3 Installation
3.1 System requirements
Technical data TF6350 TwinCAT3 SMS/SMTP
Target system WinXP, WES, Win7, WES7
IPC or CX, (x86)
Min. TwinCAT version 3.1.4000
Min. TwinCAT level TC1200 | TwinCAT 3 PLC
Requirements
Development environment Target system type PLC libraries to be linked
TwinCAT v3.1.4000 PC or CX (x86) Tc2_Smtp, Tc2_Sms
3.2 Installation
The following section describes how to install the TwinCAT3Function for Windows-based operating
systems.
üThe TwinCAT3Function setup file was downloaded from the Beckhoff website.
1. Run the setup file as administrator. To do this, select the command Run as administrator in the context
menu of the file.
ðThe installation dialog opens.
2. Accept the end user licensing agreement and click Next.

Installation
TF635010 Version: 1.4
3. Enter your user data.
4. If you want to install the full version of the TwinCAT3Function, select Complete as installation type. If
you want to install the TwinCAT3Function components separately, select Custom.

Installation
TF6350 11Version: 1.4
5. Select Next, then Install to start the installation.
ðA dialog box informs you that the TwinCAT system must be stopped to proceed with the installation.
6. Confirm the dialog with Yes.

Installation
TF635012 Version: 1.4
7. Select Finish to exit the setup.
ðThe TwinCAT3Function has been successfully installed and can be licensed (see Licensing [}14]).
3.3 Installation Windows CE
This part of the documentation describes, how you can install the TwinCAT 3 Function TF6350 SMS SMTP
on a Beckhoff Embedded PC Controller based on Windows CE.
The setup process consists of four steps:
• Downloading the setup file
• Installation on a host computer
• Transfering the executable to the Windows CE deviceSoftware installation
• Software upgrade
Downloading the setup file
The CAB installation files for Windows CE are part of the TF6350 SMS SMTP setup. Therefore you only
need to download one setup file from www.beckhoff.com which contains binaries for Windows XP, Windows
7 and Windows CE (x86 and ARM).
Installation on a host computer
After installation, the install folder (e.g. C:\TwinCAT\Functions\TF6350-SMS-SMTP) contains three
directories - each one for a different hardware platform:
•CE-ARM: ARM-based Embedded Controllers running Windows CE, e.g. CX8090, CX9020
•CE-X86: X86-based Embedded Controllers running Windows CE, e.g. CX50xx. CX20x0
•Win32: Embedded Controllers running Windows XP, Windows 7 or Windows Embedded Standard

Installation
TF6350 13Version: 1.4
The CE-ARM and CE-X86 folders contain the TF6350 CAB-File for Windows CE - corresponding to the
hardware platform of your Windows CE device. This file needs to be transfered to the Windows CE device,
see next chapter.
Transfering the executable to the Windows CE device
Transfer the corresponding CAB-File to you Windows CE device. This can be done via one of the following
ways:
• via a Shared Folder
• via the integrated FTP-Server
• via a USB Stick, CF card or SD-Card
Software installation
After the file has been transfered via one of the above methods, you need to execute the file and
acknowledge the following dialog with "Ok". Restart your Windows CE device after the installation has
finished.
After the restart has been completed, the TF6350 SMTP server and configuration will be automatically
started in background and is now available to use.
The software will be installed in the following directory on the CE device: \Hard
Disk\TwinCAT\Functions\TF6350-SMS-SMTP
Software upgrade
If you already have a version of TF6350 installed on your Windows CE device, you need to perform the
following steps on the Windows CE device to upgrade to a newer version:
• Open the CE Explorer by clicking on Start --> Run and entering "explorer"
• Navigate to \Hard Disk\TwinCAT\Functions\TF6350-SMS-SMTP\Server
• Rename TcMailSrv.exe
• Restart the Windows CE device
• Transfer the new CAB-File to the CE device
• Execute the CAB-File and install the new version of TF6350
• Delete the old (renamed) files
• Restart the Windows CE device
After the restart is complete, the new version is active.
After a successful installation the TC3 Function needs to be licensed.

Installation
TF635014 Version: 1.4
3.4 Licensing
The TwinCAT3function can be activated as a full version or as a 7-day test version. Both license types can
be activated via the TwinCAT 3 development environment (XAE).
Licensing the full version of a TwinCAT3Function
A description of the procedure to license a full version can be found in the Beckhoff Information System in
the documentation "TwinCAT3Licensing".
Licensing the 7-day test version of a TwinCAT3Function
A 7-day test version cannot be enabled for a TwinCAT 3 license dongle.
1. Start the TwinCAT 3 development environment (XAE).
2. Open an existing TwinCAT 3 project or create a new project.
3. If you want to activate the license for a remote device, set the desired target system. To do this, select
the target system from the Choose Target System drop-down list in the toolbar.
ðThe licensing settings always refer to the selected target system. When the project is activated on
the target system, the corresponding TwinCAT 3 licenses are automatically copied to this system.
4. In the Solution Explorer, double-click License in the SYSTEM subtree.
ðThe TwinCAT 3 license manager opens.

Installation
TF6350 15Version: 1.4
5. Open the Manage Licenses tab. In the AddLicense column, check the check box for the license you
want to add to your project (e.g."TF4100TC3ControllerToolbox").
6. Open the Order Information (Runtime) tab.
ðIn the tabular overview of licenses, the previously selected license is displayed with the status
“missing”.
7. Click7-DayTrialLicense... to activate the 7-day trial license.
ðA dialog box opens, prompting you to enter the security code displayed in the dialog.
8. Enter the code exactly as it is displayed and confirm the entry.
9. Confirm the subsequent dialog, which indicates the successful activation.
ðIn the tabular overview of licenses, the license status now indicates the expiry date of the license.

Installation
TF635016 Version: 1.4
10. Restart the TwinCAT system.
ðThe 7-day trial version is enabled.

TwinCAT SMTP
TF6350 17Version: 1.4
4 TwinCAT SMTP
The TwinCAT SMTP Server can be used to send emails directly from the PLC. For this purpose, the ADS
server is started together with TwinCAT when the installation is complete. The server is addressed via ADS
from the PLC. Several function blocks [}18] are available for sending emails in the PLC:
The TwinCAT SMTP Server can communicate with a local mail server or external mail providers. It supports
TLS and STARTTLS encryption methods.
4.1 Configuration
The TC SMTP server uses an XML-based configuration. The TcSmtpConfig.xml is located in the
installation directory of the supplement.
Default configuration:
<TcSmtpConfig>
<!-- EnableLogFile: 0 (Disabled), 1 (Enabled) -->
<EnableLogFile>0</EnableLogFile>
<!-- LogSize: in Byte, 0 = use Default -->
<LogSize>0</LogSize>
<!-- Authentication: 0 (NONE), 1 (AUTO), 2 (LOGIN), 3 (NTLM), 4 (PLAIN) -->
<Authentication>1</Authentication>
<!-- Port: 0 (use default ports) -->
<Port>0</Port>
<!-- ContentEncoding: 0 (7BIT), 1 (8BIT), 2 (BINARY), 3 (BASE64), 4 (QUOTED_PRINTABLE) -->
<ContentEncoding>0</ContentEncoding>
<!-- Timeout for the socket connection -->
<Timeout>8000</Timeout>
<!-- Charset for the message content -->

TwinCAT SMTP
TF635018 Version: 1.4
<Charset>iso-8859-1</Charset>
<Reconnects>5</Reconnects>
</TcSmtpConfig>
Note on the XML configuration file
EnableLogFile: a log file is created in the installation directory.
Authentication: selection of the authentication method. Use option 1 as default.
Port: option 0 uses the default ports for sending mail.
ContentEncoding: defines the decoding of the content.
Timeout: timeout for sending mail in ms.
Charset: defines the character encoding.
Reconnects: number of repetitions.
Requirements
Development environment Target system type PLC libraries to be linked
TwinCAT v3.0.0 PC or CX (x86) Tc2_Smtp
4.2 PLC API
The TwinCAT library provides function blocks for sending emails to the TwinCAT SMTP server.
Name Description
FB_SmtpV3 [}19] Function block for sending emails to the TwinCAT
SMTP Server
FB_SmtpV3_Full [}21] Function block with additional properties (e.g. send
attachments, set priorities, HTML messages)
Obsolete function blocks
The function blocks, which are described in the chapter obsolete are obsolete. Their usage is depri-
cated. Please use the function blocks FB_SmtpV3 and FB_SmtpV3_Full which should provide the
same functionality.
Requirements
Development environment Target system PLC libraries to be linked
TwinCAT v3.0.0 PC or CX (x86) Tc2_Smtp

TwinCAT SMTP
TF6350 19Version: 1.4
4.2.1 Function blocks
4.2.1.1 FB_SmtpV3
The function block sends a byte stream to an ADS device. The TwinCAT SMTP Server must be running on
the target system in order to receive the stream and send it as an email. Once the byte stream is sent, the
email is sent.
VAR_INPUT
VAR_INPUT
sNetId: T_AmsNetID; (* AmsNetID *)
sSmtpServer: T_MaxString; (* Smtp Server address ( IP or Name) *)
sUsername: T_MaxString; (* Smtp Username *)
sPassword: T_MaxString; (* Smtp Password *)
nEncryption: UDINT;(* 0=NONE, 1=STARTTLS, 2=TLS *)
sFrom: T_MaxString; (* Sender string *)
sTo: T_MaxString; (* To recipient string *)
sCc: T_MaxString; (* Cc recipient string *)
sBcc: T_MaxString; (* Bcc recipient string *)
sSubject: T_MaxString; (* Subject string *)
pMessage: POINTER TO STRING;(* Pointer to the message *)
cbMessage: UDINT;(* Message lenght in byte to send *)
bExecute: BOOL;
tTimeout: TIME := T#20s;
END_VAR
sNetId: AmsNetID on which the TwinCAT SMTP Server is running.
sSmtpServer: name or IP of the SMTP server to reach.
sUsername: user name of the SMTP server to be reached.
sPassword: password of the SMTP server to be reached.
nEncryption: SMTP encryption type:
0 = NONE
1 = STARTTLS
2 = TLS
sFrom: a string containing the email address or name of the sender. The sender must be specified. The
string is limited to 255 characters.
sTo: a string containing the email address of the recipient. At least one recipient must be entered. However,
it is also possible to enter multiple addresses. These must be separated by a semicolon. The string is limited
to 255 characters.

TwinCAT SMTP
TF635020 Version: 1.4
sCc: a string containing the email address of additional recipients (cc=carbon copy). It is possible to enter
multiple addresses of recipients, these must then be separated by a semicolon. However, the string can also
remain empty. A copy of the email will be sent to the recipient(s). The recipient's email address is visible to
other recipients. The string is limited to 255 characters.
sBcc: a string containing the email addresses of additional recipients (Bcc = blind carbon copy). It is
possible to enter multiple addresses of recipients, these must then be separated by a semicolon. However,
the string can also remain empty. A copy of the email will be sent to the recipient(s). The recipients' email
address is not visible to other recipients. The string is limited to 255 characters.
sSubject: this string contains the subject of the email. If the email is sent without a subject, the computer
name of the sender is automatically written in the subject line (e.g. "Email sent by: CX-00762C"). The subject
line string is limited to 255 characters.
pMessage: this parameter specifies the address of the string containing the message text. If the email is
sent without text, the date and time will be inserted automatically (e.g. "Mail send at Thu, 23 Mar 2006
02:31:44 -0800"). The address of the string can be specified with the ADR operator.
cbMessage: length of the email text. The length can be specified by the LEN operator.
bExecute: the function block is enabled by a rising edge at this input variable.
tTimeout: the maximum time allowed to execute a command.
VAR_OUTPUT
VAR_OUTPUT
bBusy: BOOL;
bError: BOOL;
nErrId: UDINT;
END_VAR
bBusy: the output variable remains TRUE until the function block has executed a command, but only until
tTimeOut has expired.
bError : the output variable is switched to TRUE as soon as an error occurs during the execution of the
command. The command-specific error is contained in nErrId.
nErrId: contains the command-specific error code of the last executed command
Make sure, that you don't use \o within byte-arrays. Otherwise the Message will be cut.
The maximum amount of characters, that can be used in a message, is 510.725 - you have 1275
characters for From, To, Cc, Bcc and Subject.
Requirements
Development environment Target system type PLC libraries to be linked
TwinCAT v3.0.0 PC or CX (x86) Tc2_Smtp