
GR-01 接口协议与开发接入
查阅HTTPS、Modbus RTU、CAN、MQTT与Python SDK的协议版本、数据定义和接入示例。
版本:接入协议1.0 / Python SDK 1.0,2026-11。
接口与数据分工
完整本地流程从车辆自然停稳并形成有效检测事件开始,到本地报告生成不超过10秒;有效分析窗口最低1.5秒、推荐1.5—3秒,窗口结束后3秒内生成本地报告。网络传输、平台接收与小程序消息送达单独记录。
GR-01在车辆于道闸附近自然短暂停稳时检测发动机磁场,不要求重启。基本系统提供GR-Insight独立报告管理端,不接停车平台也能查看报告。支持汽油、柴油、HEV/PHEV和增程发动机;纯电不适用,发动机未运行与采集条件未满足分别记录,检测状态清晰呈现。
| 通道 | 用途 |
|---|---|
| CAN 2.0B | 心跳、状态、最新事件索引 |
| Modbus RTU | PLC轮询只读状态和事件寄存器 |
| MQTT 3.1.1/TLS | 订阅设备状态和事件索引 |
| HTTPS / Python SDK 1.0 | 完整报告、故障部位原因、漏收事件查询 |
| HTTPS事件提交1.0 | 向停车场接收端提交完整报告并取得持久化回执 |
低带宽通道不分片塞入完整报告或波形。以站点、设备、streamId、eventIndex定位事件,以eventId、reportId、reportRevision管理正文和修订。eventIndex为持久化uint32,范围1–4294967295,0表示无事件,重启不复位;耗尽前切换streamId,同一流不回绕。流切换或设备更换后读能力接口重建游标,不跨流比较索引。
局域网管理端示例为https://192.168.10.20,MQTT Broker为192.168.10.20:8883。项目CA签发包含所配IP SAN的证书,客户端安装CA并校验证书。IP、站点和节点在交付单登记。公共产品网站提供资料下载,不承担事件接收、队列或账号后台。
结果状态
| 值 | 状态 | 含义 |
|---|---|---|
| 0 | pending | 尚无完成结果或处理中 |
| 1 | valid_reference_match | 有效,参考模式内 |
| 2 | valid_abnormal_pattern | 有效异常,部位原因见正文 |
| 3 | engine_not_running | 未运行,未检测 |
| 4 | not_applicable_bev | 纯电不适用 |
| 5 | quality_insufficient | 采集条件未满足,未检测 |
| 6 | engine_running_unknown | 运行状态待判定,本次未检测 |
| 7 | unknown_model | 已运行且质量通过,型号待建档 |
| 255 | unknown | 未识别状态,保留原码并取报告 |
状态3–7不附故障条目。有效异常要求发动机已运行、质量通过。掉线是通信状态,不映射为车辆正常或异常。多退出原因沿用事件接口第八节。
CAN 2.0B应用协议1.0
经典CAN扩展数据帧、29位ID、250 kbit/s、DLC=8;不使用CAN FD、远程帧或控制命令。node为1–127,同一总线独立分配。线型屏蔽双绞线仅两端各接120 Ω终端,参考地按隔离接口接线图连接。
| 报文 | 扩展ID | 时机 | 8字节布局 |
|---|---|---|---|
| 心跳 | 0x18FF1000 OR node | 每1秒 | B0=1主版本;B1=0次版本;B2=设备状态;B3=标志;B4–7=启动秒数 |
| 最新事件 | 0x18FF1100 OR node | 完成或修订后立即,再每1秒重复最新一条 | B0=1;B1=结果状态;B2=标志;B3=修订提示;B4–7=eventIndex |
多字节整数均为无符号大端。设备状态:0初始化、1就绪、2降级、3设备故障。标志bit0=本地报告可读,bit1=时间同步,bit2=容量告警,bit3=外部提交待传,其余发送0、接收端忽略未知位。事件B3为修订号1–254;修订≥255发255,完整值通过HTTPS读取。无事件时状态、索引、修订均0。启动秒数允许uint32回绕,不作事件号。
节点1、有效异常、报告可读且时间同步、修订1、索引42:ID=0x18FF1101 DATA=01 02 03 01 00 00 00 2A。连续3秒无心跳标记通信中断,恢复读能力和列表补齐。周期帧用于设备状态展示;完整报告收妥与岗位查看分别通过对应回执和查看日志核对。设备按只读方式接入,通行由原停车系统管理。
Modbus RTU 1.0
对外隔离RS-485作为从站,默认站号1,19200 bit/s、8E1,站号1–247。对外端口与传感器内部RS-485分开,外部主站不得接入内部链路。仅支持功能码04(Read Input Registers)。CRC16低字节先传,寄存器内部高字节先传;uint32高字在低地址,即ABCD。帧间隔至少3.5字符时间,建议轮询1秒、超时500 ms、最多重试2次。
下表为PDU零基地址,30001对应地址0。一次从0读16个寄存器,设备返回同一时刻快照;拆读不能拼成同一事件。
| 地址 | 参考编号 | 类型 | 含义 |
|---|---|---|---|
| 0 | 30001 | uint16 | 版本0x0100 |
| 1 | 30002 | uint16 | 设备状态,与CAN相同 |
| 2 | 30003 | uint16 | 标志,低4位与CAN相同 |
| 3 | 30004 | uint16 | 最新结果状态 |
| 4–5 | 30005–30006 | uint32 | eventIndex,0=无事件 |
| 6–7 | 30007–30008 | uint32 | 完整reportRevision,0=无事件 |
| 8–9 | 30009–30010 | uint32 | 启动秒数,允许回绕 |
| 10–11 | 30011–30012 | uint32 | 每次04响应递增的快照序号,允许回绕 |
| 12 | 30013 | uint16 | CAN节点号1–127 |
| 13–15 | 30014–30016 | uint16 | 保留,发0 |
索引42对应寄存器4=0x0000、5=0x002A。写功能返回异常01,越界返回02,不允许修改阈值、结论或报告。遗漏用HTTPS补齐,连续相同状态不代表无新事件。
MQTT 3.1.1/TLS主题协议1.0
TLS 1.2或以上,Broker 192.168.10.20:8883,用户名密码按项目分配,ACL按站点设备授权。ClientId每连接唯一,Keep Alive=30秒,Clean Session=false,重连复用ClientId。持久会话离线QoS1消息保存24小时,超期或积压超限用HTTPS补齐。凭据不进payload。
| 主题 | QoS | retained | 内容 |
|---|---|---|---|
| neuralan/v1/{siteId}/{deviceId}/availability | 1 | true | online/offline、streamId |
| neuralan/v1/{siteId}/{deviceId}/state | 1 | true | 设备状态、最新索引、修订 |
| neuralan/v1/{siteId}/{deviceId}/events | 1 | false | 完成或修订事件索引 |
主题标识只含字母、数字、短横线、下划线,不含/、+、#。遗嘱向availability发布offline,连接成功发布online;失联不等于发动机故障。payload为UTF-8 JSON,最多512字节:
{"protocolVersion":"1.0","streamId":"GR01-001-A","eventIndex":42,"reportRevision":1,"status":2,"replayed":false}以站点、设备、流、索引、修订去重,再经HTTPS取完整报告。QoS1可能重复,PUBACK只确认Broker接收,不代表报告持久化、通知送达或人员已读。不开放指令主题,主题不含车牌、VIN或人员信息。
HTTPS报告查询1.0
基础地址https://192.168.10.20;请求头Accept: application/json、X-NEURALAN-Token: <项目只读令牌>。权限限定站点和设备,令牌不放URL,不自动跨地址跳转。
| GET路径 | 200响应用途 |
|---|---|
| /api/v1/capabilities | 版本、设备与流能力 |
| /api/v1/events?streamId=GR01-001-A&after=41&limit=100 | 增量索引,limit为1–100 |
| /api/v1/events/42?streamId=GR01-001-A | 映射到eventId、reportId和最新修订 |
| /api/v1/reports/NR-RPT-20261114-02?revision=1 | 指定版本完整neuralan-report/1.0 JSON |
| /reports/NR-RPT-20261114-02?revision=1 | 人员详情页,使用管理端登录会话 |
能力对象含apiVersion:"1.0"、reportSchemaVersion:"neuralan-report/1.0"、eventProtocolVersion:"neuralan-events/1.0"、streamId、siteId、deviceId、firstAvailableIndex、supportedStatuses(0–7)。映射含streamId、eventIndex、eventId、reportId、reportRevision。详情diagnosis.findings保存部位、原因、依据与范围,正文沿用现有报告契约。
增量页含items(映射数组)、nextAfter、hasMore、streamId,索引升序;空页nextAfter保持after。after=0从可用首条开始,非零游标早于保留范围返回410及firstAvailableIndex。游标只发现新事件,修订通过MQTT提示或重新查映射获取;恢复时重查仍在处理的事件映射,不把索引游标当作修订变更流。持久保存报告后再推进业务游标。
JSON为UTF-8,报告最大1 MiB。错误对象含error.code和error.message:401令牌无效、403越权、404不存在、409流不匹配、410超保管范围、422参数错误、429限流、503暂不可用;429按Retry-After等待,连接失败和503递增等待。GET用于报告查询,事件回执由提交接口返回。完整报告提交另按事件接口与数据流程的POST信封、幂等和persisted回执执行,查询和提交权限分开。
Python SDK 1.0
配套gr01_sdk.py仅用Python标准库,Python 3.10及以上,提供HTTPS查询、CAN事件和Modbus快照解析。导入不联网,不含服务器或真实凭据。调用方主动执行:
import os
from gr01_sdk import GR01Client
client = GR01Client("https://192.168.10.20", os.environ["NEURALAN_TOKEN"], ca_file="project-ca.pem")
cap = client.capabilities()
page = client.events(cap["streamId"], after=0, limit=100)
for item in page["items"]:
report = client.report(item["reportId"], item["reportRevision"])
print(report["reportId"], report["diagnosis"]["status"])SDK不自动通知或重试,不把游标当持久化回执,错误通过GR01Error暴露,由集成方按项目规则处理。
授权关联和输出
GR-01不依赖摄像头/OBD,不从磁场生成车牌、VIN或唯一发动机号。仅授权外部系统提供可靠通行记录时关联车辆,记录来源、外部记录号、时间和操作者;无来源为null、维持匿名事件。型号和档案ID不是唯一车辆身份,时间接近不能单独证明同车。关联在平台业务层记录;改变报告正文须增修订,不覆盖原版。
LED显示“检测完成”“发动机未运行”“本次采集条件未满足”“请查看发动机报告”等摘要,离线显示连接状态,不公开敏感身份。打印端从完整报告生成设备、时间、结果和编号,二维码指向管理端详情页并保留授权。小程序通过运营方服务端读取授权报告,令牌不下发客户端,只向用户展示自身获授权记录;无可靠身份不向猜测的车主推送。输出失败独立记录,不改诊断,打印成功不等于人已读。
兼容与交付
CAN主版本在B0、次版本在心跳B1;Modbus版本在寄存器0;MQTT在主题v1和payload;HTTPS在/api/v1及能力对象;SDK为1.0.0。次版本只新增可忽略字段或保留位,改变既有语义、布局或必填约束升主版本。未知主版本停止解释,未知状态保留原码、不降级正常;新增状态先协商能力。报告和事件接口独立版本化,沿用报告版本不代表旧端支持扩展枚举。
交付检查节点端口、CA令牌、全部状态、断线恢复、重复修订、越权及保管范围衔接,再检查LED、打印和小程序输出。启用表登记设备、端点、版本和检查结果。集成支持:integration@parkneural.com;设备支持:support@parkneural.com。
开发下载
文件随接入包提供,定义协议和客户端,不安装接收服务。