Semtech SX1272 and SX1276 radios driver

Driver for Semtech SX1272 and SX1276 radios. More...

Detailed Description

Driver for Semtech SX1272 and SX1276 radios.

This module contains the driver for radio devices of the Semtech SX127x series (SX1272 and SX1276). Only LoRa long range modem is supported at the moment.

SX127x modules are designed to be used in the ISM radio frequency (RF) band. This RF band depends on different regional regulations worldwide. Be careful to configure the device to use a RF frequency allowed in your region. Here is the list of allowed frequencies for your region (see LoRaWAN regional parameters document available online):

For more information on Semtech SX1272 and SX1276 modules see:

Files

file  sx127x.h
 Public interface for SX127X driver.
 
file  sx127x_internal.h
 Semtech SX127X internal functions.
 
file  sx127x_netdev.h
 Netdev driver definitions for SX127X driver.
 
file  sx127x_registers.h
 SX127X registers.
 

Data Structures

struct  sx127x_lora_settings_t
 LoRa configuration structure. More...
 
struct  sx127x_radio_settings_t
 Radio settings. More...
 
struct  sx127x_internal_t
 SX127X internal data. More...
 
struct  sx127x_params_t
 SX127X hardware and global parameters. More...
 
struct  sx127x_t
 SX127X device descriptor. More...
 

Typedefs

typedef uint8_t sx127x_flags_t
 SX127X IRQ flags.
 
typedef void() sx127x_dio_irq_handler_t(sx127x_t *dev)
 Hardware IO IRQ callback function definition.
 

Enumerations

enum  { SX127X_INIT_OK = 0, SX127X_ERR_SPI, SX127X_ERR_TEST_FAILED, SX127X_ERR_THREAD }
 SX127X initialization result. More...
 
enum  { SX127X_MODEM_FSK = 0, SX127X_MODEM_LORA }
 Radio driver supported modems. More...
 
enum  { SX127X_RF_IDLE = 0, SX127X_RF_RX_RUNNING, SX127X_RF_TX_RUNNING, SX127X_RF_CAD }
 Radio driver internal state machine states definition. More...
 
enum  {
  SX127X_RX_DONE = 0, SX127X_TX_DONE, SX127X_RX_TIMEOUT, SX127X_TX_TIMEOUT,
  SX127X_RX_ERROR_CRC, SX127X_FHSS_CHANGE_CHANNEL, SX127X_CAD_DONE
}
 Event types. More...
 

Functions

void sx127x_setup (sx127x_t *dev, const sx127x_params_t *params)
 Setup the SX127X. More...
 
void sx127x_reset (const sx127x_t *dev)
 Resets the SX127X. More...
 
int sx127x_init (sx127x_t *dev)
 Initializes the transceiver. More...
 
void sx127x_init_radio_settings (sx127x_t *dev)
 Initialize radio settings with default values. More...
 
uint32_t sx127x_random (sx127x_t *dev)
 Generates 32 bits random value based on the RSSI readings. More...
 
void sx127x_start_cad (sx127x_t *dev)
 Start a channel activity detection. More...
 
uint8_t sx127x_get_state (const sx127x_t *dev)
 Gets current state of transceiver. More...
 
void sx127x_set_state (sx127x_t *dev, uint8_t state)
 Sets current state of transceiver. More...
 
void sx127x_set_modem (sx127x_t *dev, uint8_t modem)
 Configures the radio with the given modem. More...
 
uint8_t sx127x_get_syncword (const sx127x_t *dev)
 Gets the synchronization word. More...
 
void sx127x_set_syncword (sx127x_t *dev, uint8_t syncword)
 Sets the synchronization word. More...
 
uint32_t sx127x_get_channel (const sx127x_t *dev)
 Gets the channel RF frequency. More...
 
void sx127x_set_channel (sx127x_t *dev, uint32_t freq)
 Sets the channel RF frequency. More...
 
uint32_t sx127x_get_time_on_air (const sx127x_t *dev, uint8_t pkt_len)
 Computes the packet time on air in milliseconds. More...
 
void sx127x_set_sleep (sx127x_t *dev)
 Sets the radio in sleep mode. More...
 
