1. Introduction
xgolib_rider is a dedicated control library for the XGO-Rider, a bipedal wheeled-leg robot. It extends the standard XGO communication protocol with optimizations for dual-wheel balancing, high-frequency IMU feedback, and velocity-vector based locomotion.
- Library Version: 1.4.2
- Target Hardware: XGO-Rider
- Key Features: Self-balancing control, 9-axis IMU data streaming, wheel encoder feedback, and OTA firmware upgrades.
2. Quick Start
Instantiation and Initialization
The XGO_ROG class handles all serial communication.
| Step | Code | Description |
|---|---|---|
| Import | from xgolib_rider import XGO_ROG | Import the Rider-specific class. |
| Setup | dog = XGO_ROG(port='/dev/ttyAMA0', baud=115200) | Initialize serial port (Defaults for Raspberry Pi). |
| Ready | dog.reset() | Robot enters self-balancing mode automatically. |
3. Core Control Functions
3.1 Locomotion (Speed Vector Control)
Rider uses a mapping system where 128 represents zero velocity. The library handles this conversion automatically.
| Method | Description | Range (Mapped) |
|---|---|---|
move_x(step) | Forward/Backward speed | -100 (Back) to 100 (Forward) |
move_y(step) | Lateral/Side speed | -100 to 100 (Model dependent) |
turn(step) | Rotation (Yaw) speed | -100 (CCW) to 100 (CW) |
stop() | Immediate Stop | Halts all wheel rotation. |
3.2 Body Attitude & Posture
Even while balancing, the Rider can adjust its body height and tilt angles.
| Method | Description | Example |
|---|---|---|
translation(dir, val) | Body translation (X, Y, Z) | dog.translation('z', 50)(Adjust height) |
attitude(dir, val) | Body tilt (Roll, Pitch, Yaw) | dog.attitude('p', 10)(Leaning forward) |
periodic_rot(dir, p) | Periodic rotation swing | Causes the robot to oscillate rhythmically. |
3.3 Preset Actions
action(id): Triggers a built-in preset movement.rider_reset(): Restores the default balancing posture (Action ID 255).
4. Sensor Feedback
The Rider version provides enhanced IMU reading methods to support balance-sensitive applications.
4.1 Attitude Data (Euler Angles)
| Method | Return Type | Description |
|---|---|---|
rider_read_roll() | float | Body Roll angle in degrees (°). |
rider_read_pitch() | float | Body Pitch angle in degrees (°). |
rider_read_yaw() | float | Body Yaw angle in degrees (°). |
4.2 Raw IMU Data
The read_imu() method returns a comprehensive list containing:
- Acceleration (m/s²): X, Y, Z
- Angular Velocity (deg/s): X, Y, Z
- Euler Angles (Radians): Roll, Pitch, Yaw
4.3 System Status
read_battery(): Returns battery percentage (0–100).read_motor(): Returns real-time angles/positions of the joints and wheels.
5. Advanced Features
Self-Stabilization (IMU Control)
The balancing algorithm relies on the internal IMU.
dog.imu(1): Enables self-balancing (Enabled by default).dog.imu(0): Disables self-balancing (Robot will fall without external support).
OTA Firmware Upgrade
The library supports upgrading the Rider firmware directly over the serial port:
| Feature | Code Example | Parameter Description | Important Notes |
|---|---|---|---|
| Upgrade Firmware | dog.rider_upgrade("path/to/firmware.bin") | filename: Local path to the firmware file (string). | Do not power off or disconnect the cables during the upgrade; doing so may corrupt the system. |
6. Developer Notes
- Startup Environment: Always place the Rider on a flat, horizontal surface before powering on to ensure the IMU calibrates the "level" state correctly.
- Polling Frequency: Due to serial bandwidth limits, it is recommended to keep sensor polling intervals (e.g.,
read_imu) above 20ms. - Calibration Warning:
calibration()resets the balancing zero-point. Only call this when the robot is perfectly vertical and stationary. - Serial Conflict: Ensure the Linux Serial Console is disabled in
raspi-configto avoid data corruption on/dev/ttyAMA0.