# OmniRobLab-Hardware

**Repository Path**: tinymal/omni-rob-lab-hardware

## Basic Information

- **Project Name**: OmniRobLab-Hardware
- **Description**: 机器人底层所有驱动，USB-CAN等，传感器读取
- **Primary Language**: C
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-25
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# hardware_task_usbcan_o

人形机器人硬件控制程序，运行在 ARM64 Linux 平台（Radxa / Odroid 等）。

## 交叉编译环境

在 Windows 上用 Clang + lld 交叉编译 ARM64 Linux 程序，无需 WSL / Docker。

### 依赖

| 组件 | 版本 | 路径 |
|------|------|------|
| MSYS2 | — | `C:\msys64` |
| Clang | 22.x | `C:\msys64\mingw64\bin\clang.exe` |
| CMake | 4.x | `C:\msys64\mingw64\bin\cmake.exe` |
| Ninja | — | `C:\msys64\mingw64\bin\ninja.exe` |
| lld | — | `C:\msys64\mingw64\bin\ld.lld.exe` |

MSYS2 镜像源配置为清华 TUNA。

### sysroot

ARM64 系统库位于 `build/sysroot/`，从目标设备（Ubuntu 20.04 arm64）直接拉取，包含：

- glibc 2.31（libc.so / libc.a / libc_nonshared.a）
- libstdc++ (GCC 9)
- libpthread-2.31.so
- libboost-system 1.71
- libudev

特殊处理：
- `libpthread.a` → 空存根（glibc 2.31 中 pthread 仍由 libpthread.so 提供，静态库含 ld-linux 内部符号）
- `libpthread.so` → libpthread-2.31.so 的文件副本（Windows 不支持符号链接）
- `libstackchk.a` → stub，提供 `__stack_chk_guard` / `__pointer_chk_guard_local`（运行时由 ld-linux 覆盖）
- `libc.so` → libc.so.6 的文件副本（lld 不支持 GNU ld 脚本）

## 编译

### 本机 Linux 编译（推荐开发调试）

```bash
bash build.sh              # 普通硬件模式（产物 → build/）
bash build.sh --sim=RLBOYV3    # MuJoCo 仿真模式 — RLBOYV3（产物 → build_sim/）
bash build.sh --sim=RLBOYV2   # MuJoCo 仿真模式 — RLBOYV2
bash build.sh --sim=Lingloong  # MuJoCo 仿真模式 — Lingloong
bash build.sh --sim=<ROBOT> --clean  # 清除重建（仿真模式）
bash build.sh --clean      # 清除重建（普通模式）
```

仿真模式会自动检测 MuJoCo 库并创建软链接，无需手动配置。

### Windows 交叉编译（ARM64 部署）

```powershell
# 增量编译
powershell -ExecutionPolicy Bypass -File run_cmake_clang.ps1

# 清除重建
powershell -ExecutionPolicy Bypass -File run_cmake_clang.ps1 -Clean
```

脚本自动完成 CMake Configure + Ninja Build，产物输出到 `build-clang/`。

### 仿真模式 (SIM)

通过 CMake option `-DSIM=ON` 控制，默认 OFF。源码中用 `#ifdef SIM` 条件编译：

- **仿真线程** `sim_test/mujoco_sim_thread.cpp`：替换 `Thread_CAN`，用 MuJoCo 物理引擎模拟机器人动力学
- **数据对接**：直接操作 `motor_chassis[ch][j]` 结构体，与共享内存接口完全兼容
- **PD 控制**：在仿真线程内计算 `tau = kp*(set_q - q_now) - kd*qd_now + set_t`
- **IMU 仿真**：MuJoCo 传感器输出写入 `imu_o` 和 `spi_rx`，对控制端透明
- **多机器人支持**：RLBOYV3 (10DOF)、RLBOYV2 (10DOF)、Lingloong (28DOF)
- **关节映射**：`motor_chassis[ch][j]` → MuJoCo actuator，每个机器人独立映射
- **视角跟踪**：相机自动跟踪机器人基座位置
- **鼠标交互**：双击选择机器人，拖拽施加外力/力矩

