Version-specific API reference. This page describes an earlier library interface; its version label is not the latest Luwu-OS package version. For the current unified XGO() entry point, model detection and Ranger/Rider differences, start with xgolib Robot Control. Confirm the module loaded on your device before using these signatures or parameter ranges.

Hardware Support: XGO-Lite3, XGO-Mini2s, XGO-Mini3W

1. Introduction

xgolib is a lightweight Python library designed for communication with XGO robot dogs. It encapsulates complex underlying communication protocols, allowing developers to implement movement control, attitude adjustment, sensor data acquisition, and robotic arm operations through simple function calls.

  • Current Version: 1.4.3
  • Dependencies: pyserial, struct, math, time

2. Quick Start

Instantiation and Initialization

To begin controlling the robot, you must first instantiate the XGO_DOG class. This establishes the serial connection and synchronizes the software with the hardware's current state

Step Code / Configuration Description
Import from xgolib import XGO_DOG Imports the core control class from the library.
Instantiation dog = XGO_DOG(port='/dev/ttyAMA0', baud=115200) Initializes the serial interface. Defaults are optimized for Raspberry Pi.
Baud Rate 115200 The standard communication speed for XGO devices.
Serial Port /dev/ttyAMA0 The hardware serial port used for UART communication.

2. Quick Start

Instantiation and Initialization

To begin controlling the robot, you must first instantiate the XGO_DOG class. This establishes the serial connection and synchronizes the software with the hardware's current state.

Step Code / Configuration Description
Import from xgolib import XGO_DOG Imports the core control class from the library.
Instantiation dog = XGO_DOG(port='/dev/ttyAMA0', baud=115200) Initializes the serial interface. Defaults are optimized for Raspberry Pi.
Baud Rate 115200 The standard communication speed for XGO devices.
Serial Port /dev/ttyAMA0 The hardware serial port used for UART communication.

Automatic Startup Sequence

Upon running the initialization code above, the library automatically executes several internal routines to ensure the robot is ready:

Routine Purpose
Firmware Detection Reads the firmware version (e.g., 'M',, 'W', or 'R') to automatically apply the correct movement limits (Mini, Lite, or Rider).
Hardware Reset Calls self.reset()
, which triggers action 255
to stop all movement and return motors to their default neutral positions.
IMU Sync Reads the initial yaw
value from the onboard IMU to set the zero-reference for future rotation commands.
Buffer Flush Clears the serial input and output buffers to prevent old data from interfering with new commands.

3. Core Functional Descriptions

3.1 Movement Control (Gait & Movement)

These methods are used to control the overall translation and rotation of the robot dog.

Method Description Parameter Examples
move_x(step) Forward/Backward movement step
: -25 to 25 (mm/s)
move_y(step) Left/Right lateral translation step
: -18 to 18 (mm/s)
turn(step) Rotational/Yaw movement step
: -100 to 100 (deg/s)
stop() Stop all movements N/A
gait_type(mode) Switch gait patterns "trot"
, "walk"
, "high_walk"
, "slow_trot"
mark_time(height) Mark time (stepping in place) height
: Stepping height

3.2 Body Attitude Adjustment

Changes the relative position or tilt angle of the body while keeping the feet stationary.

  • Translation (translation): The direction can be 'x', 'y', or 'z'.
    • Example: dog.translation('z', 80) (Adjusts body height).
  • Rotation (attitude): The direction can be 'r' (Roll), 'p' (Pitch), or 'y' (Yaw).
    • Example: dog.attitude('p', 15) (Leans the body forward).

3.3 Preset Actions (Action)

The library contains various built-in preset actions called via an action_id.

Function Code Example Description
Execute Action dog.action(1) Triggers a specific preset movement based on the provided Action ID.
Emergency Stop / Reset dog.reset() Immediately stops all movement and restores the robot to its initial neutral state; this is functionally equivalent to calling action(255)
.

3.4 Motor and Single-Leg Control

  • Single Motor Control: motor(motor_id, angle).
    • motor_id: For example, 11 (Front-right upper leg), 12 (Middle joint), 13 (Lower joint), etc.
  • Single Leg Control: leg(leg_id, [x, y, z]).
    • Controls the specific foot-end coordinates for a given leg.

3.5 Robotic Arm Control (For Arm-Equipped Versions)

  • Cartesian Coordinate Control: arm(x, z).
    • Controls the arm's forward/backward (x) and up/down (z) movement.
  • Polar Coordinate Control: arm_polar(theta, r).
  • Gripper/Claw Control: claw(pos) (Range: 0–255).

4. Sensor Data Acquisition

The SDK provides several methods to read the real-time status of the robot dog, including battery levels, body orientation, and motor positions.

Method Return Type Description
read_battery() int Returns the current battery percentage (0–100).
read_roll() float Reads the current Roll angle of the body.
read_pitch() float Reads the current Pitch angle of the body.
read_yaw() float Reads the current Yaw angle of the body.
read_motor() list Returns a list of the current angles for all 15 motors.
read_firmware() string Returns the current firmware version string.
read_imu() list Returns a comprehensive list of 9-axis IMU data (Acceleration, Gyroscope, and Euler angles).
read_analog() int Reads the value from the analog input pin.
read_digital() int Reads the value from the digital input pin.

5. Advanced Features

Self-Stabilization System (IMU)

When enabled, the robot dog uses its onboard gyroscope data to automatically adjust its posture, ensuring the body remains level even on uneven surfaces.

Function Code Example Description
Enable IMU dog.imu(1) Activates the auto-balancing/self-stabilization mode.
Disable IMU dog.imu(0) Deactivates the auto-balancing mode.

Wheel Control (For Mini3W / Rider Versions Only)

For models equipped with motorized wheels, the SDK provides dedicated control methods:

Method Description
enable_wheel_control(mode) Switches the robot between standard gait mode and wheel-driven mode.
wheel_speed([s1, s2, s3, s4]) Controls the rotation speed of the four wheels individually.
wheel_get_encoder(id) Retrieves the encoder feedback for a specific wheel motor.

6. Parameter Limits (Reference)

Motion ranges vary depending on the specific model. Below are the typical operational limits for the XGO-Mini:

Parameter Limit / Range Unit
VX_LIMIT (Forward/Backward) ±25 mm/s
VY_LIMIT (Lateral/Side) ±18 mm/s
Roll Limit ±20° Degrees
Pitch Limit ±22° Degrees
Yaw Limit ±16° Degrees
Turn Speed Limit ±100 deg/s

7. Important Notes

To ensure the stable operation of the robot dog and a smooth development process, please pay close attention to the following technical details:

Category Item Description & Recommendations
Serial Port Serial Port Conflict When using Linux systems like Raspberry Pi, the default serial port /dev/ttyAMA0
is often occupied by the Serial Console. You must disable the serial terminal via raspi-config
before use; otherwise, communication will fail.
Calibration Hardware Calibration The calibration()
function modifies the underlying zero-point parameters of the servos. Do not call it unless absolutely necessary. Incorrect calibration can lead to abnormal postures or motor overload.
Timeout Communication Timeout The __unpack()
method has a built-in 1-second timeout. If "read" functions frequently return default values or errors, check if the physical cables are loose or if the baud rate is mismatched.
Battery Power Management When read_battery()
returns a value below 10%, please charge the robot immediately. Low voltage may cause insufficient motor torque or unexpected system reboots.
Protection Motor Protection During long debugging sessions or when carrying the robot by hand, it is recommended to call unload_allmotor()
to release motor torque. This prevents gear damage caused by manually forcing the joints.