• CUWB v5.0
CDP Logger Manual

Overview

The CDP Logger is a tool for the Ciholas Ultra-Wideband (CUWB) Real-Time Location System (RTLS). It provides a method to record all data streams from the CUWB Manager. Recordings can then be played back using the CDP Player with the same timing as when the data was logged. This allows users to record and replay system data for testing and debugging the CUWB RTLS.

Features

The CDP Logger allows a user to setup log rotation. By default, the CDP Logger logs all CUWB CDP data in a single file indefinitely. The log rotation feature allows users to split datasets into smaller files.

The logs that are captured by the CDP Logger can be played back using the CDP player. The player emits logged CDP packets over the selected network settings with the same timing at which the data was logged.

Installation

Host PC Requirements

  • OS: Ubuntu 22.04 Jammy or Ubuntu 24.04 Noble
  • CPU: 64-bit, 2.5GHz, dual-core or better
  • WAN: Must be able to reach ppa.cuwb.io via port 4431
  • Network: Two NICs or VLANs — one for the User Network and one for the isolated Anchor Network
  • RAM: 8 GB or more
  • HD: 32 GB or more2

1. Only required for online installation.
2. Additional space may be required for CDP logging depending on the size of the CUWBNet and desired amount of history being kept in logs.

The CDP Logger may be installed on the same Host PC running the rest of the CUWB Software Package.

Online Installation

Follow the instructions below for CDP Logger installation. When prompted in the “CUWB Applications Selection”, ensure that CDP Logger is selected for installation.

