Desktop-Wanderer是一款在LeKiwi机器人硬件上，基于视觉引导的移动操作机器人系统，能够自主搜索、跟踪和抓取网球。
基于YOLO神经网络实时检测网球
支持50 FPS处理频率
硬件加速：支持ONNX CPU推理和Atlas 310B NPU推理
视觉伺服控制：机器人自动导航至目标位置
智能搜索：球消失时根据最后位置进行方向性搜索
分层控制策略：优先旋转对齐，再进行前后移动
ACT模式：基于Action Chunking Transformer的端到端学习策略
逆运动学模式：基于P控制的8步抓取序列
50 FPS精确控制循环
状态机架构：SEARCH ↔ CATCH状态切换
Desktop-Wanderer/
├── src/
│ ├── main.py # 主控制循环 ，控制整个程序流程
│ ├── setup.py # Python 包管理文件，用于安装项目，不参与运行，一般不需要修改
│ ├── robot_setup.py # 机器人接口 ，初始化机器人硬件连接
│ ├── move_controller.py # 移动控制
│ ├── arm_act_controller.py # ACT策略控制器 ，机械臂的高级动作策略（抓取、放置）
│ ├── arm_inverse_controller.py # 逆运动学控制器 ，计算机械臂关节角度以达到目标位置
│ ├── yolov/ # YOLO检测模块 ，用摄像头识别物体（网球）
│ └── lekiwi/ # 硬件抽象层 ，与真实电机、摄像头通信的底层代码
├── config.yaml # 启动时的配置文件，用YAML格式存储各种可调参数。
└── README.md # 说明文档应用层：控制决策 —— 主控制逻辑和状态机
控制层：动作规划 —— 视觉处理、导航、机械臂控制
抽象层：将控制信号传递给硬件 —— 机器人接口、配置管理
硬件层：具体执行动作 —— 电机控制、相机访问
| 物理文件结构 (系统架构) | 逻辑层次结构 (分层架构) |
|---|---|
| main.py | 应用层(决策逻辑) |
| move_controller.py arm_*_controller.py yolov/ |
控制层(算法控制) |
| robot_setup.py setup.py |
抽象层(硬件接口) |
| lekiwi/ | 硬件层(物理控制) |
配置加载流程:
程序启动时自动在setup.py中通过 init_app() 函数加载
使用单例模式，只加载一次
通过 get_*() 函数访问配置值
关键配置项:
port: /dev/ttyACM0 # 串口设备
fps: 20 # 控制循环频率
hardware_mode: normal # yolo的硬件模式：normal/310b/rk3588
control_mode: inverse # 控制模式：inverse/act
log_level: INFO # 日志级别：DEBUG/INFO/WARNING/ERRORport: /dev/ttyACM0 （1）作用：指定机器人串口通信设备路径
（2）如何查找正确的串口号:
#Linux
ls /dev/tty* | grep -E "ACM|USB"（3）常见问题：串口号错误；权限不足
fps: 20 （1）作用: 设置主控制循环的执行频率（帧率）
（2）注意事项：FPS不能设置过高，否则可能导致循环执行时间超过设定间隔。实际FPS受限于图像处理和控制计算的时间
log_level: INFO （1）作用: 设置日志输出的详细程度
（2）可选值：
DEBUG: 最详细，包含所有调试信息
INFO: 一般信息，默认推荐
WARNING: 只显示警告和错误
ERROR: 只显示错误信息
hardware_mode: normal （1）作用：选择YOLO目标检测的硬件加速模式，对应的模型文件在 src/yolov/models/ 目录
（2）可选值：
normal:模型为 tennis.onnx，CPU模式，使用ONNX Runtime在CPU上推理
rk3588:模型为 tennis.rknn，RK3588 NPU模式，使用瑞芯微NPU加速
310b:模型为 tennis.om，Atlas 310B NPU模式，使用华为昇腾NPU加速
control_mode: inverse （1）作用: 选择机械臂控制策略
（2）可选值：
a. inverse: 逆运动学控制模式（默认）
b. act: ACT学习策略模式
inverse 模式 - 逆运动学控制 工作原理:
使用预定义的8步抓取动作序列
通过逆运动学计算将目标坐标转换为关节角度
使用P控制（比例控制）实现精确位置控制
特点:
不需要预训练模型
控制逻辑清晰，易于调试
可预测性强
需要精确的机械臂参数（长度、角度等）
act 模式 - ACT学习策略 工作原理:
使用预训练的ACT（Action Chunking Transformer）模型
端到端学习：直接从图像到动作
基于LeRobot框架和训练数据
特点:
可以学习复杂的抓取策略
适应性强，能处理不同场景
需要预训练模型文件
需要LeRobot框架和PyTorch
requirements.txt 关键依赖:
ultralytics - YOLO目标检测
torch - PyTorch（ACT模式需要）
opencv-python - 图像处理
pyserial - 串口通信
lerobot - 机器人学习框架
注意事项:
（1）检查你的Python环境（需要Python 3.10）
（2）安装所有依赖：pip install -r requirements.txt
（3）验证关键库是否正确安装