SX1272_LoRaRadio.h

00001 /**
00002  / _____)             _              | |
00003 ( (____  _____ ____ _| |_ _____  ____| |__
00004  \____ \| ___ |    (_   _) ___ |/ ___)  _ \
00005  _____) ) ____| | | || |_| ____( (___| | | |
00006 (______/|_____)_|_|_| \__)_____)\____)_| |_|
00007     (C)2013 Semtech
00008  ___ _____ _   ___ _  _____ ___  ___  ___ ___
00009 / __|_   _/_\ / __| |/ / __/ _ \| _ \/ __| __|
00010 \__ \ | |/ _ \ (__| ' <| _| (_) |   / (__| _|
00011 |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
00012 embedded.connectivity.solutions===============
00013 
00014 Description: Radio driver for Semtech SX1272 radio. Implements LoRaRadio class.
00015 
00016 License: Revised BSD License, see LICENSE.TXT file include in the project
00017 
00018 Maintainer: Miguel Luis ( Semtech ), Gregory Cristian ( Semtech ) and Daniel Jaeckle ( STACKFORCE )
00019 
00020 
00021 Copyright (c) 2017, Arm Limited and affiliates.
00022 
00023 SPDX-License-Identifier: BSD-3-Clause
00024 */
00025 
00026 #ifndef SX1272_LORARADIO_H_
00027 #define SX1272_LORARADIO_H_
00028 
00029 #include "PinNames.h"
00030 #include "InterruptIn.h"
00031 #include "DigitalOut.h"
00032 #include "DigitalInOut.h"
00033 #include "SPI.h"
00034 #include "Timeout.h"
00035 #include "platform/PlatformMutex.h"
00036 #ifdef MBED_CONF_RTOS_PRESENT
00037  #include "rtos/Thread.h"
00038 #endif
00039 
00040 #include "lorawan/LoRaRadio.h"
00041 
00042 #ifdef DEVICE_SPI
00043 
00044 #ifdef MBED_CONF_SX1272_LORA_DRIVER_BUFFER_SIZE
00045 #define MAX_DATA_BUFFER_SIZE_SX172                        MBED_CONF_SX1272_LORA_DRIVER_BUFFER_SIZE
00046 #else
00047 #define MAX_DATA_BUFFER_SIZE_SX172                        256
00048 #endif
00049 
00050 /**
00051  * Radio driver implementation for Semtech SX1272 plus variants.
00052  * Supports only SPI at the moment. Implements pure virtual LoRaRadio class.
00053  */
00054 class SX1272_LoRaRadio: public LoRaRadio {
00055 public:
00056     /**
00057      * Use this constructor if pin definitions are provided manually.
00058      * The pins that are marked NC are optional. It is assumed that these
00059      * pins are not connected until/unless configured otherwise.
00060      */
00061     SX1272_LoRaRadio(PinName mosi,
00062                      PinName miso,
00063                      PinName sclk,
00064                      PinName nss,
00065                      PinName reset,
00066                      PinName dio0,
00067                      PinName dio1,
00068                      PinName dio2,
00069                      PinName dio3,
00070                      PinName dio4,
00071                      PinName dio5,
00072                      PinName rf_switch_ctl1 = NC,
00073                      PinName rf_switch_ctl2 = NC,
00074                      PinName txctl = NC,
00075                      PinName rxctl = NC,
00076                      PinName ant_switch = NC,
00077                      PinName pwr_amp_ctl = NC,
00078                      PinName tcxo = NC);
00079 
00080     /**
00081      * Destructor
00082      */
00083     virtual ~SX1272_LoRaRadio();
00084 
00085     /**
00086      * Registers radio events with the Mbed LoRaWAN stack and
00087      * undergoes initialization steps if any
00088      *
00089      *  @param events Structure containing the driver callback functions
00090      */
00091     virtual void init_radio(radio_events_t *events);
00092 
00093     /**
00094      * Resets the radio module
00095      */
00096     virtual void radio_reset();
00097 
00098     /**
00099      *  Put the RF module in sleep mode
00100      */
00101     virtual void sleep(void);
00102 
00103     /**
00104      *  Sets the radio in standby mode
00105      */
00106     virtual void standby(void);
00107 
00108     /**
00109      *  Sets the reception parameters
00110      *
00111      *  @param modem         Radio modem to be used [0: FSK, 1: LoRa]
00112      *  @param bandwidth     Sets the bandwidth
00113      *                          FSK : >= 2600 and <= 250000 Hz
00114      *                          LoRa: [0: 125 kHz, 1: 250 kHz,
00115      *                                 2: 500 kHz, 3: Reserved]
00116      *  @param datarate      Sets the Datarate
00117      *                          FSK : 600..300000 bits/s
00118      *                          LoRa: [6: 64, 7: 128, 8: 256, 9: 512,
00119      *                                10: 1024, 11: 2048, 12: 4096  chips]
00120      *  @param coderate      Sets the coding rate ( LoRa only )
00121      *                          FSK : N/A ( set to 0 )
00122      *                          LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8]
00123      *  @param bandwidth_afc Sets the AFC Bandwidth ( FSK only )
00124      *                          FSK : >= 2600 and <= 250000 Hz
00125      *                          LoRa: N/A ( set to 0 )
00126      *  @param preamble_len  Sets the Preamble length ( LoRa only )
00127      *                          FSK : N/A ( set to 0 )
00128      *                          LoRa: Length in symbols ( the hardware adds 4 more symbols )
00129      *  @param symb_timeout  Sets the RxSingle timeout value
00130      *                          FSK : timeout number of bytes
00131      *                          LoRa: timeout in symbols
00132      *  @param fixLen        Fixed length packets [0: variable, 1: fixed]
00133      *  @param payload_len   Sets payload length when fixed lenght is used
00134      *  @param crc_on        Enables/Disables the CRC [0: OFF, 1: ON]
00135      *  @param freq_hop_on   Enables disables the intra-packet frequency hopping  [0: OFF, 1: ON] (LoRa only)
00136      *  @param hop_period    Number of symbols bewteen each hop (LoRa only)
00137      *  @param iq_inverted   Inverts IQ signals ( LoRa only )
00138      *                          FSK : N/A ( set to 0 )
00139      *                          LoRa: [0: not inverted, 1: inverted]
00140      *  @param rx_continuous Sets the reception in continuous mode
00141      *                          [false: single mode, true: continuous mode]
00142      */
00143     virtual void set_rx_config (radio_modems_t modem, uint32_t bandwidth,
00144                                uint32_t datarate, uint8_t coderate,
00145                                uint32_t bandwidth_afc, uint16_t preamble_len,
00146                                uint16_t symb_timeout, bool fix_len,
00147                                uint8_t payload_len,
00148                                bool crc_on, bool freq_hop_on, uint8_t hop_period,
00149                                bool iq_inverted, bool rx_continuous);
00150 
00151     /**
00152      *  Sets the transmission parameters
00153      *
00154      *  @param modem         Radio modem to be used [0: FSK, 1: LoRa]
00155      *  @param power         Sets the output power [dBm]
00156      *  @param fdev          Sets the frequency deviation ( FSK only )
00157      *                          FSK : [Hz]
00158      *                          LoRa: 0
00159      *  @param bandwidth     Sets the bandwidth ( LoRa only )
00160      *                          FSK : 0
00161      *                          LoRa: [0: 125 kHz, 1: 250 kHz,
00162      *                                 2: 500 kHz, 3: Reserved]
00163      *  @param datarate      Sets the Datarate
00164      *                          FSK : 600..300000 bits/s
00165      *                          LoRa: [6: 64, 7: 128, 8: 256, 9: 512,
00166      *                                10: 1024, 11: 2048, 12: 4096  chips]
00167      *  @param coderate      Sets the coding rate ( LoRa only )
00168      *                          FSK : N/A ( set to 0 )
00169      *                          LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8]
00170      *  @param preamble_len  Sets the preamble length
00171      *  @param fix_len       Fixed length packets [0: variable, 1: fixed]
00172      *  @param crc_on        Enables disables the CRC [0: OFF, 1: ON]
00173      *  @param freq_hop_on   Enables disables the intra-packet frequency hopping  [0: OFF, 1: ON] (LoRa only)
00174      *  @param hop_period    Number of symbols bewteen each hop (LoRa only)
00175      *  @param iq_inverted   Inverts IQ signals ( LoRa only )
00176      *                          FSK : N/A ( set to 0 )
00177      *                          LoRa: [0: not inverted, 1: inverted]
00178      *  @param timeout       Transmission timeout [us]
00179      */
00180     virtual void set_tx_config(radio_modems_t modem, int8_t power, uint32_t fdev,
00181                               uint32_t bandwidth, uint32_t datarate,
00182                               uint8_t coderate, uint16_t preamble_len,
00183                               bool fix_len, bool crc_on, bool freq_hop_on,
00184                               uint8_t hop_period, bool iq_inverted, uint32_t timeout);
00185 
00186     /**
00187      *  Sends the buffer of size
00188      *
00189      *  Prepares the packet to be sent and sets the radio in transmission
00190      *
00191      *  @param buffer        Buffer pointer
00192      *  @param size          Buffer size
00193      */
00194     virtual void send(uint8_t *buffer, uint8_t size);
00195 
00196     /**
00197      *  Sets the radio in reception mode for the given time
00198      *
00199      *  It should be noted that if the timeout is set to 0, it essentially
00200      *  puts the receiver in continuous mode and hence from thereon it should
00201      *  be treated as if in continuous mode. However, an appropriate way of
00202      *  setting the receiver in continuous mode is by using set_rx_config()
00203      *  API.
00204      *
00205      *  @param timeout       Reception timeout [ms]
00206      *
00207      */
00208     virtual void receive(uint32_t timeout);
00209 
00210     /**
00211      *  Sets the carrier frequency
00212      *
00213      *  @param freq          Channel RF frequency
00214      */
00215     virtual void set_channel(uint32_t freq);
00216 
00217     /**
00218      *  Generates a 32 bits random value based on the RSSI readings
00219      *
00220      *  Remark this function sets the radio in LoRa modem mode and disables
00221      *         all interrupts.
00222      *         After calling this function either Radio.SetRxConfig or
00223      *         Radio.SetTxConfig functions must be called.
00224      *
00225      *  @return             32 bits random value
00226      */
00227     virtual uint32_t random(void);
00228 
00229     /**
00230      *  Get radio status
00231      *
00232      *  @param status        Radio status [RF_IDLE, RF_RX_RUNNING, RF_TX_RUNNING]
00233      *  @return              Return current radio status
00234      */
00235     virtual uint8_t get_status(void);
00236 
00237     /**
00238      *  Sets the maximum payload length
00239      *
00240      *  @param modem         Radio modem to be used [0: FSK, 1: LoRa]
00241      *  @param max           Maximum payload length in bytes
00242      */
00243     virtual void set_max_payload_length(radio_modems_t modem, uint8_t max);
00244 
00245     /**
00246      *  Sets the network to public or private
00247      *
00248      *  Updates the sync byte. Applies to LoRa modem only
00249      *
00250      *  @param enable        if true, it enables a public network
00251      */
00252     virtual void set_public_network(bool enable);
00253 
00254     /**
00255      *  Computes the packet time on air for the given payload
00256      *
00257      *  Remark can only be called once SetRxConfig or SetTxConfig have been called
00258      *
00259      *  @param modem         Radio modem to be used [0: FSK, 1: LoRa]
00260      *  @param pkt_len       Packet payload length
00261      *  @return              Computed airTime for the given packet payload length
00262      */
00263     virtual uint32_t time_on_air(radio_modems_t modem, uint8_t pkt_len);
00264 
00265     /**
00266      * Perform carrier sensing
00267      *
00268      * Checks for a certain time if the RSSI is above a given threshold.
00269      * This threshold determines if there is already a transmission going on
00270      * in the channel or not.
00271      *
00272      * @param modem                     Type of the radio modem
00273      * @param freq                      Carrier frequency
00274      * @param rssi_threshold            Threshold value of RSSI
00275      * @param max_carrier_sense_time    time to sense the channel
00276      *
00277      * @return                          true if there is no active transmission
00278      *                                  in the channel, false otherwise
00279      */
00280     virtual bool perform_carrier_sense(radio_modems_t modem,
00281                                        uint32_t freq,
00282                                        int16_t rssi_threshold,
00283                                        uint32_t max_carrier_sense_time);
00284 
00285     /**
00286      *  Sets the radio in CAD mode
00287      *
00288      */
00289     virtual void start_cad(void);
00290 
00291     /**
00292      *  Check if the given RF is in range
00293      *
00294      *  @param frequency       frequency needed to be checked
00295      */
00296     virtual bool check_rf_frequency(uint32_t frequency);
00297 
00298     /** Sets the radio in continuous wave transmission mode
00299      *
00300      *  @param freq          Channel RF frequency
00301      *  @param power         Sets the output power [dBm]
00302      *  @param time          Transmission mode timeout [s]
00303      */
00304     virtual void set_tx_continuous_wave(uint32_t freq, int8_t power, uint16_t time);
00305 
00306     /**
00307      * Acquire exclusive access
00308      */
00309     virtual void lock(void);
00310 
00311     /**
00312      * Release exclusive access
00313      */
00314     virtual void unlock(void);
00315 
00316 private:
00317 
00318     // SPI and chip select control
00319     mbed::SPI _spi;
00320     mbed::DigitalOut _chip_select;
00321 
00322     // module rest control
00323     mbed::DigitalInOut _reset_ctl;
00324 
00325     // Interrupt controls
00326     mbed::InterruptIn _dio0_ctl;
00327     mbed::InterruptIn _dio1_ctl;
00328     mbed::InterruptIn _dio2_ctl;
00329     mbed::InterruptIn _dio3_ctl;
00330     mbed::InterruptIn _dio4_ctl;
00331     mbed::InterruptIn _dio5_ctl;
00332 
00333     // Radio specific controls
00334     mbed::DigitalOut _rf_switch_ctl1;
00335     mbed::DigitalOut _rf_switch_ctl2;
00336     mbed::DigitalOut _txctl;
00337     mbed::DigitalOut _rxctl;
00338     mbed::DigitalInOut _ant_switch;
00339     mbed::DigitalOut _pwr_amp_ctl;
00340     mbed::DigitalOut _tcxo;
00341 
00342     // Contains all RF control pin names
00343     // This storage is needed even after assigning the
00344     // pins to corresponding object, as the driver needs to know
00345     // which control pins are connected and which are not. This
00346     // variation is inherent to driver because of target configuration.
00347     rf_ctrls _rf_ctrls;
00348 
00349     // We need these PinNames as not all modules have those connected
00350     PinName _dio4_pin;
00351     PinName _dio5_pin;
00352 
00353     // Structure containing all user and network specified settings
00354     // for radio module
00355     radio_settings_t _rf_settings;
00356 
00357     // Structure containing function pointers to the stack callbacks
00358     radio_events_t *_radio_events;
00359 
00360     // Data buffer used for both TX and RX
00361     // Size of this buffer is configurable via Mbed config system
00362     // Default is 256 bytes
00363     uint8_t _data_buffer[MAX_DATA_BUFFER_SIZE_SX172];
00364 
00365     // TX/RX Timers - all use milisecond units
00366     mbed::Timeout tx_timeout_timer;
00367     mbed::Timeout rx_timeout_timer;
00368     mbed::Timeout rx_timeout_sync_word;
00369 
00370 #ifdef MBED_CONF_RTOS_PRESENT
00371     // Thread to handle interrupts
00372     rtos::Thread irq_thread;
00373 #endif
00374 
00375     // Access protection
00376     PlatformMutex mutex;
00377 
00378     uint8_t radio_variant;
00379 
00380     /**
00381      * Flag used to set the RF switch control pins in low power mode when the radio is not active.
00382      */
00383     bool radio_is_active;
00384 
00385     // helper functions
00386     void setup_registers();
00387     void default_antenna_switch_ctrls();
00388     void set_antenna_switch(uint8_t operation_mode);
00389     void setup_spi();
00390     void gpio_init();
00391     void gpio_deinit();
00392     void setup_interrupts();
00393     void set_modem(uint8_t modem);
00394     void set_operation_mode(uint8_t mode);
00395     void set_low_power_mode(bool status);
00396     void set_sx1272_variant_type();
00397     uint8_t get_pa_conf_reg();
00398     void set_rf_tx_power(int8_t power);
00399     int16_t get_rssi(radio_modems_t modem);
00400     uint8_t get_fsk_bw_reg_val(uint32_t bandwidth);
00401     void write_to_register(uint8_t addr, uint8_t data);
00402     void write_to_register(uint8_t addr, uint8_t *data, uint8_t size);
00403     uint8_t read_register(uint8_t addr);
00404     void read_register(uint8_t addr, uint8_t *buffer, uint8_t size);
00405     void write_fifo(uint8_t *buffer, uint8_t size);
00406     void read_fifo(uint8_t *buffer, uint8_t size);
00407     void transmit(uint32_t timeout);
00408     void rf_irq_task(void);
00409 
00410     // ISRs
00411     void  dio0_irq_isr();
00412     void  dio1_irq_isr();
00413     void  dio2_irq_isr();
00414     void  dio3_irq_isr();
00415     void  dio4_irq_isr();
00416     void  dio5_irq_isr();
00417     void  timeout_irq_isr();
00418 
00419     // Handlers called by thread in response to signal
00420     void handle_dio0_irq();
00421     void handle_dio1_irq();
00422     void handle_dio2_irq();
00423     void handle_dio3_irq();
00424     void handle_dio4_irq();
00425     void handle_dio5_irq();
00426     void handle_timeout_irq();
00427 };
00428 
00429 #endif //DEVICE_SPI
00430 
00431 #endif /* SX1272_LORARADIO_H_ */