Skip to content

Timekeeperxxx/BotDog

BranchesTags

Repository files navigation

BotDog 机器狗控制系统

Version Python License

🎯 项目简介

BotDog 是一个完整的四足机器狗远程控制系统，提供实时控制、遥测监控、AI 告警和可视化界面。

核心功能

  • ✅ 实时控制 - 键盘 + 游戏手柄（Xbox/PlayStation）
  • ✅ 遥测监控 - 实时姿态、位置、温度、电池
  • ✅ AI 告警 - 温度异常自动检测和告警
  • ✅ 配置管理 - 可视化配置界面，13 个配置项
  • ✅ 视频流 - WebRTC 实时视频传输
  • ✅ 事件系统 - 实时事件推送和历史记录

技术栈

后端:

  • Python 3.10+
  • FastAPI（Web 框架）
  • SQLAlchemy（ORM）
  • WebSocket（实时通信）
  • WebRTC（视频流）
  • MAVLink（机器人通信协议）

前端:

  • React 18
  • TypeScript
  • Vite（构建工具）
  • WebSocket（实时数据）
  • WebRTC（视频流）

🚀 快速开始

1. 环境要求

# Python 3.10+
python --version

# Node.js 18+
node --version
npm --version

2. 安装依赖

# 创建并激活 Python 虚拟环境（首次运行）
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或者在 Windows 上使用: .venv\Scripts\activate

# 后端依赖
pip install -r requirements.txt

# 前端依赖
cd frontend
npm install

3. 启动服务

# 激活虚拟环境（如果尚未激活）
source .venv/bin/activate  # Linux/Mac

# 后端（终端 1）- 从项目根目录启动
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

# 或者进入 backend 目录启动
cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 前端（终端 2）- 新开一个终端
cd frontend
npm run dev

4. 访问界面

打开浏览器访问: http://localhost:5173

🎮 控制方式

游戏手柄控制（推荐）

支持的控制器:

  • Xbox 360 / Xbox One / Xbox Series X/S
  • PlayStation 4 / PlayStation 5
  • 任何标准映射的 USB 游戏手柄

控制映射:

  • 左摇杆 Y: 前进/后退
  • 左摇杆 X: 左右平移
  • 右摇杆 Y: 上下控制
  • LB/RB: 左右转向

使用步骤:

  1. 连接游戏手柄到电脑
  2. 打开浏览器，访问前端页面
  3. 按下手柄上的任意按钮（激活 Gamepad API）
  4. 点击"启用控制"按钮
  5. 开始使用摇杆控制机器狗

键盘控制（备用）

  • W/S: 前进/后退
  • A/D: 左右平移
  • Q/E: 升降
  • ←/→: 转向

⚙️ 配置管理

配置界面

点击顶部状态栏的 "⚙️ 配置" 按钮打开配置界面。

配置类别

后端配置 (5 项):

  • thermal_threshold - 高温告警阈值
  • heartbeat_timeout - 心跳超时
  • control_rate_limit_hz - 控制速率限制
  • ws_max_clients_per_ip - WebSocket 连接限制
  • video_watchdog_timeout_s - 视频看门狗超时

前端配置 (4 项):

  • ui_alert_ack_timeout_s - 告警确认超时
  • telemetry_display_hz - 遥测显示刷新率
  • ui_lang - 界面语言
  • ui_theme - UI 主题

存储配置 (3 项):

  • snapshot_retention_days - 快照保留天数
  • max_snapshot_disk_usage_gb - 快照最大占用
  • telemetry_retention_days - 遥测数据保留天数

📊 系统架构

┌───────────────────────────────────────────────────────┐
│                       浏览器界面                        │
│  ┌────────────────────────────────────────────────┐   │
│  │  HeaderBar  │  VideoSection  │  ControlPanel │   │
│  └────────────────────────────────────────────────┘   │
│  ┌────────┐                                        │
│  │SnapshotList (告警快照)                       │
│  └────────┘                                        │
└───────────────────────────────────────────────────────┘
                            │
                    WebSocket / WebRTC
                            │