void sx127x_set_standby (sx127x_t *dev)
 Sets the radio in stand-by mode. More...
 
void sx127x_set_rx (sx127x_t *dev)
 Sets the radio in reception mode. More...
 
void sx127x_set_tx (sx127x_t *dev)
 Sets the radio in transmission mode. More...
 
uint8_t sx127x_get_max_payload_len (const sx127x_t *dev)
 Gets the maximum payload length. More...
 
void sx127x_set_max_payload_len (const sx127x_t *dev, uint8_t maxlen)
 Sets the maximum payload length. More...
 
uint8_t sx127x_get_op_mode (const sx127x_t *dev)
 Gets the SX127X operating mode. More...
 
void sx127x_set_op_mode (const sx127x_t *dev, uint8_t op_mode)
 Sets the SX127X operating mode. More...
 
uint8_t sx127x_get_bandwidth (const sx127x_t *dev)
 Gets the SX127X bandwidth. More...
 
void sx127x_set_bandwidth (sx127x_t *dev, uint8_t bandwidth)
 Sets the SX127X bandwidth. More...
 
uint8_t sx127x_get_spreading_factor (const sx127x_t *dev)
 Gets the SX127X LoRa spreading factor. More...
 
void sx127x_set_spreading_factor (sx127x_t *dev, uint8_t sf)
 Sets the SX127X LoRa spreading factor. More...
 
uint8_t sx127x_get_coding_rate (const sx127x_t *dev)
 Gets the SX127X LoRa coding rate. More...
 
void sx127x_set_coding_rate (sx127x_t *dev, uint8_t coderate)
 Sets the SX127X LoRa coding rate. More...
 
bool sx127x_get_rx_single (const sx127x_t *dev)
 Checks if the SX127X LoRa RX single mode is enabled/disabled. More...
 
void sx127x_set_rx_single (sx127x_t *dev, bool single)
 Enable/disable the SX127X LoRa RX single mode. More...
 
bool sx127x_get_crc (const sx127x_t *dev)
 Checks if the SX127X CRC verification mode is enabled. More...
 
void sx127x_set_crc (sx127x_t *dev, bool crc)
 Enable/Disable the SX127X CRC verification mode. More...
 
uint8_t sx127x_get_hop_period (const sx127x_t *dev)
 Gets the SX127X frequency hopping period. More...
 
void sx127x_set_hop_period (sx127x_t *dev, uint8_t hop_period)
 Sets the SX127X frequency hopping period. More...
 
bool sx127x_get_fixed_header_len_mode (const sx127x_t *dev)
 Gets the SX127X LoRa fixed header length mode. More...
 
void sx127x_set_fixed_header_len_mode (sx127x_t *dev, bool mode)
 Sets the SX127X to fixed header length mode (explicit mode) More...
 
uint8_t sx127x_get_payload_length (const sx127x_t *dev)
 Gets the SX127X payload length. More...
 
void sx127x_set_payload_length (sx127x_t *dev, uint8_t len)
 Sets the SX127X payload length. More...
 
uint8_t sx127x_get_tx_power (const sx127x_t *dev)
 Gets the SX127X TX radio power. More...
 
void sx127x_set_tx_power (sx127x_t *dev, int8_t power)
 Sets the SX127X transmission power. More...
 
uint16_t sx127x_get_preamble_length (const sx127x_t *dev)
 Gets the SX127X preamble length. More...
 
void sx127x_set_preamble_length (sx127x_t *dev, uint16_t preamble)
 Sets the SX127X LoRa preamble length. More...
 
void sx127x_set_symbol_timeout (sx127x_t *dev, uint16_t timeout)
 Sets the SX127X LoRa symbol timeout. More...
 
void sx127x_set_rx_timeout (sx127x_t *dev, uint32_t timeout)
 Sets the SX127X RX timeout. More...
 
void sx127x_set_tx_timeout (sx127x_t *dev, uint32_t timeout)
 Sets the SX127X TX timeout. More...
 
bool sx127x_get_iq_invert (const sx127x_t *dev)
 Checks if the SX127X LoRa inverted IQ mode is enabled/disabled. More...
 
void sx127x_set_iq_invert (sx127x_t *dev, bool iq_invert)
 Enable/disable the SX127X LoRa IQ inverted mode. More...
 
