Automated Sensor Configuration Using ubisense_ls_autoconfig_sink

Automated sensor configuration provides two key capabilities: real-time sensor installation verification and support for calibration using Cloud Calibration.

During sensor installation, ubisense_ls_autoconfig_sink validates sensor operation as each sensor is fitted. Network connectivity, timing synchronization, power, and sensor placement issues are detected immediately while the installer is still on site. Sensor LED indicators provide instant feedback, allowing problems to be identified and corrected before sensor installation work is completed. This reduces installation delays and helps avoid the cost and disruption of returning to the site later with access equipment such as ladders, cherry pickers, or scaffolding.

Automated sensor configuration also allows for sensors to be calibrated and verified before a DIMENSION4 dataset has been deployed. During calibration, ubisense_ls_autoconfig_sink captures sensor event data from the installed sensors while a point cloud scanner independently captures the point cloud data for the environment. The sensor event data and point cloud data can then be processed by Cloud Calibration to determine sensor positions, orientations, and cable offsets. When the DIMENSION4 dataset has been deployed, the calibration data from Cloud Calibration can be imported directly into the dataset. This simplifies commissioning and increases the likelihood of a successful system rollout.

Requirements

The ubisense_ls_autoconfig_sink command-line tool is located in the tools folder of your DIMENSION4 distribution directory. To use the tool, navigate to the path where you unzipped the tools folder, or add it to your PATH.

Before installing and calibrating your sensors, you must have:

  • Firmware version 1029 or above

  • Filesystem version 3545 or above

  • A dedicated sensor subnet

  • A DHCP server

  • A Cloud backend/VPC/VPN (if applicable)

  • A scanner with an attached Ubisense tag

  • Access to Cloud Calibration

The only supported timing distribution architecture is the single cable Ethernet — Power — Timing configuration with timing source TDUs and timing sink sensors, so local timing configuration is unnecessary.

Overview

The automated configuration process is as follows:

  • Set up the network

  • Run ubisense_ls_autoconfig_sink

  • Install the sensors

  • Calibrate the sensors

  • Stop ubisense_ls_autoconfig_sink

  • Process the sensor calibration

  • Load the calibrated sensors into your DIMENSION4 dataset

Setting Up the Ethernet Network

Before you can use ubisense_ls_autoconfig_sink, you must set up your network according to the following design:

  1. Ensure that the sensor firmware is set to version 1029 or above and that the sensor is flashed with filesystem version 3545 or above.

  2. Configure the Ethernet network.

    • A single subnet needs to be configured for the sensor network with no other devices on the subnet

    • A DHCP server must be provided

    • For cloud installations: set up cloud backend, VPC, and standard VPN router

This network architecture ensures that when sensors are powered up, they can automatically:

  • Obtain an IP address via DHCP

  • Find and connect to the Configuration Server

  • Receive stable timing signals (see Timing Sources and Timing Trees for more information on timing signals)

  • Function without requiring external configuration

Using ubisense_ls_autoconfig_sink During Sensor Installation

The ubisense_ls_autoconfig_sink tool is used during sensor installation to verify correct sensor operation and timing, all while the installer is at the sensor location. Start the tool before sensor installation so that data is captured while sensors are installed.

Sensor Installation

If the installation is a cloud installation, run ubisense_ls_autoconfig_sink on a cloud-hosted instance that has connectivity to the sensor network.

If the installation is an on-premises installation, run ubisense_ls_autoconfig_sink on a suitable machine that is on the sensor subnet.

Run ubisense_ls_autoconfig_sink with its parameters:

ubisense_ls_autoconfig_sink.exe <tag id> <port> <max file size> <file prefix> [debug]

For example:

ubisense_ls_autoconfig_sink.exe "00:11:CE:00:00:00:11:BE" 4000 100000 survey
Parameter Definition

tag id

The ID of the tag which you are going to use for testing.

port

The port on your machine to use for receiving events from sensors.

max file size

The maximum number of events stored in each .ubievents file. Default is 10,000 with 50 files per directory.

file prefix

The prefix of the .ubievents files to be stored.

debug

Specify this to see printouts of the messages received from sensors.

While ubisense_ls_autoconfig_sink is running, install the sensors according to a sensor plan generated by Sensor Planner. Check the LED on each sensor to confirm operation. When the sensor LED displays solid green then the sensor is registered with the backend and is ready to transmit sensor event data.

The sensor LEDs follow the patterns, in order, described in the table below.

LED category

LED color

Troubleshoot

Power

After about one second after the sensor is plugged in, the LED displays orange

If the LED does not come on then the sensor is not receiving power.

