RTLS System Status and Management

Basic settings

GET_INFO

This request allows the client to ask for some basic information about the Eliko RTLS Server Daemon (ERTLSSD).

Client sends:

$PEKIO,GET_INFO

The system responds:

$PEKIO,INFO,<parameter list>

<parameter list> is a comma-separated list with the following fields:

Note: to allow future compatibility, the client should not assume this exact order of parameters shown above. It is advised to search the parameter list for pairs or triples of keywords and values, where the keyword specifies the meaning of the parameter(s) immediately following it. Unknown keywords and other field values should be ignored.

A full example of the system’s response would be:

$PEKIO,INFO,VERS,2.3.35,2003035,TIME_STARTED,Tue Oct 15 15:11:38 2019,RUNNING_TIME,9251,RRS,15765,COORDS,4921,COMMANDS,187,TIME_NOW,1571147478

GET_ALL_SETTINGS

This request allows to get most of the important system settings for backup purposes or for moving the environment to another server. Please note that we don’t describe the responses to this request in too much detail – it depends on the functionality the user has configured for the system, may contain some internally generated attributes and will probably grow with every software upgrade. Rather than fully describing the output data, we present a list of settings which will and will not be backed up by this request.

The output will contain information about the following:

• Anchors – their coordinates, roles, last connection times, proximity detection modes.

• Tags – their update intervals, filters, alias, 2D/3D/Fixed height setting, Z limits.

• Global settings – cell size, filter multiplier, proximity mode, peak removal, custom packets.

The output will NOT contain information about the following:

• The RTLS Manager’s settings – the background map and its position, the settings for the axes.

• The historic positioning data.

• Custom network settings (set by the SET_NETWORK request) and settings for the outbound TCP socket (set by the SET_OUTPUT_PARAMS request).

• Session attributes (which notifications and reports have been requested at certain open TCP sockets).

Client sends:

$PEKIO,GET_ALL_SETTINGS

The system responds with a list of packets, terminated by the EOF end marker:

$PEKIO,<request keyword>,<parameter list>

$PEKIO,<request keyword>,<parameter list>

...

$PEKIO,EOF

The client should save the response packets to any suitable storage media. A simplified example of the system’s response would be:

$PEKIO,SET_PROXIMITY_MODE,OFF

$PEKIO,SET_ANCHOR_E,0xA6A7,D,0x000971,5,1612038269,0,8.65,4.73,2.04

$PEKIO,SET_ANCHOR_E,0xBB78,C,0x00095A,5,1612035726,0,8.86,-0.09,2.04

$PEKIO,SET_ANCHOR_E,0xC436,A,0x000969,5,1612035726,0,3.03,0.31,2.19

$PEKIO,SET_ANCHOR_E,0xCFEF,B,0x0008CC,5,1612036796,0,4.02,3.71,2.04

$PEKIO,ADD_TAG,0x42

$PEKIO,SET_TAG_PARAMS,0x42,2D,1.000000

$PEKIO,SET_TAG_SAMPLE_INTERVALS,0x42,3000,3000

$PEKIO,ADD_CUSTOM_REPORT_TYPE,CR_E3,ON,A_DIST,B_DIST

$PEKIO,EOF

Note that there is no explicit request for restoring the configuration or moving to a new RTLS Server. Instead of that, all the stored response packets should be sent back to the system one-by-one, verifying also that each of them gets the $PEKIO,OK response. To make this easier, the response packets are already in the form of requests, rather than responses. This means they are suitable for sending back to the server without any modification. Please note that there is no need to store the end marker $PEKIO,EOF and it is not meant to be sent back to the system.

Output parameters for external TCP connection

SET_OUTPUT_PARAMS

Besides operating as a TCP server for external connection requests, the RTLS Server can also be a TCP client and connect to an external TCP server.

This request allows to set the connection parameters for this automatic external TCP connection. When enabled, the RTLS Server will always try to keep an open TCP connection to the specified destination server and restores it in case of network problems.

Note that only one outbound TCP connection is supported by the RTLS Server. You may use the SET_OUTPUT_PARAMS request from any open TCP connection, the result is always the same: the one and only outbound TCP connection gets configured.

Client sends:

$PEKIO,SET_OUTPUT_PARAMS,<parameter list>

<parameter list> is a comma-separated list with the following fields:

Some examples of client’s request would be:

$PEKIO,SET_OUTPUT_PARAMS,127.0.0.1,3434,ON

$PEKIO,SET_OUTPUT_PARAMS,,,OFF

$PEKIO,SET_OUTPUT_PARAMS,,,ON

If processing the request was successful, the system responds:

$PEKIO,OK

If the arguments could not be parsed, the system responds:

$PEKIO,NOT_GOOD

Note that when switching the external connection ON, it is allowed to omit the IP address and/or Port (as shown in the last example). In this case, the values that were set last time will be used.

The Eliko RTLS Communication Protocol format is the same, no matter which party initiated the TCP connection. This means an external party can send its requests and receive the responses and reports via any TCP connection it has to the RTLS Server. There are still some differences depending if the RTLS Server acts as a TCP client or server. These are described in chapters “Protocol Overview” and “SET_REPORT_LIST”.

