Project files

HomeBot Human-Following Function User Guide

Feature Overview

The human-following function is implemented using the YOLO26 model for real-time human detection, combined with target-tracking and visual servo control algorithms to enable the robot to automatically follow the target human.

Technical Specifications

Quick Start

1. Installing Dependencies

cd /Users/zhuzhuangtian/Desktop/workspace/homebot
pip install -e .

2. Download the Model

The model will be downloaded automatically the first time it is run, or it can be downloaded manually:

cd software
python tools/download_models.py yolo26n

Convert the downloaded yolo26n.pt to ONNX format:

python tools/export_onnx.py models/yolo26n.pt

If you encounter network issues during download, you can download it from the Baidu Netdisk link: Link: https://pan.baidu.com/s/19oHB9KpET_LAxAXwsFhNVg (opens in a new tab) Extraction code: uuxs

Place the yolo26n.onnx file directly in the models directory.

3. Start the Chassis Service

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

4. Start the Vision Service

cd software/src
python -m services.vision_service

5. Start the Follow Function

cd software
python start_human_follow.py --display

Configuration Description

The configuration file is located at software/src/configs/config.py:

@dataclass
class HumanFollowConfig:
    # Model configuration
    model_path: str = "models/yolo26n.pt"
    conf_threshold: float = 0.5

    # Tracking configuration
    max_tracking_age: int = 30          # Maximum lost frames
    min_iou_threshold: float = 0.3      # IoU matching threshold
    target_selection: str = "center"    # Selection strategy: center/largest/closest

    # Inference optimization
    inference_size: int = 320           # Input resolution
    use_half_precision: bool = False    # FP16 half precision

    # Follow control
    target_distance: float = 1.0        # Target distance (meters)
    kp_linear: float = 0.001            # Linear velocity P coefficient
    kp_angular: float = 0.003           # Angular velocity P coefficient
    max_linear_speed: float = 0.3       # Maximum linear velocity
    max_angular_speed: float = 0.8      # Maximum angular velocity
    dead_zone_x: int = 50               # Horizontal dead zone (pixels)

    # Safety configuration
    stop_on_lost: bool = True           # Stop when target is lost
    search_on_lost: bool = True         # Search when target is lost

Operating Modes

Running via Command Line

# Basic mode
cd software/src
python -m applications.human_follow

# Display debug window
python -m applications.human_follow --display

Code Invocation

from applications.human_follow import HumanFollowApp

# Create the application
app = HumanFollowApp()

# Run (with debug display)
app.run(display=True)

Programmatic Control

from applications.human_follow import HumanFollowApp, FollowMode

app = HumanFollowApp()

# Initialize
app.initialize()

# Start following
app.start_following()

# Pause
app.pause()

# Resume
app.resume()

# Stop following
app.stop_following()

# Stop the application
app.stop()

Control Logic

Horizontal Control (Rotation)

• Target on the left side of the screen → Turn left
• Target on the right side of the screen → Turn right
• Within the dead zone → No rotation

Distance Control (Front and Back)

• Target too small (too far) → Move forward
• Target too large (too close) → Move backward
• Within target area range → Stop

Handling Target Loss

1. Temporary loss (<60 frames): Rotate in place to search
2. Complete loss (>60 frames): Stop moving and enter idle state

Visualization Information

The debug window displays the following information:

• Green thin box: All detected human bodies
• Red thick box: Currently tracked target
• Yellow dot: Target center
• Blue line: Offset between the target and the center of the image
• Green cross: Center of the image
• Info panel: Mode, FPS, speed, number of targets

Safety Mechanisms

1. Speed Limitation: Maximum linear and angular speeds are configurable
2. Dead Zone Control: Prevents jitter
3. Loss Protection: Automatically stops or searches when the target is lost
4. Emergency Stop Response: Can be preempted by emergency priority
5. Communication Timeout: Automatically stops if communication with the chassis times out

Performance Specifications

Frequently Asked Questions

Q: What should I do if the model fails to download?

A: Download manually:

wget https://github.com/ultralytics/assets/releases/download/v8.3.0/yolo26n.pt -O software/models/yolo26n.pt

Q: Can't detect a human?

A: Check the following:

1. Whether the camera is working properly
2. Whether the confidence threshold is too high (default: 0.5)
3. Whether the lighting is sufficient

Q: Why is the follow mode jerky?

A: Adjust the following parameters:

• Reduce inference_size to 320
• Tune kp_linear and kp_angular
• Increase dead_zone_x

Q: How to follow only a specific person?

A: Current selection strategies:

• center: Selects the person in the center of the frame
• largest: Selects the largest person (closest)
• closest: Same as largest

Future versions will support specifying a target using face recognition.

Module Structure

applications/human_follow/
├── __init__.py          # Module export
├── __main__.py          # Entry point
├── follow.py            # Main application HumanFollowApp
├── detector.py          # Detector HumanDetector (YOLO26)
├── tracker.py           # Tracker TargetTracker
└── controller.py        # Controller FollowController

Testing

Run the unit tests:

cd software/src
python -m tests.test_human_follow

Future Extensions

• Gesture control (stop, follow, leave)
• Face recognition for designated targets
• Path prediction for early adjustments
• Obstacle avoidance integration
• Web control interface integration

Document version: 1.0 Update date: 2026-03-09