GDK IMU Interface Documentation (Python)¶

Overview¶

The IMU (Inertial Measurement Unit) module provides the G02 robot with the ability to acquire real-time inertial data. Through the Python interface, developers can conveniently obtain the robot's orientation, angular velocity, and linear acceleration information, suitable for attitude detection, motion analysis, navigation, and many other scenarios.

Interface Description¶

Imu Class¶

This class encapsulates the main data acquisition interfaces of the IMU sensor.

1. `get_latest_imu()`¶

Function: Get the latest IMU data
Parameters:

Parameter	Type	Description
`type`	`ImuType`	IMU type enum value
`timeout`	`float`	Timeout duration (milliseconds)

Return value: An ImuData object, containing the following attributes:

Attribute	Type	Description	Unit
`timestamp_ns`	`int`	Timestamp of data acquisition, with nanosecond precision	nanoseconds
`angular_velocity`	`Vector3`	Angular velocity, the robot's angular velocity on the three axes	radians/second
`linear_acceleration`	`Vector3`	Linear acceleration, the robot's linear acceleration on the three axes	meters/second²

Detailed Description of the ImuData Object¶

angular_velocity (angular velocity object):

x: Angular velocity on the X axis
y: Angular velocity on the Y axis
z: Angular velocity on the Z axis

linear_acceleration (linear acceleration object):

x: Acceleration on the X axis
y: Acceleration on the Y axis
z: Acceleration on the Z axis

IMU types: - kImuUnknown: Unknown IMU - kImuFront: Front IMU - kImuBack: Rear IMU - kImuChassis: Chassis IMU

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")

imu = agibot_gdk.Imu()
time.sleep(2)  # Wait for the IMU to initialize

for i in range(10):
    # Get the latest IMU data
    imu_data = imu.get_latest_imu(agibot_gdk.ImuType.kImuFront, 1000.0)

    if imu_data is not None:
        print(f"\n--- IMU data #{i+1} ---")
        print(f"Timestamp: {imu_data.timestamp_ns}")

        # Angular velocity
        print(f"Angular velocity: x={imu_data.angular_velocity.x:.4f}, "
              f"y={imu_data.angular_velocity.y:.4f}, "
              f"z={imu_data.angular_velocity.z:.4f}")
        # Linear acceleration
        print(f"Linear acceleration: x={imu_data.linear_acceleration.x:.4f}, "
              f"y={imu_data.linear_acceleration.y:.4f}, "
              f"z={imu_data.linear_acceleration.z:.4f}")
    else:
        print(f"No IMU data received #{i+1}")
    time.sleep(1.0)

# Close the IMU
imu.close_imu()

# 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_imu()`¶

Function: Get the IMU data nearest to a specified timestamp
Parameters:

Parameter	Type	Description
`type`	`ImuType`	IMU type enum value
`timestamp`	`int`	Target timestamp (nanoseconds)
`timeout`	`float`	Timeout duration (milliseconds)

Return value: An ImuData object, with the same structure as get_latest_imu()
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")

imu = agibot_gdk.Imu()
time.sleep(1.0)
imu_type = agibot_gdk.ImuType.kImuFront

# First get the latest IMU data
imu_data = imu.get_latest_imu(imu_type, 1000.0)

if imu_data is not None:
    # Get historical IMU data (1 second earlier)
    imu_data_nearest = imu.get_nearest_imu(imu_type, imu_data.timestamp_ns-1000000000, 1000.0)

    if imu_data_nearest is not None:
        print(f"✅ Nearest IMU data: {imu_data_nearest.timestamp_ns}")
        print(f"Angular velocity: x={imu_data_nearest.angular_velocity.x:.4f}, "
              f"y={imu_data_nearest.angular_velocity.y:.4f}, "
              f"z={imu_data_nearest.angular_velocity.z:.4f}")
        print(f"Linear acceleration: x={imu_data_nearest.linear_acceleration.x:.4f}, "
              f"y={imu_data_nearest.linear_acceleration.y:.4f}, "
              f"z={imu_data_nearest.linear_acceleration.z:.4f}")
    else:
        print(f"❌ No nearest {imu_type} data found")

# Close the IMU
imu.close_imu()

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

3. `get_imu_fps()`¶

Function: Get the IMU data acquisition frame rate
Parameters:

Parameter	Type	Description
`type`	`ImuType`	IMU type enum value

Return value: int, the IMU frame rate (FPS)
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")

imu = agibot_gdk.Imu()
time.sleep(2)  # Wait for the IMU to initialize

imu_type = agibot_gdk.ImuType.kImuChassis
try:
    fps = imu.get_imu_fps(imu_type)
    print(f"IMU frame rate: {fps} FPS")
except RuntimeError as e:
    print(f"Failed to get frame rate: {e}")

# Close the IMU
imu.close_imu()

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

4. `get_imu_latency()`¶

Note: Before obtaining IMU data latency statistics, time synchronization must first be performed, otherwise the latency statistics results will be inaccurate
Function: Get IMU data latency statistics
Parameters:

Parameter	Type	Description
`type`	`ImuType`	IMU type enum value
`window_seconds`	`float`	Statistics window duration (seconds)

Return value: A LatencyStats object, containing the following 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")

imu = agibot_gdk.Imu()
time.sleep(2)  # Wait for the IMU to initialize

imu_type = agibot_gdk.ImuType.kImuChassis

try:
    latency = imu.get_imu_latency(imu_type, 1.0)
    print("IMU 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")
except RuntimeError as e:
    print(f"Failed to get latency statistics: {e}")

# Close the IMU
imu.close_imu()

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

5. `close_imu()`¶

Function: Close the IMU connection
Parameters: None
Return value: GDKRes, the operation result status code
Example:

import agibot_gdk

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

imu = agibot_gdk.Imu()

# Use the IMU...

# Close the IMU
result = imu.close_imu()
if result == agibot_gdk.GDKRes.kSuccess:
    print("IMU closed successfully")
else:
    print("Failed to close the IMU")

# 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 IMU functionality
GDK release: You must call agibot_gdk.gdk_release() to release GDK system resources before the program ends
Initialization wait: After creating an Imu object, it is recommended to wait 2 seconds to ensure the DDS connection is established
Timeout setting: Set an appropriate timeout duration based on actual needs to avoid long blocking periods
Data validity: Check whether the returned IMU data is None before use
Timestamp precision: The timestamp unit is nanoseconds, which can be used for precise time synchronization
Resource management: Call close_imu() to release IMU resources after use
Exception handling: All interfaces throw a std::runtime_error exception on failure and need to be handled appropriately
Unimplemented methods: get_imu_fps() and get_imu_latency() are currently not implemented, so use them with caution

Application Scenarios¶

Motion analysis: Using angular velocity and linear acceleration to analyze the robot's motion state
Navigation and localization: Combining with other sensor data for SLAM and localization
Balance control: Implementing robot balance control based on IMU data
Data fusion: Fusing with other sensor data to improve localization accuracy
Vibration monitoring: Monitoring the robot's vibration state through acceleration data