结论：这份档案的对象是一套面向 2014 年及以后 Kia Soul（汽油与纯电）的开源车辆控制项目（OSCC），它把「读取车辆状态」和「下发控制命令」拆成 API 与固件两层：固件侧用专门的模块通过转向力矩/油门位置/制动位置传感器与 OBD-II CAN 交互，API 侧用归一化数值下发命令、并通过回调接收回报。它的数据特征是命令归一化 + 200 ms 保活：制动与油门为 [0.0, 1.0]、转向为 [-1.0, 1.0]，且每个发布函数必须至少每 200 ms 调用一次，否则模块判为通信丢失并自行禁用。源文档未给出比特率、寻址方式与逐字节定义，其结论仅限 2014 年起的 Kia Soul 平台。
车辆与适用范围
源文档是一个软硬件项目仓库的说明：它描述 API、固件与硬件三部分，以及可扩展的车型头文件机制。数据来自项目文档，不是某台实车的采集记录。
| 项 | 内容 |
|---|---|
| 车型 | Kia Soul（2014 年及以后，汽油与纯电）；构建目标另含 Kia Niro |
| 年款 / 市场版本 | 源文档以「Kia Soul PS（2014–2018）」指代已整理信息的平台；其他年款与市场版本未确认 |
| ECU / 改装状态 | 加装 OSCC 模块：传感器接口板（转向/油门）、整车控制模块（纯电制动）或执行器控制板（汽油制动），外加 CAN 网关 |
| 采集跨度 | 源文档未提供（无日志数或事务数） |
| 适用范围 | 源文档明确「目前仅支持 2014 年起的 Kia Soul」，API 与固件按易扩展设计，但其他车型属未来扩展 |
总线与寻址
源文档把总线分成「车辆 OBD-II CAN」与「OSCC 控制 CAN」两条，固件用 CAN 网关模块在两段之间转发；但未描述物理层与标识符细节。
| 项 | 内容 |
|---|---|
| 物理层 / 比特率 | 源文档未给出 |
| 总线划分 | 车辆 OBD-II CAN 网络（读状态、发命令、接收回报）；OSCC 控制 CAN（API 与固件模块之间） |
| 寻址方式 | 源文档未给出；API 以「CAN 通道 + 标准化信号名」抽象，不暴露标识符 |
| CAN FD | 源文档未提供 |
| 接口形态 | 固件以 Arduino + 专用扩展板实现，经 USB 串口烧写与监控 |
已解码信号
下表登记源文档明确给出的接口面（命令、回报与关键参数）。位置列写接口名而非字节偏移，因为源文档只以标准化信号与回调形式暴露它们；「证据」一列注明其出处为 API 说明、固件说明或构建选项。
| 信号 / 接口 | 位置（API / 模块） | 取值与含义 | 证据 |
|---|---|---|---|
| 制动位置命令 | publish_brake_position() |
归一化 [0.0, 1.0]，转发到制动固件模块 |
API 说明 |
| 转向力矩命令 | publish_steering_torque() |
[-1.0, 1.0]，-1 为逆时针、+1 为顺时针 |
API 说明 |
| 油门位置命令 | publish_throttle_position() |
归一化 [0.0, 1.0] |
API 说明 |
| 制动回报 | oscc_brake_report_s |
通过 subscribe_to_brake_reports() 回调 |
API 说明 |
| 转向回报 | oscc_steering_report_s |
含转向角；通过 subscribe_to_steering_reports() 回调 |
API 说明 |
| 油门回报 | oscc_throttle_report_s |
通过 subscribe_to_throttle_reports() 回调 |
API 说明 |
| 故障回报 | oscc_fault_report_s |
通过 subscribe_to_fault_reports() 回调 |
API 说明 |
| OBD 原始帧 | subscribe_to_obd_messages() |
转发车辆 OBD-II CAN 上的非 OSCC 帧，按帧 ID 自行解析 | API 说明 |
| 轮速 | 车辆回报（当前控制状态） | 源文档以「转向角与轮速」为例说明可回报的车辆控制状态 | 项目说明 |
| 使能 / 禁用 | oscc_enable() / oscc_disable() |
只影响是否可发送命令；回报随时可收 | API 说明 |
| 通道开关 | oscc_open(channel) / oscc_close() |
打开/关闭与 OSCC 控制 CAN 的套接字连接 | API 说明 |
| 保活超时 | 三个发布函数 | 每个须至少每 200 ms 调用一次，否则模块判失联并自禁用 | API 说明 |
| 转向过载阈值 | TORQUE_DIFFERENCE_OVERRIDE_THRESHOLD |
调整转向人工接管灵敏度；过低会误判、过高难接管 | 构建/配置说明 |
| 电压范围检查 | API 内部安全校验 | 拒绝发送超出车辆预期范围的电压 | API 说明 |
读取方法与注意事项
生命周期由三组调用界定：oscc_open(channel) 打开控制 CAN 的套接字，oscc_enable() / oscc_disable() 决定是否允许发送命令，oscc_close() 结束。源文档提示 API 会捕获 CAN 帧到达时的 SIGIO 信号并注册处理器转发有效帧，因此在容易被中断冲突的代码段应临时屏蔽该信号、之后再解除。
最关键的运行约束是节拍：三个发布函数每个都必须至少每 200 ms 调用一次，否则固件模块会判定与上位机失去通信并自行禁用。也就是说，「不发命令」本身是一种保护动作；程序崩溃或卡顿时会自动退出控制，这是设计意图而非缺陷。
人工接管方面，源文档默认对所有模块启用接管检测，但明确提示：系统激活时试图抓方向盘可能造成严重伤害，推荐用制动踏板或急停按钮作为转向接管手段；如需关闭转向接管检测，可在构建时传 -DSTEERING_OVERRIDE=OFF。构建还需按车型选择标志（-DVEHICLE=kia_soul、kia_soul_ev 或 kia_niro）；对早于 1.2.0 的执行器控制板，需加 -DBRAKE_STARTUP_TEST=OFF 以跳过与该板不兼容的启动测试。
证据等级与边界
本文的证据等级是「项目文档级」：命令取值区间、回调接口、200 ms 保活与构建标志都可在源文档逐条核对，属于直接证据；但源文档没有逐信号解码表，也没有实车日志，因此本文不提供标识符、字节偏移或缩放系数。要落到具体字节，需回到固件与车型头文件（本快照未包含逐字节定义）。
两点不能外推。第一，源文档明确「目前仅支持 2014 年及以后的 Kia Soul」（汽油与纯电），Kia Niro 为构建目标；把接口面外推到其他起亚车型或其他品牌属于超范围。第二，各模块的板卡版本与固件版本需按源文档的对应表配套使用，混用可能触发已知安全问题的旧版本；源文档特别强调应及时更新。关于安全访问，源文档未提供任何绕过方法，且不建议尝试；项目自述其设计不改变厂方安全用例、不伪造 CAN 消息、不入侵 ADAS 功能，本档案仅描述这一接口面。
常见问题
为什么命令必须每 200 ms 发一次？
因为固件模块以 200 ms 作为与上位机的通信存活判据：任一发布函数连续超过该时间未被调用，模块就判为失联并自行禁用。这是有意的失效保护——程序卡死时会自动退出控制，而不是保持最后一个命令。
转向接管该怎么做？
源文档建议用制动踏板或急停按钮，而不是直接抓方向盘——后者在系统激活时可能造成严重伤害。若确实要关闭转向接管检测，可用 -DSTEERING_OVERRIDE=OFF 构建；保留检测时，灵敏度由 TORQUE_DIFFERENCE_OVERRIDE_THRESHOLD 调整，过低会在大扭矩区误判、过高则难以手动接管。
能从这套系统直接读到车辆的所有信号吗？
不能仅凭本文判断。API 提供的是结构化回报（制动/转向/油门/故障）与一个 subscribe_to_obd_messages() 回调，后者转发车辆 OBD-II CAN 上的非 OSCC 帧，需要按帧 ID 自行解析。源文档未给出这些帧的逐字节定义。
这套接口能套用到别的起亚车型吗？
源文档明确目前仅支持 2014 年起的 Kia Soul（汽油与纯电），Kia Niro 为构建目标；API 与固件按易扩展设计，但新增车型需按车型头文件格式补齐信息。直接外推到其他车型超出源文档证据范围。
延伸阅读
- 从使能到车轮：执行链上的八道门，以及它们各自不保证什么 —— 对应本文「使能/禁用 + 200 ms 保活 + 电压范围检查」的多道许可。
- UDS 诊断工具为什么不能随手调：只读、会话与写 ECU 的分权设计 —— 与本文「读随时可、写须使能」的分权思路一致。
- openpilot 的 100 Hz 控制回路：开源 ADAS 能给车载设备什么 —— 与本文控制命令节拍的下位对照。
- 同一个「转向灯」在三家车厂是三种实现：车辆状态归一化的坑 —— 解释本文为何用归一化命令而屏蔽标识符。
- Hyundai 控制输出：经典 CAN 与 CAN FD 两条构帧路径与独立安全门 —— 同为韩系平台的输出侧对照。
参考资料
- 项目 01 ——
public-can-dbc-datasets/additional/polysync-oscc/README.md（本项目车型档案主来源：API 与固件接口、命令归一化范围、200 ms 保活、构建标志与支持车型）。 - 项目 01 ——
public-can-dbc-datasets/additional/polysync-oscc/LICENSE.md（硬件为 CC BY-SA 4.0、固件与软件为 MIT 的许可划分）。
说明：本文整理自第三方开源项目的公开文档，仅代表该文档所记录的单个车辆样本，不代表同型号全系车型。CAN 与诊断操作存在风险，任何实车操作前请自行复核并遵守当地法规。
更新记录
首次发布 2026-10-11 最近核对：2026-10-11