void sx127x_set_freq_hop (sx127x_t *dev, bool freq_hop_on)
 Sets the SX127X LoRa frequency hopping mode. More...
 

SX127X device default configuration

#define SX127X_MODEM_DEFAULT   (SX127X_MODEM_LORA)
 Use LoRa as default modem.
 
#define SX127X_CHANNEL_DEFAULT   (868300000UL)
 Default channel frequency, 868.3MHz (Europe)
 
#define SX127X_HF_CHANNEL_DEFAULT   (868000000UL)
 Use to calibrate RX chain for LF and HF bands.
 
#define SX127X_RF_MID_BAND_THRESH   (525000000UL)
 Mid-band threshold.
 
#define SX127X_XTAL_FREQ   (32000000UL)
 Internal oscillator frequency, 32MHz.
 
#define SX127X_RADIO_WAKEUP_TIME   (1000U)
 In microseconds [us].
 
#define SX127X_TX_TIMEOUT_DEFAULT   (1000U * 1000U * 30UL)
 TX timeout, 30s.
 
#define SX127X_RX_SINGLE   (false)
 Single byte receive mode => continuous by default.
 
#define SX127X_RX_BUFFER_SIZE   (256)
 RX buffer size.
 
#define SX127X_RADIO_TX_POWER   (14U)
 Radio power in dBm.
 
#define SX1272_DEFAULT_PASELECT   (1U)
 Default PA selection config (1: RFO, 0: PABOOST) More...
 
#define SX127X_EVENT_HANDLER_STACK_SIZE   (2048U)
 Stack size event handler.
 
#define SX127X_IRQ_DIO0   (1<<0)
 DIO0 IRQ.
 
#define SX127X_IRQ_DIO1   (1<<1)
 DIO1 IRQ.
 
#define SX127X_IRQ_DIO2   (1<<2)
 DIO2 IRQ.
 
#define SX127X_IRQ_DIO3   (1<<3)
 DIO3 IRQ.
 
#define SX127X_IRQ_DIO4   (1<<4)
 DIO4 IRQ.
 
#define SX127X_IRQ_DIO5   (1<<5)
 DIO5 IRQ.
 

SX127X device descriptor boolean flags

#define SX127X_LOW_DATARATE_OPTIMIZE_FLAG   (1 << 0)
 
#define SX127X_ENABLE_FIXED_HEADER_LENGTH_FLAG   (1 << 1)
 
#define SX127X_ENABLE_CRC_FLAG   (1 << 2)
 
#define SX127X_CHANNEL_HOPPING_FLAG   (1 << 3)
 
#define SX127X_IQ_INVERTED_FLAG   (1 << 4)
 
#define SX127X_RX_CONTINUOUS_FLAG   (1 << 5)
 

Macro Definition Documentation

◆ SX1272_DEFAULT_PASELECT

#define SX1272_DEFAULT_PASELECT   (1U)

Default PA selection config (1: RFO, 0: PABOOST)

This depends on the module configuration.

Definition at line 94 of file sx127x.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

SX127X initialization result.

Enumerator
SX127X_INIT_OK 

Initialization was successful.

SX127X_ERR_SPI 

Failed to initialize SPI bus or CS line.

SX127X_ERR_TEST_FAILED 

SX127X testing failed during initialization (check chip)

SX127X_ERR_THREAD 

Unable to create DIO handling thread (check amount of free memory)

Definition at line 109 of file sx127x.h.

◆ anonymous enum

anonymous enum

Radio driver supported modems.

Enumerator
SX127X_MODEM_FSK 

FSK modem driver.

SX127X_MODEM_LORA 

LoRa modem driver.

Definition at line 119 of file sx127x.h.

◆ anonymous enum

anonymous enum

Radio driver internal state machine states definition.

Enumerator
SX127X_RF_IDLE 

Idle state.

SX127X_RF_RX_RUNNING 

Sending state.

SX127X_RF_TX_RUNNING 

Receiving state.

SX127X_RF_CAD 

Channel activity detection state.

Definition at line 127 of file sx127x.h.

◆ anonymous enum

anonymous enum

Event types.

Enumerator
SX127X_RX_DONE 

Receiving complete.

