Mistake on this page?
Report an issue in GitHub or email us
SX1276_LoRaRadio.h
1 /**
2  / _____) _ | |
3 ( (____ _____ ____ _| |_ _____ ____| |__
4  \____ \| ___ | (_ _) ___ |/ ___) _ \
5  _____) ) ____| | | || |_| ____( (___| | | |
6 (______/|_____)_|_|_| \__)_____)\____)_| |_|
7  (C)2013 Semtech
8  ___ _____ _ ___ _ _____ ___ ___ ___ ___
9 / __|_ _/_\ / __| |/ / __/ _ \| _ \/ __| __|
10 \__ \ | |/ _ \ (__| ' <| _| (_) | / (__| _|
11 |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
12 embedded.connectivity.solutions===============
13 
14 Description: LoRaWAN stack layer that controls both MAC and PHY underneath
15 
16 License: Revised BSD License, see LICENSE.TXT file include in the project
17 
18 Maintainer: Miguel Luis ( Semtech ), Gregory Cristian ( Semtech ) and Daniel Jaeckle ( STACKFORCE )
19 
20 
21 Copyright (c) 2017, Arm Limited and affiliates.
22 
23 SPDX-License-Identifier: BSD-3-Clause
24 */
25 
26 #ifndef SX1276_LORARADIO_H_
27 #define SX1276_LORARADIO_H_
28 
29 #if DEVICE_SPI
30 
31 #include "PinNames.h"
32 #include "InterruptIn.h"
33 #include "DigitalOut.h"
34 #include "DigitalInOut.h"
35 #include "SPI.h"
36 #include "platform/PlatformMutex.h"
37 #ifdef MBED_CONF_RTOS_PRESENT
38 #include "rtos/Thread.h"
39 #endif
40 
41 #include "lorawan/LoRaRadio.h"
42 
43 #ifdef MBED_CONF_SX1276_LORA_DRIVER_BUFFER_SIZE
44 #define MAX_DATA_BUFFER_SIZE_SX1276 MBED_CONF_SX1276_LORA_DRIVER_BUFFER_SIZE
45 #else
46 #define MAX_DATA_BUFFER_SIZE_SX1276 255
47 #endif
48 
49 #if DEVICE_LPTICKER
50 #include "LowPowerTimeout.h"
51 #define ALIAS_LORAWAN_TIMER mbed::LowPowerTimeout
52 #else
53 #include "Timeout.h"
54 #define ALIAS_LORAWAN_TIMER mbed::Timeout
55 #endif
56 
57 /**
58  * Radio driver implementation for Semtech SX1272 plus variants.
59  * Supports only SPI at the moment. Implements pure virtual LoRaRadio class.
60  */
61 class SX1276_LoRaRadio: public LoRaRadio {
62 public:
63  /**
64  * Use this constructor if pin definitions are provided manually.
65  * The pins that are marked NC are optional. It is assumed that these
66  * pins are not connected until/unless configured otherwise.
67  *
68  * Note: Pin ant_switch is equivalent to RxTx pin at
69  * https://developer.mbed.org/components/SX1276MB1xAS/.
70  * Reading the state of this pin indicates if the radio module type is
71  * SX1276MB1LAS(North American frequency band supported) or SX1276MAS
72  * (European frequency band supported).
73  * Pin dio4 can be mapped to multiple pins on the board, please refer to
74  * schematic of your board. For reference look at
75  * https://developer.mbed.org/components/SX1276MB1xAS/
76  *
77  * Most of the radio module control pins are not being used at the moment as
78  * the SX1276MB1xAS shield has not connected them. For consistency and future
79  * use we are leaving the pins in the constructor. For example, if in some
80  * setting SX1276 radio module gets connected to an external power amplifier
81  * or radio latch controls are connected.
82  */
83  SX1276_LoRaRadio(PinName mosi,
84  PinName miso,
85  PinName sclk,
86  PinName nss,
87  PinName reset,
88  PinName dio0,
89  PinName dio1,
90  PinName dio2,
91  PinName dio3,
92  PinName dio4,
93  PinName dio5,
94  PinName rf_switch_ctl1 = NC,
95  PinName rf_switch_ctl2 = NC,
96  PinName txctl = NC,
97  PinName rxctl = NC,
98  PinName ant_switch = NC,
99  PinName pwr_amp_ctl = NC,
100  PinName tcxo = NC);
101 
102  /**
103  * Destructor
104  */
105  virtual ~SX1276_LoRaRadio();
106 
107  /**
108  * Registers radio events with the Mbed LoRaWAN stack and
109  * undergoes initialization steps if any
110  *
111  * @param events Structure containing the driver callback functions
112  */
113  virtual void init_radio(radio_events_t *events);
114 
115  /**
116  * Resets the radio module
117  */
118  virtual void radio_reset();
119 
120  /**
121  * Put the RF module in sleep mode
122  */
123  virtual void sleep(void);
124 
125  /**
126  * Sets the radio in standby mode
127  */
128  virtual void standby(void);
129 
130  /**
131  * Sets the reception parameters
132  *
133  * @param modem Radio modem to be used [0: FSK, 1: LoRa]
134  * @param bandwidth Sets the bandwidth
135  * FSK : >= 2600 and <= 250000 Hz
136  * LoRa: [0: 125 kHz, 1: 250 kHz,
137  * 2: 500 kHz, 3: Reserved]
138  * @param datarate Sets the Datarate
139  * FSK : 600..300000 bits/s
140  * LoRa: [6: 64, 7: 128, 8: 256, 9: 512,
141  * 10: 1024, 11: 2048, 12: 4096 chips]
142  * @param coderate Sets the coding rate ( LoRa only )
143  * FSK : N/A ( set to 0 )
144  * LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8]
145  * @param bandwidth_afc Sets the AFC Bandwidth ( FSK only )
146  * FSK : >= 2600 and <= 250000 Hz
147  * LoRa: N/A ( set to 0 )
148  * @param preamble_len Sets the Preamble length ( LoRa only )
149  * FSK : N/A ( set to 0 )
150  * LoRa: Length in symbols ( the hardware adds 4 more symbols )
151  * @param symb_timeout Sets the RxSingle timeout value
152  * FSK : timeout number of bytes
153  * LoRa: timeout in symbols
154  * @param fixLen Fixed length packets [0: variable, 1: fixed]
155  * @param payload_len Sets payload length when fixed lenght is used
156  * @param crc_on Enables/Disables the CRC [0: OFF, 1: ON]
157  * @param freq_hop_on Enables disables the intra-packet frequency hopping [0: OFF, 1: ON] (LoRa only)
158  * @param hop_period Number of symbols bewteen each hop (LoRa only)
159  * @param iq_inverted Inverts IQ signals ( LoRa only )
160  * FSK : N/A ( set to 0 )
161  * LoRa: [0: not inverted, 1: inverted]
162  * @param rx_continuous Sets the reception in continuous mode
163  * [false: single mode, true: continuous mode]
164  */
165  virtual void set_rx_config(radio_modems_t modem, uint32_t bandwidth,
166  uint32_t datarate, uint8_t coderate,
167  uint32_t bandwidth_afc, uint16_t preamble_len,
168  uint16_t symb_timeout, bool fix_len,
169  uint8_t payload_len,
170  bool crc_on, bool freq_hop_on, uint8_t hop_period,
171  bool iq_inverted, bool rx_continuous);
172 
173  /**
174  * Sets the transmission parameters
175  *
176  * @param modem Radio modem to be used [0: FSK, 1: LoRa]
177  * @param power Sets the output power [dBm]
178  * @param fdev Sets the frequency deviation ( FSK only )
179  * FSK : [Hz]
180  * LoRa: 0
181  * @param bandwidth Sets the bandwidth ( LoRa only )
182  * FSK : 0
183  * LoRa: [0: 125 kHz, 1: 250 kHz,
184  * 2: 500 kHz, 3: Reserved]
185  * @param datarate Sets the Datarate
186  * FSK : 600..300000 bits/s
187  * LoRa: [6: 64, 7: 128, 8: 256, 9: 512,
188  * 10: 1024, 11: 2048, 12: 4096 chips]
189  * @param coderate Sets the coding rate ( LoRa only )
190  * FSK : N/A ( set to 0 )
191  * LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8]
192  * @param preamble_len Sets the preamble length
193  * @param fix_len Fixed length packets [0: variable, 1: fixed]
194  * @param crc_on Enables disables the CRC [0: OFF, 1: ON]
195  * @param freq_hop_on Enables disables the intra-packet frequency hopping [0: OFF, 1: ON] (LoRa only)
196  * @param hop_period Number of symbols bewteen each hop (LoRa only)
197  * @param iq_inverted Inverts IQ signals ( LoRa only )
198  * FSK : N/A ( set to 0 )
199  * LoRa: [0: not inverted, 1: inverted]
200  * @param timeout Transmission timeout [ms]
201  */
202  virtual void set_tx_config(radio_modems_t modem, int8_t power, uint32_t fdev,
203  uint32_t bandwidth, uint32_t datarate,
204  uint8_t coderate, uint16_t preamble_len,
205  bool fix_len, bool crc_on, bool freq_hop_on,
206  uint8_t hop_period, bool iq_inverted, uint32_t timeout);
207 
208  /**
209  * Sends the buffer of size
210  *
211  * Prepares the packet to be sent and sets the radio in transmission
212  *
213  * @param buffer Buffer pointer
214  * @param size Buffer size
215  */
216  virtual void send(uint8_t *buffer, uint8_t size);
217 
218  /**
219  * For backwards compatibility
220  */
221  virtual void receive(uint32_t timeout)
222  {
223  (void) timeout;
224  receive();
225  }
226 
227  /**
228  * Sets the radio to receive
229  *
230  * All necessary configuration options for reception are set in
231  * 'set_rx_config(parameters)' API.
232  */
233  virtual void receive(void);
234 
235  /**
236  * Sets the carrier frequency
237  *
238  * @param freq Channel RF frequency
239  */
240  virtual void set_channel(uint32_t freq);
241 
242  /**
243  * Generates a 32 bits random value based on the RSSI readings
244  *
245  * Remark this function sets the radio in LoRa modem mode and disables
246  * all interrupts.
247  * After calling this function either Radio.SetRxConfig or
248  * Radio.SetTxConfig functions must be called.
249  *
250  * @return 32 bits random value
251  */
252  virtual uint32_t random(void);
253 
254  /**
255  * Get radio status
256  *
257  * @param status Radio status [RF_IDLE, RF_RX_RUNNING, RF_TX_RUNNING]
258  * @return Return current radio status
259  */
260  virtual uint8_t get_status(void);
261 
262  /**
263  * Sets the maximum payload length
264  *
265  * @param modem Radio modem to be used [0: FSK, 1: LoRa]
266  * @param max Maximum payload length in bytes
267  */
268  virtual void set_max_payload_length(radio_modems_t modem, uint8_t max);
269 
270  /**
271  * Sets the network to public or private
272  *
273  * Updates the sync byte. Applies to LoRa modem only
274  *
275  * @param enable if true, it enables a public network
276  */
277  virtual void set_public_network(bool enable);
278 
279  /**
280  * Computes the packet time on air for the given payload
281  *
282  * Remark can only be called once SetRxConfig or SetTxConfig have been called
283  *
284  * @param modem Radio modem to be used [0: FSK, 1: LoRa]
285  * @param pkt_len Packet payload length
286  * @return Computed airTime for the given packet payload length
287  */
288  virtual uint32_t time_on_air(radio_modems_t modem, uint8_t pkt_len);
289 
290  /**
291  * Perform carrier sensing
292  *
293  * Checks for a certain time if the RSSI is above a given threshold.
294  * This threshold determines if there is already a transmission going on
295  * in the channel or not.
296  *
297  * @param modem Type of the radio modem
298  * @param freq Carrier frequency
299  * @param rssi_threshold Threshold value of RSSI
300  * @param max_carrier_sense_time time to sense the channel
301  *
302  * @return true if there is no active transmission
303  * in the channel, false otherwise
304  */
305  virtual bool perform_carrier_sense(radio_modems_t modem,
306  uint32_t freq,
307  int16_t rssi_threshold,
308  uint32_t max_carrier_sense_time);
309 
310  /**
311  * Sets the radio in CAD mode
312  *
313  */
314  virtual void start_cad(void);
315 
316  /**
317  * Check if the given RF is in range
318  *
319  * @param frequency frequency needed to be checked
320  */
321  virtual bool check_rf_frequency(uint32_t frequency);
322 
323  /** Sets the radio in continuous wave transmission mode
324  *
325  * @param freq Channel RF frequency
326  * @param power Sets the output power [dBm]
327  * @param time Transmission mode timeout [s]
328  */
329  virtual void set_tx_continuous_wave(uint32_t freq, int8_t power, uint16_t time);
330 
331  /**
332  * Acquire exclusive access
333  */
334  virtual void lock(void);
335 
336  /**
337  * Release exclusive access
338  */
339  virtual void unlock(void);
340 
341 private:
342 
343  // SPI and chip select control
344  mbed::SPI _spi;
345  mbed::DigitalOut _chip_select;
346 
347  // module rest control
348  mbed::DigitalInOut _reset_ctl;
349 
350  // Interrupt controls
351  mbed::InterruptIn _dio0_ctl;
352  mbed::InterruptIn _dio1_ctl;
353  mbed::InterruptIn _dio2_ctl;
354  mbed::InterruptIn _dio3_ctl;
355  mbed::InterruptIn _dio4_ctl;
356  mbed::InterruptIn _dio5_ctl;
357 
358  // Radio specific controls
359  mbed::DigitalOut _rf_switch_ctl1;
360  mbed::DigitalOut _rf_switch_ctl2;
361  mbed::DigitalOut _txctl;
362  mbed::DigitalOut _rxctl;
363  mbed::DigitalInOut _ant_switch;
364  mbed::DigitalOut _pwr_amp_ctl;
365  mbed::DigitalOut _tcxo;
366 
367  // Contains all RF control pin names
368  // This storage is needed even after assigning the
369  // pins to corresponding object, as the driver needs to know
370  // which control pins are connected and which are not. This
371  // variation is inherent to driver because of target configuration.
372  rf_ctrls _rf_ctrls;
373 
374  // We need these PinNames as not all modules have those connected
375  PinName _dio4_pin;
376  PinName _dio5_pin;
377 
378  // Structure containing all user and network specified settings
379  // for radio module
380  radio_settings_t _rf_settings;
381 
382  // Structure containing function pointers to the stack callbacks
383  radio_events_t *_radio_events;
384 
385  // Data buffer used for both TX and RX
386  // Size of this buffer is configurable via Mbed config system
387  // Default is 255 bytes
388  uint8_t _data_buffer[MAX_DATA_BUFFER_SIZE_SX1276];
389 
390  // TX timer in ms. This timer is used as a fail safe for TX.
391  // If the chip fails to transmit, its a fatal error, reflecting
392  // some catastrophic bus failure etc. We wish to have the control
393  // back from the driver in such a case.
394  ALIAS_LORAWAN_TIMER tx_timeout_timer;
395 
396 #ifdef MBED_CONF_RTOS_PRESENT
397  // Thread to handle interrupts
398  rtos::Thread irq_thread;
399 #endif
400 
401  // Access protection
402  PlatformMutex mutex;
403 
404  uint8_t radio_variant;
405 
406  // helper functions
407  void setup_registers();
408  void default_antenna_switch_ctrls();
409  void set_antenna_switch(uint8_t operation_mode);
410  void setup_spi();
411  void gpio_init();
412  void gpio_deinit();
413  void setup_interrupts();
414  void set_operation_mode(uint8_t operation_mode);
415  void set_low_power_mode();
416  void set_sx1276_variant_type();
417  uint8_t get_pa_conf_reg(uint32_t channel);
418  void set_rf_tx_power(int8_t power);
419  int16_t get_rssi(radio_modems_t modem);
420  uint8_t get_fsk_bw_reg_val(uint32_t bandwidth);
421  void write_to_register(uint8_t addr, uint8_t data);
422  void write_to_register(uint8_t addr, uint8_t *data, uint8_t size);
423  uint8_t read_register(uint8_t addr);
424  void read_register(uint8_t addr, uint8_t *buffer, uint8_t size);
425  void write_fifo(uint8_t *buffer, uint8_t size);
426  void read_fifo(uint8_t *buffer, uint8_t size);
427  void transmit(uint32_t timeout);
428  void rf_irq_task(void);
429  void set_modem(uint8_t modem);
430  void rx_chain_calibration(void);
431 
432  // ISRs
433  void dio0_irq_isr();
434  void dio1_irq_isr();
435  void dio2_irq_isr();
436  void dio3_irq_isr();
437  void dio4_irq_isr();
438  void dio5_irq_isr();
439  void timeout_irq_isr();
440 
441  // Handlers called by thread in response to signal
442  void handle_dio0_irq();
443  void handle_dio1_irq();
444  void handle_dio2_irq();
445  void handle_dio3_irq();
446  void handle_dio4_irq();
447  void handle_dio5_irq();
448  void handle_timeout_irq();
449 };
450 
451 #endif // DEVICE_SPI
452 
453 #endif // SX1276_LORARADIO_H_
The Thread class allow defining, creating, and controlling thread functions in the system...
Definition: Thread.h:92
virtual void set_tx_config(radio_modems_t modem, int8_t power, uint32_t fdev, uint32_t bandwidth, uint32_t datarate, uint8_t coderate, uint16_t preamble_len, bool fix_len, bool crc_on, bool freq_hop_on, uint8_t hop_period, bool iq_inverted, uint32_t timeout)
Sets the transmission parameters.
virtual void set_tx_continuous_wave(uint32_t freq, int8_t power, uint16_t time)
Sets the radio in continuous wave transmission mode.
virtual void start_cad(void)
Sets the radio in CAD mode.
enum modem_type radio_modems_t
Type of modem.
Structure to hold RF controls for LoRa Radio.
Definition: LoRaRadio.h:35
virtual void receive(uint32_t timeout)
For backwards compatibility.
virtual bool check_rf_frequency(uint32_t frequency)
Check if the given RF is in range.
virtual void unlock(void)
Release exclusive access.
virtual void standby(void)
Sets the radio in standby mode.
virtual bool perform_carrier_sense(radio_modems_t modem, uint32_t freq, int16_t rssi_threshold, uint32_t max_carrier_sense_time)
Perform carrier sensing.
A digital input/output, used for setting or reading a bi-directional pin.
Definition: DigitalInOut.h:35
virtual void radio_reset()
Resets the radio module.
The PlatformMutex class is used to synchronize the execution of threads.
Definition: PlatformMutex.h:47
virtual void set_max_payload_length(radio_modems_t modem, uint8_t max)
Sets the maximum payload length.
virtual void set_public_network(bool enable)
Sets the network to public or private.
virtual void set_channel(uint32_t freq)
Sets the carrier frequency.
Reporting functions for upper layers.
Definition: LoRaRadio.h:389
virtual ~SX1276_LoRaRadio()
Destructor.
virtual void send(uint8_t *buffer, uint8_t size)
Sends the buffer of size.
virtual uint32_t time_on_air(radio_modems_t modem, uint8_t pkt_len)
Computes the packet time on air for the given payload.
virtual uint32_t random(void)
Generates a 32 bits random value based on the RSSI readings.
SX1276_LoRaRadio(PinName mosi, PinName miso, PinName sclk, PinName nss, PinName reset, PinName dio0, PinName dio1, PinName dio2, PinName dio3, PinName dio4, PinName dio5, PinName rf_switch_ctl1=NC, PinName rf_switch_ctl2=NC, PinName txctl=NC, PinName rxctl=NC, PinName ant_switch=NC, PinName pwr_amp_ctl=NC, PinName tcxo=NC)
Use this constructor if pin definitions are provided manually.
virtual uint8_t get_status(void)
Get radio status.
A digital interrupt input, used to call a function on a rising or falling edge.
Definition: InterruptIn.h:65
A digital output, used for setting the state of a pin.
Definition: DigitalOut.h:49
virtual void set_rx_config(radio_modems_t modem, uint32_t bandwidth, uint32_t datarate, uint8_t coderate, uint32_t bandwidth_afc, uint16_t preamble_len, uint16_t symb_timeout, bool fix_len, uint8_t payload_len, bool crc_on, bool freq_hop_on, uint8_t hop_period, bool iq_inverted, bool rx_continuous)
Sets the reception parameters.
A SPI Master, used for communicating with SPI slave devices.
Definition: SPI.h:98
virtual void init_radio(radio_events_t *events)
Registers radio events with the Mbed LoRaWAN stack and undergoes initialization steps if any...
Global radio settings.
Definition: LoRaRadio.h:347
virtual void lock(void)
Acquire exclusive access.
virtual void sleep(void)
Put the RF module in sleep mode.
Radio driver implementation for Semtech SX1272 plus variants.
Interface for the radios, containing the main functions that a radio needs, and five callback functio...
Definition: LoRaRadio.h:440
virtual void receive(void)
Sets the radio to receive.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.