RN2483/RN2903 LoRa module driver

High-level driver for the RN2483/RN2903 LoRa modules.

enum @154
RN2XX3_OK
Command is valid.
RN2XX3_DATA
Command returned data.
RN2XX3_TIMEOUT
Command timeout.
RN2XX3_ERR_MAC_INIT
Device mac initialization failed.
RN2XX3_ERR_INVALID_PARAM
Wrong command given.
RN2XX3_ERR_NOT_JOINED
Network is not joined.
RN2XX3_ERR_NO_FREE_CH
All channels are busy.
RN2XX3_ERR_SILENT
Device is in Silent Immediately state.
RN2XX3_ERR_FR_CNT_REJOIN_NEEDED
Frame counter rolled over.
RN2XX3_ERR_BUSY
MAC is not in Idle state.
RN2XX3_ERR_MAC_PAUSED
MAC was paused.
RN2XX3_ERR_INVALID_DATA_LENGTH
Wrong payload given.
RN2XX3_ERR_KEYS_NOT_INIT
Keys not configured (“mac join” command)
RN2XX3_ERR_SLEEP_MODE
Failure because device is in sleep mode.
RN2XX3_REPLY_TX_MAC_OK
MAC transmission successful.
RN2XX3_REPLY_TX_MAC_ERR
MAC transmission failed.
RN2XX3_REPLY_TX_INVALID_DATA_LEN
Application payload too large.
RN2XX3_REPLY_TX_MAC_RX
Data received from server.
RN2XX3_REPLY_JOIN_ACCEPTED
Join procedure successful.
RN2XX3_REPLY_JOIN_DENIED
Join procedure failed.
RN2XX3_REPLY_TIMEOUT
No MAC reply received from server.
RN2XX3_REPLY_OTHER
Unknown reply.
enum @155
RN2XX3_INT_STATE_RESET
the device is being reset or initialized
RN2XX3_INT_STATE_CMD
waiting command response
RN2XX3_INT_STATE_IDLE
waiting for incoming commands
RN2XX3_INT_STATE_SLEEP
sleep mode
RN2XX3_INT_STATE_MAC_JOIN
waiting for mac join procedure reply
RN2XX3_INT_STATE_MAC_TX
waiting for mac tx reply
RN2XX3_INT_STATE_MAC_RX_PORT
waiting for mac rx port
RN2XX3_INT_STATE_MAC_RX_MESSAGE
waiting for mac rx message
void rn2xx3_setup(rn2xx3_t * dev, const rn2xx3_params_t * params)

Prepares the given RN2XX3 device.

Parameters

dev:RN2XX3 device to initialize
params:parameters for device initialization

int rn2xx3_init(rn2xx3_t * dev)

Initializes the RN2XX3 device.

Parameters

dev:RN2XX3 device descriptor

Return values

  • RN2XX3_OK on success
  • -ENXIO if UART initialization failed
  • RN2XX3_TIMEOUT if UART communication failed
int rn2xx3_sys_reset(rn2xx3_t * dev)

Restarts the RN2XX2 device.

After calling this function, dev->resp_buf contains the module name and version string.

Parameters

dev:RN2XX3 device descriptor

Return values

  • RN2XX3_OK on success
  • RN2XX3_TIMEOUT if UART communication failed
int rn2xx3_sys_factory_reset(rn2xx3_t * dev)

Performs a factory reset of the module.

The configuration data and user EEPPROM are reinitialized to factory default values and the module reboots

After calling this function, dev->resp_buf contains the module name and version string.

Parameters

dev:RN2XX3 device descriptor

Return values

  • RN2XX3_OK on success
  • RN2XX3_TIMEOUT if UART communication failed
int rn2xx3_sys_sleep(rn2xx3_t * dev)

Puts the RN2XX2 device in sleep mode.

Parameters

dev:RN2XX3 device descriptor

Return values

  • RN2XX3_OK on success
  • RN2XX3_TIMEOUT if UART communication failed
int rn2xx3_mac_init(rn2xx3_t * dev)

Initializes the RN2XX3 device MAC layer.

Parameters

dev:RN2XX3 device descriptor

Return values

  • RN2XX3_OK on success
  • RN2XX3_TIMEOUT if UART communication failed
