ethanylhuang/tvc-characterization

# TVC 特性表征 推力矢量控制（TVC）与 IMU 设备的组合安装在单个 Teensy 4.1 上。一条串行链路 （115200 波特率）同时传输舵机指令和 IMU 姿态数据流， 由一个极简的 Web 界面驱动。 ## 布局 固件（PlatformIO）位于根目录；Web 应用是位于 `web/` 目录下的 React + Vite 项目。 ``` platformio.ini Teensy 4.1 build config src/main.cpp firmware: 2 servos (pitch=5, yaw=6) + ISM330DHCX IMU data/ tables.json + characterization CSVs (created at runtime) web/ package.json React + Vite project vite.config.js dev/preview server config plugins/tables-api.js Vite middleware: GET/POST /api/tables, POST /api/save (CSV) index.html Vite entry src/ main.jsx React entry App.jsx layout + wiring styles.css lib/ framework-agnostic logic constants.js constants + built-in default tables serial.js Web Serial connect/disconnect/send + line events orientation.js IMU angle store, tracking mode, sample events tables.js lookup tables, gimbal-command math, persistence measure.js shared measurement primitives (settle, projection, capture) autotune.js automated lookup-table characterization characterize.js the six mount-characterization tests csv.js CSV formatting + save-to-data/ hooks/ useSerial / useTableRanges / useOrientationDisplay components/ ConnectionBar, ServoPanel, AutoTune, ImuPanel, Characterize, Stage, NumberField ``` ## 固件 ``` pio run # compile pio run -t upload # flash the Teensy pio device monitor # view the serial stream ``` 串口协议： - `p \n` — 设置俯仰舵机脉冲宽度（微秒） - `y \n` — 设置偏航舵机脉冲宽度（微秒） - `r \n` — 设置串口流传输周期（5–1000 ms；默认为 50）。用于 特性表征测试以约 100 Hz 的频率捕获瞬态响应，随后恢复为 50。 - 持续发送 `ms angle deg X: .. Y: .. Z: ..`（融合互补滤波器数据） - 以及 `ms accel deg X: .. Y: ..`（仅加速度计倾斜数据）。`ms ` 前缀 是固件的毫秒时间戳；旧版解析器会将其忽略。 ## Web 界面 ``` cd web npm install # first time only npm run dev # Vite dev server with HMR at http://127.0.0.1:8787 # npm run build # 生产 bundle 到 web/dist/ # npm run preview # 提供已构建的 bundle（相同的 table API） ``` Vite 提供了开发服务器和模块热重载；一个小型 Vite 插件 （`plugins/tables-api.js`）提供 `GET`/`POST /api/tables` 服务，以便在 `dev` 和 `preview` 模式下将调校好的参数表持久化保存到 `data/tables.json`。 在 Chrome 或 Edge（Web Serial）中打开该 URL，点击 **Connect**，然后选择 Teensy。 - **Gimbal command** — 输入每个轴的万向节*偏转角度（度）*。页面会 将俯仰/偏航查找表（指令 µs → 偏转角度）进行反向插值以 得到脉冲宽度，根据各轴的 **trim µs**（即 0° 中性脉冲， 俯仰默认为 1605 / 偏航默认为 1640）对其进行重新居中，并发送原始的 `p`/`y` 指令。 生成的 µs 值会显示在每个轴的旁边。**cmd µs** 会直接发送 原始脉冲宽度，绕过查找表（便于进行特性表征）。**Center both** 将两个轴归零。 - **IMU orientation** — 一个直立的灰色圆柱体显示了开发板的姿态 （拖动可旋转视图）。提供各轴 X/Y/Z 的读数；**Zero** 会将 当前读数捕获为新的参考基准。**Tracking** 用于切换角度数据源： *Dynamic* 使用融合互补滤波器（响应灵敏，运动时表现良好）； *Static* 仅使用加速度计获取无漂移的稳态倾斜（最适合 特性表征测量）。航向角（Z）始终来自陀螺仪， 因为加速度计无法感知围绕重力的旋转。 内置的默认参数表位于 `web/src/lib/constants.js`（`DEFAULT_TABLES`）中。 启动时，应用会将任何已保存的 `data/tables.json` 叠加在其上，因此调校过的轴 会自动生效。 ### 自动调校 (`web/src/lib/autotune.js`) **Auto-tune pitch** 和 **Auto-tune yaw** 各自会运行一次自动化的特性表征 扫描。对于每个脉冲宽度，该程序会向舵机发送指令，等待一个固定的最短时间后， 自适应地等待角度稳定，然后对一段窗口内的 纯加速度计样本进行平均。它会向上和向下扫描整个范围，并对 匹配点取平均值以消除舵机回程间隙，将 X/Y 倾斜投影到其 主方向上（因此即使 IMU 与万向节平面没有完美对齐， 也能保持精度），将 0° 锚定在中心指令处，并调整 符号以匹配参数表约定。 结果会**立即应用并保存到 `data/tables.json`** — 无需 复制/粘贴，并且在重新加载后依然有效。（删除该文件即可回退到 内置默认值。）请先进行连接；无论 UI 开关状态如何，它都会读取加速度计数据。 ### 特性表征 (`web/src/lib/characterize.js`) **Characterization** 面板用于测量物理安装参数。选择一个轴， 运行任何测试；每次测试都会以**原始微秒**为单位（独立于查找表）扫描/步进舵机， 并将指令 µs 与 IMU 测量出的度数配对，然后通过 `POST /api/save` 将每次运行的 数据以 CSV 格式保存到 `data/`。所有测试都会将 X/Y 倾斜投影到万向节 所发现的主轴上，因此结果对 IMU 的安装偏斜具有鲁棒性。 - **Repeatability** — K 个设定点 × N 次试验，每次均从中心点接近；按设定点计算 σ/极差。 - **Hysteresis** — 分别记录升序和降序扫描；计算每个 µs 对应的上下行间隙。 - **Response time** — 高速率（`r 10`）捕获阶跃瞬态；计算上升/稳定/超调量。 - **Deadband** — 先测量本底噪声，再找出能产生 >3σ 移动的最小 µs 步进。 - **Max slew** — 以约 100 Hz 的频率进行双向全范围阶跃；得出最大角速率（度/秒）。 - **Cross-axis** — 扫描一个轴，同时保持另一个轴居中；测量对所保持轴的泄漏量。 通用的测量原语（稳定/平均、主轴投影、 本底噪声、高速率捕获、瞬态分析）位于 `web/src/lib/measure.js` 中， 可同时被自动调校和特性表征测试复用。 ## 备注 - 引脚：俯仰 = 5，偏航 = 6；IMU 位于 Wire 总线上（SDA 18 / SCL 19）。 - IMU 轴到圆柱体模型的映射符号取决于安装方式；如果某个运动 读数反向，请翻转 `web/src/hooks/useOrientationDisplay.js` 中 模型变换的相应符号。

标签：IMU传感器, PlatformIO, React, Syscalls, Teensy, 嵌入式硬件, 推力矢量控制, 自动控制系统, 自定义脚本