sx127x.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 2016 Unwired Devices <info@unwds.com>
3  * 2017 Inria
4  *
5  * This file is subject to the terms and conditions of the GNU Lesser
6  * General Public License v2.1. See the file LICENSE in the top level
7  * directory for more details.
8  */
9 
60 #ifndef SX127X_H
61 #define SX127X_H
62 
63 #include "xtimer.h"
64 #include "net/netdev.h"
65 #include "periph/gpio.h"
66 #include "periph/spi.h"
67 
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
71 
76 #define SX127X_MODEM_DEFAULT (SX127X_MODEM_LORA)
77 #define SX127X_CHANNEL_DEFAULT (868300000UL)
78 #define SX127X_HF_CHANNEL_DEFAULT (868000000UL)
79 #define SX127X_RF_MID_BAND_THRESH (525000000UL)
80 #define SX127X_XTAL_FREQ (32000000UL)
81 #define SX127X_RADIO_WAKEUP_TIME (1000U)
83 #define SX127X_TX_TIMEOUT_DEFAULT (1000U * 1000U * 30UL)
84 #define SX127X_RX_SINGLE (false)
85 #define SX127X_RX_BUFFER_SIZE (256)
86 #define SX127X_RADIO_TX_POWER (14U)
88 #define SX127X_EVENT_HANDLER_STACK_SIZE (2048U)
89 #define SX127X_IRQ_DIO0 (1<<0)
90 #define SX127X_IRQ_DIO1 (1<<1)
91 #define SX127X_IRQ_DIO2 (1<<2)
92 #define SX127X_IRQ_DIO3 (1<<3)
93 #define SX127X_IRQ_DIO4 (1<<4)
94 #define SX127X_IRQ_DIO5 (1<<5)
105 #ifndef SX127X_DIO_PULL_MODE
106 #define SX127X_DIO_PULL_MODE (GPIO_IN_PD)
107 #endif
108 
113 enum {
118 };
119 
123 enum {
126 };
127 
131 enum {
136 };
137 
141 enum {
149 };
150 
158 enum {
161 };
162 
167 #define SX127X_LOW_DATARATE_OPTIMIZE_FLAG (1 << 0)
168 #define SX127X_ENABLE_FIXED_HEADER_LENGTH_FLAG (1 << 1)
169 #define SX127X_ENABLE_CRC_FLAG (1 << 2)
170 #define SX127X_CHANNEL_HOPPING_FLAG (1 << 3)
171 #define SX127X_IQ_INVERTED_FLAG (1 << 4)
172 #define SX127X_RX_CONTINUOUS_FLAG (1 << 5)
173 
178 typedef struct {
179  uint16_t preamble_len;
180  int8_t power;
181  uint8_t bandwidth;
182  uint8_t datarate;
183  uint8_t coderate;
184  uint8_t freq_hop_period;
185  uint8_t flags;
186  uint32_t rx_timeout;
187  uint32_t tx_timeout;
189 
193 typedef struct {
194  uint32_t channel;
195  uint8_t state;
196  uint8_t modem;
199 
203 typedef struct {
204  /* Data that will be passed to events handler in application */
207  uint32_t last_channel;
210 
214 typedef struct {
216  gpio_t nss_pin;
217  gpio_t reset_pin;
218  gpio_t dio0_pin;
219  gpio_t dio1_pin;
220  gpio_t dio2_pin;
221  gpio_t dio3_pin;
222  gpio_t dio4_pin;
223  gpio_t dio5_pin;
224 #if defined(SX127X_USE_TX_SWITCH) || defined(SX127X_USE_RX_SWITCH)
225  gpio_t rx_switch_pin;
226  gpio_t tx_switch_pin;
227 #endif
228  uint8_t paselect;
230 
234 typedef uint8_t sx127x_flags_t;
235 
240 typedef struct {
245  sx127x_flags_t irq;
246 } sx127x_t;
247 
251 typedef void (sx127x_dio_irq_handler_t)(sx127x_t *dev);
252 
259 void sx127x_setup(sx127x_t *dev, const sx127x_params_t *params);
260 
266 int sx127x_reset(const sx127x_t *dev);
267 
275 int sx127x_init(sx127x_t *dev);
276 
283 
296 uint32_t sx127x_random(sx127x_t *dev);
297 
303 void sx127x_start_cad(sx127x_t *dev);
304 
314 bool sx127x_is_channel_free(sx127x_t *dev, uint32_t freq, int16_t rssi_threshold);
315 
323 int16_t sx127x_read_rssi(const sx127x_t *dev);
324 
332 uint8_t sx127x_get_state(const sx127x_t *dev);
333 
342 void sx127x_set_state(sx127x_t *dev, uint8_t state);
343 
350 void sx127x_set_modem(sx127x_t *dev, uint8_t modem);
351 
359 uint8_t sx127x_get_syncword(const sx127x_t *dev);
360 
367 void sx127x_set_syncword(sx127x_t *dev, uint8_t syncword);
368 
376 uint32_t sx127x_get_channel(const sx127x_t *dev);
377 
384 void sx127x_set_channel(sx127x_t *dev, uint32_t freq);
385 
397 uint32_t sx127x_get_time_on_air(const sx127x_t *dev, uint8_t pkt_len);
398 
404 void sx127x_set_sleep(sx127x_t *dev);
405 
411 void sx127x_set_standby(sx127x_t *dev);
412 
418 void sx127x_set_rx(sx127x_t *dev);
419 
425 void sx127x_set_tx(sx127x_t *dev);
426 
434 uint8_t sx127x_get_max_payload_len(const sx127x_t *dev);
435 
442 void sx127x_set_max_payload_len(const sx127x_t *dev, uint8_t maxlen);
443 
451 uint8_t sx127x_get_op_mode(const sx127x_t *dev);
452 
459 void sx127x_set_op_mode(const sx127x_t *dev, uint8_t op_mode);
460 
468 uint8_t sx127x_get_bandwidth(const sx127x_t *dev);
469 
476 void sx127x_set_bandwidth(sx127x_t *dev, uint8_t bandwidth);
477 
485 uint8_t sx127x_get_spreading_factor(const sx127x_t *dev);
486 
493 void sx127x_set_spreading_factor(sx127x_t *dev, uint8_t sf);
494 
502 uint8_t sx127x_get_coding_rate(const sx127x_t *dev);
503 
510 void sx127x_set_coding_rate(sx127x_t *dev, uint8_t coderate);
511 
519 bool sx127x_get_rx_single(const sx127x_t *dev);
520 
527 void sx127x_set_rx_single(sx127x_t *dev, bool single);
528 
536 bool sx127x_get_crc(const sx127x_t *dev);
537 
544 void sx127x_set_crc(sx127x_t *dev, bool crc);
545 
553 uint8_t sx127x_get_hop_period(const sx127x_t *dev);
554 
561 void sx127x_set_hop_period(sx127x_t *dev, uint8_t hop_period);
562 
571 
578 void sx127x_set_fixed_header_len_mode(sx127x_t *dev, bool mode);
579 
587 uint8_t sx127x_get_payload_length(const sx127x_t *dev);
588 
595 void sx127x_set_payload_length(sx127x_t *dev, uint8_t len);
596 
604 uint8_t sx127x_get_tx_power(const sx127x_t *dev);
605 
612 void sx127x_set_tx_power(sx127x_t *dev, int8_t power);
613 
621 uint16_t sx127x_get_preamble_length(const sx127x_t *dev);
622 
629 void sx127x_set_preamble_length(sx127x_t *dev, uint16_t preamble);
630 
637 void sx127x_set_symbol_timeout(sx127x_t *dev, uint16_t timeout);
638 
645 void sx127x_set_rx_timeout(sx127x_t *dev, uint32_t timeout);
646 
653 void sx127x_set_tx_timeout(sx127x_t *dev, uint32_t timeout);
654 
662 bool sx127x_get_iq_invert(const sx127x_t *dev);
663 
670 void sx127x_set_iq_invert(sx127x_t *dev, bool iq_invert);
671 
678 void sx127x_set_freq_hop(sx127x_t *dev, bool freq_hop_on);
679 
680 #ifdef __cplusplus
681 }
682 #endif
683 
684 #endif /* SX127X_H */
685 
uint8_t freq_hop_period
Frequency hop period.
Definition: sx127x.h:184
void sx127x_set_state(sx127x_t *dev, uint8_t state)
Sets current state of transceiver.
SX127X internal data.
Definition: sx127x.h:203
uint8_t sx127x_get_tx_power(const sx127x_t *dev)
Gets the SX127X TX radio power.
gpio_t dio1_pin
Interrupt line DIO1 (Rx timeout)
Definition: sx127x.h:219
void sx127x_set_rx_timeout(sx127x_t *dev, uint32_t timeout)
Sets the SX127X RX timeout.
Channel change.
Definition: sx127x.h:147
uint8_t sx127x_get_spreading_factor(const sx127x_t *dev)
Gets the SX127X LoRa spreading factor.
Failed to initialize SPI bus or CS line.
Definition: sx127x.h:115
uint8_t sx127x_get_bandwidth(const sx127x_t *dev)
Gets the SX127X bandwidth.
void sx127x_init_radio_settings(sx127x_t *dev)
Initialize radio settings with default values.
sx127x_internal_t _internal
Internal sx127x data used within the driver.
Definition: sx127x.h:244
uint8_t sx127x_flags_t
SX127X IRQ flags.
Definition: sx127x.h:234
LoRa modem driver.
Definition: sx127x.h:125
FSK modem driver.
Definition: sx127x.h:124
int sx127x_reset(const sx127x_t *dev)
Resets the SX127X.
Channel activity detection complete.
Definition: sx127x.h:148
void sx127x_start_cad(sx127x_t *dev)
Start a channel activity detection.
Radio settings.
Definition: sx127x.h:193
int16_t sx127x_read_rssi(const sx127x_t *dev)
Reads the current RSSI value.
Low-level GPIO peripheral driver interface definitions.
void sx127x_set_crc(sx127x_t *dev, bool crc)
Enable/Disable the SX127X CRC verification mode.
void sx127x_setup(sx127x_t *dev, const sx127x_params_t *params)
Setup the SX127X.
uint8_t modem
Driver model (FSK or LoRa)
Definition: sx127x.h:196
sx127x_params_t params
Device driver parameters.
Definition: sx127x.h:243
xtimer_t rx_timeout_timer
RX operation timeout timer.
Definition: sx127x.h:206
uint8_t sx127x_get_max_payload_len(const sx127x_t *dev)
Gets the maximum payload length.
uint32_t sx127x_get_time_on_air(const sx127x_t *dev, uint8_t pkt_len)
Computes the packet time on air in milliseconds.
spi_t spi
SPI device.
Definition: sx127x.h:215
Definitions low-level network driver interface.
void sx127x_set_rx_single(sx127x_t *dev, bool single)
Enable/disable the SX127X LoRa RX single mode.
gpio_t nss_pin
SPI NSS pin.
Definition: sx127x.h:216
RFO HF or RFO LF.
Definition: sx127x.h:159
uint8_t state
Radio state.
Definition: sx127x.h:195
uint8_t sx127x_get_state(const sx127x_t *dev)
Gets current state of transceiver.
uint32_t sx127x_random(sx127x_t *dev)
Generates 32 bits random value based on the RSSI readings.
bool is_last_cad_success
Sign of success of last CAD operation (activity detected)
Definition: sx127x.h:208
gpio_t dio2_pin
Interrupt line DIO2 (FHSS channel change)
Definition: sx127x.h:220
bool sx127x_is_channel_free(sx127x_t *dev, uint32_t freq, int16_t rssi_threshold)
Checks that channel is free with specified RSSI threshold.
uint32_t channel
Radio channel.
Definition: sx127x.h:194
Idle state.
Definition: sx127x.h:132
void sx127x_set_iq_invert(sx127x_t *dev, bool iq_invert)
Enable/disable the SX127X LoRa IQ inverted mode.
netdev_t netdev
Netdev parent struct.
Definition: sx127x.h:241
uint8_t datarate
Spreading factor rate, e.g datarate.
Definition: sx127x.h:182
void sx127x_set_channel(sx127x_t *dev, uint32_t freq)
Sets the channel RF frequency.
Low-level SPI peripheral driver interface definition.
uint32_t rx_timeout
RX timeout in microseconds.
Definition: sx127x.h:186
Receiving state.
Definition: sx127x.h:134
gpio_t dio5_pin
Interrupt line DIO5 (not used)
Definition: sx127x.h:223
Sending state.
Definition: sx127x.h:133
sx127x_flags_t irq
Device IRQ flags.
Definition: sx127x.h:245
uint8_t coderate
Error coding rate.
Definition: sx127x.h:183
int sx127x_init(sx127x_t *dev)
Initializes the transceiver.
void sx127x_set_modem(sx127x_t *dev, uint8_t modem)
Configures the radio with the given modem.
void sx127x_set_syncword(sx127x_t *dev, uint8_t syncword)
Sets the synchronization word.
gpio_t dio4_pin
Interrupt line DIO4 (not used)
Definition: sx127x.h:222
uint8_t sx127x_get_op_mode(const sx127x_t *dev)
Gets the SX127X operating mode.
void sx127x_set_op_mode(const sx127x_t *dev, uint8_t op_mode)
Sets the SX127X operating mode.
No valid device version found.
Definition: sx127x.h:117
void sx127x_set_sleep(sx127x_t *dev)
Sets the radio in sleep mode.
Failed to initialize GPIOs.
Definition: sx127x.h:116
Power amplifier boost (high power)
Definition: sx127x.h:160
Receiving complete.
Definition: sx127x.h:142
sx127x_radio_settings_t settings
Radio settings.
Definition: sx127x.h:242
uint16_t sx127x_get_preamble_length(const sx127x_t *dev)
Gets the SX127X preamble length.
Sending timeout.
Definition: sx127x.h:145
void sx127x_set_freq_hop(sx127x_t *dev, bool freq_hop_on)
Sets the SX127X LoRa frequency hopping mode.
void sx127x_set_coding_rate(sx127x_t *dev, uint8_t coderate)
Sets the SX127X LoRa coding rate.
void sx127x_set_standby(sx127x_t *dev)
Sets the radio in stand-by mode.
void sx127x_set_fixed_header_len_mode(sx127x_t *dev, bool mode)
Sets the SX127X to fixed header length mode (explicit mode)
uint32_t tx_timeout
TX timeout in microseconds.
Definition: sx127x.h:187
uint32_t last_channel
Last channel in frequency hopping sequence.
Definition: sx127x.h:207
Structure to hold driver state.
Definition: netdev.h:283
xtimer interface definitions
void sx127x_set_preamble_length(sx127x_t *dev, uint16_t preamble)
Sets the SX127X LoRa preamble length.
Receiving timeout.
Definition: sx127x.h:144
xtimer_t tx_timeout_timer
TX operation timeout timer.
Definition: sx127x.h:205
void sx127x_set_rx(sx127x_t *dev)
Sets the radio in reception mode.
void sx127x_set_tx(sx127x_t *dev)
Sets the radio in transmission mode.
void sx127x_set_max_payload_len(const sx127x_t *dev, uint8_t maxlen)
Sets the maximum payload length.
bool sx127x_get_crc(const sx127x_t *dev)
Checks if the SX127X CRC verification mode is enabled.
void() sx127x_dio_irq_handler_t(sx127x_t *dev)
Hardware IO IRQ callback function definition.
Definition: sx127x.h:251
LoRa configuration structure.
Definition: sx127x.h:178
uint8_t sx127x_get_coding_rate(const sx127x_t *dev)
Gets the SX127X LoRa coding rate.
int8_t power
Signal power.
Definition: sx127x.h:180
bool sx127x_get_iq_invert(const sx127x_t *dev)
Checks if the SX127X LoRa inverted IQ mode is enabled/disabled.
Sending complete.
Definition: sx127x.h:143
Receiving CRC error.
Definition: sx127x.h:146
uint8_t sx127x_get_syncword(const sx127x_t *dev)
Gets the synchronization word.
gpio_t dio3_pin
Interrupt line DIO3 (CAD done)
Definition: sx127x.h:221
uint8_t sx127x_get_hop_period(const sx127x_t *dev)
Gets the SX127X frequency hopping period.
uint8_t paselect
Power amplifier mode (RFO or PABOOST)
Definition: sx127x.h:228
uint8_t bandwidth
Signal bandwidth.
Definition: sx127x.h:181
void sx127x_set_tx_timeout(sx127x_t *dev, uint32_t timeout)
Sets the SX127X TX timeout.
uint32_t sx127x_get_channel(const sx127x_t *dev)
Gets the channel RF frequency.
Initialization was successful.
Definition: sx127x.h:114
xtimer timer structure
Definition: xtimer.h:81
uint16_t preamble_len
Length of preamble header.
Definition: sx127x.h:179
bool sx127x_get_rx_single(const sx127x_t *dev)
Checks if the SX127X LoRa RX single mode is enabled/disabled.
sx127x_lora_settings_t lora
LoRa settings.
Definition: sx127x.h:197
gpio_t dio0_pin
Interrupt line DIO0 (Tx done)
Definition: sx127x.h:218
uint8_t flags
Boolean flags.
Definition: sx127x.h:185
void sx127x_set_hop_period(sx127x_t *dev, uint8_t hop_period)
Sets the SX127X frequency hopping period.
void sx127x_set_spreading_factor(sx127x_t *dev, uint8_t sf)
Sets the SX127X LoRa spreading factor.
void sx127x_set_tx_power(sx127x_t *dev, int8_t power)
Sets the SX127X transmission power.
void sx127x_set_bandwidth(sx127x_t *dev, uint8_t bandwidth)
Sets the SX127X bandwidth.
void sx127x_set_payload_length(sx127x_t *dev, uint8_t len)
Sets the SX127X payload length.
bool sx127x_get_fixed_header_len_mode(const sx127x_t *dev)
Gets the SX127X LoRa fixed header length mode.
SX127X hardware and global parameters.
Definition: sx127x.h:214
void sx127x_set_symbol_timeout(sx127x_t *dev, uint16_t timeout)
Sets the SX127X LoRa symbol timeout.
gpio_t reset_pin
Reset pin.
Definition: sx127x.h:217
unsigned int spi_t
Default type for SPI devices.
Definition: spi.h:118
Channel activity detection state.
Definition: sx127x.h:135
SX127X device descriptor.
Definition: sx127x.h:240
uint8_t sx127x_get_payload_length(const sx127x_t *dev)
Gets the SX127X payload length.