# fairino_project

**Repository Path**: wind_stl/fairino_project

## Basic Information

- **Project Name**: fairino_project
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-01
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Fairino 机器人开发平台

## 项目结构

```
fairino_project/
├── README.md                       ← 本文档
├── setup.sh                        ← 环境初始化（先 source 这个）
├── fairino-python-sdk-master/      ← Python SDK（独立于 ROS2，不需要 ROS 环境）
│   ├── linux/                      ← Linux 版：Robot.py SDK + 示例
│   │   ├── fairino/                ←    Python 封装（Cython 编译的 .so）
│   │   ├── libfairino/             ←    底层 C 通信库
│   │   └── example/                ←    示例脚本（TPD、运动、IO 等）
│   └── windows/                    ← Windows 版（结构同上）
│
├── ros2_control_ws/                ← ROS2 控制框架工作空间（全部源码编译，不依赖 apt）
│   └── src/ros-controls/
│       ├── ros2_control/           ← 【核心】ros2_control 框架
│       │   ├── controller_interface/   ← 控制器接口定义
│       │   ├── controller_manager/     ← 控制器管理器（加载/切换/运行）
│       │   ├── hardware_interface/     ← 硬件抽象层（read/write/activate）
│       │   ├── joint_limits_interface/ ← 关节限位接口
│       │   ├── transmission_interface/ ← 传动接口（减速比等）
│       │   └── ros2controlcli/         ← 命令行工具
│       ├── ros2_controllers/       ← 【核心】标准控制器（轨迹/状态/力矩等）
│       │   ├── joint_trajectory_controller/ ← MoveIt2 依赖的轨迹控制器
│       │   ├── joint_state_broadcaster/    ← 关节状态发布器
│       │   └── ...                        ← 其他 20+ 控制器
│       ├── ros2_control_demos/     ← 官方示例（各种场景 demo）
│       ├── control_msgs/           ← 控制相关 ROS2 消息定义
│       ├── control_toolbox/        ← 控制算法工具箱（PID 等）
│       ├── realtime_tools/         ← 实时线程工具
│       ├── kinematics_interface/   ← 运动学接口
│       ├── gz_ros2_control/        ← Gazebo 仿真桥接
│       │   ├── gz_ros2_control/        ← Gazebo 版插件
│       │   ├── gz_ros2_control_demos/  ← Gazebo 仿真示例
│       │   └── ign_ros2_control/       ← Ignition（旧版）插件
│       └── mujoco_ros2_control/    ← MuJoCo 仿真桥接
│           ├── mujoco_vendor/      ←    MuJoCo 物理引擎（已打包，自包含）
│           └── lodepng/            ←    PNG 编码库（本地备份）
│
└── ros2_ws/                        ← Fairino 机器人工作空间
    └── src/fairino_robot/
        ├── fairino_description/    ← 机器人 URDF 模型 + STL 网格文件
        ├── fairino_msgs/           ← 自定义 ROS2 消息/服务
        ├── fairino_hardware_master/← 【核心】硬件接口 + 命令服务器（主线）
        │   ├── libfairino/         ←    C++ SDK（FRRobot 类）
        │   └── src/
        │       ├── fairino_hardware_interface.cpp ← ros2_control 插件
        │       ├── command_server.cpp            ← ROS2 Service（200+ API）
        │       └── CNDE_thread.cpp              ← CNDE 实时状态采集
        ├── fairino_hardware_v3_9_7/  ← 硬件接口版本（适配控制器 v3.9.7）
        ├── ..._v3_9_6/ .../        ← 其他固件版本（v3.8 ~ v3.9.7）
        ├── fairino*_v6_moveit2_config/  ← 各机型 MoveIt2 配置（共 7 个）
        │   └── config/
        │       ├── *.urdf.xacro           ← 机器人模型总成
        │       └── *.ros2_control.xacro   ← 仿真/真实硬件插件切换（第 9 行）
        └── fairino_mtc_demo/        ← MoveIt Task Constructor 演示
```

## 系统前提

目标机器只需安装以下 3 个包：

```bash
sudo apt install -y ros-humble-ros-base ros-humble-moveit libglfw3-dev
```

> 所有其他依赖（ros2_control、ros2_controllers、MuJoCo 等）均在工作空间内源码编译，无需额外 apt 安装。

