forest-rain fa5959f7d3 optimize doxyfile		3 سال پیش
..
doxygen_image	a28d6f7813 feature,doxygen,add doxyfile for api	4 سال پیش
pics	7f3efc0342 update pic	5 سال پیش
README.md	a28d6f7813 feature,doxygen,add doxyfile for api	4 سال پیش
lora-radio-driver_Doxyfile	fa5959f7d3 optimize doxyfile	3 سال پیش

LoRa-Radio-Driver软件包使用说明

1 简介

LoRa-Radio-Driver软件包是基于RTOS( RT-Thread ) 实现的LoRa Tranceiver芯片(SX126x、SX127x等)的驱动文件，该驱动文件通过SPI访问LoRa Tranceiver芯片，可用于快速搭建基于LoRa等通信的应用产品。 LoRa-Radio-Driver软件包在LoRaWAN开源协议栈LoRaMAC-Node中的radio基础上，进一步封装实现。

LoRaMac\Radio https://github.com/Lora-net/LoRaMac-node/tree/master/src/radio

主要特点:
- 当前支持LoRa Transceiver（sx126x\sx127x ）
  - 支持调制方式
    - LoRa
    - FSK
- 可通过EVN工具menuconfig直接定义LoRa模块的对外接口，降低入门门槛
  - 支持使用引脚号来定义GPIO
  - 支持使用引脚名来定义GPIO
- 提供常用实例代码，可用于射频性能测试、空口数据包监听、双向通信测试等
- 可作为phy层对接到LoRaWAN End-Device协议栈
- 当前测试的LoRa 模块\芯片
  - LoRa Transceiver (SPI)
    - SX126X (SX1262\ASR6500S\LLCC68\SX1268..)
    - SX1268
      - LSD4RF-2R717N40
    - SX1262
      - ASR6500S
    - LLCC68
    - LR1110
    - SX127X (SX1272\SX1276\SX1278..)
    - SX1278
      - LSD4RF-2F717N20
      - Ra-01
    - SX1276
  - LoRa SIP\SoC
- 当前测试的MCU平台
  - LoRa Radio Driver当前功能主要在STM32L平台测试通过，未来计划将适配更多的MCU平台（华大MCU、nRF、BK）
    - STM32L0系列
    - STM32L4系列
- 当前支持的RTOS
  - RT-Thread
  - RT-Thread Nano

2 LoRa Radio Driver 软件包组织结构

lora-radio
- sx126x
  - lora-radio-sx126x.c
    - 对外提供了上层访问接口实现
  - lora-spi-sx126x.c
    - sx126x芯片的spi读写接口实现，独立于MCU平台
    - rt_device
    - SPI裸机方式
  - sx126x.c
    - lora芯片sx126x底层驱动
- sx127x
  - lora-radio-sx127x.c
    - 对外提供了上层访问接口
  - lora-spi-sx127x.c
    - sx127x芯片的spi读写接口实现，独立于MCU平台
    - rt_device
    - SPI裸机方式
  - sx127x.c
    - lora芯片sx127x底层驱动
- common
  - lora-radio-timer.c
    - 提供了lora-radio所需的定时服务接口，用于发送与接收超时等，基于RT-Thread内核rt_timer实现
    - 注意这种方式提供的定时最小颗粒度取决于系统tick RT_TICK_PER_SECOND
    - 注:如果使能了Multi-Rtimer软件包，则优先使用Multi-Rtimer提供定时\超时服务
- include
  - lora-radio.h
    - 上层服务接口
  - lora-radio-debug.h
    - 根据需要使能输出lora-radio不同层级的调试信息
  - lora-radio-rtos-config.h
    - rtos适配层，选择，当前默认为RT-Thread
    - 未来支持RT-Thread-Nano、以及其他RTOS....
samples
- lora radio driver示例文件
  - lora-radio-test-shell
    - shell示例，主要实现了射频性能测试、空口数据包监听、双向通信测试等shell命令，便于日常测试
port
- 主要包含当前在不同MCU平台下支持的lora模块，lora-module文件夹中的xxxx-borad.c包含了与LoRa模块直接相关的主要硬件接口配置：
  - lora-module
    - stm32_adapter
    - lora-board-spi.c
      - STM32平台的SPI外设初始化等通用接口
    - LSD4RF-2F717N20 （SX1278 LoRa模块）
    - LSD4RF-2R717N40 （SX1268 LoRa模块）
    - Ra-01 （SX1278 LoRa模块）
      - xxxx-borad.c
        
        LoRa模块功率输出方式（PA\RFO...）
        
        LoRa模块的RF高频开关控制方式（TXE、RXE、无..）
        
        LoRa模块的DIO口（DIO0、DIO1、DIO2....）
        
        LoRa模块的工作频率限制等
    - xxx_adapter
    - 其他mcu平台下的硬件接口实现
      
      3 LoRa Radio Driver软件包使用说明
      
      3.1 依赖

