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)
100 enum {
105 };
106 
110 enum {
113 };
114 
118 enum {
123 };
124 
128 enum {
136 };
137 
145 enum {
148 };
149 
154 #define SX127X_LOW_DATARATE_OPTIMIZE_FLAG (1 << 0)
155 #define SX127X_ENABLE_FIXED_HEADER_LENGTH_FLAG (1 << 1)
156 #define SX127X_ENABLE_CRC_FLAG (1 << 2)
157 #define SX127X_CHANNEL_HOPPING_FLAG (1 << 3)
158 #define SX127X_IQ_INVERTED_FLAG (1 << 4)
159 #define SX127X_RX_CONTINUOUS_FLAG (1 << 5)
160 
165 typedef struct {
166  uint16_t preamble_len;
167  int8_t power;
168  uint8_t bandwidth;
169  uint8_t datarate;
170  uint8_t coderate;
171  uint8_t freq_hop_period;
172  uint8_t flags;
173  uint32_t rx_timeout;
174  uint32_t tx_timeout;
176 
180 typedef struct {
181  uint32_t channel;
182  uint8_t state;
183  uint8_t modem;
186 
190 typedef struct {
191  /* Data that will be passed to events handler in application */
194  uint32_t last_channel;
197 
201 typedef struct {
203  gpio_t nss_pin;
204  gpio_t reset_pin;
205  gpio_t dio0_pin;
206  gpio_t dio1_pin;
207  gpio_t dio2_pin;
208  gpio_t dio3_pin;
209  gpio_t dio4_pin;
210  gpio_t dio5_pin;
211  uint8_t paselect;
213 
217 typedef uint8_t sx127x_flags_t;
218 
223 typedef struct {
229 } sx127x_t;
230 
234 typedef void (sx127x_dio_irq_handler_t)(sx127x_t *dev);
235 
242 void sx127x_setup(sx127x_t *dev, const sx127x_params_t *params);
243 
249 void sx127x_reset(const sx127x_t *dev);
250 
258 int sx127x_init(sx127x_t *dev);
259 
266 
279 uint32_t sx127x_random(sx127x_t *dev);
280 
286 void sx127x_start_cad(sx127x_t *dev);
287 
297 bool sx127x_is_channel_free(sx127x_t *dev, uint32_t freq, int16_t rssi_threshold);
298 
306 int16_t sx127x_read_rssi(const sx127x_t *dev);
307 
315 uint8_t sx127x_get_state(const sx127x_t *dev);
316 
325 void sx127x_set_state(sx127x_t *dev, uint8_t state);
326 
333 void sx127x_set_modem(sx127x_t *dev, uint8_t modem);
334 
342 uint8_t sx127x_get_syncword(const sx127x_t *dev);
343 
350 void sx127x_set_syncword(sx127x_t *dev, uint8_t syncword);
351 
359 uint32_t sx127x_get_channel(const sx127x_t *dev);
360 
367 void sx127x_set_channel(sx127x_t *dev, uint32_t freq);
368 
380 uint32_t sx127x_get_time_on_air(const sx127x_t *dev, uint8_t pkt_len);
381 
387 void sx127x_set_sleep(sx127x_t *dev);
388 
394 void sx127x_set_standby(sx127x_t *dev);
395 
401 void sx127x_set_rx(sx127x_t *dev);
402 
408 void sx127x_set_tx(sx127x_t *dev);
409 
417 uint8_t sx127x_get_max_payload_len(const sx127x_t *dev);
418 
425 void sx127x_set_max_payload_len(const sx127x_t *dev, uint8_t maxlen);
426 
434 uint8_t sx127x_get_op_mode(const sx127x_t *dev);
435 
442 void sx127x_set_op_mode(const sx127x_t *dev, uint8_t op_mode);
443 
451 uint8_t sx127x_get_bandwidth(const sx127x_t *dev);
452 
459 void sx127x_set_bandwidth(sx127x_t *dev, uint8_t bandwidth);
460 
468 uint8_t sx127x_get_spreading_factor(const sx127x_t *dev);
469 
476 void sx127x_set_spreading_factor(sx127x_t *dev, uint8_t sf);
477 
485 uint8_t sx127x_get_coding_rate(const sx127x_t *dev);
486 
493 void sx127x_set_coding_rate(sx127x_t *dev, uint8_t coderate);
494 
502 bool sx127x_get_rx_single(const sx127x_t *dev);
503 
510 void sx127x_set_rx_single(sx127x_t *dev, bool single);
511 
519 bool sx127x_get_crc(const sx127x_t *dev);
520 
527 void sx127x_set_crc(sx127x_t *dev, bool crc);
528 
536 uint8_t sx127x_get_hop_period(const sx127x_t *dev);
537 
544 void sx127x_set_hop_period(sx127x_t *dev, uint8_t hop_period);
545 
554 
561 void sx127x_set_fixed_header_len_mode(sx127x_t *dev, bool mode);
562 
570 uint8_t sx127x_get_payload_length(const sx127x_t *dev);
571 
578 void sx127x_set_payload_length(sx127x_t *dev, uint8_t len);
579 
587 uint8_t sx127x_get_tx_power(const sx127x_t *dev);
588 
595 void sx127x_set_tx_power(sx127x_t *dev, int8_t power);
596 
604 uint16_t sx127x_get_preamble_length(const sx127x_t *dev);
605 
612 void sx127x_set_preamble_length(sx127x_t *dev, uint16_t preamble);
613 
620 void sx127x_set_symbol_timeout(sx127x_t *dev, uint16_t timeout);
621 
628 void sx127x_set_rx_timeout(sx127x_t *dev, uint32_t timeout);
629 
636 void sx127x_set_tx_timeout(sx127x_t *dev, uint32_t timeout);
637 
645 bool sx127x_get_iq_invert(const sx127x_t *dev);
646 
653 void sx127x_set_iq_invert(sx127x_t *dev, bool iq_invert);
654 
661 void sx127x_set_freq_hop(sx127x_t *dev, bool freq_hop_on);
662 
663 #ifdef __cplusplus
664 }
665 #endif
666 
667 #endif /* SX127X_H */
668 
uint8_t freq_hop_period
Frequency hop period.
Definition: sx127x.h:171
void sx127x_set_state(sx127x_t *dev, uint8_t state)
Sets current state of transceiver.
SX127X internal data.
Definition: sx127x.h:190
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:206
void sx127x_set_rx_timeout(sx127x_t *dev, uint32_t timeout)
Sets the SX127X RX timeout.
Definitions low-level network driver interface.
No valid device version found.
Definition: sx127x.h:104
Channel change.
Definition: sx127x.h:134
Sending state.
Definition: sx127x.h:120
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:227
RFO HF or RFO LF.
Definition: sx127x.h:146
uint8_t sx127x_flags_t
SX127X IRQ flags.
Definition: sx127x.h:217
void sx127x_start_cad(sx127x_t *dev)
Start a channel activity detection.
Radio settings.
Definition: sx127x.h:180
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:183
sx127x_params_t params
Device driver parameters.
Definition: sx127x.h:226
Receiving complete.
Definition: sx127x.h:129
xtimer_t rx_timeout_timer
RX operation timeout timer.
Definition: sx127x.h:193
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:202
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:203
uint8_t state
Radio state.
Definition: sx127x.h:182
uint8_t sx127x_get_state(const sx127x_t *dev)
Gets current state of transceiver.
Channel activity detection state.
Definition: sx127x.h:122
Channel activity detection complete.
Definition: sx127x.h:135
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:195
Sending timeout.
Definition: sx127x.h:132
gpio_t dio2_pin
Interrupt line DIO2 (FHSS channel change)
Definition: sx127x.h:207
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:181
Initialization was successful.
Definition: sx127x.h:101
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:224
uint8_t datarate
Spreading factor rate, e.g datarate.
Definition: sx127x.h:169
Idle state.
Definition: sx127x.h:119
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 symbols.
Definition: sx127x.h:173
Power amplifier boost (high power)
Definition: sx127x.h:147
Failed to initialize GPIOs.
Definition: sx127x.h:103
Receiving timeout.
Definition: sx127x.h:131
gpio_t dio5_pin
Interrupt line DIO5 (not used)
Definition: sx127x.h:210
sx127x_flags_t irq
Device IRQ flags.
Definition: sx127x.h:228
uint8_t coderate
Error coding rate.
Definition: sx127x.h:170
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:209
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.
sx127x_radio_settings_t settings
Radio settings.
Definition: sx127x.h:225
uint16_t sx127x_get_preamble_length(const sx127x_t *dev)
Gets the SX127X preamble length.
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 symbols.
Definition: sx127x.h:174
uint32_t last_channel
Last channel in frequency hopping sequence.
Definition: sx127x.h:194
Structure to hold driver state.
Definition: netdev.h:275
xtimer interface definitions
Receiving state.
Definition: sx127x.h:121
void sx127x_set_preamble_length(sx127x_t *dev, uint16_t preamble)
Sets the SX127X LoRa preamble length.
Receiving CRC error.
Definition: sx127x.h:133
xtimer_t tx_timeout_timer
TX operation timeout timer.
Definition: sx127x.h:192
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.
LoRa modem driver.
Definition: sx127x.h:112
Failed to initialize SPI bus or CS line.
Definition: sx127x.h:102
void() sx127x_dio_irq_handler_t(sx127x_t *dev)
Hardware IO IRQ callback function definition.
Definition: sx127x.h:234
LoRa configuration structure.
Definition: sx127x.h:165
uint8_t sx127x_get_coding_rate(const sx127x_t *dev)
Gets the SX127X LoRa coding rate.
int8_t power
Signal power.
Definition: sx127x.h:167
bool sx127x_get_iq_invert(const sx127x_t *dev)
Checks if the SX127X LoRa inverted IQ mode is enabled/disabled.
void sx127x_reset(const sx127x_t *dev)
Resets the SX127X.
Sending complete.
Definition: sx127x.h:130
FSK modem driver.
Definition: sx127x.h:111
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:208
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:211
uint8_t bandwidth
Signal bandwidth.
Definition: sx127x.h:168
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:166
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:184
gpio_t dio0_pin
Interrupt line DIO0 (Tx done)
Definition: sx127x.h:205
uint8_t flags
Boolean flags.
Definition: sx127x.h:172
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:201
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:204
unsigned int spi_t
Default type for SPI devices.
Definition: spi.h:105
SX127X device descriptor.
Definition: sx127x.h:223
uint8_t sx127x_get_payload_length(const sx127x_t *dev)
Gets the SX127X payload length.