EMQX JT/T 808 网关新特性全解析:2019 协议、GBK 编码、未知消息透传与自定义报文序号
EMQX JT/T 808 网关新特性全解析:2019 协议、GBK 编码、未知消息透传与自定义报文序号
导读
本篇基于 EMQX 开源仓库变更记录(changes/ee/feat-16736.en.md)及其对应实现源码,系统讲解 JT/T 808 网关上线的六项关键能力:未知消息透明转发、JT/T 808-2019 协议支持、GBK 字符编码转换、下行自定义消息序号、CAN 总线参数消息修复与驾驶员身份报告解析修复。读完本文,你将掌握如何在 EMQX 中启用这些配置项(frame.parse_unknown_message、frame.string_encoding 等)、理解其底层实现原理,并学会利用测试套件验证行为,可直接应用于车联网终端接入与平台对接场景。
变更概览:一次补齐 JT/T 808 网关六项能力
JT/T 808 是中国交通运输行业标准的车载卫星定位系统终端与监控平台间数据交换协议,EMQX 通过 emqx_gateway_jt808 应用(见 apps/emqx_gateway_jt808)将该协议的终端事件与消息翻译为 MQTT Publish 消息。本次变更(由 PR #16220、#16596、#16609、#16619、#16627、#16655 合入)为网关带来:
| 变更项 | 类型 | 核心配置/涉及消息 |
|---|---|---|
| 未知消息透明转发 | 新增特性 | frame.parse_unknown_message |
| JT/T 808-2019 协议支持 | 新增特性 | 2019 版报文头自动识别 |
| GBK 字符编码支持 | 新增特性 | frame.string_encoding |
下行自定义 msg_sn |
新增特性 | 下行 MQTT payload 头部 msg_sn 字段 |
| CAN 总线 ID 参数类型修复 | 缺陷修复 | 参数设置 0x8103 / 查询应答 0x0104 |
| 驾驶员身份报告解析修复 | 缺陷修复 | 驾驶员身份信息上报 0x0702 |
下文逐一展开实现细节与配置方式。
未知消息透明转发:frame.parse_unknown_message
配置项说明
在网关上新增布尔配置项 frame.parse_unknown_message,默认值为 true,允许网关将无法识别的 JT/T 808 消息原样转发到 MQTT,而不是直接丢弃。其 Schema 定义位于 emqx_jt808_schema.erl:
parse_unknown_message(type) -> boolean();
parse_unknown_message(desc) -> ?DESC(parse_unknown_message);
parse_unknown_message(default) -> true;
parse_unknown_message(required) -> false;
实现原理
在 emqx_jt808_frame.erl 的 parse_message/2 中,当消息体解析抛出 unknown_message_id 异常时,会根据该配置决定行为:
- 配置为
true时,构造#{"unknown_id" => true, "data" => base64:encode(RestBinary)}的 body 继续上送,原始消息体以 base64 形式随 MQTT 消息透传,保证"不丢包"; - 配置为
false时,记录错误日志并抛出invalid_message,该帧被丢弃。
典型场景
当终端厂商使用私有扩展消息、或网关尚未内置某条新消息定义时,将该项保持默认 true 即可实现"应用层自己解析、平台侧透明转发"的架构,避免因网关不识别消息 ID 而中断上行链路。关闭则适用于严格校验、只允许标准消息进入 MQTT 的场景。
JT/T 808-2019 协议支持
2019 版报文头差异
2019 版协议相比 2013 版,在报文头做了三处关键扩展(实现见 emqx_jt808_frame.erl):
- 版本标识位:2019 版使用报文头第 14 位(version identifier bit)标记版本,置 1 表示 2019 格式;
- 协议版本号字段:2019 版头部新增 1 字节
proto_ver字段(?PROTO_VER_2019); - 终端电话号码长度:2019 版由 BCD[6](12 位号码)扩展为 BCD[10](20 位号码,高位补零)。
解析时通过头部位判断自动路由到对应分支:2019 版无分包时头部 17 字节、有分包时 21 字节;2013 版对应为 12/16 字节。解析结果统一产出 msg_id、encrypt、len、phone、msg_sn 等字段,proto_ver 仅在 2019 格式中出现,未出现时按 ?PROTO_VER_2013 处理,从而实现新旧协议在同一网关内共存。
2019 版消息体差异
部分消息体也按协议版本分叉解析,例如:
- 注册消息(0x0100):2019 版中厂商编码、终端型号、终端 ID 字段长度更大;
- 终端属性查询应答(0x0107):2019 版为 30 字节型号、30 字节 ID,2013 版为 20 字节型号、7 字节 ID(见 emqx_jt808_frame.erl);
- 驾驶员身份信息上报(0x0702):2019 版在 2013 版字段之后追加 20 字节身份证号(见下文修复章节)。
下行序列化同样依据头部 proto_ver 选择 BCD10]/BCD[6] 电话号码与版本位(见 [emqx_jt808_frame.erl)。测试套件中提供了完整的 2019 注册、鉴权流程用例(emqx_jt808_SUITE.erl),可作为对接参考;仓库还附带 JTT_808_2019-compare.md 新旧协议对比文档。
注意:应用内 README.md 仍标注"仅支持 2013 版",属于历史文档尚未同步,实际实现与测试已覆盖 2019 版,请以变更记录与源码为准。
GBK 字符编码支持:frame.string_encoding
背景
JT/T 808 协议规定 STRING 类型字段使用 GBK 编码,而 MQTT 报文负载规范为 UTF-8。此前网关对字符串字段原样透传,导致中文车牌号、驾驶员姓名、文本信息、区域名称、客户端参数等在跨协议传输时出现乱码。本次变更新增枚举配置 frame.string_encoding:
utf8(默认):字符串原样透传,保持向后兼容;gbk:上行时把设备发来的 GBK 字符串转换为 UTF-8 进入 MQTT,下行时把 MQTT 的 UTF-8 字符串转换为 GBK 发送给设备。
无论何种设置,MQTT 侧 payload 始终为 UTF-8,编码转换仅发生在网关与终端之间的线缆侧。
实现原理
转换逻辑集中在 emqx_jt808_encoding.erl:
maybe_decode_string/3(上行解析,GBK→UTF-8):当配置为gbk时调用egbk:to_utf8/1解码,并在结果中出现替换字符 U+FFFD 时输出gbk_decode_replacement告警日志(含字段名、原始字节十六进制与方向);maybe_encode_string/3(下行序列化,UTF-8→GBK):调用egbk:to_gbk/1编码,若输出中?数量相比输入增多(GBK 无法表达的字符被替换),记录gbk_encode_replacement告警;- 配置为
utf8或未配置时直接返回原值,零开销透传。
该转换被应用到所有 STRING 类型字段,包括车牌号、驾驶员姓名(见 emqx_jt808_frame.erl)、组织机构、文本消息、区域名称,以及 0x8103 参数设置中的字符串类型客户端参数(encode_cp_string/4 中同样调用 maybe_encode_string,见 emqx_jt808_frame.erl)。
配置示例
gateway.jt808 {
frame {
string_encoding = gbk # 或 utf8(默认)
}
}
对应测试覆盖了 GBK 双向转换与 UTF-8 透传两类行为(emqx_jt808_parser_SUITE.erl、emqx_jt808_SUITE.erl)。如果你的终端中文文本在 EMQX 侧显示乱码,将 string_encoding 设为 gbk 即可解决。
下行消息自定义 msg_sn
配置与用法
JT/T 808 网关默认使用通道内自增序号(channel.msg_sn,从 0 开始,0xFFFF 后回绕为 0,见 emqx_jt808_channel.erl)填充下行报文头。本次变更允许外部系统在下行 MQTT 消息 payload 的 header 中显式携带 msg_sn 字段,网关将优先使用该值,而非自动生成序号。
实现原理
关键逻辑在 emqx_jt808_channel.erl 的 build_downlink_header/3:
- 若 payload 头部没有
msg_sn:使用通道自增序号,并推进通道序号计数器(记录downlink_use_channel_msg_sn调试日志); - 若 payload 头部携带
msg_sn:使用该值构造报文头,且不推进通道计数器(记录downlink_use_payload_msg_sn信息日志),从而保证外部系统对报文的序号拥有完全控制权。
典型场景
- 需要与自有业务系统"一对一定位"每条下行指令的场景,例如指令下发的幂等去重;
- 需按外部规则排定报文序号(如批量指令下发、严格顺序要求的终端配置流程);
- 报文重发场景中希望复用原序号以匹配终端侧应答。
注意:由于自定义序号不经过通道自增计数器,若自行管理序号,需避免重复序号与终端 ACK 匹配混淆。实现中亦加入了自定义序号与自动序号的去重/顺序兼容处理(duplicate_custom_msg_sn_delivered、custom_msg_sn_after_auto 等告警路径,见 emqx_jt808_channel.erl)。
缺陷修复一:0x8103 / 0x0104 CAN 总线 ID 参数类型
问题描述
JT/T 808 参数设置消息(0x8103,下行)与参数查询应答消息(0x0104,上行)中的 CAN 总线 ID 单独采集设置参数(参数 ID 0x0110~0x01FF),协议规定其数据类型为 BYTE[8]。此前网关将其误当作字符串处理,导致 JSON 序列化出错。
修复内容
在 emqx_jt808_frame.erl 中,参数类型映射新增范围判断:
%% 0x0110~0x01FF: CAN bus ID individual collection settings, BYTE[8]
client_param_data_type(Id) when
Id >= ?CP_CAN_BUS_ID_PARAM_START andalso Id =< ?CP_CAN_BUS_ID_PARAM_END
->
byte8;
- 0x0110~0x01FF 范围参数映射为
byte8类型; - JSON 中该类型参数以 base64 编码表示 8 字节原始二进制(见
encode_cp_byte8/3,emqx_jt808_frame.erl:base64:decode/1后按 8 字节长度编码进参数块); - 其余 CAN 通道相关参数(0x0100~0x0104 采样/上传设置等)保持 word/dword 类型映射不变。
修复后,通过 Dashboard / API 下发 CAN 总线 ID 采集参数、或解析终端上报的参数查询应答时,均能得到正确的 base64 二进制字段。
缺陷修复二:0x0702 驾驶员身份信息上报解析
问题描述
驾驶员身份信息上报消息(0x0702)在 IC 卡读取结果为成功(ic_result = 0)时,携带驾驶员姓名、从业资格证号、发证机构、证件有效期等字段;2019 版还额外包含 20 字节身份证号。旧实现解析存在字段错位或无法区分版本的问题。
修复内容
解析逻辑见 emqx_jt808_frame.erl,修复后按状态分叉处理:
status = 1(插卡)且ic_result = 0(读卡成功)时,依次解析姓名长度/姓名、20 字节从业资格证号、机构长度/发证机构、4 字节证件有效期(BCD);- 当
proto_ver >= ?PROTO_VER_2019时,继续读取末尾 20 字节作为id_card(身份证号,去除尾部零填充);2013 版则无该字段; - 姓名与发证机构字段同时接入
maybe_decode_string/3,在string_encoding = gbk配置下自动完成 GBK→UTF-8 转换; - 读卡失败(
ic_result != 0)时仅返回状态与结果码。
修复后的上报 JSON 结构稳定,配合 GBK 配置可正确呈现中文驾驶员姓名与机构名称。
配置与验证指引
完整配置片段
gateway.jt808 {
frame {
max_length = 8192 # 帧最大长度,默认 8192
parse_unknown_message = true # 未知消息透明转发,默认 true
string_encoding = gbk # GBK 字符串转 UTF-8,默认 utf8
}
proto {
up_topic = "jt808/${phone}/up" # 上行主题模板
dn_topic = "jt808/${phone}/dn" # 下行主题模板
ignore_unsupported_frames = true
}
mountpoint = "jt808/${phone}/"
retry_interval = 8s
max_retry_times = 3
message_queue_len = 10
}
各配置项的 Schema 定义与默认值详见 emqx_jt808_schema.erl。除 emqx.conf 逐节点配置外,也可以通过 Dashboard 或 HTTP API 进行集群级配置(见 README.md)。
测试验证
仓库测试覆盖了本文全部特性,可用于验证行为:
- 未知消息转发:
t_enable_parse_unknown_message与关闭场景(emqx_jt808_parser_SUITE.erl),以及配置下发与生效断言(emqx_jt808_SUITE.erl); - 2019 协议全流程:2019 注册、鉴权、报文头格式断言(emqx_jt808_SUITE.erl);
- GBK/UTF-8 双向转换与透传(emqx_jt808_parser_SUITE.erl)。
运行网关应用测试可参考仓库 scripts/run-plugins-ct.sh 等测试脚本。
小结
本次变更从"可用性"与"兼容性"两个维度完善了 EMQX JT/T 808 网关:parse_unknown_message 消除未知消息丢包风险,2019 协议支持扩大终端接入范围,string_encoding 解决中文乱码这一车联网高频痛点,自定义 msg_sn 把下行序号控制权交还业务系统,同时修复 CAN 总线参数类型与 0x0702 解析两处缺陷。配合仓库内完整源码与测试套件,开发者可快速完成网关升级、配置调优与问题排查。