SPI外设——用户需根据实际MCU平台，自定义LoRa模块实际所需要使用的SPI外设

选择SPI外设

Hardware Drivers Config --->
On-chip Peripheral Drivers --->
 [*] Enable SPI  --->
         --- Enable SPI
         [ ]   Enable SPI1
         [ ]   Enable SPI2
         [ ]   Enable SPI3
         [ ]   Enable SPI4
         [ ]   Enable SPI5

在bsp\目标板XX\board\Kconfig增加如下定义

menuconfig BSP_USING_SPI
bool "Enable SPI"
select RT_USING_SPI

if BSP_USING_SPI
 config BSP_USING_SPI1
    bool "Enable SPI1"
    default n
    if BSP_USING_SPI1
      config BSP_SPI1_RX_USING_DMA
        bool "Enable SPI1 RX DMA"
        default n
      config BSP_SPI1_TX_USING_DMA
        bool "Enable SPI1 TX DMA"
        default n
    endif
            
    # 根据实际需要，增加其他BSP_USING_SPI2、BSP_USING_SPI3...
endif

定时服务——用于提供射频通信所需的定时\超时服务，目前支持以下两种方式，二选一
- 内核 SOFT_TIMER
  - 若未选用Multi-Rtimer软件包，则默认采用内核的rt_timer来提供定时服务(lora-radio-timer.c)
  - 注意检测是否开启RT-Thread内核的SOFT_TIMER
- Multi-Rtimer软件包
  - 若使能multi-rtimer，lora-radio-driver优先使用multi-rtimer提供定时\超时服务。
    
    注：如果应用在工业温度范围、时间精度要求高(us\ms级别)的场景，建议使用multi-rtimer，并设置RTC时钟源为外部32768晶振，否则可能会出现下行丢包的情况。
```
RT-Thread online packages --->
peripheral libraries and drivers --->
[*] multi_rtimer: a real-time and low power software timer module. --->
    Version (latest)  --->
    multi_rtimer options --->
        [] multi_rtimer demo example
```
可选内核组件
- ulog组件——用于打印日志信息
  - 使能ulog
    - ulog缓存大小设置≥ 128 Byte
    - lora-raido-driver内部可看到更多LoRa底层的调试信息
    - lora-radio-test-shell.c使用ulog接口，用于打印调试信息、原始16进制数据等
  - 如果没有使用ulog，默认使用rt_kprintf来实现信息输出功能
```
RT-Thread Components --->
Utiliess --->
[*] Enable ulog
[*] Enable ISR log.
```

3.2 获取软件包

使用 lora-radio-driver 软件包，需要在 RT-Thread 的包管理中选中它，具体路径如下：

RT-Thread online packages --->
    peripheral libraries and drivers --->
        [*] lora_radio_driver: lora chipset(sx126x\sx127x.)driver. --->
            Select LoRa Radio Object Type (LoRa Radio Single-Instance)
                (lora-radio0)Setup LoRa Radio Device Name       
                (spi3)  Setup LoRa Radio Spi Name (Define BSP_USING_SPIx in [Target Platform]\Board\Kconfig)
                        Select LoRa Chip Type (LoRa Transceiver [SX126X])  --->
                        Select Supported LoRa Module [SX126X]  --->
                [ ]     Enable LoRa Radio Debug
                        Select LoRa Radio Driver Sample --->  
                    Version (latest)  --->

Select LoRa Chip \ LoRa Module
1. "Setup LoRa Radio Device Name"
  1. 设置LoRa Radio设备名称，缺省为"lora-radio0"
2. "Setup LoRa Radio Spi Name"
  1. 设置LoRa Radio Spi名称
  2. 若在 [Target Platform]\Board\Kconfig提前设定好所使用的BSP_USING_SPIx，则会自动配置
3. "Select LoRa Radio Single-Instance"
  1. 选择为单实例对象，当前只支持单个lora设备
4. "Select LoRa Chip Type"
  1. 选择实际使用的LoRa芯片类型
    - 当前支持 SX126X、SX127x Transceiver
5. "Select Supported LoRa Module"
  1. 选择lora模块，根据实际使用的MCU硬件平台与lora模块，配置关联的GPIO引脚等功能选项
    1. 设定LoRa模块的GPIO口（比如 RESET、NSS、BUSY、DIO1、TXE、RXE...）
    2. " Select LoRa Chip GPIO by Pin Number "
      - 支持使用引脚号来定义GPIO，比如输入 10 代表 A10
    3. "Select LoRa Chip GPIO by Pin Name"
      - 支持使用引脚名来定义GPIO，比如输入 A10 代表引脚GPIOA的PIN10脚 (STM32)
