# fmrobot

**Repository Path**: imzack/fmrobot

## Basic Information

- **Project Name**: fmrobot
- **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-08-27
- **Last Updated**: 2026-09-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# fmrobot

基于宇树 Go2 EDU 的教室巡检机器人项目。

当前阶段：`v0.1.0` 分阶段开发；`v0.0.4` 已实现带阶段门的 Go2 高层运动安全桥，
软件与 ROS 2 仿真输出已验证，实机阶段门尚未通过。

## v0.1.0 一句话目标

机器人在单楼层、预先建图、门已开启且有人值守的室内环境中，按配置的拍照点自主导航，停稳后拍照，并把带有点位和时间信息的照片发送到指定飞书群。

## 文档入口

从 [docs/README.md](docs/README.md) 开始阅读。

## v0.0.2 M0 基线检查

`v0.0.2` 会校验硬件清单、网络地址与安全演练记录。当前文件保留待实机填写的
`null/pending`，因此预期返回退出码 `1` 和完整阻断项，不会误报 M0 已通过：

```bash
PYTHONPATH=ros2_ws/src/fmrobot_inspection \
  python3 -m fmrobot_inspection.m0_cli check \
  --hardware config/robot/hardware-inventory.yaml \
  --network config/network/network-addresses.example.yaml \
  --safety config/safety/m0-checklist.yaml
```

现场填写与证据规则见 [M0 实机盘点操作指南](docs/03-development/m0-operator-guide.md)。
该工具只读取文件，不探测网络、不连接 Go2、不发送运动命令。

## v0.0.3 Go2 只读预检查

`v0.0.3` 新增 `fmrobot_unitree_bridge`，只订阅 `/sportmodestate` 并记录频率、断流和
JSONL 会话证据。M0 未完成或 DDS 网卡、Domain、XML 不一致时拒绝启动：

```bash
PYTHONPATH=ros2_ws/src/fmrobot_inspection:ros2_ws/src/fmrobot_unitree_bridge \
  python3 -m fmrobot_unitree_bridge.cli preflight \
  --monitor config/robot/go2-readonly-monitor.yaml \
  --hardware config/robot/hardware-inventory.yaml \
  --network config/network/network-addresses.example.yaml \
  --safety config/safety/m0-checklist.yaml
```

仓库模板目前仍会返回 NOT READY，这是缺少实机证据时的预期安全行为。安装
`unitree_go` 并完成 M0 后，按 [Go2 只读通信指南](docs/03-development/v0.0.3-readonly-go2.md)
执行真实 30 分钟记录。

## v0.0.4 高层运动安全桥

先运行不会连接机器人的仿真预检查与节点：

```bash
source /opt/ros/humble/setup.bash
colcon build --packages-select fmrobot_inspection fmrobot_unitree_bridge
source install/setup.bash
ros2 run fmrobot_unitree_bridge fmrobot-go2-motion preflight \
  --config config/robot/go2-motion-bridge.simulation.yaml --json
ros2 run fmrobot_unitree_bridge go2-motion-bridge \
  --config config/robot/go2-motion-bridge.simulation.yaml
```

仿真只发布 `/fmrobot/sim/sport_request`，用于验证显式 arm、来源唯一性、限速、
`0.5 s` watchdog、急停锁存、复位和退出停车。硬件配置当前会返回 NOT READY；必须先
完成 M0 和 v0.0.3 只读证据。详细命令、预期 JSON 和现场阶段门见
[v0.0.4 ROS 2 命令验证指南](docs/03-development/v0.0.4-ros2-command-validation.md)。

## 飞书通知功能（提前实现）

已新增独立 `fmrobot_feishu` 包，实现 token 缓存、JPEG/SHA-256 校验、图片与元数据发送、
任务摘要、持久化有界队列、指数退避和重启续传。真实凭证使用被 Git 忽略且要求 `0600`
权限的 `config/feishu/feishu.local.yaml`：

