HomeBot 是一个面向家庭场景的轻量级机器人项目，采用 分层模块化架构 和 ZeroMQ 通信总线，支持手机遥控、语音交互、模仿学习、人体跟随等多种应用。
- 2025-03-28 - HomeBot Plus：新增升降平台功能，支持机械臂整体高度调节
- 2025-03-24 - 语音交互与视觉理解：新增语音交互系统、视觉理解功能、电池状态监测
📋 查看完整更新记录
homebot/
├── docs/ # 文档 (中文)
├── hardware/ # 硬件设计文件（STEP, STL）
│ └── structure/
├── software/ # 软件代码
│ ├── src/
│ │ ├── common/ # 公共工具、消息定义、配置类
│ │ ├── configs/ # 运行时配置 (config.py)
│ │ ├── applications/ # 应用层
│ │ │ ├── remote_control/ # 网页遥控端 (含视频流)
│ │ │ ├── gamepad_control/ # 游戏手柄控制 (Xbox手柄)
│ │ │ ├── human_follow/ # 人体跟随 (YOLO + 视觉伺服)
│ │ │ ├── speech_interaction/# 语音交互
│ │ │ └── imitation_learning/# 模仿学习
│ │ ├── services/ # 服务层
│ │ │ ├── motion_service/ # 底盘控制服务
│ │ │ │ └── chassis_arbiter/ # 仲裁器核心
│ │ │ └── vision_service/ # 视觉服务 (图像采集发布)
│ │ ├── hal/ # 硬件抽象层
│ │ │ ├── camera/ # 摄像头驱动
│ │ │ ├── chassis/ # 底盘驱动
│ │ │ ├── gamepad/ # Xbox手柄驱动
│ │ │ └── ftservo_driver.py # 飞特舵机底层驱动
│ │ ├── examples/ # 示例代码
│ │ └── tests/ # 测试代码
│ ├── models/ # 机器学习模型 (YOLO26 等)
│ ├── tools/ # 辅助脚本（设备查看、校准、模型下载等）
│ ├── start_system.py # 跨平台系统启动器
│ ├── start_human_follow.py # 启动人体跟随
│ └── start_chassis_service.py
├── requirements.txt # Python 依赖
├── pyproject.toml # 构建系统配置
├── setup.py # 包安装配置
└── README.md # 项目说明
- 纯 Python 实现，轻松跨平台（Windows、Linux、Mac、树莓派）
- ZeroMQ 通信总线，低延迟，低资源消耗
- 网页遥控端，支持手机/平板/PC，实时视频流显示
- 游戏手柄控制，Xbox 手柄同时控制底盘和机械臂
- 人体跟随，基于 YOLO26 的视觉伺服自动跟随
- 紧急停止锁定，触发后需手动归位解锁，确保安全
- 一键启动脚本，自动检查端口占用，启动所有服务
- 硬件抽象层，可适配不同传感器与执行器
- 分层模块化，易于扩展新功能
# 在项目根目录
python -m pip install -e .或手动安装依赖：
pip install -r requirements.txt机器人相关配置统一保存在software/src/config/configs.py中
必须进行的配置：底盘和机械臂串口设置
@dataclass
class ArmConfig:
"""机械臂配置"""
serial_port: str = "/dev/tty.usbmodem5AE60527771" # 默认与底盘共用串口，也可独立配置
baudrate: int = 1000000
# 剩余配置略
@dataclass
class ChassisConfig:
"""底盘配置 - 从机器人配置文件读取"""
# 串口配置（Windows: COM3, Linux: /dev/ttyUSB0）
serial_port: str = "/dev/tty.usbmodem5AE60527771" # 默认与机械臂共用串口，也可独立配置
baudrate: int = 1000000
# 剩余配置略
更多配置选项说明详见 配置修改说明
快速查看系统中可用的串口、摄像头和麦克风设备，方便修改配置：
cd software
python tools/list_devices.py输出示例：
📟 串口: COM15
描述: USB-SERIAL CH340
📷 摄像头索引: 0
分辨率: 1920x1080
🎤 麦克风索引: 1
名称: 麦克风 (Realtek(R) Audio)
更多工具脚本（机械臂校准、模型下载等）详见 👉 工具脚本使用指南
首次使用或更换机械臂舵机后，需要先进行零点校准：
cd software
python tools/calibrate_arm.py按提示将机械臂各关节移动到零点位置，完成后校准数据会自动保存。
👉 详细说明请查看 工具脚本使用指南
cd software
python start_system.py这会启动三个服务：
- 底盘服务&机械臂服务 (ZeroMQ: tcp://127.0.0.1:5556 & tcp://127.0.0.1:5557)
- 视觉服务 (Camera PUB: tcp://127.0.0.1:5560)
- Web 控制端 (Flask: http://0.0.0.0:5000)
启动时会检查端口占用，如有占用会提示处理。
打开局域网内手机/电脑浏览器，访问：
http://<robot-ip>:5000
界面包含：
- 实时视频流（摄像头画面）
- 虚拟摇杆（左侧控制底盘移动）
- 紧急停止按钮（红色，触发后锁定底盘）
- 归位按钮（蓝色，解锁紧急停止）
使用 Xbox 手柄同时控制底盘和机械臂：
# 1. 启动底盘服务
cd software/src
python -m services.motion_service.chassis_service
# 2. 启动机械臂服务
python -m services.motion_service.arm_service
# 3. 启动游戏手柄控制
python -m applications.gamepad_control控制映射：
- 底盘：左摇杆（移动/旋转）+ LT/RT（平移）
- 机械臂：右摇杆（基座/伸缩）+ 十字键（升降/腕转）+ Y/A/B（腕翻）+ RB/LB（夹爪）
- 系统：Back（急停）/ Start（复位）
详细使用说明 👉 游戏手柄控制使用指南
通过 Picoclaw（小龙虾） AI 助手实现自然语言控制：
"让机器人前进 20 厘米"
"右转 90 度"
"机器人看到了什么？"
Picoclaw 会自动解析指令并控制机器人，支持底盘运动、机械臂控制、视觉查询等功能。
详情请查看 👉 用 Picoclaw 控制 HomeBot 完整指南
HomeBot 提供基于 YOLO26 的实时人体跟随功能，支持视觉伺服控制，让机器人自动跟随目标人体。
| 特性 | 说明 |
|---|---|
| 检测模型 | YOLO26-nano (~2.4MB) |
| 检测速度 | CPU 38ms/帧，比 YOLO11 快 43% |
| 跟踪算法 | IoU 匹配 + 卡尔曼滤波 |
| 控制算法 | 视觉伺服 (Visual Servoing) |
| 控制优先级 | auto=3（可被 emergency 抢占） |
启动系统服务后，在网页端点击人体跟随按钮即可，启动大约需要5-10秒钟（加载模型）。
- FOLLOWING: 正常跟随目标
- SEARCHING: 目标丢失，原地旋转搜索
- IDLE: 空闲状态
- PAUSED: 暂停状态
- 水平控制：目标在画面左侧 → 左转，右侧 → 右转
- 距离控制：目标太小（太远）→ 前进，太大（太近）→ 后退
- 丢失处理：短暂丢失时旋转搜索，完全丢失时停止
编辑 software/src/configs/config.py：
@dataclass
class HumanFollowConfig:
model_path: str = "models/yolo26n.pt"
target_distance: float = 1.0 # 目标距离（米）
kp_linear: float = 0.001 # 线速度 P 系数
kp_angular: float = 0.003 # 角速度 P 系数
max_linear_speed: float = 0.3 # 最大线速度
max_angular_speed: float = 0.8 # 最大角速度
max_tracking_age: int = 30 # 最大丢失帧数更多详情请查看 人体跟随使用指南。
- 自动连接 VisionService 获取摄像头画面
- 支持 MJPEG 实时流播放
- 断线自动检测，显示离线状态
- 点击紧急停止 → 底盘立即停止，进入锁定状态
- 锁定期间：
- 摇杆操作被忽略
- 底盘拒绝所有运动命令
- 按钮显示"已锁定"
- 点击归位 → 解除锁定，恢复正常控制
- WebSocket 状态 - 连接状态指示灯
- 仲裁器状态 - 底盘服务连接状态
- 视频状态 - LIVE / OFFLINE
- FPS 显示 - 摇杆指令发送频率
# 底盘服务
python -m services.motion_service.chassis_service [--port COM3]
# 机械臂服务
python -m services.motion_service.arm_service
# 视觉服务
python -m services.vision_service [--display]
# Web 控制端
python -m applications.remote_control [--host 0.0.0.0] [--port 5000]
# 人体跟随
python -m applications.human_follow [--display]
# 游戏手柄控制
python -m applications.gamepad_control [--controller 0] [--verbose]from services.vision_service import VisionSubscriber
import cv2
sub = VisionSubscriber("tcp://localhost:5560")
frame_id, frame = sub.read_frame() # 读取单帧
# 或持续读取
sub.read_loop(callback=process_frame)底盘控制命令：
{
"source": "web", # 控制源: web/voice/auto/emergency/home
"vx": 0.5, # 线速度 X (m/s)
"vy": 0.0, # 线速度 Y (m/s)
"vz": 0.3, # 角速度 Z (rad/s)
"priority": 1 # 优先级: 1=web, 2=voice, 3=auto, 4=emergency
}- AI 助手控制 - 通过 Picoclaw 用自然语言控制机器人
- 游戏手柄 - 使用 Xbox 手柄直接控制，详见 游戏手柄控制使用指南
可在后续迭代中添加：
- MQTT 桥接 - 云端远程控制
- 多机器人协同 - 分布式任务
- SLAM 导航 - 自主建图与定位
- 语音交互 - 集成大语言模型
- 模仿学习 - 兼容 LeRobot 框架
Last updated: 2026-03-17