Select LoRa Radio Driver Sample
1. 根据实际情况，可选择测试示例
  
  3.3 新增LoRa模块
  
  在 lora-radio-driver\ports\lora-module文件下，参考已有模板，根据实际需要增加新的mcu平台适配文件、新的lora模块驱动文件xxxx-board.c

4 使用示例

4.1 硬件测试平台

当前所使用的硬件测试平台如下所示 | 序号 | 硬件平台 | MCU | LoRa模块 | 主要用户接口 | | --- | --- | --- | --- | --- | | 1 | LSD4RF-TEST2002 | STM32L476VG | LSD4RF-2R717N40
( SX1268 ) |
- 用户接口定义
- VCC - 3.3V
- GND
- SCK - PC10 (SPI3)
- MISO - PC11 (SPI3)
- MOSI - PC12 (SPI3)
- NSS - PA15
- RESET - PA7
- DIO0 - PB1
- BUSY - PB2
- RFSW1 - PB0
- RFSW2 - PC5
- 射频开关TX trace
- TX: RFSW1 = 1 , RFSW2 = 0
- TX: RFSW1 = 0 , RFSW2 = 1
| | 2 | LSD4RF-TEST2002 | STM32L476VG | LSD4RF-2F717N20
( SX1278 ) |
- 用户接口定义
- VCC - 3.3V
- GND
- SCK - PC10 (SPI3)
- MISO - PC11 (SPI3)
- MOSI - PC12 (SPI3)
- NSS - PB6
- RESET - PA7
- DIO0 - PB1
- DIO1 - PC4
- DIO2 - PB2
- DIO3 - NC
- DIO4 - NC
- RFSW1 - PB0
- RFSW2 - PC5
- 射频开关TX trace
- TX: RFSW1 = 1 , RFSW2 = 0
- TX: RFSW1 = 0 , RFSW2 = 1
| | 3 | Nucleo-L476RG | STM32L476RG | Ra-01
(RT-thread LoRa Adruino扩展板V1) |
- 用户接口定义
- VCC - 3.3V
- GND
- SCK - PA5(SPI1)
- MISO - PA6(SPI1)
- MOSI - PA7(SPI1)
- NSS - PB6
- RESET - PC7
- DIO0 - PA9
- DIO1 - PA8
|

4.2 Shell测试命令

若使能 [* ] LoRa Radio Test Shell，则可以通过shell（finish）命令直接进行LoRa相关测试

[*] Enable LoRa Radio Test Shell                                                                                              │ │
     Select the RF frequency (Region CN470)  --->                                                                            │ │
     Select RF Modem (Modem LoRa)  --->

lora ping 双向通信测试示例(SX1278 <-> SX1268) lora rx 单向接收(监听)lora数据包测试示例 (SX1278 <- 或-> SX1268)

4.3 应用层调用说明

用户层调用可以参考如下步骤

定义射频DIO中断服务回调函数


/*!
* \brief Function to be executed on Radio Tx Done event
*/
void OnTxDone( void );

/*!
* \brief Function to be executed on Radio Rx Done event
*/
void OnRxDone( uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr );

/*!
* \brief Function executed on Radio Tx Timeout event
*/
void OnTxTimeout( void );

/*!
* \brief Function executed on Radio Rx Timeout event
*/
void OnRxTimeout( void );

/*!
* \brief Function executed on Radio Rx Error event
*/
void OnRxError( void );

调用lora-radio初始化

void main(void)
{
// Radio initialization
RadioEvents.TxDone = OnTxDone;
RadioEvents.RxDone = OnRxDone;
RadioEvents.TxTimeout = OnTxTimeout;
RadioEvents.RxTimeout = OnRxTimeout;
RadioEvents.RxError = OnRxError;

if(Radio.Init(&RadioEvents))
{
    Radio.SetPublicNetwork( false );
    lora_chip_initialized = true;
}
//.....
}

配置射频通信参数

{
Radio.SetChannel( lora_radio_test_paras.frequency );

if( lora_radio_test_paras.modem == MODEM_LORA )
{
    Radio.SetTxConfig( MODEM_LORA, lora_radio_test_paras.txpower, 0, lora_radio_test_paras.bw,
                      lora_radio_test_paras.sf, lora_radio_test_paras.cr,
                      LORA_PREAMBLE_LENGTH, LORA_FIX_LENGTH_PAYLOAD_ON_DISABLE,
                      true, 0, 0, LORA_IQ_INVERSION_ON_DISABLE, 3000 );

    Radio.SetRxConfig( MODEM_LORA, lora_radio_test_paras.bw, lora_radio_test_paras.sf,
                      lora_radio_test_paras.cr, 0, LORA_PREAMBLE_LENGTH,
                      LORA_SYMBOL_TIMEOUT, LORA_FIX_LENGTH_PAYLOAD_ON_DISABLE,
                      0, true, 0, 0, LORA_IQ_INVERSION_ON_DISABLE, true );
}
}

