JT808 协议接入

本文档说明 SiliZap 平台对 JT/T 808-2019 设备的接入方式，适用于已经使用 JT808 TCP 协议上报定位、心跳、鉴权等数据的终端。

当前平台采用：

终端设备通过 JT808 TCP 连接接入
平台服务端完成 JT808 -> SZ-JSON MQTT 协议转换
转换后统一进入平台原生 MQTT 主题体系
Web、小程序、告警、规则引擎等上层能力无需感知终端原始 JT808 报文格式

如果你的设备本身已经支持平台 SZ-JSON MQTT 协议，建议优先参考 MQTT协议（SZ-JSON）；如果是车载定位器、资产定位器、国标定位终端等 JT808 设备，则按本文方式接入。

一、总体架构

JT808 接入的完整链路如下：

设备通过 TCP 连接到 JT808 接入服务
终端发送 0x0100 注册、0x0102 鉴权、0x0002 心跳、0x0200 位置汇报
平台服务端解析 JT808 报文，并维护设备在线会话
鉴权成功后，桥接服务以平台设备身份连接 MQTT
服务端将 JT808 数据转换为平台 SZ-JSON 并发布：
- info/post
- property/post
- event/post
平台下发的 function/get、monitor/get 等指令会被转换回 JT808 下行指令，再发送给终端

二、适用场景

适合以下终端类型：

JT808 车载终端
基于 JT808 二次开发的定位器
使用手机号字段承载设备编号的 TCP 定位设备
需要兼容现有国标定位协议，同时接入 SiliZap 物联网平台的设备

三、连接参数

3.1 TCP 接入

终端连接参数由平台分配，常见包括：

host：JT808 TCP 服务地址
port：JT808 TCP 服务端口
phone：终端手机号字段
auth_code：注册成功后平台返回的鉴权码

其中：

phone 字段必须和终端头部保持一致
平台支持将“前导 0 + IMEI”形式的手机号还原为设备实际 IMEI
当 MQTT 桥接启用时，平台会优先使用鉴权报文中的 IMEI 作为 device_id

示例：

IMEI: 862419074519256
phone: 00000862419074519256

3.2 MQTT 桥接认证

JT808 终端本身不需要直接连接 MQTT。

当终端完成 JT808 鉴权后，平台桥接服务会代表设备连接 MQTT，并按平台产品配置生成认证信息：

javascript

// 客户端ID = 认证类型 + 设备编号 + 产品ID + 用户ID
Client ID = "S|E" + "&" + device_id + "&" + product_id + "&" + user_id

// 用户名
Username = MQTT账号

// 密码
Password = MQTT密码 或 Token

其中：

device_id：默认使用鉴权报文中的 IMEI
product_id：平台产品 ID
user_id：平台用户 ID
S：简单认证
E：Token 加密认证

详细 MQTT 认证规则见 MQTT协议（SZ-JSON）。

四、JT808 上报报文

4.1 注册 `0x0100`

平台按 JT/T 808-2019 解析注册报文，主要使用以下字段：

省域 ID
市县域 ID
制造商 ID
终端型号
终端 ID
车牌颜色
车牌号

这些信息会保存到设备会话中，并在后续 info/post 的 summary 中参与上报。

4.2 鉴权 `0x0102`

平台支持标准 2019 鉴权结构，也支持在标准字段后追加 JSON 扩展信息。

当前兼容格式：

plain

+--------------------------------------------------------------+
| auth_length(1) | auth_code | imei(15) | version(20) | extra |
+--------------------------------------------------------------+

其中 extra 为可选 UTF-8 JSON，推荐用于补充终端关键元数据，例如：

json

{
  "fversion": "LuatOS-SoC_1.2.3",
  "rssi": 23,
  "userId": "1922956817214873666",
  "uuid": "d51726cc634f4738bd12328a3c026271",
  "iccid": "898608271025D1379254",
  "rtm_id": 137,
  "chip": "EC718P",
  "summary": {
    "electricity": 60,
    "keepalive_interval": 30,
    "gps_interval": 30,
    "sleep_interval": 0,
    "device_model": 1,
    "product": "SZ-4G01",
    "author": "silizap",
    "create": "2025-05-18",
    "name": "device"
  }
}

4.3 心跳 `0x0002`

平台收到心跳后会：

更新设备最后在线时间
维持 JT808 在线会话
确保已建立的 MQTT 桥接连接继续可用

4.4 位置汇报 `0x0200`

平台会解析：

经度、纬度
海拔
速度
方向
时间
附加信息

已支持的附加信息包括：

0x30：无线通信网络信号强度 gprs
0x31：卫星数
0xE0：电量 electricity
0xE1：电池电压 vbat_mv
0xE2：定位类型 loc_type

