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 255to stop all movement and return motors to their default neutral positions. |
| IMU Sync | Reads the initial yawvalue 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): Thedirectioncan be'x','y', or'z'.- Example:
dog.translation('z', 80)(Adjusts body height).
- Example:
- Rotation (
attitude): Thedirectioncan be'r'(Roll),'p'(Pitch), or'y'(Yaw).- Example:
dog.attitude('p', 15)(Leans the body forward).
- Example:
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/ttyAMA0is often occupied by the Serial Console. You must disable the serial terminal via raspi-configbefore 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. |