# chirplan-node

**Repository Path**: experienceop/chirplan-node

## Basic Information

- **Project Name**: chirplan-node
- **Description**: ChirpLAN终端模块、USB Dongle源码
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 8
- **Created**: 2023-04-09
- **Last Updated**: 2023-04-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChirpLAN终端模块

ChirpLAN模块定位为一个支持网络和点对点协议的低频半双工Chirp模块，内置功能完整的 AT 指令,   使用串口进行数据收发，降低了无线应用的门槛，可实现一对一或一对多的通信应用场景。

ChirpLAN USBDongle模块在终端模块的基础上，增加了终端定时自动上报温度功能，增加了网关下发控制RGB三色灯的功能。

代码支持三种模块，分别是黑色NODE终端模组，绿色NODE终端模组，USBDongle演示模块。通过代码中hardware.h文件头部的宏定义控制。切换不同的宏定义可以应用到不同的模块上。

## 一、开发环境

- 开发环境编译器：Keil5
- pack包：HC32L136.1.0.0.pack
- Device：HC32L136J8TA
- Flash：HC32L136_64K

## 二、模块引脚说明

![image-20220903162925295](pic/image-20220903162925295.png)

<center>ChirpLAN网络模块引脚示意图</center>



| 引脚名称 | IO 类型 | 引脚描述                                                     |
| -------- | ------- | ------------------------------------------------------------ |
| VCC      | 电源    | 供电引脚                                                     |
| GND      | 电源    | 参考地                                                       |
| ANT      | 模拟    | 射频信号输入/输出端口, ANT 端口预留匹配电路, <br />走线使用 50 Ω 阻抗匹配， 铺地并在周围加过孔 |
| AUX      | 输出    | **模块状态指示引脚：**<br />0: 模块可以接收串口数据<br />1: 模块不可以接收串口数据 |
| UART-RX  | 输入    | TTL 串口接收引脚                                             |
| UART-TX  | 输出    | TTL 串口发送引脚                                             |
| SETA     | 输入    | AT 与透传切换, 内部上拉, <br />0: P2P传输模式 <br />1: AT 指令模式 |
| SETB     | 输入    | 控制模块休眠, 内部上拉 <br />0: 休眠(或无线电唤醒) <br />1: 唤醒 |

**注意：** 如果 SETA, SETB悬空，模块进入AT指令模式，这种机制是为了方便用户进行AT指令测试。

## 三、使用说明

终端支持多种工作模式，包括AT指令模式，点对点透传模式，组网透传模式。

ChirpLAN USBDongle模块不支持低功耗功能，模块在组网透传模式下，支持网关下发控制RGB三色灯的功能，在MODE-C模式下，模块具有定时自动上报温度功能。

### 3.1AT指令模式

该模式下只支持AT指令配置，对于无效信息会返回错误。

进入AT指令模式有两种方式：

1、通过上位机工具配置进入和退出。

2、通过配置SETA=1、SETB=1进入AT模式， 通过配置SETA=0、SETB=1退出AT模式。

退出AT指令模式后（或上电即为非AT指令时），模块会根据AT配置的协议模式，自动进入点对点透传工作模式或组网透传工作模式。

### 3.2点对点透传模式

该模式分为透明传输模式和定点传输模式，子模式的选择需要通过AT指令配置。

通过设置SETA选择进入AT指令模式或工作模式，通过设置SETB选择进入低功耗模式或非低功耗模式。

典型配置方式：

1、令SETA=1、SETB=1，再通过上位机工具配置工作模式，例如配置为点对点协议、透明传输，设置相应射频参数。

2、通过上位机工具配置退出配置状态，此时模组自动进入点对点透明传输工作状态。

3、通过串口发送任意数据，模组即可将数据透传发射出去。如果模组接收到数据，会通过串口显示出来。

4、如果想进入低功耗模式，可以令SETA=0、SETB=0，模组即可进入低功耗模式。需要再次发送时，需要令SETB=1，再通过串口发送数据。

注意，点对点定点传输模式下，需要将本模块发送数据的前 2 字节设置为目标模组的地址0和地址1， 发送时本模块改变目标地址和 信道， 发送后恢复原有设置。例如目标模块的射频地址0和射频地址1均设置为100，本模块想发送16进制数12 34 56，那么本模块发送的数据应为（16进制）64 64 12 34 56，目标模块会显示接收结果为12 34 56。详细说明及操作可以参考https://docs.panchip.com/chirplan-doc/latest/03_chirp_end_info/ChirpLAN_end_p2p_mode_info.html#id1