SX127X_TX_DONE 

Sending complete.

SX127X_RX_TIMEOUT 

Receiving timeout.

SX127X_TX_TIMEOUT 

Sending timeout.

SX127X_RX_ERROR_CRC 

Receiving CRC error.

SX127X_FHSS_CHANGE_CHANNEL 

Channel change.

SX127X_CAD_DONE 

Channel activity detection complete.

Definition at line 137 of file sx127x.h.

Function Documentation

◆ sx127x_get_bandwidth()

uint8_t sx127x_get_bandwidth ( const sx127x_t dev)

Gets the SX127X bandwidth.

Parameters
[in]devThe sx127x device descriptor
Returns
the bandwidth

◆ sx127x_get_channel()

uint32_t sx127x_get_channel ( const sx127x_t dev)

Gets the channel RF frequency.

Parameters
[in]devThe sx127x device descriptor
Returns
The channel frequency

◆ sx127x_get_coding_rate()

uint8_t sx127x_get_coding_rate ( const sx127x_t dev)

Gets the SX127X LoRa coding rate.

Parameters
[in]devThe sx127x device descriptor
Returns
the current LoRa coding rate

◆ sx127x_get_crc()

bool sx127x_get_crc ( const sx127x_t dev)

Checks if the SX127X CRC verification mode is enabled.

Parameters
[in]devThe sx127x device descriptor
Returns
the LoRa single mode

◆ sx127x_get_fixed_header_len_mode()

bool sx127x_get_fixed_header_len_mode ( const sx127x_t dev)

Gets the SX127X LoRa fixed header length mode.

Parameters
[in]devThe sx127x device descriptor
Returns
the LoRa implicit mode

◆ sx127x_get_hop_period()

uint8_t sx127x_get_hop_period ( const sx127x_t dev)

Gets the SX127X frequency hopping period.

Parameters
[in]devThe sx127x device descriptor
Returns
the frequency hopping period

◆ sx127x_get_iq_invert()

bool sx127x_get_iq_invert ( const sx127x_t dev)

Checks if the SX127X LoRa inverted IQ mode is enabled/disabled.

Parameters
[in]devThe sx127x device descriptor
Returns
the LoRa IQ inverted mode

◆ sx127x_get_max_payload_len()

uint8_t sx127x_get_max_payload_len ( const sx127x_t dev)

Gets the maximum payload length.

Parameters
[in]devThe sx127x device descriptor
Returns
The maximum payload length

◆ sx127x_get_op_mode()

uint8_t sx127x_get_op_mode ( const sx127x_t dev)

Gets the SX127X operating mode.

Parameters
[in]devThe sx127x device descriptor
Returns
The actual operating mode

◆ sx127x_get_payload_length()

uint8_t sx127x_get_payload_length ( const sx127x_t dev)

Gets the SX127X payload length.

Parameters
[in]devThe sx127x device descriptor
Returns
the payload length

◆ sx127x_get_preamble_length()

uint16_t sx127x_get_preamble_length ( const sx127x_t dev)

Gets the SX127X preamble length.

Parameters
[in]devThe sx127x device descriptor
Returns
the preamble length

◆ sx127x_get_rx_single()

bool sx127x_get_rx_single ( const sx127x_t dev)

Checks if the SX127X LoRa RX single mode is enabled/disabled.

Parameters
[in]devThe sx127x device descriptor
Returns
the LoRa single mode

◆ sx127x_get_spreading_factor()

uint8_t sx127x_get_spreading_factor ( const sx127x_t dev)

Gets the SX127X LoRa spreading factor.

Parameters
[in]devThe sx127x device descriptor
Returns
the spreading factor

◆ sx127x_get_state()

uint8_t sx127x_get_state ( const sx127x_t dev)

Gets current state of transceiver.

Parameters
[in]devThe sx127x device descriptor
Returns
radio state [RF_IDLE, RF_RX_RUNNING, RF_TX_RUNNING]

◆ sx127x_get_syncword()

uint8_t sx127x_get_syncword ( const sx127x_t dev)

Gets the synchronization word.

Parameters
[in]devThe sx127x device descriptor
Returns
The synchronization word

◆ sx127x_get_time_on_air()

