ethercat-linux/README.md

el6695-rt — J1900 ↔ TwinCAT 1 kHz 通讯验证（EL6695 EtherCAT 桥）

J1900 (Linux, PREEMPT_RT) 经 EL6695 EtherCAT 桥与 TwinCAT Windows PC 之间 1 kHz 双向过程数据（1024 字节/方向）通讯验证程序。参考 rustbootd/gateway-workspace 的 ecat_el6695_* 示例重新实现，并修复了 评审中发现的问题（见文末）。

拓扑

J1900(eth1) → EK1100 → EBUS → EL6695(X2/primary) → X1 → EK1100 → TwinCAT 主机

• SM2 @0x1C00：1024B，J1900 → TwinCAT（TwinCAT 侧 aIn1）
• SM3 @0x8E00：1026B（ticker 模式：2B 诊断 + 1024B）或 1046B（follow/probe 模式：22B 0x1A02 时间戳 + 1024B），TwinCAT → J1900
• 每周期：fprd SM3 → 原样回显 → fpwr SM2，本地周期号写在字节 8..16 （TwinCAT PLC 用字节 0..8 的自身序列号计算往返）

构建与部署

# Windows + Git Bash，交叉编译 musl 静态二进制
RUSTFLAGS="-C linker=rust-lld -C link-self-contained=y" \
  cargo build --release --target x86_64-unknown-linux-musl

# 部署（经跳板，按实际地址调整）
scp -J tonycao@192.168.58.8 \
  target/x86_64-unknown-linux-musl/release/el6695-rt \
  root@192.168.68.100:/root/gateway/el6695_rt

运行（J1900 上，root）

el6695_rt eth1 --mode follow --duration 600          # DC 跟随（推荐）
el6695_rt eth1 --mode ticker --duration 60           # 本地 1ms 自由跑
el6695_rt eth1 --mode probe  --duration 10 --debug-ts 40   # 时间戳探针

参数：--phase-us N（follow 模式网格相位，默认 500）、--cycle-us N、 --core N（绑核，默认 2）、--prio N（SCHED_FIFO，默认 80）、 --quiet（不打每秒状态行）。--duration 0 = 跑到 Ctrl-C/SIGTERM 为止， 信号触发优雅退出并打印完整统计。

--el2202（默认关闭）：每周期翻转 EL2202 数字输出（0x01/0x00），产生 ~500Hz 方波供示波器观察发送时序抖动。--el2202-dual：双通道同相翻转 （写 0x05/0x00），输出 1 → EL1252 回采、输出 2 → 示波器，同一信号两种 视角。注意 EL2202 过程字节语义（EEPROM PDO 0x1600/0x1601 实证）： bit0=通道1数据, bit1=通道1三态, bit2=通道2数据, bit3=通道2三态—— 写 0x03 会把通道 1 置为高阻（三态），双通道必须写 0x05。实现：手动 配置 EL2202 SM0（输出物理地址 0x0F00，1 字节，ctrl 0x44，enable 0x09 按 EEPROM），裸 AL 驱动进 OP，写回读验证后才启用；翻转帧使单圈执行 时间从 ~410µs 增至 ~650µs（仍在 1ms 预算内）。注意：输出端子可能 接着真实执行器，确认接线后再启用。 简单 DO 端子无邮箱且 SM/FMMU 在组 PREOP→SAFEOP 转换时才被编程（我们跳过该转换），这是必须手动配 SM0 的原因。

--el2262（默认关闭）：EL2262 XFC 输出 DC 同步锁定方波（方案 B）。 配置 DC 同步单元（SYNC0/1 周期 1ms、+100ms 启动、0x0980=0x03）并手动 配 SM0（0x1000/1B/0x64/0x09），输出沿锁定 DC 1ms 网格，可作示波器或 EL1252 回采的基准。

--el1252（默认关闭）：EL1252 锁存时间戳回采（方案 C）。每周期读 ESC 寄存器 0x09AE 起 34 字节（status + 双通道 Latch Pos/Neg u64）， 统计两通道上升沿间隔与沿相位。详见 docs/scope-waveform-design.md §8。 帧预算：A+C 或 B+C 组合单圈 ~898µs，A+B+C 不要同开（超 1ms）。

三种模式

