Products

GDK v2.6.3 — Python API Reference

Version: v1.0Release Date: 2026-07-04Genie G2

Robot Hardware Overview

The G02 is a mobile humanoid robot with the following physical structure:

                    ┌─────────────────────────┐
                    │          HEAD           │
                    │  Stereo cameras (L/R)   │
                    │  Fisheye cameras (L/R/Back)│
                    │  Color camera + Depth   │
                    │  Neck joints            │
                    └────────────┬────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
        LEFT ARM           WAIST / LIFT        RIGHT ARM
        (joints)           (pitch + lift)       (joints)
              │                  │                  │
        LEFT END                 │             RIGHT END
        EFFECTOR                 │             EFFECTOR
        (gripper/tool)           │             (gripper/tool)
        Left hand camera         │             Right hand camera
                                 │
                    ┌────────────┴────────────┐
                    │         CHASSIS         │
                    │  Front LiDAR + Back LiDAR│
                    │  Front IMU + Back IMU   │
                    │  Chassis IMU            │
                    │  Ultrasonic radars      │
                    │  Mobile base            │
                    └─────────────────────────┘

Key body segments and their GDK identifiers:

Segment	Description
`right_arm` / `left_arm`	6-DOF arms with error, control, and estop state
`right_end` / `left_end`	End effectors (grippers/tools); model is readable
`waist`	Waist pitch joint
`lift`	Vertical lift mechanism
`neck` / head	Head with 3-axis motion
`chassis`	Mobile base (Ackermann or crab-walk drive modes)

GDK Architecture

All GDK functionality is accessed through the agibot_gdk Python package. The SDK uses DDS (Data Distribution Service) as its internal communication layer. Every module creates its own DDS subscriber/publisher, so a short time.sleep() after instantiation is required to let the connection establish.

Package layout:

Module	Class / Function	Role
`common`	`gdk_init()`, `gdk_release()`	System lifecycle
`types`	Enums, data structures	Shared data types
`robot`	`Robot`	Joint & body state + control
`tf`	`TF`	Coordinate frame transforms
`imu`	`Imu`	Inertial measurement data
`camera`	`Camera`	Image data from all cameras
`lidar`	`Lidar`	Point cloud data
`ultrasonicradar`	`UltrasonicRadar`	Proximity sensing
`slam`	`Slam`	Mapping and localization
`map`	`Map`	Map management
`pnc`	`Pnc`	Path planning and navigation
`interaction`	`Interaction`	Voice, display, media playback

Lifecycle: Init & Release

Every GDK program must call gdk_init() before using any module and gdk_release() before exiting.

import agibot_gdk

result = agibot_gdk.gdk_init()
if result != agibot_gdk.GDKRes.kSuccess:
    exit(1)

# ... use GDK modules ...

agibot_gdk.gdk_release()

Module Reference

Common

Core system lifecycle functions.

Function	Parameters	Returns	Description
`gdk_init()`	—	`GDKRes`	Initialize the GDK system. Must be called first.
`gdk_release()`	—	`GDKRes`	Release all GDK resources. Must be called on exit.

Types

Shared enumerations and data structures used across all modules.

Enumerations

GDKRes — Return status code for all GDK operations.

Value	Meaning
`kSuccess`	Operation succeeded
`kInvalidInput`	Invalid input parameter
`kInvalidOutput`	Invalid output parameter
`kRuntimeError`	Runtime error
`kUnknown`	Unknown error

CameraType — Identifies which physical camera to access.

Value	Camera
`kHeadStereoLeft` / `kHeadStereoRight`	Head stereo pair
`kHeadColor`	Head color camera
`kHeadDepth`	Head depth (RGBD) camera
`kHeadLeftFisheye` / `kHeadRightFisheye` / `kHeadBackFisheye`	Head fisheye cameras
`kHandLeftColor` / `kHandRightColor`	Wrist-mounted color cameras
`kHandLeftDepth` / `kHandRightDepth`	Wrist-mounted depth cameras

In normal mode only head stereo, hand color, head color, and head depth cameras are active by default. Additional cameras require developer mode.

LidarType — Front or back LiDAR.

Value	Sensor
`kLidarFront`	Front-facing LiDAR
`kLidarBack`	Rear-facing LiDAR

ImuType — Which IMU unit to read.

Value	Sensor
`kImuFront`	Front IMU
`kImuBack`	Rear IMU
`kImuChassis`	Chassis IMU

