• 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 the streams of data from the CUWB Manager. Recordings can then be played back with the CDP Player with the same timing as the data was logged. This allows a user to record and play back data from the system for testing and debugging the CUWB RTLS.

Features

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

The Logs that are captured by the CDP Logger can be played back with the CDP player. The player will emit logged CDP packets over the selected network settings with the same timing with 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 will be 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 will be 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 and port, and use the Interface Address command line option (-i) to set the network interface. For example, the following command will set up 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

Whenever the application is started it will print the Interface Address it is listening on, the UDP stream it is listening for, and the file it is logging to. When attempting to take a CDP log of one of the data streams of the CUWBNet the Interface Address should match the Interface specified for that stream inside the CUWB Manager and the UDP stream should match the IP:Port specified for that stream inside the CUWB Manager.

The CDP Logger can be stopped by pressing Ctrl+C inside the terminal running the logger.

Log Naming

By default the CDP Logger logs to the file cdp-log-\<date\>.00. With the -f option a specific name can be given to the log file. This option includes the ability to specify a filepath for the log to be stored at for example, ~/Documents/my-log.00. The logger will automatically append a 2 digit minimum number to the end of every log. This allows for the same filename to be provided multiple times and still result in unique log files.

Log Rotation

By default, log rotation is disabled in the CDP logger, so the CDP logger will log all incoming CDP data in a single file that will grow indefinitely. In order to change the log rotation settings, use the Rotating Files command line option (-r) to set the number of files to rotate through, and use the Split Hours command line option (–splithours) to set the amount of time to log data in each file. For example, the following command will set up the CDP logger to rotate through 100 files with each file containing 15 minutes worth 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: With log rotation enabled, old log files will start being overwrote by new log files when the number of files specified in the Rotating Files command line option has been reached. In the first example of 100 log files each storing 15 minutes of data, the oldest log file will start being replaced after 25 hours of logging. In the second example of 10 log files each storing no more than 1GB of data, the oldest log file will start being replaced after 10GB of data has been logged.

Advanced Logging

Using the Linux command nohup a cdp-logger process can be started in the background. This can allow for the creation of a more complex logging system that captures more of the data of the CUWB System. For example, given the following Ethernet Settings for a CUWBNet:

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 play the log back. The player will emit the logged CDP packets over the selected network settings with the same timing with which the data was logged. The CDP Player can be launched by typing cdp-player into the command line with any options 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 will playback all incoming CDP data from 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 and port, and use the Interface Address command line option (-i) to set the network interface. For example, the following command will set up the CDP player to play data on 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

Whenever the application is started it will print the UDP stream it is listening for and the name of the file it is playing. When attempting to play the log to another program the UDP stream should match the UDP stream the other program is listening for. You may also need to use the -i flag to set the interface the player will use.

The CDP Player will stop automatically once it reaches the end of the log file. It can also be stopped at any time by pressing Ctrl+C in the terminal running the player. When using the -l option, Ctrl+C is the only way to stop the player.

Choosing a Log to Play

By default, the CDP Player attempts to play the log default.log. With the -f option a specific log can be played instead. This option includes the ability to specify the filepath the desired log is stored at for example, ~/Documents/my-log.00.

Playing a Portion of a Log

Using the --start and --end options, playback of only a portion of a log is possible. If for example, the default log contained an hour worth of data, but the only interesting portion occurs between the 20 minute and 35 minute mark then the following example would play only that 15 minute span of time.

cdp-player --start 1200 --end 2100

Use with CUWB Viewer

CDP Log playback is compatible with the CUWB Viewer. The CUWB Viewer should be configured to listen to the CDP Player IP and port through the Viewer’s Network Settings. Once that is complete, playback the stream from the CDP Player and the CUWB Viewer will display the data just like a live network.

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