GET_OUTPUT_PARAMS

This request allows to get the connection parameters that were previously set by command SET_OUTPUT_PARAMS.

Client sends:

$PEKIO,GET_OUTPUT_PARAMS

The system responds:

$PEKIO,OUTPUT_STREAM_STATUS,<parameter list>

<parameter list> is a comma-separated list with the following fields:

A full example of the system’s response would be:

$PEKIO,OUTPUT_STREAM_STATUS,127.0.0.1,9201,ENABLED,DOWN

Network settings

SET_NETWORK

This request allows to configure the network interface of the RTLS Server machine. Currently this functionality is limited to configuring the client’s ethernet port (ETH_C) only, but this may change in the future.

As with other requests, the SET_NETWORK may also be used via any network interface available on the RTLS Server machine, even the ETH_C itself. Please be careful when using this request, especially if you are using ETH_C itself to access the server. When using static IP configuration, the IP address, network mask and possibly other parameters should match the client network’s requirements, or otherwise there would be no communication possible via ETH_C. This means when using static IP configuration, it is easy to make a mistake and lock yourself out of further access via ETH_C. If this happens, the possibilities to recover are as follows:

• If the latest ETH_C configuration is known, it might be possible to connect ETH_C to a network or PC that matches the latest ETH_C configuration. In case the latest ETH_C configuration was to use a DHCP server, the network or PC used for recovery should have a DHCP server running. In case the latest ETH_C configuration was to use a static IP, the network or PC used for recovery should have the same network mask that was configured to the ETH_C interface of the RTLS Server machine and it is also important to avoid any IP address conflict in the recovery network.

• If there is access to the RTLS Server machine’s Wi-Fi or ETH_A network port, the recovery may be done via them.

• If no access to the server is possible via ETH_C, ETH_A or Wi-Fi, you need to send the server physically to Eliko for recovery.

Client sends:

$PEKIO,SET_NETWORK,<parameter list>

<parameter list> is a comma-separated list with the following fields:

To configure the ETH_C interface to use static IP configuration, the following key and value pairs may be used as <network settings>:

The order of key and value pairs in <network settings> section is not important. Optional key and value pairs may be completely omitted.

Some examples of client’s request would be:

$PEKIO,SET_NETWORK,ETH_C,DHCP

$PEKIO,SET_NETWORK,ETH_C,IP,192.168.2.8,MASK,255.255.255.0,GW,192.168.2.0,DNS,8.8.8.8,BROADCAST,192.168.2.255

When receiving the SET_NETWORK request, the RTLS Server first sends a response and then makes the necessary changes in ETH_C interface settings. Note that in case this request was given through ETH_C interface itself, the TCP connection is lost. If using another interface (ETH_A or Wi-Fi), the connection stays open.

If processing the SET_NETWORK request was successful, the system responds:

$PEKIO,OK

If the system encountered an error when processing the request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

Some full examples of the system’s error responses would be:

$PEKIO,NOT_GOOD,IP_FIELD

$PEKIO,NOT_GOOD,UNSUPPORTED_FIELD,ABC

GET_NETWORK

This request allows to get information about network interface of the RTLS Server machine. Currently this functionality is limited to the client’s ethernet port (ETH_C) only, but this may change in the future.

Client sends:

$PEKIO,GET_NETWORK,ETH_C

Note that the last field of the request is the name of the network interface for which information is requested. Currently only the value of “ETH_C” is supported.

If processing the GET_NETWORK request was successful, the system responds:

$PEKIO,NETWORK,<parameter list>

<parameter list> is a comma-separated list with the following fields:

Currently, the <network settings> section contains only one key and value pair:

The client should parse the <network settings> section as key and value pairs. For future compatibility, the user should not expect these key and value pairs to appear in some specific order. Pairs with unknown keys should be ignored by the client.

A full example of the system’s response would be:

$PEKIO,NETWORK,ETH_C,DYNAMIC,IP,192.168.2.8

If the system encountered an error when processing the GET_NETWORK request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

A full example of the system’s error response would be:

$PEKIO,NOT_GOOD,NO_INTERFACE_GIVEN

System time and NTP settings

SET_SYSTIME

This request allows to set the system time.

Client sends:

$PEKIO,SET_SYSTIME,<time parameter>

<time parameter> may be:

• A Unix timestamp in integer format – for manually setting the system time. Note that fractional part is not allowed. For sub-second precision, please use the NTP option.

• The keyword “NTP” – to use the NTP servers for automatic time synchronization. By default, the NTP servers pointed by the DHCP server are used. To modify them, please use the SET_NTP_POOL request. This may be required for example in case the DHCP server does not provide information about the NTP servers or in case these NTP servers are not accessible by the RTLS Server.

Some full examples of client request would be:

$PEKIO,SET_SYSTIME,1614950443

$PEKIO,SET_SYSTIME,NTP

If the manual time setting is successful, the system responds:

$PEKIO,OK,<diff>

<diff> is the difference in seconds between the old and new timestamps, just for informational purpose. The value is negative when setting the clock forward and positive when setting it backwards.

A full example of the system’s response for manual time setting is as follows:

