LPGWMD002用户手册--软件设计开发指南
LPGWMD002支持硬件SPI或USB方式连接LinuxHost主机构成lorawan网关，下面将分别对这两种使用场景进行说明，帮助用户快速熟悉模块的使用和操作流程。
本文还将对模块驱动代码工程进梳理，有利于客户进行优化和二次开发。
2.1基础概念
下图是lorawan网络的基础系统构架，其中LPGWMD002是lorawan网络的核心模块，由它进行无线数据的收发；但是部分协议处理的相关工作由外部的Host主机系统以及lorawanserver完成。
2.2 Host主机系统
参考上图需要由Host主机系统配合LPGWMD002来构成Gateway(此处我们假设用户已经准备好了linux(包括嵌入式linux)系统的Host主机系统,如Raspberry PI或类似的系统，同样我们假设用户对基础的linux操作已经熟悉，包括命令行操作、代码编译操作等)。
本文所有的操作及使用均在Debian 8 “Jessie” Linux发型版上进行，依赖的硬件平台为Raspberry PI3 B+或CM3。虽然本文操作均在Raspberry PI上进行，但是在其他类似的linux系统同样也适用，但是可能有些微小差别（本文不负责解释和说明）。
参考《LPGWMD002-miniPCIE接口sx1301模块-硬件设计开发指南-V1.00.pdf》文档第7节之7.1所述将模块与LinuxHost主机，此处根据需要使用硬件SPI或者USB接口，注意电源供电需满足条件。
Semtech提供了开源的sx1301驱动代码，并将其存储在( https://github.com/ )上，github仓库地址(https://github.com/Lora-net ),此处存放所有官方提供的lorawan相关的代码资源，本文所有用到的驱动代码为：
https://github.com/Lora-net/lora_gateway
注１：本文所用的SPI驱动版本为3.2.1，其他版本可参考本文以及github文档自行处理，恕不通知。
注２：本文所用的USB驱动版本为3.0.1，该版本为最后支持USB驱动的固件版本之一，在此之后官方删除了对USB的支持。
2.5.1获取源码
A)sudo apt-get install git
B)mkdir -p ~/LoRa/lora_gateway
C)cd ~/LoRa/lora_gateway
D)git clone https://github.com/Lora-net/lora_gateway.git
2.5.2Host主机系统配置
E)驱动源码需要使用主机系统的 “native” SPI，源码中的设备名为 “/dev/spidev0.0”，通过以下一系列操作开启主机系统的“native” SPI，最后需要重启生效：
sudo raspi-config->Advanced Options->SPI->YES->sudo reboot
F)配置完SPI接口还需配置RESET控制引脚，此处需要编写一个脚本文件，假设使用 Raspberry Pi 的 GPIO 17 (pin 11)作为RESET引脚，内容如下：
#!/bin/bash
echo "17" > /sys/class/gpio/export
echo "out" > /sys/class/gpio/gpio17/direction
echo "1" > /sys/class/gpio/gpio17/value
sleep 5
echo "0" > /sys/class/gpio/gpio17/value
sleep 1
echo "0" > /sys/class/gpio/gpio17/value
然后保存为“LPGWMD002-SPI_reset.sh”，以后每次Raspberry Pi重启后需手动执行该复位脚本，使sx1301正常复位后开始工作。
2.5.3驱动配置
通过修改ora_gateway/libloragw/library.cfg中的相关配置，可以打印相关信息，用于测试和调试
DEBUG_AUX = 0
DEBUG_SPI = 0
DEBUG_REG = 0
DEBUG_HAL = 0
DEBUG_GPS = 0
只需将相应的项设置成=1即可开始相关调试信息。
2.5.4编译驱动
G)cd ~/LoRa/lora_gateway
H)make
执行完该命令后将在目录“lora_gateway\libloragw”编译生成 “libloragw.a” 备用，以及测试程序如：“test_loragw_reg”，“test_loragw_hal”等，可以之后测试sx1301硬件寄存器功能等‘
将在“lora_gateway”下再生成“lora_gateway\util_tx_test”等目录可以用于测试sx1301通信功能，如：
A)cd lora_gateway/util_tx_test
B)./util_tx_test –r 1255 –f 471.5
执行完后将按如下所示参数进行周期数据发送。
Sending -1 packets on 471500000 Hz (BW 125 kHz, SF 10, CR 1,
16 bytes payload, 8 symbols preamble) at 14 dBm, with 1000 ms
between each
INFO: concentrator started, packet can be sent
Sending packet number 1 ...OK
Sending packet number 2 ...OK
Sending packet number 3 ...OK
...
其他不在赘述，更详细内容请参考每个文件夹下的“readme.md”说明文件。
2.6.1安装扩展驱动
LPGWMD002通过USB连接到Host主机，需要安装“libmpsse”驱动。
A)sudo apt-get update
B)sudo apt-get install git --assume-yes
C)sudo apt-get install libftdi-dev --assume-yes
D)mkdir –p ~/LoRa/libmpsse
E)cd ~/LoRa/libmpsse
F)wget https://storage.googleapis.com/google-code-archive-downloads/v2/code.google.com/libmpsse/
libmpsse-1.3.tar.gz
G)tar zxvf libmpsse-1.3.tar.gz
H)cd libmpsse-1.3/src
I)./configure --prefix=/usr --disable-python
J)make
K)sudo make install
L)cd /etc/udev/rules.d
M)sudo wget N)https://raw.githubusercontent.com/mirakonta/lora_gateway/master/libloragw/99-libftdi.rules
O)sudo udevadm control --reload-rules
P)sudo udevadm trigger
2.6.2获取源码
R)sudo apt-get install git
S)mkdir -p ~/LoRa/lora_gateway
T)cd ~/LoRa/lora_gateway
U)git clone https://github.com/Lora-net/lora_gateway.git
2.6.3驱动配置
通过修改ora_gateway/libloragw/library.cfg中的相关配置，可以打印相关信息，用于测试和调试
CFG_SPI= ftdi
CFG_BRD= ref_1301_868
此处为源码中对应的硬件版本号，只是一个宏定义，在此默认它就是LPGWMD002。
DEBUG_AUX = 0
DEBUG_SPI = 0
DEBUG_REG = 0
DEBUG_HAL = 0
DEBUG_GPS = 0
只需将相应的项设置成=1即可开启相关调试信息。
2.6.4编译驱动
同2.5.4所述，不再赘述。
3 lora_gateway源码结构及HAL库使用说明
本文使用https://github.com/Lora-net/lora_gateway仓库中V5.0.1版本进行说明。
是配合Semtech的SX1301AP2参考设计所用的文件。
是sx1301的HAL层(LoRa concentrator Hardware Abstraction Layer)，通过这个C库用户可以通过API调用实现对sx1301的配置以及数据收发，这个HAL层由以下6(8)个子模块构成，
目录是lora_gateway\libloragw\src：
l loragw_hal：主模块，包含高等级函数来配置和使用集中器
l loragw_reg：这个模块用来操作集中器的寄存器
l loragw_spi：通过SPI接口来操作集中器的寄存器
l loragw_aux：包含一个主机需要的wait_ms函数，用于指定ms的延时
l loragw_gps：通过基准时基来同步集中器内部计数，例如例程中的GPS授时。
l loragw_radio：配置 SX125x 和 SX127x。
l loragw_fpga (only for SX1301AP2 ref design)：SX1301AP2参考设计才需要，用于操作FPGA的寄存器，以及配置FPGA功能。
l loragw_lbt (only for SX1301AP2 ref design)：SX1301AP2参考设计才需要，用于配置和使用LBT功能。
文件lora_gateway\libloragw\library.cfg用来配置HAL库调试信息的输出，
DEBUG_AUX = 0
DEBUG_SPI = 0
DEBUG_REG = 0
DEBUG_HAL = 0
DEBUG_LBT = 0
DEBUG_GPS = 0
如需输出某种打印信息将DEBUG_xx置成 = 1即可。
3.3目录lora_gateway\util_xx_xx类似的文件
均为使用通过API调用HAL库的例子程序，这些例子同样可以做为测试功能使用。
l lora_gateway\util_lbt_test：这个软件用来测试“Listen-Before-Talk”的信道时间戳。
l lora_gateway\util_pkt_logger：这个软件用来让sx1301使用JSON配置文件，以及将所有的包记录于一个log文件。
l lora_gateway\util_spectral_scan：这个软件用来扫描基站工作环境的频谱。
l lora_gateway\util_spi_stress：这个软件通过Host主机读取sx1301的寄存器文件来检测的连接的稳定性。
l lora_gateway\util_tx_continuous：这个软件用来设置sx1301为持续TX模式，用于频谱测试。
l lora_gateway\util_tx_test：这个软件用来做发包测试。包里有少量非协议格式信息，但可以用来检测基站下行功能，需要使用另一台基站来做接收。
3.4文件lora_gateway\reset_lgw.sh
他是依赖于特定平台的通过GPIO口复位sx1301的脚本文件，需要在每次使用sx1301功能前执行此脚本复位芯片。
3.5.1软件细节
这个库按照ANSI C99进行编写。loragw_aux模块中的ms精确延时含有POSIX格式函数，嵌入式平台可以用硬件定时器进行重写。
library.cfg 中 DEBUG_xxx 如果置为1，则会用 fprintf 输出对应的调试信息。
对于交叉编译，需要设置 Makefile 中的 ARCH 和 CROSS_COMPILE 变量，或者在 shell 环境中，使用正确的工具链名字和路径。
例如：
l export PATH=/home/foo/rpi-toolchain/tools/arm-bcm2708/gcc-linaro-arm-linux-gnueabihf-raspbian-x64/bin:$PATH
l export ARCH=arm
l export CROSS_COMPILE=arm-linux-gnueabihf-
libloragw目录下的Makefile会解析 library.cfg 文件，产生一个config.h的C头文件，包含 #define 选项。那些选项会使能或禁用loragw_xxx.h 文件和 .c 原文件中的代码。library.cfg 也用来直接选择动态链接库。
注：树莓派系统自带编译和以直接编译本文代码。
如果想在其他系统使用编译后的库，你需要导出这些文件：
l libloragw/library.cfg -> 根配置文件
l libloragw/libloragw.a -> 静态库
l libloragw/readme.md -> license要求
l libloragw/inc/config.h -> 从 library.cfg 衍生出的C配置标志
l libloragw/inc/loragw_.h -> 你需要用到的头文件 (例如. _hal and _gps)
在这个库链接到你的应用之后，只有 license 文件要求在程序文件中拷贝和保留。
3.6.1 设置软件环境
对一个典型应用，你需要这么做：
l 源码中包含 loragw_hal.h
l 编译时链接 libloragw.a 静态库文件
l 由于 loragw_aux 的依赖关系，需要链接 librt 库
如果应用需要直接访问集中器配置寄存器的话(例如做些高级配置)，你还需要这样做：
l 源码中包含 loragw_reg.h
3.6.2 使用软件API
要在你的应用中使用 HAL，需要遵守如下规则：
l 在射频启动之前需要配置好 radios path 和 IF+modem path
l 只有在调用了 start 函数之后，配置才会传送给硬件
l 只有在 radio 使能，同时IF+modem 使能，以及集中器启动后，才能接收数据包。
l 只有在 radio 使能，以及集中器启动后，才能发送数据包。
l 改变配置之前，必须停止集中器。
一个对HAL的典型应用流程图如下：
<configure the radios and IF+modems>
<start the LoRa concentrator>
loop {
<fetch packets that were received by the concentrator>
<process, store and/or forward received packets>
<send packets through the concentrator>
}
<stop the concentrator>
注意：lgw_send 在LoRa集中器仍然发包时，或者即使在准备开始发包时，是非阻塞立即返回。当有数据包在发送时，将无法收到任何数据。你的应用需要考虑发包的时长，或者在尝试发包前检查下状态(使用 lgw_status)。当前一包未完成时立即发一包，会导致前一包无法发送，或者发送部分(会导致接收端出现CRC错误)。
3.7.1 硬件版本
loragw_reg 和 loragw_hal 是针对Semtech硬件编写的程序：
Semtech SX1301 芯片
Semtech SX1257 or SX1255 收发器
如果硬件版本和库版本不匹配的话，这个库将无法使用。你可以用 test_loragw_reg 来测试软硬件是否匹配。
loragw_spi 的SPI函数适合平台相关的，如果你用别的SPI接口可能需要重写这个函数：
SPI master matched to the Linux SPI device driver (provided)
SPI over USB using FTDI components (not provided)
native SPI using a microcontroller peripheral (not provided)
你可以用 test_loragw_spi 来测试SPI通信。
为了使用库中的GPS模块，主机必须要通过串口连接GPS接收器，串口连接必须以“tty”设备出现在 /dev/ 目录，启用这个程序的用户必须用读写这个设备的权限。使用 chmod a+rw 来允许所有用户能操作指定的tty设备，或者使用sudo来运行你的程序(例如. sudo ./test_loragw_gps)。
当前版本，库只从串口读取数据，在GPS接收器上电后会收到他们发出NMEA帧 以及 u-blox 模块私有的 UBX 消息。
GPS接收器必须在发出PPS脉冲后发出UBX消息，让内部集中器的时间戳可以用GPS时基校准。如果GPS接收器发出了GGA NMEA语句，gateway则可以进行3D定位。