┌───────────────────────────────────────────────────────┐
│                    FastAPI 后端                      │
│  ┌───────────────┐  ┌───────────────┐  ┌─────────┐ │
│  │  WebSocket   │  │  WebRTC信令   │  │MAVLink  │ │
│  │   Handler     │  │   Server      │  │ Gateway │ │
│  └───────────────┘  └───────────────┘  └─────────┘ │
│  ┌───────────────┐  ┌───────────────┐                │
│  │ AlertService  │  │ConfigService  │  Database  │ │
│  └───────────────┘  └───────────────┘  (SQLite)  │
└───────────────────────────────────────────────────────┘
                            │
                    MAVLink / Serial
                            │
┌───────────────────────────────────────────────────────┐
│              机器狗硬件（摄像头、MAVLink 设备）      │
└───────────────────────────────────────────────────────┘

🧪 验收测试

# 运行所有验收测试（UC-01 到 UC-05）
python acceptance_test.py

测试覆盖

  • ✅ UC-01: 系统健康检查
  • ✅ UC-02: 遥测 WebSocket 连接
  • ✅ UC-03: 事件 WebSocket 连接
  • ✅ UC-04: 配置管理 API
  • ✅ UC-05: 告警系统功能

当前通过率: 100% (5/5) 🎉

📚 文档

详细文档请查看 docs/ 目录：

核心文档

技术规范

最新功能

部署指南

🔧 开发命令

提示: 所有后端命令都需要先激活虚拟环境：

source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

后端

# 开发模式（热重载）
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

# 生产模式
uvicorn backend.main:app --host 0.0.0.0 --port 8000 --workers 4

# 初始化配置数据库
python init_config.py

# 运行单元测试
pytest tests/

前端

# 开发模式
cd frontend
npm run dev

# 生产构建
npm run build

# 预览生产构建
npm run preview

数据库

# 初始化数据库表
python init_config.py

# 清理数据库（谨慎使用）
rm -f data/botdog.db

📁 项目结构

BotDog/
├── backend/              # FastAPI 后端
│   ├── main.py          # 主应用入口
│   ├── database.py      # 数据库连接
│   ├── models*.py       # SQLAlchemy 模型
│   ├── services_*.py    # 业务服务层
│   └── ws_*.py          # WebSocket 处理器
│
├── frontend/            # React 前端
│   ├── src/
│   │   ├── components/   # React 组件
│   │   ├── hooks/        # React Hooks
│   │   ├── types/        # TypeScript 类型
│   │   └── utils/        # 工具函数
│   └── package.json
│
├── docs/                # 项目文档
├── tests/               # 后端测试
├── data/                # 数据库文件
├── acceptance_test.py   # 验收测试
└── requirements.txt     # Python 依赖

🚢 部署

前置条件

  1. 机器狗端需要:

    • MAVLink 设备（串口或 UDP 连接）
    • 摄像头设备（/dev/video0）
    • Python 3.10+ 环境
    • GStreamer 库

  2. 操作端需要:

    • 现代浏览器（Chrome/Firefox/Edge）
    • 网络连接到机器狗
    • 游戏手柄（可选）

详细部署步骤请参考: docs/24_deployment_testing_guide.md

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

开发流程

  1. Fork 本仓库
  2. 创建功能分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m 'Add some AmazingFeature')
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 开启 Pull Request

提交规范

📄 许可证

MIT License

👥 作者

  • 开发者: Claude Code + Human collaborator
  • 项目: BotDog 机器狗控制系统
  • 版本: v5.0

🎉 致谢

感谢所有开源项目的贡献者：

  • FastAPI
  • React
  • WebRTC
  • MAVLink
  • GStreamer
  • aiortc

状态: ✅ 生产就绪 最后更新: 2026-03-06 仓库: https://github.com/Timekeeperxxx/BotDog

About

西部泰力机器狗

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages