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 /** @addtogroup LoRaWAN
00022  * Parent class for a LoRa radio driver
00023  *  @{
00024  */
00025 
00026 #include "platform/Callback.h"
00027 #include "PinNames.h"
00028 
00029 /**
00030  * Structure to hold RF controls for LoRa Radio.
00031  * SX1276 have an extra control for the crystal (used in DISCO-L072CZ).
00032  * A subset of these pins may be used by the driver in accordance with the physical
00033  * implementation.
00034  */
00035 typedef struct {
00036     /** TX latch switch pin.
00037      * Exact operation is implementation specific.
00038      */
00039     PinName rf_switch_ctl1;
00040 
00041     /** RX latch switch pin.
00042      * Exact operation is implementation specific.
00043      */
00044     PinName rf_switch_ctl2;
00045 
00046     /** TX control pin for transceiver packaged as a module.
00047      * Exact operation is implementation specific.
00048      */
00049     PinName txctl;
00050 
00051     /** RX control pin for transceiver packaged as a module.
00052      * Exact operation is implementation specific.
00053      */
00054     PinName rxctl;
00055 
00056     /** Transceiver switch pin.
00057      * Exact operation is implementation specific. One of the polarities of the
00058      * pin may drive the transceiver in either TX or RX mode.
00059      */
00060     PinName ant_switch;
00061 
00062     /** Power amplifier control pin.
00063      * Exact operation is implementation specific. If defined,
00064      * controls the operation of an external power amplifier.
00065      */
00066     PinName pwr_amp_ctl;
00067 
00068     /** TCXO crystal control pin.
00069      * Exact operation is implementation specific.
00070      */
00071     PinName tcxo;
00072 } rf_ctrls;
00073 
00074 /** Radio driver internal state.
00075  * Helps identify current state of the transceiver.
00076  */
00077 typedef enum radio_state {
00078     /** IDLE state.
00079      * Radio is in idle state.
00080      */
00081     RF_IDLE = 0,
00082 
00083     /** RX state.
00084      * Radio is receiving.
00085      */
00086     RF_RX_RUNNING,
00087 
00088     /** TX state.
00089      * Radio is transmitting.
00090      */
00091     RF_TX_RUNNING,
00092 
00093     /** CAD state.
00094      * Radio is detecting channel activity.
00095      */
00096     RF_CAD,
00097 } radio_state_t;
00098 
00099 /** Type of modem.
00100  *  [LORA/FSK]
00101  */
00102 typedef enum modem_type {
00103     /** FSK operation mode.
00104      * Radio is using FSK modulation.
00105      */
00106     MODEM_FSK = 0,
00107 
00108     /** LoRa operation mode.
00109      * Radio is using LoRa modulation.
00110      */
00111     MODEM_LORA
00112 } radio_modems_t;
00113 
00114 /** FSK modem parameters.
00115  * Parameters encompassing FSK modulation.
00116  */
00117 typedef struct radio_fsk_settings {
00118     /**
00119      * Transmit power.
00120      */
00121     int8_t   power;
00122 
00123     /**
00124      * Frequency deviation.
00125      */
00126     uint32_t f_dev;
00127 
00128     /**
00129      * Modulation bandwidth.
00130      */
00131     uint32_t bandwidth;
00132 
00133     /**
00134      * Automated frequency correction bandwidth.
00135      */
00136     uint32_t bandwidth_afc;
00137 
00138     /**
00139      * Data rate (SF).
00140      */
00141     uint32_t datarate;
00142 
00143     /**
00144      * Expected preamble length.
00145      */
00146     uint16_t preamble_len;
00147 
00148     /**
00149      * This flag turns on if the TX data size is fixed.
00150      */
00151     bool fix_len;
00152 
00153     /**
00154      * Size of outgoing data.
00155      */
00156     uint8_t  payload_len;
00157 
00158     /**
00159      * Turn CRC on/off.
00160      */
00161     bool crc_on;
00162 
00163     /** @deprecated
00164      * Does not apply to FSK. Will be removed.
00165      */
00166     bool iq_inverted ;
00167 
00168     /**
00169      * Turn continuous reception mode (such as Class C mode) on/off.
00170      */
00171     bool rx_continuous;
00172 
00173     /**
00174      * Timeout value in milliseconds (ms) after which the radio driver reports
00175      * a timeout if the radio was unable to transmit.
00176      */
00177     uint32_t tx_timeout;
00178 
00179     /**
00180      * Timeout value in symbols (symb) after which the radio driver reports a timeout
00181      * if the radio did not receive a Preamble.
00182      */
00183     uint32_t rx_single_timeout;
00184 } radio_fsk_settings_t;
00185 
00186 /** FSK packet handle.
00187  * Contains information about an FSK packet and various metadata.
00188  */
00189 typedef struct radio_fsk_packet_handler {
00190     /**
00191      * Set to true (1) when a Preamble is detected, otherwise false (0).
00192      */
00193     uint8_t preamble_detected;
00194 
00195     /**
00196      * Set to true (1) when a SyncWord is detected, otherwise false (0).
00197      */
00198     uint8_t sync_word_detected;
00199 
00200     /**
00201      * Storage for RSSI value of the received signal.
00202      */
00203     int8_t rssi_value;
00204 
00205     /**
00206      * Automated frequency correction value.
00207      */
00208     int32_t afc_value;
00209 
00210     /**
00211      * LNA gain value (dbm).
00212      */
00213     uint8_t rx_gain;
00214 
00215     /**
00216      * Size of the received data in bytes.
00217      */
00218     uint16_t size;
00219 
00220     /**
00221      * Keeps track of number of bytes already read from the RX FIFO.
00222      */
00223     uint16_t nb_bytes;
00224 
00225     /**
00226      * Stores the FIFO threshold value.
00227      */
00228     uint8_t fifo_thresh;
00229 
00230     /**
00231      * Defines the size of a chunk of outgoing buffer written to
00232      * the FIFO at a unit time. For example, if the size of the data exceeds the FIFO
00233      * limit, a certain sized chunk is written to the FIFO. Later, a FIFO-level
00234      * interrupt enables writing of the remaining data to the FIFO chunk by chunk until
00235      * transmission is complete.
00236      */
00237     uint8_t chunk_size;
00238 } radio_fsk_packet_handler_t;
00239 
00240 /** LoRa modem parameters.
00241  * Parameters encompassing LoRa modulation.
00242  */
00243 typedef struct radio_lora_settings {
00244     /**
00245      * Transmit power.
00246      */
00247     int8_t power;
00248 
00249     /**
00250      * Modulation bandwidth.
00251      */
00252     uint32_t bandwidth;
00253 
00254     /**
00255      * Data rate (SF).
00256      */
00257     uint32_t datarate;
00258 
00259     /**
00260      * Turn low data rate optimization on/off.
00261      */
00262     bool low_datarate_optimize;
00263 
00264     /**
00265      * Error correction code rate.
00266      */
00267     uint8_t coderate;
00268 
00269     /**
00270      * Preamble length in symbols.
00271      */
00272     uint16_t preamble_len;
00273 
00274     /**
00275      * Set to true if the outgoing payload length is fixed.
00276      */
00277     bool fix_len;
00278 
00279     /**
00280      * Size of outgoing payload.
00281      */
00282     uint8_t payload_len;
00283 
00284     /**
00285      * Turn CRC on/off.
00286      */
00287     bool crc_on;
00288 
00289     /**
00290      * Turn frequency hopping on/off.
00291      */
00292     bool freq_hop_on;
00293 
00294     /**
00295      * Number of symbols between two frequency hops.
00296      */
00297     uint8_t hop_period;
00298 
00299     /**
00300      * Turn IQ inversion on/off. Usually, the end device sends an IQ inverted
00301      * signal, and the base stations do not invert. We recommended sending an
00302      * IQ inverted signal from the device side, so any transmissions from the
00303      * base stations do not interfere with end device transmission.
00304      */
00305     bool iq_inverted;
00306 
00307     /**
00308      * Turn continuous reception mode (such as in Class C) on/off.
00309      */
00310     bool rx_continuous;
00311 
00312     /**
00313      * Timeout in milliseconds (ms) after which the radio driver reports an error
00314      * if the radio was unable to transmit.
00315      */
00316     uint32_t tx_timeout;
00317 
00318     /**
00319      * Change the network mode to Public or Private.
00320      */
00321     bool public_network;
00322 } radio_lora_settings_t;
00323 
00324 /** LoRa packet
00325  * Contains information about a LoRa packet.
00326  */
00327 typedef struct radio_lora_packet_handler {
00328     /**
00329      * Signal-to-noise ratio of a received packet.
00330      */
00331     int8_t snr_value;
00332 
00333     /**
00334      * RSSI value in dBm for the received packet.
00335      */
00336     int8_t rssi_value;
00337 
00338     /**
00339      * Size of the transmitted or received packet.
00340      */
00341     uint8_t size;
00342 } radio_lora_packet_handler_t;
00343 
00344 /** Global radio settings.
00345  * Contains settings for the overall transceiver operation.
00346  */
00347 typedef struct radio_settings {
00348     /**
00349      * Current state of the radio, such as RF_IDLE.
00350      */
00351     uint8_t                     state;
00352 
00353     /**
00354      * Current modem operation, such as MODEM_LORA.
00355      */
00356     uint8_t                     modem;
00357 
00358     /**
00359      * Current channel of operation.
00360      */
00361     uint32_t                    channel;
00362 
00363     /**
00364      * Settings for FSK modem part.
00365      */
00366     radio_fsk_settings_t        fsk;
00367 
00368     /**
00369      * FSK packet and meta data.
00370      */
00371     radio_fsk_packet_handler_t  fsk_packet_handler;
00372 
00373     /**
00374      * Settings for LoRa modem part.
00375      */
00376     radio_lora_settings_t       lora;
00377 
00378     /**
00379      * LoRa packet and metadata.
00380      */
00381     radio_lora_packet_handler_t lora_packet_handler;
00382 } radio_settings_t;
00383 
00384 /** Reporting functions for upper layers.
00385  * The radio driver reports various vital events to the upper controlling layers
00386  * using callback functions provided by the upper layers at the initialization
00387  * phase.
00388  */
00389 typedef struct radio_events {
00390     /**
00391      * Callback when Transmission is done.
00392      */
00393     mbed::Callback<void()> tx_done;
00394 
00395     /**
00396      * Callback when Transmission is timed out.
00397      */
00398     mbed::Callback<void()> tx_timeout;
00399 
00400     /**
00401      * Rx Done callback prototype.
00402      *
00403      *  @param payload Received buffer pointer.
00404      *  @param size    Received buffer size.
00405      *  @param rssi    RSSI value computed while receiving the frame [dBm].
00406      *  @param snr     Raw SNR value given by the radio hardware.
00407      *                     FSK : N/A (set to 0)
00408      *                     LoRa: SNR value in dB
00409      */
00410     mbed::Callback<void(const uint8_t *payload, uint16_t size, int16_t rssi, int8_t snr)> rx_done;
00411 
00412     /**
00413      * Callback when Reception is timed out.
00414      */
00415     mbed::Callback<void()> rx_timeout;
00416 
00417     /**
00418      * Callback when Reception ends up in error.
00419      */
00420     mbed::Callback<void()> rx_error;
00421 
00422     /**
00423      * FHSS Change Channel callback prototype.
00424      *
00425      *  @param current_channel   The index number of the current channel.
00426      */
00427     mbed::Callback<void(uint8_t current_channel)> fhss_change_channel;
00428 
00429     /**
00430      * CAD Done callback prototype.
00431      *
00432      *  @param channel_busy    True, if Channel activity detected.
00433      */
00434     mbed::Callback<void(bool channel_busy)> cad_done;
00435 } radio_events_t;
00436 
00437 /**
00438  * Interface for the radios, containing the main functions that a radio needs, and five callback functions.
00439  */
00440 class LoRaRadio {
00441 
00442 public:
00443 
00444     /**
00445      * Registers radio events with the Mbed LoRaWAN stack and undergoes initialization steps, if any.
00446      *
00447      *  @param events Contains driver callback functions.
00448      */
00449     virtual void init_radio(radio_events_t *events) = 0;
00450 
00451     /**
00452      * Resets the radio module.
00453      */
00454     virtual void radio_reset() = 0;
00455 
00456     /**
00457      *  Put the RF module in sleep mode.
00458      */
00459     virtual void sleep(void) = 0;
00460 
00461     /**
00462      *  Sets the radio to standby mode.
00463      */
00464     virtual void standby(void) = 0;
00465 
00466     /**
00467      *  Sets reception parameters.
00468      *
00469      *  @param modem         The radio modem [0: FSK, 1: LoRa].
00470      *  @param bandwidth     Sets the bandwidth.
00471      *                          FSK : >= 2600 and <= 250000 Hz
00472      *                          LoRa: [0: 125 kHz, 1: 250 kHz,
00473      *                                 2: 500 kHz, 3: Reserved]
00474      *  @param datarate      Sets the datarate.
00475      *                          FSK : 600..300000 bits/s
00476      *                          LoRa: [6: 64, 7: 128, 8: 256, 9: 512,
00477      *                                10: 1024, 11: 2048, 12: 4096  chips]
00478      *  @param coderate      Sets the coding rate (LoRa only).
00479      *                          FSK : N/A ( set to 0 )
00480      *                          LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8]
00481      *  @param bandwidth_afc Sets the AFC bandwidth (FSK only).
00482      *                          FSK : >= 2600 and <= 250000 Hz
00483      *                          LoRa: N/A (set to 0)
00484      *  @param preamble_len  Sets the preamble length (LoRa only).
00485      *                          FSK : N/A (set to 0)
00486      *                          LoRa: Length in symbols (the hardware adds four more symbols).
00487      *  @param symb_timeout  Sets the RxSingle timeout value.
00488      *                          FSK : Timeout number of bytes
00489      *                          LoRa: Timeout in symbols
00490      *  @param fix_len        Fixed length packets [0: variable, 1: fixed].
00491      *  @param payload_len   Sets the payload length when fixed length is used.
00492      *  @param crc_on        Enables/disables CRC [0: OFF, 1: ON].
00493      *  @param freq_hop_on   Enables/disables intra-packet frequency hopping [0: OFF, 1: ON] (LoRa only).
00494      *  @param hop_period    The number of symbols bewteen each hop (LoRa only).
00495      *  @param iq_inverted   Inverts the IQ signals (LoRa only).
00496      *                          FSK : N/A (set to 0)
00497      *                          LoRa: [0: not inverted, 1: inverted]
00498      *  @param rx_continuous Sets the reception to continuous mode.
00499      *                          [false: single mode, true: continuous mode]
00500      */
00501     virtual void set_rx_config(radio_modems_t modem, uint32_t bandwidth,
00502                                uint32_t datarate, uint8_t coderate,
00503                                uint32_t bandwidth_afc, uint16_t preamble_len,
00504                                uint16_t symb_timeout, bool fix_len,
00505                                uint8_t payload_len,
00506                                bool crc_on, bool freq_hop_on, uint8_t hop_period,
00507                                bool iq_inverted, bool rx_continuous) = 0;
00508 
00509     /**
00510      *  Sets the transmission parameters.
00511      *
00512      *  @param modem         The radio modem [0: FSK, 1: LoRa].
00513      *  @param power         Sets the output power [dBm].
00514      *  @param fdev          Sets the frequency deviation (FSK only).
00515      *                          FSK : [Hz]
00516      *                          LoRa: 0
00517      *  @param bandwidth     Sets the bandwidth (LoRa only).
00518      *                          FSK : 0
00519      *                          LoRa: [0: 125 kHz, 1: 250 kHz,
00520      *                                 2: 500 kHz, 3: Reserved]
00521      *  @param datarate      Sets the datarate.
00522      *                          FSK : 600..300000 bits/s
00523      *                          LoRa: [6: 64, 7: 128, 8: 256, 9: 512,
00524      *                                10: 1024, 11: 2048, 12: 4096  chips]
00525      *  @param coderate      Sets the coding rate (LoRa only).
00526      *                          FSK : N/A ( set to 0 )
00527      *                          LoRa: [1: 4/5, 2: 4/6, 3: 4/7, 4: 4/8]
00528      *  @param preamble_len  Sets the preamble length.
00529      *  @param fix_len       Fixed length packets [0: variable, 1: fixed].
00530      *  @param crc_on        Enables/disables CRC [0: OFF, 1: ON].
00531      *  @param freq_hop_on   Enables/disables intra-packet frequency hopping [0: OFF, 1: ON] (LoRa only).
00532      *  @param hop_period    The number of symbols between each hop (LoRa only).
00533      *  @param iq_inverted   Inverts IQ signals (LoRa only)
00534      *                          FSK : N/A (set to 0).
00535      *                          LoRa: [0: not inverted, 1: inverted]
00536      *  @param timeout       The transmission timeout [ms].
00537      */
00538     virtual void set_tx_config(radio_modems_t modem, int8_t power, uint32_t fdev,
00539                                uint32_t bandwidth, uint32_t datarate,
00540                                uint8_t coderate, uint16_t preamble_len,
00541                                bool fix_len, bool crc_on, bool freq_hop_on,
00542                                uint8_t hop_period, bool iq_inverted, uint32_t timeout) = 0;
00543 
00544     /**
00545      *  Sends the packet.
00546      *
00547      *  Prepares the packet to be sent and sets the radio to transmission mode.
00548      *
00549      *  @param buffer        A pointer to the buffer.
00550      *  @param size          The buffer size.
00551      */
00552     virtual void send(uint8_t *buffer, uint8_t size) = 0;
00553 
00554     /**
00555      *  Sets the radio to reception mode.
00556      *
00557      *  To configure the receiver, use the `set_rx_config()` API.
00558      */
00559     virtual void receive(void) = 0;
00560 
00561     /**
00562      *  Sets the carrier frequency.
00563      *
00564      *  @param freq          Channel RF frequency.
00565      */
00566     virtual void set_channel(uint32_t freq) = 0;
00567 
00568     /**
00569      *  Generates a 32 bit random value based on RSSI readings.
00570      *
00571      *  \remark This function sets the radio in LoRa modem mode and disables all interrupts.
00572      *          After calling this function, either `Radio.SetRxConfig` or
00573      *         `Radio.SetTxConfig` functions must be called.
00574      *
00575      *  @return             A 32 bit random value.
00576      */
00577     virtual uint32_t random(void) = 0;
00578 
00579     /**
00580      *  Gets the radio status.
00581      *
00582      *  @return              The current radio status.
00583      */
00584     virtual uint8_t get_status(void) = 0;
00585 
00586     /**
00587      *  Sets the maximum payload length.
00588      *
00589      *  @param modem         The radio modem [0: FSK, 1: LoRa].
00590      *  @param max           The maximum payload length in bytes.
00591      */
00592     virtual void set_max_payload_length(radio_modems_t modem, uint8_t max) = 0;
00593 
00594     /**
00595      *  Sets the network to public or private.
00596      *
00597      *  Updates the sync byte. Applies to LoRa modem only.
00598      *
00599      *  @param enable        If true, enables a public network.
00600      */
00601     virtual void set_public_network(bool enable) = 0;
00602 
00603     /**
00604      *  Computes the packet time on air for the given payload.
00605      *
00606      *  \remark This can only be called after `SetRxConfig` or `SetTxConfig`.
00607      *
00608      *  @param modem         The radio modem [0: FSK, 1: LoRa].
00609      *  @param pkt_len       The packet payload length.
00610      *  @return              The computed `airTime` for the given packet payload length.
00611      */
00612     virtual uint32_t time_on_air(radio_modems_t modem, uint8_t pkt_len) = 0;
00613 
00614     /**
00615      * Performs carrier sensing.
00616      *
00617      * Checks for a certain time if the RSSI is above a given threshold.
00618      * This threshold determines whether or not there is a transmission on
00619      * the channel already.
00620      *
00621      * @param modem                     The type of radio modem.
00622      * @param freq                      The carrier frequency.
00623      * @param rssi_threshold            The threshold value of RSSI.
00624      * @param max_carrier_sense_time    The time set for sensing the channel (ms).
00625      *
00626      * @return                          True if there is no active transmission
00627      *                                  in the channel, otherwise false.
00628      */
00629     virtual bool perform_carrier_sense(radio_modems_t modem,
00630                                        uint32_t freq,
00631                                        int16_t rssi_threshold,
00632                                        uint32_t max_carrier_sense_time) = 0;
00633 
00634     /**
00635      *  Sets the radio to CAD mode.
00636      *
00637      */
00638     virtual void start_cad(void) = 0;
00639 
00640     /**
00641      *  Checks whether the given RF is in range.
00642      *
00643      *  @param frequency       The frequency to check.
00644      */
00645     virtual bool check_rf_frequency(uint32_t frequency) = 0;
00646 
00647     /** Sets the radio to continuous wave transmission mode.
00648      *
00649      *  @param freq          The RF frequency of the channel.
00650      *  @param power         The output power [dBm].
00651      *  @param time          The transmission mode timeout [s].
00652      */
00653     virtual void set_tx_continuous_wave(uint32_t freq, int8_t power, uint16_t time) = 0;
00654 
00655     /**
00656      * Acquires exclusive access to this radio.
00657      */
00658     virtual void lock(void) = 0;
00659 
00660     /**
00661      * Releases exclusive access to this radio.
00662      */
00663     virtual void unlock(void) = 0;
00664 };
00665 
00666 #endif // LORARADIO_H_
00667 /** @}*/