uint32_t sx127x_get_time_on_air ( const sx127x_t dev,
uint8_t  pkt_len 
)

Computes the packet time on air in milliseconds.

Precondition
Can only be called if sx127x_init_radio_settings has already been called.
Parameters
[in]devThe sx127x device descriptor
[in]pkt_lenThe received packet payload length
Returns
computed air time (ms) for the given packet payload length

◆ sx127x_get_tx_power()

uint8_t sx127x_get_tx_power ( const sx127x_t dev)

Gets the SX127X TX radio power.

Parameters
[in]devThe sx127x device descriptor
Returns
the radio power

◆ sx127x_init()

int sx127x_init ( sx127x_t dev)

Initializes the transceiver.

Parameters
[in]devThe sx127x device descriptor
Returns
result of initialization

◆ sx127x_init_radio_settings()

void sx127x_init_radio_settings ( sx127x_t dev)

Initialize radio settings with default values.

Parameters
[in]devThe sx127x device pointer

◆ sx127x_random()

uint32_t sx127x_random ( sx127x_t dev)

Generates 32 bits random value based on the RSSI readings.

Attention
This function sets the radio in LoRa mode and disables all interrupts from it. After calling this function either sx127x_set_rx_config or sx127x_set_tx_config functions must be called.
Parameters
[in]devThe sx127x device structure pointer
Returns
random 32 bits value

◆ sx127x_reset()

void sx127x_reset ( const sx127x_t dev)

Resets the SX127X.

Parameters
[in]devThe sx127x device descriptor

◆ sx127x_set_bandwidth()

void sx127x_set_bandwidth ( sx127x_t dev,
uint8_t  bandwidth 
)

Sets the SX127X bandwidth.

Parameters
[in]devThe sx127x device descriptor
[in]bandwidthThe new bandwidth

◆ sx127x_set_channel()

void sx127x_set_channel ( sx127x_t dev,
uint32_t  freq 
)

Sets the channel RF frequency.

Parameters
[in]devThe sx127x device descriptor
[in]freqChannel RF frequency

◆ sx127x_set_coding_rate()

void sx127x_set_coding_rate ( sx127x_t dev,
uint8_t  coderate 
)

Sets the SX127X LoRa coding rate.

Parameters
[in]devThe sx127x device descriptor
[in]coderateThe LoRa coding rate

◆ sx127x_set_crc()

void sx127x_set_crc ( sx127x_t dev,
bool  crc 
)

Enable/Disable the SX127X CRC verification mode.

Parameters
[in]devThe sx127x device descriptor
[in]crcThe CRC check mode

◆ sx127x_set_fixed_header_len_mode()

void sx127x_set_fixed_header_len_mode ( sx127x_t dev,
bool  mode 
)

Sets the SX127X to fixed header length mode (explicit mode)

Parameters
[in]devThe sx127x device descriptor
[in]modeThe header mode

◆ sx127x_set_freq_hop()

void sx127x_set_freq_hop ( sx127x_t dev,
bool  freq_hop_on 
)

Sets the SX127X LoRa frequency hopping mode.

Parameters
[in]devThe sx127x device descriptor
[in]freq_hop_onThe LoRa frequency hopping mode

◆ sx127x_set_hop_period()

void sx127x_set_hop_period ( sx127x_t dev,
uint8_t  hop_period 
)

Sets the SX127X frequency hopping period.

Parameters
[in]devThe sx127x device descriptor
[in]hop_periodThe frequency hopping period

◆ sx127x_set_iq_invert()

void sx127x_set_iq_invert ( sx127x_t dev,
bool  iq_invert 
)

Enable/disable the SX127X LoRa IQ inverted mode.

Parameters
[in]devThe sx127x device descriptor
[in]iq_invertThe LoRa IQ inverted mode

◆ sx127x_set_max_payload_len()

void sx127x_set_max_payload_len ( const sx127x_t dev,
uint8_t  maxlen 
)

Sets the maximum payload length.

Parameters
[in]devThe sx127x device descriptor
[in]maxlenMaximum payload length in bytes

◆ sx127x_set_modem()

void sx127x_set_modem ( sx127x_t dev,
uint8_t  modem 
)

Configures the radio with the given modem.

