Project files

HomeBot Game Controller User Guide

This document explains how to use an Xbox game controller to control the HomeBot robot.

Table of Contents

• Function Overview
• System Requirements
• Hardware Preparation
• Software Configuration
• Control Mapping
• Startup Steps
• Advanced Features
• Troubleshooting
• Safety Precautions

Function Overview

The gamepad control application allows you to simultaneously control HomeBot's chassis and robotic arm using an Xbox controller:

• Simultaneous Control: Left stick controls chassis movement, right stick controls the robotic arm, no mode switching required
• Precision Control: Analog sticks provide smooth speed control
• One-Click Functions: Quickly perform functions like wrist leveling and gripper control
• Vibration Feedback: Controller vibrates to alert during emergency stops
• Safety Protection: Back button for emergency stop, Start button for reset

System Requirements

• Operating System:
  • Windows 10/11 (using XInput API)
  • Ubuntu 20.04/22.04/24.04 (using native /dev/input/js* joystick interface)
• Python: 3.11+
• Hardware: Xbox controller (360/One/Series X|S)
• Services: Chassis service and robotic arm service must be running

Preparing the Linux (Ubuntu) System

Before using an Xbox controller on Ubuntu, you need to install the joystick toolkit and ensure that the current user has read permissions for /dev/input/js*.

1. Install the joystick package

sudo apt update
sudo apt install joystick

After installation, the system provides:

• Joystick device nodes such as /dev/input/js0, /dev/input/js1, etc.
• Debugging tools like jstest and jscal

2. Adding User Permissions

Add the current user to the input group to gain permission to read the joystick device:

sudo usermod -aG input $USER

You need to log out and log back in again (or restart the system) for the permissions to take effect.

3. Verifying the Joystick Connection

After connecting the joystick via wired or Bluetooth, check the device node:

ls /dev/input/js*

You should normally see a device like /dev/input/js0.

Use jstest to view joystick data in real time:

jstest /dev/input/js0

When you move the joystick or press buttons, the corresponding axis/button values in the terminal will change, indicating that the joystick has been recognized by the system.

4. Automatic Backend Selection

HomeBot automatically selects the gamepad backend based on the running platform without manual configuration:

• Windows: Native XInput API (hal/gamepad/xinput_core.py)
• Linux: Native /dev/input/js* interface (hal/gamepad/linux_js_backend.py)
• macOS / Others: pygame joystick fallback (hal/gamepad/pygame_backend.py)

Hardware Preparation

Supported Controllers

Connection Steps

1. Wired Connection: Connect directly to the computer using a USB cable.

2. Wireless Connection:

   • Press the pairing button on the controller (the small button next to the Xbox button).
   • Go to Windows Settings → Bluetooth & other devices → Add device.
   • Select "Xbox Wireless Controller".

3. Verify Connection:

   • Press the Xbox button; a steady light indicates a successful connection.
   • Check the status in Windows Game Controllers settings.
   • On Ubuntu, use jstest /dev/input/js0 to see if axis/button values change with input.

Software Configuration

1. Basic Configuration

Edit GamepadConfig in software/src/configs/config.py:

@dataclass
class GamepadConfig:
    """Gamepad control configuration"""

    # ========== Chassis Control Parameters ==========
    max_linear_speed: float = 0.5          # Maximum linear speed (m/s)
    max_angular_speed: float = 1.0         # Maximum angular speed (rad/s)
    trigger_deadzone: float = 0.1          # Trigger deadzone
    left_stick_deadzone: float = 0.15      # Left stick deadzone

    # ========== Robotic Arm Control Parameters ==========
    arm_base_step: float = 3.0             # Base joint step (degrees/frame)
    arm_elbow_step: float = 2.0            # Elbow joint step (degrees/frame)
    arm_shoulder_step: float = 2.0         # Shoulder joint step (degrees/frame)
    arm_wrist_flex_step: float = 3.0       # Wrist flexion step (degrees/operation)
    arm_wrist_roll_step: float = 3.0       # Wrist rotation step (degrees/frame)
    arm_gripper_open: float = 90.0         # Gripper open angle
    arm_gripper_close: float = 0.0         # Gripper close angle
    arm_speed: int = 800                   # Robotic arm movement speed
    right_stick_deadzone: float = 0.15     # Right stick deadzone

    # ========== Communication Configuration ==========
    chassis_service_addr: str = "tcp://localhost:5556"
    arm_service_addr: str = "tcp://localhost:5557"

    # ========== Polling Configuration ==========
    polling_interval: float = 0.02         # 50Hz (20ms)