• ticker：clock_nanosleep(TIMER_ABSTIME) 绝对时间网格，无漂移； SM3 布局为 0x1A01 诊断字。
• follow（默认）：软件 PLL 跟随 TwinCAT DC 时钟（0x1A02 外部时间戳）， 读点锁在 TC 网格边界 + phase。与参考实现的差异见下。
• probe：ticker 节拍 + follow 布局，不做 PLL 反馈，只 dump 原始 时间戳相位（诊断用）。

相对参考实现（rustbootd ecat_el6695_*）的修复

1. DC 跟随 PLL 的周期二狩猎（最重要）：参考实现每个周期用原始 采样直接重算锚点（deadbeat：floor(ext)+1ms+phase）。实测该环路是 带延迟的反馈系统（TwinCAT 发送相位与我们的帧时序相互耦合），存在 多个周期轨道：相位关系漂移（实测 ~155ppm）到不利区间时，周期时间 在 0.4/1.6ms 间交替、相位误差双峰跨度 >1ms。参考二进制只是恰好落 在稳定轨道上。本实现：锚点变化 slew 限幅 ±50µs/周期，且检测到 卡死（误差连续 100 周期顶在同一限幅边界，即"读到上一帧"的双稳态 陷阱）时一次性 snap 重锚定；deadline 落后 >2ms 时 re-prime（同时 丢弃被污染的 offset）。修复后此前必现狩猎的 phase=500 配置： 30000 周期/30s 精确 1kHz，phase_err p50=164µs、std 4.4µs， period_jitter p99.9=0.2µs，锁相质量优于参考实现（std 6~10µs）。
2. 合理性与稳定性评测发现的参考实现其它问题：
   • bridge_dump 用自旋凑满 1ms，无绝对时间锚点，超时即永久相移 → 本实现 ticker 模式用绝对时间网格。
   • 统计用逐样本 Vec 再排序（~30MB/小时/指标）→ 有界直方图 + Welford。
   • 无信号处理，Ctrl-C 丢失全部统计 → SIGINT/SIGTERM 优雅退出。
   • 配置代码在 4+ 个 example 中复制粘贴 ~300 行 → 单一 bridge 模块。
   • 错误只计数不上报，死链静默累积 → 连续 1000 周期错误即中止。
   • 时间戳合理性过滤与"上一个原始样本"比较（而非上一个已接受样本）， 单个坏样本最多造成两次拒绝、自动恢复（过滤与已接受值比较会在启动 离群值后永久死锁——实测踩中）。
   • 移除模拟内存 loopback 线程/mutex（CH368/RFM2G 模拟遗留），RT 路径 直接回显。
   • 删除循环内嵌 PLC 时间戳的端到端延迟指标（跨时钟域且依赖 PLC 程序 内嵌格式，实测数据无意义；端到端延迟应在 TwinCAT 侧用 PLC RTT 统计 测量）。

保留的参考实现经验（全部实测有效）

• EL6695 用户 OD 在主站更替时被固件清空，每次上线自检自配。
• 映射对象必须 Complete Access 单条邮箱消息写（vendor/ethercrab 补丁 sdo_write_complete），标准分段流程被固件拒绝 MBXERR_INVALIDSIZE。
• PDO 布局逐字节复制 TwinCAT 线格式：0x1608/0x1A08 各 35 条目 （首条目 @240bit + 33 条 0x0000 延续 + 1 条 @32bit）。
• SM 用裸寄存器配置，AL 状态机裸 fpwr/fprd 驱动；SAFEOP 后邮箱坏死， 数据循环内禁止 SDO。
• RT 手段：PREEMPT_RT 内核 + SCHED_FIFO 80 + 绑核 + mlockall + 栈 prefault；musl 静态链接下 sched_setscheduler 需走 raw syscall。

目录

• src/main.rs — 主循环（ticker/follow/probe）、PLL、信号处理
• src/bridge.rs — EL6695 自检自配、SM 裸配置、AL 状态机
• src/rt.rs — RT 提升、绝对时间睡眠、Ticker
• src/stats.rs — 有界在线统计（直方图 + Welford）
• vendor/ethercrab — 带 sdo_write_complete/send_raw_coe 补丁的 ethercrab 0.7.1（复制自 rustbootd/gateway-workspace/vendor）