11# Embodied-Tactile-Control-Pipeline
22
3- Open-source reference project for a tactile closed loop built with ** ROS2 + TensorRT + CUDA** .
3+ Open-source reference project for a tactile closed loop built with ** ROS2 + TensorRT + CUDA** .
4+ 基于 ** ROS2 + TensorRT + CUDA** 的触觉闭环控制开源参考项目。
45
5- ** Highlight** : from tactile slip detection to motor reaction, the full chain reaches ** 2 ms end-to-end latency** (p99 ~ = 2.00 ms).
6+ ** Highlight** : from tactile slip detection to motor reaction, the full chain reaches ** 2 ms end-to-end latency** (p99 ~ = 2.00 ms).
7+ ** 亮点** :从触觉滑移感知到电机响应,整条链路端到端延迟可做到 ** 2 ms** (p99 约 ** 2.00 ms** )。
68
7- ## What this repo demonstrates
9+ ## What This Repo Demonstrates / 仓库展示内容
810
9- - A complete closed loop:
10- ` tactile/raw -> preprocess -> TensorRT slip inference -> reactive controller -> motor/command ` .
11+ - A complete closed loop: ` tactile/raw -> preprocess -> TensorRT slip inference -> reactive controller -> motor/command `
12+ - 完整闭环链路: ` tactile/raw -> preprocess -> TensorRT 滑移推理 -> 反应式控制器 -> motor/command `
1113- A latency-first design focused on deterministic behavior.
14+ - 以“低延迟和确定性”为核心目标的系统设计。
1215- Practical instrumentation for stage and end-to-end microsecond latency.
16+ - 提供分阶段与端到端微秒级时延埋点与统计方案。
1317
14- ## Architecture
18+ ## Architecture / 架构
1519
1620``` mermaid
1721flowchart LR
@@ -22,104 +26,105 @@ flowchart LR
2226 E --> F[Actuator]
2327```
2428
25- ## Latency result (reference)
29+ ## Latency Results (Reference) / 时延结果(参考)
2630
2731- End-to-end p50: ** 1.87 ms**
2832- End-to-end p95: ** 1.96 ms**
2933- End-to-end p99: ** 2.00 ms**
34+ - 端到端 p50:** 1.87 ms**
35+ - 端到端 p95:** 1.96 ms**
36+ - 端到端 p99:** 2.00 ms**
3037
31- Detailed budget is in ` docs/latency_budget.md ` .
38+ Detailed budget is in ` docs/latency_budget.md ` .
39+ 详细预算请见 ` docs/latency_budget.md ` 。
3240
33- ## Low-latency techniques used
41+ ## Low-Latency Techniques / 低延迟关键技术
3442
3543- ROS2 QoS for control path: ` KeepLast(1) ` , ` BestEffort ` , ` Volatile ` .
44+ - 控制链路 ROS2 QoS:` KeepLast(1) ` 、` BestEffort ` 、` Volatile ` 。
3645- Async CUDA path with pinned memory to reduce transfer jitter.
46+ - 使用 pinned memory + CUDA 异步路径降低拷贝抖动。
3747- Fixed-shape TensorRT engine with FP16.
48+ - 固定输入 shape + FP16 TensorRT 引擎。
3849- Lightweight reactive control law with bounded compute.
50+ - 轻量反应式控制律,计算开销有界。
3951- Per-frame timestamp tracing in microseconds.
52+ - 每帧微秒级时间戳追踪。
4053
41- ## Repo layout
54+ ## Repo Layout / 仓库结构
4255
43- - ` docs/architecture.md ` : dataflow and node contracts.
44- - ` docs/latency_budget.md ` : stage-level latency budget and verification method.
45- - ` ros2_ws/src/tactile_msgs ` : custom message ` SlipEvent.msg ` .
46- - ` ros2_ws/src/embodied_tactile_control ` : ROS2 nodes + launch + config.
47- - ` scripts/benchmark.py ` : parse ROS logs and report p50/p95/p99.
48- - ` .github/workflows/ci.yml ` : ROS2 build sanity check.
56+ - ` docs/architecture.md ` : dataflow and node contracts.
57+ ` docs/architecture.md ` :数据流与节点接口约定。
58+ - ` docs/latency_budget.md ` : stage-level latency budget and verification method.
59+ ` docs/latency_budget.md ` :分阶段时延预算与验证方法。
60+ - ` ros2_ws/src/tactile_msgs ` : custom message ` SlipEvent.msg ` .
61+ ` ros2_ws/src/tactile_msgs ` :自定义消息 ` SlipEvent.msg ` 。
62+ - ` ros2_ws/src/embodied_tactile_control ` : ROS2 nodes + launch + config.
63+ ` ros2_ws/src/embodied_tactile_control ` :ROS2 节点、启动文件和配置。
64+ - ` scripts/benchmark.py ` : parse ROS logs and report p50/p95/p99.
65+ ` scripts/benchmark.py ` :解析日志并输出 p50/p95/p99。
66+ - ` .github/workflows/ci.yml ` : ROS2 build sanity check.
67+ ` .github/workflows/ci.yml ` :ROS2 构建 CI 检查。
4968
50- ## Quick start
69+ ## Quick Start / 快速开始
5170
52- ### Prerequisites
71+ ### Prerequisites / 依赖环境
5372
5473- Ubuntu 22.04
5574- ROS2 Humble
5675- CUDA 12+
5776- TensorRT 10+
5877
59- ### Build
78+ ### Build / 编译
6079
6180``` bash
6281cd ros2_ws
6382colcon build --symlink-install
6483source install/setup.bash
6584```
6685
67- ### Run closed loop (with built-in tactile simulator)
86+ ### Run Closed Loop / 运行闭环
87+
88+ Built-in tactile simulator is included.
89+ 仓库内置触觉传感器模拟节点。
6890
6991``` bash
7092ros2 launch embodied_tactile_control closed_loop.launch.py | tee ros2_run.log
7193```
7294
73- ### Benchmark latency
95+ ### Benchmark / 时延统计
7496
7597``` bash
7698python3 scripts/benchmark.py --log ros2_run.log
7799```
78100
79- Expected tracer line pattern:
101+ Expected tracer pattern / 日志格式示例:
80102
81103``` text
82104LATENCY_US frame=... preprocess=... inference=... control=... end_to_end=... slip=...
83105```
84106
85- ## Reproducible 2 ms validation protocol
86-
87- 1 . Timestamp tactile frame capture in sensor node.
88- 2 . Keep timestamps through preprocess and inference.
89- 3 . Timestamp publish in reactive controller callback.
90- 4 . Compute ` end_to_end_us ` per frame.
91- 5 . Report p50/p95/p99 over at least 10,000 frames.
92-
93- ## Publish to GitHub
94-
95- If ` gh ` is available and authenticated:
96-
97- ``` bash
98- git init
99- git add .
100- git commit -m " feat: initial ROS2 + TensorRT + CUDA tactile control pipeline"
101- gh repo create Embodied-Tactile-Control-Pipeline --public --source . --remote origin --push
102- ```
103-
104- Manual alternative: create an empty repo named ` Embodied-Tactile-Control-Pipeline ` on GitHub, then:
107+ ## Reproducible 2 ms Validation Protocol / 可复现 2ms 验证流程
105108
106- ``` bash
107- git init
108- git add .
109- git commit -m " feat: initial ROS2 + TensorRT + CUDA tactile control pipeline"
110- git remote add origin git@github.com:< your-user> /Embodied-Tactile-Control-Pipeline.git
111- git branch -M main
112- git push -u origin main
113- ```
109+ 1 . Timestamp tactile frame capture in sensor node.
110+ 在传感器节点记录触觉帧采集时间戳。
111+ 2 . Keep timestamps through preprocess and inference.
112+ 在预处理和推理阶段持续传递时间戳。
113+ 3 . Timestamp publish in reactive controller callback.
114+ 在控制器回调发布电机命令时打时间戳。
115+ 4 . Compute ` end_to_end_us ` per frame.
116+ 逐帧计算 ` end_to_end_us ` 。
117+ 5 . Report p50/p95/p99 over at least 10,000 frames.
118+ 至少统计 10,000 帧并给出 p50/p95/p99。
114119
115- ## Status
120+ ## Status / 当前状态
116121
117- - [x] End-to-end closed-loop ROS2 graph
118- - [x] Slip event message and latency tracer
119- - [x] TensorRT and CUDA path scaffold
120- - [x] Benchmark parser for latency verification
121- - [ ] Hardware-specific motor bus adapter (CAN/EtherCAT)
122+ - [x] End-to-end closed-loop ROS2 graph / 端到端闭环 ROS2 拓扑
123+ - [x] Slip event message and latency tracer / 滑移事件消息与时延追踪
124+ - [x] TensorRT and CUDA path scaffold / TensorRT 与 CUDA 路径骨架
125+ - [x] Benchmark parser for latency verification / 时延验证脚本
126+ - [ ] Hardware-specific motor bus adapter (CAN/EtherCAT) / 硬件总线适配层
122127
123- ## License
128+ ## License / 许可证
124129
125- MIT
130+ MIT
0 commit comments