System Architecture

Architecture Overview

This document describes the CUWB Real-Time Location System (RTLS) architecture and components. It provides a high level overview of the system along with details on how user applications can integrate with the system and consume location data.

System Components Diagram

CUWB Subscribers

CUWB subscribers are applications that consume data from a CUWBNet instance. These applications range from Ciholas provided applications to custom integrations. More details on some of these applications can be found in Support Applications.

Typical subscriber applications utilize a Ciholas Data Protocol (CDP) connection to the user data stream in order to consume location data. For an example on consuming location data via CDP, check out our Using CDP Application Note.

Host PC

The CUWB system utilizes a Host PC running the CUWB Management Package and other support applications. These computers typically run 64-bit Ubuntu LTS. A virtual machine can be utilized as the Host PC, but certain precautions related to resources and networking must be taken into account. These can involve USB passthrough difficulties, additional latency in VMs, and applications receive inadequate amounts of resources when the VM is set up.

The Host PC is the heart of the CUWB system. These are two major components on the Host PC: the CUWBs Manager and CUWB Configurations. A CUWB Configuration is a set of settings that describes how to regulate the CUWB Devices and produce output for the CUWB subscribers for an associated CUWBNet. The CUWB Manager is a web based tool for managing and interacting with CUWB Configurations or CUWBNets. It can be used to launch (aka. Start and stop) CUWBNets as well as provide status and other pertinent system information.

The CUWB system could use one or more computers running as a Host PC. Systems that utilize more than one Host PC must be connected on the same Anchor LAN for intercommunication.

Please reference the CUWB Manager Manual for details on Host PC requirements and details on installation.

CUWB Devices

CUWB devices communicate over Ultra-Wideband (UWB) and are compatible with the Ciholas UWB RTLS system. CUWB devices may also connect to a running CUWBNet over Ethernet utilizing a UDP protocol called Ciholas Data Protocol (CDP), or via a serial connection using Ciholas Serial Protocol (CSP) which is based on CDP.

There are two classes of CUWB devices: Anchors and Tags.

Anchors

Anchors are static devices placed in a region of interest that act as reference points. To generate meaningful position output, RTLS applications require known physical locations within a region to compare timing data.

Anchors must have Ethernet connectivity to communicate with the CUWB Engine for configuration, scheduling, commands and data transport.

System Architecture Diagram

CUWB Manager

The CUWB Manager is a process that runs on the Host PC. The process runs at system startup, and is used to create, configure, and perform actions on CUWB Configurations. It hosts the CUWB Manager frontend to HTML clients. See the CUWB Manager Manual for additional instructions on use.

API Backend

The backend is a python-based web server that exposes a RESTful HTTP API. The documentation for the API is available under API Control.

The backend reads and writes to the CUWB Configuration File and monitors CDP Streams for status information. The backend utilizes redis for interprocess communication with the CUWB Engine.

UI Frontend

The frontend is a web application served by the CUWB Manager which provides end users with a convenient interface to configure, monitor, and control CUWB Configurations and CUWBNets.The frontend is accessed by a browser. It utilizes the RESTful API to communicate with the backend, providing users with up-to-date information regarding CUWB Configurations and CUWBNets. Additionally, the frontend opens a WebSocket connection to receive real-time updates from the Host PC. For a walkthrough of the CUWB Manager UI, see the CUWB Manager GUI Walkthrough.

Websocket

The CUWB Manager launches a separate ‘WebSocket’ process at startup. The WebSocket process is used to send events, such as device and network status, to frontend instances.

CUWB Configurations & CUWBNets

A CUWB Configuration is a user configured set of UWB devices and settings that define a CUWBNet. A CUWBNet is the running, or operating, collection of anchors and tags whose settings are defined by a CUWB Configuration. The Host PC can have multiple CUWBNets running at the same time.

CUWB Configuration File

CUWB Configuration Files are databases with the .cuwb file extension stored on the Host PC. The configuration files are read and monitored by the CUWB Manager and allow for dynamic changes even when the associated CUWBNet is running.

CUWB Engine

The CUWB Engine is a process that is instantiated by the CUWB Manager using the settings defined by a CUWB configuration. In the Frontend user interface (UI) users ‘start’ a CUWB Configuration resulting in a CUWB Engine instance and active CUWBNet that is based on that configuration. The CUWB Engine is responsible for running a CUWBNet and interfacing with the devices defined by that configuration. The CUWB Engine is responsible for managing Anchors and Tags: scheduling UWB transmission, synchronizing time, calculating locations, and much more.

Configuration Management

When a CUWB Engine is launched, it reads the CUWB Configuration file and schedules device transmission over UWB accordingly. It monitors the CUWB Configuration file for any changes, making adjustments to network and device parameters as indicated by the configuration file.

Scheduler

The CUWB Engine implements a scheduler that is responsible for managing the UWB transmission and receptions for all CUWB devices in a CUWB Configuration. The schedule is based on parameters provided by the user using the CUWB Manager front-end web interface. These parameters define various network behaviors such as Tag beacon rates, Anchor synchronization rate, smoothing, etc.

Time Synchronization Management

The CUWB Engine tracks the internal drift and offset of the Anchor clocks. The CUWB Engine generates a common network time that is utilized by each device to schedule transmissions and receptions. Network time is used for precision time stamping of events and is used by the CUWB Engine for Tag localization.

Localization

