GDK UltrasonicRadar API Reference (C++)¶

Overview¶

The UltrasonicRadar module provides the G02 robot with the ability to acquire real-time ultrasonic radar data. Through the C++ interface, developers can conveniently obtain the robot's obstacle detection data, suitable for scenarios such as obstacle avoidance, navigation, safety detection, and close-range obstacle perception.

Interface Description¶

UltrasonicRadar Class¶

This class encapsulates the main data acquisition interfaces of the ultrasonic radar sensor.

1. `GetLatestUltrasonicRadar()`¶

Function: Get the latest ultrasonic radar data
Parameters:

Parameter	Type	Description
`ultrasonic_radar`	`std::shared_ptr<UltrasonicRadars>&`	Output parameter, ultrasonic radar data pointer

Return value: GDKRes, the operation result status code. Returns GDKRes::kSuccess on success, and the ultrasonic_radar parameter contains the ultrasonic radar data

Detailed Description of the UltrasonicRadars Object¶

The UltrasonicRadars struct contains the following members:

Member	Type	Description	Unit
`timestamp_ns`	`uint64_t`	Timestamp of ultrasonic radar data acquisition (chassis sensor timestamp)	nanoseconds
`ultrasonic_radar_datas`	`std::vector<UltrasonicRadarData>`	List of ultrasonic radar data	None

struct UltrasonicRadars{
  uint64_t timestamp_ns{0};  ///< timestamp in nanoseconds
  std::vector<UltrasonicRadarData> ultrasonic_radar_datas;  ///< ultrasonic radar datas
};

ultrasonic_radar_datas (Radar Data List):

Each UltrasonicRadarData contains the following attributes:

Member	Type	Description	Unit
`id`	`uint32_t`	Ultrasonic radar ID	None
`distance_mm`	`uint32_t`	Detected distance	millimeters
`fault_state`	`uint8_t`	Fault state (0 indicates normal, non-zero indicates a fault)	None

struct UltrasonicRadarData {
  uint32_t id{};           ///< ultrasonic_radar_id
  uint32_t distance_mm{};  ///< distance in millimeters
  uint8_t fault_state{};  ///< fault state
};

Example:

#include <iostream>
#include <chrono>
#include <thread>
#include <memory>
#include "gdk/gdk.h"

int main() {
    // Initialize the GDK system
    if (agibot::gdk::GDKInit() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK initialization failed" << std::endl;
        return -1;
    }
    std::cout << "GDK initialization succeeded" << std::endl;

    agibot::gdk::UltrasonicRadar radar;
    std::this_thread::sleep_for(std::chrono::seconds(1)); // Wait 1 second to ensure the DDS connection is established

    std::shared_ptr<agibot::gdk::UltrasonicRadars> ultrasonic_radar;
    auto res = radar.GetLatestUltrasonicRadar(ultrasonic_radar);

    if (res == agibot::gdk::GDKRes::kSuccess && ultrasonic_radar != nullptr) {
        std::cout << "✅ Timestamp: " << ultrasonic_radar->timestamp_ns << std::endl;
        std::cout << "Number of ultrasonic radars: " << ultrasonic_radar->ultrasonic_radar_datas.size() << std::endl;

        for (const auto& data : ultrasonic_radar->ultrasonic_radar_datas) {
            std::cout << "  Radar[" << data.id << "]: "
                      << "Distance=" << data.distance_mm << " mm, "
                      << "Fault state=" << static_cast<int>(data.fault_state) << std::endl;
        }
    } else {
        std::cout << "No ultrasonic radar data obtained" << std::endl;
    }

    // Release GDK system resources
    if (agibot::gdk::GDKRelease() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK release failed" << std::endl;
        return -1;
    }
    std::cout << "GDK release succeeded" << std::endl;

    return 0;
}

2. `GetNearestUltrasonicRadar()`¶

Function: Get the ultrasonic radar data nearest to a specified timestamp
Parameters:

Parameter	Type	Description
`timestamp_ns`	`const uint64_t`	Target timestamp (nanoseconds)
`ultrasonic_radar`	`std::shared_ptr<UltrasonicRadars>&`	Output parameter, ultrasonic radar data pointer

Return value: GDKRes, the operation result status code. Returns GDKRes::kSuccess on success, and the ultrasonic_radar parameter contains the ultrasonic radar data
Example:

#include <iostream>
#include <chrono>
#include <thread>
#include <memory>
#include "gdk/gdk.h"

