sx127x.h

Public interface for SX127X driver.

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.