Semtech SX1272 and SX1276 radios driver

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):

  • Europe has 2 allowed bands (ETSI):
    • EU863-870
    • EU433 (from 433.175MHZ to 434.665MHZ exactly)
  • US is US902-928
  • China has 2 allowed bands:
    • CN779-787 (from 779.5MHz to 786.5MHz exactly)
    • CN470-510 (from 470.3MHz to 509.7MHz exactly)
  • Australia is AU915-928
  • South asia, AS923:
    • Bruneï [923-925 MHz]
    • Cambodia [923-925 MHz]
    • Hong Kong [920-925 MHz]
    • Indonesia [923-925 MHz]
    • Japan [920-928 MHz]
    • Laos [923-925 MHz]
    • New Zealand [915-928 MHz]
    • Singapore [920-925 MHz]
    • Taiwan [922-928 MHz]
    • Thailand [920-925 MHz]
    • Vietnam [920-925 MHz]
  • South Korea: KR920-923 (from 920.9MHz to 923.3MHz exactly)

For more information on Semtech SX1272 and SX1276 modules see:

SX127X_MODEM_DEFAULT

Use LoRa as default modem. 

1
(SX127X_MODEM_LORA)
SX127X_CHANNEL_DEFAULT

Default channel frequency, 868.3MHz (Europe) 

1
(868300000UL)
SX127X_HF_CHANNEL_DEFAULT

Use to calibrate RX chain for LF and HF bands. 

1
(868000000UL)
SX127X_RF_MID_BAND_THRESH

Mid-band threshold. 

1
(525000000UL)
SX127X_XTAL_FREQ

Internal oscillator frequency, 32MHz. 

1
(32000000UL)
SX127X_RADIO_WAKEUP_TIME

In microseconds [us]. 

1
(1000U)
SX127X_TX_TIMEOUT_DEFAULT

TX timeout, 30s. 

1
(1000U * 1000U * 30UL)
SX127X_RX_SINGLE

Single byte receive mode => continuous by default. 

1
(false)
SX127X_RX_BUFFER_SIZE

RX buffer size. 

1
(256)
SX127X_RADIO_TX_POWER

Radio power in dBm. 

1
(14U)
SX127X_EVENT_HANDLER_STACK_SIZE

Stack size event handler. 

1
(2048U)
SX127X_IRQ_DIO0

DIO0 IRQ. 

1
(1<<0)
SX127X_IRQ_DIO1

DIO1 IRQ. 

1
(1<<1)
SX127X_IRQ_DIO2

DIO2 IRQ. 

1
(1<<2)
SX127X_IRQ_DIO3

DIO3 IRQ. 

1
(1<<3)
SX127X_IRQ_DIO4

DIO4 IRQ. 

1
(1<<4)
SX127X_IRQ_DIO5

DIO5 IRQ. 

1
(1<<5)
SX127X_LOW_DATARATE_OPTIMIZE_FLAG
1
(1 << 0)
SX127X_ENABLE_FIXED_HEADER_LENGTH_FLAG
1
(1 << 1)
SX127X_ENABLE_CRC_FLAG
1
(1 << 2)
SX127X_CHANNEL_HOPPING_FLAG
1
(1 << 3)
SX127X_IQ_INVERTED_FLAG
1
(1 << 4)
SX127X_RX_CONTINUOUS_FLAG
1
(1 << 5)
enum @160
SX127X_INIT_OK = 0
Initialization was successful.
SX127X_ERR_SPI
Failed to initialize SPI bus or CS line.
SX127X_ERR_GPIOS
Failed to initialize GPIOs.
SX127X_ERR_NODEV
No valid device version found.
enum @161
SX127X_MODEM_FSK = 0
FSK modem driver.
SX127X_MODEM_LORA
LoRa modem driver.
enum @162
SX127X_RF_IDLE = 0
Idle state.
SX127X_RF_RX_RUNNING
Sending state.
SX127X_RF_TX_RUNNING
Receiving state.
SX127X_RF_CAD
Channel activity detection state.
enum @163
SX127X_RX_DONE = 0
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.
enum @164
SX127X_PA_RFO = 0
RFO HF or RFO LF.
SX127X_PA_BOOST
Power amplifier boost (high power)
uint8_t sx127x_flags_t