### 3.3组网透传模式

该模式分为MODEA、MODEB、MODEC模式，子模式的选择需要通过AT指令配置。

通过设置SETA选择进入AT指令模式或工作模式，通过设置SETB选择进入低功耗模式或非低功耗模式。

典型配置方式：

1、令SETA=1、SETB=1，再通过上位机工具配置工作模式，例如配置为网络协议、主动上报模式，设置相应射频参数。

2、通过上位机工具配置退出配置状态，此时模组自动进入网络模式工作状态，并开始发起入网。

3、通过串口发送任意数据，模组即可将数据透传发射出去。如果模组接收到数据，会通过串口显示出来。

4、如果想进入低功耗模式，可以令SETA=0、SETB=0，模组即可进入低功耗模式。需要再次发送时，需要令SETB=1，此时模组会再次发起入网，入网成功后，可再通过串口发送数据。

### 3.4IO切换及使用方法

模组引脚说明如下。

| 引脚名称 | IO 类型 | 引脚描述                                                     |
| -------- | ------- | ------------------------------------------------------------ |
| VCC      | 电源    | 供电引脚                                                     |
| GND      | 电源    | 参考地                                                       |
| ANT      | 模拟    | 射频信号输入/输出端口, ANT 端口预留匹配电路, 走线使用 50 Ω 阻抗匹配， 铺地并在周围加过孔 |
| AUX      | 输出    | **模块状态指示引脚：** 0: 模块可以接收串口数据 1: 模块不可以接收串口数据 |
| UART-RX  | 输入    | TTL 串口接收引脚                                             |
| UART-TX  | 输出    | TTL 串口发送引脚                                             |
| SETA     | 输入    | AT 与工作模式切换, 内部上拉, 0:工作模式 1: AT 指令模式       |
| SETB     | 输入    | 控制模块休眠, 内部上拉 0: 休眠(或无线电唤醒) 1: 唤醒         |

AUX引脚用于向用户指示模块状态。高电平时表示模组忙，此时不可接收新的串口数据；低电平时表示模组空闲。

SETA和SETB用于用户控制模组状态，IO悬空时默认为高电平。用户需要通过控制SETA和SETB的状态来控制模组工作。其中，SETA控制AT 指令模式和工作模式，SETB控制模块休眠。

当SETA拉高时，模块会进入AT指令模式，此模式下，可以对模块进行AT指令配置。

当SETA拉低时，模块会根据AT指令配置的工作模式（AT+WMODE）选择进入透传模式还是组网模式。

当SETB拉高时，模块会进入唤醒模式，不休眠。

当SETB拉低时，模块会进入休眠模式。

集中典型的工作模式如下：

| SETA | SETB | 模块状态                                                     |
| ---- | ---- | ------------------------------------------------------------ |
| 悬空 | 悬空 | 上电前，将SETA和SETB悬空，上电后，模块会进入AT指令模式，MCU不休眠，工作电流大约4-5mA。 |
| 高   | 高   | 模块会进入AT指令模式，MCU不休眠。                            |
| 高   | 低   | 模块会进入AT指令模式，MCU不休眠。                            |
| 低   | 高   | 若当前AT软件配置为透传模式，模块会进入透传模式，未发射时一直处于接收状态，当有串口数据时会发送数据。若当前AT软件配置为组网模式，则模块会先发起入网，入网成功后，再根据配置的MODE A/B/C选择不同的工作方式。其中，A模式会保持5mA左右的工作电流，当有串口数据时会发送数据；B模式会维持5mA左右的工作电流，同时自动进行周期性接收，当有串口数据时会发送数据；C模式会维持大约22mA左右的工作电流，模块一直处于接收状态，当有串口数据时会发送数据。 |
| 低   | 低   | 若当前AT软件配置为透传模式，则模块会根据配置的唤醒周期，在休眠的基础上自动进行周期性接收。若当前AT软件配置为组网模式，则模块会先发起入网，入网成功后，再根据配置的MODE A/B/C选择不同的工作方式。A/C模式会进入休眠，B模式会在休眠的基础上自动进行周期性接收。在此模式下，A/B/C均不能通过串口发送数据，如果需要发送，需先将SETB拉高，退出休眠模式后，才可以通过串口发送数据。 |

上位机工具还支持通过串口指令进入AT指令模式，具体操作为：在非休眠模式下（将SETB拉高），通过上位机工具“进入配置模式”按钮进入，此时不论SETA是什么状态，都可以进入AT指令模式。