int main() {
    // Initialize the GDK system
    if (agibot::gdk::GDKInit() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK initialization failed" << std::endl;
        return -1;
    }
    std::cout << "GDK initialization succeeded" << std::endl;

    agibot::gdk::UltrasonicRadar radar;
    std::this_thread::sleep_for(std::chrono::seconds(1)); // Wait 1 second to ensure the DDS connection is established

    // First get the latest data
    std::shared_ptr<agibot::gdk::UltrasonicRadars> latest_radar;
    radar.GetLatestUltrasonicRadar(latest_radar);

    if (latest_radar != nullptr) {
        std::cout << "✅ Latest data timestamp: " << latest_radar->timestamp_ns << std::endl;

        // Find the nearest data (1 second earlier)
        std::shared_ptr<agibot::gdk::UltrasonicRadars> nearest_radar;
        agibot::gdk::GDKRes res = radar.GetNearestUltrasonicRadar(
            latest_radar->timestamp_ns - 1000000000LL, // 1 second earlier
            nearest_radar
        );
        if (res == agibot::gdk::GDKRes::kSuccess && nearest_radar != nullptr) {
            std::cout << "✅ Nearest data timestamp: " << nearest_radar->timestamp_ns << std::endl;
            std::cout << "Time difference: " << (nearest_radar->timestamp_ns > latest_radar->timestamp_ns - 1000000000LL ?
                                          nearest_radar->timestamp_ns - (latest_radar->timestamp_ns - 1000000000LL) :
                                          (latest_radar->timestamp_ns - 1000000000LL) - nearest_radar->timestamp_ns)
                      << " ns" << std::endl;
            std::cout << "Number of ultrasonic radars: " << nearest_radar->ultrasonic_radar_datas.size() << std::endl;
        } else {
            std::cout << "❌ Nearest ultrasonic radar data not found" << std::endl;
        }
    } else {
        std::cout << "No ultrasonic radar data obtained" << std::endl;
    }

    // Release GDK system resources
    if (agibot::gdk::GDKRelease() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK release failed" << std::endl;
        return -1;
    }
    std::cout << "GDK release succeeded" << std::endl;

    return 0;
}

3. `GetUltrasonicRadarFps()`¶

Function: Get the ultrasonic radar data acquisition frame rate
Parameters:

Parameter	Type	Description
`fps`	`float&`	Output parameter, ultrasonic radar frame rate (FPS)

Return value: GDKRes, the operation result status code. Returns GDKRes::kSuccess on success, and the fps parameter contains the frame rate value
Example:

#include <iostream>
#include <chrono>
#include <thread>
#include "gdk/gdk.h"

int main() {
    // Initialize the GDK system
    if (agibot::gdk::GDKInit() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK initialization failed" << std::endl;
        return -1;
    }
    std::cout << "GDK initialization succeeded" << std::endl;

    agibot::gdk::UltrasonicRadar radar;
    std::this_thread::sleep_for(std::chrono::seconds(2)); // Wait 2 seconds to let data accumulate

    float fps;
    if (radar.GetUltrasonicRadarFps(fps) != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "Failed to get frame rate" << std::endl;
    } else {
        std::cout << "Ultrasonic radar frame rate: " << fps << " fps" << std::endl;
    }

    // Release GDK system resources
    if (agibot::gdk::GDKRelease() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK release failed" << std::endl;
        return -1;
    }
    std::cout << "GDK release succeeded" << std::endl;

    return 0;
}

4. `GetUltrasonicRadarLatency()`¶

Function: Get ultrasonic radar data latency statistics
Parameters:

Parameter	Type	Description
`window_seconds`	`const float`	Statistics window duration (seconds)
`latency`	`LatencyStats&`	Output parameter, latency statistics

Return value: GDKRes, the operation result status code. Returns GDKRes::kSuccess on success, and the latency parameter contains the latency statistics
LatencyStats Struct Description:

struct LatencyStats {
  double max_latency_ms{0.0};    ///< max latency(ms)
  double avg_latency_ms{0.0};    ///< average latency(ms)
  double p99_latency_ms{0.0};    ///< 99th percentile latency(ms)
  double p999_latency_ms{0.0};   ///< 99.9th percentile latency(ms)
  double p9999_latency_ms{0.0};  ///< 99.99th percentile latency(ms)
};

Member	Type	Description	Unit
`max_latency_ms`	`double`	Maximum latency	milliseconds
`avg_latency_ms`	`double`	Average latency	milliseconds
`p99_latency_ms`	`double`	99^th percentile latency	milliseconds
`p999_latency_ms`	`double`	99.9^th percentile latency	milliseconds
`p9999_latency_ms`	`double`	99.99^th percentile latency	milliseconds

Example:

#include <iostream>
#include <chrono>
#include <thread>
#include "gdk/gdk.h"