SX127X IRQ flags.

void() sx127x_dio_irq_handler_t()

Hardware IO IRQ callback function definition.

void sx127x_setup(sx127x_t * dev, const sx127x_params_t * params)

Setup the SX127X.

Parameters

dev:Device descriptor
params:Parameters for device initialization

int sx127x_reset(const sx127x_t * dev)

Resets the SX127X.

Parameters

dev:The sx127x device descriptor

int sx127x_init(sx127x_t * dev)

Initializes the transceiver.

Parameters

dev:The sx127x device descriptor

Return values

  • result of initialization
void sx127x_init_radio_settings(sx127x_t * dev)

Initialize radio settings with default values.

Parameters

dev:The sx127x device pointer

uint32_t sx127x_random(sx127x_t * dev)

Generates 32 bits random value based on the RSSI readings.

Parameters

dev:The sx127x device structure pointer

Return values

  • random 32 bits value
void sx127x_start_cad(sx127x_t * dev)

Start a channel activity detection.

Parameters

dev:The sx127x device descriptor

bool sx127x_is_channel_free(sx127x_t * dev, uint32_t freq, int16_t rssi_threshold)

Checks that channel is free with specified RSSI threshold.

Parameters

dev:The sx127x device structure pointer
freq:channel RF frequency
rssi_threshold:RSSI threshold

Return values

  • true if channel is free, false otherwise
int16_t sx127x_read_rssi(const sx127x_t * dev)

Reads the current RSSI value.

Parameters

dev:The sx127x device structure pointer

Return values

  • the current value of RSSI (in dBm)
uint8_t sx127x_get_state(const sx127x_t * dev)

Gets current state of transceiver.

Parameters

dev:The sx127x device descriptor

Return values

  • radio state [RF_IDLE, RF_RX_RUNNING, RF_TX_RUNNING]
void sx127x_set_state(sx127x_t * dev, uint8_t state)

Sets current state of transceiver.

Parameters

dev:The sx127x device descriptor
state:The new radio state

Return values

  • radio state [RF_IDLE, RF_RX_RUNNING, RF_TX_RUNNING]
void sx127x_set_modem(sx127x_t * dev, uint8_t modem)

Configures the radio with the given modem.

Parameters

dev:The sx127x device descriptor
modem:Modem to be used [0: FSK, 1: LoRa]

uint8_t sx127x_get_syncword(const sx127x_t * dev)

Gets the synchronization word.

Parameters

dev:The sx127x device descriptor

Return values

  • The synchronization word
void sx127x_set_syncword(sx127x_t * dev, uint8_t syncword)

Sets the synchronization word.

Parameters

dev:The sx127x device descriptor
syncword:The synchronization word

uint32_t sx127x_get_channel(const sx127x_t * dev)

Gets the channel RF frequency.

Parameters

dev:The sx127x device descriptor

Return values

  • The channel frequency
void sx127x_set_channel(sx127x_t * dev, uint32_t freq)

Sets the channel RF frequency.

Parameters

dev:The sx127x device descriptor
freq:Channel RF frequency

uint32_t sx127x_get_time_on_air(const sx127x_t * dev, uint8_t pkt_len)

Computes the packet time on air in milliseconds.

Parameters

dev:The sx127x device descriptor
pkt_len:The received packet payload length

Return values

  • computed air time (ms) for the given packet payload length
void sx127x_set_sleep(sx127x_t * dev)

Sets the radio in sleep mode.

Parameters

dev:The sx127x device descriptor

void sx127x_set_standby(sx127x_t * dev)

Sets the radio in stand-by mode.

Parameters

dev:The sx127x device descriptor

void sx127x_set_rx(sx127x_t * dev)

Sets the radio in reception mode.

Parameters

dev:The sx127x device descriptor

void sx127x_set_tx(sx127x_t * dev)

Sets the radio in transmission mode.

Parameters

dev:The sx127x device descriptor

uint8_t sx127x_get_max_payload_len(const sx127x_t * dev)

