1. 产品概述¶
ChirpLAN模块定位为一个支持网络和点对点协议的低频半双工Chirp模块，内置功能完整的 AT 指令, 使用串口进行数据收发，降低了无线应用的门槛，可实现一对一或一对多的通信应用场景。本说明书主要介绍ChirpLAN终端模块协议开发说明。
2. Chirplan协议接口¶
2.1用户层¶
用户层为进程提供服务，也可以向用户提供数据，SDK中未对此层做明确的划分和规定。它的数据功能我们在网络层为用户预留了接口。用户可以根据自己的需求对SDK用户层进行规定和扩展。
2.2网络层¶
网络层负责对链路层的接口和参数初始化，并负责整个协议的运行、IO事件管理、低功耗管理等。
网络层可以根据需要，注册发送事件（选配）、接收事件（必须配置）、入网事件（选配）、参数事件（必须配置）。注册事件后，链路层就可以通过回调函数接口通知网络层。
网络层提供通过串口向网关发送数据的接口。
2.3链路层¶
链路层负责实现收发逻辑，提供重传、碰撞检测等功能。
链路层为上层提供接口，使用这些接口，上层可以完成对射频的相关操作，而不用关注这些操作是如何实现的。
chirp_function是链路层接口的集合，链路层接口包括：
2.3.1初始化接口¶
chirplan_status_t ( *MacInit )(chirp_t *config, chirp_config_callback config_cb);
config：参数结构体，包含所有希望链路层初始化的参数。
config_cb：网关配置参数的回调函数。当网关有配置更新时，链路层会通过此回调函数将新的配置通知上层，此参数不可为NULL。
初始化之后，才可进行入网操作。
2.3.3链路层状态获取接口¶
获取状态接口可以帮助上层了解链路层此时的工作情况，上层可以根据需要选择查询，共有四种查询接口。
chirplan_state_t ( *GetStatus )( void );
获取ChirpLAN工作状态。包含CHIRP_STATE_IDLE，CHIRP_STATE_UPLINK，CHIRP_STATE_DOWNLINK，CHIRP_STATE_RF_ERR。
chirplan_send_status_t ( *GetSendStatus )( void );
获取ChirpLAN发送状态。包含CHIRP_SEND_IDLE，CHIRP_SEND_ING，CHIRP_SEND_OK，CHIRP_SEND_ERR。
chirplan_recv_status_t ( *GetRecvStatus )( void );
获取ChirpLAN接收状态。包含CHIRP_RECV_IDLE，CHIRP_RECV_ING，CHIRP_RECV_OK，CHIRP_RECV_ERR。
chirplan_join_status_t ( *GetJoinStatus )( void );
获取ChirpLAN入网状态。包含CHIRP_RESET，CHIRP_SET。
2.3.4设置射频工作参数接口¶
chirplan_status_t ( *SetRfConfig )( uint8_t txpower, uint8_t ldr,
uint8_t crcOn, uint16_t preambletime, uint16_t rxtimeouttime, uint16_t rxsleeptime);
txpower：发射功率，取值范围：0~29。
ldr：低速率模式开关，0：关闭，1：打开。
crcOn：CRC校验开关，0：关闭，1：打开。
preambletime：前导码时间，此设置仅对A/C模式有效，单位：毫秒。
rxtimeouttime：超时接收窗口时间，A模式下有效，单位：毫秒。
rxsleeptime：网关会下发这个参数，表示B模式的休眠时间，单位：秒。
2.3.5设置射频速率参数接口¶
chirplan_status_t ( *SetRate )( uint8_t sf, uint8_t bandwidth, uint8_t coderate);
sf：扩频因子，取值范围：7~12。值越小传输速率越高。
bandwidth：信道带宽，取值范围：6~9。值越大传输速率越高。
coderate：编码率，取值范围：1~4。值越大，单次传输的冗余数据越多，有效数据速率越低，传输时间越长，但通信成功率越好。
2.3.6数据发送接口¶
chirplan_status_t ( *Send )(chirp_app_data_t * app_data, chirp_confirm_t confirmed, chirp_send_callback send_cb);
app_data：本次要发送的数据。最大数据长度支持233字节。
confirmed：本次发送数据是否要求网关回复应答。
send_cb：发送回调函数。当发送结束时，链路层会通过此回调函数通知上层发送结果事件（上层可在事件中查询结果，结果即ChirpLAN的发送状态，CHIRP_SEND_OK或CHIRP_SEND_ERR）。不需要发送回调函数时，此参数可以配置为NULL。
2.3.7入网接口¶
chirplan_status_t ( *Join )(chirp_join_callback join_cb);
join_cb：入网回调函数。当入网结束时，链路层会通过此回调函数通知上层入网结果事件（上层可在事件中查询结果，结果即ChirpLAN的入网状态）。不需要入网回调函数时，此参数可以配置为NULL。
2.3.8注册接收回调函数接口¶
chirplan_status_t ( *Recv )(chirp_recv_callback recv_cb);
recv_cb：接收回调函数。当有接收结果时，链路层会通过此回调函数通知上层接收事件（上层可在事件中查询接收结果，结果可以通过chirp_config.app_data.RxBuffSize便捷查看，当有数据时，RxBuffSize不为0）。此参数不可为NULL，建议在初始化后，配置此接口。
2.3.10休眠重置接口¶
chirplan_status_t ( *StatusReset )( void );
在休眠接口的基础上，重置链路层的所有状态，相当于关闭整个链路层。
再次唤醒只可以使用初始化接口，并需要重新入网。
2.4物理层¶
物理层为PAN3028驱动程序，是射频芯片的底层操作。
3. 链路层帧格式¶
所有的上下行消息都会在链路层进行封装，形成MAC帧。
MAC帧包含入网请求帧， 入网回复帧，数据上行帧，数据下行帧，配置下行帧。
3.1入网请求帧¶
入网请求帧是在终端入网时，由终端向网关发送的上行帧。
帧类型（含加密位） |
帧序号 |
应用ID |
节点ID |
通信模式 |
校验 |
|---|---|---|---|---|---|
1字节（bit7为加密位） |
1字节 |
1字节 |
4字节 |
1字节，取值1-3 |
2字节 |
3.2入网回复帧¶
入网请求帧是在网关收到终端的入网请求帧时，回复终端请求结果的下行帧。
帧类型（含加密位） |
帧序号 |
应用ID |
网络ID |
目标节点ID |
上行参数 |
终端唤醒间隔 |
通信模式 |
校验 |
|---|---|---|---|---|---|---|---|---|
1字节（bit7为加密位） |
1字节 |
1字节 |
4字节（由网关分配） |
4字节 |
9字节，缺省值用0代替（依次为3个上行信道（3字节），3个下行信道（3字节），BW（1字节），SF（1字节），LDR和CR（共用1字节，LDR使用bit7-bit4，CR使用bit3-bit0），本字节值为0时代表LDR和CR都缺省）。上行信道取值0-7，下行信道取值8-15，BW取值6-9，SF取值7-12，CR取值1-4，LDR取值0-1。 |
2字节（单位秒，空中唤醒时有效），取值范围1-30秒 |
为1字节，取值0-3，缺省值0 |
2字节 |
3.3数据上行帧¶
数据上行帧是由终端发出的数据帧，包含主动上报数据，ACK回复数据等细分类型。
帧类型（含加密位） |
帧序号 |
应用ID |
网络ID |
数据内容长度 |
数据内容/ACK |
校验 |
|---|---|---|---|---|---|---|
1字节（bit7为加密位） |
1字节 |
1字节 |
4字节 |
1字节 |
>=0字节 |
2字节 |
3.4数据下行帧¶
数据下行帧是由网关发出的数据帧，包含主动下发数据，ACK回复数据等细分类型。
帧类型（含加密位） |
帧序号 |
应用ID |
网络ID |
数据内容长度 |
数据内容/ACK |
校验 |
|---|---|---|---|---|---|---|
1字节（bit7为加密位） |
1字节 |
1字节 |
4字节 |
1字节 |
>=0字节 |
2字节 |
3.5配置下行帧¶
配置下行帧是由网关发出的参数配置帧，目前SDK暂不支持入网后下发配置下行帧。
帧类型（含加密位） |
帧序号 |
应用ID |
网络ID |
数据内容长度 |
配置内容 |
校验 |
|---|---|---|---|---|---|---|
1字节（bit7为加密位） |
1字节 |
1字节 |
4字节 |
1字节 |
>=0字节 |
2字节 |
3.6各字段含义¶
3.6.1帧类型¶
链路层定义了7种帧类型。帧类型最高位bit7为加密位，加密位用来指示本帧是否经过算法加密，高电平有效，加密表示本帧所有数据都经过算法加密（帧类型字段本身不会被加密）。bit0~6位代表不同的帧类型。
入网请求，7’b0000001
入网回复，7’b0000010
不需要确认上行数据包Unconfirmed Uplink Data，7’b0000011
需要确认上行数据包Confirmed Uplink Data，7’b0000100
不需要确认下行数据包Unconfirmed Downlink Data，7’b0000101
需要确认下行数据包Confirmed Downlink Data，7’b0000110
需要确认下行配置Confirmed Downlink Config，7’b0000111
3.6.2节点ID¶
终端节点设备的本地ID。
3.6.3应用ID¶
网络号，用于区分不同的子网络，网关只接受与自己应用ID相同的节点的入网请求。
3.6.4通信模式¶
取值范围：0~3。1：主动上报模式，2：空中唤醒模式，3：全速运行模式，0：默认值缺省值，表示服务器不修改终端通信模式。
3.6.5校验¶
软件校验位。
3.6.6数据内容长度¶
指示本帧的数据内容长度。
3.6.7节点网络ID¶
节点入网后，由网关或服务器分配的网络地址ID，组网后的通信地址均使用网络ID。
3.6.8上行参数¶
9字节，缺省值用0代替（依次为3个上行信道（3字节），3个下行信道（3字节），BW（1字节），SF（1字节），LDR和CR（共用1字节，LDR使用bit7-bit4，CR使用bit3-bit0），本字节值为0时代表LDR和CR都缺省）。上行信道取值0-7，下行信道取值8-15，BW取值6-9，SF取值7-12，CR取值1-4，LDR取值0-1。
3.6.8终端唤醒间隔¶
空中唤醒模式下，节点的周期性上报时间间隔，单位：秒，取值范围1-30秒。
3.6.9帧序号¶
指示本帧的序号，用0-255循环累计计数表示，上行帧和下行帧独立计数。ACK帧的帧序号与请求帧的帧序号相同。
4通信与加密¶
ChirpLAN协议使用软件AES128算法加密，支持用户自定义一个16字节的密钥，对数据帧进行加密，保障通信的安全性。
ChirpLAN协议物理层PAN3028支持配置CRC校验和CR编码率，增加通信的可靠性。
ChirpLAN协议在通信前需要先入网，终端不入网的情况下，不能与网关通信。终端入网流程图如下：
入网后，终端支持三种工作模式。
4.2空中唤醒模式¶
空中唤醒模式仅支持单向通信，终端具有极低的功耗，网关在终端入网时规定终端的休眠周期，终端会定期自唤醒和接收，如果未发现Chirp信号，则会继续休眠；如果发现Chirp信号，则会接收一包完整的数据。