## 包的加载来源

`setup.sh` 按顺序 source，后 source 的覆盖先 source 的：

```
/opt/ros/humble           ← 底层（仅提供 ROS2 核心 + MoveIt2）
      ↓ 被覆盖
ros2_control_ws/install   ← 中层（ros2_control 框架 + 控制器 + MuJoCo/Gazebo）
      ↓ 被覆盖
ros2_ws/install           ← 最上层（fairino_hardware + MoveIt2 配置）
```

所有控制和仿真相关的包均从本地工作空间加载，不依赖 apt。

## 构建

### 1. 加载环境

```bash
cd fairino_project
source setup.sh
```

### 2. 编译

```bash
# 先编译 ros2_control 框架及所有控制器（ros2_ws 依赖它）
cd ros2_control_ws && colcon build

# 再编译 Fairino 机器人相关包
cd ../ros2_ws && colcon build
```

> 首次编译 ros2_control_ws 约需 10-15 分钟（含 60+ 个包），后续增量编译秒级完成。

---

## 启动方式

### 场景一：MoveIt2 仿真（mock，无物理引擎，推荐入门）

使用 mock 硬件组件，在 RViz 中验证运动规划，无需连接机器人。

```bash
source setup.sh
ros2 launch fairino10_v6_moveit2_config demo.launch.py
```

其他机型替换 `fairino10_v6` 为：`fairino3_v6`、`fairino5_v6`、`fairino16_v6`、`fairino20_v6`、`fairino30_v6`、`fairino3mt_v6`。

**效果**：RViz 打开，显示机械臂 3D 模型，可拖拽末端规划运动轨迹。

---

### 场景二：Gazebo 物理仿真（待配置）

支持碰撞、重力、传感器等物理交互。

前置步骤（尚未完成）：
1. 将对应机型的 `ros2_control.xacro` 第 9 行改为 `<plugin>gz_ros2_control/GazeboSystem</plugin>`
2. 添加 Gazebo world 启动文件

---

### 场景三：MuJoCo 物理仿真（待配置）

支持高精度动力学仿真，适合强化学习。

前置步骤（尚未完成）：
1. 将对应机型的 `ros2_control.xacro` 第 9 行改为 `<plugin>mujoco_ros2_simulation/MujocoSystemInterface</plugin>`
2. 创建 MJCF 模型文件并编写 launch

---

### 场景四：连接真实机器人

1. 将对应机型 `ros2_control.xacro` 第 9 行改为 `<plugin>fairino_hardware/FairinoHardwareInterface</plugin>`
2. 确保 PC 与机器人控制器（默认 IP `192.168.58.2`）网络互通
3. 编译并启动：

```bash
source setup.sh
cd ros2_ws && colcon build
ros2 launch fairino10_v6_moveit2_config demo.launch.py
```

---

### 场景五：ROS2 Service 指令控制

适合集成到上层应用，通过 ROS2 Service 发送字符串指令：

```bash
# 终端 1：启动命令服务器
ros2 run fairino_hardware_master ros2_cmd_server

# 终端 2：发送指令
ros2 service call /fairino_remote_command_service \
  fairino_msgs/srv/RemoteCmdInterface "{command: 'MoveJ(0,0,0,0,0,0)'}"
```

---

### 场景六：Python SDK 直控（非 ROS2）

不依赖 ROS2，直接 Python 脚本控制机器人：

```bash
cd fairino-python-sdk-master/linux
python3 example/TestTPDCommand.py
```

参考：https://fair-documentation.readthedocs.io/zh_CN/latest/SDKManual/python_intro.html

---

## 各组件关系

| | Python SDK | ROS2 (fairino_hardware) | 仿真 (mock/Gazebo/MuJoCo) |
|---|---|---|---|
| **语言** | Python (Cython) | C++ | C++ |
| **通信协议** | CNDE + XML-RPC | CNDE + XML-RPC | 模拟（无物理 / 物理引擎） |
| **依赖** | 无（独立运行） | ros2_control + MoveIt2 | ros2_control + 仿真引擎 |
| **场景** | 脚本调试、简单任务 | 复杂集成、运动规划 | 离线开发、算法验证 |

三者**共享**同一套底层 `libfairino` 通信库，可根据需求选其一或组合使用。