Gets the maximum payload length.

Parameters

dev:The sx127x device descriptor

Return values

  • The maximum payload length
void sx127x_set_max_payload_len(const sx127x_t * dev, uint8_t maxlen)

Sets the maximum payload length.

Parameters

dev:The sx127x device descriptor
maxlen:Maximum payload length in bytes

uint8_t sx127x_get_op_mode(const sx127x_t * dev)

Gets the SX127X operating mode.

Parameters

dev:The sx127x device descriptor

Return values

  • The actual operating mode
void sx127x_set_op_mode(const sx127x_t * dev, uint8_t op_mode)

Sets the SX127X operating mode.

Parameters

dev:The sx127x device descriptor
op_mode:The new operating mode

uint8_t sx127x_get_bandwidth(const sx127x_t * dev)

Gets the SX127X bandwidth.

Parameters

dev:The sx127x device descriptor

Return values

  • the bandwidth
void sx127x_set_bandwidth(sx127x_t * dev, uint8_t bandwidth)

Sets the SX127X bandwidth.

Parameters

dev:The sx127x device descriptor
bandwidth:The new bandwidth

uint8_t sx127x_get_spreading_factor(const sx127x_t * dev)

Gets the SX127X LoRa spreading factor.

Parameters

dev:The sx127x device descriptor

Return values

  • the spreading factor
void sx127x_set_spreading_factor(sx127x_t * dev, uint8_t sf)

Sets the SX127X LoRa spreading factor.

Parameters

dev:The sx127x device descriptor
sf:The spreading factor

uint8_t sx127x_get_coding_rate(const sx127x_t * dev)

Gets the SX127X LoRa coding rate.

Parameters

dev:The sx127x device descriptor

Return values

  • the current LoRa coding rate
void sx127x_set_coding_rate(sx127x_t * dev, uint8_t coderate)

Sets the SX127X LoRa coding rate.

Parameters

dev:The sx127x device descriptor
coderate:The LoRa coding rate

bool sx127x_get_rx_single(const sx127x_t * dev)

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

Parameters

dev:The sx127x device descriptor

Return values

  • the LoRa single mode
void sx127x_set_rx_single(sx127x_t * dev, bool single)

Enable/disable the SX127X LoRa RX single mode.

Parameters

dev:The sx127x device descriptor
single:The LoRa RX single mode

bool sx127x_get_crc(const sx127x_t * dev)

Checks if the SX127X CRC verification mode is enabled.

Parameters

dev:The sx127x device descriptor

Return values

  • the LoRa single mode
void sx127x_set_crc(sx127x_t * dev, bool crc)

Enable/Disable the SX127X CRC verification mode.

Parameters

dev:The sx127x device descriptor
crc:The CRC check mode

uint8_t sx127x_get_hop_period(const sx127x_t * dev)

Gets the SX127X frequency hopping period.

Parameters

dev:The sx127x device descriptor

Return values

  • the frequency hopping period
void sx127x_set_hop_period(sx127x_t * dev, uint8_t hop_period)

Sets the SX127X frequency hopping period.

Parameters

dev:The sx127x device descriptor
hop_period:The frequency hopping period

bool sx127x_get_fixed_header_len_mode(const sx127x_t * dev)

Gets the SX127X LoRa fixed header length mode.

Parameters

dev:The sx127x device descriptor

Return values

  • the LoRa implicit mode
void sx127x_set_fixed_header_len_mode(sx127x_t * dev, bool mode)

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

Parameters

dev:The sx127x device descriptor
mode:The header mode

uint8_t sx127x_get_payload_length(const sx127x_t * dev)

Gets the SX127X payload length.

Parameters

dev:The sx127x device descriptor

Return values

  • the payload length
void sx127x_set_payload_length(sx127x_t * dev, uint8_t len)

Sets the SX127X payload length.

Parameters

dev:The sx127x device descriptor
len:The payload len

uint8_t sx127x_get_tx_power(const sx127x_t * dev)

Gets the SX127X TX radio power.

Parameters

dev:The sx127x device descriptor

Return values

  • the radio power