仿真模式依赖：
```
MuJoCo >= 3.2  (pip3 install mujoco)
```

### MuJoCo 独立验证（Python）

`sim_test/RL_BOYV3/` 下提供 Python 脚本，可脱离 C++ 框架独立验证模型：

```bash
cd sim_test/RL_BOYV3
python3 verify_mujoco.py   # 关节检查 + 固定基座站立 + 自由基座测试
```

模型文件：`sim_test/RL_BOYV3/xmls/rl_boyv3.xml`（MJCF 格式，10 DOF 腿部）

### 启动仿真

```bash
bash run_sim.sh                          # 默认 RLBOYV3, 打开可视化
bash run_sim.sh --robot=RLBOYV2         # 指定机器人
bash run_sim.sh --robot=Lingloong        # Lingloong 人形机器人
bash run_sim.sh --no-viewer              # 无头模式
bash run_sim.sh --no-build               # 跳过编译，直接运行上次产物
```

切换机器人时自动检测并全量重编，同机器人增量编译。

### 可视化快捷键

| 按键 | 功能 |
|------|------|
| F1 | 显示/隐藏坐标系 |
| F2 | 显示/隐藏接触力 |
| F3 | 显示/隐藏质心 |
| F4 | 显示/隐藏执行器 |
| F5 | 显示/隐藏肌腱 |
| F6 | 显示/隐藏关节标签 |
| F7 | 切换渲染模式 (实体/透明) |
| F8 | 显示/隐藏惯量椭球 |
| F9 | 切换重力 |
| F10 | 显示/隐藏机器人网格 |
| F11 | 显示所有快捷键 |
| P | 切换悬挂模式 (释放/锁定) |
| Space | 暂停/继续仿真 |
| J | 切换虚拟遥控器 |
| Esc | 关闭窗口 |

### 鼠标操作

| 操作 | 功能 |
|------|------|
| 左键拖拽 | 旋转视角 |
| 右键拖拽 | 缩放 |
| 中键拖拽 | 平移 |
| 滚轮 | 缩放 |
| **双击** | 选择机器人 (base_link) |
| **双击后拖拽** | 施加外力/力矩 |

### 虚拟遥控器

| 按键 | 功能 |
|------|------|
| WASD | 左摇杆 (ch0/ch1) |
| Q/E | 转向 (ch2) |
| ↑/↓ | 右摇杆Y (ch3) |
| 1-8 | 按键 (A/B/X/Y/Start/Back/LR/UD) |

## 编译产物

### 本机 Linux（build/ 或 build_sim/）

| 文件 | 类型 | 说明 |
|------|------|------|
| `hardware_task_tinker_usbcan_o` | ELF64 x86_64 PIE | 主程序 |
| `motors/Gripper/Gripper_sdk/libgripper_sdk.so` | SO x86_64 | 灵巧手 SDK |
| `output/libserial.a` | 静态库 | serial 串口库 |
| `lib/libyaml-cpp.a` | 静态库 | YAML 解析库 |

### ARM64 交叉编译（build-clang/）

| 文件 | 类型 | 说明 |
|------|------|------|
| `hardware_task_tinker_usbcan_o` | ELF64 AArch64 PIE | 主程序 |
| `motors/Gripper/Gripper_sdk/libgripper_sdk.so` | SO AArch64 | 灵巧手 SDK |
| `output/libserial.a` | 静态库 | serial 串口库 |
| `lib/libyaml-cpp.a` | 静态库 | YAML 解析库 |

## 部署

将以下文件拷贝到 ARM64 设备的同一目录：

```
hardware_task_tinker_usbcan_o
libgripper_sdk.so  →  重命名为 libgripper_sdk.so.0
```

RPATH 设置为 `$ORIGIN`，程序会从自身所在目录加载 `libgripper_sdk.so`。

### 部署脚本

```powershell
# PowerShell 一键部署（调用 deploy.sh）
powershell -ExecutionPolicy Bypass -File deploy.ps1

# 或直接使用 bash
bash deploy.sh
```

默认部署到 `odroid@192.168.8.202:/home/odroid/zdd_test_zhengxi`，可在 `deploy.sh` 中修改。