int rn2xx3_write_cmd(rn2xx3_t * dev)

Writes a command to the RN2XX3 device.

The module will immediately reply with a meaningful message if the command is valid or not.

Parameters

dev:RN2XX3 device descriptor

Return values

  • RN2XX3_OK on success
  • RN2XX3_TIMEOUT if no response is received from the module
  • RN2XX3_ERR_INVALID_PARAM if command is invalid
  • RN2XX3_ERR_NOT_JOINED if network is not joined
  • RN2XX3_ERR_NO_FREE_CH if no free channel
  • RN2XX3_ERR_SILENT if device is in Silent state
  • RN2XX3_ERR_FR_CNT_REJOIN_NEEDED if frame counter rolled over
  • RN2XX3_ERR_BUSY if MAC is not in Idle state
  • RN2XX3_ERR_INVALID_DATA_LENGTH if payload is too large
  • RN2XX3_ERR_KEYS_NOT_INIT if keys are not configured
int rn2xx3_write_cmd_no_wait(rn2xx3_t * dev)

Writes a command to the RN2XX3 device but don’t wait for timeout.

The module will immediately reply with a meaningful message if the command is valid or not.

Parameters

dev:RN2XX3 device descriptor

Return values

  • RN2XX3_OK on success
  • RN2XX3_ERR_INVALID_PARAM if command is invalid
  • RN2XX3_ERR_NOT_JOINED if network is not joined
  • RN2XX3_ERR_NO_FREE_CH if no free channel
  • RN2XX3_ERR_SILENT if device is in Silent state
  • RN2XX3_ERR_FR_CNT_REJOIN_NEEDED if frame counter rolled over
  • RN2XX3_ERR_BUSY if MAC is not in Idle state
  • RN2XX3_ERR_INVALID_DATA_LENGTH if payload is too large
  • RN2XX3_ERR_KEYS_NOT_INIT if keys are not configured
int rn2xx3_wait_response(rn2xx3_t * dev)

Waits for a response to a command from the device.

Parameters

dev:RN2XX3 device descriptor

Return values

  • RN2XX3_OK on success
  • RN2XX3_TIMEOUT if no response is received from the module
  • RN2XX3_ERR_INVALID_PARAM if command is invalid
  • RN2XX3_ERR_NOT_JOINED if network is not joined
  • RN2XX3_ERR_NO_FREE_CH if no free channel
  • RN2XX3_ERR_SILENT if device is in Silent state
  • RN2XX3_ERR_FR_CNT_REJOIN_NEEDED if frame counter rolled over
  • RN2XX3_ERR_BUSY if MAC is not in Idle state
  • RN2XX3_ERR_INVALID_DATA_LENGTH if payload is too large
  • RN2XX3_ERR_KEYS_NOT_INIT if keys are not configured
int rn2xx3_wait_reply(rn2xx3_t * dev, uint8_t timeout)

Waits for a reply from the LoRaWAN network.

Parameters

dev:LoRaBee device descriptor
timeout:Reply wait timeout in seconds

Return values

  • RN2XX3_REPLY_TIMEOUT when no MAC reply is received from server
  • RN2XX3_REPLY_TX_MAC_OK when MAC transmission succeeded
  • RN2XX3_REPLY_TX_MAC_ERR when MAC transmission failed
  • RN2XX3_REPLY_TX_MAC_RX when received downlink data from server
  • RN2XX3_REPLY_TX_INVALID_DATA_LEN when Application payload is too large
  • RN2XX3_REPLY_JOIN_ACCEPTED when the join procedure succeded
  • RN2XX3_REPLY_JOIN_DENIED when the join procedure failed
  • RN2XX3_REPLY_OTHER when an unknown reply is received
int rn2xx3_mac_tx(rn2xx3_t * dev, uint8_t * payload, uint8_t payload_len)

Sends data to LoRaWAN server.

Parameters

dev:RN2XX3 device descriptor
payload:Payload to transmit
payload_len:Payload length to transmit

