# tennis_robot

**Repository Path**: linfei83/tennis_robot

## Basic Information

- **Project Name**: tennis_robot
- **Description**: 网球机器人树莓派端代码
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-10-09
- **Last Updated**: 2026-02-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 网球机器人

一个基于树莓派的智能网球拾取机器人系统，集成了计算机视觉、机器人控制和Web界面管理功能。

## 项目概述

这是一个网球机器人解决方案，包含以下核心功能：
- 基于YOLO的网球检测与跟踪
- 全向移动机器人控制系统
- Web界面远程控制
- 实时视频流处理
- 系统监控与通知服务

## 系统架构

```
tennis_robot/
├── web_server.py              # 主Web服务器程序
├── web_modules/               # Web模块化组件
│   ├── robot_controller.py    # 机器人控制器
│   ├── vision_processor.py    # 视觉处理器
│   ├── ball_tracker.py        # 网球跟踪器
│   └── ball_controller.py     # 球类控制器
├── base_robot/                # 机器人底层控制
│   ├── wheeltec_robot.py      # WheelTec机器人驱动
│   └── wheeltec_robot_config.py # 机器人配置
├── vision/                    # 计算机视觉模块
│   ├── tennis_detector.py     # 网球检测器
│   ├── camera_manager.py      # 摄像头管理
│   └── model/                 # YOLO模型
├── notice/                    # 通知服务
│   ├── notification_service.py # 通知服务
│   └── notifier.py            # 邮件通知器
├── templates/                 # Web模板
│   └── index.html             # 主界面
├── static/                    # 静态资源
└── requirements.txt           # 依赖包列表
```

## 核心功能

### 1. 智能网球检测
- **YOLO模型**: 使用TensorFlow Lite优化模型进行实时网球检测
- **高精度识别**: 支持多种环境下的网球识别
- **实时处理**: 优化的推理速度，适合树莓派等嵌入式设备

### 2. 机器人运动控制
- **全向移动**: 支持前后左右及旋转运动
- **精确定位**: 基于里程计的位置反馈
- **速度控制**: 可调节的运动速度和加速度
- **安全保护**: 紧急停止和碰撞检测

### 3. 自动拾取系统
- **智能跟踪**: 自动跟踪检测到的网球
- **路径规划**: 优化的移动路径算法
- **拾取统计**: 实时统计拾取数量和效率
- **模式切换**: 手动/自动模式切换

### 4. Web控制界面
- **实时视频流**: 低延迟的摄像头画面传输
- **键盘控制**: WASD键盘控制机器人移动
- **状态监控**: 实时显示系统状态和性能指标
- **响应式设计**: 支持手机、平板等移动设备

### 5. 系统监控
- **性能监控**: CPU、内存使用率实时监控
- **电池监控**: 机器人电池电压状态
- **通知服务**: 重要事件的邮件通知
- **日志记录**: 详细的系统运行日志

## 技术规格

### 硬件要求
- **主控**: 树莓派4B (推荐4GB内存)
- **摄像头**: USB摄像头或CSI摄像头
- **机器人底盘**: WheelTec全向移动底盘
- **通信**: USB串口通信
- **网络**: WiFi或以太网连接

### 软件环境
- **操作系统**: Ubuntu 20.04+ / Raspberry Pi OS
- **Python版本**: Python 3.8+
- **深度学习**: TensorFlow Lite 2.13+
- **计算机视觉**: OpenCV 4.8+
- **Web框架**: Flask + Flask-SocketIO

## 快速开始

### 1. 环境准备

```bash
# 克隆项目
git clone <repository_url>
cd tennis_robot

# 安装依赖
pip install -r requirements.txt

# 或使用uv (推荐)
uv sync
```

### 2. 硬件连接

1. 连接机器人底盘控制器到树莓派USB端口
2. 连接摄像头到树莓派
3. 确保机器人底盘电源正常

### 3. 配置设置

```bash
# 检查串口设备
ls /dev/ttyUSB* /dev/wheeltec_controller

# 设置串口权限
sudo usermod -a -G dialout $USER
sudo chmod 666 /dev/ttyUSB0
```

### 4. 启动系统

```bash
# 启动Web服务器
python web_server.py
```

### 5. 访问界面

在浏览器中访问: `http://树莓派IP:5000`

## 使用指南

### Web界面操作

1. **启动系统组件**
   - 点击"启动机器人"按钮启动机器人控制
   - 点击"启动视觉"按钮启动摄像头和检测

2. **手动控制**
   - 使用WASD键控制机器人移动
   - 空格键紧急停止
   - 实时查看速度和位置信息

3. **自动拾取**
   - 点击"开启拾取模式"启动自动拾取
   - 机器人将自动寻找并移向网球
   - 查看拾取统计和效率信息

