GDK UltrasonicRadar Interface Documentation (Python)¶

Overview¶

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

Interface Description¶

UltrasonicRadar Class¶

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

1. `get_latest_ultrasonic_radar()`¶

Function: Get the latest ultrasonic radar data
Parameters: None
Return value: dict, a dictionary containing ultrasonic radar data; throws an exception on failure

Return value dictionary structure:

Key	Type	Description	Unit
`timestamp_ns`	`int`	Timestamp (chassis sensor timestamp)	nanoseconds
`ultrasonic_radar_datas`	`list[dict]`	List of ultrasonic radar data	unitless

Fields of each dict in the ultrasonic_radar_datas list:

Key	Type	Description	Unit
`id`	`int`	Ultrasonic radar ID	none
`distance_mm`	`int`	Detected distance	millimeters
`fault_state`	`int`	Fault state (0 means normal, non-zero indicates a fault)	none

Example:

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

radar = agibot_gdk.UltrasonicRadar()
time.sleep(1)  # Wait 1 second to ensure the DDS connection is established

# Get the latest data
radar_data = radar.get_latest_ultrasonic_radar()

print(f"✅ Timestamp: {radar_data['timestamp_ns']} ns")
print(f"Number of ultrasonic radars: {len(radar_data['ultrasonic_radar_datas'])}")

for data in radar_data['ultrasonic_radar_datas']:
    print(f"  Radar[{data['id']}]: "
          f"distance={data['distance_mm']} mm, "
          f"fault state={data['fault_state']}")

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

2. `get_nearest_ultrasonic_radar()`¶

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

Parameter	Type	Description
`timestamp_ns`	`int`	Target timestamp (nanoseconds)

Return value: dict, a dictionary containing ultrasonic radar data; throws an exception on failure

Return value dictionary structure:

Key	Type	Description	Unit
`timestamp_ns`	`int`	Timestamp (chassis sensor timestamp)	nanoseconds
`ultrasonic_radar_datas`	`list[dict]`	List of ultrasonic radar data	unitless

Fields of each dict in the ultrasonic_radar_datas list:

Key	Type	Description	Unit
`distance_mm`	`int`	Detected distance	millimeters
`fault_state`	`int`	Fault state (0 means normal, non-zero indicates a fault)	none

Note: The radar data dictionary returned by get_nearest_ultrasonic_radar() does not include the id field.

Example:

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

radar = agibot_gdk.UltrasonicRadar()
time.sleep(1)  # Wait 1 second to ensure the DDS connection is established

# First get the latest data
latest_data = radar.get_latest_ultrasonic_radar()
print(f"✅ Latest data timestamp: {latest_data['timestamp_ns']} ns")

# Find the nearest data (1 second earlier)
target_timestamp = latest_data['timestamp_ns'] - 1000000000  # 1 second = 1,000,000,000 nanoseconds
nearest_data = radar.get_nearest_ultrasonic_radar(target_timestamp)

print(f"✅ Nearest data timestamp: {nearest_data['timestamp_ns']} ns")
time_diff = abs(nearest_data['timestamp_ns'] - target_timestamp)
print(f"Time difference: {time_diff} ns")
print(f"Number of ultrasonic radars: {len(nearest_data['ultrasonic_radar_datas'])}")

for i, data in enumerate(nearest_data['ultrasonic_radar_datas']):
    print(f"  Radar[{i}]: "
          f"distance={data['distance_mm']} mm, "
          f"fault state={data['fault_state']}")

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

3. `get_ultrasonic_radar_fps()`¶

Function: Get the ultrasonic radar data acquisition frame rate
Parameters: None
Return value: float, the ultrasonic radar frame rate (FPS); throws an exception on failure
Example:

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

radar = agibot_gdk.UltrasonicRadar()
time.sleep(2)  # Wait 2 seconds to let data accumulate

# Get the frame rate
fps = radar.get_ultrasonic_radar_fps()
print(f"Ultrasonic radar frame rate: {fps} fps")

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

4. `get_ultrasonic_radar_latency()`¶

Function: Get ultrasonic radar data latency statistics
Parameters:

Parameter	Type	Description
`window_seconds`	`float`	Statistics window duration (seconds), defaults to 10.0 seconds

Return value: A LatencyStats object, containing latency statistics; throws an exception on failure

LatencyStats object attributes:

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

Example:

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

radar = agibot_gdk.UltrasonicRadar()
time.sleep(1)  # Wait 1 second to ensure the DDS connection is established

# Wait a while to collect data
time.sleep(10)

# Get latency statistics
latency = radar.get_ultrasonic_radar_latency(10.0)

