LoRaRadio.h

00001 /**
00002  * Copyright (c) 2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef LORARADIO_H_
00019 #define LORARADIO_H_
00020 
00021 #include "platform/Callback.h"
00022 #include "PinNames.h"
00023 
00024 /**
00025  * Structure to hold RF controls for LoRa Radio.
00026  * SX1276 have an extra control for the crystal (used in DOSCO-L072CZ)
00027  */
00028 typedef struct {
00029     PinName rf_switch_ctl1;
00030     PinName rf_switch_ctl2;
00031     PinName txctl;
00032     PinName rxctl;
00033     PinName ant_switch;
00034     PinName pwr_amp_ctl;
00035     PinName tcxo;
00036 } rf_ctrls;
00037 
00038 /** Radio driver internal state.
00039  * State machine states definition.
00040  */
00041 typedef enum radio_state {
00042     RF_IDLE = 0,
00043     RF_RX_RUNNING,
00044     RF_TX_RUNNING,
00045     RF_CAD,
00046 } radio_state_t;
00047 
00048 /** Type of the modem.
00049  *  [LORA/FSK]
00050  */
00051 typedef enum modem_type {
00052     MODEM_FSK = 0,
00053     MODEM_LORA
00054 } radio_modems_t;
00055 
00056 /** Radio FSK modem parameters.
00057  *
00058  */
00059 typedef struct radio_fsk_settings {
00060     int8_t   power;
00061     uint32_t f_dev;
00062     uint32_t bandwidth;
00063     uint32_t bandwidth_afc;
00064     uint32_t datarate;
00065     uint16_t preamble_len;
00066     bool     fix_len;
00067     uint8_t  payload_len;
00068     bool     crc_on;
00069     bool     iq_inverted;
00070     bool     rx_continuous;
00071     uint32_t tx_timeout;
00072     uint32_t rx_single_timeout;
00073 } radio_fsk_settings_t;
00074 
00075 /** Radio FSK packet handler state.
00076  *
00077  */
00078 typedef struct radio_fsk_packet_handler {
00079     uint8_t  preamble_detected;
00080     uint8_t  sync_word_detected;
00081     int8_t   rssi_value;
00082     int32_t  afc_value;
00083     uint8_t  rx_gain;
00084     uint16_t size;
00085     uint16_t nb_bytes;
00086     uint8_t  fifo_thresh;
00087     uint8_t  chunk_size;
00088 } radio_fsk_packet_handler_t;
00089 
00090 /** Radio LoRa modem parameters.
00091  *
00092  */
00093 typedef struct radio_lora_settings {
00094     int8_t   power;
00095     uint32_t bandwidth;
00096     uint32_t datarate;
00097     bool     low_datarate_optimize;
00098     uint8_t  coderate;
00099     uint16_t preamble_len;
00100     bool     fix_len;
00101     uint8_t  payload_len;
00102     bool     crc_on;
00103     bool     freq_hop_on;
00104     uint8_t  hop_period;
00105     bool     iq_inverted;
00106     bool     rx_continuous;
00107     uint32_t tx_timeout;
00108     bool     public_network;
00109 } radio_lora_settings_t;
00110 
00111 /** Radio LoRa packet handler state.
00112  *
00113  */
00114 typedef struct radio_lora_packet_handler {
00115     int8_t  snr_value;
00116     int8_t  rssi_value;
00117     uint8_t size;
00118 } radio_lora_packet_handler_t;
00119 
00120 /** Radio settings.
00121  *
00122  */
00123 typedef struct radio_settings {
00124     uint8_t                     state;
00125     uint8_t                     modem;
00126     uint32_t                    channel;
00127     radio_fsk_settings_t        fsk;
00128     radio_fsk_packet_handler_t  fsk_packet_handler;
00129     radio_lora_settings_t       lora;
00130     radio_lora_packet_handler_t lora_packet_handler;
00131 } radio_settings_t;
00132 
00133 /** Radio driver callback functions.
00134  *
00135  */
00136 typedef struct radio_events {
00137     /**
00138      * Callback when Transmission is done
00139      */
00140     mbed::Callback<void()> tx_done;
00141 
00142     /**
00143      * Callback when Transmission is timed out
00144      */
00145     mbed::Callback<void()> tx_timeout;
00146 
00147     /**
00148      * Rx Done callback prototype.
00149      *
00150      *  @param payload Received buffer pointer.
00151      *  @param size    Received buffer size.
00152      *  @param rssi    RSSI value computed while receiving the frame [dBm].
00153      *  @param snr     Raw SNR value given by the radio hardware.
00154      *                     FSK : N/A (set to 0)
00155      *                     LoRa: SNR value in dB
00156      */
00157     mbed::Callback<void(const uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr)> rx_done;
00158 
00159     /**
00160      * Callback when Reception is timed out
00161      */
00162     mbed::Callback<void()> rx_timeout;
00163 
00164     /**
00165      * Callback when Reception ends up in error
00166      */
00167     mbed::Callback<void()> rx_error;
00168 
00169    /**
00170     * FHSS Change Channel callback prototype.
00171     *
00172     *  @param current_channel   The index number of the current channel.
00173     */
00174     mbed::Callback<void(uint8_t current_channel)> fhss_change_channel;
00175 
00176     /**
00177      * CAD Done callback prototype.
00178      *
00179      *  @param channel_busy    True, if Channel activity detected.
00180      */
00181     mbed::Callback<void(bool channel_busy)> cad_done;
00182 } radio_events_t;
00183 
00184 /**
00185  *    Interface for the radios, contains the main functions that a radio needs, and five callback functions.
00186  */
00187 class LoRaRadio
00188 {
00189 
00190 public:
00191 
00192     /**
00193      * Registers radio events with the Mbed LoRaWAN stack and undergoes the initialization steps if any.
00194      *
00195      *  @param events The structure containing the driver callback functions.
00196      */
00197     virtual void init_radio(radio_events_t *events) = 0;
00198 
00199     /**
00200      * Resets the radio module.
00201      */
00202     virtual void radio_reset() = 0;
00203 
00204     /**
00205      *  Put the RF module in the sleep mode.
00206      */
00207     virtual void sleep(void) = 0;
00208 
00209     /**
00210      *  Sets the radio in the standby mode.
00211      */
00212     virtual void standby(void) = 0;
00213 
00214     /**
00215      *  Sets the reception parameters.
00216      *
00217      *  @param modem         The radio modem to be used [0: FSK, 1: LoRa].
00218      *  @param bandwidth     Sets the bandwidth.
00219      *                          FSK : >= 2600 and <= 250000 Hz
00220      *                          LoRa: [0: 125 kHz, 1: 250 kHz,
00221      *                                 2: 500 kHz, 3: Reserved]
00222      *  @param datarate      Sets the datarate.
00223      *                          FSK : 600..300000 bits/s
00224      *                          LoRa: [6: 64, 7: 128, 8: 256, 9: 512,
00225      *                                10: 1024, 11: 2048, 12: 4096  chips]
00226      *  @param coderate      Sets the coding rate (LoRa only).
00227      *                          FSK : N/A ( set to 0 )
00228      *                          LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8]
00229      *  @param bandwidth_afc Sets the AFC bandwidth (FSK only).
00230      *                          FSK : >= 2600 and <= 250000 Hz
00231      *                          LoRa: N/A (set to 0)
00232      *  @param preamble_len  Sets the preamble length (LoRa only).
00233      *                          FSK : N/A (set to 0)
00234      *                          LoRa: Length in symbols (the hardware adds four more symbols).
00235      *  @param symb_timeout  Sets the RxSingle timeout value.
00236      *                          FSK : Timeout number of bytes
00237      *                          LoRa: Timeout in symbols
00238      *  @param fix_len        Fixed length packets [0: variable, 1: fixed].
00239      *  @param payload_len   Sets the payload length when fixed length is used.
00240      *  @param crc_on        Enables/disables the CRC [0: OFF, 1: ON].
00241      *  @param freq_hop_on   Enables/disables the intra-packet frequency hopping [0: OFF, 1: ON] (LoRa only).
00242      *  @param hop_period    The number of symbols bewteen each hop (LoRa only).
00243      *  @param iq_inverted   Inverts the IQ signals (LoRa only).
00244      *                          FSK : N/A (set to 0)
00245      *                          LoRa: [0: not inverted, 1: inverted]
00246      *  @param rx_continuous Sets the reception in continuous mode.
00247      *                          [false: single mode, true: continuous mode]
00248      */
00249     virtual void set_rx_config (radio_modems_t modem, uint32_t bandwidth,
00250                                uint32_t datarate, uint8_t coderate,
00251                                uint32_t bandwidth_afc, uint16_t preamble_len,
00252                                uint16_t symb_timeout, bool fix_len,
00253                                uint8_t payload_len,
00254                                bool crc_on, bool freq_hop_on, uint8_t hop_period,
00255                                bool iq_inverted, bool rx_continuous) = 0;
00256 
00257     /**
00258      *  Sets the transmission parameters.
00259      *
00260      *  @param modem         The radio modem to be used [0: FSK, 1: LoRa].
00261      *  @param power         Sets the output power [dBm].
00262      *  @param fdev          Sets the frequency deviation (FSK only).
00263      *                          FSK : [Hz]
00264      *                          LoRa: 0
00265      *  @param bandwidth     Sets the bandwidth (LoRa only).
00266      *                          FSK : 0
00267      *                          LoRa: [0: 125 kHz, 1: 250 kHz,
00268      *                                 2: 500 kHz, 3: Reserved]
00269      *  @param datarate      Sets the datarate.
00270      *                          FSK : 600..300000 bits/s
00271      *                          LoRa: [6: 64, 7: 128, 8: 256, 9: 512,
00272      *                                10: 1024, 11: 2048, 12: 4096  chips]
00273      *  @param coderate      Sets the coding rate (LoRa only).
00274      *                          FSK : N/A ( set to 0 )
00275      *                          LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8]
00276      *  @param preamble_len  Sets the preamble length.
00277      *  @param fix_len       Fixed length packets [0: variable, 1: fixed].
00278      *  @param crc_on        Enables/disables the CRC [0: OFF, 1: ON].
00279      *  @param freq_hop_on   Enables/disables the intra-packet frequency hopping [0: OFF, 1: ON] (LoRa only).
00280      *  @param hop_period    The number of symbols between each hop (LoRa only).
00281      *  @param iq_inverted   Inverts IQ signals (LoRa only)
00282      *                          FSK : N/A (set to 0).
00283      *                          LoRa: [0: not inverted, 1: inverted]
00284      *  @param timeout       The transmission timeout [ms].
00285      */
00286     virtual void set_tx_config(radio_modems_t modem, int8_t power, uint32_t fdev,
00287                               uint32_t bandwidth, uint32_t datarate,
00288                               uint8_t coderate, uint16_t preamble_len,
00289                               bool fix_len, bool crc_on, bool freq_hop_on,
00290                               uint8_t hop_period, bool iq_inverted, uint32_t timeout) = 0;
00291 
00292     /**
00293      *  Sends the buffer of size
00294      *
00295      *  Prepares the packet to be sent and sets the radio in transmission.
00296      *
00297      *  @param buffer        A pointer to the buffer.
00298      *  @param size          The buffer size.
00299      */
00300     virtual void send(uint8_t *buffer, uint8_t size) = 0;
00301 
00302     /**
00303      *  Sets the radio in reception mode.
00304      *
00305      *  For configuration of the receiver use the `set_rx_config()` API.
00306      */
00307     virtual void receive(void) = 0;
00308 
00309     /**
00310      *  Sets the carrier frequency
00311      *
00312      *  @param freq          Channel RF frequency.
00313      */
00314     virtual void set_channel(uint32_t freq) = 0;
00315 
00316     /**
00317      *  Generates a 32 bit random value based on the RSSI readings.
00318      *
00319      *  \remark This function sets the radio in LoRa modem mode and disables all interrupts.
00320      *          After calling this function, either `Radio.SetRxConfig` or
00321      *         `Radio.SetTxConfig` functions must be called.
00322      *
00323      *  @return             A 32 bit random value.
00324      */
00325     virtual uint32_t random(void) = 0;
00326 
00327     /**
00328      *  Gets the radio status.
00329      *
00330      *  @return              The current radio status.
00331      */
00332     virtual uint8_t get_status(void) = 0;
00333 
00334     /**
00335      *  Sets the maximum payload length.
00336      *
00337      *  @param modem         The radio modem to be used [0: FSK, 1: LoRa].
00338      *  @param max           The maximum payload length in bytes.
00339      */
00340     virtual void set_max_payload_length(radio_modems_t modem, uint8_t max) = 0;
00341 
00342     /**
00343      *  Sets the network to public or private.
00344      *
00345      *  Updates the sync byte. Applies to LoRa modem only.
00346      *
00347      *  @param enable        If true, it enables a public network.
00348      */
00349     virtual void set_public_network(bool enable) = 0;
00350 
00351     /**
00352      *  Computes the packet time on air for the given payload.
00353      *
00354      *  \remark This can only be called once `SetRxConfig` or `SetTxConfig` have been called.
00355      *
00356      *  @param modem         The radio modem to be used [0: FSK, 1: LoRa].
00357      *  @param pkt_len       The packet payload length.
00358      *  @return              The computed `airTime` for the given packet payload length.
00359      */
00360     virtual uint32_t time_on_air(radio_modems_t modem, uint8_t pkt_len) = 0;
00361 
00362     /**
00363      * Performs carrier sensing.
00364      *
00365      * Checks for a certain time if the RSSI is above a given threshold.
00366      * This threshold determines whether or not there is a transmission going on
00367      * in the channel already.
00368      *
00369      * @param modem                     The type of the radio modem.
00370      * @param freq                      The carrier frequency.
00371      * @param rssi_threshold            The threshold value of RSSI.
00372      * @param max_carrier_sense_time    The time set for sensing the channel (ms).
00373      *
00374      * @return                          True if there is no active transmission
00375      *                                  in the channel, otherwise false.
00376      */
00377     virtual bool perform_carrier_sense(radio_modems_t modem,
00378                                        uint32_t freq,
00379                                        int16_t rssi_threshold,
00380                                        uint32_t max_carrier_sense_time) = 0;
00381 
00382     /**
00383      *  Sets the radio in CAD mode.
00384      *
00385      */
00386     virtual void start_cad(void) = 0;
00387 
00388     /**
00389      *  Checks whether the given RF is in range.
00390      *
00391      *  @param frequency       The frequency to be checked.
00392      */
00393     virtual bool check_rf_frequency(uint32_t frequency) = 0;
00394 
00395     /** Sets the radio in continuous wave transmission mode.
00396      *
00397      *  @param freq          The RF frequency of the channel.
00398      *  @param power         The output power [dBm].
00399      *  @param time          The transmission mode timeout [s].
00400      */
00401     virtual void set_tx_continuous_wave(uint32_t freq, int8_t power, uint16_t time) = 0;
00402 
00403     /**
00404      * Acquires exclusive access to this radio.
00405      */
00406     virtual void lock(void) = 0;
00407 
00408     /**
00409      * Releases the exclusive access to this radio.
00410      */
00411     virtual void unlock(void) = 0;
00412 };
00413 
00414 #endif // LORARADIO_H_