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®, 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.


Introduction

The following documentation gives an example, how to build up a communication between TwinCAT and a Maestro100Lite-Modem. The attached example-program consists of four function-blocks for:
  • Logging in to a SIM-card with the PIN-number
  • sending a SMS
  • reading a SMS from the SIM-card
  • deleting a SMS from the SIM-card

The commands sent to the modem are given in the AT-format. Each documentation of the function-blocks contains a short reference, which AT-commands are used. Due to copyright-restrictions it is not possible to give a whole overview of all AT-commands here. But such lists can be easily found in the internet.

Requirements

  • Microsoft Windows with TwinCAT PLC (from version 2.10) for programming and commissioning
  • TwinCAT PLC Serial Communication Library
  • BK9000 with KL6031 and KL9010 or Embedded-PC (e.g. CX9000) with N030 interface (RS232)
  • Knowledge of programming in IEC 61131-3 under TwinCAT
  • Valid SIM-Card with PIN-Code
  • Maestro 100 Lite GMS/GPRS Modem


Example Overwiew

Maestro 100 Lite GMS/GPRS Modem

Example-program

This example will show, how to connect the modem to the TwinCAT-hardware and how to send commands from the PLC. There are two different versions: one for a 9-pin-COM-port of a CX9000 and another one for a RS232-Terminal KL6031. Each program consists of 4 different function-blocks with which it is possible to build up a send- and receive-operation with SMS-messages. The communication with the modem is based upon so-called AT-commands, which are described in the documentation of the function-blocks. Due to copyright-restrictions it is not possible to give a complete overview of all AT-commands here. Nevertheless such lists can be easily found in the internet.

Example-program | PLC-program and TwinCAT System Manager as a zip-file
Connecting the modem, CX-version | Connection to the Beckhoff-hardware and TwinCAT System Manager-settings, CX-version
Connecting the modem , KL-version | Connection to the Beckhoff-hardware and TwinCAT System Manager-settings, KL-version
Program-description, CX-version | Description how to use and modify the program, CX-Version
Program-description, KL-version | Description how to use and modify the program, KL-Version
FB_Maestro100LT_LogIn | FB to log in to a SIM-card with a valid PIN-number
FB_Maestro100LT_SendSMS | FB to send SMS-messages
FB_Maestro100LT_ReadSMS | FB to read SMS-messages
FB_Maestro100LT_DeleteSMS | FB to delete SMS-messages from the SIM-card
Errorcodes | Errors, which may come up


Connection to a COM-Port (CX)

Maestro 100 Lite GMS/GPRS Modem

Connection to a COM-Port

The modem has to be connected with the cable (15-pin male to 9-pin female), which is enclosed in the modem-box. If neccessary a 1:1 extension-cable can be used in case of longer distances.

The different pins on the connectors have the following meaning (the "function" refers to the COM-port of the CX, not to the modem):

SUB-D 15 (male) | function | SUB-D 9 (female)
1 | DCD | 1
2 | TX | 3
3 | BOOT |
4 | microphone+ |
5 | microphone- |
6 | Rx | 2
7 | DSR | 6
8 | DTR | 4
9 | GND | 5
10 | speaker+ |
11 | CTS | 8
12 | RTS | 7
13 | RI | 9
14 | Reset |
15 | speaker- |

The COM-port has to be inserted in the TwinCAT System Manager, if this is not already done and the proper port has to be selected. In the example-file however everything is already existent and properly configured.

After that, the communication-properties have to be set:

  • KL6xx1 Mode
  • 64 Data Bytes
  • RS232
  • 9600 Baudrate
  • 8 Databits
  • Parity: none
  • 1 Stoppbit


Connection to a KL6031

Unlike the connection to the COM-port, the connection to the KL6031 has to be wired by oneself:

The different pins on the connectors have the following meaning (the "function" refers to the KL6031, not to the modem):

SUB-D 15 (male) | function | SUB-D 9 (female)
1 | DCD | 1
2 | TX | 3
3 | BOOT |
4 | microphone+ |
5 | microphone- |
6 | Rx | 2
7 | DSR | 6
8 | DTR | 4
9 | GND | 5
10 | speaker+ |
11 | CTS | 8
12 | RTS | 7
13 | RI | 9
14 | Reset |
15 | speaker- |

