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.

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:

  1. Acceleration (m/s²): X, Y, Z
  2. Angular Velocity (deg/s): X, Y, Z
  3. 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

  1. Startup Environment: Always place the Rider on a flat, horizontal surface before powering on to ensure the IMU calibrates the "level" state correctly.
  2. Polling Frequency: Due to serial bandwidth limits, it is recommended to keep sensor polling intervals (e.g., read_imu) above 20ms.
  3. Calibration Warning: calibration() resets the balancing zero-point. Only call this when the robot is perfectly vertical and stationary.
  4. Serial Conflict: Ensure the Linux Serial Console is disabled in raspi-config to avoid data corruption on /dev/ttyAMA0.