Reason(s) for error: cable fault, connector fault, Power of Ethernet (PoE) issue not being supplied from the switch, or failed sensor.

Networking

After about one minute the LED should change from steady orange to flashing green-off-green-off to indicate successful network connection

After about 30 seconds to a few minutes, if there is a network failure, the LED will change to red, followed by a four-color error code, repeated six times. There are two possible error codes that may be seen:

  • Red-orange-red-orange: indicates that the first stage of networking failed (retrieval of DHCP address).

  • Red-orange-red-green: indicates that the second stage failed (retrieval of sensor configuration). This second failure mode will only happen if the network itself is incorrectly set up.

Reason(s) for error:  cable fault, or connector fault.

Sensor internal initialization

After about 30 to 40 seconds the LED should change from flashing green and quickly stabilize to flashing green-orange-green-orange, until a tag is placed in front of the sensor, when it will progress further

If the sensor persistently flashes red-off-red-off for over one minute then it has an internal fault and should be replaced (this will be extremely rare).

If the sensor persistently flashes orange-off-orange-off for over one minute then it is not receiving a stable timing signal.

Reason(s) for error: cable fault, connector fault, or incorrect cable plugging in the TDU for the sensor.

Detecting UWB

When a tag is placed in front of the sensor, if its LED was previously flashing green-orange-green-orange, it should quickly transition to solid green

If no signal has been picked up from the tag then the LED continues to flash orange-off-orange-off.

Reason(s) for error: tag not transmitting, or sensor internal fault.

If the sensor flashes long green-long red-long green-long red (where each color persists for two seconds or more), then it has received UWB but failed to receive any acknowledgment from the

ubisense_ls_autoconfig_sink tool. This is highly unlikely if all the other networking checks have

succeeded (which they must have to reach this stage) and would indicate a misconfiguration of the underlying network.

Using ubisense_ls_autoconfig_sink During Sensor Calibration

After you have installed the sensors, calibrate the sensors while ubisense_ls_autoconfig_sink is still running by capturing a point cloud scan of the site using a suitable scanner with an attached Ubisense tag. When you have finished capturing the point cloud scan, stop ubisense_ls_autoconfig_sink.

A calibrated sensor has three parameters:

  • Position: the position of the sensor

  • Orientation: the direction the sensor is pointing

  • Timing: the signal delay through the timing cable

With these parameters known, DIMENSION4 has all the geometric information it needs to compute the positions of tags. These positions are computed from both the angle of arrival of the tag signal at each sensor, and the time difference of arrival between pairs of sensors. The former requires the position and orientation, while the latter requires the position and timing.

Sensors in DIMENSION4 are arranged in groups, where each group can combine observations of a tag to compute its location within the area covered by the group. For example, a single assembly line or storage area might be covered by a sensor group.

After conducting the point cloud scan, the ubisense_ls_autoconfig_sink tool generates .ubievents files which contain sensor events. The .ubievents files and the physical survey data from the point cloud scan can then be used in Cloud Calibration to determine and refine the real-world positions and orientations of installed sensors. Cloud Calibration computes all the sensor calibrations at once for a single group by matching sensor data to a 3D point cloud scan of the site and saves them into an output file called calibrations.csv. This file contains the sensor positions, orientations and timing delays between sensor pairs and is used to load the calibrated sensors into your DIMENSION4 dataset. Press F1 in Cloud Calibration to view its help file.

Sensor Events Files

The ubisense_ls_autoconfig_sink tool receives measurements from individual sensors and groups them together according to tag ID or sequence number so that each individual tag transmission generates a single measurement event. The tool writes events to .ubievents files and creates a directory structure created as required.

Each measurement in the .ubievents file contents comprises:

  • The measured angles and pseudo-range

  • The timing root of the sensor (because of the standardized reference architecture, this is always the TDU that the sensor is plugged into)

  • Arbitrary sensor positions

    The .ubievents file at this point doesn't know what the sensor positions are, so each sensor is placed along an arbitrary position on the Y axis. The .ubievents file is used in Cloud Calibration to solve the positions of the sensors and their orientation. Cloud Calibration uses the time, tag ID, azimuth, elevation (angle to the tag from each sensor), and the time of arrival for each sensor from the .ubievents file.

Physical Survey Data

The point cloud scan generates two files containing the necessary physical data for calibration:

  • A point cloud (text format containing X, Y, Z coordinates)

  • A trajectory file (in text time, position, orientation format, presented as 8 floats containing time, Cartesian position and quaternion orientation)

Loading Calibrated Sensors into Your DIMENSION4 Dataset

Load calibrations.csv into your DIMENSION4 dataset by running:

ubisense_calibration_loader calibrations.csv