上位机工具“进入配置模式”按钮的内部逻辑为：串口先向模块发送+++，模块回复a，串口再发送a，模块回复OK，即表示进入AT指令模式成功。

更多详细模块介绍请访问https://docs.panchip.com/chirplan-doc/latest/03_chirp_end_info/ChirpLAN_end_info.html#

## 四、代码结构

![](pic/image-20221109143014.png)



### 4.1应用层

应用层为进程提供服务，也可以向用户提供数据。它的数据功能我们在网络层为用户预留了接口。用户可以根据自己的需求对应用层进行规定和扩展。

### 4.2网络层

网络层负责对链路层的接口和参数初始化，并负责整个协议的运行、IO事件管理、低功耗管理等。

网络层可以根据需要，注册发送事件（选配）、接收事件（必须配置）、入网事件（选配）、参数事件（必须配置）。注册事件后，链路层就可以通过回调函数接口通知网络层。

网络层提供通过串口向网关发送数据的接口。

### 4.3链路层

链路层负责实现收发逻辑，提供重传、碰撞检测等功能。

链路层为上层提供接口，使用这些接口，上层可以完成对射频的相关操作，而不用关注这些操作是如何实现的。

chirp_function是链路层接口的集合，链路层接口包括：

#### 4.3.1初始化接口

```
chirplan_status_t	 ( *MacInit )(chirp_t *config, chirp_config_callback config_cb);
```

 * config：参数结构体，包含所有希望链路层初始化的参数。
 * config_cb：网关配置参数的回调函数。当网关有配置更新时，链路层会通过此回调函数将新的配置通知上层，此参数不可为NULL。 

初始化之后，才可进行入网操作。

#### 4.3.2唤醒接口

```
chirplan_status_t    ( *Wakeup )(void);
```

唤醒接口，与休眠接口搭配使用。

#### 4.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。

#### 4.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模式的休眠时间，单位：秒。

#### 4.3.5设置射频速率参数接口

```
chirplan_status_t    ( *SetRate )( uint8_t sf, uint8_t bandwidth, uint8_t coderate);
```

 * sf：扩频因子，取值范围：7~12。值越小传输速率越高。
 * bandwidth：信道带宽，取值范围：6~9。值越大传输速率越高。
 * coderate：编码率，取值范围：1~4。值越大，单次传输的冗余数据越多，有效数据速率越低，传输时间越长，但通信成功率越好。

#### 4.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。

#### 4.3.7入网接口

```
chirplan_status_t    ( *Join )(chirp_join_callback join_cb);
```

 * join_cb：入网回调函数。当入网结束时，链路层会通过此回调函数通知上层入网结果事件（上层可在事件中查询结果，结果即ChirpLAN的入网状态）。不需要入网回调函数时，此参数可以配置为NULL。

#### 4.3.8注册接收回调函数接口

```
chirplan_status_t    ( *Recv )(chirp_recv_callback recv_cb);
```

 * recv_cb：接收回调函数。当有接收结果时，链路层会通过此回调函数通知上层接收事件（上层可在事件中查询接收结果，结果可以通过chirp_config.app_data.RxBuffSize便捷查看，当有数据时，RxBuffSize不为0）。此参数不可为NULL，建议在初始化后，配置此接口。

#### 4.3.9休眠接口

```
 chirplan_status_t    ( *Sleep )( void );
```

配置链路层进入低功耗休眠状态，休眠后，链路层不再工作。

再次唤醒需要使用唤醒接口或初始化接口。

#### 4.3.10休眠重置接口

```
chirplan_status_t    ( *StatusReset )( void );
```

在休眠接口的基础上，重置链路层的所有状态，相当于关闭整个链路层。

再次唤醒只可以使用初始化接口，并需要重新入网。

#### 4.3.11空中唤醒模式接收接口

```
chirplan_status_t    ( *ClassBRx )( void );
```

在空中唤醒模式下，需要接收时调用。链路层会通过回调函数返回接收结果。

#### 4.3.12射频中断处理接口

```
void ( *IrqProcess )( void );
```

在链路层使用，用来处理射频中断事件。除特殊应用，此接口一般不需要上层使用。

### 4.4驱动层

驱动层为PAN3028驱动程序，是射频芯片的底层操作。

## 五、在线调试和固件升级

### 5.1在线调试