Return values

  • RN2XX3_ERR_KEYS_NOT_INIT if the loramac params are not configured
  • RN2XX3_ERR_NO_FREE_CH if channels are busy
  • RN2XX3_ERR_SILENT if device is in Silent state
  • RN2XX3_ERR_BUSY if MAC layer is in idle state
  • RN2XX3_ERR_MAC_PAUSED if MAC layed is paused
  • RN2XX3_REPLY_TX_INVALID_DATA_LEN if payload is too large
  • RN2XX3_REPLY_TX_MAC_ERR when MAC transmission failed
  • RN2XX3_REPLY_TX_MAC_RX when received downlink data from server
  • RN2XX3_REPLY_TX_MAC_OK when MAC transmission succeeded
int rn2xx3_mac_join_network(rn2xx3_t * dev, loramac.h::loramac_join_mode_t mode)

Starts network activation procedure.

Parameters

dev:RN2XX3 device descriptor
mode:Activation procedure type

Return values

  • RN2XX3_ERR_KEYS_NOT_INIT if the loramac params are not configured
  • RN2XX3_ERR_NO_FREE_CH if channels are busy
  • RN2XX3_ERR_SILENT if device is in Silent state
  • RN2XX3_ERR_BUSY if MAC layer is in idle state
  • RN2XX3_ERR_MAC_PAUSED if MAC layed is paused
  • RN2XX3_REPLY_JOIN_ACCEPTED when the join procedure succeded
  • RN2XX3_REPLY_JOIN_DENIED when the join procedure failed
int rn2xx3_mac_save(rn2xx3_t * dev)

Saves current LoRaMAC configuration to internal EEPROM.

The configuration parameters saved are: frequency band, end device EUI, application EUI, application key, network session key, application session key, end device EUI and all channel parameters.

Parameters

dev:RN2XX3 device descriptor

Return values

  • RN2XX3_OK if all is ok
  • RN2XX3_TIMEOUT if the device didn’t reply
void rn2xx3_mac_get_deveui(rn2xx3_t * dev, uint8_t * eui)

Gets the rn2xx3 LoRaMAC device EUI.

The device EUI is an array of 8 bytes.

Parameters

dev:The rn2xx3 device descriptor
eui:The device EUI

void rn2xx3_mac_set_deveui(rn2xx3_t * dev, const uint8_t * eui)

Sets the rn2xx3 LoRaMAC device EUI.

The device EUI is an array of 8 bytes.

Parameters

dev:The rn2xx3 device descriptor
eui:The device EUI

void rn2xx3_mac_get_appeui(rn2xx3_t * dev, uint8_t * eui)

Gets the rn2xx3 LoRaMAC application EUI.

The application EUI is an array of 8 bytes.

Parameters

dev:The rn2xx3 device descriptor
eui:The application EUI

void rn2xx3_mac_set_appeui(rn2xx3_t * dev, const uint8_t * eui)

Sets the rn2xx3 LoRaMAC application EUI.

The application key is an array of 8 bytes.

Parameters

dev:The rn2xx3 device descriptor
eui:The application EUI

void rn2xx3_mac_set_appkey(rn2xx3_t * dev, const uint8_t * key)

Sets the rn2xx3 LoRaMAC application key.

The application key is an array of 16 bytes.

Parameters

dev:The rn2xx3 device descriptor
key:The application key

void rn2xx3_mac_set_appskey(rn2xx3_t * dev, const uint8_t * key)

Sets the rn2xx3 LoRaMAC application session key.

The application session key is an array of 16 bytes.

Parameters

dev:The rn2xx3 device descriptor
key:The application session key

void rn2xx3_mac_set_nwkskey(rn2xx3_t * dev, const uint8_t * key)

Sets the rn2xx3 LoRaMAC network session key.

The network session key is an array of 16 bytes.

Parameters

dev:The rn2xx3 device descriptor
key:The network session key

void rn2xx3_mac_get_devaddr(rn2xx3_t * dev, uint8_t * addr)

Gets the rn2xx3 LoRaMAC device address.

The device address is an array of 4 bytes.

Parameters

dev:The rn2xx3 device descriptor
addr:The device address

void rn2xx3_mac_set_devaddr(rn2xx3_t * dev, const uint8_t * addr)

Sets the rn2xx3 LoRaMAC device address.

The device address is an array of 4 bytes.

Parameters

dev:The rn2xx3 device descriptor
addr:The device address

