ROS2 Parameter Demo - Workflow Components

This project contains a ROS2-based ultrasonic data acquisition and processing system for Evo hardware, with real-time visualization and parameter control.

Overview

The system consists of three main ROS2 nodes that work together:

1. Publisher Node (publisher.py) - Interfaces with Evo hardware to acquire ultrasonic A-scan data
2. Processor Node (processor.py) - Processes raw A-scan data and displays real-time visualizations
3. Controller Node (controller.py) - Provides a GUI for monitoring and controlling system parameters

Architecture

┌─────────────────┐      Ascan Message      ┌─────────────────┐
│                 │ ──────────────────────> │                 │
│    Publisher    │                         │    Processor    │
│  (Hardware I/O) │                         │ (Visualization) │
└─────────────────┘                         └─────────────────┘
         ↑                                           ↑
         │                                           │
         │          ROS2 Parameters                  │
         └───────────────────┬───────────────────────┘
                             │
                    ┌────────────────┐
                    │   Controller   │
                    │     (GUI)      │
                    └────────────────┘

Components

Publisher Node (ascan_publisher)

Purpose: Interfaces with Evo ultrasonic hardware to acquire A-scan waveform data from up to 2 channels.

The publisher does not include code on temperature gathering. You should implement your own temperature aquisition code, and there is a segment in the code where you can do this.

Parameters:

• numAverages (int, 1-1000): Number of waveform averages used by the publisher for each published A-scan. The calibration flow temporarily modifies this value to improve SNR during collection.
• numChannels (int, 1-2): Number of active channels (1 or 2)
• numCycles (int, 1-3): Number of excitation cycles (read-only)
• numSamples (int): Number of samples to record (read-only)
• signalFrequency (int): EMAT signal frequency in Hz

Published Topics:

• /ascan (interfaces/msg/Ascan): Contains active channels, encoded waveform data, and temperature

Processor Node (ascan_processor)

Purpose: Processes raw A-scan data and provides real-time visualization with automatic peak detection.

Key Features:

• Real-time matplotlib-based visualization for active channels
• Automatic subplot arrangement based on number of active channels
• Peak detection and thickness calculation
• Multiple processing modes (first peak, multi-echo, zero crossing)
• Temperature-corrected measurements

Parameters (per channel, ch1-ch2):

• ch{N}_sampling_frequency (int): Sampling frequency in Hz
• ch{N}_lowbound_time (int): Lower bound time in microseconds
• ch{N}_minimum_thickness (float): Minimum detectable thickness in mm
• ch{N}_wave_velocity (float): Wave velocity in m/s
• ch{N}_num_cycles (float): Number of cycles for processing
• ch{N}_signal_frequency (int): Signal frequency in Hz
• ch{N}_threshold_snr (float): SNR threshold in dB
• ch{N}_noise_width (int): Noise calculation window width
• ch{N}_calibration_index (int): Calibration reference index
• ch{N}_firstPeak (bool): Enable first peak detection mode
• ch{N}_multiEcho (bool): Enable multi-echo mode
• ch{N}_zeroCrossing (bool): Enable zero crossing detection
• ch{N}_temperatureCorrected (bool): Enable temperature correction
• ch{N}_rectified (bool): Plot rectified/hilbert envelope instead of raw/full-wave
• ch{N}_fullWave (bool): Plot full band-passed waveform

Subscribed Topics:

• /ascan (interfaces/msg/Ascan): Receives waveform data from publisher

Controller Node (parameter_manager_gui)

Purpose: Provides a PyQt5-based GUI for real-time parameter monitoring and control.

Key Features:

• Automatic discovery of ROS2 nodes and their parameters
• Tabbed interface with separate tabs for each active channel
• Parameter filtering based on configuration file
• Support for various parameter types (sliders, spinboxes, checkboxes)
• Real-time parameter updates with visual feedback
• Configurable display names and parameter bounds