print("Ultrasonic radar latency statistics:")
print(f"  Max latency: {latency.max_latency_ms} ms")
print(f"  Average latency: {latency.avg_latency_ms} ms")
print(f"  P99 latency: {latency.p99_latency_ms} ms")
print(f"  P99.9 latency: {latency.p999_latency_ms} ms")
print(f"  P99.99 latency: {latency.p9999_latency_ms} ms")

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

5. `close_ultrasonic_radar()`¶

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

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

radar = agibot_gdk.UltrasonicRadar()
print("UltrasonicRadar init")

# Use the ultrasonic radar...

# Close the ultrasonic radar
if radar.close_ultrasonic_radar() != agibot_gdk.GDKRes.kSuccess:
    print("Failed to close the ultrasonic radar")
else:
    print("Ultrasonic radar closed successfully")

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

Complete Example¶

import agibot_gdk
import time

# Initialize the GDK system
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    print("GDK initialization failed")
    exit(1)
print("GDK initialized successfully")

# Create an ultrasonic radar object
radar = agibot_gdk.UltrasonicRadar()

# Wait for initialization to complete
time.sleep(1)

# Get the latest data
radar_data = radar.get_latest_ultrasonic_radar()

print("=== Ultrasonic radar data ===")
print(f"Timestamp: {radar_data['timestamp_ns']} ns")
print(f"Number of radars: {len(radar_data['ultrasonic_radar_datas'])}")

for data in radar_data['ultrasonic_radar_datas']:
    print(f"  Radar[{data['id']}]: "
          f"distance={data['distance_mm']} mm, "
          f"fault state={data['fault_state']}")

# Get the frame rate
fps = radar.get_ultrasonic_radar_fps()
print(f"Frame rate: {fps} fps")

# Get latency statistics
time.sleep(5)
latency = radar.get_ultrasonic_radar_latency(5.0)
print("Latency statistics:")
print(f"  Max latency: {latency.max_latency_ms} ms")
print(f"  Average latency: {latency.avg_latency_ms} ms")

# Close the interface
radar.close_ultrasonic_radar()

# Release GDK system resources
if agibot_gdk.gdk_release() != agibot_gdk.GDKRes.kSuccess:
    print("GDK release failed")
else:
    print("GDK released successfully")

Usage Notes¶

GDK initialization: You must call agibot_gdk.gdk_init() to initialize the GDK system before using the UltrasonicRadar functionality
GDK release: You must call agibot_gdk.gdk_release() to release GDK system resources before the program ends
Initialization wait: After creating an UltrasonicRadar object, it is recommended to wait 1 second to ensure the DDS connection is established
Exception handling: All interfaces throw an exception on failure, so it is recommended to use try-except for exception handling
Timestamp precision: The timestamp unit is nanoseconds, and it is the chassis sensor's timestamp, which can be used for precise time synchronization
Distance unit: The distance unit is millimeters (mm), so pay attention to unit conversion when using it
Fault state: fault_state of 0 means normal, a non-zero value indicates a fault, so it needs to be checked when used
Data acquisition: get_latest_ultrasonic_radar() returns the current latest data; if there is no new data, it may throw an exception
Timestamp lookup: get_nearest_ultrasonic_radar() looks up the nearest data based on the timestamp; if the timestamp is out of range, it may throw an exception
Data format difference: The radar data returned by get_latest_ultrasonic_radar() includes the id field, while the data returned by get_nearest_ultrasonic_radar() does not include the id field
Frame rate statistics: get_ultrasonic_radar_fps() requires waiting a while (at least 2 seconds recommended) for data to accumulate before an accurate frame rate can be obtained
Latency statistics: get_ultrasonic_radar_latency() requires waiting a while (at least 10 seconds recommended) for data to accumulate before accurate statistics can be obtained
Resource release: Call close_ultrasonic_radar() to release resources after use
Dictionary access: The return value is a dictionary type; use dictionary key names to access data, and pay attention to the case and spelling of the key names

Application Scenarios¶

Obstacle avoidance detection: Real-time detection of obstacles around the robot, for obstacle-avoidance decision making
Short-range perception: Detecting nearby obstacles, complementing the blind spots of lidar
Safety detection: Monitoring the safety zone around the robot to prevent collisions
Navigation assistance: Providing short-range obstacle information for robot navigation
Parking assistance: Assisting the robot with precise parking and positioning
Low-speed navigation: Providing reliable obstacle detection during low-speed movement
Multi-sensor fusion: Fusing with other sensor data (such as lidar, cameras) to improve perception accuracy
Safety zone monitoring: Monitoring the safety zone around the robot to ensure safe operation
Obstacle classification: Combining distance information for obstacle classification and recognition
Path planning: Planning safe paths based on ultrasonic radar data