$PEKIO,OK,-12

If setting the time management mode to “NTP” is successful, the system responds:

$PEKIO,OK

If processing the request resulted with an error, the system responds:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

A full example of client error response would be:

$PEKIO,NOT_GOOD,PARAMS

GET_SYSTIME

This request allows the client to request information about the system time settings and status.

Client sends:

$PEKIO,GET_SYSTIME

If processing the request was successful, the system responds:

$PEKIO,SYSTIME,<parameter list>

<parameter list> is a comma-separated list with the following fields:

Some full examples of the system’s response would be:

$PEKIO,SYSTIME,1589209744.717368,ACTIVE,"Synchronized to time server 91.189.91.157:123 (ntp.ubuntu.com)."

$PEKIO,SYSTIME,1589209711.179742,INACTIVE,N/A

If the system reported an error while trying to query the time settings, the system responds:

$PEKIO,NOT_GOOD,QUERY_FAIL

SET_NTP_POOL

By default, the RTLS Server synchronizes its clock by using the default configuration of systemd-timesyncd service, which means the NTP server addresses are queried from the DHCP server. There may be occasions, when this behavior is not sufficient and for these, the SET_NTP_POOL request allows to set the NTP server addresses explicitly.

Client sends:

$PEKIO,SET_NTP_POOL,<server list>

<server list> is a variable length, comma separated list of NTP server addresses. May contain both the IP addresses and domain names. Up to 3 values may be specified, the rest will be ignored. Specifying an empty list will restore the default behavior, which means only the NTP servers pointed by the DHCP server are used.

Some full examples of client request would be:

$PEKIO,SET_NTP_POOL,192.98.49.10,ntp.ubuntu.com

$PEKIO,SET_NTP_POOL

If processing the request was successful, the system responds:

$PEKIO,OK

If the system reported an error when trying to modify the list of NTP servers, the system responds:

$PEKIO,NOT_GOOD,SYSTEM_ERROR

GET_NTP_POOL

This request allows to get the list of existing NTP server addresses, configured previously by the SET_NTP_POOL request.

Client sends:

$PEKIO,GET_NTP_POOL

If processing the request was successful, the system responds:

$PEKIO,NTP_POOL,<server list>

<server list> is a variable length, comma separated list of NTP server addresses currently present in the system (up to 3). May contain both the IP addresses and domain names.

If there are no NTP servers configured, the keyword “DEFAULT” is responded. This means the system can use only the NTP servers pointed by the DHCP server.

Some full examples of the system’s responses would be:

$PEKIO,NTP_POOL,192.98.49.10,ntp.ubuntu.com

$PEKIO,NTP_POOL,DEFAULT

If the system encountered an error when processing the GET_NTP_POOL request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

Note that these errors should not appear during normal usage of the system, so in case they still do, please report them to Eliko!

A full example of the system’s error response would be:

$PEKIO,NOT_GOOD,NO_ACCESS

VPN settings

SET_VPN

Supported from RTLS Server software version 2.5.14.

The RTLS Server contains a VPN client, which allows to connect to Eliko’s cloud-based VPN server. When the VPN client is enabled, the RTLS Server automatically creates the VPN connection and keeps it open. There are two main objectives to use this VPN solution:

• When enabled, the relevant technical people at Eliko can get access to the RTLS Server, to be able to offer remote support.

• The VPN solution is a prerequisite to use Eliko’s Remote Monitoring Service, which allows to constantly gather diagnostic data about system health, as well as to get automatic e-mail notifications when some issues arise. This service is separately licensed by Eliko and when used, assumes the VPN service to be always up and running.

For the VPN solution to work, it is necessary that the on-site network allows the RTLS Server to connect to public internet. The connection is made through outbound TCP port 443. There are no inbound TCP ports used for this VPN service.

Starting from October 2021, all the Eliko RTLS Servers are shipped with the VPN client already installed and configured, but its status is OFF by default (unless explicitly agreed to be ON during the sales process). Updating the software of earlier RTLS Servers to have the VPN capabilities is possible, please contact Eliko for more details.

The SET_VPN request allows to switch the VPN service ON and OFF. The change takes place immediately and the new state is persistent through system reboots and power cycles.

To switch the VPN service ON, the client sends:

$PEKIO,SET_VPN,ON

To switch the VPN service OFF, the client sends:

$PEKIO,SET_VPN,OFF

If processing the request was successful, the system responds:

$PEKIO,OK

If the system encountered an error when processing the SET_VPN request, the following response will be sent:

$PEKIO,NOT_GOOD,<error ID>

<error ID> can be one of the following:

A full example of the system’s error response would be:

$PEKIO,NOT_GOOD,FIRST_PARAM

GET_VPN_STATUS

This request allows to query the VPN client’s status. The response contains information both for the desired status set by request SET_VPN, as well as the actual status (which might be affected by the network).

Client sends:

$PEKIO,GET_VPN_STATUS

The system responds:

$PEKIO,VPN_STATUS,<parameter list>

<parameter list> is a comma-separated list with the following fields:

A full example of the system’s response would be:

$PEKIO,VPN_STATUS,ON,ON,ON