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)
106 #ifndef SX127X_DIO_PULL_MODE
107 #define SX127X_DIO_PULL_MODE (GPIO_IN_PD)
108 #endif
109 
114 enum {
119 };
120 
124 enum {
127 };
128 
132 enum {
137 };
138 
142 enum {
150 };
151 
159 enum {
162 };
163 
168 #define SX127X_LOW_DATARATE_OPTIMIZE_FLAG (1 << 0)
169 #define SX127X_ENABLE_FIXED_HEADER_LENGTH_FLAG (1 << 1)
170 #define SX127X_ENABLE_CRC_FLAG (1 << 2)
171 #define SX127X_CHANNEL_HOPPING_FLAG (1 << 3)
172 #define SX127X_IQ_INVERTED_FLAG (1 << 4)
173 #define SX127X_RX_CONTINUOUS_FLAG (1 << 5)
174 
179 typedef struct {
180  uint16_t preamble_len;
181  int8_t power;
182  uint8_t bandwidth;
183  uint8_t datarate;
184  uint8_t coderate;
185  uint8_t freq_hop_period;
186  uint8_t flags;
187  uint32_t rx_timeout;
188  uint32_t tx_timeout;
190 
194 typedef struct {
195  uint32_t channel;
196  uint8_t state;
197  uint8_t modem;
200 
204 typedef struct {
205  /* Data that will be passed to events handler in application */
208  uint32_t last_channel;
211 
215 typedef struct {
217  gpio_t nss_pin;
218  gpio_t reset_pin;
219  gpio_t dio0_pin;
220  gpio_t dio1_pin;
221  gpio_t dio2_pin;
222  gpio_t dio3_pin;
223  gpio_t dio4_pin;
224  gpio_t dio5_pin;
225 #if defined(SX127X_USE_TX_SWITCH) || defined(SX127X_USE_RX_SWITCH)
226  gpio_t rx_switch_pin;
227  gpio_t tx_switch_pin;
228 #endif
229  uint8_t paselect;
231 
235 typedef uint8_t sx127x_flags_t;
236 
241 typedef struct {
246  sx127x_flags_t irq;
247 } sx127x_t;
248 
252 typedef void (sx127x_dio_irq_handler_t)(sx127x_t *dev);
253 
260 void sx127x_setup(sx127x_t *dev, const sx127x_params_t *params);
261 
267 int sx127x_reset(const sx127x_t *dev);
268 
276 int sx127x_init(sx127x_t *dev);
277 
284 
297 uint32_t sx127x_random(sx127x_t *dev);
298 
304 void sx127x_start_cad(sx127x_t *dev);
305 
315 bool sx127x_is_channel_free(sx127x_t *dev, uint32_t freq, int16_t rssi_threshold);
316 
324 int16_t sx127x_read_rssi(const sx127x_t *dev);
325 
333 uint8_t sx127x_get_state(const sx127x_t *dev);
334 
343 void sx127x_set_state(sx127x_t *dev, uint8_t state);
344 
351 void sx127x_set_modem(sx127x_t *dev, uint8_t modem);
352 
360 uint8_t sx127x_get_syncword(const sx127x_t *dev);
361 
368 void sx127x_set_syncword(sx127x_t *dev, uint8_t syncword);
369 
377 uint32_t sx127x_get_channel(const sx127x_t *dev);
378 
385 void sx127x_set_channel(sx127x_t *dev, uint32_t freq);
386 
398 uint32_t sx127x_get_time_on_air(const sx127x_t *dev, uint8_t pkt_len);
399 
405 void sx127x_set_sleep(sx127x_t *dev);
406 
412 void sx127x_set_standby(sx127x_t *dev);
413 
419 void sx127x_set_rx(sx127x_t *dev);
420 
426 void sx127x_set_tx(sx127x_t *dev);
427 
435 uint8_t sx127x_get_max_payload_len(const sx127x_t *dev);
436 
443 void sx127x_set_max_payload_len(const sx127x_t *dev, uint8_t maxlen);
444 
452 uint8_t sx127x_get_op_mode(const sx127x_t *dev);
453 
460 void sx127x_set_op_mode(const sx127x_t *dev, uint8_t op_mode);
461 
469 uint8_t sx127x_get_bandwidth(const sx127x_t *dev);
470 
477 void sx127x_set_bandwidth(sx127x_t *dev, uint8_t bandwidth);
478 
486 uint8_t sx127x_get_spreading_factor(const sx127x_t *dev);
487 
494 void sx127x_set_spreading_factor(sx127x_t *dev, uint8_t sf);
495 
503 uint8_t sx127x_get_coding_rate(const sx127x_t *dev);
504 
511 void sx127x_set_coding_rate(sx127x_t *dev, uint8_t coderate);
512 
520 bool sx127x_get_rx_single(const sx127x_t *dev);
521 
528 void sx127x_set_rx_single(sx127x_t *dev, bool single);
529 
537 bool sx127x_get_crc(const sx127x_t *dev);
538 
545 void sx127x_set_crc(sx127x_t *dev, bool crc);
546 
554 uint8_t sx127x_get_hop_period(const sx127x_t *dev);
555 
562 void sx127x_set_hop_period(sx127x_t *dev, uint8_t hop_period);
563 
572 
579 void sx127x_set_fixed_header_len_mode(sx127x_t *dev, bool mode);
580 
588 uint8_t sx127x_get_payload_length(const sx127x_t *dev);
589 
596 void sx127x_set_payload_length(sx127x_t *dev, uint8_t len);
597 
605 uint8_t sx127x_get_tx_power(const sx127x_t *dev);
606 
613 void sx127x_set_tx_power(sx127x_t *dev, int8_t power);
614 
622 uint16_t sx127x_get_preamble_length(const sx127x_t *dev);
623 
630 void sx127x_set_preamble_length(sx127x_t *dev, uint16_t preamble);
631 
638 void sx127x_set_symbol_timeout(sx127x_t *dev, uint16_t timeout);
639 
646 void sx127x_set_rx_timeout(sx127x_t *dev, uint32_t timeout);
647 
654 void sx127x_set_tx_timeout(sx127x_t *dev, uint32_t timeout);
655 
663 bool sx127x_get_iq_invert(const sx127x_t *dev);
664 
671 void sx127x_set_iq_invert(sx127x_t *dev, bool iq_invert);
672 
679 void sx127x_set_freq_hop(sx127x_t *dev, bool freq_hop_on);
680 
681 #ifdef __cplusplus
682 }
683 #endif
684 
685 #endif /* SX127X_H */
686 
uint8_t freq_hop_period
Frequency hop period.
Definition: sx127x.h:185
void sx127x_set_state(sx127x_t *dev, uint8_t state)
Sets current state of transceiver.
SX127X internal data.
Definition: sx127x.h:204
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:220
void sx127x_set_rx_timeout(sx127x_t *dev, uint32_t timeout)
Sets the SX127X RX timeout.
Channel change.
Definition: sx127x.h:148
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:116
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:245
uint8_t sx127x_flags_t
SX127X IRQ flags.
Definition: sx127x.h:235
LoRa modem driver.
Definition: sx127x.h:126
FSK modem driver.
Definition: sx127x.h:125
int sx127x_reset(const sx127x_t *dev)
Resets the SX127X.
Channel activity detection complete.
Definition: sx127x.h:149
void sx127x_start_cad(sx127x_t *dev)
Start a channel activity detection.
Radio settings.
Definition: sx127x.h:194
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:197
sx127x_params_t params
Device driver parameters.
Definition: sx127x.h:244
xtimer_t rx_timeout_timer
RX operation timeout timer.
Definition: sx127x.h:207
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:216
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:217
RFO HF or RFO LF.
Definition: sx127x.h:160
uint8_t state
Radio state.
Definition: sx127x.h:196
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:209
gpio_t dio2_pin
Interrupt line DIO2 (FHSS channel change)
Definition: sx127x.h:221
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:195
Idle state.
Definition: sx127x.h:133
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:242
uint8_t datarate
Spreading factor rate, e.g datarate.
Definition: sx127x.h:183
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:187
Receiving state.
Definition: sx127x.h:135
gpio_t dio5_pin
Interrupt line DIO5 (not used)
Definition: sx127x.h:224
Sending state.
Definition: sx127x.h:134
sx127x_flags_t irq
Device IRQ flags.
Definition: sx127x.h:246
uint8_t coderate
Error coding rate.
Definition: sx127x.h:184
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:223
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:118
void sx127x_set_sleep(sx127x_t *dev)
Sets the radio in sleep mode.
Failed to initialize GPIOs.
Definition: sx127x.h:117
Power amplifier boost (high power)
Definition: sx127x.h:161
Receiving complete.
Definition: sx127x.h:143
sx127x_radio_settings_t settings
Radio settings.
Definition: sx127x.h:243
uint16_t sx127x_get_preamble_length(const sx127x_t *dev)
Gets the SX127X preamble length.
Sending timeout.
Definition: sx127x.h:146
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:188
uint32_t last_channel
Last channel in frequency hopping sequence.
Definition: sx127x.h:208
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:145
xtimer_t tx_timeout_timer
TX operation timeout timer.
Definition: sx127x.h:206
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:252
LoRa configuration structure.
Definition: sx127x.h:179
uint8_t sx127x_get_coding_rate(const sx127x_t *dev)
Gets the SX127X LoRa coding rate.
int8_t power
Signal power.
Definition: sx127x.h:181
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:144
Receiving CRC error.
Definition: sx127x.h:147
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:222
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:229
uint8_t bandwidth
Signal bandwidth.
Definition: sx127x.h:182
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:115
xtimer timer structure
Definition: xtimer.h:80
uint16_t preamble_len
Length of preamble header.
Definition: sx127x.h:180
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:198
gpio_t dio0_pin
Interrupt line DIO0 (Tx done)
Definition: sx127x.h:219
uint8_t flags
Boolean flags.
Definition: sx127x.h:186
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:215
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:218
unsigned int spi_t
Default type for SPI devices.
Definition: spi.h:118
Channel activity detection state.
Definition: sx127x.h:136
SX127X device descriptor.
Definition: sx127x.h:241
uint8_t sx127x_get_payload_length(const sx127x_t *dev)
Gets the SX127X payload length.