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)
95 #ifdef SX127X_USE_DIO_MULTI
96 #define SX127X_IRQ_DIO_MULTI (1<<6)
97 #endif
98 
103 enum {
108 };
109 
113 enum {
116 };
117 
121 enum {
126 };
127 
131 enum {
139 };
140 
148 enum {
151 };
152 
157 #define SX127X_LOW_DATARATE_OPTIMIZE_FLAG (1 << 0)
158 #define SX127X_ENABLE_FIXED_HEADER_LENGTH_FLAG (1 << 1)
159 #define SX127X_ENABLE_CRC_FLAG (1 << 2)
160 #define SX127X_CHANNEL_HOPPING_FLAG (1 << 3)
161 #define SX127X_IQ_INVERTED_FLAG (1 << 4)
162 #define SX127X_RX_CONTINUOUS_FLAG (1 << 5)
163 
168 typedef struct {
169  uint16_t preamble_len;
170  int8_t power;
171  uint8_t bandwidth;
172  uint8_t datarate;
173  uint8_t coderate;
174  uint8_t freq_hop_period;
175  uint8_t flags;
176  uint32_t rx_timeout;
177  uint32_t tx_timeout;
179 
183 typedef struct {
184  uint32_t channel;
185  uint8_t state;
186  uint8_t modem;
189 
193 typedef struct {
194  /* Data that will be passed to events handler in application */
197  uint32_t last_channel;
200 
204 typedef struct {
206  gpio_t nss_pin;
207  gpio_t reset_pin;
208  gpio_t dio0_pin;
209  gpio_t dio1_pin;
210  gpio_t dio2_pin;
211  gpio_t dio3_pin;
212  gpio_t dio4_pin;
213  gpio_t dio5_pin;
214 #ifdef SX127X_USE_DIO_MULTI
215  gpio_t dio_multi_pin;
216 #endif
217  uint8_t paselect;
219 
223 typedef uint8_t sx127x_flags_t;
224 
229 typedef struct {
234  sx127x_flags_t irq;
235 } sx127x_t;
236 
240 typedef void (sx127x_dio_irq_handler_t)(sx127x_t *dev);
241 
248 void sx127x_setup(sx127x_t *dev, const sx127x_params_t *params);
249 
255 int sx127x_reset(const sx127x_t *dev);
256 
264 int sx127x_init(sx127x_t *dev);
265 
272 
285 uint32_t sx127x_random(sx127x_t *dev);
286 
292 void sx127x_start_cad(sx127x_t *dev);
293 
303 bool sx127x_is_channel_free(sx127x_t *dev, uint32_t freq, int16_t rssi_threshold);
304 
312 int16_t sx127x_read_rssi(const sx127x_t *dev);
313 
321 uint8_t sx127x_get_state(const sx127x_t *dev);
322 
331 void sx127x_set_state(sx127x_t *dev, uint8_t state);
332 
339 void sx127x_set_modem(sx127x_t *dev, uint8_t modem);
340 
348 uint8_t sx127x_get_syncword(const sx127x_t *dev);
349 
356 void sx127x_set_syncword(sx127x_t *dev, uint8_t syncword);
357 
365 uint32_t sx127x_get_channel(const sx127x_t *dev);
366 
373 void sx127x_set_channel(sx127x_t *dev, uint32_t freq);
374 
386 uint32_t sx127x_get_time_on_air(const sx127x_t *dev, uint8_t pkt_len);
387 
393 void sx127x_set_sleep(sx127x_t *dev);
394 
400 void sx127x_set_standby(sx127x_t *dev);
401 
407 void sx127x_set_rx(sx127x_t *dev);
408 
414 void sx127x_set_tx(sx127x_t *dev);
415 
423 uint8_t sx127x_get_max_payload_len(const sx127x_t *dev);
424 
431 void sx127x_set_max_payload_len(const sx127x_t *dev, uint8_t maxlen);
432 
440 uint8_t sx127x_get_op_mode(const sx127x_t *dev);
441 
448 void sx127x_set_op_mode(const sx127x_t *dev, uint8_t op_mode);
449 
457 uint8_t sx127x_get_bandwidth(const sx127x_t *dev);
458 
465 void sx127x_set_bandwidth(sx127x_t *dev, uint8_t bandwidth);
466 
474 uint8_t sx127x_get_spreading_factor(const sx127x_t *dev);
475 
482 void sx127x_set_spreading_factor(sx127x_t *dev, uint8_t sf);
483 
491 uint8_t sx127x_get_coding_rate(const sx127x_t *dev);
492 
499 void sx127x_set_coding_rate(sx127x_t *dev, uint8_t coderate);
500 
508 bool sx127x_get_rx_single(const sx127x_t *dev);
509 
516 void sx127x_set_rx_single(sx127x_t *dev, bool single);
517 
525 bool sx127x_get_crc(const sx127x_t *dev);
526 
533 void sx127x_set_crc(sx127x_t *dev, bool crc);
534 
542 uint8_t sx127x_get_hop_period(const sx127x_t *dev);
543 
550 void sx127x_set_hop_period(sx127x_t *dev, uint8_t hop_period);
551 
560 
567 void sx127x_set_fixed_header_len_mode(sx127x_t *dev, bool mode);
568 
576 uint8_t sx127x_get_payload_length(const sx127x_t *dev);
577 
584 void sx127x_set_payload_length(sx127x_t *dev, uint8_t len);
585 
593 uint8_t sx127x_get_tx_power(const sx127x_t *dev);
594 
601 void sx127x_set_tx_power(sx127x_t *dev, int8_t power);
602 
610 uint16_t sx127x_get_preamble_length(const sx127x_t *dev);
611 
618 void sx127x_set_preamble_length(sx127x_t *dev, uint16_t preamble);
619 
626 void sx127x_set_symbol_timeout(sx127x_t *dev, uint16_t timeout);
627 
634 void sx127x_set_rx_timeout(sx127x_t *dev, uint32_t timeout);
635 
642 void sx127x_set_tx_timeout(sx127x_t *dev, uint32_t timeout);
643 
651 bool sx127x_get_iq_invert(const sx127x_t *dev);
652 
659 void sx127x_set_iq_invert(sx127x_t *dev, bool iq_invert);
660 
667 void sx127x_set_freq_hop(sx127x_t *dev, bool freq_hop_on);
668 
669 #ifdef __cplusplus
670 }
671 #endif
672 
673 #endif /* SX127X_H */
674 
uint8_t freq_hop_period
Frequency hop period.
Definition: sx127x.h:174
void sx127x_set_state(sx127x_t *dev, uint8_t state)
Sets current state of transceiver.
SX127X internal data.
Definition: sx127x.h:193
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:209
void sx127x_set_rx_timeout(sx127x_t *dev, uint32_t timeout)
Sets the SX127X RX timeout.
Definitions low-level network driver interface.
uint8_t sx127x_get_spreading_factor(const sx127x_t *dev)
Gets the SX127X LoRa spreading factor.
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:233
Initialization was successful.
Definition: sx127x.h:104
uint8_t sx127x_flags_t
SX127X IRQ flags.
Definition: sx127x.h:223
int sx127x_reset(const sx127x_t *dev)
Resets the SX127X.
void sx127x_start_cad(sx127x_t *dev)
Start a channel activity detection.
Radio settings.
Definition: sx127x.h:183
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:186
sx127x_params_t params
Device driver parameters.
Definition: sx127x.h:232
xtimer_t rx_timeout_timer
RX operation timeout timer.
Definition: sx127x.h:196
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:205
void sx127x_set_rx_single(sx127x_t *dev, bool single)
Enable/disable the SX127X LoRa RX single mode.
FSK modem driver.
Definition: sx127x.h:114
gpio_t nss_pin
SPI NSS pin.
Definition: sx127x.h:206
uint8_t state
Radio state.
Definition: sx127x.h:185
uint8_t sx127x_get_state(const sx127x_t *dev)
Gets current state of transceiver.
Receiving CRC error.
Definition: sx127x.h:136
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:198
gpio_t dio2_pin
Interrupt line DIO2 (FHSS channel change)
Definition: sx127x.h:210
bool sx127x_is_channel_free(sx127x_t *dev, uint32_t freq, int16_t rssi_threshold)
Checks that channel is free with specified RSSI threshold.
Power amplifier boost (high power)
Definition: sx127x.h:150
uint32_t channel
Radio channel.
Definition: sx127x.h:184
Failed to initialize SPI bus or CS line.
Definition: sx127x.h:105
RFO HF or RFO LF.
Definition: sx127x.h:149
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:230
uint8_t datarate
Spreading factor rate, e.g datarate.
Definition: sx127x.h:172
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:176
Failed to initialize GPIOs.
Definition: sx127x.h:106
Receiving complete.
Definition: sx127x.h:132
gpio_t dio5_pin
Interrupt line DIO5 (not used)
Definition: sx127x.h:213
Receiving state.
Definition: sx127x.h:124
sx127x_flags_t irq
Device IRQ flags.
Definition: sx127x.h:234
uint8_t coderate
Error coding rate.
Definition: sx127x.h:173
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:212
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.
void sx127x_set_sleep(sx127x_t *dev)
Sets the radio in sleep mode.
Sending timeout.
Definition: sx127x.h:135
sx127x_radio_settings_t settings
Radio settings.
Definition: sx127x.h:231
uint16_t sx127x_get_preamble_length(const sx127x_t *dev)
Gets the SX127X preamble length.
Channel activity detection complete.
Definition: sx127x.h:138
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:177
No valid device version found.
Definition: sx127x.h:107
uint32_t last_channel
Last channel in frequency hopping sequence.
Definition: sx127x.h:197
Structure to hold driver state.
Definition: netdev.h:277
xtimer interface definitions
void sx127x_set_preamble_length(sx127x_t *dev, uint16_t preamble)
Sets the SX127X LoRa preamble length.
xtimer_t tx_timeout_timer
TX operation timeout timer.
Definition: sx127x.h:195
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:240
LoRa configuration structure.
Definition: sx127x.h:168
uint8_t sx127x_get_coding_rate(const sx127x_t *dev)
Gets the SX127X LoRa coding rate.
int8_t power
Signal power.
Definition: sx127x.h:170
bool sx127x_get_iq_invert(const sx127x_t *dev)
Checks if the SX127X LoRa inverted IQ mode is enabled/disabled.
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:211
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:217
uint8_t bandwidth
Signal bandwidth.
Definition: sx127x.h:171
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.
xtimer timer structure
Definition: xtimer.h:70
uint16_t preamble_len
Length of preamble header.
Definition: sx127x.h:169
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:187
Channel change.
Definition: sx127x.h:137
gpio_t dio0_pin
Interrupt line DIO0 (Tx done)
Definition: sx127x.h:208
Sending state.
Definition: sx127x.h:123
uint8_t flags
Boolean flags.
Definition: sx127x.h:175
Sending complete.
Definition: sx127x.h:133
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.
Idle state.
Definition: sx127x.h:122
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.
Channel activity detection state.
Definition: sx127x.h:125
LoRa modem driver.
Definition: sx127x.h:115
SX127X hardware and global parameters.
Definition: sx127x.h:204
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:207
unsigned int spi_t
Default type for SPI devices.
Definition: spi.h:105
Receiving timeout.
Definition: sx127x.h:134
SX127X device descriptor.
Definition: sx127x.h:229
uint8_t sx127x_get_payload_length(const sx127x_t *dev)
Gets the SX127X payload length.