APH RTLS-Datenexportdienst-V2.13.0.0 76

SIMATIC RTLS Data Export Service
Introduction 1
Security recommendations 2
3
SIMATIC RTLS Overview
Installing the "Data Export

Service" 4
Locating systems
SIMATIC RTLS Data Export Service Configuration of the "Data
5
Export Service"
Troubleshooting 6
Application Manual
C79000-G8976-C531-07
Legal information
Warning notice system
This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent
damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert
symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are
graded according to the degree of danger.
DANGER
indicates that death or severe personal injury will result if proper precautions are not taken.
WARNING
indicates that death or severe personal injury may result if proper precautions are not taken.
CAUTION
indicates that minor personal injury can result if proper precautions are not taken.
NOTICE
indicates that property damage can result if proper precautions are not taken.
If more than one degree of danger is present, the warning notice representing the highest degree of danger will
be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to
property damage.
Qualified Personnel
The product/system described in this documentation may be operated only by personnel qualified for the specific
task in accordance with the relevant documentation, in particular its warning notices and safety instructions.
Qualified personnel are those who, based on their training and experience, are capable of identifying risks and
avoiding potential hazards when working with these products/systems.
Proper use of Siemens products
Note the following:
WARNING
Siemens products may only be used for the applications described in the catalog and in the relevant technical
documentation. If products and components from other manufacturers are used, these must be recommended
or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and
maintenance are required to ensure that the products operate safely and without any problems. The permissible
ambient conditions must be complied with. The information in the relevant documentation must be observed.
Trademarks
All names identified by ® are registered trademarks of Siemens AG. The remaining trademarks in this publication
may be trademarks whose use by third parties for their own purposes could violate the rights of the owner.
Disclaimer of Liability
We have reviewed the contents of this publication to ensure consistency with the hardware and software
described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the
information in this publication is reviewed regularly and any necessary corrections are included in subsequent
editions.
Siemens AG C79000-G8976-C531-07 Copyright © Siemens AG .

Digital Industries Ⓟ 01/2022 Subject to change All rights reserved
Postfach 48 48
90026 NÜRNBERG
GERMANY
Table of contents
1 Introduction ........................................................................................................................................... 5
2 Security recommendations .................................................................................................................... 9
3 Overview.............................................................................................................................................. 13
4 Installing the "Data Export Service" ..................................................................................................... 15
5 Configuration of the "Data Export Service" ......................................................................................... 17
5.1 General configurations ...................................................................................................... 17
5.2 Supported framing methods in the RTLS localization network ............................................. 20
5.3 Logging of internal events and data transfer ...................................................................... 21
5.4 "ExportDatabase" export module ........................................................................................ 23
5.5 "ExportTCPIP" export module .............................................................................................. 24
5.6 "ExportSTDIP" export module ............................................................................................. 25
5.7 Export module "ExportSLMP: ISO/IEC 24730-1:2014" .......................................................... 29
5.7.1 SLMP via socket (TCP/IP) ..................................................................................................... 29
5.8 "ExportAVT" export module ................................................................................................ 31
5.8.1 Configuration of the "ExportAVT" export module ................................................................ 32
5.8.2 "[Orientation]" section of the configuration file .................................................................. 35
5.8.3 Output data of the "ExportAVT" export module ................................................................... 36
5.8.4 Parameter "NodeIdent"....................................................................................................... 39
5.8.5 Telegram types of the "ExportAVT" export module .............................................................. 40
5.8.6 Coordinates for the "ExportAVT" export module .................................................................. 56
5.9 "ExportEpaperAPI" export module....................................................................................... 57
5.9.1 Overview ........................................................................................................................... 57
5.9.2 Communication via the programming interface .................................................................. 58
5.9.3 RPC calls ............................................................................................................................ 60
5.9.4 Event messages ................................................................................................................. 62
5.9.5 Code examples .................................................................................................................. 64
5.9.6 Additional information ....................................................................................................... 67
5.10 BatteryLevelEvents............................................................................................................. 67
6 Troubleshooting .................................................................................................................................. 69

Application Manual, , C79000-G8976-C531-07 3
Table of contents

4 Application Manual, , C79000-G8976-C531-07
Introduction 1
Purpose of this documentation
This document supports you in the installation and configuration of the "SIMATIC RTLS Data
Export Service" (or simply, "Data Export Service"), which is part of the localization software
"SIMATIC RTLS Locating Manager" (or simply, Locating Manager).
Validity of this documentation