其中定位类型约定：

1：GPS
2：LBS
3：WiFi

五、平台 MQTT 主题映射

JT808 终端数据经过服务端转换后，统一进入平台标准主题：

5.1 设备信息上报

plain

$sys/{product_id}/{device_id}/silizap/info/post

典型消息：

json

{
  "did": "0db795ee45fe93a2eda268a3fda76976",
  "version": "1.0",
  "params": {
    "time": "2026-02-24 17:01:03",
    "timestamp": 1771923663581,
    "info": {
      "longitude": "",
      "latitude": "",
      "version_name": "SZJT808-2019",
      "fversion": "LuatOS-SoC_1.2.3",
      "rssi": 23,
      "status": 3,
      "summary": {
        "electricity": 60,
        "keepalive_interval": 30,
        "gps_interval": 30,
        "sleep_interval": 0,
        "device_model": 1,
        "product": "SZ-4G01",
        "author": "silizap",
        "create": "2025-05-18",
        "name": "device",
        "manufacturer": "SILIZAP2019",
        "terminal_model": "MODEL-TEST-2019"
      },
      "userId": "1922956817214873666",
      "uuid": "d51726cc634f4738bd12328a3c026271",
      "iccid": "898608271025D1379254",
      "rtm_id": 137,
      "chip": "EC718P",
      "protocol": "JT808",
      "device_id": "862419074519256",
      "imei": "862419074519256"
    }
  }
}

5.2 属性上报

plain

$sys/{product_id}/{device_id}/silizap/property/post

常见属性包括：

longitude
latitude
altitude
speed_kmh
speed_mps
direction
loc_type
loc_type_name
alarm_bits
status_bits
gprs
mobile_signal
satellite
electricity
vbat_mv

5.3 事件上报

plain

$sys/{product_id}/{device_id}/silizap/event/post

当前会将 JT808 报警标志位映射为平台事件，例如：

jt808_alarm_bits

六、平台下行控制与 JT808 映射

平台会使用以下主题向 JT808 设备下发业务指令：

plain

$sys/{product_id}/{device_id}/silizap/function/get
$sys/{product_id}/{device_id}/silizap/monitor/get

6.1 `function/get` 到 JT808 的映射

当前已支持的 function/get 映射关系如下：

平台命令	说明	JT808 下行
`sensorname=status`, `sensorcmd=open`	刷新终端当前状态	`0x8201`
`sensorname=location_query`, `sensorcmd=get`	查询位置信息	`0x8201`
`sensorname=tracking`, `sensorcmd=open`	临时位置跟踪	`0x8202`
`sensorname=tracking`, `sensorcmd=close`	关闭临时位置跟踪	`0x8202`
`sensorname=restart`, `sensorcmd=open`	远程重启终端	自定义 `0x8F01`

终端执行后，平台会按标准 MQTT 回执主题返回：

plain

$sys/{product_id}/{device_id}/silizap/function/get_reply

6.2 `monitor/get` 到 JT808 的映射

monitor/get 主要用于配置同步、组合控制和批量下发。当前 JT808 桥接已支持以下映射：

平台命令	说明	JT808 下行
`sensorname=deviceconfig`, `sensorcmd=open`	同步设备运行配置	自定义 `0x8F10`
`sensorname=rtmconfig`, `sensorcmd=open`	同步网络与平台连接配置	自定义 `0x8F11`
`sensorname=tracking`, `sensorcmd=open`	开启临时跟踪	`0x8202`
`sensorname=tracking`, `sensorcmd=close`	关闭临时跟踪	`0x8202`

其中：

deviceconfig 用于设备运行配置，如上报周期、休眠时间、模式等
rtmconfig 用于平台连接配置，如服务器地址、端口、保活、定位类型、产品密钥等
monitor/get 支持一次下发多个 params，服务端会拆成多条 JT808 下行命令分别发送给终端

6.3 `deviceconfig` 下发示例

平台下发：

json

{
  "did": "KTCWPx00ckooPz98GgDFUdJSwCtHUjpw",
  "params": [
    {
      "extdata": {
        "cmd_ext": 0,
        "deeprest_interval": 600000,
        "device_model": 1,
        "gps_interval": 10,
        "interval": 10000,
        "scan_interval": 60,
        "sleep_interval": 0,
        "uuid": "5842d0ae4e50465d81ad7fc716302b8c"
      },
      "sensorcmd": "open",
      "sensorname": "deviceconfig"
    }
  ],
  "version": "1.0"
}

终端收到后建议行为：

覆盖本地运行配置
持久化到本地存储
立即刷新定时上报周期
成功后返回 monitor/get_reply