数据发送
```
Radio.Send( Buffer, len );
```

数据接收

void OnRxDone( uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr )
{
Radio.Sleep( );
BufferSize = size;
rt_memcpy( Buffer, payload, BufferSize );
rssi_value = rssi;
snr_value = snr;
// .....
}

5 版本更新历史

V1.0.0 版本 2020-06-20
- 主体功能实现基于STM32平台
  - 支持SX126x、SX127x系列芯片
    - 测试LoRa芯片支持LSD4RF-2R717N40(SX1268)、SX1278、ASR6500S @ zyk6271
- 支持基于RT-Thread内核rt_timer的lora-radio-timer接口@ AnswerInTheWind
- 优化日志换行功能@zyk6271
V1.1.0 版本 2020-08-30
- 完善用户使用指南
- .lora-radio-driver软件包
  - 新增日志输出选择 lora-radio-debug.h，可以按需开启调试日志，也可以用于适配不同日志输出方式
  - 新增rtos适配选择 lora-radio-rtos-config.h，便于未来适配RT-Thread-Nano、不同的RTOS平台
  - lora-radio(sx126x\sx127x)
    - 同步更新到lorawan4.4.4 release版本的radio
    - sx126x更新 SX126xSetLoRaSymbNumTimeout（同步到loramac-node-master）
    - sx126x更新 RadioRandom 与 SX126xGetRandom
    - 更新 RadioIrqProcess
    - 更新RadioTimeOnAir
    - RadioIrqProcess 增加临界区保护，防止出现硬件异常
  - 调整lora-radio-driver软件包架构，便于未来适配不同的MCU平台
    - port目录下新增mcu平台适配层，如stm32_adapter
- lora-radio-test-shell
  - 修复 PHY CRC Error后，没有重新进入接收问题
  - lora ping命令
    - 新增发送空口数据包的TOA时间显示
    - 新增主机侧接收到数据包后，seqno显示
- Kconfig
  - 更新lora-radio-driver\Kconfig 软件包配置文件
    - 区分单实例(单lora模块)与多实例（多lora模块）情况，目前支持单实例
    - 移除了Kconfig中对BSP_USING_SPIx的直接定义，BSP_USING_SPIx定义调整到[Target Platform]\Board\Kconfig)
    - 重命名宏定义REGION_X为PHY_REGION_X(如REGION_CN470 -> PHY_REGION_CN470)，以便与LoRaWAN协议栈中缺省REGION_X共存
V1.1.2 版本 2020-10-12
- 修复Ra-01未同步与v1.1.1更新导致的问题
- 优化 drv_gpio.h使用，兼容RT-Thread Studio
- 优化 lora-radio-test-shell.c 功能
- 新增接收超时时间设置
V1.2 版本 2020-10-14
- 新增硬件测试平台
- ART-Pi+LSD4RF-2F717N30(SX1268)模块平台 (470~510MHz频段)
- ART-Pi+LSD4RF-2R717N40(SX1268)模块平台 (470~510MHz频段)
- ART-Pi+LSD4RF-2R822N30(SX1262)模块平台 (868/915MHz频段)
V1.4.0 版本 2021-04-25
- 重设计lora config命令，便于快速配置单个radio参数
- ping数据包长度最大支持255Byte，可通过shell自定义ping测试数据包长度
- shell新增加iq version、public network参数设置
- 使用LORA_RADIO_DEBUG_LOG代替rt_kprintf
V1.5.0 版本 2021-11-15
- 新增doxygen支持

6 问题和建议

如果有什么问题或者建议欢迎提交 Issue 进行讨论。

序号	finish命令	说明
1	lora probe	测试lora设备(SPI)访问是否正常
2	lora cw	输出CW,可用于测试发射功率、频点等 <para1>:频点，单位Hz <para2>:功率，单位dBm
3	lora ping	单向\双向通信测试 <para1> : 主机\从机 -m 主机 -s 从机 <para2>: 发送数据包个数
4	lora rx	接收(监听)数据包，同时以16进制格式与ASCII码显示数据内容
5	lora config	配置射频参数 <para1>:radio参数，字符表示 freq 表示频率，单位Hz power 表示发射功率，单位dbm sf 表示扩频因子，有效值: 7~12 bw表示带宽，有效值: 0 (125kHz)、1 (250KHz)、2 (500KHz) public表示同步字，有效值: 0 （sync = 0x12), 1 (sync = 0x34) iq 表示iq反转，有效值: 0 (iq不反转)，1 (iq反转) <para2>:radio参数的具体值

README.md