This documentation is valid for version 2.13.0.0 of the "SIMATIC RTLS Locating Manager".
Additional information
You can find additional information on the SIMATIC RTLS products mentioned in this
documentation in the Readme file or on the Siemens support pages.
Link: (https://support.industry.siemens.com/cs/en/en/ps/25277)
Trademarks
SIMATIC RTLS ® is a registered trademark of the Siemens AG.
Industry Online Support

In addition to the product documentation, the comprehensive online information platform of
Siemens Industry Online Support offers support at the following Internet address:
(https://support.industry.siemens.com/cs/us/en/)
Apart from news, there you will also find:
• Project information: Manuals, FAQs, downloads, application examples etc.
• Contacts, Technical Forum
• The option submitting a support query: (https://support.industry.siemens.com/My/us/en/)
• Our service offer:
Right across our products and systems, we provide numerous services that support you in
every phase of the life of your machine or system - from planning and implementation to
commissioning, through to maintenance and modernization.
You will find contact information on the Internet at the following address:
(https://www.automation.siemens.com/aspa_app/?ci=yes&lang=en)

Introduction
SITRAIN - Training for Industry

The training offer includes more than 300 courses on basic topics, extended knowledge and
special knowledge as well as advanced training for individual sectors - available at more than
130 locations. Courses can also be organized individually and held locally at your location.
You will find detailed information on the training curriculum and how to contact our
customer consultants at the following Internet address:
(https://new.siemens.com/global/en/products/services/industry/sitrain/personal.html)
RTLS Technology and Practice (ID-RTLS-TP)

Training and certification
After completing the RTLS certification training, you will be able to plan and implement small
and medium-sized RTLS projects and provide efficient and multifaceted support in large
projects. Your RTLS basics will be strengthened and, building upon them, you will receive
new tools of the trade in order to offer customers the optimal solution for them. The
complete project sequence is taken as a reference and important steps, resources and work
results for each phase are presented. Comprehensive practical exercises in connection with
troubleshooting techniques and a great deal of input from industrial projects allow you to
internalize a confident approach to working with different types of localization projects. With
the training documents, you also receive extensive reference material for your daily work.
Link: (https://www.sitrain-learning.siemens.com/EN/en/rw35251/Industrielle-Identifikation-
RTLS-Technologie-und-Praxis)
Security information
Siemens provides products and solutions with industrial security functions that support the
secure operation of plants, systems, machines, and networks.
In order to protect plants, systems, machines and networks against cyber threats, it is
necessary to implement – and continuously maintain – a holistic, state-of-the-art industrial
security concept. Siemens’ products and solutions form one element of such a concept.
Customers are responsible for preventing unauthorized access to their plants, systems,
machines and networks. These systems, machines and components should only be
connected to the enterprise network or the Internet if and only to the extent necessary and
with appropriate security measures (firewalls and/or network segmentation) in place.
You can find more information on protective measures in the area of industrial security by
visiting: (https://www.siemens.com/industrialsecurity).
Siemens’ products and solutions undergo continuous development to make them more
secure. Siemens strongly recommends performing product updates as soon as they are
available and using only the latest product versions. Use of product versions that are no
longer supported, and failure to apply latest updates may increase customer’s exposure to
cyber threats.
To stay informed about product updates, subscribe to the Siemens Industrial Security RSS
Feed under (https://www.siemens.com/industrialsecurity).

Introduction
Note on firmware/software support

Siemens only provides bug and security fixes for the last released firmware/software version.
This means that Siemens only monitors the current firmware/software version for security
vulnerabilities.
Recycling and disposal

The products are low in harmful substances, can be recycled and meet the requirements of
the Directive 2012/19/EU for disposal of waste electrical and electronic equipment (WEEE).
Do not dispose of the products at public disposal sites.
For environmentally compliant recycling and disposal of your electronic waste, please contact
a company certified for the disposal of electronic waste or your Siemens representative.
Note the different national regulations.

Introduction

Security recommendations 2
General
Note the following security recommendations to prevent unauthorized access:
• You should make regular checks to ensure that the devices meet these recommendations
and/or other security guidelines.
• Evaluate your plant as a whole in terms of security. Use a cell protection concept with
suitable products (https://new.siemens.com/global/en/company/topic-areas/future-of-
manufacturing/industrial-security.html).
• Keep the software up to date. Check regularly for security updates for the device. You can
find information on this at the Industrial Security
(https://new.siemens.com/global/en/company/topic-areas/future-of-
manufacturing/industrial-security.html) website.
• Only activate protocols that you require to operate your system.
• Whenever possible, always use the variants of protocols that provide enhanced security
(e.g. SNMPv3).
• Connections over unsecured network areas must be secured by security mechanisms such
as SSL VPN.
• Always click on the "Disconnect" button when you have finished working with the clients.
Especially when you work remotely on the host on which the clients are located.
• Restrict access to the software and its add-on programs (e.g. database) to qualified
personnel.
• Use the user and role administration to configure the rights of the users according to their
authorizations.
Users, roles and passwords

• Define rules for the use of the software and assignment of passwords. Configure these
roles using UMC and Active Directory.
• Regularly update the passwords to increase security.
• Change user names and default passwords of the databases before you use the software.
For the SIMATIC RTLS Locating Manager, a changeable user and an editable password is
used for each installation. You can change the password via the respective DBMS version.
• Create users and roles that are tailored to the scope of authorization required by each
user. Do not exclusively use the "System administrator" role that is present by default, and
disable the "System administrator" user that is present by default after new users with
corresponding rights have been created. You disable the "System Administrator" rights for
the UMC administrator by assigning this role to a specific user or a user group.
• Only use passwords with a high password strength. Avoid weak passwords, for example
password1, 123456789, abcdefgh.

Security recommendations
• Make sure that all passwords are protected and inaccessible to unauthorized personnel.
• Do not use the same password for different users and systems or after it has expired.
Physical access
Restrict physical access to the device to qualified personnel.
Automation License Manager

If you do not require the network functions of the Automation License Manager, deny access
to its functions in your firewall.
Software (security functions)

• Keep the software up to date. Check regularly for security updates for the product. You
can find information on this at the website
(https://new.siemens.com/global/en/company/topic-areas/future-of-
manufacturing/industrial-security.html).
• Only activate the protocols, functions and interfaces that you require to operate your
system.
• Restrict access to the device with a firewall or rules in an access control list (ACL - Access
Control List).
• The option of VLAN structuring provides good protection against DoS attacks and
unauthorized access. Check whether this is practical or useful in your environment.
• Enable the logging functions to record changes and access attempts. Check the logging
information regularly.
Secure and non-secure protocols

• Check whether the use of SNMPv2c is necessary. SNMPv2c is classified as non-secure. The
product provides you with suitable setting options.
• When SNMP is enabled, change the community names. When no unrestricted access is
necessary, restrict access with SNMP.
• Use secure protocols when access to the device is not secured by physical protection
measures. The following protocols provide a secure alternative:
– SNMPv2c → SNMPv3
– SMTP (simple) → SMTP via SSL
– NTLM → Kerberos (UMC connection to Active Directory)
• Avoid or disable non-secure protocols. For historical reasons, these protocols are available,
however not intended for secure applications. Use non-secure protocols on the device
with caution.
• To prevent unauthorized access to the device or network, take appropriate protective
measures against non-secure protocols.

List of available protocols (local access via a local network)

The following is a list of all available protocols and their ports through which the RTLS
devices/products can be accessed. Note the list when you configure a firewall.
Explanation for table:
• Services/protocols
Services or protocols that support the RTLS devices/products.
• Port number
Port number assigned to the protocol/service.
• Default port status
– Open
The port is open by default.
– Closed
As default the port is closed.
• Authentication
Specifies whether the communication partner is authenticated.
• Loopback only
Specifies whether the protocol only needs local connections.
– Yes: No port must be open within the firewall. Access restrictions are recommended.
– No: The functionality requires this port to be accessed. Restrict access to necessary
hosts.
– Optional: The functionality depends on your system. Restrict access to necessary hosts
if your system requires remote access.
Service/Protocol Port number Default port status Authentication Loopback only

Data export modules TCP/variable Closed No Optional
Internal server TCP/8001 Closed No Yes
communication
Client connection TCP/9500 Open Yes Optional
Client connection TCP/9501 Open No Optional
E-mail TCP/variable Closed Optional No
Wireless network TCP/8000 Open No No
WAMP router TCP/12344 Closed Yes Optional
Microsoft SQL Server TCP/1433 Open Yes Optional
Microsoft SQL Server UDP/1434 Open No Optional


Overview 3
General
This section describes the operation of the "Data Export Service" for the Locating Manager.
The service is required if the localization data calculated by the Locating Manager will not be
visualized and managed using the clients or not exclusively with them.
Note
The service may only be used by experienced and trained users.
Application
The "Data Export Service" sends the position data calculated by the Locating Manager and,
depending on the configuration, user-specific data from the transponders to the external
recipient for further processing and analysis. The following technologies are used for this
purpose:
Name Description
Database Export of positions in a database table
TCP client The module is a TCP client that establishes a connection to a TCP server. If the
connection is interrupted, the module cyclically attempts to re-establish the
connection.
TCP server The module is a TCP server and opens a TCP port.
WAMP The module exports its information about this technology.
The following simultaneously operable export processes are available as output options:
Name Technology Description

ExportDatabase Database Export of positions in a database table
ExportTCPIP TCP client Export of position data from transponders
ExportSTDIP TCP client Export of position data and IO data from transponders
ExportSLMP TCP server Provision of position and battery status data from
transponders.
ExportEpaperAPI WAMP Transfer of themes to transponders with display and
feedback to an external client application
ExportAVT TCP server Provision of transponder and gateway data
The "Data Export Service" is configured via the "RTLS_LM_DataExport.ini" file. This is stored in
the "C:\Windows" directory by default. The configuration must be performed before starting
the "Data Export Service".
Start client
The "Data Export Service" (RTLS_LM_DataExportService.exe) is started automatically when the
PC is booted.

Overview

Installing the "Data Export Service" 4
Follow the steps below to install the "Data Export Service":
1. Start the installation by running the file "RTLS_LM Data Export Service Setup.exe".
2. Select the setup language and confirm with "OK".
3. Close all active applications and confirm with "Next" to continue the installation.
4. Accept the license agreements and confirm with "Next".
5. Use "Browse..." to navigate to the installation folder and confirm with "Next". By default, the
Locating Manager server and Clients installation folder is displayed.
6. Click "Yes" if you want to overwrite the existing folder.
7. Select the components to be installed and confirm with "Next".
8. Use the "Browse..." to select a folder in which the program shortcuts are to be created. The
"SIMATIC RTLS Locating Manager" folder is selected by default.
9. Check your configurations and confirm with "Install" or correct with "Back".
10.Click "Finish" to complete the installation.
Result: The "Data Export Service" was installed in the automatically created subfolder
"DataExport" in the installation directory of the Locating Manager, if you have selected the
default installation directory.
To now start the "Data Export Service", you need to select the check box before you click
"Finish" at the end of the installation.
Ensure that the UMC user used for the "Data Export Service" can log on to the Locating
Manager if you have entered a user. You can find additional information on creating a user in
the document (https://support.industry.siemens.com/cs/en/de/view/109798998).
Note
Before starting the "Data Export Service", you need to edit the "RTLS_LM_DataExport.ini"
configuration file, otherwise the service will not provide export modules. You can find more
information about configuration of the export modules in the respective sections.

Installing the "Data Export Service"

Configuration of the "Data Export Service" 5
5.1 General configurations
Before you start the "Data Export Service" manually, you need to configure it. You start the
configuration via the "RTLS_LM_DataExport.ini" configuration file, which is located by default
in the directory "C:\Windows". A double-click on the file opens it in the text editor. Save
entries made in this file before closing the editor so that they take effect. Any changes made
to the "RTLS_LM_DataExport.ini" configuration file are only applied after restarting the "Data
Export Service".
Note
When using the Windows text editor, make sure that you are logged into Windows with
administrator rights, otherwise there may be complications with assigning the file to the
service. To avoid this problem, use the Notepad++ editor, for example.
There is a section in the "RTLS_LM_DataExport.ini" configuration file for each export module.
These sections are created for the standard modules during installation These sections
contain the parameters required to configure the module. The name of the section defines
the type of the module. All modules have the "Active" parameter, which determines whether
the respective module is enabled.
Note
If a module is enabled or disabled via the "Network configuration" client, the "Active"
parameter is written.
In some cases, a module with different configurations is required. There is the possibility to
start export modules several times for this purpose.
1. Create an "["Exportmodul"]" section in the "RTLS_LM_DataExport.ini" configuration file and
give it a name that is different from any other section and contains "Modules".
2. Create a parameter named "ExportType" in this section.
3. Specify the name of the export module in this parameter.
Note
The names of the sections are the export modules listed in the "Overview (Page 13)" section.

Configuration of the "Data Export Service"
Note that these are completely separate modules that are only structurally located in the
same "Data Export Service". The following example shows two "ExportTCPIP" modules that
connect to different ports of different PCs.
[LocSystem]
Host=localhost
Port=9500
;ReconnectInterval=1000
;The user used can be overwritten. This user must be created with
the UserAdmin.
login=DataExport
pwd=DA2
[ExportTCPIP]
;sends timestamp, address and coordinates via a TCP connection. Make
the connection yourself. It is a line-based protocol.
;LineFeed
Active=1
;Configuration to where the export interface connects.
Host=localhost
Port=5004
[Module.TCPIP2]
ExportType=ExportTCPIP
Active=1
Host=remotehost_2
Port=5005
The different configurations are available depending on the export module.
Note
If an export module needs a resource, the export modules do not share it.
When an export module opens a socket at port 1234, no other export module or program on
that PC can open the port. The order in which the export modules are instantiated and
initialized is not defined.
When an export module is active and trying to connect to another system, the "Data Export
Service" is temporarily blocked during this time and the transfer of all data from the Locating
Manager server to the other export modules is briefly interrupted.

The "Data Export Service" can be run on a PC different than the Locating Manager. If the "Data
Export Service" is installed on another PC, a copy of the server's "LocNetBasicServer.ini"
configuration file must be located in the Windows folder of the "RTLS_LM_DataExport.ini"
configuration file of the "Data Export Service" to establish the data connection. You can
configure the Locating Manager host and port in the "[LocSystem]" section of the
configuration file for the "Data Export Service". For the host, you need to specify the name of
the PC or the IP address. For the port, you need to specify the corresponding TCP port. The
connection between the Locating Manager and the "Data Export Service" must not be blocked
by a firewall.
For authentication on the Locating Manager, the "Data Export Service" requires its own
credentials if the "Data Export Service" is operated on a different PC than the Locating
Manager. For this, you need to configure the "login" parameter and the "pwd" parameter in
the "[LocSystem]" section. If these parameters are not configured, the credentials of the "Data
Export Service" are only allowed on the PC where the Locating Manager is installed. If the
user is a domain, the domain must be specified as follows during login: "Domäne\Login".
You can enter the password in plain text or encrypted in the "RTLS_LM_DataExport.ini"
configuration file. Navigate to "Option > Encrypt password" in the menu bar to encrypt the
password. The option can be found in each client and the client does not need to be
connected to the server at this time. In the dialog box, enter the plain text password in the
"Password" text box and click the "Encrypt Password" button. The encrypted password
appears in the "Encrypted password" display field.
Note
The credentials for the default user "Administrator" are not created during installation. You
must therefore create a corresponding UMC user yourself. You can find instructions on how
to create UMC users in the Locating Manager installation manual.
Note
The "Observer" and "Manager" roles cannot be used to log onto the "Data Export Service". The
user must at least have the role "Applications".
For some export modules of the "Data Export Service", network addresses of transponders
must be output with a length of 6 bytes instead of 3.5 bytes. You can implement this using
the configuration of the technology prefix. The configuration changes the output of the 6-
byte network address of the devices in the export modules of the "Data Export Service" which
support these functions. The following parameters can be configured in the "[LocSystem]"
section for this purpose.
Parameter Range of values Description

UseOwnRadioAddress 0 ... 1 Activate/deactivate the parameter
"OverwriteTagRangingTechnologyPrefix".
Default value: 0
0: not active
1: active

5.2 Supported framing methods in the RTLS localization network

OverwriteTagRangingTechnologyPrefix [00..FF]:[00..FF]:[0...F]0:00:00:00 Technology prefix
[1 Byte]:[1 Byte]:[1/2 Byte] [00..FF]:[00..FF]:[0...F]0:00:00:00 [1
byte]:[1 byte]:[1/2 byte]
Modifies the first seven network
identification characters of the device
address in the messages when the
"UseOwnRadioAddress" parameter is active.
5.2 Supported framing methods in the RTLS localization network

By using framing (message packaging), you can separate messages from each other in the
data stream. The following table lists all supported framing methods:
Framing method Description

LineFeedFraming This framing method identifies a message by a line break (0x0a).
LineFeedFramingCR This framing method marks a message by a line break with line feed
(0x0d0a).
Framing7F8F This framing method supports the transfer of binary data. In this case, a
message is delimited by a start and end character.
BSCFraming This framing method supports the transfer of binary data.
LengthEncodingFraming This framing method is an optimized protocol for TCP connections. First
the length of the message is transmitted as a 4-byte number and then
the data is transmitted.
Example: 00:00:00:0b:48:65:6c:6c:6f:20:57:6f:72:6c:64 (hexadecimal)
corresponds to 48:65:6c:6c:6f:20:57:6f:72:6c:64 (hexadecimal)
corresponds to "Hello World" (ASCII)
"Framing7F8F" framing method

All received data that is not between the start and end character is ignored by the processing
module. When a protocol character occurs in the data stream, this character must be marked
by an ESC character or a mask for special characters in the data stream.
Characters Value
Start character 0x7F
End character 0x8F
ESC character 0x1B
Masking for special characters 0x20

5.3 Logging of internal events and data transfer
Example of a masked data packet:
Data (hexadecimal) 01 35 B2 8F 00 FF 01 1A 1B 1C 33
Masked data 7F 01 35 B2 1B AF 00 FF 01 1A 1B 3B 1C 33 8F
(hexadecimal)
Description SC Data Esc MC Data Esc MC Data EC
SC: Start character

Data: Unmasked data
Esc: ESC character
MC: Masked data
EC: End character
Logging of internal events

The "Data Export Service" logs connection establishment, disconnection and error messages
in internal logs. These logs can be read and displayed in the "Log Viewer" client.
Logging the data transfer

The transmission of all telegrams of all export modules can additionally be logged in files for
subsequent analyses. A file is created for each interface, which can be assigned via the file
name of the respective export module. You can configure the general logging parameters in
the "[protocol]" section of the "RTLS_LM_DataExport.ini" configuration file. You can close a
log file and start a new one. This option is referred to as "log rotation". The file name of the
log is composed of the name of the export module and the time when the file was opened.
The Locating Manager has no function to clean up these files. If logging is disabled because
there is limited memory on the hard disk, for example, it is not restarted. To restart logging,
you need to deactivate the export module and activate again.
You can configure the following parameters for logging data in the "[protocol]" section:
Parameter Description
ProtocolFile.dwMaxFileSize This parameter specifies the maximum file size in megabytes. The log rotates
when this value is reached.
The value "0" means that this parameter is inactive and a maximum limit does not
exist.
Default value: 100
ProtocolFile.dwMaxFileAge This parameter specifies the maximum age of the log files in seconds. The log
rotates when this value is reached.
The value "0" means that this parameter is inactive and a maximum age does not
exist.
Default value: 7200

ProtocolFile.dwMinFreeDiskSpace This parameter specifies the minimum space in megabytes on the drive. If the
value drops below this, logging is disabled.
The value "0" means that this parameter is inactive and a check for available
memory is not activated.
Default value: 500
ProtocolFile.sFilePath This parameter specifies the path to the log files. If no path is specified, the
"RTLS_LM_DataExportService.exe" folder is created and used in the folder where
the "logs" file is located.
Logging is disabled when the specified path does not exist.
You can then enable or disable logging using the following parameters in each export
module block. If you enable it, the data transfer of this export module will be exported to log
files.
ProtocolFile.boEnable This parameter specifies whether logging is active. The following values are
possible:
0: not active
1: active
Default value: 0
Structure of protocol messages

The protocol message consists of several elements. These are described in the following
table.
Elements of the protocol messages Description

Logging time The time is specified in UTC. Time resolution is 1 millisecond.
The smallest time possible is 01.01.1970, 00:00 UTC
The time is specified in the following format:
YYYY-MM-DDThh:mm:ss.SSSZ
Example: <2021-08-14T14:08:26.234Z>
Separator Separation of the message elements: < ### >
Protocol message direction Specifies the transmission direction for the protocol message to be sent/received
from whom to whom.
<Rx>: Protocol message is sent from host system to the Locating Manager
<Tx>: Protocol message is sent from Locating Manager to the host system
Connection identification Specifies the TCP socket for the protocol message.
<All>: Protocol messages are sent to all TCP sockets connected to the Data Export
Service module
<<IP:Port> Protocol messages are sent or received from or to the specified TCP
connection, depending on the direction of transmission
Example: <127.0.0.1:49786>
Export module specific data The export module specific protocol messages that were received or sent. The
structure is bound to the respective export module.
A protocol message is therefore always structured as follows:

<Logging time><Separator><Protocol message direction><Separator><>Connection
identification> <Separator><Export module specific data>.

5.4 "ExportDatabase" export module
5.4 "ExportDatabase" export module
Preferences for exporting to a database

To output the position data calculated by the Locating Manager to a database you have
defined, you need to specify the database type, the database user name and password, the
database server, and the database in the "ExportDataBase" section of the
"RTLS_LM_DataExport.ini" configuration file. In addition, you must set the value of the
"Active" parameter from "0" to "1" to enable the export via the database interface.
Exported data in the database

When the service is active and you start the Locating Manager, the "locsystrack" database
table is created if it is not present. An entry with all the important information is written to
this table for each transponder. This information is overwritten cyclically with more current
data. You can display the current positions of the transponders from this transfer database.
The following entries are available in the database table:
Entry Type Unique Description

tag_addr char[17] Yes Node (wireless) address in xx:xx:xx:xx:xx:xx:xxx format
tag_desc string No Description of the transponder
pos_x int No X position in cm
pos_y int No Y position in cm
pos_z int No Z position in cm
instime datetime No Time of the database entry
instime_ms int No Milliseconds of insertion time

5.5 "ExportTCPIP" export module
5.5 "ExportTCPIP" export module

The "Data Export Service" initiates the connection establishment for communication. The
connection is established when the "Data Export Service" starts or repeated cyclically until the
connection is established if the connection is interrupted. The "ExportTCPIP" export module
enables position data to be sent to other software systems via a simple TCP connection. The
individual data components of a data packet are sent, in tabular form and similar to a file with
"*.csv" format with semicolons separated into a single string. The string also ends with a
semicolon.
Configurations
The position data calculated by the Locating Manager are sent to the external recipient,
which you have defined in the "RTLS_LM_DataExport.ini" configuration file in the section
"ExportTCPIP" with the parameters "Host" and "Port". In addition, you must set the value of the
"Active" parameter from "0" to "1" to activate the data export via the socket connection. The
"FixedLineLength" parameter is important if you want an output of the distance data in the
same character length. If the value "0" is set, the output of e.g. 8 and 12 meters is different in
length. If you set the value to "1", +0008.00 or +0012.00 would be output (eight characters
each with leading zeros).
Output data
The "ExportTCP" export module data packet consists of the following eight fields. The output
format is specified in the respective description field:
Fiel Name Description

d
1 Date Date in the format yyyymmdd (local time)
2 Time Time in hhmmss format
3 Milliseconds Milliseconds in the value range 0 ... 999
4 Transponder address String with the Locating Manager address of the transponder in
the format xx:xx:xx:xx:xx:xx
5 X coordinate x coordinate in meters and centimeters with two decimal places
The leading zeros are not displayed
The decimal separator is a dot "."
6 Y coordinate Y coordinate, format like x coordinate
7 Z coordinate Z coordinate, format like x coordinate
8 Line break 0x0A, dataset end delimiter
Example string: "20190712;150257;27;3c:4b:89:12:77:6f;83.67;10.67;2.50;\n"

5.6 "ExportSTDIP" export module

The "ExportSTDIP" export module can be flexibly adapted and can also transfer IO data of the
transponders, i.e. read out inputs and set outputs.
Configuration
The position data calculated by the Locating Manager are sent to the external recipient,
which you have defined in the "RTLS_LM_DataExport.ini" configuration file in the section
"ExportSTDIP" with the parameters "Host" and "Port". In addition, you must set the value of
the "Active" parameter from "0" to "1" to activate the export via the socket connection.
Output data
The data packet of the "ExportSTDIP" export module consists of the fields described in the
table below. Different telegram types (command) are used in field 2, each of which triggers a
different output. The telegram types are described in the following.
The data packet is structured as follows:
Field Name Description

1 Time stamp Time stamp in the format yyyy-mm-ddThh:mm:ss.ms
The milliseconds are specified in the value range 0 ... 999.
Example:
2019-10-28T12:43:59.449;1;00:00:00:01:00:01;5.36;0.53;1.20
2 Telegram Defines the content of the following data
(command)
Data Data dependent on telegram type
Line break 0x0A, dataset end delimiter
The date and time indicate the time of the message transmission and are sent in local time.
The "Time stamp" parameter is only included in telegrams transmitted from the export
module to the other party. For commands in the opposite direction, do not use this
parameter and remove it from the telegram.
The following telegram types are supported in field 2:
Field Name Type Description Source

0 Protocol version Comm Acknowledgment of the protocol Customer1),
and version RTLS
1 Localization message Data Transmission of the position RTLS
10 Activate IO transmission Comm Activates the transmission of Customer, RTLS
and the IO data
11 Input data Data Status of the inputs of the RTLS
transponder
12 Switch outputs Comm Command for switching the outputs Customer, RTLS
and

Field Name Type Description Source

13 Outputs successfully Data Success message that RTLS
switched the outputs have been switched
100 Error message Data An error occurred executing a RTLS
command.
1) Customer software that communicates with the RTLS
All telegrams are described below and each end with a line break.
Telegram type 0 (command: Protocol version)

Telegram type 0 ensures that the same version of the interface is used at both ends of the
connection.
The RTLS does not send data over this TCP connection and does not accept commands until
the other party has sent the protocol version message. The current version of the protocol
is 1.

3 Protocol version Current version of the protocol
The telegram is sent by the RTLS as confirmation of the request by a telegram 0. A message
with telegram 0 and current protocol version is sent.
Telegram type 1 (data: Localization message)

Telegram type 1 transmits, usually cyclically, the position data of the transponder in the
fields:

3 Transponder address String with the address of the RTLS transponder in the format
xx:xx:xx:xx:xx:xx
4 X coordinate x coordinate in meters and centimeters with two decimal places. The
decimal separator is a dot "."
Negative coordinates are transmitted with minus,
for example -13.34
5 Y coordinate Y coordinate
6 Z coordinate Z coordinate
Telegram type 10 (command: Activate IO transmission)

The transmitted command activates the transmission of IO data. This telegram must be sent
once to enable telegram type 11. If errors occur when processing the command, a type 100
command is transmitted.

3 Active Specifies whether or not the IO data are to be sent.
• 1: sending
• 0: Do not send

If the IO data are to be sent, telegram 11 is transmitted for all transponders with valid IO
data. The telegram is sent by the Locating Manager as confirmation of the request by
telegram 10. A message is sent with telegram 10 without attached data.
Telegram type 11 (data: Input data)

This telegram type sends a status message (IO data) about the change of a digital or virtual
input at the transponder. This data packet is sent asynchronously, that is, whenever an event
occurs.
The digital inputs can indicate, for example, the opening or closing of a bus door, the fill level
of the sanding machine, the tire pressure or other electrically connected sensors.
The virtual inputs pass on already processed data from sensors, e.g. the result of the
evaluation of the acceleration sensor of the transponder.

xx:xx:xx:xx:xx:xx
4 Inputs Status of the input pins as decimal number
5 Virtual inputs State of the virtual input pins
The telegram is sent by the RTLS:

• If the status in the transponder changes
• When the transmission is enabled by a telegram 10
The availability of the inputs and virtual inputs fields varies depending on the design and
software version of the devices. Information on this can be found in the respective operating
instructions.
Telegram type 12 (command: Switch outputs)

The data transmitted by this telegram type can be defined for each specific customer and
depends on the technical system that generates the outputs. For example, the connection of
the heating control of a tram to enable the automatic startup of the tram heating.

xx:xx:xx:xx:xx:xx
4 Output number Output to be switched:
• 1: Switch output 1
• 2: Switch output 2
5 Target value • 0: Switch output to Low (no voltage)
• 1: Switch output to High (voltage)
6 Referrer Reference for responses.
Any integer in the value range
-2147483648 ... 2147483647
When the telegram is received, the Locating Manager attempts to transmit the message for
switching the output to the corresponding transponder.

Either a "Telegram 13: Outputs successfully switched" or a "Telegram 100: Error message" is
sent with each telegram of this type. The responses to the command can be assigned via the
referrer.
If errors occur when processing the command, a type 100 command is transmitted.
Telegram type 13 (data: Outputs successfully switched)

Acknowledgment of receipt, processing and execution of the command from telegram type
12.

3 Referrer Reference to which command was successfully set.
The telegram is sent by the Locating Manager when telegram 12 has been confirmed by the
transponder.
Telegram type 100 (error message)

This telegram type represents the error message, i.e. it informs that a command could not be
executed.
The structure of this message varies. Depending on whether there is a reference telegram ID
and a referrer is available when the error occurs, the fields in the message may be missing at
the corresponding position.

3 Error ID An error occurred (see table below)
4 Reference telegram ID An error occurred with a command.
5 Referrer Reference of the command, if available
Table 5- 1 Table of error codes
Error ID Name Description

0 ProtocolVersionUnknown The other party1) of the interface has not sent a protocol version message
and may not yet transmit any commands.
1 CommandIDUnknown The other party has transmitted an unknown command ID.
2 CommandNotSupported The feature is not supported by the transponder. The command itself is
supported by the interface.
3 CommandLength The number of parameters for the telegram ID is wrong. If the message
does not contain a telegram ID, the error message is transmitted without
a reference telegram ID.
4 CommandParsingFailed The recognition of a parameter of the command failed.
5 ParamOutOfRange A parameter of the command is outside the value range or a command
for an unknown transponder has been transmitted.
6 InternalError An unexpected error occurred and was logged in the internal log of the
Locating Manager.
7 CommandExecutingFailed The execution of the command failed. The error was logged in the
internal log of the Locating Manager.
1) Designates the application to which the interface has connected.

5.7 Export module "ExportSLMP: ISO/IEC 24730-1:2014"

The "ExportSLMP" export module sends data according to ISO/IEC 24730-1:2014. The "Data
Export Service" connects to the Locating Manager via TCP/IP, where the Locating Manager
responds with a large number of telegrams that do not end until the connection to the "Data
Export Service" is closed. If no telegrams are sent over a long period of time, the Locating
Manager sends "Keep-Alive" telegrams to signal the "Data Export Service" that the connection
is continuing. The corresponding cycle is controlled by the "RTLS_LM_DataExport.ini"
configuration file of the "Data Export Service". If the connection is interrupted, the "Data
Export Service" must periodically initiate the reestablishment of the connection.
5.7.1 SLMP via socket (TCP/IP)

The service supports SLMP telegrams (Simple Location Message Protocol), which are
structured according to the ISO/IEC 24730-1:2014 standard and transmitted via TCP/IP. As
described in the "General configurations (Page 17)" section, this functionality must be
enabled in the "RTLS_LM_DataExport.ini" configuration file of the "Data Export Service".
You can configure the following parameters in the "RTLS_LM_DataExport.ini" configuration
file regarding this module in the "ExportSLMP" section:

Active 0 This parameter specifies whether the "ExportSLMP" export
module is active.
The following values are possible:
0: not active
1: active
Port - This parameter specifies the TCP port that is opened and must
be configured.
KeepAliveMsgActive 0 Enables or disables the generation of the "Keep-Alive"
telegrams of the Locating Manager.
0: not active
1: active
KeepAliveMsgTime 60 The Locating Manager generates a "Keep-Alive" telegram after
the configured time has expired and when no other
telegrams have been sent by the Locating Manager during
this time via the interface and the parameter
"KeepAliveMsgActiveKeepAliveMsgActive" is configured to the
value "1". The configured time is specified in seconds.
5: minimum value
3600: maximum value
WelcomeField SIMATIC RTLS LM The parameter is used to modify the welcome message while
connecting.
A text length of 256 characters is permitted.
Appliance_ID LM01 The parameter value is integrated into the telegrams as
identifier of the RTLS system so that it is possible to
determine with two or more Locating Manager system
instances which system has sent the telegram. A text length
of 10 characters is permitted.

The telegram specification is made by the Locating Manager in accordance with the ISO/IEC
24720-1:2014 standard and can be found there.
Connection setup, data and telegram definition

Examples for the "Welcome", "Field Definitions" and the "Telegram Definition" telegrams
transmitted during connection setup are provided below. <CR><LF> is used as telegram end
delimiter.
Welcome message, version (1.0), interface, text:
LM01,SLMF,1.0,0.0,Welcome<CR><LF>
The following field definitions are sent:

FieldDefinition,Source,String<CR><LF>
FieldDefinition,Format,String<CR><LF>
FieldDefinition,Tag_ID_Format,HexBinary<CR><LF>
FieldDefinition,Tag_ID,HexBinary<CR><LF>
FieldDefinition,X,Double<CR><LF>
FieldDefinition,Y,Double<CR><LF>
FieldDefinition,Z,Double<CR><LF>
FieldDefinition,Battery,HexBinary<CR><LF>
FieldDefinition,Timestamp,DateTime<CR><LF>
The telegram definition is structured as follows:

LocateMessageDefinition,SIMATIC_RTLS_LM,DFT,Tag_ID_Format,Tag_ID,X,Y
,Z,Battery,Timestamp<CR><LF>
Telegram for keep alive

If the "KeepAliveMsgTime" configuration parameter is set to the value "30", the keepalive
telegram is structured as follows:
KeepAlive,30<CR><LF>
Telegram for position transmission

Similar to telegram definition
LocateMessageDefinition,SIMATIC_RTLS_LM,DFT,Tag_ID_Format,Tag_ID,X,Y
,Z,Battery,Timestamp<CR><LF>
the following telegram results as position transmission:
SIMATIC_RTLS_LM,DFT,17850000193f,-31.38,8.94,2.80,3,2016-09-
13T11:38:23+02:00<CR><LF>
This telegram is sent by the Locating Manager server when the transponder has a relevant
position change. A relevant position change is when the locating calculation signals a change
of the position, when a transponder sends a position for the first time. The telegram is not
sent when a connection is established or when a position becomes invalid.

5.8 "ExportAVT" export module

The "ExportAVT" export module (Automotive Vehicle Tracking) is a functionality of the "Data
Export Service". In addition, external parties (customer-specific management software) obtain
access to localization and status information of the transponders and infrastructure devices
during operation of the Locating Manager. It is possible to connect multiple parties at the
same time through the export module.
The "ExportAVT" export module sends a proprietary plain text protocol. The data is transferred
via the "TCP/IP" transport layer. In this case, the "Data Export Service" is the TCP server. You
can configure the port used for this and you may only use it once in the entire RTLS locating
system. If the connection between the "Data Export Service" and the Locating Manager server
is terminated, the port is closed and the existing connection to the other party is
disconnected.
In the "RTLS_LM_DataExport.ini" configuration file you can determine which data is
transmitted and whether this data is transmitted initially during the connection setup. The
transmitted messages contain fields with a time stamp. The Locating Manager server does
not ensure that the time stamps in the sent messages increase monotonically.
The "ExportAVT" export module is backward compatible. If you have installed another party
with version 1.2 and upgrade the "ExportAVT" export module to a version higher 1.2, the
other party will continue to behave like version 1.2. If messages requiring a higher version
are selected in the configuration file, the other party with the outdated version is rejected.
If the port is open, the "ExportAVT" export module can connect to the other party. A protocol
handshake is performed before the data is sent to detect error configurations. Next, the initial
data is sent. After that, data is only transmitted when there are changes in a transponder or
infrastructure device.
Behavior with commands (from "ExportAVT" V1.2)

Version 1.2 of the "ExportAVT" export module introduced commands that can be sent from
the other party to control devices in the Locating Manager. Each of these commands is either
acknowledged or answered with an error message. It may take some time to execute the
commands depending on the device accessibility. If a device enters the "Heartbeat timeout"
state while a command is being executed, the command is aborted with an error message.
For commands to devices, the device is identified or specified with the "NodeIdent"
parameter. The data type of this parameter corresponds to the interface configuration with
regard to the identification feature with the "NodeIdent" parameter of the same name.
Note
If the "Name" parameter was selected as identification feature, it is possible that this
parameter may not be unique in the project. If a command for a device is requested via the
"Name" parameter, an attempt is made to execute the command for the first available device
of the corresponding type with this name. It is not defined which device this is if several
devices use the same name.
For commands, "String" type parameters may not contain the separator character, which is
also used for separating parameters. This concerns, for example, the "NodeIdent" parameter
in the "Name" selection and the "Referrer" parameter. Responses can be assigned to the
command via the combination of the "Telegram ID", "NodeIdent" and "Referrer" parameters. If

another party sends such a command to the Locating Manager, but disconnects and
reestablishes the connection before the response message, it will not receive a response
message for this request. The request will still be executed. If multiple parties send such
commands, the commands will be executed according to the order in which they arrive on
the Locating Manager.
Note
Device specific commands are not supported by all devices. You can learn which devices
support specific functions in the operating instructions of the device.
Behavior depending on the version of the other party for all incoming commands
Occurrence As of version Reaction

Number of parameters less than 3 All Connection abort with log entry
First command is not V1 All Connection abort with log entry
Invalid command 1.0, 1.1 Connection abort with log entry
Invalid command 1.2 ERROR1 message with error ID 1
Number of parameters invalid 1.0, 1.1 Connection abort with log entry
Number of parameters invalid 1.2 ERROR1 message with error ID 2
5.8.1 Configuration of the "ExportAVT" export module

In the "RTLS_LM_DataExport.ini" configuration file, you can configure the "[ExportAVT]"
export module in the section "ExportAVT". If you do not configure a parameter, the default
value is used for this parameter. When you make changes, you must restart the "ExportAVT"
export module or the "Data Export Service".
It is possible to create different configurations for several individual connections. To do this,
you need to start the export modules several times as described in the "General
configurations (Page 17)" section.
If a configuration error occurs, the "ExportAVT" export module changes to the "Initialization
failed" state. A log entry is created and the services of the "ExportAVT" export module are not
made available. The error message is logged in the Locating Manager system log.
You can configure the following parameters in the "RTLS_LM_DataExport.ini" configuration
file:
Parameter Default value Description

Active 0 This parameter specifies whether the "ExportAVT" export
module is active. The following values are possible:
0 Not active
1 Active
Port 800 This parameter specifies the TCP port that is opened and
must be configured.


RemoteFraming LineFeedFraming This parameter detects the end of a message. The following
framing types are possible:
LineFeedFraming (0x0A)
LineFeedFramingCR (0x0D0A)
Framing7f8f
BSCFraming
LengthEncodingFraming
SendInitialData 1 This parameter transmits the initial data during connection
setup. The following values are possible:
0 Do not send
1 Send
PosDataMsg - This parameter specifies which position message is to be
transmitted. The following value is possible:
P1
StateDataMsg - This parameter specifies which status message is to be
S1
NodeDataMsg - This parameter specifies which device message is to be
N1
HBDataMsg - This parameter specifies which heartbeat messages are to
be transmitted. The following value is possible:
H1
NodeIdent NetworkAddress This parameter specifies which identification feature is to be
transferred. The following values are possible:
Name
NetworkAddress
NodeKeyHex
NodeKey
PositionFormate xyz This parameter specifies which coordinate type is to be
used. The following values are possible:
xyz
LatLon
The "[Orientation]" section in the configuration file
"RTLS_LM_DataExport.ini" is required for the "LatLon" value.
OldPosDataMsg - This parameter specifies whether the last known position is
transmitted during connection setup. This parameter is only
active when the "SendInitialData" parameter is active and
the "PosDataMsg" parameter has the value "P1".
The following value is possible:
OP1
LED_InfoMsg - This parameter specifies which messages are to be
transmitted for the status of the LEDs. The following value is
possible:
LED_Info1
ButtonStateMsg - This parameter specifies which messages are to be
transmitted for the status of the function buttons. The
following value is possible:
BtnStates1


BatteryStateMsg - This parameter specifies which messages are to be
transmitted for battery states. The following value is
possible:
BattState1
KeepAliveMsg - This parameter specifies which heartbeat messages are to
be transmitted. The following value is possible:
KeepAlive1
KeepAliveMsgTime 60 This parameter specifies the time interval in which a
heartbeat telegram is to be transmitted.
This value must be greater than 0 if heartbeat messages are
to be transmitted. The value is specified in seconds.
If the "KeepAliveMsg" parameter is set to the "KeepAlive1"
value, the "KeepAliveMsgTime" parameter must be set to a
value greater than 0, otherwise the export module will close
again.
TagGroupFilter - This parameter specifies the transponder groups in which
transponders may be located so that messages are
transmitted for them.
The value is a comma-separated list of transponder group
numbers. If the parameter is not specified, the filter is
inactive and data for all transponders are transmitted.
Example: 1,2,7
SendInfrastructure 1 This parameter specifies whether data for infrastructure
Data devices should be transmitted.
If the parameter is not specified, the filter is inactive and the
data for all infrastructure devices will be transmitted. The
following values are possible:
0 Do not transfer data
1 Transfer data
Device filter
In the configuration file, you can define special filters so that the data for fewer devices
should be transmitted. If a device is filtered out by this filter, in the export module it is treated
as if it were not present. In this case, no information is transferred for the device and the
corresponding error message is transferred for commands.

5.8.2 "[Orientation]" section of the configuration file

The "[Orientation]" section in the "RTLS_LM_DataExport.ini" configuration file is used by
various export modules. In this section, you can specify information how the x, y and z
coordinates are converted to "Latitude" and "Longitude".
The Cartesian and the GPS coordinate system are supported for the "ExportAVT" export
module. The Cartesian coordinate system is used by default. The parameters are defined in x,
y and z coordinates. The "[Orientation]" section is only used if the position data is to be sent
as "Latitude" and "Longitude".
The localized position of a transponder is specified in Cartesian x, y and z coordinates relative
to a point, e.g. the coordinate origin. The coordinate values can be positive or negative. You
can configure the position of the coordinate origin and the alignment of the axes. A right-
hand coordinate system with positive direction of rotation is used. The z axis points upwards
by default. The values are specified in meters with two decimal places.
When you select the output "LatLonLatLon", the positions are specified in longitude, latitude
and altitude according to WGS84. If you have specified the "X position", "Y position" and "Z
position" parameters for the telegram types, the values of the coordinates mean the
following:
Fiel Parameter Data type Contents

d
- X position Double Latitude (in decimal degrees)
Example: 50.857745
+1 Y position Double Longitude (in decimal degrees)
Example: 12.929436
+2 Z position Double Height (in meters)
Example: 350.47
If you use GPS coordinates, the values must be converted. To do this, you need to give the
"PositionFormate" parameter the "LatLon" value and configure the reference points in the
"[Orientation]" section. For each reference point, you must specify a coordinate as
Locating Manager coordinate and its corresponding GPS coordinate. You must specify the
North direction. The closest conversion point is always used for the conversion. Specifying
the height is optional. If you do not specify a height, the value "0" is used. The name of the
reference point is part of the parameter name.

RefPointNames - This parameter specifies the names of the reference points.
The separator is the colon.
Example for the reference point "RTLSHQ":

RefPointNames = RTLSHQ
;The direction of north in x, y and z coordinates (in cm)
RTLSHQ.North.X = 3
RTLSHQ.North.Y = 100
;A coordinate of the area in x, y and z coordinates (in cm)
RTLSHQ.LocRef.X = -434
RTLSHQ.LocRef.Y = 1564
RTLSHQ.LocRef.Z = 0

;The corresponding GPS coordinates (in degrees)

RTLSHQ.Latitude = 50.857745
RTLSHQ.Longitude = 12.929436
RTLSHQ.HeightCM = 35000
5.8.3 Output data of the "ExportAVT" export module

The data is transmitted as plain text in "UTF8" format. The fields of the individual messages
are separated by a semicolon. Transfer of empty fields is valid. In this case, only the
semicolons are sent. The "ExportAVT" export module consists of the fields described in the
table below. The telegram types are described in sequence.
If a datum in a message is unknown or invalid, it is not sent and only the semicolons are sent.
You can choose from the following data types:
Data type Description

DateTime This data type specifies the time in UTC. Time resolution is 1 millisecond.
The smallest time possible is 01.01.1970, 00:00 UTC
The time is specified in the following format: YYYY-MM-DDThh:mm:ss.SSSZ
Example: 2020-02-14T19:08:26.234Z
Double This data type only includes rational numbers. The decimal sign is a point. It is optional
for whole numbers.
Example: 2345.334, -98.7, 1.0, 4, 0.0, 0.5
HexBinary This data type must have an even number of ASCII characters (2, 4, 6, etc.). The colon
is used as separator.
Example: 17:85:01:00:16:b9 corresponds to 0x17 0x85 0x01 0x00 0x16 0xB9
Integer This data type is a whole number that must be within the value range "-
2147483648 ... 2147483647".
32 Bit signed integer
String All printable characters are permissible for this data type, except for the semicolon
because it is already being used as a separator.
If a semicolon is included, this character is removed from the string. The end of the
message is a line break "0xD 0xA".
NodeIdent This data type describes the identifier of the device. You can configure which
information is used for this.
The messages are structured as follows:

<Telegram ID>;<time stamp>;<NodeIdent>;telegram-specific values
Parameter Data type Description

Telegram ID String This parameter indicates the ID of the telegram.
Time stamp DateTime This parameter specifies the time when the telegram was
sent.
For messages from an external software to the
Locating Manager server, a time stamp is optional.

The following telegram types are supported:
Telegram ID Name As of version* Locating Remote --> Description

ExportAVT / Manager --> Locating
Locating Remote Manager
Manager
V1 Version 1.0 / 2.6.1 x x Information about
information the expected or
confirmed
interface version
I1 Initial transmission 1.0 / 2.6.1 x Acknowledgment
completed of transmission of
initial data
P1 Basic position data 1.0 / 2.6.1 x Current position of
the transponder
S1 Device status 1.0 / 2.6.1 x Current state of a
transponder or
infrastructure
device.
H1 HeartBeat 1.0 / 2.6.1 x Information when
a device has sent a
heartbeat.
N1 Device data 1.0 / 2.6.1 x Information on the
device data
OP1 OldPosition 1.1 / 2.8 x Last known
position of a
transponder
CMD_Ack1 Acknowledgment 1.2 / 2.12 x A command was
of a command received and
processed.
Error1 Error message 1.2 / 2.12 x Errors occurred
during the
processing of a
command from
the other party.
SetOutputs1 Switch outputs 1.2 / 2.12 x Switches the state
of the outputs of
transponders.
Acknowledgment
via telegram ID
"CMD_Ack1". Error
via telegram ID
"Error1".
LED_Blink1 Start of a flash 1.2 / 2.12 x Starts the flashing
pattern of the LED of a
device with
configurable flash
pattern and flash
duration.
Acknowledgment
via telegram ID
"CMD_Ack1". Error
via telegram ID
"Error1".

Telegram ID Name As of version* Locating Remote --> Description

ExportAVT / Manager --> Locating
Locating Remote Manager
Manager
LED_Off1 Flash pattern stop 1.2 / 2.12 x Stops the flashing
of the LED of a
device.
Acknowledgment
via telegram ID
"CMD_Ack1". Error
via telegram ID
"Error1".
LED_Info1 Status of the LED 1.2 / 2.12 x Information about
the current flash
pattern of the LED
of this device.
BtnStates1 Status of the 1.2 / 2.12 x Transmits status of
button the function
buttons of this
transponder
BattState1 Battery status 1.2 / 2.12 x Battery status of
the device
KeepAlive1 Keep Alive 1.2 / 2.12 x Cyclically
transmitted
heartbeat
telegram
SetAMAState1 Switching of the 1.2 / 2.12 x Switching the AMA
AMA mode mode of a
transponder. Error
via telegram ID
"Error1".
* All telegrams supported by an older version of ExportAVT are also supported in newer ExportAVT versions.

5.8.4 Parameter "NodeIdent"

Depending on the project, the devices are identified differently. You can use the "ExportAVT"
export module to configure the identification feature to be transferred for device-specific
messages. The configuration is described in the section "Configuration of the "ExportAVT"
export module (Page 32)".
Parameter Data type Description

Name String This parameter specifies the name of the device that is
stored in the Locating Manager. Automatically generated
names have the format "Tff98" for transponders and
"G19ae" for gateways.
It is possible for multiple devices to have the same name.
NetworkAddress HexBinary This parameter specifies the network address that is defined
in a numerical sequence of 6 bytes. It is a unique numerical
sequence that identifies the device.
Example: 17:85:00:00:ff:98
NodeKeyHex HexBinary This parameter specifies an internal identifier of the
Locating Manager that is formed from the network address.
The identifier is 4 bytes long.
Example: 00:00:ff:98 corresponds to 17:85:00:00:ff:98
NodeKey Integer This parameter specifies an internal identifier of the
Locating Manager that is formed from the network address.
The number is always greater than 0.
Example: 65432 corresponds to 17:85:00:00:ff:98
Note
If the content of the "NodeIdent" parameter changes for a device, no new message is sent,
but the corresponding telegram type.

5.8.5 Telegram types of the "ExportAVT" export module
Telegram type V1: Version information

This telegram type is sent by the "ExportAVT" export module when it receives a version
message from an external party (customer-specific management software). When the
"ExportAVT" export module has sent the telegram, the "Data Export Service" starts the data
transfer. If the received version is not supported, the connection is terminated.
This telegram is always the first telegram that must be sent. It must not be sent again. If
several external software programs connect to the "ExportAVT" export module, all external
software must send this telegram.
Field Parameter Data type Description

1 Telegram ID String This parameter indicates the ID of the telegram.
Example: V1
2 Time stamp DateTime This parameter specifies the time when the telegram was
sent.
3 version String This parameter indicates the version of the protocol.
In this example, the protocol specification is for version "1.2":

Telegram from the external software:
V1;2020-04-01T10:58:02.147Z;1.2
Telegram from the Locating Manager server:
V1;2020-04-01T10:58:02.155Z;1.2
Telegram type I1: Initial transmission completed

This telegram type is sent by the "ExportAVT" export module after the initial data is
transmitted following the protocol handshake. If you disable the transmission of the initial
data in the "RTLS_LM_DataExport.ini" configuration file, this telegram is not sent. When a
change occurs, the data is transmitted following the protocol handshake.

Example: I1
2 Time stamp DateTime This parameter describes the time when the telegram was
sent.
Example:
I1;2020-04-01T10:58:02.155Z

Telegram type P1: Basic position data

The telegram is sent by the "ExportAVT" export module during the connection setup if this
was configured. This telegram is also sent when the transponder has a relevant position
change. A relevant position change is when the locating calculation signals a change of the
position, when a transponder sends a position for the first time or when a position becomes
invalid.

Example: P1
sent.
3 NodeIdent HexBinary, This parameter specifies the identifier of the transponder.
String or
Integer
4 X position Double X coordinate in meters
5 Y position Double Y coordinate in meters
6 Z position Double Z coordinate in meters
7 Time stamp DateTime This parameter specifies the time at which the
Locating Manager server receives the sensor data that have
resulted in the position.
In this example, the update of the transponder coordinates is transmitted.

P1;2020-04-01T10:34:56.655Z;17:85:00:00:ff:98;31.01;-8.54;4.72;2019-
06-01T10:34:56.255Z
In this example, the transponder coordinate is invalid.
P1;2020-04-01T10:34:56.655Z;17:85:00:00:ff:98;;;;2020-04-
01T10:34:56.015Z

Telegram type S1: Device status

The telegram is sent by the "ExportAVT" export module during the connection setup if you
have configured this. This telegram is sent when the status of a transponder or infrastructure
device changes. Depending on the device, the "Digital inputs", "Virtual inputs", "Digital
outputs", "Voltage" or "Battery level" parameter values are not always sent.

Example: S1
sent.
String or
Integer
4 Digital inputs Integer This parameter specifies the status of the digital inputs
1 to 8.
Bit field
5 Virtual inputs Integer This parameter specifies the status of the virtual inputs
1 to 8.
Bit field
6 Digital outputs Integer This parameter specifies the status of the digital outputs
1 to 8.
Bit field
7 Voltage Double This parameter specifies the voltage in volts.
8 Battery level Integer This parameter specifies the battery level as a percentage.
9 Heartbeat Integer This parameter specifies the heartbeat of the device. The
0 Heartbeat timeout
1 Heartbeat present
Examples:
S1;2019-06-01T10:32:01.113Z;17:c5:00:00:19:ae;0;0;;11.700;;0
S1;2020-04-01T10:45:50.783Z;17:85:00:00:ff:98;3;8;2;;45;1

Telegram type H1: Heartbeat

The telegram is sent by the "ExportAVT" export module with every heartbeat of a device sent,
if you have configured this. This telegram is not sent with the initial data.

Example: H1
sent.
String or
Integer
Example:
H1;2020-04-01T10:32:01.115Z;17:c5:00:00:19:ae
Telegram type N1: Device data

The telegram is sent by the "ExportAVT" export module during the connection setup if you
have configured this. This telegram is sent when the data of a device change.

Example: N1
2 Time stamp DateTime This parameter specifies the time when the telegram
was sent.
3 NodeIdent HexBinary, This parameter specifies the identifier of the
String or transponder.
Integer
4 Network address HexBinary This parameter specifies the network address of the
device.
Example: 17:85:01:00:ff:98
5 NodeKey Integer This parameter specifies the identifier within the
Locating Manager.
6 Name String This parameter specifies the name of the device.
7 IP address String This parameter specifies the IPv4 address with port
number via which the device was last connected to
the Locating Manager server. This field is empty for
devices without IP connection.
Example: 192.168.2.3:1010
8 Serial number String This parameter specifies the serial number of the
device.
Example: A01085
9 Device Type String This parameter specifies the type of the device. The
TAG Mobile device, transponder
Anchor Infrastructure device
Gateway Infrastructure device


10 X position Double X coordinate in meters for infrastructure device
This field is empty for transponders.
11 Y position Double Y coordinate in meters for infrastructure device
12 Z position Double Z coordinate in meters for infrastructure device
13 Group String This parameter specifies the group name of the
device.
14 Error memory entries Integer This parameter specifies the number of error memory
entries.
15 Text1 String This parameter is the description text 1 for
transponders. This field is empty for infrastructure
devices.
devices.
devices.
devices.
devices.
Examples:
Telegram from the Locating Manager server (device data of a gateway):
N1;2020-04-
01T10:45:50.783Z;17:c5:00:00:19:ae;17:c5:00:00:19:ae;6574;
G01.27;10.1.2.3:1010;A01085;Gateway;3.03;2.50;3.00;GateGroup3;0;;;;;
Telegram from the Locating Manager server (device data of a transponder)
N1;2020-04-
01T10:45:50.783Z;17:85:00:00:ff:98;17:85:00:00:ff:98;65432;
Tff98;;B65432;TAG;;;;Default;4;Text1;Text2;Text3;Text4;Text5

Telegram type OP1: Position message

This telegram is sent by the "ExportAVT" export module for each transponder during the
connection establishment, if you have configured this.
This message is sent for all transponders that currently have no position. In order for this
position data to be transmitted, the "ExportDatabase" export module must be enabled and
have the same configuration as the server database connection.

Example: OP1
sent.
String or
Integer
4 X position Double X coordinate in meters
5 Y position Double Y coordinate in meters
6 Z position Double Z coordinate in meters
7 Time stamp DateTime This parameter specifies the time at which the
Locating Manager server receives the sensor data that have
resulted in the position.
Example:
OP1;2020-04-01T10:34:56.655Z;17:85:00:00:ff:98;31.01;-
8.54;4.72;2020-04-01T10:34:56.255Z
Telegram type CMD_Ack1: Acknowledgment of a command

This telegram is sent by the "ExportAVT" export module after successful execution of the
command from the "Reference telegram ID" parameter. The exact condition is described in
the respective command. The responses to the command can be assigned via the
combination of the parameters "Reference telegram ID", "NodeIdent" and "Referrer".

The value is always "CMD_Ack1".
sent.
3 Reference String This parameter indicates which command is acknowledged.
telegram ID
String or
Integer
5 Referrer String This parameter specifies the reference of the command.
Example
The "SetOutputs1" command for setting output 1 to the value 0 of the "17:85:00:00:ff:98"
device with the "Referrer" value "MyRef42" is sent and successfully processed:

SetOutputs1;2021-05-17T10:54:58.776Z;17:85:00:00:ff:98;MyRef42;1;0
CMD_Ack1;2021-05-
17T10:54:58.776Z;SetOutputs1;17:85:00:00:ff:98;MyRef42
Telegram Error1: Error message

The telegram is sent by the "ExportAVT" export module if errors occurred during processing of
a command from the other party. The first detected error is returned. The responses to the
command can be assigned via the combination of the parameters "Reference telegram ID",
"NodeIdent" and "Referrer".

The value is always "Error1".
sent.
3 Error ID Integer This parameter specifies which error has occurred, see the
following table "Error codes".
4 Reference String This parameter indicates which command is acknowledged.
telegram ID
String or
Integer
6 Referrer String This parameter specifies the reference of the command.
7 Additional data (variable) Depending on the error ID, this parameter is used differently
to transfer additional information about the error, see the
following table "Error codes".
Table of error codes:

0 Version missing The other party of the export module has not sent
any version information and may not transmit any
commands yet.
1 Unknown command The other party has transmitted an unknown
command ID. This error code is also sent if a
telegram is transmitted in the wrong direction.
Special situation: Telegram V1: With this
command, the previous behavior from the older
versions of the export module is retained and the
connection is disconnected.
In this error scenario, the other fields are not
filled.
2 Wrong number of parameters Too many or too few parameters were specified
for the command.
In this error scenario, the other fields are not
filled.
3 Out of range One or more parameters are out of the value
range or invalid. In the "Additional data"
parameter, the numbers of the affected
parameters are listed separated by commas.


21 Unknown device A command for an unknown device was
transmitted. This also happens if a transponder-
specific command for a gateway was transmitted.
Or, if transponder groups are specified in the
transponder group filter, a command was
transmitted for a transponder that is not in the
transponder group filter.
Or, if the infrastructure data filter is being used, a
command (LED_Blink1, LED_Off1) was
transmitted for an infrastructure device.
22 Device not reachable The command could not be sent to the device
because it is unreachable.
23 Feature not supported The feature is not supported by the device.
However, the command is supported by the
export module.
25 Busy The command cannot be executed because the
device is busy at the moment. The command will
not be executed again automatically, but must be
sent again via the export module.
100 Internal error An unexpected error has occurred and has been
logged in the Locating Manager system log.
Example:
The "SetOutputs1" command for setting the output 1 to the value 0 of the
"17:85:00:00:ff:98" device with the "Referrer" value "MyRef42" is sent. The device is not
accessible.
Error1;2021-05-
17T10:54:58.776Z;22;SetOutputs1;17:85:00:00:ff:98;MyRef42;

Telegram SetOutputs1: Switch outputs

The transmitted command switches the specified digital output on the corresponding
transponder to the requested state.
The data transmitted by this telegram can be defined for each specific customer and depends
on the technical system that receives the outputs. To give an example, here is the connection
of the heating control of a streetcar to enable the automatic start of the wagon heating.
If errors occur while processing the command, an Error1 telegram is transmitted. If the
command was confirmed by the device, a CMD_Ack1 telegram is transmitted.

The value is always "SetOutputs1".
sent.
String or
Integer
4 Referrer String This parameter specifies the reference of the command and
may be empty.
5 Output number Integer This parameter specifies which digital output is to be
switched. The following values are possible:
1: Switch output 1
2: Switch output 2
6 Target value Integer This parameter specifies to which state the output is to be
switched. The following values are possible:
0: Switch output to Low (no voltage)
1: Switch output to High (voltage)
Note
If the device is no longer accessible, e.g. via a heartbeat timeout, the command is rejected or
aborted with error 22 "Device not accessible".
Example:
The "SetOutputs1" command for setting the output 1 to the value 0 of the
"17:85:00:00:ff:98" device with the "Referrer" value "MyRef42" is sent. The device is not
accessible.
Error1;2021-05-
17T10:54:58.776Z;22;SetOutputs1;17:85:00:00:ff:98;MyRef42;

Telegram LED_Blink1: Start of a flash pattern

The transmitted command starts the transferred flash pattern with corresponding duration
on the device.
command was confirmed by the device, a CMD_Ack1 telegram is transmitted. The responses
to the command can be assigned via the combination of the parameters "Reference telegram
ID", "NodeIdent" and "Referrer". If another party sends such a command to the Locating
Manager, but disconnects and reestablishes the connection before responding, it will not
receive a response for that command. The command will still be executed. If multiple parties
send such commands, the commands are executed according to the order in which they
arrive on the Locating Manager.

The value is always "LED_Blink1".
sent.
String or
Integer
may be empty.
5 Duration Integer This parameter specifies how many seconds the flash pattern
should be executed.
Range of values: 0 ... 43200 seconds (max. 12 hours)
6 Cycle duration Integer This parameter specifies the cycle duration of the flash
pattern in milliseconds.
During the execution on the devices, the cycle duration is
rounded commercially to a multiple of 50 milliseconds.
Value Result
24 ms 0 ms
25 ms 50 ms
50 ms 50 ms
75 ms 100 ms
Range of values: 0 ... 12750 seconds
7 Pulse duration Integer This parameter specifies how many milliseconds in the
period the LED should be lit. If this value is greater than or
equal to the value of the "Cycle duration" parameter, the LED
lights up permanently.
During the execution on the devices, the pulse duration is
commercially rounded to a multiple of 10 milliseconds.
Value Result
4 ms 0 ms
5 ms 10 ms
10 ms 10 ms
15 ms 20 ms


8 Force Integer This parameter indicates whether the flash pattern should
also be executed if a flash pattern is already active. If a flash
pattern is active and this field is not set to the value 1, error
25 "Busy" is transmitted. The following values are possible:
0: Start this flash pattern only if the device is not currently
executing a flash pattern.
1: Start this flash pattern even if the device is busy with a
flash pattern.
Note
• Note the increased power consumption of battery-operated devices when flashing for a
longer period of time.
• A flash pattern with a "cycle duration" or a "pulse duration" with a value of 0 causes the
device not to flash for the duration. This nevertheless counts as an active flash pattern.
• If the device is no longer accessible, e.g. via a heartbeat timeout, the command is rejected
or aborted with error 22 "Device not accessible".
• At the end of the flashing period, the device terminates the flashing pattern automatically.
Example:
The "LED_Blink1" command for activating the flashing pattern is sent.
Parameters:
• Duration: 10 seconds
• Cycle duration: 200 milliseconds
• Pulse duration: 100 milliseconds
• Force: No
• Device: 17:85:00:00:ff:98
• Referrer: MyRef42
The device is not accessible.
LED_Blink1;2021-05-
17T10:54:58.776Z;17:85:00:00:ff:98;MyRef42;10;200;100;0
Error1;2021-05-
17T10:54:58.776Z;22;LED_Blink1;17:85:00:00:ff:98;MyRef42;

Telegram LED_Off1: Flash pattern stop

The transmitted command stops the current flash pattern on the device.
command was confirmed by the device, a CMD_Ack1 telegram is transmitted. If no flash
pattern was active on the device, this is nevertheless confirmed as a successful stop. The
responses to the command can be assigned via the combination of the parameters
"Reference telegram ID", "NodeIdent" and "Referrer". If another party sends such a command
to the Locating Manager, but disconnects and reestablishes the connection before
responding, it will not receive a response for that command. The command will still be
executed. If multiple parties send such commands, the commands are executed according to
the order in which they arrive on the Locating Manager.

The value is always "LED_Off1".
sent.
String or
Integer
may be empty.
Note
If the device is no longer accessible, e.g. via a heartbeat timeout, the command is rejected or
aborted with error 22 "Device not accessible".
Example:
The "LED_Off1" command to deactivate the LED of the "17:85:00:00:ff:98" device with the
"Referrer" value "MyRef42" is sent. The device is not accessible.
LED_Off1;2021-05-17T10:54:58.776Z;17:85:00:00:ff:98;MyRef42
Error1;2021-05-
17T10:54:58.776Z;22;LED_Off1;17:85:00:00:ff:98;MyRef42

Telegram LED_Info1: Status of the LED

The telegram is sent by the "ExportAVT" export module for each device during connection
establishment, if this has been configured. This telegram is also sent when the flash pattern
state of a transponder or infrastructure device changes (flash pattern active, inactive or
forced to another flash pattern).

The value is always "LED_Info1".
sent.
String or
Integer
4 Flash pattern Integer This parameter indicates whether a flash pattern is active. If
active a flash pattern is active, fields 4 to 6 are filled with content.
0: No flash pattern active
1: Flash pattern active
5 Duration Integer This parameter specifies how many seconds the flash pattern
should be executed.
Range of values: 0 ... 43200 seconds (max. 12 hours)
6 Cycle duration Integer This parameter specifies the cycle duration of the flash
pattern in milliseconds.
During the execution on the devices, the cycle duration is
rounded commercially to a multiple of 50 milliseconds.
Value Result
24 ms 0 ms
25 ms 50 ms
50 ms 50 ms
75 ms 100 ms
7 Pulse duration Integer This parameter specifies how many milliseconds in the
period the LED should be lit. If this value is greater than or
equal to the value of the "Cycle duration" parameter, the LED
lights up permanently.
During the execution on the devices, the pulse duration is
commercially rounded to a multiple of 10 milliseconds.
Value Result
4 ms 0 ms
5 ms 10 ms
10 ms 10 ms
15 ms 20 ms
If the Locating Manager has been restarted while a flash pattern is active on a device and it
has been configured that the telegram is sent during the connection establishment, the
"Flash pattern active" parameter is transmitted with the value 1 in this telegram. However,
the "Duration", "Cycle duration" and "Pulse duration" parameters are then transmitted empty.

Example:
The change of the flash pattern of the "17:85:00:00:ff:98" device that these are actively
executed for 10 seconds with a cycle duration of 200 milliseconds and a pulse duration of
100 milliseconds without forcing:
LED_Info1;2021-05-17T10:54:58.776Z;17:85:00:00:ff:98;1;10;200;100
Telegram BtnStates1: Status of the button

The telegram is sent by the "ExportAVT" export module when a function button of a
transponder RTLS4083T or RTLS4084T has been pressed. The RTLS4083T transponder has 1
function button, the RTLS4084T transponder has 2 function buttons. The telegram is
transmitted when the detection of the press pattern on the transponder is completed. For
example, a "pressed short" is transmitted when the operator has briefly pressed the function
button and then released it.

The value is always "BtnStates1".
sent.
String or
Integer
4 Button 1 String The state of function button 1 is transmitted as a character.
(empty): Not pressed or unknown
S: Pressed short (a "pressed" on RTLS4084T is sent as
"pressed short")
L: Pressed long
D: Pressed twice
5 Button 2 String The status of function button 2 is transmitted as one
character. With the RTLS4083T transponder, this parameter
is transmitted empty.
(empty): Not pressed or unknown
S: Pressed short (a "pressed" on RTLS4084T is sent as
"pressed short")
L: Pressed long
D: Pressed twice
Example:
The change of state of the function buttons of the "17:85:00:00:ff:98" transponder, where
the function button 1 is pressed long (L) and the function button 2 is pressed short (S), is
transmitted:
BtnStates1;2021-05-17T10:54:58.776Z;17:85:00:00:ff:98;L;S

Telegram BattState1: Battery status

The telegram is sent by the "ExportAVT" export module during the connection establishment
if this was configured. This telegram is also sent when the battery status of a transponder or
infrastructure device changes.

The value is always "BattState1".
sent.
String or
Integer
4 Battery status Integer This parameter indicates the battery status of the
transponder. The thresholds are configured in the
"Localization Configuration" client.
0: Full - Greater than or equal to threshold 1
1: Threshold 1 - Greater than or equal to threshold 2.
2: Threshold 2 - Below threshold 2
3: Unknown - No voltage information
4: Empty - The device reports an undervoltage warning.
5: Charging station - The device is in the charging station.
Example:
The battery status of the transponder "17:85:00:00:ff:98", which is in the charging station
(5), is transmitted.
BattState1;2021-05-17T10:54:58.776Z;17:85:00:00:ff:98;5
Telegram KeepAlive1: Keep Alive

The telegram is sent by the "ExportAVT" export module during the connection establishment
if this was configured. This telegram is sent cyclically at the configured interval
(KeepAliveMsgTime).

The value is always "KeepAlive1".
sent.
3 Interval Integer This parameter specifies the seconds after which a heartbeat
is to be sent via "KeepAliveMsgTime".
Example:
The interval is configured to 5 seconds:
KeepAlive1;2021-05-17T10:54:58.776Z;5

Telegram SetAMAState1: Switching the AMA state

The transmitted command switches the device to the desired AMA state. If errors occur while
processing the command, an Error1 telegram is transmitted. If the command was confirmed
by the device, a CMD_Ack1 telegram is transmitted.

The value is always "SetAMAState1".
sent.
String or
Integer
may be empty.
5 AMA state Integer This parameter specifies the AMA state to be switched to.
The AMA states are configured in the "Localization
Configuration" client. The following values are possible:
129 - AMA 1
130 - AMA 2
131 - AMA 3
132 - AMA 4
133 - AMA 5
134 - AMA 6
135 - AMA 7
Note
If the device is no longer accessible, e.g. due to a "heartbeat timeout", the command is
rejected or aborted with error 22 "Device not accessible".
If the device is in the "via static configuration" operating mode, the command is rejected or
aborted with error 25 "Busy".
Example:
The "SetAMAState1" command to set the AMA state to the value 132 (AMA 4) of the device
"17:85:00:00:ff:98" is sent by the "Referrer" with the value "MyRef42". The device is not
accessible:
SetAMAState1;2021-05-17T10:54:58.776Z;17:85:00:00:ff:98;MyRef42;132
Error1;2021-05-
17T10:54:58.776Z;22;SetAMAState1;17:85:00:00:ff:98;MyRef42;

5.8.6 Coordinates for the "ExportAVT" export module

The Cartesian and the GPS coordinate system are supported for the "ExportAVT" export
module. The Cartesian coordinate system is used by default. The parameters are defined in x,
y and z coordinates.
The localized position of a transponder is specified in Cartesian x, y and z coordinates relative
to a point, e.g. the coordinate origin. The coordinate values can be positive or negative. You
can configure the position of the coordinate origin and the alignment of the axes. A right-
hand coordinate system with positive direction of rotation is used. The z axis points upwards
by default. The values are specified in meters with two decimal places.
When you select the output "LatLonLatLon", the positions are specified in longitude, latitude
and altitude according to WGS84. If you have specified the "X position", "Y position" and "Z
position" parameters for the telegram types, the values of the coordinates mean the
following:
Field Parameter Data type Contents

- X position Double Latitude (in decimal degrees)
Example: 50.857745
+1 Y position Double Longitude (in decimal degrees)
Example: 12.929436
+2 Z position Double Height (in meters)
Example: 350.47
If GPS coordinates are used, the values must be converted as described in section
""[Orientation]" section of the configuration file (Page 35)".

5.9 "ExportEpaperAPI" export module
5.9.1 Overview
Functionality of the programming interface

The export module "ExportEpaperAPI" operates the programming interface of transponders
with E-paper functionality. It enables external client applications to communicate with the
transponders via the Locating Manager Server. The transponder can be accessed via WAMP
(Web Application Messaging Protocol) independent of the operating system or the code
language of the external client. It is possible to connect multiple parties at the same time
through the export module.
Additional functions of the transponders

In addition to the basic function of their use as localizable nodes, transponders offer
additional functions, such as "ePaper display" or "Control keys", which can be used by the
external client applications. The display content is managed via "Themes". A transponder
Theme contains a background graphic and various form fields to display text and barcode. A
form field is a text field on the display of the transponders with the following configurable
properties:
• Field type
– Text field
– 1D barcode
• Size and position on the display
• Font and font size
Project-specific requirements for the configuration of the "Themes" as well as the download
of the configuration to the transponders can be performed during operation. Optionally, the
configuration of the "Themes" can be transferred from the manager to the transponders.
Configuration options of the programming interface

The following properties can be configured for the transponders via the programming
interface:
• Request a list showing all configured transponders of a Locating Manager Server.
• Activation of "Themes" for the transponders including transfer of the texts / barcodes to be
displayed
• Changing the contents of a form field of a transponder
• Query the current text or code and the current "Themes"
• Indication of the status of the "Control keys" used

5.9.2 Communication via the programming interface
General
The communication of the programming interface is done via a WAMP-Router that is a
component of the Locating Manager Server. Establishing a connection from an application to
the Locating Manager Server requires the implementation of a WAMP client on the part of
this application. There is no provision for client-specific parameterization. A connection can
be terminated at any time using the WAMP client application. By default, the port for the
WAMP router is not accessible outside of the PC. A parameter is available in the "Network
configuration" client that you can use to open and close the WAMP router port.
Properties of the coding

The coding via the programming interface has the following properties:
• The data to be transferred for the data transport is transferred in the "JSON" format
(JavaScript Object Notation).
• The text to be displayed is transmitted in "UTF-8" format (8-Bit UCS Transformation
Format).
• Line breaks in text fields are managed using the "\r" element

Characteristics of the programming interface
Blue Communication between programming interface and RTLS Locating Manager

Green Communication between RTLS Locating Manager and transponder
Red Communication between RTLS Locating Manager and transponder
All RPC calls (Remote Procedure Call) received by the programming interface are answered
immediately. This means that there is no need to wait for an acknowledgment of the RPC call
until the data transfer is completed. The completion of the data transmission is confirmed by
an event message provided for this purpose. The various event messages can be found in the
section "Event messages (Page 62)".
The positive acknowledgment of an RPC call does not guarantee or indicate successful
transmission to and display of new display contents on the transponders. This can happen,
for example, when the transponders were switched off during this time or are not within

radio range. Because the commands to be transmitted in the wireless network do not reach
the transponders or reach them incompletely, no event message is generated in this case.
If an RPC call sets a field form to a value that is already set, an event message is sent
immediately. This happens during or very shortly after the RPC call. Event messages are sent
when a situation is reached.
If a field content still to be transmitted is overwritten again before the previous value could
be sent to the transponders, only the value set last is transmitted to the transponders. In this
case, only the writing of the last value is acknowledged by an event message.
The transmission of background images, fonts and theme files is given higher priority and
temporarily interrupts the transmission of text content.
5.9.3 RPC calls
Parameters of the RPC calls

The following parameters can be used for RPC calls via the programming interface:
TransponderID 48-bit ID according to IEEE EUI-48
The network address in decimal notation contains the transponder ID:
• 17:b4:1a:bb:cc:e2 • 180079842
• 17:b4:10:00:00:07 • 7
• 17:b4:11:23:45:67 • 19088743
ThemeID The number of the displayed theme
The value range depends on the type and version of the transponders.
FieldID The number of the text field
The value range depends on the type and version of the transponders.
Text Permitted characters: all printable ASCII characters and German umlauts
Result Sends the return value
Return values for RPC calls

The following return values are possible for RPC calls via the programming interface:
Code Description
0x0000 No error was detected.
0x0011 The "TransponderID" parameter is invalid.
0x0012 The "ThemeID" parameter is invalid.
0x0013 The "FieldID" parameter is invalid.
0x0101 The text length is invalid.
0x0102 The text contains invalid characters or the characters are not supported.

Command "Get Version"

This command queries the protocol version. The default value is 1.
URI "agilion.wls.epaper. get_version"

Parameter None
Return value Consists of:
Version of the protocol, type: UInt32
Command "Get Tags"

This command queries a list of all configured transponders in the Locating Manager Server.
URI "agilion.wls.epaper.get_tags"
Parameter None
Result, type: UInt32
Field with the following parameters:

TransponderID, type: UInt64
ProductID, type: UInt64
FirmwareVersion, type: String
Command "Set Display Theme"

This command selects and activates the "theme" visible on the display and the transfer of the
text and barcode to be displayed. Texts are set to "empty" if they are not transferred in this
call. If one text is invalid, the others are still set.
URI "agilion.wls.epaper.set_display_theme"
Parameter TransponderID, type: UInt64
ThemeID, type: UInt32

FieldID, type: UInt32
Text, type: String

RPCResult, type: UInt32
1 ... n FieldResults, type: UInt32

Command "Get Display Theme"

This command outputs the current "theme" and the current texts and codes for a single
transponder. Only completely transmitted texts are returned. If the current "ThemeID" is
unknown, it has the return value -1.
URI "agilion.wls.epaper.get_display_theme"
Parameter TransponderID, type: UInt64

Text, type: String
5.9.4 Event messages
General
The event messages and their parameters are described below.
"Display Theme Changed" event message

This event message is sent after a "Theme" on the display has been changed. If the text
transmission has failed, the value "-1" is set in the "ThemeID" parameter, which invalidates
the parameter.
URI "agilion.wls.epaper.display_theme_changed"
Parameter Consists of:
"Display Text Changed" event message

This event message is sent after the contents of a form field on the display have been
changed. Text is the content of this form field. If the text is empty, a problem with setting the
text occurred.
URI "agilion.wls.epaper.display_text_changed"
Text, type: String

"Button Pressed" event message

This event message is sent after the F1 function key has been pressed or released. If you want
to adapt the short/long press functionality, you need to change the parameter involved in the
configuration file, "RTLS_LM_DataExport.ini".
URI "agilion.wls.epaper.button_pressed"
ButtonID, type: UInt32
ButtonDown, type: UInt32
The following happens when you briefly press the F1 function key:
Value Description
0 Evaluated as not pressed
OnShortButtonPress = 0
• Function key briefly pressed > Event parameter: ButtonDown = 0
• Function key pressed long (> 2 seconds) > Event parameter:
ButtonDown = 1
• After a short or long press and subsequent heartbeat > Event
parameter: ButtonDown = 0
1 Considered pressed
OnShortButtonPress = 1
• Function key pressed short or long > Event parameter: ButtonDown = 1
• After a short or long press and subsequent heartbeat > Event
parameter: ButtonDown = 0
The default value is 1 in the configuration file "RTLS_LM_DataExport.ini".

5.9.5 Code examples
Code example WAMP connection

{
"wamp": {
"url": "ws://127.0.0.1:12344/",
"realm": "agilion.wls",
"user": "Administrator",
"key": Contact Siemens Support for the current password.
}
}
Code example WAMP connection with RPC call

console.log("start")
var config = null
function changetheme(session, addr, themeid, param){
console.log("change zone for etag (zoneid,etag)",themeid,addr)
var epapercmd = [parseInt(addr,10),parseInt(themeid,10),param]
if ( config.debug ) console.log("send epapercmd: ",epapercmd)
session.call("agilion.wls.epaper.set_display_theme",
epapercmd).then(
function (res) {
if ( config.debug ) console.log("epaperapi response:", res);
/*
Code Bedeutung
* 0x0000 No error
* 0x0011 TransponderID invalid
* 0x0012 ThemeID invalid
* 0x0013 FieldID invalid
* 0x0101 Text length invalid
* 0x0102 Text contains invalid characters or characters not
supported
*/

);
}
console.log("load configuration")
try {
var config = require('./config.json')
} catch (e) {
console.error(e)
process.exit(1);
}
console.log("load autobahn")
try {
var autobahn = require('autobahn')
} catch (e) {
console.error(e)
process.exit(1);
}
console.log("connect to wamp-router", config.wamp.name)
var connection = new autobahn.Connection({
url: config.wamp.url,
realm: config.wamp.realm,
max_retries: 1,
authmethods: ['wampcra'],
authid: config.wamp.user,
onchallenge: function (session, method, extra) {
if (method === "wampcra") {
return autobahn.auth_cra.sign(config.wamp.key,
extra.challenge);
}
}
});
connection.onopen = function (session) {
console.log("connected to wamp-router", config.wamp.name)
if ( config.debug ) console.info("check epaper api tags")

session.call("agilion.wls.epaper.get_tags").then(

function (res) {
/*if ( config.debug ) console.log("epaperapi response:",
res);*/
for (let etag of config.tagwhitelist){
var isin = false
for (let epaper of res["args"][1]){
if ( config.debug ) console.log("check epaperadr", epaper[0]);
if (epaper[0] == etag.addr){
isin = true
break
}
}
if (isin == false){
console.error("epaper in config not found in wls
(nodekey): ",etag.addr)
}
}
}
);
}; //connection.onopen
connection.onclose = function (reason, details) {

console.log("no connection to wamp-router",config.wamp.name);
}
connection.open();

Code example RPC calls (pseudo code)

//get_version
RPC: agilion.wls.epaper.get_version [ ]
-> In return value: [Version]
//get_tags
RPC: agilion.wls.epaper.get_tags [ ]
-> In return value: [ [TransponderID, ProductID, "FirmwareVersion"]
, TransponderID, ProductID, "FirmwareVersion"], ...]
-> [ [34954, 6021999, "GANYMED_TY41_002.000.025"] , [35319, 6021999,
"GANYMED_TY41_002.000.025"], ...]
//set_display_theme
RPC: agilion.wls.epaper.set_display_theme [TransponderID, ThemeID, [
[FieldID, "text1"], [FieldID, "text2"] ] ]
agilion.wls.epaper.set_display_theme [12345, 1, [ [0, "text1"], [1,
"text2"] ] ]
-> Theme 1 with texts 1: text1 and 2: text2
//get_display_theme
RPC: agilion.wls.epaper.get_display_theme [TransponderID]
agilion.wls.epaper.set_display_theme [12345]
-> In return value: [result_code, ThemeID, [ [FieldID, "text1"],
[FieldID, "text2"] ] ]
5.9.6 Additional information

You can find additional information on the subject of WAMP etc. at:
LINK: https://wamp-proto.org/
LINK: https://crossbar.io/docs/
LINK: https://crossbar.io/autobahn/
LINK: https://github.com/crossbario/autobahn-js
LINK: https://github.com/crossbario/autobahn-cpp

5.10 BatteryLevelEvents
5.10 BatteryLevelEvents
The "Data Export Service" can support battery level monitoring. In this case, battery level
events are generated for transponders and gateways if you enable this in the
"RTLS_LM_DataExport.ini" configuration file and the transponders send voltage information.
Set the "Active" parameter to "1" to enable the generation of events. For this, create the
section in the "RTLS_LM_DataExport.ini" configuration file if it is not available. If the "Active"
parameter is not configured, "0" is assumed.
If the voltage falls below or exceeds one of the thresholds, an event is generated and
processed via the "Message management" functionality. If the voltage value is close to a
threshold, it is possible that this threshold will be undershot and exceeded several times in
succession. Hysteresis is used to prevent these unnecessary events.
When a threshold is undershot and the voltage value changes from the safe to the critical
range, the event is sent immediately. If the voltage value changes from the critical to the safe
range, it must also exceed hysteresis for the event to be sent. The hysteresis is specified in
percent and can be configured via the "RTLS_LM_DataExport.ini" configuration file.
The "VoltageHysteresisPercentage1" and "VoltageHysteresisPercentage2" parameters specify
the percentage of the voltage that must be exceeded for the event to be sent. You can
disable the hysteresis if you set it to the value "0". If the parameter is not configured, the
value "20" is assumed. For more information about the message code "40002 Battery status",
refer to the documentation of the "Message management" functionality.
Threshold 1 and Threshold 2 have typical default values. You can configure the values in the
"Localization Configuration" client on a device-specific or group basis.

Troubleshooting 6
If you cannot connect via an export module, check the following possibilities:
• Check if the "Data Export Service" is active and the export modules are activated.
The "Network Configuration" client provides an overview of the "Data Export Service" and
its active export modules. If the message "No active data export service" is displayed,
check whether the "Data Export Service" is active and whether login data and/or password
have been entered correctly.
If the "Data Export Service" is active, all export modules are listed with state on the
corresponding page. If an export module is listed in red, read out the messages in the "Log
Viewer" client in the "Readout" section.
• Correct connection problems
If the connection still cannot be established, check configuration for the port, host, and
firewall.


APH RTLS-Datenexportdienst-V2.13.0.0 76

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

APH RTLS-Datenexportdienst-V2.13.0.0 76

Uploaded by

Copyright:

Available Formats

SIMATIC RTLS Data Export Service

Installing the "Data Export

Siemens AG C79000-G8976-C531-07 Copyright © Siemens AG .

SIMATIC RTLS Data Export Service

SIMATIC RTLS Data Export Service

Validity of this documentation

Industry Online Support

SIMATIC RTLS Data Export Service

SITRAIN - Training for Industry

RTLS Technology and Practice (ID-RTLS-TP)

SIMATIC RTLS Data Export Service

Note on firmware/software support

Recycling and disposal

SIMATIC RTLS Data Export Service

SIMATIC RTLS Data Export Service

Users, roles and passwords

SIMATIC RTLS Data Export Service

Automation License Manager

Software (security functions)

Secure and non-secure protocols

SIMATIC RTLS Data Export Service

List of available protocols (local access via a local network)

Service/Protocol Port number Default port status Authentication Loopback only

SIMATIC RTLS Data Export Service

SIMATIC RTLS Data Export Service

Name Technology Description

SIMATIC RTLS Data Export Service

SIMATIC RTLS Data Export Service

SIMATIC RTLS Data Export Service

SIMATIC RTLS Data Export Service

SIMATIC RTLS Data Export Service

The different configurations are available depending on the export module.

SIMATIC RTLS Data Export Service

Parameter Range of values Description

SIMATIC RTLS Data Export Service

Parameter Range of values Description

5.2 Supported framing methods in the RTLS localization network

Framing method Description

"Framing7F8F" framing method

SIMATIC RTLS Data Export Service

Example of a masked data packet:

SC: Start character

5.3 Logging of internal events and data transfer

Logging of internal events

Logging the data transfer

SIMATIC RTLS Data Export Service

Structure of protocol messages

Elements of the protocol messages Description

A protocol message is therefore always structured as follows:

SIMATIC RTLS Data Export Service

5.4 "ExportDatabase" export module

Preferences for exporting to a database

Exported data in the database

Entry Type Unique Description

SIMATIC RTLS Data Export Service

5.5 "ExportTCPIP" export module

Fiel Name Description

Example string: "20190712;150257;27;3c:4b:89:12:77:6f;83.67;10.67;2.50;\n"

SIMATIC RTLS Data Export Service

5.6 "ExportSTDIP" export module

Field Name Description

Field Name Type Description Source

SIMATIC RTLS Data Export Service