编译器默认设置的优化等级为Level 3，如果需要使用J-Link在线调试，需要修改优化等级设置。

![image-20221110093409755](pic/image-20221110093409755.png)

代码中各个文件都有串口LOG信息接口，如果需要使用，只需要对相关接口进行定义。

#### 5.1.1AT指令LOG

文件：at_log.h

定义：//#define AT_DEBUG

#### 5.1.2网络层LOG

文件：server_net.h

定义：//#define NET_DEBUG

文件：ddl.h

定义：//#define _PC_DEBUG_

#### 5.1.3链路层LOG

文件：ddl.h

定义：//#define _CHIRPLAN_LOG_DEBUG_

文件：chirplan.h

定义：//#define _CHIRPLAN_DEBUG_LEVEL_LOW_
定义：//#define _CHIRPLAN_DEBUG_LEVEL_HIGH_

调试时可以根据需要，打开LOG信息接口，不建议一次打开过多的LOG信息接口，否则容易出现FLASH空间不足、上位机工具堵塞等问题。

### 5.2固件升级

#### 5.2.1 固件升级说明

![image-20221110103203316](pic/image-20221110103203316.png)

0x0000~0x1000是boot.bin区

0x1000~0xFA00是app.bin区

0xFA00~0xFE00是参数存储区

0xFE00~0xFFFF是标志位区

#### 5.2.2 固件升级使用

##### 5.2.2.1 配置项

使用固件升级时，需要进行如下两项配置

![image-20221110103554778](pic/image-20221110103554778.png)

startup_hc32l13x.s文件中，配置中断向量偏移长度

new_vect_table  EQU     0x00001000 ;

##### 5.2.2.2 配置步骤

初次烧录

1、使用专用工具生成boot.bin+app.bin

2、擦除芯片

3、烧录合成的bin文件

再次升级固件

1、打开ChirpLAN上位机工具（ChirpLanTool.exe），选择正确的COM口，点击打开串口-进入配置状态-固件升级

2、浏览导入需要升级的app.bin（不需要使用boot.bin+app.bin）文件

3、点击开始升级

4、等待绿色进度条正常进行到100%即可

#### 5.2.3 不使用固件升级

##### 5.2.3.1 配置项

不使用固件升级时，需要进行如下两项配置

![image-20221110103855562](pic/image-20221110103855562.png)

startup_hc32l13x.s文件中，配置中断向量偏移长度

new_vect_table  EQU     0x00000000 ;

##### 5.2.3.2 配置步骤

1、擦除芯片

2、直接烧录bin文件

## 六、CAD信道检测与重传

​		PAN3028芯片支持CAD-IRQ中断，开启CAD功能并进入Rx模式后，PAN3028会检测信道中是否存在ChirpIOT™信号，如果存在则将CAD-IRQ置高，外部MCU可以通过在一定时间内检测CAD-IRQ信号是否拉高来判断信道中是否存在ChirpIOT™信号。

### 6.1CAD信道检测接口

```
uint32_t check_cad_rx_inactive(void)
```

接收CAD信道检测函数，适用于空中唤醒模式下，在准备接收时，使用此接口来判断空中是否有信号存在。如果信道忙，则继续进行接收，反之，则进入休眠。

 * 返回值LEVEL_INACTIVE表示信道空闲
 * 返回值LEVEL_ACTIVE表示信道忙

```
void check_cad_tx_inactive(void)
```

发射CAD信道检测函数，适用于在发射前，使用此接口来检测空中是否有干扰信号存在。如果有，则需要进行退避，再选择时间发射，反之，如果空中没有干扰，则可以立即发射。

 * chirplan_proc.cad_tx_timeout_flag为MAC_EVT_TX_CAD_TIMEOUT表示信道空闲
 * chirplan_proc.cad_tx_timeout_flag为MAC_EVT_TX_CAD_ACTIVE表示信道忙

### 6.2入网帧退避及重传

入网帧的退避时间与chirplan_proc.cad_tx_join_time，chirplan_proc.cad_tx_try_times和一个随机数R相关。

首次入网时，chirplan_proc.cad_tx_join_time = 10，chirplan_proc.cad_tx_try_times = 1，先按如下方式延时后，再发起首次入网：

```
chirplan_proc.cad_tx_join_time*chirplan_proc.cad_tx_try_times*(Trng_GetData0() % 100 + 1), 
```