2. Parameter Tuning Suggestions

Stick Dead Zone Adjustment:

• If the chassis moves even when the stick is not touched, increase the dead zone value
• Recommended range: 0.10 ~ 0.25

left_stick_deadzone: float = 0.20   # Increase dead zone to reduce drift
right_stick_deadzone: float = 0.20

Speed Limitation:

• Beginners are advised to lower the speed first, then increase it after familiarization

max_linear_speed: float = 0.3       # Lower maximum linear speed
max_angular_speed: float = 0.6      # Lower maximum angular speed

Robotic Arm Step Size:

• If the robotic arm moves too fast or too slow, adjust the step size

arm_shoulder_step: float = 1.0      # Reduce step size for finer control
arm_elbow_step: float = 1.0

Control Mapping

Chassis Control (Left Hand Area)

Tip: You can operate the stick and trigger simultaneously, e.g., Left Stick forward + RT right strafe = diagonal movement

Robotic Arm Control (Right-Hand Area)

System Control

Startup Steps

Method 1: Manual Startup (Recommended for Development and Debugging)

Step 1: Start the Chassis Service

cd software/src
python -m services.motion_service.chassis_service

Step 2: Start the Arm Service

cd software/src
python -m services.motion_service.arm_service

Step 3: Start the Gamepad Control

cd software/src
python -m applications.gamepad_control

The following output indicates successful startup:

============================================================
Initializing Gamepad Control Application
============================================================
Connecting gamepad (index: 0)...
Connected gamepads: [0]
✓ Gamepad initialized
Connecting to chassis service...
✓ Chassis client connected: tcp://localhost:5556
Connecting to arm service...
✓ Arm client connected: tcp://localhost:5557
============================================================
Initialization complete, waiting for startup...
============================================================
============================================================
Gamepad control started
============================================================
Control Mapping:
  Chassis: Left stick (movement/rotation) + LT/RT (translation)
  Arm: Right stick (base/extension) + D-pad (lift/rotation) + Y/A/B (wrist flip) + RB/LB (gripper)
  System: Back (emergency stop) / Start (reset)
============================================================
Press Ctrl+C to stop
============================================================

Method 2: Specify the Controller Index

If multiple controllers are connected:

# Use the 2nd controller
python -m applications.gamepad_control --controller 1

Method 3: Detailed Logs

Check detailed communication logs during debugging:

python -m applications.gamepad_control --verbose

Advanced Features

1. One-Click Horizontal Wrist

Press the B button to automatically calculate the wrist angle as:

wrist_flex = 180° - shoulder - elbow

Principle Explanation:

• shoulder = 30°, elbow = 45° → wrist_flex = 105°
• This ensures the end effector remains level regardless of the arm's posture

Use Cases:

• Maintaining stability when transporting objects
• Automatically leveling items when placing them
• Keeping sensors level during photography/scanning

2. Speed Superposition Techniques

With simultaneous control, you can:

• Diagonal Movement: Push left stick forward + pull RT right trigger = move toward the upper-right
• Move While Turning: Push left stick forward + move left/right stick left/right = walk while turning
• Cooperative Operation: Adjust the robotic arm posture while the chassis is moving

3. Fine Control Mode

When fine control is needed, you can:

• Gently push the joystick (small range) for low-speed movement
• Quickly click the direction keys instead of long-pressing (step control)
• Adjust the step value in the configuration to reduce movement range

