Embed:
(wiki syntax)
Show/hide line numbers
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(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_
Generated on Tue Jul 12 2022 12:21:59 by
1.7.2