int main() {
    // Initialize the GDK system
    if (agibot::gdk::GDKInit() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK initialization failed" << std::endl;
        return -1;
    }
    std::cout << "GDK initialization succeeded" << std::endl;

    agibot::gdk::UltrasonicRadar radar;
    std::this_thread::sleep_for(std::chrono::seconds(1)); // Wait 1 second to ensure the DDS connection is established

    // Wait for a while to collect data
    std::this_thread::sleep_for(std::chrono::seconds(10));

    agibot::gdk::LatencyStats latency;
    if (radar.GetUltrasonicRadarLatency(10.0, latency) != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "Failed to get latency statistics" << std::endl;
    } else {
        std::cout << "Ultrasonic radar latency statistics:" << std::endl;
        std::cout << "  Maximum latency: " << latency.max_latency_ms << "ms" << std::endl;
        std::cout << "  Average latency: " << latency.avg_latency_ms << "ms" << std::endl;
        std::cout << "  P99 latency: " << latency.p99_latency_ms << "ms" << std::endl;
        std::cout << "  P99.9 latency: " << latency.p999_latency_ms << "ms" << std::endl;
        std::cout << "  P99.99 latency: " << latency.p9999_latency_ms << "ms" << std::endl;
    }

    // Release GDK system resources
    if (agibot::gdk::GDKRelease() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK release failed" << std::endl;
        return -1;
    }
    std::cout << "GDK release succeeded" << std::endl;

    return 0;
}

5. `Close()`¶

Function: Close the ultrasonic radar DDS connection
Parameters: None
Return value: GDKRes, the operation result status code. Returns GDKRes::kSuccess on success
Example:

#include <iostream>
#include <chrono>
#include <thread>
#include "gdk/gdk.h"

int main() {
    // Initialize the GDK system
    if (agibot::gdk::GDKInit() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK initialization failed" << std::endl;
        return -1;
    }
    std::cout << "GDK initialization succeeded" << std::endl;

    agibot::gdk::UltrasonicRadar radar;
    std::cout << "UltrasonicRadar init" << std::endl;

    // Use the ultrasonic radar...

    // Close the ultrasonic radar
    if (radar.Close() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "Failed to close the ultrasonic radar" << std::endl;
    } else {
        std::cout << "Ultrasonic radar closed successfully" << std::endl;
    }

    // Release GDK system resources
    if (agibot::gdk::GDKRelease() != agibot::gdk::GDKRes::kSuccess) {
        std::cout << "GDK release failed" << std::endl;
        return -1;
    }
    std::cout << "GDK release succeeded" << std::endl;

    return 0;
}

Usage Notes¶

GDK Initialization: Before using UltrasonicRadar functionality, you must first call agibot::gdk::GDKInit() to initialize the GDK system
GDK Release: Before the program ends, you must call agibot::gdk::GDKRelease() to release the GDK system resources
Initialization Wait: After creating the UltrasonicRadar object, it is recommended to wait 1 second to ensure the DDS connection is established
Return Value Check: Before use, check whether the GDKRes return value is kSuccess
Smart Pointer Management: The UltrasonicRadars object is managed using shared_ptr; pay attention to its lifecycle
Timestamp Precision: The timestamp unit is nanoseconds and is the chassis sensor's timestamp, which can be used for precise time synchronization
Distance Unit: The distance unit is millimeters (mm); pay attention to unit conversion when using it
Fault State: fault_state of 0 indicates normal, a non-zero value indicates a fault; check it when using
Data Acquisition: GetLatestUltrasonicRadar() returns the current latest data; if there is no new data, it may return a failure
Timestamp Lookup: GetNearestUltrasonicRadar() looks up the closest data based on the timestamp; if the timestamp is out of range, it may return a failure
Frame Rate Statistics: GetUltrasonicRadarFps() requires waiting for a while (at least 2 seconds recommended) for data to accumulate before an accurate frame rate can be obtained
Latency Statistics: GetUltrasonicRadarLatency() requires waiting for a while (at least 10 seconds recommended) for data to accumulate before accurate statistics can be obtained
Resource Release: After use, call Close() to release resources
Error Handling: Always check the GDKRes return value to ensure the operation succeeded

Application Scenarios¶

Obstacle Avoidance Detection: Detect obstacles around the robot in real time for obstacle avoidance decisions
Close-Range Perception: Detect close-range obstacles to supplement the blind spots of LiDAR
Safety Detection: Monitor the safety zone around the robot to prevent collisions
Navigation Assistance: Provide close-range obstacle information for robot navigation
Parking Assistance: Assist the robot with precise parking and positioning
Low-Speed Navigation: Provide reliable obstacle detection during low-speed movement
Multi-Sensor Fusion: Fuse data with other sensors (such as LiDAR and cameras) to improve perception accuracy
Safety Zone Monitoring: Monitor the safety zone around the robot to ensure safe operation
Obstacle Classification: Combine distance information for obstacle classification and recognition
Path Planning: Plan safe paths based on ultrasonic radar data