GR-01终端、边缘单元和参考组件的系统展示

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 RTUPLC轮询只读状态和事件寄存器
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、站点和节点在交付单登记。公共产品网站提供资料下载,不承担事件接收、队列或账号后台。

结果状态

值状态含义
0pending尚无完成结果或处理中
1valid_reference_match有效,参考模式内
2valid_abnormal_pattern有效异常,部位原因见正文
3engine_not_running未运行,未检测
4not_applicable_bev纯电不适用
5quality_insufficient采集条件未满足,未检测
6engine_running_unknown运行状态待判定,本次未检测
7unknown_model已运行且质量通过,型号待建档
255unknown未识别状态,保留原码并取报告

状态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个寄存器,设备返回同一时刻快照;拆读不能拼成同一事件。

地址参考编号类型含义
030001uint16版本0x0100
130002uint16设备状态,与CAN相同
230003uint16标志,低4位与CAN相同
330004uint16最新结果状态
4–530005–30006uint32eventIndex,0=无事件
6–730007–30008uint32完整reportRevision,0=无事件
8–930009–30010uint32启动秒数,允许回绕
10–1130011–30012uint32每次04响应递增的快照序号,允许回绕
1230013uint16CAN节点号1–127
13–1530014–30016uint16保留,发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。

主题QoSretained内容
neuralan/v1/{siteId}/{deviceId}/availability1trueonline/offline、streamId
neuralan/v1/{siteId}/{deviceId}/state1true设备状态、最新索引、修订
neuralan/v1/{siteId}/{deviceId}/events1false完成或修订事件索引

主题标识只含字母、数字、短横线、下划线,不含/、+、#。遗嘱向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。

开发下载

文件随接入包提供,定义协议和客户端,不安装接收服务。

开发文件下载