Integration using the DIMENSION4 ISO 24730 service

The DIMENSION4 ISO 24730 service is an ISO 24730 API server, serving real-time Ubisense platform locations to external clients via TCP/IP connections. The service supports connections from multiple clients simultaneously. When used with a DIMENSION4 system running the location sink registration service, the service can be configured to override the V2 sink address and receive locations from the sensors directly.

Requirements

The DIMENSION4 ISO 24730 service is configured using the ubisense_iso24730_configuration_admin.exe tool.

To get the tool, run Application Manager, open the DOWNLOADABLES task, and expand Location system / ISO 24730 tools and documentation. Select ubisense_iso24730_configuration_admin.exe and click Download selected items. Optionally, change the download destination directory. Then click Start download.

Protocol Summary

The communication protocol outlined in the ISO 24730 standard is a ‘Text over Socket’ protocol, where data is sent to the clients as human readable messages over a TCP/IP connection. Protocol messages are comma-separated fields of human readable data ending in <CR><LF>.

When a client connects to the service, it receives a stream of protocol messages including keep-alive messages during periods of inactivity on the line. Messages sent from the client to the server will be ignored. The client is responsible for maintaining the connection and reconnecting if the connection is lost.

Locate Message Formats

The service uses several formats of locate message:

Locate messages with only the mandatory fields.
Locate message with the classification field in addition to the mandatory fields. The classification field’s value represents the type of object the location is for, when the object is not a tag.

Only fields defined in the standard are used in the locate messages: there are no custom Ubisense extension fields.

DIMENSION4 ISO 24730 service Configuration

You define which cells/controllers to run the API service on and which TCP socket address each instance of the service will listen for clients on. Definitions are created using a mapping file that is imported to your system using the ubisense_iso24730_configuration_admin.exe tool. You can also use the tool to download the current configuration from your DIMENSION4 system.

Create a mapping file to define your configuration.

The mapping file is a human readable text file consisting of lines of comma-separated cell name, controller name, listening address tuples. For example:
```
Location Cell 00001, Controller1, 0.0.0.0:12345
Geometry Cell 00002, Controller1, 0.0.0.0:54321
```
The service will be deployed for each cell/controller in your mapping file, registering a sink address for each location cell which is a child of this cell. Each listening address must be unique for that controller.

Using the IP address 0.0.0.0 will make the server listen for clients on all available network interfaces. Unless you have multiple network interfaces and want to restrict the service to listen only on a specific interface, you can safely use the IP address 0.0.0.0 in your mapping file. Otherwise use the IP address of the desired network interface.
Import the mapping file using the ubisense_iso24730_configuration_admin.exe tool.

The tool has an advertise_location_sink option that can be used when importing a mapping. When this option is used, the service will advertise its sink address as a location sink for the location cell(s). If your dataset is running the location sink registration service that is part of the DIMENSION4 package, the service’s sink address will be registered as the V2 sink address, causing the service to receive locations directly from the sensors instead of these locations being sent to the location cells. When this option is not set, the service will not receive Ubisense tag locations without another program forwarding locations to its sink.

Advanced Configuration

The service has the following advanced parameters that are configured via the Registry or platform.conf file. In most cases, you should not need to set these parameters.

Parameter	Description
iso24730_api_server_keepalive_period	The period of keep-alive messages as defined by the standard, in seconds. Default value of 10. Valid values are integers in the range 1 to 3600
iso24730_api_server_cell_list	Comma-separated list of location cell names. When set, the service will only serve location from within the cells listed
iso24730_api_server_max_client_send_buffer_mb	Maximum size, in MB, of the send queue for a client before it is disconnected. Used to disconnect slow clients when the service is under heavy load. Default value of 1.

Health metrics

If you have SmartSpace Health monitoring licensed and configured, health metrics are available to monitor the performance of the DIMENSION4 ISO 24730 service. See the section on Health monitoring on the SmartSpace website. A spreadsheet giving details of the metrics provided is available on the Ubisense Downloads Portal (login required).