yunxiao.zhu
b1710e5d01
* 将预捕获 alpha 数据表替换为解析式 7 阶平滑点到点时间律 s(u)=35u⁴-84u⁵+70u⁶-20u⁷，形状系数按 1~3 阶导数最大值重算 * 新增离散限位校验：按真实 8ms 采样点反算速度/加速度/jerk， 不满足时自动拉长总时长后重采样，最多迭代 10000 次 * 实发轨迹落盘：ActualSendJointTraj.txt（角度制）、 ActualSendJerkStats.txt（点间跃度统计），按时间目录归档 * J519 AcceptsCommand 门控：只有机器人就绪时才发送下一帧， 减少无效下发；状态日志附带最近发送目标关节轴 * FanucControllerRuntime 构造函数改为必选 ILogger 注入， 确保 DI 解析时稳定拿到日志实例 * LegacyHttpApiController 移除已废弃的 ConnectServer 调用， EnableRobot 参数从 2 改为 4 * 新增跃度报警分析文档和六轴限值表，补充反馈远离拒绝测试 Co-authored-by: Copilot <copilot@github.com>
194 lines
9.1 KiB
Markdown
194 lines
9.1 KiB
Markdown
# Flyshot Replacement 仓库规范
|
||
|
||
## 1. 仓库目标
|
||
|
||
本仓库用于重写并替代现有 RVBUST/FANUC 飞拍服务端链路。
|
||
|
||
第一版目标固定为：
|
||
|
||
- 使用 `C# + .NET 8`
|
||
- 提供跨平台独立服务端
|
||
- 以新的 ASP.NET Core HTTP API 作为唯一上层接口
|
||
- 重写轨迹生成、触发时序、FANUC 控制链路和状态监控
|
||
- Windows / Linux 都能运行完整服务端
|
||
- 只支持当前现场这套组合
|
||
|
||
明确不做：
|
||
|
||
- GUI 桌面程序
|
||
- 多机器人同时控制
|
||
- 面向多控制柜的通用平台化框架
|
||
- 恢复旧 `50001/TCP+JSON` 网关
|
||
|
||
## 2. 代码与资料边界
|
||
|
||
本仓库是新的独立实现仓库，不复用旧的 RVBUST 二进制作为运行时依赖。
|
||
|
||
允许依赖的内容：
|
||
|
||
- 旧仓库中的逆向分析文档
|
||
- 旧仓库中的协议样本、轨迹样本和配置样本
|
||
- 旧仓库中的 `ControllerClient.h` 公开接口
|
||
|
||
不允许把旧服务端实现直接包装成“新系统”。
|
||
|
||
## 3. 当前目录结构
|
||
|
||
```text
|
||
flyshot-replacement/
|
||
├─ src/
|
||
│ ├─ Flyshot.Server.Host/
|
||
│ ├─ Flyshot.ControllerClientCompat/
|
||
│ ├─ Flyshot.Core.Config/
|
||
│ ├─ Flyshot.Core.Domain/
|
||
│ ├─ Flyshot.Core.Planning/
|
||
│ ├─ Flyshot.Core.Triggering/
|
||
│ ├─ Flyshot.Runtime.Fanuc/
|
||
│ └─ Flyshot.Runtime.Common/
|
||
├─ tests/
|
||
│ ├─ Flyshot.Server.IntegrationTests/
|
||
│ └─ Flyshot.Core.Tests/
|
||
├─ FlyshotReplacement.sln
|
||
├─ Directory.Build.props
|
||
├─ README.md
|
||
└─ AGENTS.md
|
||
```
|
||
|
||
后续新增模块时，优先保持以下边界：
|
||
|
||
- `Flyshot.Core.Domain`
|
||
- 纯领域对象
|
||
- 不依赖网络、文件系统、HTTP、UI、操作系统
|
||
- `Flyshot.Core.Config`
|
||
- 配置兼容
|
||
- `.robot` 解析
|
||
- 路径兼容
|
||
- `Flyshot.Core.Planning`
|
||
- `icsp`
|
||
- `self-adapt-icsp`
|
||
- `doubles`
|
||
- `Flyshot.Core.Triggering`
|
||
- `TrajectoryDO` 等价时间轴
|
||
- `shot_flags / offset_values / addr` 解析
|
||
- `Flyshot.ControllerClientCompat`
|
||
- HTTP 控制器后端兼容服务
|
||
- 旧 `ControllerClient` 语义适配
|
||
- 不启动 `50001/TCP+JSON` 监听
|
||
- `Flyshot.Runtime.Fanuc`
|
||
- `10010 / 10012 / 60015`
|
||
- `Flyshot.Web.Status`
|
||
- 状态查看
|
||
- 诊断页
|
||
- 不直接处理底层协议细节
|
||
|
||
## 4. 开发规范
|
||
|
||
### 4.1 通用要求
|
||
|
||
- 正式文档默认使用中文。
|
||
- 不要把临时验证脚本直接塞进正式运行时代码。
|
||
- 兼容性优先级高于“重新发明接口”。
|
||
- 第一版默认围绕当前现场组合实现，不提前做泛化设计。
|
||
|
||
### 4.2 实现约束
|
||
|
||
- 旧 `ControllerClient` 资料只作为接口语义参考；运行时入口以新 HTTP API 为准，不恢复旧 `50001/TCP+JSON` 网关。
|
||
- 旧协议兼容以“语义兼容”为主，不追求二进制逐字节一致。
|
||
- 轨迹规划必须与底层 Socket / HTTP / Web UI 解耦。
|
||
- 领域层不允许引用 ASP.NET Core、Socket、文件系统 API。
|
||
- 网页只做状态监控，不把复杂控制流程放进前端。
|
||
- 多机型切换通过不同 `.robot` 文件加载，不在第一版做插件化机型框架。
|
||
|
||
### 4.3 测试要求
|
||
|
||
- 默认采用 TDD。
|
||
- 至少先写失败测试，再写最小实现。
|
||
- 每完成一个阶段，要补最小可运行验证，而不是只看代码编译是否“像是对的”。
|
||
|
||
### 4.4 注释要求
|
||
|
||
- 所有生成代码都必须带中文注释，不可缺漏。
|
||
- 所有类定义都必须在类头提供 XML 注释。
|
||
- 所有静态变量都必须提供 XML 注释。
|
||
- 关键代码块必须补充单行注释，说明该段逻辑为什么存在、在做什么，不允许只写空泛注释。
|
||
|
||
### 4.5 机器人模型字段约定
|
||
|
||
- 当任务涉及六轴 `velocity / acceleration / jerk` 来源时，默认先查看机器人模型文件中的 `joint.limit`，不要先从抓包、导出轨迹或聊天记录反推。
|
||
- 当前仓库约定：`velocity_eff = velocity_base`，`acceleration_eff = acceleration_base * acc_limit`，`jerk_eff = jerk_base * jerk_limit`。
|
||
- `acc_limit / jerk_limit` 来自运行时 `RobotConfig.json`，它们是全局倍率，不是每轴单独配置。
|
||
- 模型里的 `limit.effort` 目前只能当静态模型字段记录，不能直接当现场真实电流。
|
||
- 如果用户问“电流是不是从这个模型文件提取的”，默认先明确区分：模型里的 `effort` 不等于 J519 反馈里的电机电流。
|
||
- 相关固定表格文档见 `docs/robot-joint-limit-table-20260505.md`。
|
||
|
||
## 5. 构建与验证命令
|
||
|
||
在当前环境中，推荐使用下面两条命令：
|
||
|
||
```bash
|
||
/bin/bash -lc 'DOTNET_CLI_HOME=/tmp NUGET_PACKAGES=/tmp/nuget-packages dotnet test tests/Flyshot.Server.IntegrationTests/Flyshot.Server.IntegrationTests.csproj -v minimal'
|
||
/bin/bash -lc 'DOTNET_CLI_HOME=/tmp NUGET_PACKAGES=/tmp/nuget-packages dotnet build FlyshotReplacement.sln --no-restore -v minimal'
|
||
```
|
||
|
||
说明：
|
||
|
||
- 第一条命令当前已经验证通过，可用于检查最小宿主和 `/healthz`。
|
||
- 第二条命令当前已经验证通过，可用于检查解决方案骨架是否完整。
|
||
|
||
后续新增模块时，继续补充：
|
||
|
||
- `Flyshot.Core.Tests`
|
||
- 协议回放测试
|
||
- golden sample 对拍测试
|
||
- 端到端集成测试
|
||
|
||
## 6. 修改前优先查看的资料
|
||
|
||
本仓库上层是独立实现，但上下文仍然依赖父目录中的逆向资料。开始重要改动前，优先阅读：
|
||
|
||
- `../analysis/ControllerServer_analysis.md`
|
||
- `../analysis/ICSP_algorithm_reverse_analysis.md`
|
||
- `../analysis/CommonMsg_protocol_analysis.md`
|
||
- `../analysis/J519_stream_motion_analysis.md`
|
||
- `../analysis/UTTC_20260428_packet_validation.md`
|
||
- `../analysis/FANUC_realtime_comm_analysis.md`
|
||
- `../FlyingShot/FlyingShot/Include/ControllerClient/ControllerClient.h`
|
||
|
||
### 6.1 父目录资料引用约定
|
||
|
||
- 日常开发、测试和 Codex 会话默认从 `flyshot-replacement/` 根目录启动。
|
||
- 当前仓库内的 `@` 引用默认只覆盖本仓库文件，不要假设它能索引父目录资料。
|
||
- 引用父目录资料时，统一直接写明确路径，优先使用相对路径，例如：
|
||
- `../analysis/ICSP_algorithm_reverse_analysis.md`
|
||
- `../analysis/ControllerServer_analysis.md`
|
||
- `../FlyingShot/FlyingShot/Include/ControllerClient/ControllerClient.h`
|
||
- 当路径较长或跨工具复制时，可以使用绝对路径，但在文档和注释中优先保留相对路径写法，便于仓库整体搬迁。
|
||
- 父目录中的 `analysis/`、`FlyingShot/`、`RobotController/`、`RPS/` 默认视为参考资料区，不在这些目录中继续落地新实现。
|
||
- 新实现、测试、兼容层代码、设计文档和运行说明，都应优先写入 `flyshot-replacement/` 内部。
|
||
- 如果父目录资料中的某段结论会长期影响本仓库实现，应在本仓库 `docs/` 中补充归纳说明，并标明来源路径，而不是要求后续开发反复回看聊天记录。
|
||
- 如果需要引用父目录样本文件做测试输入，优先通过只读方式加载；只有在测试需要固化样本且样本已明确收敛时，才复制到本仓库测试数据目录。
|
||
|
||
## 7. 任务推进方式
|
||
|
||
- `README.md` 中的 Todo 需要随着阶段推进同步更新。
|
||
- 如果实现范围发生收敛或扩展，先更新设计或计划，再继续改代码。
|
||
- 如果发现计划漏了关键对象或模块，直接补到文档里，不要把缺口留到后面。
|
||
|
||
## 8. 当前已验证状态
|
||
|
||
- 独立仓库已初始化。
|
||
- `dotnet 8` 解决方案骨架已建立。
|
||
- `Flyshot.Server.Host` 已提供最小 `/healthz`。
|
||
- 最小集成测试已通过。
|
||
- 解决方案构建已通过。
|
||
- 新 HTTP API / HTTP-only `ControllerClientCompat` 已覆盖旧 HTTP 控制器后端的主要兼容语义。
|
||
- `Flyshot.Core.Planning` 已落地 `icsp` 与 `self-adapt-icsp`，并已完成旧系统导出轨迹对齐。
|
||
- `Flyshot.Core.Triggering` 已能从 `shot_flags / offset_values / addr` 生成触发时间轴。
|
||
- `Flyshot.Runtime.Fanuc` 已固化 `10010 / 10012 / 60015` 基础协议帧编解码，`10010` 状态帧以 `j519 协议.pcap` 和 `Rvbust/uttc-20260428/20260428.pcap` 真机抓包确认为 90B。
|
||
- `Flyshot.Runtime.Fanuc` 已将 TCP 10010 的 `pose[6]`、`joint[6]`、`external_axes[3]` 和 `raw_tail_words[4]` 映射为明确状态帧字段，并在状态快照中保留尾部状态字诊断信息。
|
||
- `Rvbust/uttc-20260428` 抓包确认 J519 命令目标为关节角 `deg`，而导出 `JointDetialTraj.txt` 为 `rad`；执行链路必须做单位转换。
|
||
- `Rvbust/uttc-20260428` 抓包确认 `speed_ratio=0.7` 体现为 UDP 下发时间轴约 `1.427730x` 拉伸；本抓包机器人侧 `TCP 10012` 未出现 `0x2207 SetSpeedRatio`，不要把速度缩放只建模成单个机器人命令。实发按 `t_traj = k * 0.008 * speed_ratio` 重采样，`UTTC_MS11` 的 `464` 行导出轨迹对应 `1322` 个主运行 J519 包。
|
||
- `Rvbust/uttc-20260428` 抓包确认 `UTTC_MS11` 的 17 个 `shot_flags=true` 对应 17 个 UDP IO 脉冲，`io_keep_cycles=2` 对应约两周期清零。
|
||
- `Flyshot.Runtime.Fanuc` 已具备基础 Socket 客户端、速度倍率/TCP/IO 参数命令和 J519 周期发送链路；稠密轨迹下发已按 `speed_ratio` 推进轨迹时间，J519 闭环状态判断与现场联调仍需补齐。
|
||
- `ExecuteTrajectory` / `ExecuteFlyShotTraj` 已接入 `Planning + Triggering + Runtime`，不再只是兼容层内存赋值。
|