EndEffectorControlGroup — Which arm(s) to include in a motion command.

Value	Group
`kLeftArm` / `kRightArm` / `kBothArms`	Arms only
`kBothArmsWaistLift`	Arms + waist + lift
`kBothArmsWaistPitch`	Arms + waist pitch
`kBothArmsWaist`	Arms + waist
(and symmetric left/right variants)

SensorExtrinsicType — Pre-defined sensor-to-sensor or sensor-to-base_link transform pairs (used with TF.get_tf_from_sensor()).

Examples: kHeadLeftStereoToHeadRightStereo, kChassisFrontLidarToBaseLink, kHeadRGBDToHeadLink3, etc.

Data Structures

Type	Fields	Units
`Vector3`	`x`, `y`, `z` (float)	meters (or rad/s for angular)
`Quaternion`	`x`, `y`, `z`, `w` (float)	dimensionless
`Pose`	`position: Vector3`, `orientation: Quaternion`	m + dimensionless
`Twist`	`linear: Vector3`, `angular: Vector3`	m/s + rad/s
`Wrench`	`force: Vector3`, `torque: Vector3`	N + N·m
`Image`	`timestamp_ns`, `width`, `height`, `encoding`, `color_format`, `bit_depth`, `data: bytes`	—
`PointCloud`	`timestamp_ns`, `width`, `height`, `point_step`, `row_step`, `is_dense`, `fields`, `data: bytes`	—
`ImuData`	`timestamp_ns`, `angular_velocity: Vector3`, `linear_acceleration: Vector3`	rad/s + m/s²
`LatencyStats`	`max_latency_ms`, `avg_latency_ms`, `p99_latency_ms`, `p999_latency_ms`, `p9999_latency_ms`	ms

Robot

agibot_gdk.Robot() — Controls joints and reads body state for the G02.

Wait ~2 seconds after instantiation before calling any method.

State Reading

Method	Returns	Description
`get_joint_states()`	`dict`	All joint positions, velocities, torques, motor currents, and error codes
`get_whole_body_status()`	`dict`	Per-segment error codes, control flags, estop state, and end-effector model names
`get_motion_control_status()`	`MotionControlStatus`	End-effector frame poses, velocities, wrenches, collision pairs, current mode
`get_end_state()`	`dict`	End-effector state
`get_chassis_power_state()`	—	Chassis power information
`get_chest_power_state()`	—	Chest (upper body) power information

get_joint_states() return structure:

{
  "timestamp": int,        # nanoseconds
  "nums": int,             # number of joints
  "states": [
    {
      "name": str,
      "mode": int,         # 0=stop, 1=G1_servo, 2=path_plan, 5=G2_servo
      "motor_position": float,   # radians (use this, not "position")
      "motor_velocity": float,   # rad/s
      "motor_current": float,    # amperes
      "effort": float,           # N·m
      "error_code": int
    }, ...
  ]
}

Joint Control — Path Planning Mode

Method	Description
`joint_control_request()`	Switch joint control mode
`move_head_joint(...)`	Move head joints via path planning
`move_waist_joint(...)`	Move waist joint via path planning
`move_arm_joint(...)`	Move arm joints via path planning

Joint Control — Servo Mode

Method	Description
`joint_servo_control(...)`	Generic servo control
`move_head_joint_servo(...)`	Direct servo command to head
`move_waist_joint_servo(...)`	Direct servo command to waist
`move_arm_joint_servo(...)`	Direct servo command to arm(s)

End-Effector Control

Method	Description
`move_ee_pos(...)`	Move end-effector position (G2 servo mode)
`end_effector_pose_control(...)`	Full 6-DOF end-effector pose command

TF (Coordinate Transforms)

agibot_gdk.TF() — Query real-time coordinate transforms between robot frames.

The root frame is base_link (center of the chassis). All transforms use (translation: Vector3, rotation: Quaternion) representation.

Method	Parameters	Returns	Description
`get_all_tf_from_base_link()`	—	`list[TransformStamped]`	All known transforms from `base_link`
`get_tf_from_base_link(child_frame_id)`	`str`	`Transform`	Transform from `base_link` to a named frame
`get_tf_from_sensor(sensor_extrinsic_type)`	`SensorExtrinsicType`	`Transform`	Pre-defined sensor-to-sensor extrinsic
`lookup_transform_latest(target, source, return_timestamp=False)`	`str`, `str`	`(Transform, int or None)`	Latest transform between any two frames
`lookup_transform(target, source, time_ns)`	`str`, `str`, `int`	`Transform`	Time-interpolated transform at a specific timestamp
`can_transform(target, source)`	`str`, `str`	`bool`	Check if a transform path exists
`get_all_frame_names()`	—	`list[str]`	All available coordinate frame names

