Added SX1276 getTemp() method.

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers SX1276_LoRaRadio.h Source File

SX1276_LoRaRadio.h

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