Robocon/RC_Legged
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[init] RC_Legged 项目初始化

Browse Source
This commit is contained in:
eastzio
2026-06-25 10:49:09 +08:00
commit c80ac936c7
3 changed files with 355 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+40
View File
@@ -0,0 +1,40 @@
# 编译产出
build/
devel/
install/
*.o
*.elf
*.hex
# Python
__pycache__/
*.pyc
*.pyo
.venv/
venv/
# IDE
.vscode/
.idea/
*.swp
*.swo
# 训练产出
05_software/rl_training/logs/
05_software/rl_training/checkpoints/
wandb/
# ROS
*.bag
*.mcap
# 系统
.DS_Store
Thumbs.db
# 本地参考项目（不纳入版本管理）
00_reference/
# 机械备份
*.bak
*.old
README.md
+28
View File
@@ -0,0 +1,28 @@
# RC_Legged
四轮足强化学习机器狗项目 —— 从机械到代码，从 0 到 1。
## 目录结构
```
RC_Legged/
├── 00_reference/ # 参考项目与文档
├── 01_doc/ # 项目文档
├── 02_mechanical/ # 机械设计
├── 03_hardware/ # 硬件电路
├── 04_firmware/ # 嵌入式固件
├── 05_software/ # 上层软件（RL/ROS）
├── 06_assets/ # 媒体资源
├── 项目规范.md # 项目规范
└── README.md
```
## Gitea 仓库
`https://git.zeitvex.com/Robocon/RC_Legged.git`
## 参考项目
- EDULITE_A3 — 教育级四足机器人
- OpenDog — 开源四足机器狗
- reBot-DevArm — 开源机械臂
项目规范.md
+287
View File
@@ -0,0 +1,287 @@
# RC_Legged 项目规范
## 1. 项目概述
RC_Legged 是一个四轮足强化学习（RL）机器狗项目，涵盖机械设计、硬件电路、嵌入式软件和控制算法全栈开发。
### 仓库地址
- **Gitea 远程仓库**: `https://git.zeitvex.com/Robocon/RC_Legged.git`
- **SSH**: `git@git.zeitvex.com:Robocon/RC_Legged.git`
---
## 2. 仓库目录结构规范
```
RC_Legged/
├── 00_reference/ # 参考项目与文档（只读，不改动）
├── 01_doc/ # 项目文档（设计文档、会议记录、需求文档）
├── 02_mechanical/ # 机械设计（SolidWorks/STL/URDF/STEP）
│ ├── CAD/ # 源文件
│ ├── STL/ # 3D 打印文件
│ └── URDF/ # URDF 描述文件
├── 03_hardware/ # 硬件电路设计（KiCad/Altium）
│ ├── PCB/ # PCB 工程文件
│ ├── BOM/ # 物料清单
│ └── datasheet/ # 芯片/模块数据手册
├── 04_firmware/ # 嵌入式固件（STM32/ESP32 等）
│ ├── motor_driver/ # 电机驱动固件
│ └── sensor_board/ # 传感器板固件
├── 05_software/ # 上层软件
│ ├── rl_training/ # 强化学习训练代码
│ │ ├── configs/ # 训练配置
│ │ ├── envs/ # 环境定义
│ │ └── logs/ # 训练日志（.gitignore）
│ ├── ros_ws/ # ROS 工作空间
│ │ ├── src/
│ │ └── scripts/
│ └── utils/ # 通用工具脚本
├── 06_assets/ # 媒体资源（渲染图、演示视频等）
├── .gitignore
├── .pre-commit-config.yaml # Pre-commit 配置
├── README.md # 项目总览
└── 项目规范.md # 本文件
```
---
## 3. 分支管理策略
### 3.1 分支结构
```
main ─────●────────────●────────────────●── 最稳定，仅里程碑合并
\ / /
main-nightly ──●────●──●────●─────────●─────────── 每日构建/集成测试
\ \ / \ /
task-<name> ─────●──●────────●──●──────────●──── 具体任务分支（实验/算法/feature）
\ /
task-<name>-infra ─────────●────────────────●─────── 核心代码修补分支（紧急修复）
```
### 3.2 分支职责
| 分支 | 角色 | 说明 |
|------|------|------|
| `main` | 项目所有负责人 | 最保守，只合并经过充分验证的里程碑版本。每次合并应为 **no-ff**（保留合并记录）。 |
| `main-nightly` | 主要维护人员 | 日常集成测试目标。任务分支达标后先合入此分支，稳定后再合入 `main`。 |
| `task-<name>` | 具体任务开发者 | 自己维护，主要用于 task 配置和实验记录。**只允许修改对应子目录内的文件**。 |
| `task-<name>-infra` | 任务开发者（极端情况） | 当必须修改 `main-nightly` 核心代码才能跑通当前训练时使用，快速验证后合入 `main-nightly`。 |
### 3.3 分支操作规则
1. **`main` 分支**：禁止直接推送。只能通过 Pull Request 从 `main-nightly` 合并，且必须经过 Code Review。
2. **`main-nightly` 分支**：原则上禁止直接推送。任务分支通过 PR 合入，需经过基本验证。
3. **`task-*` 分支**：从 `main-nightly` 创建，开发者自行推送。
4. **`task-*-infra` 分支**：从 `main-nightly` 创建，只包含核心代码改动，**不允许包含任何 task 配置文件**，合入后立即删除。
5. **配置代码与逻辑代码分离**：训练 config 文件和核心逻辑代码必须在不同的分支维护。只允许 config 分支从 logic 分支 merge。在里程碑之前，logic 分支不吸收任何 config 分支改动。
---
## 4. 提交（Commit）规范
### 4.1 Commit Message 格式
```
[tag] 一句话描述（不超过 72 字符）
（空一行后可补充详细说明，例如改动动机、注意事项等）
```
### 4.2 标签规则
| 标签 | 含义 | 示例 |
|------|------|------|
| `[add]` | 新增功能/文件 | `[add] 四足逆运动学求解器` |
| `[update]` | 修改已有功能 | `[update] 优化步态切换逻辑` |
| `[fix]` | 修复 Bug | `[fix] 电机 CAN 通讯超时处理` |
| `[remove]` | 删除功能/文件 | `[remove] 废弃旧版遥控器协议` |
| `[format]` | 代码格式化/重构 | `[format] 统一命名规范` |
| `[log]` | 实验记录/日志提交 | `[log] 第3轮训练结果，reward 收敛至0.85` |
| `[doc]` | 文档相关 | `[doc] 添加CAN总线协议说明` |
| `[hardware]` | 硬件相关改动 | `[hardware] PCB v1.2 修改电源走线` |
| `[mechanical]` | 机械相关改动 | `[mechanical] 大腿连杆加厚2mm` |
### 4.3 Commit 原则
1. **一个 Commit 只做一件事**。如果一次改动了多个不相关的问题，必须拆分为多个 commit。
2. **Commit Message 必须说清楚改动内容**。只看 message 就能理解改了什么，否则需要修正。
3. **Task 配置文件和核心代码不得混在同一个 commit 中**。
4. **未通过 Pre-commit 检查的代码不允许 commit**。
5. **如果 commit 历史有问题，必须先修复再继续开发**。
---
## 5. 代码质量规范
### 5.1 Pre-commit 自动检查
- 使用 [pre-commit](https://pre-commit.com/) 工具实现提交前自动检查。
- 安装：`pip install pre-commit`
- 启用：在仓库根目录执行 `pre-commit install`
- 手动运行：`pre-commit run --all-files`
- 所有检查项必须全部通过（绿色/蓝色）方可 commit。
- `.pre-commit-config.yaml` 需包含：代码格式化（Clang-Format / Black）、Python 语法检查（Flake8 / Ruff）、YAML 检查、文件末尾换行符检查等。
### 5.2 代码风格
- **C/C++**：遵循 Google C++ Style Guide，使用 `.clang-format` 统一格式。
- **Python**：遵循 PEP 8，使用 Black 格式化。
- **ROS**：遵循 ROS C++/Python 编码规范。
- **命名**：
- 文件名：小写 + 下划线（`imu_driver.cpp`）
- 类名：大驼峰（`ImuDriver`）
- 函数/变量：小写 + 下划线（`read_imu_data()`）
- 宏/常量：全大写 + 下划线（`IMU_TIMEOUT_MS`）
### 5.3 接口变更流程
1. 首先尝试在现有接口定义下完成需求。
2. 如必须修改接口，向项目负责人 + 所有使用者提交申请。
3. 通过后，使用 **Pull Request** 标记变更过程，关联相关 Issue。
---
## 6. Pull Request 与代码审查（Code Review）
### 6.1 PR 流程
1. 在 `task-*` 或 `task-*-infra` 分支上完成开发并推送。
2. 在 Gitea 上创建 Pull Request：
- **来源分支**：`task-*` → **目标分支**：`main-nightly`
- **来源分支**：`main-nightly` → **目标分支**：`main`
3. PR 标题格式：`[tag] 简短描述`（与 commit message 一致）。
4. PR 描述中说明：改动内容、验证方式、影响范围。
### 6.2 审查要求
- 必须由至少 1 名项目成员 Review 后方可合并。
- 审查重点：功能正确性、接口兼容性、代码风格、是否包含无关文件。
- 如有修改意见，PR 作者修改后重新请求 Review。
### 6.3 合并方式
- 合入 `main-nightly`：使用 **Squash Merge**（保持 nightly 历史清晰）。
- 合入 `main`：使用 **Merge Commit (no-ff)**（保留完整分支历史）。
---
## 7. Gitea 配置
### 7.1 仓库设置
- **可见性**：私有（Private）
- **默认分支**：`main`
- **分支保护**（`main` 分支）：
- 禁止直接推送
- 要求 PR 审查通过后才能合并
- 要求 PR 必须基于最新 `main`
- 禁用强制推送
### 7.2 初始推送
```bash
git init
git checkout -b main
git add .
git commit -m "[init] RC_Legged 项目初始化"
git remote add origin https://git.zeitvex.com/Robocon/RC_Legged.git
git push -u origin main
```
---
## 8. 硬件测试规范
### 8.1 真机测试要求
1. **全程录像**：每次真机测试必须有独立相机全程拍摄视频。
2. **ROS Bag 记录**：完整系统测试时必须用 ROS Bag 记录所有 message 数据。
- 使用 `ros2 bag record -s mcap -o <bag_name> /topic1 /topic2 ...`
- 推荐编写 `rosbag.sh` 脚本自动记录所有传感器数据。
- 所有与项目相关的电脑需安装 [Foxglove Studio](https://foxglove.dev/) 用于查看 bag。
3. **可视化配置**：所有 ROS 系统必须配置 RViz + `robot_state_publisher` + `joint_state_publisher`。
### 8.2 急停方案
所有真机测试脚本必须包含：
- 除 `Ctrl+C` 外的独立急停机制（如遥控器急停按钮）。
- 急停触发后立即进入 **Damping Mode**，无任何等待延迟。
- 推荐方案：控制程序监听遥控器急停信号，触发后立即终止程序。
---
## 9. .gitignore 示例
```gitignore
# 编译产出
build/
devel/
install/
*.o
*.elf
*.hex
# Python
__pycache__/
*.pyc
*.pyo
.venv/
venv/
# IDE
.vscode/
.idea/
*.swp
*.swo
# 训练产出
05_software/rl_training/logs/
05_software/rl_training/checkpoints/
wandb/
# ROS
*.bag
*.mcap
# 系统
.DS_Store
Thumbs.db
# 机械
*.sldprt
*.sldasm
*.step
*.stp
```
---
## 10. 项目里程碑工作流
```
[日常开发]
task-xxx 分支开发 → 提交 → 推送 → PR → Code Review → 合入 main-nightly
[里程碑发布]
main-nightly 经过充分测试
→ 创建 PR: main-nightly → main
→ 项目负责人 Review
→ 合入 main
→ 创建 Git Tag: v1.0.0, v1.1.0, ...
```
---
## 11. 参考项目
| 项目 | 类型 | 地址 |
|------|------|------|
| EDULITE_A3 | 四足机器人 | `00_reference/EDULITE_A3/` |
| OpenDog | 四足机器人 | `00_reference/open-dog/` |
| reBot-DevArm | 机械臂 | `00_reference/reBot-DevArm/` |
---
*本规范参考上述开源项目及行业最佳实践编写，随项目推进持续完善。*