Note: The CDP Player is bundled with the CDP Logger, both tools are installed as a part of the CDP Logger package.

  1. Follow best practices and review the install.sh script.
  2. bash <(wget -qO- https://cuwb.io/docs/v5.0/assets/install.sh)
  3. Paste into an Ubuntu 22.04/24.04 terminal and press Enter

Offline Installation

The CDP Logger can be installed on Host PCs that do not have PPA access.

For instructions on how to obtain the DEB package, see Current Downloads Available for Software Packages. After downloading the package, transfer the DEB to a USB drive or other transfer method to the Host PC. After transferring the file, navigate to the file location, and type the command below into a terminal window to install the package:

sudo apt install ./cdp-logger_<version>_amd64.deb

Note: The CDP Player is bundled with the CDP Logger, both tools are installed as a part of the CDP Logger package.

CDP Logger

Once the CDP Logger has been installed, launch the application by typing cdp-logger into a terminal window with any options below.

CDP Logger Command Line Options

The command line options supported by the system are as follows:

Option Parameters Arguments Description
Debug -d, --debug none Activates debug mode.
File -f, --file name_of_file File where the CDP packets will be logged. If this option is not provided, it will default to cdp-log-\<date\>.00.
Help -h, --help none Prints the help message.
Interface Address -i, --iface iface_addr Log will be recorded on network interface with the specified IP address.
Max File Size -m --max_size max_size The max size, in megabytes, a log can be before splitting and logging to a new file.
Rotating Files -r, --rotate number_of_files The logger will rotate through the specified number of log files, moving to the next after each split.
Split Hours --splithours number_of_hours How often, in hours, to split and log to a new file. Value can be entered as decimal.
UDP Stream -u udp_stream Packets will be recorded from the specified UDP stream (ip:port). Default value is 239.255.76.67:7667.
Version --version none Print the version.
Zip -z --zip none Used in conjunction with other arguments that split logs. Whenever logging begins on a new file, the previous one is compressed.

Network Configuration

By default, the CDP Logger will log all incoming CDP data on the following network settings:

Parameter Value
IP 239.255.76.67
port 7667
interface 0.0.0.0

To change network settings, use the UDP Stream command-line option (-u) to set the IP address and port; use the Interface Address command-line option (-i) to set the network interface. For example, the following command sets the CDP Logger to log data on IP = 239.255.76.66, port = 7665, and interface = 127.0.0.1 (localhost):

cdp-logger -u 239.255.76.66:7665 -i 127.0.0.1

Controlling the Logger

Stop / Start

Upon start up, the application prints the Interface Address, the UDP stream it is monitoring, and the designated log file path. To successfully capture a CDP log from a CUWBNet data stream, the Interface Address must align with the interface configured in the CUWB Manager. Similarly, the UDP stream settings must exactly match the IP:Port configuration specified within the Manager for that particular stream.

To conclude a logging session and ensure data is properly saved, stop the CDP Logger by pressing CTRL + C within the terminal.

Log Naming

By default, the CDP Logger saves data to a file named cdp-log-\<date\>.00. You can define a custom filename or specific directory file path using the -f option (e.g., ~/Documents/my-log.00). The Logger automatically appends a minimum two-digit numeric suffix to the filename; this ensures that even if the same filename if reused, the application will generate a unique file rather than overwriting previous data.

Log Rotation

By default, log rotation is disabled, causing the CDP Logger to record all incoming data into a single file that grows indefinitely. To manage file sizes, you can configure rotation using the Rotating Files option (-r) to set the maximum number of files to maintain, and the Split Hours option (–splithours) to define the duration of each log segment. For example, the following command configures the Logger to rotate through a pool of 100 files, with each file capturing 15 minutes of data:

cdp-logger -r 100 --splithours 0.25

Log rotation can also be paired with the Max File Size option. The following command will set up the CDP logger such that the total size of the logs does not exceed 10GB, while each individual log is not greater than 1GB:

cdp-logger -r 10 -m 1024

Note: When log rotation is enabled, the system will begin overwriting the oldest log files once the limit specified by the Rotating Files option is reached. For instance, if you configure 100 log files at 15 minutes each, the oldest data will be replaced after 25 hours of continuous logging. Similarly, if the Logger is set to rotate through 10 files with a 1 GB size limit, the oldest file will be overwritten once the total logged data exceeds 10 GB.

Advanced Logging

Using the Linux command nohup, the cdp-logger process can be executed in the background. This approach facilitates the creation of a more complex logging system capable of capturing extensive data across the CUWBNet simultaneously. For example, consider a CUWBNet configured with the following Ethernet settings:

Stream Name UDP Stream Interface Address
Config 239.255.76.67:7671 169.254.100.100
Anchor 239.255.76.66:5858 169.254.100.100
User 239.255.76.66:9000 127.0.0.1

The following commands will capture logs of both their Anchor stream and User stream at the same time storing the data inside of anchor.log.00 and user.log.00 respectively:

nohup cdp-logger -u 239.255.76.66:5858 -i 169.254.100.100 -f anchor.log &
nohup cdp-logger -u 239.255.76.66:9000 -i 127.0.0.1 -f user.log &

Once logging has been completed, the command killall cdp-logger can be used to stop all the cdp-loggers at the same time.

Note: If performing an advanced logging task it is highly encouraged to use the -f flag to help with organizing the resulting logs.

CDP Player

Once a log file has been captured using the CDP Logger, the CDP Player can be used to replay the data. The player emits the recorded CDP packets over the selected network settings, strictly maintaining the original timing captured during the logging process. To launch the application, enter cdp-player into the command line followed by any of the configuration options listed below.

CDP Player Command Line Options

The command line options supported by the system are as follows:

Option Parameters Arguments Description
Debug -d, --debug none Activates debug mode.
End Time --end end_time The cdp-player will end playback at end_time seconds.
File -f, --file name_of_file Log file containing CDP data that will be played back. If this option is not provided, it will default to default.log
Help -h, --help none Prints the help message.
Interface Address -i, --iface iface_addr Log will be played on network interface with the specified IP address.
Loop -l, --loop none Replay continuously in a loop until the player is terminated.
Speed -s, --speed speed_multiplier Speed to play back the log (default is 1x). Can be a decimal number.
Start Time --start start_time The cdp-player will start playback at start_time seconds through the log.
UDP Stream -u udp_stream Packets will be played from the specified UDP stream (ip:port)
Default value is - 239.255.76.67:7667
Version --version none Print the version.

Network Configuration

By default, the CDP player replays all recorded CDP data using the following network settings:

Parameter Value
IP 239.255.76.67
port 7667
interface 0.0.0.0

To modify the network settings, use the UDP Stream command-line option (-u) to define the IP address and port, and the Interface Address option (-i) to specify the network interface. For example, the following command configures the CDP Player to broadcast data to IP = 239.255.76.66, port = 7665, and interface = 127.0.0.1 (localhost):

cdp-player -u 239.255.76.66:7665 -i 127.0.0.1

Controlling the Player

Stop / Start

Upon startup, the application prints the UDP stream target and the name of the log file being played. When replaying data for another program, ensure the player’s UDP stream aligns with the destination’s listening settings. You may also need the -i flag to specify the correct network interface for transmission. The CDP Player terminates automatically upon reaching the end of the log file. It can be manually stopped at any time by pressing CTRL+C in the terminal. Note that when using the loop option (-l), the player will repeat indefinitely, making CTRL+C the only method to end the process.

Choosing a Log to Play

By default, the CDP Player searches for a file named default.log. To play a specific file, use the -f option followed by the filename or full directory path (e.g, ~/Documents/my-log.00).

Playing a Portion of a Log

You can isolate specific segments of a log using the --start and --end options, which accept values in seconds. For example, if a one-hour log contains relevant data only between the 20-minute and 35-minute marks, the following command will play only that 15-minute window:

cdp-player --start 1200 --end 2100

Use with CUWB Viewer

CDP Playback is fully compatible with the CUWB Viewer. To view the data:

  1. Open network settings in the CUWB Viewer
  2. Configure the Viewer to listen to the specific IP address and Port used by the CDP player
  3. Start the playback; the viewer will render the movements and data exactly as it would for a live CUWBNet.

Revision

Version Date Change Description
v5.0.1 2025-11-14 Updating Host PC Requirements
v5.0.0 2025-10-31 Initial Preliminary Release

APPENDIX A : License Terms and Conditions


APPENDIX B : Software License Attributions