DTU与上位机通信协议
版本 |
时间 |
作者 |
备注 |
V1.0 |
2023-7-10 |
Lcj |
初建 |
V1.1 |
2023-7-11 |
Lcj |
增加综合信息 |
V1.2 |
2023-7-12 |
Lcj |
增加传感器模版 |
V1.3 |
2023-7-13 |
Lcj |
增加网关工作模式设置 |
V1.4 |
2023-8-10 |
Lcj |
修改传感器模版编辑错误 |
V1.5 |
2023-8-30 |
Msd |
增加低功耗睡眠命令 |
V1.6 |
2023-8-30 |
Lcj |
加入测试指令的描述(十五) |
V1.7 |
2023-9-12 |
Zmx |
修改协议格式 |
V1.8 |
2023-9-12 |
Msd |
修改低功耗睡眠命令 |
V2.0 |
2023-9-15 |
Zmx |
规范协议: 1. CTL < 0xA0 2. 设置命令的回复帧数据域长度固定为1 |
V3.0 |
2023-10-21 |
Zmx |
1. 新增透传帧 2. 更改了DTU命令 3. 更改了自动测试命令 |
V3.1 |
2023-11-29 |
Zmx |
1. 透传帧格式:删除字段Address 2. 查询设备信息:新增DTU软件版本字段, 用户ID字段改为4个字节 3. 查询和设置子系统配置:删除用户ID长度字段 4. 查询睡眠唤醒后IO输出配置:增加开关字段 5. 设置睡眠DFE唤醒、同步信号检测唤醒、信号检测唤醒(精简):删除串口唤醒开关字段 6. 设置睡眠信号检测唤醒(精简):串口唤醒开关字段改为设置无效 7. 设置上行测试参数:CTL改为0x31,上行测试周期改为4个字节,单位毫秒 8. 删除查询硬件板类型命令 9. 重置所有参数:改为重置用户静态数据信息 10. 设置发送数据然后睡眠:改为RTC唤醒 11. 新增查询和设置接入设备类型两条命令 12. 新增查询和设置发送控制配置两条命令 13. 新增查询上行测试参数,CTL为0x30 |
V3.1 |
2024-04-11 |
jpwang |
1.增加拉GPIO口命令 |
V3.1 |
2024-04-12 |
wz |
增加 8.1 读tag(国网仓储项目定制需求) |
本文档也适用于DTU与AP或网关通信。
一、协议帧格式
协议帧包括透传帧、命令帧(包括查询帧、设置帧)、回复帧,数据格式采用小端。
1.1 透传帧格式
内容 |
长度 |
描述 |
DATA |
n字节 |
数据域: AP或网关到DTU的长度范围单播0~306,广播0~1020 DTU到AP或网关长度范围0~300 |
注意:长度达到11及以上且前两个字节为0xAA, 0x1的帧会被识别为命令帧和回复帧,不做透传处理。
1.2 命令帧和回复帧格式
内容 |
长度 |
描述 |
0xAA |
1字节 |
帧起始符 |
Version |
1字节 |
固定为1 |
Address |
4字节 |
设备地址(0地址表示广播地址) |
CTL |
1字节 |
控制码,必须小于0xA0 |
LEN |
2字节 |
数据域长度,最长1124 |
DATA |
n字节 |
数据域 |
CHECKSUM |
1字节 |
从0xAA开始到数据域的校验和 |
0xEE |
1字节 |
帧结束符 |
命令帧由上位机发出,回复帧由DTU发出;
所有命令帧的回复帧CTL与命令帧CTL一致;
设置命令的回复帧数据域长度L=1(数据范围0~255),表示设置结果,0为设置成功,其他数值为错误码。
二、DTU命令
2.1 查询设备信息(CTL=0x0)
数据域 |
长度 |
描述 |
硬件版本 |
16字节 |
字符串 |
协议栈版本 |
16字节 |
字符串 |
DTU软件版本 |
16字节 |
字符串 |
无源/有源晶振 |
1字节 |
取值0:无源晶振,1:有源晶振 |
设备ID |
4字节 |
取自设备串号地址(设备唯一标识)的1~4字节并舍弃最高位,在同步AP时设备ID会赋值给用户ID |
用户ID(V3.1版本时改为4个字节) |
4字节 |
接入网关后,网关会分配一个新的用户ID |
最大发射功率 |
1字节 |
范围-18~21dBm |
最大数据速率 |
1字节 |
最大数据发送速率级别,范围 0~7 |
工作状态 |
1字节 |
取值0:未工作,1:同步成功,2:同步失败,3:错误 |
当前工作频点 |
1字节 |
|
RSSI |
1字节 |
信号强度,范围-150~0dBm,负数为补码形式 |
SNR |
1字节 |
信噪比,范围-25~30dB,负数为补码形式 |
当前发射功率 |
1字节 |
范围-18~21dBm |
当前数据速率 |
1字节 |
当前数据发送速率级别,范围0~7 |
2.2 查询子系统配置(CTL=0x1)
数据域 |
长度 |
描述 |
AP发射功率 |
1字节 |
范围0~29dBm |
子系统ID |
4字节 |
当前使用的子系统ID |
用户ID长度(V3.1版本时删除) |
1字节 |
固定为1,代表用户ID长度为4,目前仅支持查询,设置无效 |
默认频点 |
1字节 |
关闭扫频时使用的频点,频谱idx为3时,范围0~200 |
pp |
1字节 |
固定为1,目前仅支持查询,设置无效 |
symbol len |
1字节 |
帧配置,取值0:128,1:256,2:512,3:1024 |
下行上行比 |
1字节 |
帧配置,取值0:1比1,1:1比2 |
bt value |
1字节 |
滤波器带宽,取值0:BT_1.2,1:BT_0.3,BT_1.2的数据速率更高 |
上行group数量 |
1字节 |
帧配置,取值0:1,1:2,2:4,3:8 |
频谱idx |
1字节 |
频谱序列号,默认为3 |
连接态时间 |
4字节 |
连接状态保持的时间,要和AP保持一致,单位:秒 |
心跳时间 |
4字节 |
单位:秒 |
默认发射功率 |
1字节 |
范围-18~22dBm,设置为107为自动功率 |
数据速率模式 |
1字节 |
取值0:正常模式,1:中等模式,2:高级模式 |
数据速率 |
1字节 |
范围0~8(8表示自动速率) |
2.3 设置子系统配置(CTL=0x2)
设置成功后5s内会重启DTU。
数据域 |
长度 |
描述 |
AP发射功率 |
1字节 |
范围为0~29dBm |
子系统ID |
4字节 |
当前使用的子系统ID |
用户ID长度(V3.1版本时删除) |
1字节 |
固定为1,代表用户ID长度为4,目前仅支持查询,设置无效 |
默认频点 |
1字节 |
关闭扫频时使用的频点,频谱idx为3时,范围0~200 |
pp |
1字节 |
固定为1,目前仅支持查询,设置无效 |
symbol len |
1字节 |
帧配置,取值0:128,1:256,2:512,3:1024 |
下行上行比 |
1字节 |
帧配置,取值0:1比1,1:1比2 |
bt value |
1字节 |
滤波器带宽,取值0:BT_1.2,1:BT_0.3,BT_1.2的数据速率更高 |
上行group数量 |
1字节 |
帧配置,取值0:1,1:2,2:4,3:8 |
频谱idx |
1字节 |
频谱序列号,默认为3 |
连接态时间 |
4字节 |
连接态保持时间,需与AP一致,单位:秒 |
心跳时间 |
4字节 |
单位:秒 |
默认发射功率 |
1字节 |
范围-18~21dBm,设置为107为自动功率 |
数据速率模式 |
1字节 |
取值0:正常模式,1:中等模式,2:高级模式 |
数据速率 |
1字节 |
范围0~8(8表示自动速率) |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
2.4 查询扫频配置(CTL=0x3)
数据域 |
长度 |
描述 |
扫频开关 |
1字节 |
取值0:关扫频,1:开扫频,开启扫频则会使用频点列表和子系统ID列表中的各项值去尝试连接AP,若某次连接成功则结束扫频,进入连接状态 |
超时时间 |
2字节 |
单位:秒 |
频点个数 |
1字节 |
每个频点占用1个字节 |
频点列表 |
16字节 |
若频点个数小于16,则以255为结束标志 |
子系统ID个数 |
1字节 |
每个子系统ID占用4个字节 |
子系统ID列表 |
32字节 |
若子系统ID个数小于8,则以0或者0xffffffff为结束标志 |
2.5 设置扫频配置(CTL=0x4)
设置成功后5s内会重启DTU。
数据域 |
长度 |
描述 |
扫频开关 |
1字节 |
取值0:扫描关,1:扫描开 |
超时时间 |
2字节 |
单位:秒 |
频点个数 |
1字节 |
每个频点占用1个字节 |
频点列表 |
16字节 |
可以配置16个频点,若频点个数小于16,则以255为结束标志 |
子系统ID个数 |
1字节 |
每个子系统ID占用4个字节 |
子系统ID列表 |
32字节 |
可以配置8个子系统ID,若子系统ID个数小于8,则以0或者0xffffffff为结束标志 |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
2.6 查询RS485串口配置(CTL=0x5)
数据域 |
长度 |
描述 |
波特率 |
4字节 |
默认值4800 |
校验位 |
1字节 |
取值0:无校验,1:奇校验,2:偶校验,默认值0 |
2.7 设置RS485串口配置(CTL=0x6)
数据域 |
长度 |
描述 |
波特率 |
4字节 |
|
校验位 |
1字节 |
取值0:无校验,1:奇校验,2:偶校验 |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
2.8 查询传感器模版配置(CTL=0x7)
数据域 |
长度 |
描述 |
传感器探测开关 |
1字节 |
取值0:关,1:开 |
传感器探测周期 |
4字节 |
单位:秒 |
传感器命令模版长度 |
1字节 |
范围1~32 |
传感器命令模版 |
32字节 |
模版长度字段指明了其有效字节数 |
2.9 设置传感器模版配置(CTL=0x8)
数据域 |
长度 |
描述 |
传感器探测开关 |
1字节 |
取值0:关,1:开 |
传感器探测周期 |
4字节 |
单位:秒 |
传感器命令模版长度 |
1字节 |
范围1~32 |
传感器命令模版 |
32字节 |
模版长度字段指明了其有效字节数 |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
2.10 查询接入设备类型(CTL=0x9)(V3.1版本时新增)
数据域 |
长度 |
描述 |
设备类型 |
1字节 |
取值0:网关/8路网关,1:AP |
2.11 设置接入设备类型(CTL=0xA)(V3.1版本时新增)
设置成功后5s内会重启DTU。
数据域 |
长度 |
描述 |
设备类型 |
1字节 |
取值0:网关/8路网关,1:AP |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
2.12 查询发送控制配置(CTL=0xB)(V3.1版本时新增)
数据域 |
长度 |
描述 |
重发次数 |
1字节 |
数据发送失败后的重发次数,范围0~4,设置0为不重发 |
分时发送 |
1字节 |
取值0:关,1:开,开启后发送数据将在发送周期内的指定时隙发送 |
发送周期(ms) |
4字节 |
单位:毫秒 |
发完睡眠(DFE唤醒) |
1字节 |
取值0:关,1:开 |
2.13 设置发送控制配置(CTL=0xC)(V3.1版本时新增)
数据域 |
长度 |
描述 |
重发次数 |
1字节 |
数据发送失败后的重发次数,范围0~4,设置0为不重发 |
分时发送 |
1字节 |
取值0:关,1:开,开启后发送数据将在发送周期内的指定时隙发送 |
发送周期(ms) |
4字节 |
单位:毫秒 |
发完睡眠(DFE唤醒) |
1字节 |
取值0:关,1:开 |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
2.14 控制GPIO口输出高低电平(CTL=0x50)(V3.1版本时新增)
数据域 |
长度 |
描述 |
GPIO口 |
1字节 |
要控制的GPIO口,如:2 |
电平 |
1字节 |
0表示拉低,1表示拉高 |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
三、网关命令
3.1 查询网关工作模式(CTL=0x10)
数据域 |
长度 |
描述 |
网关工作模式 |
1字节 |
取值 0:默认工作模式,终端必须接入才能数据透传。建议终端不超过2000个时采用 1:工厂测试模式,用于各个外设硬件通路测试 2:透传模式,不要接入WIOTA同步成功后直接数据透传,终端如果超过2000个,建议采用透传模式。 3:低功耗模式。 |
3.2 设置网关工作模式(CTL=0x11)
设置成功后5s内会重启DTU。
数据域 |
长度 |
描述 |
网关工作模式 |
1字节 |
取值 0:默认工作模式,终端必须接入才能数据透传。建议终端不超过2000个时采用 1:工厂测试模式,用于各个外设硬件通路测试 2:透传模式,不要接入WIOTA同步成功后直接数据透传,终端如果超过2000个,建议采用透传模式 3:低功耗模式 |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
四、低功耗命令
4.1 查询睡眠唤醒后IO输出配置(CTL=0x20)
数据域 |
长度 |
描述 |
输出开关(V3.1版本时新增) |
1字节 |
取值0:关,1:开 |
输出pin脚 |
1字节 |
|
输出高电平保持时间(ms) |
4字节 |
单位:毫秒,取值0:一直输出高电平 |
4.2 设置睡眠唤醒后IO输出配置(CTL=0x21)
数据域 |
长度 |
描述 |
输出开关(V3.1版本时新增) |
1字节 |
取值0:关,1:开 |
输出pin脚 |
1字节 |
|
输出高电平保持时间(ms) |
4字节 |
单位:毫秒,取值0:一直输出高电平 |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
4.3 查询Clock Gating省电(CTL=0x22)
注意:如果设备正处于省电状态,需要先向串口发送任意数据,让程序退出省电,正常运行,才能查询。
数据域 |
长度 |
描述 |
Clock Gating省电开关 |
1字节 |
取值0:关,1:开 |
4.4 设置Clock Gating省电(CTL=0x23)
注意:如果设备正处于省电状态,需要先向串口发送任意数据,让程序退出省电,正常运行,才能设置。
数据域 |
长度 |
描述 |
Clock Gating省电开关 |
1字节 |
取值0:关,1:开 |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
4.5 设置睡眠:RTC唤醒(CTL=0x24)
数据域 |
长度 |
描述 |
串口唤醒开关 |
1字节 |
取值0:关,1:开 |
RTC定时唤醒时间 |
4字节 |
单位:秒,取值0:关闭定时唤醒 |
唤醒后IO输出开关 |
1字节 |
取值0:关,1:开 |
注意:成功进入睡眠则无回复数据。
数据域 |
长度 |
描述 |
执行结果 |
1字节 |
范围0~255,取值0:设置成功,1:参数长度错误,2:睡眠失败 |
4.6 设置睡眠:DFE唤醒(CTL=0x25)
数据域 |
长度 |
描述 |
串口唤醒开关(V3.1版本时删除) |
1字节 |
取值0:关,1:开 |
定时唤醒时间(ms) |
4字节 |
精度比RTC高,单位:毫秒,最小为20ms |
唤醒后IO输出开关 |
1字节 |
取值0:关,1:开 |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
4.7 设置睡眠:同步信号检测唤醒(CTL=0x26)
数据域 |
长度 |
描述 |
检测间隔 |
4字节 |
检测间隔时长=(检测间隔+1)*帧时长,每到检测间隔时长基带会醒来检测一次 |
最大检测次数 |
4字节 |
达到最大检测次数,无论是否检测到有效信号,都会强制唤醒系统。取值0:不检测 |
串口唤醒开关(V3.1版本时删除) |
1字节 |
取值0:关,1:开 |
RTC定时唤醒时间 |
4字节 |
单位:秒,取值0:关闭定时唤醒 |
唤醒后IO输出开关 |
1字节 |
取值0:关,1:开 |
注意:成功进入睡眠则无回复数据。
数据域 |
长度 |
描述 |
执行结果 |
1字节 |
范围0~255,取值0:设置成功,1:参数长度错误,2:睡眠失败 |
4.8 设置睡眠:信号检测唤醒(精简)(CTL=0x27)
数据域 |
长度 |
描述 |
唤醒ID |
2字节 |
根据symbol len不同,最大值不同,当symbol len为0,1,2,3时, 唤醒ID最大值限制分别为41,82,168,339(可等于,最小值为0,实际可能变化,以代码接口为准),可根据接口获取 |
检测周期(ms) |
4字节 |
单位:毫秒,最大值44s |
最大检测次数 |
4字节 |
达到最大检测次数,无论是否检测到有效信号,都会强制唤醒系统。取值0:不检测 |
串口唤醒开关(V3.1版本时删除) |
1字节 |
取值0:关,1:开 |
RTC定时唤醒时间 |
4字节 |
单位:秒,取值0:关闭定时唤醒 |
唤醒后IO输出开关 |
1字节 |
取值0:关,1:开 |
注意:成功进入睡眠则无回复数据。
数据域 |
长度 |
描述 |
执行结果 |
1字节 |
范围0~255,取值0:设置成功,1:参数长度错误,2:睡眠失败 |
4.9 设置睡眠:信号检测唤醒(全)(CTL=0x28)
数据域 |
长度 |
描述 |
频点 |
1字节 |
|
频谱idx |
1字节 |
频谱序列号,默认为3 |
bandwIDth |
1字节 |
滤波器带宽,取值0:BT_1.2,1:BT_0.3,BT_1.2的数据速率更高 |
symbol len |
1字节 |
帧配置,取值0:128,1:256,2:512,3:1024 |
lpm_nlen |
1字节 |
检测头配置,默认值4 |
lpm_utimes |
1字节 |
检测头配置,默认值2 |
检测门限 |
1字节 |
3~15,默认值10,增大该值,漏检率增大,虚警率减小,虚警率即对噪声的敏感程度,漏检率即对唤醒信号的敏感程度 |
继续休眠使能 |
1字节 |
取值0:关,1:开 |
继续休眠时长 |
4字节 |
单位:毫秒,必须大于检测周期+10ms,最大值44s |
唤醒ID |
2字节 |
根据symbol len不同,最大值不同,当symbol len为0,1,2,3时, 唤醒ID最大值限制分别为41,82,168,339(可等于,最小值为0,实际可能变化,以代码接口为准),可根据接口获取 |
检测周期(ms) |
4字节 |
单位:毫秒,最大值44s |
最大检测次数 |
4字节 |
达到最大检测次数,无论是否检测到有效信号,都会强制唤醒系统 |
串口唤醒开关 |
1字节 |
取值0:关,1:开,(V3.1版本时改为默认关闭,设置无效) |
定时唤醒时间 |
4字节 |
RTC定时唤醒时间,单位:秒0为关闭定时唤醒 |
唤醒后IO输出开关 |
1字节 |
取值0:关,1:开 |
注意:成功进入睡眠则无回复数据。
数据域 |
长度 |
描述 |
执行结果 |
1字节 |
范围0~255,取值0:设置成功,1:参数长度错误,2:睡眠失败 |
五、测试命令
5.1 查询上行测试参数(CTL=0x30)
数据域 |
长度 |
描述 |
测试开关 |
1字节 |
取值0:关,1:开 |
重发次数 |
1字节 |
数据发送失败后的重发次数,范围0~4,设置0为不重发 |
分时发送 |
1字节 |
取值0:关,1:开,开启后发送数据将在测试周期内的指定时隙发送 单个终端测试可以关闭,多个终端测试需要打开 |
发完睡眠(DFE唤醒) |
1字节 |
取值0:关,1:开 |
上行测试数据长度 |
2字节 |
范围:1~300 |
上行测试周期(ms) |
4字节 |
单位:毫秒 |
5.2 设置上行测试参数(CTL=0x31)
数据域 |
长度 |
描述 |
测试开关 |
1字节 |
取值0:关,1:开 |
重发次数 |
1字节 |
数据发送失败后的重发次数,范围0~4,设置0为不重发 |
分时发送 |
1字节 |
取值0:关,1:开,开启后发送数据将在测试周期内的指定时隙发送 单个终端测试可以关闭,多个终端测试需要打开 |
发完睡眠(DFE唤醒) |
1字节 |
取值0:关,1:开 |
上行测试数据长度 |
2字节 |
范围:1~300 |
上行测试周期(ms) |
2字节 (V3.1版本改为4字节) |
单位:秒,(V3.1版本改为毫秒) |
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,0为设置成功,其他数值为错误码 |
5.3 查询测试序列ID(CTL=0x32)
5.4 设置测试序列ID(CTL=0x33)
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
5.5 设置发送数据然后睡眠:RTC唤醒(CTL=0x34)
数据域 |
长度 |
描述 |
串口唤醒开关 |
1字节 |
取值0:关,1:开 |
RTC定时唤醒时间 |
4字节 |
单位:秒,取值0:关闭定时唤醒 |
唤醒后IO输出开关 |
1字节 |
取值0:关,1:开 |
发送数据 |
n字节 |
范围1~300,上位机发送此命令给DUT,DUT将发送指定长度的数据到网关,然后按照发送周期时间后醒来 |
注意:成功进入睡眠则无回复数据。
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
六、上报信息
6.1 向上位机上报扫频信息(CTL=0x40)
此帧用于未同步时自动上报扫频信息。
数据域 |
长度 |
描述 |
频点 |
1字节 |
当前扫频使用的频点 |
RSSI |
1字节 |
信号强度,范围-150~0dBm,负数为补码形式 |
SNR |
1字节 |
信噪比,范围-25~30dB,负数为补码形式 |
同步状态 |
1字节 |
取值0:未同步,1:已同步 |
七、恢复设备命令
7.1 重置用户静态数据信息(CTL=0x90)
将用户静态数据信息重置为程序内预设的默认参数。
设置成功后5s内会重启DTU。
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
7.2 重启设备(CTL=0x91)
数据域 |
长度 |
描述 |
设置结果 |
1字节 |
范围0~255,取值0:设置成功,其他数值为错误码 |
八、项目定制
8.1 读标签数据(CTL=0xc0)(此命令仅仅是国网仓储项目支持此命令)
通过I2c读tag数据。V3.1以后的版本支持此命令。
设置成功后5s内会重启DTU。
数据域 |
长度 |
描述 |
地址 |
2 |
读取tag的地址。长度2字节 |
读取长度 |
1 |
读取长度范围 0 ~ 32 字节 |