6.4 `rtmconfig` 下发示例

平台下发：

json

{
  "version": "1.0",
  "params": [
    {
      "sensorname": "rtmconfig",
      "sensorcmd": "open",
      "extdata": {
        "log_flag": 0,
        "mqtt_port": 1883,
        "mqtt_domain": "iot.silizap.com",
        "mqtt_password": "PFZqWGRMRjhYZHNLMHU0RzA4RHl3NEcwZWdWR01QY28=",
        "mqtt_username": "gQxu0Ro7JP",
        "location_types": ["gps", "lbs", "wifi"],
        "product_secret": "KTdQQ1hDallzenF6akkzWFRPc2R6Y3hmR05RUnp6UXc=",
        "keepalive_interval": 30,
        "mqtt_encryptionmode": "S",
        "rtm_id": 147
      }
    }
  ],
  "did": "jbQyyAXvIJuRCMIoLwe71AWzRk2oflLp"
}

终端收到后建议行为：

覆盖本地网络接入配置
持久化到本地存储
先返回业务应答
再主动重启设备，使新的服务器地址和端口生效

说明：

对 JT808 终端而言，mqtt_domain、mqtt_port 在桥接场景下通常表示“下一次 JT808 TCP 连接应连接到的服务端地址与端口”
location_types 建议直接持久化，供终端决定当前允许使用的定位来源

6.5 批量下发示例

平台支持同一个 monitor/get 中同时携带多个配置项，例如同时下发 deviceconfig + rtmconfig：

json

{
  "did": "KTCWPx00ckooPz98GgDFUdJSwCtHUjpw",
  "params": [
    {
      "extdata": {
        "cmd_ext": 0,
        "deeprest_interval": 600000,
        "device_model": 1,
        "gps_interval": 10,
        "interval": 10000,
        "scan_interval": 60,
        "sleep_interval": 0,
        "uuid": "5842d0ae4e50465d81ad7fc716302b8c"
      },
      "sensorcmd": "open",
      "sensorname": "deviceconfig"
    },
    {
      "extdata": {
        "keepalive_interval": 60,
        "mqtt_domain": "iot.silizap.com",
        "mqtt_encryptionmode": "S",
        "mqtt_password": "PFZqWGRMRjhYZHNLMHU0RzA4RHl3NEcwZWdWR01QY28=",
        "mqtt_port": 1883,
        "mqtt_username": "gQxu0Ro7JP",
        "product_secret": "KTdQQ1hDallzenF6akkzWFRPc2R6Y3hmR05RUnp6UXc=",
        "rtm_id": 135
      },
      "sensorcmd": "open",
      "sensorname": "rtmconfig"
    }
  ],
  "version": "1.0"
}

平台桥接服务会等待终端逐条应答，并汇总为一次 monitor/get_reply 返回。

6.6 `monitor/get_reply` 回执结构

典型回执示例：

json

{
  "did": "KTCWPx00ckooPz98GgDFUdJSwCtHUjpw",
  "version": "1.0",
  "code": 200,
  "msg": "",
  "time": "2026-04-22 12:11:21",
  "timestamp": 1776831081000,
  "params": {
    "results": [
      {
        "command": "deviceconfig",
        "message_id": 36624,
        "sequence": 17,
        "reply_message_id": 36624,
        "reply_sequence": 17,
        "code": 200,
        "msg": "success",
        "result": 0
      },
      {
        "command": "rtmconfig",
        "message_id": 36625,
        "sequence": 18,
        "reply_message_id": 36625,
        "reply_sequence": 18,
        "code": 200,
        "msg": "success",
        "result": 0
      }
    ],
    "functions": [
      {
        "sensorname": "deviceconfig",
        "sensorcmd": "open",
        "extdata": {
          "gps_interval": 10,
          "uuid": "5842d0ae4e50465d81ad7fc716302b8c",
          "code": 200
        }
      },
      {
        "sensorname": "rtmconfig",
        "sensorcmd": "open",
        "extdata": {
          "mqtt_domain": "iot.silizap.com",
          "rtm_id": 135,
          "code": 200
        }
      }
    ]
  }
}

字段说明：

did：与平台原始下发保持一致
params.results：JT808 逐条命令的执行结果
params.functions：按平台原始命令维度回显，便于前端直接渲染
code=200：整批命令全部成功
code=500：整批命令中存在失败项

七、设备实现建议

7.1 终端手机号与设备号

建议：

终端真实唯一编号使用 IMEI
phone 字段如需补足长度，可采用“前导 0 + IMEI”方式
鉴权报文中显式带上 IMEI，便于平台准确映射 device_id

7.2 鉴权扩展信息