The KL6031 has to be inserted in the TwinCAT System Manager. In the example-file however everything is already existent and properly configured.

The parametrisation of this COM-Port is done in the PLC.


Program-description (CX)

Maestro 100 Lite GMS/GPRS Modem

Program-description

This program will show how the serial communication between the PLC and the modem can work. There are four function-blocks in this program: one for logging in to the SIM-card, one for sending SMS-messages, one for reading messages and another one for deleting them from the SIM-card. Prior to them an instance of the function-block SerialLineControl is called at the beginning of the MAIN-routine. This function-block is part of the library COMlibV2 and handles the data-communication between the PLC and the serial port.

The two structure-variables stPCComInData (input) and stPCComOutData (output) are the connection between the PLC and the COM-port and have to be linked in the TwinCAT System Manager:

After the fbSerialLineControl one instance of each function-block, FB_LogOn, FB_SendSMS, FB_ReadSMS and FB_DeleteSMS is called. These function-blocks can be parametrized and started vwith auxiliary variables in the online-mode by writing the new value with "STRG+F7".

NOTE: Prior to the first start (the modem is properly connected to the hardware) both the control-hardware and the modem have to be currentless.

The four FBs only need triggers to be started. Therefore the starting variables are reset at the end of the MAIN-routine.

Internal structure of the function-blocks