loramac.h::loramac_tx_pwr_idx_t rn2xx3_mac_get_tx_power(rn2xx3_t * dev)

Gets the rn2xx3 LoRaMAC TX radio power index.

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The radio power index
void rn2xx3_mac_set_tx_power(rn2xx3_t * dev, loramac.h::loramac_tx_pwr_idx_t power)

Sets the rn2xx3 LoRaMAC transmission power index.

Parameters

dev:The rn2xx3 device descriptor
power:The TX power index

loramac.h::loramac_dr_idx_t rn2xx3_mac_get_dr(rn2xx3_t * dev)

Gets the rn2xx3 LoRaMAC datarate.

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The datarate
void rn2xx3_mac_set_dr(rn2xx3_t * dev, loramac.h::loramac_dr_idx_t dr)

Sets the rn2xx3 LoRaMAC datarate.

Parameters

dev:The rn2xx3 device descriptor
dr:The datarate

uint16_t rn2xx3_mac_get_band(rn2xx3_t * dev)

Gets the rn2xx3 LoRaMAC frequency band in operation.

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The frequency band
bool rn2xx3_mac_get_adr(rn2xx3_t * dev)

Checks if the rn2xx3 LoRaMAC adaptive datarate is enabled/disabled.

Parameters

dev:The rn2xx3 device descriptor

Return values

  • true if adaptive datarate is set, false otherwise
void rn2xx3_mac_set_adr(rn2xx3_t * dev, bool adr)

Enables/disables the rn2xx3 LoRaMAC adaptive datarate.

Parameters

dev:The rn2xx3 device descriptor
adr:The adaptive datarate mode

void rn2xx3_mac_set_battery(rn2xx3_t * dev, uint8_t battery)

Sets the rn2xx3 battery level measured by the end device.

Parameters

dev:The rn2xx3 device descriptor
battery:The battery level:
  • 0 means external power,
  • 1 means low level,
  • 254 high level,
  • 255 means the battery level couldn’t be measured by the device.

uint8_t rn2xx3_mac_get_retx(rn2xx3_t * dev)

Gets the rn2xx3 LoRaMAC uplink retransmission retries number.

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The number of uplink retransmission retries
void rn2xx3_mac_set_retx(rn2xx3_t * dev, uint8_t retx)

Sets the rn2xx3 LoRaMAC uplink retransmission retries number.

Parameters

dev:The rn2xx3 device descriptor
retx:The number of uplink retransmission retries

void rn2xx3_mac_set_linkchk_interval(rn2xx3_t * dev, uint16_t linkchk)

Sets the rn2xx3 LoRaMAC link check interval (in seconds)

Parameters

dev:The rn2xx3 device descriptor
linkchk:The link check interval in seconds

uint16_t rn2xx3_mac_get_rx1_delay(rn2xx3_t * dev)

Gets the rn2xx3 LoRaMAC interval delay before the first reception window (in ms)

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The delay in ms
void rn2xx3_mac_set_rx1_delay(rn2xx3_t * dev, uint16_t rx1)

Sets the rn2xx3 LoRaMAC interval delay before the first reception window (in ms)

Parameters

dev:The rn2xx3 device descriptor
rx1:The delay in ms

uint16_t rn2xx3_mac_get_rx2_delay(rn2xx3_t * dev)

Gets the rn2xx3 LoRaMAC interval delay before the second reception window (in ms)

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The delay in ms
bool rn2xx3_mac_get_ar(rn2xx3_t * dev)

Checks the rn2xx3 LoRaMAC automatic reply state.

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The automatic reply state
void rn2xx3_mac_set_ar(rn2xx3_t * dev, bool ar)

Enables/disables LoRaMAC rn2xx3 MAC automatic reply state.

Parameters

dev:The rn2xx3 device descriptor
ar:The automatic reply state

loramac.h::loramac_dr_idx_t rn2xx3_mac_get_rx2_dr(rn2xx3_t * dev)

Gets the rn2xx3 LoRaMAC datarate used for second receive window.

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The datarate during second receive window
void rn2xx3_mac_set_rx2_dr(rn2xx3_t * dev, loramac.h::loramac_dr_idx_t dr)

Sets the rn2xx3 LoRaMAC datarate used for second receive window.

Parameters