如果发生CAD  TX退避，chirplan_proc.cad_tx_join_time不变，chirplan_proc.cad_tx_try_times每次加1，延时后继续发起入网。如果连续退避次数大于SEND_MSG_CAD_RETRY_TIME，则会直接结束本次入网请求，认为入网失败。当顺利发射后，chirplan_proc.cad_tx_try_times会被重新置为1。

如果入网回复帧接收错误，则会检查chirplan_proc.send_msg_try_times，初始值为0，每次失败后计数会加1，如果失败次数大于SEND_MSG_RETRY_TIME，则会直接结束本次入网请求，认为入网失败。在重传时，chirplan_proc.cad_tx_join_time每次加10，延时后继续发起入网。

### 6.3数据帧退避及重传

数据帧的退避时间与chirplan_proc.cad_tx_try_times和一个随机数R相关。chirplan_proc.cad_tx_join_time固定为1。

首次发射时，不需要延时，直接进行CAD TX检测及发射。

如果发生CAD  TX退避，chirplan_proc.cad_tx_try_times初始值为1，每次退避后计数会加1，延时后继续尝试发射。如果连续退避次数大于SEND_MSG_CAD_RETRY_TIME，则会直接结束本次发射请求，认为发射失败。

如果数据回复帧接收错误，则会检查chirplan_proc.send_msg_try_times，初始值为0，每次失败后计数会加1，如果失败次数大于SEND_MSG_RETRY_TIME，则会直接结束本次发射请求，认为发射失败。

值得注意的一种情况是，假设终端发射上行帧A后，终端接收到CONFIRM类型的下行帧B，终端需要再次发射ACK回复帧C，此时，对于数据帧C，chirplan_proc.send_msg_try_times会重新从0开始计数，不与数据帧A的计数叠加。

![image-20230106135435915](pic/image-20230106135435915.png)

## 七、控制帧格式

其它模组帧类型，请访问https://docs.panchip.com/chirplan-doc/latest/06_chirp_end_dev/ChirpLAN_end_dev.html

### 3.1数据上行帧

数据上行帧是由终端发出的数据帧，包含主动上报数据，ACK回复数据等细分类型。

<center>数据上行帧</center>

| 帧类型（含加密位）    | 帧序号 | 应用ID | 网络ID | 数据内容长度 | 数据内容/ACK | 校验  |
| --------------------- | ------ | ------ | ------ | ------------ | ------------ | ----- |
| 1字节（bit7为加密位） | 1字节  | 1字节  | 4字节  | 1字节        | >=0字节      | 2字节 |

### 3.2数据下行帧

数据下行帧是由网关发出的数据帧，包含主动下发数据，ACK回复数据等细分类型。

<center>数据下行帧</center>

| 帧类型（含加密位）    | 帧序号 | 应用ID | 网络ID | 数据内容长度 | 数据内容/ACK | 校验  |
| --------------------- | ------ | ------ | ------ | ------------ | ------------ | ----- |
| 1字节（bit7为加密位） | 1字节  | 1字节  | 4字节  | 1字节        | >=0字节      | 2字节 |

### 3.3USBDongle三色灯控制帧

在上述数据上行帧和数据下行帧的基础上，发送特定的数据内容作为三色灯控制命令：

上行帧：定时上报终端温度，数据内容为：

| 头部 | 温度值（整数部分）  | 温度值（小数部分）  | 当前RGB状态（红灯）                    | 当前RGB状态（绿灯）                    |
| ---- | ------------------- | ------------------- | -------------------------------------- | -------------------------------------- |
| 0XAA | 十六进制数（1字节） | 十六进制数（1字节） | 十六进制数（1字节，0XFF为最亮，0为灭） | 十六进制数（1字节，0XFF为最亮，0为灭） |

下行帧：控制RGB灯的状态，数据内容为：

| 头部 | 设置RGB状态（红灯）                    | 设置RGB状态（绿灯）                    | 温度上报间隔                             |
| ---- | -------------------------------------- | -------------------------------------- | ---------------------------------------- |
| 0xBB | 十六进制数（1字节，0XFF为最亮，0为灭） | 十六进制数（1字节，0XFF为最亮，0为灭） | 十六进制数（1字节，0为不修改，单位：秒） |

## 八、注意事项

​		模组发射功耗较高，如果无法入网成功（例如参数配置不当或不存在网关），模组会持续入网，此时注意模组发热情况，避免模组由于过热而损坏。

​		模组使用HC32L130F8UA作为主控MCU，支持64K字节FLASH，8K字节RAM。二次开发时，请注意FLASH剩余大小。

​