Troubleshooting

Controller cannot be connected

Symptom: Prompt "Controller not detected" at startup

Troubleshooting steps:

1. Check controller power

   Press the Xbox button to confirm the indicator light is on
   

2. Check Windows connection

   • Settings → Bluetooth & other devices
   • Confirm "Xbox Wireless Controller" is displayed as connected

3. Re-pairing

   • Long-press the Xbox button for 6 seconds to turn off the controller
   • Press the Xbox button again to turn it on
   • If using Bluetooth, delete the device and re-pair

4. Check driver

   • Device Manager → Xbox peripherals
   • Confirm no yellow exclamation mark

Ubuntu additional troubleshooting

1. Check if the joystick package is installed

   dpkg -l | grep joystick
   

   If not installed:

   sudo apt install joystick
   

2. Check if the device node exists

   ls -l /dev/input/js*
   

   If js0 and similar devices are not visible, the gamepad has not been recognized by the system. Check the USB/Bluetooth connection.

3. Check user permissions

   groups $USER
   

   Ensure input is included in the output. If not:

   sudo usermod -aG input $USER
   # Changes take effect after logging out and back in
   

4. Verify raw data using jstest

   jstest /dev/input/js0
   

   If jstest shows data but the program fails to detect it, check whether software/src/hal/gamepad/__init__.py correctly selects linux_js_backend on the Linux platform.

Chassis/Arm No Response

Symptom: The joystick operates normally, but the robot does not move.

Troubleshooting Steps:

1. Check if the service is running

   # View port listening status
   netstat -an | findstr 5556
   netstat -an | findstr 5557
   

2. Check the configuration address

   # Confirm the address in the configuration is correct
   chassis_service_addr: str = "tcp://localhost:5556"
   arm_service_addr: str = "tcp://localhost:5557"
   

3. View service logs

   • Check the chassis/arm service terminal for any error output
   • Confirm that the serial port connection is normal

Stick Drift

Symptom: Chassis moves on its own even when the stick is untouched

Solution:

Increase the deadzone value:

# software/src/configs/config.py
left_stick_deadzone: float = 0.20   # Increased from 0.15 to 0.20
right_stick_deadzone: float = 0.20

No response from buttons

Symptom: Some buttons do not respond when pressed

Possible causes:

• In emergency stop state (press Start to reset)
• Priority is occupied (check chassis/robotic arm service logs)
• Low gamepad battery; replace or charge the battery

Communication Timeout

Symptom: Frequent "communication failure" warnings appear

Solution:

• Check if the USB connection is stable
• Reduce the polling frequency:

  polling_interval: float = 0.05  # Changed from 0.02 to 0.05 (20Hz)
  

Safety Precautions

⚠️ Important Notes Before Use

1. First-Time Use

   • Test in an open area with no fragile items nearby
   • Start at low speed to familiarize yourself with the controls, then gradually increase speed
   • Know the location of the emergency stop button (Back key)

2. During Operation

   • Keep the controller within the effective range (approximately 10 meters for Bluetooth)
   • Be mindful of the robotic arm’s movement range to avoid collisions
   • Keep personnel away from the robot’s path of motion

3. Abnormal Situations

   • Immediately press the Back key to emergency stop if any abnormality occurs
   • The system will automatically stop if the connection is lost (1-second timeout)
   • After reconnecting, press Start to reset

4. Robotic Arm Position Limits

   • Pay attention to the angle limits of each joint
   • Avoid continuous rapid operations to prevent motor overheating
   • Stop immediately and inspect if any unusual noise is heard

Emergency Stop Procedure

1. Press the Back button → Chassis and robotic arm stop immediately
2. Controller vibration feedback → Confirm emergency stop has been triggered
3. Check for abnormal causes → Troubleshoot and resolve the issue
4. Press the Start button → System resets and control is restored

Document version: 1.1 Last updated: 2026-07-06