```bash
cp config/feishu/feishu.example.yaml config/feishu/feishu.local.yaml
chmod 600 config/feishu/feishu.local.yaml
source /opt/ros/humble/setup.bash
colcon build --packages-select fmrobot_feishu
source install/setup.bash
ros2 run fmrobot_feishu fmrobot-feishu \
  --config config/feishu/feishu.local.yaml --json check
```

配置、入队、发送、失败恢复和清理步骤见
[飞书可靠通知指南](docs/03-development/feishu-notifier.md)。

## v0.0.5 传感器与相机链路

`fmrobot_sensor_suite` 提供 MID-360 `PointCloud2` 频率、断流、时间戳、frame 和 TF 证据；
`fmrobot_camera_client` 提供 Orin ROS1 图像代理、认证 HTTP、幂等拍照以及工作站 JPEG/
SHA-256 校验。软件仿真配置不会连接机器人或发布运动命令：

```bash
source /opt/ros/humble/setup.bash
colcon build --packages-select fmrobot_camera_client fmrobot_sensor_suite
source install/setup.bash
ros2 run fmrobot_sensor_suite fmrobot-sensors \
  --config config/sensors/m2-sensor-chain.simulation.yaml --json preflight
ros2 run fmrobot_camera_client fmrobot-camera \
  --config config/camera/camera-client.example.yaml --json check
```

仿真闭环、Orin ROS1、MID-360、TF、失败注入和 30 分钟 M2 阶段门见
[v0.0.5 ROS 2 命令验证指南](docs/03-development/v0.0.5-ros2-command-validation.md)。

## 任务配置验证

任务 dry-run 仍可用，且不连接机器人：

```bash
PYTHONPATH=ros2_ws/src/fmrobot_inspection \
  python3 -m fmrobot_inspection.cli dry-run config/missions/classroom-a.example.yaml
python3 -m pytest
```

需要同时确认飞书目标环境变量已配置时：

```bash
PYTHONPATH=ros2_ws/src/fmrobot_inspection \
  python3 -m fmrobot_inspection.cli dry-run \
  config/missions/classroom-a.example.yaml --require-target-env
```

命令只显示环境变量名与配置状态，不显示其值。完整版本拆分见 [v0.1.0 版本拆分](docs/03-development/version-plan.md)。

在已安装 ROS 2 Humble 的工作站中，可按标准 `ament_python` 包构建：

```bash
source /opt/ros/humble/setup.bash
colcon build --packages-select fmrobot_inspection fmrobot_unitree_bridge
source install/setup.bash
ros2 run fmrobot_inspection fmrobot-mission dry-run \
  config/missions/classroom-a.example.yaml
ros2 run fmrobot_inspection fmrobot-baseline check \
  --hardware config/robot/hardware-inventory.yaml \
  --network config/network/network-addresses.example.yaml \
  --safety config/safety/m0-checklist.yaml
```

## 当前结论

- 现有硬件组合原则上覆盖 v0.1.0：Go2 EDU、Orin Nano 8GB、MID-360、D435i、遥控器和长续航电池。
- 当前采用混合架构：Orin 保留 ROS1 Noetic 和 D435i；Ubuntu 22.04 工作站运行 ROS2 Humble、MID-360、Nav2、巡检任务和飞书客户端。
- 工作站通过 Wi-Fi 和 CycloneDDS 直接访问 Go2，通过路由器接收 MID-360 UDP 数据；ROS1/ROS2 首版不做全量 topic 桥接。
- D435i 由 Orin 上的轻量拍照代理提供 HTTP 接口，工作站按需下载 JPEG 后上传飞书。
- v0.1.0 不做无人值守、自动开门、自动充电、多楼层、电梯联动、人员识别或课堂内容分析。
- 在任何自主移动测试前，必须完成遥控接管、速度限制、Wi-Fi/DDS 断链停车和雷达 UDP 稳定性验证。