Parameters
[in]devThe sx127x device descriptor
[in]modemModem to be used [0: FSK, 1: LoRa]

◆ sx127x_set_op_mode()

void sx127x_set_op_mode ( const sx127x_t dev,
uint8_t  op_mode 
)

Sets the SX127X operating mode.

Parameters
[in]devThe sx127x device descriptor
[in]op_modeThe new operating mode

◆ sx127x_set_payload_length()

void sx127x_set_payload_length ( sx127x_t dev,
uint8_t  len 
)

Sets the SX127X payload length.

Parameters
[in]devThe sx127x device descriptor
[in]lenThe payload len

◆ sx127x_set_preamble_length()

void sx127x_set_preamble_length ( sx127x_t dev,
uint16_t  preamble 
)

Sets the SX127X LoRa preamble length.

Parameters
[in]devThe sx127x device descriptor
[in]preambleThe LoRa preamble length

◆ sx127x_set_rx()

void sx127x_set_rx ( sx127x_t dev)

Sets the radio in reception mode.

Parameters
[in]devThe sx127x device descriptor

◆ sx127x_set_rx_single()

void sx127x_set_rx_single ( sx127x_t dev,
bool  single 
)

Enable/disable the SX127X LoRa RX single mode.

Parameters
[in]devThe sx127x device descriptor
[in]singleThe LoRa RX single mode

◆ sx127x_set_rx_timeout()

void sx127x_set_rx_timeout ( sx127x_t dev,
uint32_t  timeout 
)

Sets the SX127X RX timeout.

Parameters
[in]devThe sx127x device descriptor
[in]timeoutThe RX timeout

◆ sx127x_set_sleep()

void sx127x_set_sleep ( sx127x_t dev)

Sets the radio in sleep mode.

Parameters
[in]devThe sx127x device descriptor

◆ sx127x_set_spreading_factor()

void sx127x_set_spreading_factor ( sx127x_t dev,
uint8_t  sf 
)

Sets the SX127X LoRa spreading factor.

Parameters
[in]devThe sx127x device descriptor
[in]sfThe spreading factor

◆ sx127x_set_standby()

void sx127x_set_standby ( sx127x_t dev)

Sets the radio in stand-by mode.

Parameters
[in]devThe sx127x device descriptor

◆ sx127x_set_state()

void sx127x_set_state ( sx127x_t dev,
uint8_t  state 
)

Sets current state of transceiver.

Parameters
[in]devThe sx127x device descriptor
[in]stateThe new radio state
Returns
radio state [RF_IDLE, RF_RX_RUNNING, RF_TX_RUNNING]

◆ sx127x_set_symbol_timeout()

void sx127x_set_symbol_timeout ( sx127x_t dev,
uint16_t  timeout 
)

Sets the SX127X LoRa symbol timeout.

Parameters
[in]devThe sx127x device descriptor
[in]timeoutThe LoRa symbol timeout

◆ sx127x_set_syncword()

void sx127x_set_syncword ( sx127x_t dev,
uint8_t  syncword 
)

Sets the synchronization word.

Parameters
[in]devThe sx127x device descriptor
[in]syncwordThe synchronization word

◆ sx127x_set_tx()

void sx127x_set_tx ( sx127x_t dev)

Sets the radio in transmission mode.

Parameters
[in]devThe sx127x device descriptor

◆ sx127x_set_tx_power()

void sx127x_set_tx_power ( sx127x_t dev,
int8_t  power 
)

Sets the SX127X transmission power.

Parameters
[in]devThe sx127x device descriptor
[in]powerThe TX power

◆ sx127x_set_tx_timeout()

void sx127x_set_tx_timeout ( sx127x_t dev,
uint32_t  timeout 
)

Sets the SX127X TX timeout.

Parameters
[in]devThe sx127x device descriptor
[in]timeoutThe TX timeout

◆ sx127x_setup()

void sx127x_setup ( sx127x_t dev,
const sx127x_params_t params 
)

Setup the SX127X.

Parameters
[in]devDevice descriptor
[in]paramsParameters for device initialization

◆ sx127x_start_cad()

void sx127x_start_cad ( sx127x_t dev)

Start a channel activity detection.

Parameters
[in]devThe sx127x device descriptor