dev:The rn2xx3 device descriptor
dr:The datarate during second receive window

uint32_t rn2xx3_mac_get_rx2_freq(rn2xx3_t * dev)

Gets the rn2xx3 LoRaMAC frequency used during second receive window (in Hz)

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The frequency during second receive window
void rn2xx3_mac_set_rx2_freq(rn2xx3_t * dev, uint32_t freq)

Sets the rn2xx3 LoRaMAC frequency used during second receive window (in Hz)

Parameters

dev:The rn2xx3 device descriptor
freq:The frequency during second receive window

uint8_t rn2xx3_mac_get_tx_port(rn2xx3_t * dev)

Gets the rn2xx3 LoRaMAC TX port.

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The TX port
void rn2xx3_mac_set_tx_port(rn2xx3_t * dev, uint8_t port)

Sets the rn2xx3 LoRaMAC TX port.

Parameters

dev:The rn2xx3 device descriptor
port:The TX port (from 1 to 223)

loramac.h::loramac_tx_mode_t rn2xx3_mac_get_tx_mode(rn2xx3_t * dev)

Gets the rn2xx3 LoRaMAC TX mode.

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The TX mode, either confirmable or unconfirmable
void rn2xx3_mac_set_tx_mode(rn2xx3_t * dev, loramac.h::loramac_tx_mode_t mode)

Sets the rn2xx3 LoRaMAC TX mode.

Parameters

dev:The rn2xx3 device descriptor
mode:The TX mode, either confirmable or unconfirmable

uint8_t rn2xx3_mac_get_rx_port(rn2xx3_t * dev)

Parses the response buffer to get the LoRaWAN RX port.

Parameters

dev:The rn2xx3 device descriptor

Return values

  • The RX port (between 1 and 223)
void rn2xx3_sys_set_sleep_duration(rn2xx3_t * dev, uint32_t sleep)

Sets the rn2xx3 sleep mode duration (in ms)

Parameters

dev:The rn2xx3 device descriptor
sleep:The sleep mode duration (ms)

RN2XX3_MAX_BUF

Maximum length of an exchanged messages with commands. 

1
(40U)
RN2XX3_RX_MAX_BUF

Maximum length of an RX message. 

1
(250U)

LoRaMAC payload can be up to 250 bytes.

RN2XX3_REPLY_DELAY_TIMEOUT

Maximum delay in second to receive a reply from server. 

1
(60U)
RN2XX3_SLEEP_MIN

Minimum sleep duration (in ms) 

1
(100U)
RN2XX3_DEFAULT_SLEEP

Default sleep duration (in ms) 

1
(5000U)
struct loramac_settings_t

LoRaMAC communication settings.

uint32_t rx2_freq

Center frequency used for second receive window.

loramac.h::loramac_dr_idx_t rx2_dr

Datarate used for second receive window.

uint8_t tx_port

Application TX port (between 1 and 223)

loramac.h::loramac_tx_mode_t tx_mode

TX mode, either confirmable of unconfirmable.

uint8_t rx_port

RX port (between 1 and 223)

struct rn2xx3_params_t

Configuration parameters for RN2483/RN2903 devices.

uart.h::uart_t uart

UART interfaced the device is connected to.

uint32_t baudrate

baudrate to use

gpio.h::gpio_t pin_reset

GPIO pin that is connected to the STATUS pin set to GPIO_UNDEF if not used.

struct rn2xx3_t

RN2483/RN2903 device descriptor.

netdev.h::netdev_t netdev

Netdev parent struct.

rn2xx3_params_t p

configuration parameters

loramac_settings_t loramac

loramac communication settings

char cmd_buf()

command to send data buffer

mutex_t cmd_lock

mutex to allow only one command at a time

uint8_t int_state

current state of the device

mutex_t resp_lock

mutex for waiting for command response

char resp_buf()

command response data buffer

uint16_t resp_size

counter for received char in response

uint8_t resp_done

check if response has completed

char rx_tmp_buf()

Temporary RX buffer used to convert 2 hex characters in one byte on the fly.

uint8_t rx_buf()

RX data buffer.

uint16_t rx_size

counter for received char in RX

xtimer.h::xtimer_t sleep_timer

Timer used to count module sleep time.

uint32_t sleep

module sleep duration