4. **系统监控**
   - 查看CPU和内存使用情况
   - 监控机器人电池电压
   - 接收系统通知和警告

### API接口

系统提供RESTful API接口：

```bash
# 机器人控制
POST /api/robot/start          # 启动机器人
POST /api/robot/stop           # 停止机器人
POST /api/robot/velocity       # 设置速度

# 视觉系统
POST /api/vision/start         # 启动视觉
POST /api/vision/stop          # 停止视觉

# 拾取系统
POST /api/pickup/toggle        # 切换拾取模式
GET  /api/pickup/status        # 获取拾取状态
POST /api/pickup/reset_stats   # 重置统计

# 系统监控
GET  /api/system/stats         # 获取系统状态
POST /api/system/restart       # 重启服务
```

## 配置说明

### 机器人配置

在 `base_robot/wheeltec_robot_config.py` 中配置：

```python
# 串口配置
usart_port_name = "/dev/wheeltec_controller"
serial_baud_rate = 115200

# 运动参数
odom_x_scale = 1.0
odom_y_scale = 1.0
```

### 视觉系统配置

在 `vision/config/` 目录中配置：

```python
# 检测参数
confidence_threshold = 0.6
model_path = "vision/model/model_float32_myv8.tflite"

# 摄像头参数
camera_width = 640
camera_height = 480
fps = 30
```

### 通知服务配置

在 `notice/config.ini` 中配置邮件通知：

```ini
[email]
smtp_server = smtp.gmail.com
smtp_port = 587
sender_email = your_email@gmail.com
sender_password = your_app_password
receiver_email = receiver@gmail.com
```

## 故障排除

### 常见问题

1. **串口连接失败**
   ```bash
   # 检查设备
   ls /dev/ttyUSB*
   
   # 检查权限
   sudo chmod 666 /dev/ttyUSB0
   
   # 添加用户组
   sudo usermod -a -G dialout $USER
   ```

2. **摄像头无法启动**
   ```bash
   # 检查摄像头
   lsusb | grep -i camera
   
   # 测试摄像头
   v4l2-ctl --list-devices
   ```

3. **模型加载失败**
   ```bash
   # 检查模型文件
   ls -la vision/model/
   
   # 检查TensorFlow Lite安装
   python -c "import tflite_runtime.interpreter as tflite"
   ```

4. **网络连接问题**
   ```bash
   # 检查端口占用
   netstat -tulpn | grep :5000
   
   # 检查防火墙
   sudo ufw status
   ```


## 开发指南

### 添加新功能

1. **扩展API接口**
   ```python
   @app.route('/api/new_feature', methods=['POST'])
   def new_feature():
       # 实现新功能
       return jsonify({'status': 'success'})
   ```

2. **添加新的检测算法**
   ```python
   class NewDetector:
       def __init__(self):
           # 初始化检测器
           pass
       
       def detect(self, frame):
           # 实现检测逻辑
           return results
   ```

3. **扩展机器人控制**
   ```python
   def new_control_method(self, params):
       # 实现新的控制方法
       return self.robot.execute_command(params)
   ```

### 测试

```bash
# 运行单元测试
python -m pytest tests/

# 测试特定模块
python -m pytest tests/test_vision.py

# 性能测试
python tests/performance_test.py
```

## 系统服务

### 创建系统服务

```bash
# 创建服务文件
sudo nano /etc/systemd/system/tennis-robot.service
```

```ini
[Unit]
Description=Tennis Robot Web Server
# 确保在网络准备就绪后启动
After=network.target

[Service]
# 使用 'ubuntu'用户和用户组来运行此服务
User=ubuntu
Group=ubuntu

# 设置工作目录，这对于脚本中使用了相对路径的情况非常重要
WorkingDirectory=/home/ubuntu/project/tennis_robot

# 您的启动命令
ExecStart=/home/ubuntu/project/tennis_robot/.venv/bin/python /home/ubuntu/project/tennis_robot/web_server.py

# 设置服务在失败时自动重启
Restart=on-failure
# 可以根据需要设置为 always
# Restart=always

[Install]
# 定义服务在哪个系统目标下启用，multi-user.target 意味着在系统进入多用户模式时启动
WantedBy=multi-user.target

```

```bash
# 手动启动服务
sudo systemctl start tennis-robot.service
# 检查服务状态
sudo systemctl status tennis-robot.service
# 停止服务
sudo systemctl stop tennis-robot.service
# 重启服务
sudo systemctl restart tennis-robot.service
# 取消开机自启
sudo systemctl disable tennis-robot.service
# 查看实时日志
sudo journalctl -u tennis-robot.service -f
```