LoRa API手册
1. 网络相关参数配置及控制API
1.1 入网模式（OTAA、ABP）
1.1.1 设置
/*
功能：设置入网模式
Input Param：
lorawan_joinmethod_e mode: 目前仅支持OTAA
0 - OTAA模式； 1 - ABP模式
Return Param：
LORAWAN_API_STATUS_OK： 成功；
LORAWAN_API_STATUS_BUSY：协议栈处理忙；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_joinmode(lorawan_joinmethod_e mode);
1.1.2 获取
/*
功能：获取当前入网模式
Return Param：
lorawan_joinmethod_e mode: 目前仅支持OTAA
0 - OTAA模式； 1 - ABP模式
*/
lorawan_joinmethod_e lorawan_get_joinmode(void);
1.2 DevEUI（OTAA入网）
1.2.1 设置
/*
功能：设置节点DevEUI
Input Param：
uint8_t *deveui: 节点DevEUI
int len: 节点DevEUI长度
Return Param：
LORAWAN_API_STATUS_OK ： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_deveui(uint8_t *deveui, int len);
1.2.2 获取
/*
功能：获取节点DevEUI
Input Param：
uint8_t *deveui: 接收DevEUI的buffer地址
int size: buffer size
Return Param：
获取数据的长度
*/
int lorawan_get_deveui(uint8_t *deveui, int size);
1.3 AppEUI（OTAA入网）
1.3.1 设置
/*
功能：设置节点AppEUI
Input Param：
uint8_t *appeui: 节点AppEUI
int len: 节点AppEUI长度
Return Param：
LORAWAN_API_STATUS_OK ： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_appeui(uint8_t *appeui, int len);
1.3.2 获取
/*
功能：获取节点AppEUI
Input Param：
uint8_t *appeui: 接收AppEUI的buffer地址
int size: buffer size
Return Param：
获取数据的长度
*/
int lorawan_get_appeui(uint8_t *appeui, int size);
1.4 AppKey（OTAA入网）
1.4.1 设置
/*
功能：设置节点AppKey
Input Param：
uint8_t *appkey: 节点AppKey
int len: 节点AppKey长度
Return Param：
LORAWAN_API_STATUS_OK ： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_appkey(uint8_t *appkey, int len);
1.4.2 获取
/*
功能：获取节点AppKey
Input Param：
uint8_t *appkey: 接收AppEUI的buffer地址
int size: buffer size
Return Param：
获取数据的长度
*/
int lorawan_get_appkey(uint8_t *appkey, int size);
1.5 同频、异频模式
1.5.1 设置
/*
功能：设置节点同频、异频模式
Input Param：
lorawan_freqmode_e mode:
1 - 同频模式； 2 - 异频模式
Return Param：
LORAWAN_API_STATUS_OK ： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_freqmode(lorawan_freqmode_e freqmode);
1.5.2 获取
/*
功能：获取节点节点同频、异频模式
Return Param：
lorawan_freqmode_e mode:
1 - 同频模式； 2 - 异频模式
*/
lorawan_freqmode_e lorawan_get_freqmode(void);
2 控制和状态命令API
2.1 Class类型
2.1.1 设置
/*
功能：设置节点LoRaWAN Class类型，目前仅支持Class A
Input Param：
int8_t class:
0 - Class A； 1 - Class B；2 - Class C
Return Param：
LORAWAN_API_STATUS_OK ： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_class(int8_t class);
2.1.2 获取
/*
功能：获取节点LoRaWAN Class类型
Return Param：
0 - Class A； 1 - Class B；2 - Class C
*/
int8_t lorawan_get_class(void);
2.2 获取节点当前入网状态
/*
功能：获取入网状态
Return Param：
LORAWAN_API_STATUS_OK ： 入网成功；
LORAMAC_STATUS_NO_NETWORK_JOINED：未入网； */
int lorawan_get_joinstatus(void);
2.3 节点入网
/*
功能：节点发起入网请求
Return Param：
LORAWAN_API_STATUS_BUSY：协议栈处理忙
LORAWAN_API_STATUS_NO_NETWORK_JOINED: 入网失败
*/
int lorawan_open(void);
2.4 清除节点入网状态
/*
功能：清除节点入网状态
Return Param：
LORAWAN_API_STATUS_OK： 成功；
LORAWAN_API_STATUS_BUSY：协议栈处理忙；
*/
int lorawan_close( void);
2.5 入网参数配置
2.5.1 设置
/*
功能：入网请求失败时，尝试次数及间隔的配置
Input Param：
lorawan_joinparams_t *joinparams:
typedef struct {
bool autojoin; //入网失败时，是否自动重试
uint8_t joininterval; //入网请求失败时，发送间隔，单位： 秒
uint8_t jointrials; //入网请求最大发送次数（失败时）
} lorawan_joinparams_t;
Return Param：
LORAWAN_API_STATUS_OK ： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_joinparams( lorawan_joinparams_t *joinparams);
2.5.2 获取
/*
功能：获取入网请求配置参数
Input Param：
lorawan_joinparams_t *joinparams:
typedef struct {
bool autojoin;
uint8_t joininterval;
uint8_t jointrials;
} lorawan_joinparams_t;
Return Param：
LORAWAN_API_STATUS_OK ： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_get_joinparams(lorawan_joinparams_t *joinparams);
3 数据收发API
3.1 LoRaWAN API
3.1.1 数据发送（同步）
/*
Input Param：
lora_appdata_t *appdata:
typedef struct {
uint8_t *buff; //发送数据
uint8_t buffsize; 发送数据长度 要求<= 51
uint8_t port; 发送端口号
} lora_appdata_t;
Return Param：
LORAWAN_API_STATUS_BUSY：协议栈处理忙；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
LORAWAN_API_STATUS_LENGTH_ERROR：数据长度错误，大于51（LinkWAN）；
LORAWAN_API_STATUS_NO_NETWORK_JOINED ： 未入网
LORAWAN_API_EVENT_INFO_STATUS_OK： 消息发送成功
> LORAWAN_API_EVENT_INFO_STATUS_OK : 失败
*/
int lorawan_send(lora_appdata_t *appdata);
3.1.2 设置应用端口号
3.1.2.1 设置
/*
功能：设置应用端口号
Input Param：
uint8_t port: 1~223
Return Param：
LORAWAN_API_STATUS_OK ： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_appport(uint8_t port);
3.1.2.2 获取
/*
功能：获取当前应用端口号
Return Param：
1~223
*/
uint8_t lorawan_get_appport(void);
3.1.3 数据发送参数配置
3.1.3.1 设置
/*
功能：设置发送数据类型及尝试发送次数
Input Param：
lorawan_sendparams_t *sendparams:
typedef struct {
lorawan_msgtype_e msgtype; //0 - unconfirm包；1 - confirm包
uint8_t nbtrails; //数据最大发送次数
} lorawan_sendparams_t;
Return Param：
LORAWAN_API_STATUS_OK ： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_sendparams(lorawan_sendparams_t *sendparams);
3.1.3.2 获取
/*
功能：获取数据发送参数配置
Input Param：
lorawan_sendparams_t *sendparams:
typedef struct {
lorawan_msgtype_e msgtype;
uint8_t nbtrails;
} lorawan_sendparams_t;
Return Param：
LORAWAN_API_STATUS_OK ： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_get_sendparams(lorawan_sendparams_t *sendparams);
3.1.4 数据接收
/*
Input Param：
lora_appdata_t *appdata:
typedef struct {
uint8_t *buff; //接收数据
uint8_t buffsize; 接收数据长度，传进去是buffer size，返回接收到的数据长度
uint8_t port; 接收端口号
} lora_appdata_t;
Return Param：
LORAWAN_API_STATUS_ERROR: 协议栈未接收到数据
LORAWAN_API_EVENT_INFO_STATUS_OK： 数据接收成功
> LORAWANAPI_EVENT_INFO_STATUS_OK : 数据接收失败，参见[返回值说明](#返回值说明)
*/
int lorawan_recv(lora_appdata_t *appdata)
3.2 Radio API
3.2.1 Radio回调注册
/*
功能：节点配置lora发送参数
Input Param：
RadioEvents_t *radioEvents:
typedef struct
{
/*!
* \brief Tx Done callback prototype.
*/
void ( *TxDone )( void );
/*!
* \brief Tx Timeout callback prototype.
*/
void ( *TxTimeout )( void );
/*!
* \brief Rx Done callback prototype.
*
* \param [IN] payload Received buffer pointer
* \param [IN] size Received buffer size
* \param [IN] rssi RSSI value computed while receiving the frame [dBm]
* \param [IN] snr Raw SNR value given by the radio hardware
* FSK : N/A ( set to 0 )
* LoRa: SNR value in dB
*/
void ( RxDone )( uint8_t payload, uint16_t size, int16_t rssi, int8_t snr );
/*!
* \brief Rx Timeout callback prototype.
*/
void ( *RxTimeout )( void );
/*!
* \brief Rx Error callback prototype.
*/
void ( *RxError )( void );
}RadioEvents_t;
Return Param：
0 - 成功； 1 - 参数错
*/
int radiolora_init(RadioEvents_t *radioEvents)
3.2.2 数据发送参数
/*
功能：节点配置lora发送参数
Input Param：
uint32_t freq: 信道所在的频点
int8_t tx_power: SX1262/8的发射功率, 范围: 15~22 dBm
uint8_t bandwidth: 信道带宽,
范围: 0 ~ 2;
0 - 125kHZ
1 - 200kHZ
2 - 250kHZ
uint8_t spreadfactor: 扩频因子
范围: 12 ~ 7, 对应扩频因子SF12 ~ SF7
Return Param：
0 - 成功；1 - 参数错
*/
int radiolora_txconfig(uint32_t freq, int8_t tx_power, uint32_t bandwidth, uint32_t spreadfactor )
3.2.3 数据发送
/*
功能：节点使用lora发送数据
Input Param：
uint8_t *payload: 发送数据
uint8_t len: 发送数据长度
Return Param：
0 - 成功； 1 - 参数错
*/
int radiolora_tx(int8_t *payload, uint8_t len)
3.2.4 数据接收参数
/*
功能：节点配置lora接收参数
Input Param：
uint32_t freq: 信道所在的频点
uint32_t bandwidth: 信道带宽
uint32_t spreadfactor: 扩频因子
范围: 12 ~ 7, 对应扩频因子SF12 ~ SF7
uint16_t preambleLen: 前导码长度 8/12
uint8_t fixLen: 数据长度为固定长度或可变长度
0 - 可变长度； 1 - 固定长度
uint8_t payloadLen: 数据包长度
Return Param：
0 - 成功； 1 - 参数错
*/
int radiolora_rxconfig(uint32_t freq, uint32_t bandwidth, uint32_t spreadfactor, uint16_t preambleLen, uint8_t fixLen, uint8_t payloadLen )
3.2.5 数据接收
/*
功能：节点使用lora接收数据
Input Param：
uint32_t timeout: 接收超时；单位：ms，
0 : wait forever
Return Param：
0 - 成功； 1 - 参数错
*/
int radiolora_rx(uint32_t timeout)
4 MAC配置API
4.1 发送数据速率
4.1.1 设置
/*
功能：设置节点发送数据速率
Input Param：
uint8_t datarate:
范围：0~5 （SF12 ~ SF7）
Return Param：
LORAWAN_API_STATUS_OK： 成功；
LORAWAN_API_STATUS_BUSY：协议栈处理忙；
LORAWAN_API_STATUS_DATARATE_INVALID：DR设置不合法
LORAWAN_API_STATUS_FREQ_AND_DR_INVALID：ADR已使能，禁止设置DR
*/
int lorawan_set_txdatarate(uint8_t datarate);
4.1.2 获取
/*
功能：获取当前发送数据速率
Return Param：
范围：0~5 （SF12 ~ SF7）
*/
int8_t lorawan_get_txdatarate(void);
4.2 发射功率
4.2.1 设置
/*
功能：设置节点发射功率
Input Param：
uint8_t txpower: 发射功率，
CN470的取值范围：
| 序号 | 功率值(dBm) |
|---|---|
| 0 | 17 |
| 1 | 15 |
| 2 | 13 |
| 3 | 11 |
| 4 | 9 |
| 5 | 7 |
| 6 | 5 |
| 7 | 3 |
Return Param：
LORAWAN_API_STATUS_OK： 成功；
LORAWAN_API_STATUS_BUSY:协议栈忙
*/
int lorawan_set_txpower(uint8_t txpower);
4.2.2 获取
/*
功能：获取当前发射功率
Return Param：
参考如上CN470发射功率取值范围。
*/
uint8_t lorawan_get_txpower(void);
4.3 ADR功能
4.3.1 设置
/*
功能：开启、关闭ADR功能
Input Param：
bool enable:
True: 开启ADR功能; False: 关闭ADR功能
Return Param：
LORAWAN_API_STATUS_OK： 成功；
LORAWAN_API_STATUS_BUSY：协议栈处理忙
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_adr(bool enable);
4.3.2 获取
/*
功能：ADR开启状态
Return Param：
True: ADR开启; False: ADR关闭
*/
bool lorawan_get_adr(void);
4.4 RX1窗口时延
4.4.1 设置
/*
功能：设置节点RX1 window 时延
Input Param：
uint32_t rx1windowdelay:
单位：秒， 范围0 ~ 15秒
Return Param：
LORAWAN_API_STATUS_OK： 成功；
LORAWAN_API_STATUS_BUSY：协议栈处理忙
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_rx1delay(uint32_t rx1delay);
4.4.2 获取
/*
功能：获取节点RX1 window 开启时延
Return Param：
取值范围：0 ~ 15 单位：秒
*/
uint32_t lorawan_get_rx1delay(void);
4.5 接收窗口RX1、RX2配置
4.5.1 设置
/*
功能：设置节点RX1、RX2参数
Input Param：
uint8_t rx1droffset: RX1 window的DR偏移 范围：0 ~ 3
uint8_t rx2datarate: RX2 window的DR 范围：0 ~ 5
uint32_t rx2freq: RX2 window的频点 范围：CN470 ~ CN510, 说明详见LoRaWAN协议
Return Param：
LORAWAN_API_STATUS_OK： 成功；
LORAWAN_API_STATUS_BUSY：协议栈处理忙
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
int lorawan_set_rxwindownparams(uint8_t rx1droffset, uint8_t rx2datarate, uint32_t rx2freq);
4.5.2 获取
/*
功能：获取节点RX1、RX2参数
Input Param：
uint8_t *rx1droffset: RX1 window的DR偏移
uint8_t *rx2datarate: RX2 window的DR
uint32_t *rx2freq: RX2 window的频点
Return Param：
LORAWAN_API_STATUS_OK： 成功；
LORAWAN_API_STATUS_BUSY：协议栈处理忙
*/
int lorawan_get_rxwindownparams(uint8_t *rx1droffset, uint8_t *rx2datarate, uint32_t *rx2freq)
4.6 检测频段各信道接收灵敏度
/*
功能：检测LinkWAN使用频段各信道接收灵敏度
Input Param：
uint8_t band: 频段编号，目前仅支持1A2频段
0 - 1A1（483.9MHz～485.3MHz）
1 - 1A2（485.5MHz～486.9MHz）
int16_t *channel_rssi: 返回RSSI值的buffer地址
uint8_t channel_num: buffer length; >= 8
Return Param：
LORAWAN_API_STATUS_OK： 成功；
LORAWAN_API_STATUS_PARAMETER_INVALID： 传参错误；
*/
void lorawan_get_rssi(uint8_t band, int16_t *channel_rssi, uint8_t channel_num)
4.7 链路检测
/*
功能：链路检测
Input Param：
uint8_t *demodmargin: 返回当前链路的Demodulation margin
uint8_t *nbgateways: 返回当前链路所在网络的网关数
int16_t *rssi: 返回当前链路的接收灵敏度
uint8_t *snr: 返回当前链路的SNR
Return Param：
LORAWAN_API_STATUS_OK： 成功；
LORAWAN_API_STATUS_NO_NETWORK_JOINED
*/
int lorawan_linkcheck(uint8_t *demodmargin, uint8_t *nbgateways, int16_t *rssi, uint8_t *snr)
4.8 保存当前配置参数
int lorawan_saveconfig(void)
4.9 恢复默认配置参数
int lorawan_restoreconfig(void);
5 协议栈运行
5.1 初始化
/*
功能：协议栈初始化
Input Param：
lora_workmode_e loramode:
0 - LoRaWAN模式， 初始化LoRaWAN协议栈
1 - Radio模式，传参非法时默认Radio模式
*/
void lora_system_init(lora_workmode_e loramode)
5.2 运行
/*
功能：运行协议栈状态机
Input Param：
void *arg : 任务创建时传参，为NULL
*/
void lora_system_run(void *arg)
5.3 复位
/*
功能：协议栈复位
Input Param：
int8_t mode:
0 - 立即复位; 1 - 发送最后一包数据，再复位
*/
void lora_system_reboot(int8_t mode)
6 返回值说明
typedef enum {
/*!
\* Service started successfully
*/
LORAWAN_API_STATUS_OK = 0,
/*!
\* Service not started - LoRaMAC is busy
*/
LORAWAN_API_STATUS_BUSY,
/*!
\* Service unknown
*/
LORAWAN_API_STATUS_SERVICE_UNKNOWN,
/*!
\* Service not started - invalid parameter
*/
LORAWAN_API_STATUS_PARAMETER_INVALID,
/*!
\* Service not started - invalid frequency
*/
LORAWAN_API_STATUS_FREQUENCY_INVALID,
/*!
\* Service not started - invalid datarate
*/
LORAWAN_API_STATUS_DATARATE_INVALID,
/*!
\* Service not started - invalid frequency and datarate
*/
LORAWAN_API_STATUS_FREQ_AND_DR_INVALID,
/*!
\* Service not started - the device is not in a LoRaWAN
*/
LORAWAN_API_STATUS_NO_NETWORK_JOINED,
/*!
\* Service not started - payload length error
*/
LORAWAN_API_STATUS_LENGTH_ERROR,
/*!
\* Service not started - the specified region is not supported
\* or not activated with preprocessor definitions.
*/
LORAWAN_API_STATUS_REGION_NOT_SUPPORTED,
/*!
\* The application data was not transmitted
\* because prioritized pending MAC commands had to be sent.
*/
LORAWAN_API_STATUS_SKIPPED_APP_DATA,
/*!
\* ToDo
*/
LORAWAN_API_STATUS_DUTYCYCLE_RESTRICTED,
/*!
*
*/
LORAWAN_API_STATUS_NO_CHANNEL_FOUND,
/*!
*
*/
LORAWAN_API_STATUS_NO_FREE_CHANNEL_FOUND,
/*!
\* ToDo
*/
LORAWAN_API_STATUS_BUSY_BEACON_RESERVED_TIME,
/*!
\* ToDo
*/
LORAWAN_API_STATUS_BUSY_PING_SLOT_WINDOW_TIME,
/*!
\* ToDo
*/
LORAWAN_API_STATUS_BUSY_UPLINK_COLLISION,
/*!
\* An error in the cryptographic module is occurred
*/
LORAWAN_API_STATUS_CRYPTO_ERROR,
/*!
\* An error in the frame counter handler module is occurred
*/
LORAWAN_API_STATUS_FCNT_HANDLER_ERROR,
/*!
\* An error in the MAC command module is occurred
*/
LORAWAN_API_STATUS_MAC_COMMAD_ERROR,
/*!
\* An error in the Class B module is occurred
*/
LORAWAN_API_STATUS_CLASS_B_ERROR,
/*!
\* An error in the Confirm Queue module is occurred
*/
LORAWAN_API_STATUS_CONFIRM_QUEUE_ERROR,
/*!
\* Undefined error occured
*/
LORAWAN_API_STATUS_ERROR,
/*!
\* Service performed successfully
*/
LORAWAN_API_EVENT_INFO_STATUS_OK,
/*!
\* An error occurred during the execution of the service
*/
LORAWAN_API_EVENT_INFO_STATUS_ERROR,
/*!
\* A Tx timeout occurred
*/
LORAWAN_API_STATUS_TX_TIMEOUT,
/*!
\* An Rx timeout occurred on receive window 1
*/
LORAWAN_API_STATUS_RX1_TIMEOUT,
/*!
\* An Rx timeout occurred on receive window 2
*/
LORAWAN_API_STATUS_RX2_TIMEOUT,
/*!
\* An Rx error occurred on receive window 1
*/
LORAWAN_API_STATUS_RX1_ERROR,
/*!
\* An Rx error occurred on receive window 2
*/
LORAWAN_API_STATUS_RX2_ERROR,
/*!
\* An error occurred in the join procedure
*/
LORAWAN_API_STATUS_JOIN_FAIL,
/*!
\* A frame with an invalid downlink counter was received. The
\* downlink counter of the frame was equal to the local copy
\* of the downlink counter of the node.
*/
LORAWAN_API_STATUS_DOWNLINK_REPEATED,
/*!
\* The MAC could not retransmit a frame since the MAC decreased the datarate. The
\* payload size is not applicable for the datarate.
*/
LORAWAN_API_STATUS_TX_DR_PAYLOAD_SIZE_ERROR,
/*!
\* The node has lost MAX_FCNT_GAP or more frames.
*/
LORAWAN_API_STATUS_DOWNLINK_TOO_MANY_FRAMES_LOSS,
/*!
\* An address error occurred
*/
LORAWAN_API_STATUS_ADDRESS_FAIL,
/*!
\* Message integrity check failure
*/
LORAWAN_API_STATUS_MIC_FAIL
} lorawan_api_status;