The CUWB Engine is responsible for collecting timestamps for all UWB transmissions and receptions defined by a CUWB configuration. UWB receive time and transmit timestamps are converted to the common network time and are used by the CUWB Engine for localization. Depending on the network mode (Multi-Time or Multi-Range), the CUWB Engine calculates ranges or time differences between devices and implements an algorithm to determine XYZ location of devices based on that data.

CDP Processing

The CUWB Engine’s primary Real-Time form of communication is CDP (Ciholas Data Protocol) over UDP/IP. The CUWB Engine has three main streams of CDP traffic and three user optional streams :

Anchor Stream: The anchor stream is for Anchor Array to send information to the CUWB Engine.
User Stream: The user stream is utilized by support applications to track configuration status, position information, and sensor information (if available).
Config Stream: The config stream is utilized to bring new devices online.
Command Stream: This optional stream is utilized by the CUWB Engine to send multicast commands to UWB devices.
Debug Stream: This optional stream is utilized by the Anchor array to send to Ethernet debug packets and statistics.
Data to Device Stream: This optional stream accepts commands from external applications bound for CUWB tags / anchors.

CUWB Firmware

Each device in a CUWB Configuration utilizes CUWB Firmware. The firmware has limited default behaviors, along with configurable applications that help the devices fulfill their roles within a CUWB Configuration.

The CUWB Engine provides a list of commands to each device upon joining a CUWB Configuration. These commands determine how the device will interact, when it will receive and transmit, what sensors it will use, and other behaviors like Wake-on-Shake.

UWB Communications Search

All devices, even Ethernet connected devices, listen for UWB traffic periodically when they are not configured to be in a CUWBNet. Once a device is able to detect and lock into a CUWBNet, a UWB packet is sent to join the device to the CUWBNet. The CUWB Engine gives each device their commands, allowing the device to behave according to the CUWB Configuration.

Command Processing / Applications

Each CUWB device handles commands from the CUWB Engine. The firmware has separate applications to handle each command. The applications can do any number of tasks, such as setup sensors, drive LEDs, or schedule events in the UWB stack to cause transmissions and receptions to occur.

Ethernet Devices

CUWB devices with Ethernet connectivity can serve as Anchors. After devices establish an Ethernet link, they send discovery CDP packets on the Config Stream. The CUWB Engine utilizes these discovery packets to detect new devices and send them commands.

Support Applications

User Applications

Customers often run their own applications to log, monitor, and control CUWBNets. These applications have access to position data, sensor data (if available), and user data.

CDP processing from the User Stream is the most common connection. Some applications utilize the API to dynamically change configuration and device settings. Additionally, some applications send CDP to a CUWBNet using the Data to Device Stream.

CUWB Viewer

CUWB Viewer provides a user interface displaying the locations of CUWBNet devices, such as anchors and tags in real time. The CUWB Viewer also presents basic system information, such as device status, statistics, sensor plotting, and more.

CUWB Viewer also gives users the ability to import objects and create 3D environments replicating the physical space of a CUWBNet. Additional information can be found in the CUWB Viewer Manual.

The CUWB Viewer listens to the User Stream.

CDP Logger / Player

The CDP Logger records data from the CDP Streams. The player can playback the logged data in a time synchronized fashion. The logger and player are useful in debugging and development. Additional information can be found in the CDP Logger Manual.

System Interface

Data Hooks

The Ciholas Data Protocol (CDP) provides a method of communication between devices and services. CDP data is transmitted over ethernet as User Datagram Protocol (UDP) packets. Ciholas Real-Time Location Systems (RTLS) emit position data using the CDP format as an accessible way for users to gain access to the data and integrate their software. CDP packets are transmitted through CDP Streams. CDP Streams are identified by the Ethernet interface, IP address, and Port through which the packet is sent. Streams are allowed to be both multicast and unicast. Different CDP Streams may be defined to distinguish different categories or classes of data.

The CUWB RTLS supports using Ciholas Data Protocol (CDP) over a User Datagram Protocol (UDP) connection. The CDP packet definitions are available under Ciholas Data Protocol.

Position Delivery

Allows Tags to receive their own locations while participating in a CUWBNet.

Position delivery uses additional airtime in the schedule. Using position delivery with high speed UWB networks or large, dense networks will cause less tags to be supported in the schedule.

For examples on how to use CDP, see Using CDP Application Note and Position Delivery Application Note.

Control Hooks

The CUWB RTLS has an RESTful API available for use. This API configures all of the resource units required to facilitate the creation, configuration, and deletion of CUWB Networks within the CUWB RTLS platform. Users have the option of creating their own control mechanisms utilizing this API. The expected response formats are also provided for success, failure, and error scenarios.

The CUWB RTLS API is available under CUWB Manager - API Control

User Data

A CUWBNet can be configured to allow Tags to send additional data (User Data) along with beacons. The Tags are configured to send this data over time, using fragmentation, to reduce the air traffic required to support this additional data. CUWB Engine collects and reassembles the fragmented data. Upon full reassembly the CUWB Engine emits a CDP Data Item on the External Stream with the contents of the additional data.

End to End Communication using User Data

User data can be used to send data from a tag through the CUWB RTLS to a user application and vice versa.

End-to-End Communication (E2E) uses additional airtime in the schedule. Using E2E with high speed UWB networks or large, dense networks will cause less tags to be supported in the schedule.

SNMP Support

Ciholas is working to provide SNMP support for Enterprise level customers. Keep an eye out for additional SNMP announcements.