IMU

agibot_gdk.Imu() — Reads angular velocity and linear acceleration from any of the robot’s IMU units.

Method	Parameters	Returns	Description
`get_latest_imu(type, timeout)`	`ImuType`, `float` (ms)	`ImuData`	Most recent IMU sample
`get_nearest_imu(type, timestamp, timeout)`	`ImuType`, `int` (ns), `float` (ms)	`ImuData`	Closest sample to a given timestamp
`get_imu_fps(type)`	`ImuType`	`int`	Data rate in Hz (not yet implemented)
`get_imu_latency(type, window_seconds)`	`ImuType`, `float`	`LatencyStats`	Latency statistics (requires time sync; not yet implemented)
`close_imu()`	—	`GDKRes`	Release IMU resources

Camera

agibot_gdk.Camera() — Retrieves images from any of the robot’s cameras.

Method	Parameters	Returns	Description
`get_latest_image(type, timeout)`	`CameraType`, `float` (ms)	`Image`	Most recent frame
`get_nearest_image(type, timestamp, timeout)`	`CameraType`, `int` (ns), `float` (ms)	`Image`	Frame closest to a given timestamp
`get_image_shape(type)`	`CameraType`	`tuple(int, int)`	`(width, height)` without transferring pixel data
`get_image_fps(type)`	`CameraType`	`float`	Camera frame rate
`get_image_latency(type, window_seconds)`	`CameraType`, `float`	`LatencyStats`	Latency statistics (requires time sync)
`close_camera()`	—	—	Release camera resources

Image encoding values: "rgb8", "bgr8", "mono8", "mono16", "32FC1" (depth float).

Lidar

agibot_gdk.Lidar() — Streams point clouds from the front or rear LiDAR.

Method	Parameters	Returns	Description
`get_latest_pointcloud(type, timeout)`	`LidarType`, `float` (ms)	`PointCloud`	Most recent scan
`get_nearest_pointcloud(type, timestamp, timeout)`	`LidarType`, `int` (ns), `float` (ms)	`PointCloud`	Scan closest to a given timestamp
`get_lidar_fps(type)`	`LidarType`	`float`	Scan rate (not yet implemented)
`get_lidar_latency(type, window_seconds)`	`LidarType`, `float`	`LatencyStats`	Latency statistics (requires time sync; not yet implemented)
`close_lidar()`	—	`GDKRes`	Release LiDAR resources

Point cloud fields typically contain x, y, z, and intensity. Raw bytes in data must be parsed using the fields descriptor.

UltrasonicRadar

agibot_gdk.UltrasonicRadar() — Reads distance measurements from the array of ultrasonic sensors on the chassis.

Method	Parameters	Returns	Description
`get_latest_ultrasonic_radar()`	—	`dict`	Latest readings from all sensors
`get_nearest_ultrasonic_radar(timestamp_ns)`	`int` (ns)	`dict`	Readings closest to a given timestamp
`get_ultrasonic_radar_fps()`	—	`float`	Update rate in Hz
`get_ultrasonic_radar_latency(window_seconds)`	`float`	`LatencyStats`	Latency statistics
`close_ultrasonic_radar()`	—	`GDKRes`	Release resources

Return dict structure:

{
  "timestamp_ns": int,
  "ultrasonic_radar_datas": [
    {"id": int, "distance_mm": int, "fault_state": int},
    ...
  ]
}

fault_state == 0 means the sensor is healthy. Distance is in millimeters.

Note: get_nearest_ultrasonic_radar() does not include an id field in each sensor dict.

SLAM

agibot_gdk.Slam() — Controls simultaneous localization and mapping.

Method	Parameters	Returns	Description
`get_slam_state()`	—	`int`	`1`=mapping, `2`=stopped, `0`=cancelled
`start_mapping()`	—	—	Begin building a new map
`stop_mapping()`	—	—	Finish and save the current map
`cancel_mapping()`	—	—	Discard the current mapping session
`get_odom_info()`	—	`OdomInfo`	Rich odometry: pose, velocity, acceleration, localization confidence and state, slip detection
`get_curr_pose()`	—	`Pose`	Current position and orientation in the map frame
`record_spec_loc()`	—	—	Save current position as charging dock location (not yet released)