Configuration (config.json):

• multipleTabs: Enable/disable tabbed interface
• whitelist: Enable parameter whitelisting
• hideReadOnlyParameters: Hide read-only parameters
• whitelistNodes: List of nodes to display
• whitelistParameters: Parameters to show per node
• parameterDisplayNames: Custom display names for parameters
• parameter_bounds: Min/max bounds for numeric parameters

Channel Numbering

The system uses 1-based channel numbering (1-2) for parameter names and user-facing labels.

• Channel parameters are named ch1_* through ch2_*.
• The publisher's channelsOnReceive parameter is an integer array indexed 0..N-1 (internal representation). The controller and processor map this to 1-based channel IDs for display and parameter naming.
• The Ascan message uses zero-based indices in active_channels (0..), but the GUI/parameter names use 1-based channels.

Message Format

Ascan Message

int32[] active_channels   # List of active channel indices (0-based) corresponding to which entries in ascan_data are present
string[] ascan_data       # Base64-encoded waveform data for each active channel (float64 samples)
float32 temperature       # Temperature reported by the publisher (if available)
int32 signal_frequency    # EMAT pulser frequency

Dependencies

• ROS2 Humble or later (tested on Jazzy) (Desktop Variant is required for processor and controller)
• Evo ultrasonic system (for publisher)

Installation

1. Under the project root folder, run

cd drivers
sudo ./sonobotics_runtime_<version&architecture>.deb
sudo ./sonobotics_waveforms_<version&architecture>.deb
tar -xvf pololu-jrk-g2-1.4.0-linux-x86.tar.xz
cd pololu-jrk-g2-1.4.0-linux-x86
sudo ./install.sh

2. Once drivers have been installed, run

colcon build

to build all the packages.

Usage

Starting the System

1. Launch the publisher node (requires Evo hardware):

ros2 run ros_parameter_demo publisher

2. Launch the processor node for visualization:

ros2 run ros_parameter_demo processor

3. Launch the controller GUI:

ros2 run ros_parameter_demo controller

Configuring Channels

To enable specific receive channels, modify the numChannels parameter in the publisher file.

Processing Modes

Each channel can operate in different processing modes:

• First Peak: Detects the first significant peak in the waveform
• Multi-Echo: Processes multiple reflections
• Zero Crossing: Uses zero-crossing detection for improved accuracy
• Temperature Corrected: Applies temperature compensation to measurements

Note: First Peak and Multi-Echo modes are mutually exclusive.

If you set both in the controller, the processor falls back to which none of the four parameters are set.

Calibration (EvoROS)

EvoROS includes an interactive calibration workflow accessible from the Controller GUI.

Steps:

1. Open the Controller GUI (ros2 run ros_parameter_demo controller) and click Calibrate.
2. Enter the known thickness of the calibration block (mm) and press Start calibration.
3. The controller will temporarily set the publisher's numAverages to 40 to improve SNR, then collect a series of measurements (default collection target: 100 samples).
4. When collection completes the dialog shows a computed Calibrated Speed of Sound value.
5. Press Apply Speed of Sound to write the calibrated ch{N}_wave_velocity value to any node that exposes per-channel *_wave_velocity parameters (for example ascan_processor). The publisher's numAverages is restored afterwards.

Notes:

• The calibration dialog runs collection in a background subscription and attempts a best-effort restore of the original numAverages value.
• If you have a custom publisher, ensure it exposes numAverages and channelsOnReceive parameters to integrate with the controller's calibration flow.

Configuration Files

• config.json: Controller GUI configuration
• Channel parameters can be saved/loaded via ROS2 parameter services

Troubleshooting

1. No visualization appears: Ensure at least one channel is enabled in numChannels
2. Controller doesn't show parameters: Controller won't show anything until the publishing node is on. Check that nodes are running and config.json whitelist is correct.
3. Hardware errors: Verify Evo device is connected and permissions are set correctly.