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 [us].
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 for a given time.
00304      *
00305      *  If the timeout is set to 0, it essentially puts the receiver in continuous mode and it should
00306      *  be treated as if in continuous mode. However, an appropriate way to set the receiver in continuous mode is
00307      *  to use the `set_rx_config()` API.
00308      *
00309      *  @param timeout       Reception timeout [ms].
00310      *
00311      */
00312     virtual void receive(uint32_t timeout) = 0;
00313 
00314     /**
00315      *  Sets the carrier frequency
00316      *
00317      *  @param freq          Channel RF frequency.
00318      */
00319     virtual void set_channel(uint32_t freq) = 0;
00320 
00321     /**
00322      *  Generates a 32 bit random value based on the RSSI readings.
00323      *
00324      *  \remark This function sets the radio in LoRa modem mode and disables all interrupts.
00325      *          After calling this function, either `Radio.SetRxConfig` or
00326      *         `Radio.SetTxConfig` functions must be called.
00327      *
00328      *  @return             A 32 bit random value.
00329      */
00330     virtual uint32_t random(void) = 0;
00331 
00332     /**
00333      *  Gets the radio status.
00334      *
00335      *  @return              The current radio status.
00336      */
00337     virtual uint8_t get_status(void) = 0;
00338 
00339     /**
00340      *  Sets the maximum payload length.
00341      *
00342      *  @param modem         The radio modem to be used [0: FSK, 1: LoRa].
00343      *  @param max           The maximum payload length in bytes.
00344      */
00345     virtual void set_max_payload_length(radio_modems_t modem, uint8_t max) = 0;
00346 
00347     /**
00348      *  Sets the network to public or private.
00349      *
00350      *  Updates the sync byte. Applies to LoRa modem only.
00351      *
00352      *  @param enable        If true, it enables a public network.
00353      */
00354     virtual void set_public_network(bool enable) = 0;
00355 
00356     /**
00357      *  Computes the packet time on air for the given payload.
00358      *
00359      *  \remark This can only be called once `SetRxConfig` or `SetTxConfig` have been called.
00360      *
00361      *  @param modem         The radio modem to be used [0: FSK, 1: LoRa].
00362      *  @param pkt_len       The packet payload length.
00363      *  @return              The computed `airTime` for the given packet payload length.
00364      */
00365     virtual uint32_t time_on_air(radio_modems_t modem, uint8_t pkt_len) = 0;
00366 
00367     /**
00368      * Performs carrier sensing.
00369      *
00370      * Checks for a certain time if the RSSI is above a given threshold.
00371      * This threshold determines whether or not there is a transmission going on
00372      * in the channel already.
00373      *
00374      * @param modem                     The type of the radio modem.
00375      * @param freq                      The carrier frequency.
00376      * @param rssi_threshold            The threshold value of RSSI.
00377      * @param max_carrier_sense_time    The time set for sensing the channel (ms).
00378      *
00379      * @return                          True if there is no active transmission
00380      *                                  in the channel, otherwise false.
00381      */
00382     virtual bool perform_carrier_sense(radio_modems_t modem,
00383                                        uint32_t freq,
00384                                        int16_t rssi_threshold,
00385                                        uint32_t max_carrier_sense_time) = 0;
00386 
00387     /**
00388      *  Sets the radio in CAD mode.
00389      *
00390      */
00391     virtual void start_cad(void) = 0;
00392 
00393     /**
00394      *  Checks whether the given RF is in range.
00395      *
00396      *  @param frequency       The frequency to be checked.
00397      */
00398     virtual bool check_rf_frequency(uint32_t frequency) = 0;
00399 
00400     /** Sets the radio in continuous wave transmission mode.
00401      *
00402      *  @param freq          The RF frequency of the channel.
00403      *  @param power         The output power [dBm].
00404      *  @param time          The transmission mode timeout [s].
00405      */
00406     virtual void set_tx_continuous_wave(uint32_t freq, int8_t power, uint16_t time) = 0;
00407 
00408     /**
00409      * Acquires exclusive access to this radio.
00410      */
00411     virtual void lock(void) = 0;
00412 
00413     /**
00414      * Releases the exclusive access to this radio.
00415      */
00416     virtual void unlock(void) = 0;
00417 };
00418 
00419 #endif // LORARADIO_H_