OdomInfo key fields: pose, twist, velocity, velocity_body, acceleration, ang_vel, orientation_euler, is_stationary, is_sliping, loc_confidence, loc_state.

Map

agibot_gdk.Map() — Manages the set of stored maps on the robot.

Method	Parameters	Returns	Description
`get_curr_map()`	—	`MapName`	Currently active map (`id`, `name`, `is_curr_map`)
`get_all_map()`	—	`list[MapName]`	All stored maps
`switch_map(map_id)`	`int`	—	Activate a different map (do not call during active navigation)
`remove_map(map_id)`	`int`	—	Permanently delete a stored map

Map IDs are uint8 (0–255). Deletion is irreversible.

PNC (Planning & Control)

agibot_gdk.Pnc() — Sends navigation goals and manages task execution. Requires prior relocation on the G02 Pad before calling navigation methods.

Task State

Method	Returns	Description
`get_task_state()`	`PNCTaskState`	Current task `state`, `message`, `id`, and `type`

Task states: 0=idle, 1=starting, 2=running, 3=pausing, 4=paused, 5=resuming, 6=cancelling, 7=cancelled, 8=failed, 9=success. Task types: 0=idle, 1=normal navigation, 2=remote control.

Method	Parameters	Description
`normal_navi(target)`	`NaviReq` (map frame)	Navigate to a pose with obstacle avoidance
`high_precision_navi(target)`	`NaviReq` (map frame)	High-precision navigation (not yet released)
`relative_move(target)`	`NaviReq` (base_link frame)	Small-range displacement, stop-on-obstacle, no detour

Task Control

Method	Parameters	Description
`cancel_task(task_id)`	`int`	Cancel an in-progress navigation task
`pause_task(task_id)`	`int`	Pause a running task
`resume_task(task_id)`	`int`	Resume a paused task

Remote / Direct Chassis Control

Method	Parameters	Description
`request_chassis_control(control_mode)`	`int` (`0`=Ackermann, `1`=crab)	Acquire chassis control in remote mode
`move_chassis(twist)`	`Twist`	Send velocity commands directly to the chassis

Interaction

agibot_gdk.Interaction() — Controls voice, audio, video, and display output. Requires cross-network-segment access; run with --privileged if inside a Docker container.

Voice / Audio

Method	Parameters	Description
`set_language(language)`	`Language.kLanguageChinese` or `kLanguageEnglish`	Set TTS/ASR language
`set_volume(volume)`	`int` (0–100)	Set speaker volume
`set_wakeup_switch(is_on)`	`bool`	Enable/disable wake word detection
`set_audio_switch(is_on)`	`bool`	Enable/disable audio subsystem
`set_call_mode(is_on)`	`bool`	Enter/exit call mode (continuous listening, no wake word needed)
`play_tts(text)`	`str`	Convert text to speech and play it
`play_audio(audio_path)`	`str`	Play an audio file from disk
`get_func_status()`	—	Returns `VoiceFuncStatus` with wakeup state, volume, language settings, etc.
`get_asr_text()`	—	Retrieve transcribed speech text (use in call mode)
`register_callback(...)`	—	Register callback for ASR events

Display / Video

Method	Parameters	Description
`set_display_switch(is_on)`	`bool`	Enable/disable the display
`play_video(video_path, loop_count)`	`str`, `int`	Play a video file; `loop_count=-1` for infinite loop

Usage Pattern

Every GDK program follows this lifecycle:

import agibot_gdk
import time

# 1. Initialize
if agibot_gdk.gdk_init() != agibot_gdk.GDKRes.kSuccess:
    exit(1)

try:
    # 2. Instantiate needed modules
    robot = agibot_gdk.Robot()
    camera = agibot_gdk.Camera()
    time.sleep(2)  # Allow DDS connections to establish

    # 3. Use APIs
    joints = robot.get_joint_states()
    image = camera.get_latest_image(agibot_gdk.CameraType.kHeadStereoLeft, 1000.0)

except Exception as e:
    print(f"Error: {e}")

finally:
    # 4. Close module resources before releasing GDK
    camera.close_camera()

    # 5. Release
    agibot_gdk.gdk_release()