建议在 0x0102 后追加 JSON 扩展，用于首包上报终端元信息，避免依赖前端二次拼装，例如：

uuid
iccid
rtm_id
chip
fversion
rssi
summary

建议优先上报：

当前已持久化生效的 uuid
当前已持久化生效的 rtm_id
当前已生效的 gps_interval
当前已生效的 sleep_interval
当前已生效的 keepalive_interval

这样平台可以直接依据终端当前实际配置判断是否还需要继续同步。

7.3 重连机制

终端侧建议实现：

TCP 断开自动重连
服务器重启后的延迟重试
网络恢复后等待 IP_READY 再发起连接
重连成功后重新注册、重新鉴权、重新进入心跳与位置上报流程

7.4 定位策略

建议根据实际定位来源上报 loc_type：

有有效卫星定位时上报 GPS
基站定位中可暂缓位置报文，避免错误状态混入正常轨迹
WiFi 定位时显式标记为 WiFi

7.5 配置持久化建议

对于支持 deviceconfig、rtmconfig 的终端，建议实现以下机制：

收到配置下发后，先解析并校验 JSON
配置写入本地持久化存储
将持久化后的结果同步回当前运行时变量
deviceconfig 成功后立即刷新上报周期
rtmconfig 成功后先回 0x0001 应答，再重启设备
设备重启后，在新的 0x0102 扩展信息中上报最新 uuid、rtm_id

如果设备重启后仍继续上报旧的 uuid、rtm_id，平台会持续判定“配置尚未生效”，从而重复下发相同配置。

八、调试建议

联调时建议重点关注：

0x0100 注册是否成功
0x0102 鉴权码是否匹配
平台是否已按 IMEI 建立 MQTT 设备身份
是否成功发布 info/post
0x0200 是否稳定转换为 property/post
平台下行 function/get 后终端是否收到对应 JT808 指令
平台下行 monitor/get 后终端是否已正确持久化配置
设备重启后的首个 0x0102 扩展信息是否已经变成最新 uuid、rtm_id

8.1 常见问题排查

如果出现“设备每次重启后平台都重复下发 deviceconfig / rtmconfig”，优先检查：

终端是否真的把配置写入本地存储
设备启动后是否已从本地存储重新加载配置
0x0102 鉴权扩展信息里上报的 uuid、rtm_id 是否仍然是旧值
info/post 中的 uuid、rtm_id 是否与平台期待值一致

如果终端已经保存成功，但 0x0102 仍上报旧值，通常不是平台判定问题，而是终端启动后没有把持久化配置同步回运行时变量。

JT808 协议接入 ​

一、总体架构 ​

二、适用场景 ​

三、连接参数 ​

3.1 TCP 接入 ​

3.2 MQTT 桥接认证 ​

四、JT808 上报报文 ​

4.1 注册 0x0100 ​

4.2 鉴权 0x0102 ​

4.3 心跳 0x0002 ​

4.4 位置汇报 0x0200 ​

五、平台 MQTT 主题映射 ​

5.1 设备信息上报 ​

5.2 属性上报 ​

5.3 事件上报 ​

六、平台下行控制与 JT808 映射 ​

6.1 function/get 到 JT808 的映射 ​

6.2 monitor/get 到 JT808 的映射 ​

6.3 deviceconfig 下发示例 ​

6.4 rtmconfig 下发示例 ​

6.5 批量下发示例 ​

6.6 monitor/get_reply 回执结构 ​

七、设备实现建议 ​

7.1 终端手机号与设备号 ​

7.2 鉴权扩展信息 ​

7.3 重连机制 ​

7.4 定位策略 ​

7.5 配置持久化建议 ​

八、调试建议 ​

8.1 常见问题排查 ​

JT808 协议接入

一、总体架构

二、适用场景

三、连接参数

3.1 TCP 接入

3.2 MQTT 桥接认证

四、JT808 上报报文

4.1 注册 `0x0100`

4.2 鉴权 `0x0102`

4.3 心跳 `0x0002`

4.4 位置汇报 `0x0200`

五、平台 MQTT 主题映射

5.1 设备信息上报

5.2 属性上报

5.3 事件上报

六、平台下行控制与 JT808 映射

6.1 `function/get` 到 JT808 的映射

6.2 `monitor/get` 到 JT808 的映射

6.3 `deviceconfig` 下发示例

6.4 `rtmconfig` 下发示例

6.5 批量下发示例

6.6 `monitor/get_reply` 回执结构

七、设备实现建议

7.1 终端手机号与设备号

7.2 鉴权扩展信息

7.3 重连机制

7.4 定位策略

7.5 配置持久化建议

八、调试建议

8.1 常见问题排查