## 文件说明

| 文件 | 说明 |
|------|------|
| `CMakeLists.txt` | CMake 构建配置（含 SIM 仿真模式） |
| `build.sh` | 本机 Linux 编译脚本（支持 `--sim` 仿真模式） |
| `run_sim.sh` | 启动 MuJoCo 仿真（支持 `--viewer` / `--no-build`） |
| `toolchain-clang.cmake` | Clang 交叉编译 toolchain（编译器、sysroot、链接器） |
| `run_cmake_clang.ps1` | Windows 交叉编译脚本（ARM64 部署） |
| `deploy.ps1` / `deploy.sh` | 部署到目标设备脚本 |
| `.clangd` | clangd 语言服务器配置 |
| `build/sysroot/` | ARM64 系统库 |
| `sim_test/` | MuJoCo 仿真相关文件 |

### 仿真模块 (按机器人目录隔离)

| 目录 | 机器人 | DOF |
|------|--------|-----|
| `sim_test/RLBOYV3/` | RL_BOYV3 双足 | 10 |
| `sim_test/RLBOYV2/` | RLBOYV2 双足 | 10 |
| `sim_test/Lingloong/` | Lingloong 人形 | 28 |

每个机器人目录下包含：

| 文件 | 说明 |
|------|------|
| `mujoco_sim_thread.cpp/h` | 仿真主线程（渲染、键盘、鼠标交互） |
| `sim_feedback.cpp/h` | 反馈写入（关节状态 + IMU 数据） |
| `sim_control.cpp/h` | 控制读取（PD + 前馈力矩） |
| `param_sim.yaml` | 仿真配置（XML 路径、步长、viewer） |
| `Robot/` | MJCF 模型 + meshes |

### 仿真参数

| 参数 | 值 | 说明 |
|------|------|------|
| 仿真频率 | 1000 Hz | 物理步进频率 |
| 渲染频率 | 30 Hz | 可视化刷新频率 |
| 关节阻尼 | 0.15 | 关节速度阻尼 |
| 关节摩擦 | 0.2 | 关节摩擦损失 |
| 足部阻尼 | 2.0 | 足部关节额外阻尼 |
| 地面摩擦 | 1.0 | 滑动摩擦系数 |
| 悬挂高度 | 因机器人而异 | 初始悬挂高度 (RLBOYV3=0.48m, RLBOYV2=0.43m, Lingloong=0.98m) |

## 子模块

| 目录 | 链接方式 | 说明 |
|------|----------|------|
| `third_parts/serial/` | 静态 | 串口通信 |
| `third_parts/yaml-cpp/` | 静态 | YAML 配置解析 |
| `motors/Gripper/Gripper_sdk/` | 动态 | 灵巧手 SDK（SO 文件随主程序部署） |

## 源码目录

```
src/        主程序入口（main, comm, audio, serial, sys_timer, global_config, common）
drivers/    驱动层（spi, audio）
inc/        公共头文件（base_struct, spi_node, imu_cmd, global_config 等）
motors/
├── BLDC/       BLDC 电机（ECOS, MIT, 维泰）
├── Hand/       灵巧手控制
├── Servo/      舵机控制
├── Gripper/    夹爪（含 Gripper_sdk）
└── *.cpp       SocketCAN 线程, 电机数据转换
sensors/    传感器（IMU 超核/微学, 磁定向, RS232）
remote/     遥控（USB RC, Simple RC 2.4G）
sim_test/
├── RLBOYV3/        RL_BOYV3 仿真 (10DOF 双足)
│   ├── mujoco_sim_thread.cpp/h  仿真主线程
│   ├── sim_feedback.cpp/h       反馈写入（关节+IMU）
│   ├── sim_control.cpp/h        控制读取（PD+前馈）
│   ├── param_sim.yaml           仿真配置
│   └── Robot/                   XML、meshes
├── RLBOYV2/        RLBOYV2 仿真 (10DOF 双足)
│   └── ...（同上结构）
└── Lingloong/      Lingloong 仿真 (28DOF 人形)
    └── ...（同上结构）
```