void sx127x_set_tx_power(sx127x_t * dev, int8_t power)

Sets the SX127X transmission power.

Parameters

dev:The sx127x device descriptor
power:The TX power

uint16_t sx127x_get_preamble_length(const sx127x_t * dev)

Gets the SX127X preamble length.

Parameters

dev:The sx127x device descriptor

Return values

  • the preamble length
void sx127x_set_preamble_length(sx127x_t * dev, uint16_t preamble)

Sets the SX127X LoRa preamble length.

Parameters

dev:The sx127x device descriptor
preamble:The LoRa preamble length

void sx127x_set_symbol_timeout(sx127x_t * dev, uint16_t timeout)

Sets the SX127X LoRa symbol timeout.

Parameters

dev:The sx127x device descriptor
timeout:The LoRa symbol timeout

void sx127x_set_rx_timeout(sx127x_t * dev, uint32_t timeout)

Sets the SX127X RX timeout.

Parameters

dev:The sx127x device descriptor
timeout:The RX timeout

void sx127x_set_tx_timeout(sx127x_t * dev, uint32_t timeout)

Sets the SX127X TX timeout.

Parameters

dev:The sx127x device descriptor
timeout:The TX timeout

bool sx127x_get_iq_invert(const sx127x_t * dev)

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

Parameters

dev:The sx127x device descriptor

Return values

  • the LoRa IQ inverted mode
void sx127x_set_iq_invert(sx127x_t * dev, bool iq_invert)

Enable/disable the SX127X LoRa IQ inverted mode.

Parameters

dev:The sx127x device descriptor
iq_invert:The LoRa IQ inverted mode

void sx127x_set_freq_hop(sx127x_t * dev, bool freq_hop_on)

Sets the SX127X LoRa frequency hopping mode.

Parameters

dev:The sx127x device descriptor
freq_hop_on:The LoRa frequency hopping mode

struct sx127x_lora_settings_t

LoRa configuration structure.

uint16_t preamble_len

Length of preamble header.

int8_t power

Signal power.

uint8_t bandwidth

Signal bandwidth.

uint8_t datarate

Spreading factor rate, e.g datarate.

uint8_t coderate

Error coding rate.

uint8_t freq_hop_period

Frequency hop period.

uint8_t flags

Boolean flags.

uint32_t rx_timeout

RX timeout in microseconds.

uint32_t tx_timeout

TX timeout in microseconds.

struct sx127x_radio_settings_t

Radio settings.

uint32_t channel

Radio channel.

uint8_t state

Radio state.

uint8_t modem

Driver model (FSK or LoRa)

sx127x_lora_settings_t lora

LoRa settings.

struct sx127x_internal_t

SX127X internal data.

xtimer.h::xtimer_t tx_timeout_timer

TX operation timeout timer.

xtimer.h::xtimer_t rx_timeout_timer

RX operation timeout timer.

uint32_t last_channel

Last channel in frequency hopping sequence.

bool is_last_cad_success

Sign of success of last CAD operation (activity detected)

struct sx127x_params_t

SX127X hardware and global parameters.

spi.h::spi_t spi

SPI device.

gpio.h::gpio_t nss_pin

SPI NSS pin.

gpio.h::gpio_t reset_pin

Reset pin.

gpio.h::gpio_t dio0_pin

Interrupt line DIO0 (Tx done)

gpio.h::gpio_t dio1_pin

Interrupt line DIO1 (Rx timeout)

gpio.h::gpio_t dio2_pin

Interrupt line DIO2 (FHSS channel change)

gpio.h::gpio_t dio3_pin

Interrupt line DIO3 (CAD done)

gpio.h::gpio_t dio4_pin

Interrupt line DIO4 (not used)

gpio.h::gpio_t dio5_pin

Interrupt line DIO5 (not used)

uint8_t paselect

Power amplifier mode (RFO or PABOOST)

struct sx127x_t

SX127X device descriptor.

netdev.h::netdev_t netdev

Netdev parent struct.

sx127x_radio_settings_t settings

Radio settings.

sx127x_params_t params

Device driver parameters.

sx127x.h::sx127x_flags_t irq

Device IRQ flags.