The four function-blocks for the SMS-handling are equally structured. The Login- and the Send-FB first check, if the entered values are within certain ranges. After that - in all FBs - the AT-command is put together - first as a string, because most of the entries like phone-number or SMS-text are easier to handle that way. Then they are converted to an ARRAY OF BYTE. In this mode characters like <CR> (16#0D) or <ctrl+z> (16#1A) can easily be inserted. After that the command is sent and the upcoming answer alalysed. If no answer comes up or it takes too much time, the internal sequence will be terminated in one of the last steps, the timeout. The timer for this function is started at the beginning of each function-block by the start-trigger.


Program-description (KL)

Maestro 100 Lite GMS/GPRS Modem

Program-description

This program will show how the serial communication between the PLC and the modem can work. There are four function-blocks in this program: one for logging in to the SIM-card, one for sending SMS-messages, one for reading messages and another one for deleting them from the SIM-card. Prior to them an instance of the function-block KL6configuration is called, as well an an instance of the function-block SerialLineControl . Both modules are part of the library COMlibV2. While KL6configuration is responsible for the configuration of the KL6031-terminal, the function-block SerialLineControl handles the data-communication between the PLC and the serial port.

The two structure-variables stPCComInData (input) and stPCComOutData (output) are the connection between the PLC and the COM-port and have to be linked in the TwinCAT System Manager:

After the fbSerialLineControl one instance of each function-block, FB_LogOn, FB_SendSMS, FB_ReadSMS and FB_DeleteSMS is called. These function-blocks can be parametrized and started with auxiliary variables in the online-mode by writing the new value with "STRG+F7".

NOTE: Prior to the first start (the modem is properly connected to the hardware) both the control-hardware and the modem have to be currentless.

The four FBs only need triggers to be started. Therefore the starting variables are reset at the end of the MAIN-routine.

Internal structure of the function-blocks

The four function-blocks for the SMS-handling are equally structured. The Login- and the Send-FB first check, if the entered values are within certain ranges. After that - in all FBs - the AT-command is put together - first as a string, because most of the entries like phone-number or SMS-text are easier to handle that way. Then they are converted to an ARRAY OF BYTE. In this mode characters like <CR> (16#0D) or <ctrl+z> (16#1A) can easily be inserted. After that the command is sent and the upcoming answer alalysed. If no answer comes up or it takes too much time, the internal sequence will be terminated in one of the last steps, the timeout. The timer for this function is started at the beginning of each function-block by the start-trigger.


FB_Maestro100LT_LogIn

Description

With a valid PIN-number, this function-block logs in to the SIM-card. Prior to the login an AT-command is sent, which deactivates the echo-function. With the echo-function activated, the whole command will be repeated, when the modem is answering. This makes the analysis of the answer needlessly complicated. With a rising edge at bstart, this function-block is activated.

Internally used AT-commands

ATE0 | Turns the echo-function off
AT+CPIN=<Pin> | activates the mobile-phone-account with the PIN-number <Pin>

VAR_INPUT

bStart     : BOOL;
sPinNumber : STRING(15);

bStart: A rising edge at this input activates the function-block.

sPinNumber: PIN-number of the mobile-phone-account. The PIN-number has to be entered as a STRING. Numeric variables would loose a "0" at the beginning.

VAR_OUTPUT

bBusy    : BOOL;
bError   : BOOL;
nErrorID : UINT;

bBusy: As long as the function-block is active, this output is set to TRUE.

bError: This output is switched to TRUE if an error occurs . The command-specific error code is contained in nErrorId. bError is reset to FALSE by the next execution of the function-block.

nErrorId: Contains the command-specific error code of the most recently executed command. nErrorId is reset to 0 by the next execution of the function-block. See Errorcodes.

VAR_IN_OUT

stTxBuffer : ComBuffer;
stRxBuffer : ComBuffer;

stTxBuffer: Reference to the buffer with the transmit-data to the serial hardware.

stRxBuffer: Reference to the buffer into which the received data from the hardware is stored.


FB_Maestro100LT_SendSMS

Description

This function-block will send a SMS-message to a certain recipient (sPhoneNumber). The message will be sent in the text-mode, which is more conveniant to handle than the PDU-mode for binary files. Therefore an AT-command switching over to text-mode will always be sent prior to the sending-command.

Internally used AT-commands

AT+CMGF=1 | Switches over to text-mode (=1)
AT+CMGS=<DestinationAddress><CR><text><ctrl-z> | Sends a text <text> to the phone-number <DestinationAddress>

The AT-command for sending messages is divided into two parts: First the phone-number is sent with <CR> (16#0D) at the end. The answer from the modem should be a ">"-character (16#3E). After receiving this answer, the message text is sent and dilimited with <ctrl-z> (16#1A).

VAR_INPUT

bStart       : BOOL;
sPhoneNumber : STRING(30);
sSMSText     : STRING(160);

bStart: A rising edge at this input activates the function-block.

sPhoneNumber: Phone-number of the recipient. The phone-number has to be entered as a STRING. Numeric variables would loose a "0" at the beginning.

sSMSText: The message-text.

VAR_OUTPUT

bBusy    : BOOL;
bError   : BOOL;
nErrorID : UINT;

bBusy: As long as the function-block is active, this output is set to TRUE.

bError: This output is switched to TRUE if an error occurs . The command-specific error code is contained in nErrorId. bError is reset to FALSE by the next execution of the function-block.

nErrorId: Contains the command-specific error code of the most recently executed command. nErrorId is reset to 0 by the next execution of the function-block. See Errorcodes.

VAR_IN_OUT

stTxBuffer : ComBuffer;
stRxBuffer : ComBuffer;

stTxBuffer: Reference to the buffer with the transmit-data to the serial hardware.

stRxBuffer: Reference to the buffer into which the received data from the hardware is stored.


FB_Maestro100LT_ReadSMS

Description

There are 15 different places availble to store received SMS-messages on the SIM-card. With a rising edge at bstart, this function-block will read the message in place nIndex and show the contents at the output sMessageText.

Internally used AT-commands

AT+CMGR=<Index> Reads the SMS-message in place <Index>

VAR_INPUT

bStart : BOOL;
nIndex : USINT;

Start: A rising edge at this input activates the function-block.

nIndex: Number of the SMS-message to be read.

VAR_OUTPUT

sMessageText : STRING(240);
bBusy        : BOOL;
bError       : BOOL;
nErrorID     : UINT;

sMessageText: Text-output with the contents of the selected SMS-place.

bBusy: As long as the function-block is active, this output is set to TRUE.

bError: This output is switched to TRUE if an error occurs . The command-specific error code is contained in nErrorId. bError is reset to FALSE by the next execution of the function-block.

nErrorId: Contains the command-specific error code of the most recently executed command. nErrorId is reset to 0 by the next execution of the function-block. See Errorcodes.

VAR_IN_OUT

stTxBuffer : ComBuffer;
stRxBuffer : ComBuffer;

stTxBuffer: Reference to the buffer with the transmit-data to the serial hardware.

stRxBuffer: Reference to the buffer into which the received data from the hardware is stored.


FB_Maestro100LT_DeleteSMS

Description

There are 15 different places availble to store received SMS-messages on the SIM-card. With a rising edge at bstart, this function-block will delete the message in place nIndex. All other places remain untouched - no message will change its place after another one is deleted.

Internally used AT-commands

AT+CMGD=<Index> Deletes the SMS-message in place <Index>

VAR_INPUT

bStart : BOOL;
nIndex : USINT;

bStart: A rising edge at this input activates the function-block.

nIndex: Number of the SMS-message to be deleted.

VAR_OUTPUT

bBusy    : BOOL;
bError   : BOOL;
nErrorID : UINT;

bBusy: As long as the function-block is active, this output is set to TRUE.

bError: This output is switched to TRUE if an error occurs . The command-specific error code is contained in nErrorId. bError is reset to FALSE by the next execution of the function-block.

nErrorId: Contains the command-specific error code of the most recently executed command. nErrorId is reset to 0 by the next execution of the function-block. See Errorcodes.

VAR_IN_OUT

stTxBuffer : ComBuffer;
stRxBuffer : ComBuffer;

stTxBuffer: Reference to the buffer with the transmit-data to the serial hardware.

stRxBuffer: Reference to the buffer into which the received data from the hardware is stored.


Errorcodes

Value (hex) | Value (dec) | Description
0x0000 | 0 | no Error
0x8001 | 32769 | Timeout-Error
0x8002 | 32770 | FB_Maestro100LT_LogIn: The entered PIN-number contains less than one or more than 10 digits
0x8003 | 32771 | FB_Maestro100LT_LogIn: The entered PIN-number contains non-numeric characters
0x8004 | 32772 | FB_Maestro100LT_LogIn: The login-request sent to the modem was answered with an error-message. Possible reasons are: wrong PIN-number, no SIM-card or already logged in
0x8005 | 32773 | FB_Maestro100LT_LogIn: Undefined response from the modem
0x8006 | 32774 | FB_Maestro100LT_SendSMS: The entered phone-number contains less than one or more than 25 digits
0x8007 | 32775 | FB_Maestro100LT_SendSMS: The entered phone-number contains non-numeric characters (except the "+" for international calls)
0x8008 | 32776 | FB_Maestro100LT_SendSMS: The entered message-text contains less than one or more than 160 characters
0x8009 | 32777 | FB_Maestro100LT_SendSMS: The AT-command ATE0 for switching over to text-format is answered with an error-message from the modem
0x800A | 32778 | FB_Maestro100LT_SendSMS: The AT-command ATE0 for switching over to text-format is answered with an undefined response from the modem
0x800B | 32779 | FB_Maestro100LT_SendSMS: The AT-command AT+CMGS for sending SMS messages is answered with an error-message from the modem
0x800C | 32780 | FB_Maestro100LT_SendSMS: The AT-command AT+CMGS for sending SMS messages is answered with an undefined response from the modem
0x800D | 32781 | FB_Maestro100LT_ReadSMS: The AT-command AT+CMGR for reading SMS messages is answered with an error-message from the modem
0x800E | 32782 | FB_Maestro100LT_ReadSMS: The AT-command AT+CMGR for reading SMS messages is answered with an undefined response from the modem
0x800F | 32783 | FB_Maestro100LT_DeleteSMS: The AT-command AT+CMGD for deleting SMS messages is answered with an error-message from the modem
0x8010 | 32784 | FB_Maestro100LT_DeleteSMS: The AT-command AT+CMGD for deleting SMS messages is answered with an undefined response from the modem