# T2G 座椅真实硬件台架接入

本链路把前端一句话生成的 `FunctionConfig` 确定性编译为统一 IAR 固件的经典 CAN 协议，并以开发板真实反馈作为成功依据。默认仍为 `dry_run`；只有服务端启用硬件且目标通过门禁时才会打开 CAN 适配器。生产/公网环境默认还要求每次请求携带正确授权令牌；本地受控调试可显式关闭该令牌门禁。

## 自包含固件

仓库已经包含完整构建输入：

```text
firmware/t2g/
├── CYPRESS_SDK_LICENSE.txt
├── common/
├── tviibh8m/
└── Seat_Controller_demo/
    ├── App/ Bsp/ Config/ Driver/
    ├── Docs/ Tests/
    └── IAR/Seat_Controller_demo.ewp
```

因此迁移仓库后不再依赖原电脑桌面的 `T2G_Sample_Driver_Library_7.9.0`。IAR、CMSIS-DAP 与 ZLG 驱动属于本机工具链/硬件驱动，仍须在台架电脑安装。

```powershell
powershell -ExecutionPolicy Bypass -File .\tools\build_seat_firmware.ps1
```

构建脚本只使用仓库内 `common/tviibh8m`，在临时目录编译并回写 HEX/OUT，不连接探针、不烧录、不启动执行器。非标准 IAR 路径可通过 `COGNITIVE_AGENT_IAR_BUILD` 或 `-IarBuild` 指定。

## 四轴与量程

统一坐标为最近端 `0 Hall = 0%`，朝最远端 Hall 增加，`0x302.Value_X100` 范围为 0–10000。

| MotorID | 前端能力 | 物理执行器 | 最近端 → 最远端 | MaxHall | 全量程 |
| ---: | --- | --- | --- | ---: | ---: |
| M0 | `seat.set_longitudinal_position` | 水平前后 | 最前 → 最后 | 480 | 215 mm |
| M1 | `seat.set_cushion_tilt` | 坐盆斜上下 | 最高 → 斜向下 | 374 | 水平 51 mm / 垂直 56 mm |
| M2 | `seat.set_backrest_recline` | 靠背 | 竖直 → 后躺 | 917 | 68° |
| M3 | `seat.set_legrest_height` | 腿托 | 最下 → 抬起 | 647 | 72° |

四轴与 physical Mode 同号，均已纳入硬件映射；台架不实现独立腿托伸缩轴，因此 `seat.set_legrest_extension` 只保留虚拟展示，真实请求会在打开 CAN 前拒绝。

## CAN 协议与反馈

- 热管理命令：`0x29E/0x3CE`；档位反馈：`0x4FA`。
- 移动命令：`0x300`；系统 ACK：`0x301`；归一化位置：`0x302`；Hall/量程：`0x303`。
- 电流诊断：`0x304` 四轴轮询，`0x305` 通风/加热；这些值用于台架可见性，当前保守阈值不能替代外部限流或量产保护。
- Opcode 1 的 `ParamA` 为 0–10000 绝对位置，`ParamB=0` 使用各轴固件默认超时。
- Opcode 3 的 `ParamA` 为持续时间，`ParamB` 为驱动等级×10（默认 90% 即 900）。
- `STOP_ALL` 的专用 ACK 为 4；完成/故障 TaskState 分别为 6/7。

新版固件把 `0x304/0x305` 用于电流诊断，不能继续发送旧版身份请求。后端在任何控制帧之前被动观察 `0x301–0x305`、`0x4FA`、四个 MotorID 和 MaxHall `480/374/917/647`；真实硬件执行启用后，未观察到完整签名会自动使用仓库内 IAR 镜像烧写，重新被动验证成功后继续原请求。烧写或复验失败时禁止发送座椅控制帧。

## 启用配置

```dotenv
COGNITIVE_AGENT_HARDWARE_EXECUTION_ENABLED=true
COGNITIVE_AGENT_HARDWARE_APPROVAL_TOKEN_REQUIRED=false
COGNITIVE_AGENT_HARDWARE_APPROVAL_TOKEN=123456
COGNITIVE_AGENT_SEAT_FIRMWARE_PROFILES=combined
COGNITIVE_AGENT_SEAT_AUTO_FLASH_ENABLED=true
COGNITIVE_AGENT_IAR_CSPYBAT=D:\Program Files\IAR Systems\Embedded Workbench 9.2\common\bin\cspybat.exe
COGNITIVE_AGENT_SEAT_CAN_BACKEND=zlgcan
COGNITIVE_AGENT_SEAT_CAN_CHANNEL=0
COGNITIVE_AGENT_SEAT_CAN_BITRATE=500000
COGNITIVE_AGENT_SEAT_AUTO_HOME_ENABLED=false
COGNITIVE_AGENT_SEAT_HOME_TIMEOUT_S=120
```

`COGNITIVE_AGENT_HARDWARE_APPROVAL_TOKEN_REQUIRED` 默认为 `true`，生产和公网部署应保持默认值。本地受控台架调试可显式设为 `false`，此时前端隐藏令牌输入且服务端不再逐请求校验令牌；硬件启用、固件、适配器、副驾目标、物理反馈和故障 STOP_ALL 等其他门禁保持不变。

`COGNITIVE_AGENT_SEAT_AUTO_FLASH_ENABLED` 在真实硬件执行启用时默认为 `true`，上面的显式配置便于台架审计；如需禁止自动覆盖控制器固件，可明确设置为 `false`。此默认值不会影响 `dry_run`。

当前台架只公布并接受副驾目标 `passenger/front_right`。没有座位词的座椅指令默认副驾；显式主驾、主副驾或前排范围请求会在打开 CAN 前拒绝，不能静默重定向。热管理 CAN 中仍出现的 `Driver_Seat_*` 是板端既有协议字段名，不代表应用层可以控制主驾。

## 绝对位置与已知量程归零

绝对命令发送前必须看到 `Position_Valid=1`。SMV8 clean 记录有效时，一句话可以直接下发绝对目标；位置无效时默认失败关闭，不会静默触发全行程标定。

台架无遮挡、急停就绪并且明确允许自动回最近端时，可设置 `COGNITIVE_AGENT_SEAT_AUTO_HOME_ENABLED=true`。后端仅对目标失效轴发送 `HOME_KNOWN_RANGE(0x0B)`，先核对 MaxHall，再等待 `COMPLETE/OK`、Near、Hall≤2 和 PositionValid，随后继续原绝对目标。此流程会产生真实机械运动，但不会访问最远端或重测量程。Opcode `0x0A` 全行程标定不会由普通一句话请求触发。

## 上电与安全检查

1. 固定座椅，清空四轴全行程，准备硬件急停和 12 V 限流电源。
2. CAN4：RX=P3.7、TX=P3.6、P3.1 收发器使能；CANH/CANL 正确、共地、总线两端各 120 Ω。
3. 使用 Classic CAN、11-bit、DLC 8、500 kbit/s；ZCANPRO 与服务不能同时独占适配器。
4. 首次动作只做单轴短行程并目视核对 M0/M1/M2/M3 与方向；任一映射异常立即急停。
5. 先验证通风/加热关闭与低档，再执行移动；无示波器时不得声称 PWM、死区或硬实时关断已经验证。
6. 每次检查 `ExecutionReport.spec.mode=hil`、协议签名、命令帧、ACK、位置/Hall 回读与失败后的 STOP_ALL。

完整固件协议、HIL 结果和手工回归工具位于 `firmware/t2g/Seat_Controller_demo/Docs` 与 `Tests/manual_hil`。