Line data Source code
1 : #if !defined(_RADIOLIB_PHYSICAL_LAYER_H)
2 : #define _RADIOLIB_PHYSICAL_LAYER_H
3 :
4 : #include "../../TypeDef.h"
5 : #include "../../Module.h"
6 :
7 : // common IRQ values - the IRQ flags in RadioLibIrqFlags_t arguments are offset by this value
8 : enum RadioLibIrqType_t {
9 : RADIOLIB_IRQ_TX_DONE = 0x00,
10 : RADIOLIB_IRQ_RX_DONE = 0x01,
11 : RADIOLIB_IRQ_PREAMBLE_DETECTED = 0x02,
12 : RADIOLIB_IRQ_SYNC_WORD_VALID = 0x03,
13 : RADIOLIB_IRQ_HEADER_VALID = 0x04,
14 : RADIOLIB_IRQ_HEADER_ERR = 0x05,
15 : RADIOLIB_IRQ_CRC_ERR = 0x06,
16 : RADIOLIB_IRQ_CAD_DONE = 0x07,
17 : RADIOLIB_IRQ_CAD_DETECTED = 0x08,
18 : RADIOLIB_IRQ_TIMEOUT = 0x09,
19 : RADIOLIB_IRQ_NOT_SUPPORTED = 0x1F, // this must be the last value, intentionally set to 31
20 : };
21 :
22 : // some commonly used default values - defined here to ensure all modules have the same default behavior
23 : #define RADIOLIB_IRQ_RX_DEFAULT_FLAGS ((1UL << RADIOLIB_IRQ_RX_DONE) | (1UL << RADIOLIB_IRQ_TIMEOUT) | (1UL << RADIOLIB_IRQ_CRC_ERR) | (1UL << RADIOLIB_IRQ_HEADER_VALID) | (1UL << RADIOLIB_IRQ_HEADER_ERR))
24 : #define RADIOLIB_IRQ_RX_DEFAULT_MASK ((1UL << RADIOLIB_IRQ_RX_DONE))
25 : #define RADIOLIB_IRQ_CAD_DEFAULT_FLAGS ((1UL << RADIOLIB_IRQ_CAD_DETECTED) | (1UL << RADIOLIB_IRQ_CAD_DONE))
26 : #define RADIOLIB_IRQ_CAD_DEFAULT_MASK ((1UL << RADIOLIB_IRQ_CAD_DETECTED) | (1UL << RADIOLIB_IRQ_CAD_DONE))
27 :
28 : /*!
29 : \struct LoRaRate_t
30 : \brief Data rate structure interpretation in case LoRa is used
31 : */
32 : struct LoRaRate_t {
33 : /*! \brief LoRa spreading factor */
34 : uint8_t spreadingFactor;
35 :
36 : /*! \brief LoRa bandwidth in kHz */
37 : float bandwidth;
38 :
39 : /*! \brief LoRa coding rate denominator */
40 : uint8_t codingRate;
41 : };
42 :
43 : /*!
44 : \struct FSKRate_t
45 : \brief Data rate structure interpretation in case FSK is used
46 : */
47 : struct FSKRate_t {
48 : /*! \brief FSK bit rate in kbps */
49 : float bitRate;
50 :
51 : /*! \brief FSK frequency deviation in kHz */
52 : float freqDev;
53 : };
54 :
55 : /*!
56 : \struct LrFhssRate_t
57 : \brief Data rate structure interpretation in case LR-FHSS is used
58 : */
59 : struct LrFhssRate_t {
60 : /*! \brief Bandwidth */
61 : uint8_t bw;
62 :
63 : /*! \brief Coding rate */
64 : uint8_t cr;
65 :
66 : /*! \brief Grid spacing */
67 : bool narrowGrid;
68 : };
69 :
70 : /*!
71 : \union DataRate_t
72 : \brief Common data rate structure
73 : */
74 : union DataRate_t {
75 : /*! \brief Interpretation for LoRa modems */
76 : LoRaRate_t lora;
77 :
78 : /*! \brief Interpretation for FSK modems */
79 : FSKRate_t fsk;
80 :
81 : /*! \brief Interpretation for LR-FHSS modems */
82 : LrFhssRate_t lrFhss;
83 : };
84 :
85 : struct LoRaPacketConfig_t {
86 : /*! \brief LoRa preamble length */
87 : uint16_t preambleLength;
88 :
89 : /*! \brief LoRa implicit header mode */
90 : bool implicitHeader;
91 :
92 : /*! \brief LoRa CRC mode */
93 : bool crcEnabled;
94 :
95 : /*! \brief LoRa low data rate optimization */
96 : bool ldrOptimize;
97 : };
98 :
99 : struct FSKPacketConfig_t {
100 : /*! \brief FSK preamble length in bits */
101 : uint16_t preambleLength;
102 :
103 : /*! \brief Length of the sync word in bits */
104 : uint8_t syncWordLength;
105 :
106 : /*! \brief FSK CRC length in bytes */
107 : uint8_t crcLength;
108 : };
109 :
110 : struct LrFhssPacketConfig_t {
111 : /*! \brief LR-FHSS header count (1 - 4) */
112 : uint8_t hdrCount;
113 : };
114 :
115 : /*!
116 : \union PacketConfig_t
117 : \brief Common packet configuration structure
118 : */
119 : union PacketConfig_t {
120 : LoRaPacketConfig_t lora;
121 : FSKPacketConfig_t fsk;
122 : LrFhssPacketConfig_t lrFhss;
123 : };
124 :
125 : /*!
126 : \struct CADScanConfig_t
127 : \brief Channel scan configuration interpretation in case LoRa CAD is used
128 : */
129 : struct CADScanConfig_t {
130 : /*! \brief Number of symbols to consider signal present */
131 : uint8_t symNum;
132 :
133 : /*! \brief Number of peak detection symbols */
134 : uint8_t detPeak;
135 :
136 : /*! \brief Number of minimum detection symbols */
137 : uint8_t detMin;
138 :
139 : /*! \brief Exit mode after signal detection is complete - module-specific value */
140 : uint8_t exitMode;
141 :
142 : /*! \brief Timeout in microseconds */
143 : RadioLibTime_t timeout;
144 :
145 : /*! \brief Optional IRQ flags to set, bits offset by the value of RADIOLIB_IRQ_ */
146 : RadioLibIrqFlags_t irqFlags;
147 :
148 : /*! \brief Optional IRQ mask to set, bits offset by the value of RADIOLIB_IRQ_ */
149 : RadioLibIrqFlags_t irqMask;
150 : };
151 :
152 : /*!
153 : \struct RSSIScanConfig_t
154 : \brief Channel scan configuration interpretation in case RSSI threshold is used
155 : */
156 : struct RSSIScanConfig_t {
157 : /*! \brief RSSI limit in dBm */
158 : float limit;
159 : };
160 :
161 : /*!
162 : \union ChannelScanConfig_t
163 : \brief Common channel scan configuration structure
164 : */
165 : union ChannelScanConfig_t {
166 : /*! \brief Interpretation for modems that use CAD (usually LoRa modems)*/
167 : CADScanConfig_t cad;
168 :
169 : /*! \brief Interpretation for modems that use RSSI threshold*/
170 : RSSIScanConfig_t rssi;
171 : };
172 :
173 : struct StandbyConfig_t {
174 : /*! \brief Module-specific standby mode configuration. */
175 : uint8_t mode;
176 : };
177 :
178 : struct ReceiveConfig_t {
179 : /*! \brief Raw timeout value. Some modules use this argument to specify operation mode (single vs. continuous receive). */
180 : uint32_t timeout;
181 :
182 : /*! \brief Sets the IRQ flags. */
183 : RadioLibIrqFlags_t irqFlags;
184 :
185 : /*! \brief Sets the mask of IRQ flags that will trigger the radio interrupt pin. */
186 : RadioLibIrqFlags_t irqMask;
187 :
188 : /*! \brief Packet length, needed for some modules under special circumstances (e.g. LoRa implicit header mode). */
189 : size_t len;
190 : };
191 :
192 : struct TransmitConfig_t {
193 : /*! \brief Binary data that will be transmitted. */
194 : const uint8_t* data;
195 :
196 : /*! \brief Length of binary data to transmit (in bytes). */
197 : size_t len;
198 :
199 : /*! \brief Node address to transmit the packet to. Only used in FSK mode. */
200 : uint8_t addr;
201 : };
202 :
203 : struct SleepConfig_t {
204 : /*! \brief Module-specific sleep mode configuration. */
205 : uint8_t mode;
206 : };
207 :
208 : union RadioModeConfig_t {
209 : /*! \brief Interpretation for standby mode */
210 : StandbyConfig_t standby;
211 :
212 : /*! \brief Interpretation for Rx mode */
213 : ReceiveConfig_t receive;
214 :
215 : /*! \brief Interpretation for Tx mode */
216 : TransmitConfig_t transmit;
217 :
218 : /*! \brief Interpretation for scanning */
219 : ChannelScanConfig_t scan;
220 :
221 : /*! \brief Interpretation for sleep mode */
222 : SleepConfig_t sleep;
223 : };
224 :
225 : /*!
226 : \enum ModemType_t
227 : \brief Type of modem, used by setModem.
228 : */
229 : enum ModemType_t {
230 : RADIOLIB_MODEM_FSK = 0,
231 : RADIOLIB_MODEM_LORA,
232 : RADIOLIB_MODEM_LRFHSS,
233 : RADIOLIB_MODEM_NONE, // last entry
234 : };
235 :
236 : /*!
237 : \enum RadioModeType_t
238 : \brief Basic radio operating modes, used by stageMode.
239 : */
240 : enum RadioModeType_t {
241 : RADIOLIB_RADIO_MODE_NONE = 0,
242 : RADIOLIB_RADIO_MODE_STANDBY,
243 : RADIOLIB_RADIO_MODE_RX,
244 : RADIOLIB_RADIO_MODE_TX,
245 : RADIOLIB_RADIO_MODE_SCAN,
246 : RADIOLIB_RADIO_MODE_SLEEP,
247 : };
248 :
249 : #define RADIOLIB_LORA_SYNC_WORD_PRIVATE (0x12UL << 0) // 7 0 LoRa sync word: private network
250 : #define RADIOLIB_LORA_SYNC_WORD_PUBLIC (0x34UL << 0) // 7 0 public network (LoRaWAN)
251 :
252 : #define RADIOLIB_LR_FHSS_CR_5_6 (0x00UL << 0) // 7 0 LR-FHSS coding rate: 5/6
253 : #define RADIOLIB_LR_FHSS_CR_2_3 (0x01UL << 0) // 7 0 2/3
254 : #define RADIOLIB_LR_FHSS_CR_1_2 (0x02UL << 0) // 7 0 1/2
255 : #define RADIOLIB_LR_FHSS_CR_1_3 (0x03UL << 0) // 7 0 1/3
256 : #define RADIOLIB_LR_FHSS_BW_39_06 (0x00UL << 0) // 7 0 LR-FHSS bandwidth: 39.06 kHz
257 : #define RADIOLIB_LR_FHSS_BW_85_94 (0x01UL << 0) // 7 0 85.94 kHz
258 : #define RADIOLIB_LR_FHSS_BW_136_72 (0x02UL << 0) // 7 0 136.72 kHz
259 : #define RADIOLIB_LR_FHSS_BW_183_59 (0x03UL << 0) // 7 0 183.59 kHz
260 : #define RADIOLIB_LR_FHSS_BW_335_94 (0x04UL << 0) // 7 0 335.94 kHz
261 : #define RADIOLIB_LR_FHSS_BW_386_72 (0x05UL << 0) // 7 0 386.72 kHz
262 : #define RADIOLIB_LR_FHSS_BW_722_66 (0x06UL << 0) // 7 0 722.66 kHz
263 : #define RADIOLIB_LR_FHSS_BW_773_44 (0x07UL << 0) // 7 0 773.44 kHz
264 : #define RADIOLIB_LR_FHSS_BW_1523_4 (0x08UL << 0) // 7 0 1523.4 kHz
265 : #define RADIOLIB_LR_FHSS_BW_1574_2 (0x09UL << 0) // 7 0 1574.2 kHz
266 :
267 : #define RADIOLIB_FLRC_BR_2600 (0x00UL << 0) // 7 0 bitrate/bandwidth: 2600 kbps, 2666 kHz
268 : #define RADIOLIB_FLRC_BR_2080 (0x01UL << 0) // 7 0 2080 kbps, 2222 kHz
269 : #define RADIOLIB_FLRC_BR_1300 (0x02UL << 0) // 7 0 1300 kbps, 1333 kHz
270 : #define RADIOLIB_FLRC_BR_1040 (0x03UL << 0) // 7 0 1040 kbps, 1333 kHz
271 : #define RADIOLIB_FLRC_BR_650 (0x04UL << 0) // 7 0 650 kbps, 888 kHz
272 : #define RADIOLIB_FLRC_BR_520 (0x05UL << 0) // 7 0 520 kbps, 769 kHz
273 : #define RADIOLIB_FLRC_BR_325 (0x06UL << 0) // 7 0 325 kbps, 444 kHz
274 : #define RADIOLIB_FLRC_BR_260 (0x07UL << 0) // 7 0 260 kbps, 444 kHz
275 : #define RADIOLIB_FLRC_CR_1_2 (0x00UL << 0) // 7 0 coding rate: 1/2
276 : #define RADIOLIB_FLRC_CR_3_4 (0x01UL << 0) // 7 0 3/4
277 : #define RADIOLIB_FLRC_CR_1_0 (0x02UL << 0) // 7 0 1 (un-coded)
278 : #define RADIOLIB_FLRC_CR_2_3 (0x03UL << 0) // 7 0 2/3
279 :
280 : struct ConfigLoRa_t {
281 : /*! \brief Carrier frequency in MHz. Defaults to 434.0 MHz. */
282 : float frequency = 434.0;
283 : /*! \brief LoRa bandwidth in kHz. Defaults to 125.0 kHz. */
284 : float bandwidth = 125.0;
285 : /*! \brief LoRa spreading factor. Defaults to 9. */
286 : uint8_t spreadingFactor = 9;
287 : /*! \brief LoRa coding rate. Defaults to 7 (coding rate 4/7). Allowed values range from 4 to 8. Note that a value of 4 means no coding,
288 : is undocumented and not recommended without your own FEC. */
289 : uint8_t codingRate = 7;
290 : /*! \brief 1-byte LoRa sync word. Defaults to RADIOLIB_LORA_SYNC_WORD_PRIVATE (0x12). */
291 : uint8_t syncWord = RADIOLIB_LORA_SYNC_WORD_PRIVATE;
292 : /*! \brief Output power in dBm. Defaults to 10 dBm. */
293 : int8_t power = 10;
294 : /*! \brief LoRa preamble length in symbols. Defaults to 8 symbols. */
295 : uint16_t preambleLength = 8;
296 : };
297 :
298 : struct ConfigFSK_t {
299 : /*! \brief Carrier frequency in MHz. Defaults to 434.0 MHz. */
300 : float frequency = 434.0;
301 : /*! \brief FSK bit rate in kbps. Defaults to 4.8 kbps. */
302 : float bitRate = 4.8;
303 : /*! \brief FSK frequency deviation in kHz. Defaults to 5.0 kHz. */
304 : float frequencyDeviation = 5.0;
305 : /*! \brief FSK receiver bandwidth in kHz. Defaults to 125.0 kHz. */
306 : float receiverBandwidth = 125.0;
307 : /*! \brief Output power in dBm. Defaults to 10 dBm. */
308 : int8_t power = 10;
309 : /*! \brief FSK preamble length in bits. Defaults to 16 bits. */
310 : uint16_t preambleLength = 16;
311 : };
312 :
313 : struct ConfigBPSK_t {
314 : /*! \brief Carrier frequency in MHz. Defaults to 434.0 MHz. */
315 : float frequency = 434.0;
316 : /*! \brief FSK bit rate in kbps. Defaults to 4.8 kbps. */
317 : float bitRate = 4.8;
318 : /*! \brief Output power in dBm. Defaults to 10 dBm. */
319 : int8_t power = 10;
320 : };
321 :
322 : struct ConfigOOK_t {
323 : /*! \brief Carrier frequency in MHz. Defaults to 434.0 MHz. */
324 : float frequency = 434.0;
325 : /*! \brief FSK bit rate in kbps. Defaults to 4.8 kbps. */
326 : float bitRate = 4.8;
327 : /*! \brief FSK receiver bandwidth in kHz. Defaults to 125.0 kHz. */
328 : float receiverBandwidth = 125.0;
329 : /*! \brief Output power in dBm. Defaults to 10 dBm. */
330 : int8_t power = 10;
331 : /*! \brief FSK preamble length in bits. Defaults to 16 bits. */
332 : uint16_t preambleLength = 16;
333 : };
334 :
335 : struct ConfigLRFHSS_t {
336 : /*! \brief Carrier frequency in MHz. Defaults to 434.0 MHz. */
337 : float frequency = 434.0;
338 : /*! \brief LR-FHSS bandwidth, one of RADIOLIB_LR_FHSS_BW_* values. Defaults to 722.66 kHz. */
339 : uint8_t bandwidth = RADIOLIB_LR_FHSS_BW_722_66;
340 : /*! \brief LR-FHSS coding rate, one of RADIOLIB_LR_FHSS_CR_* values. Defaults to 2/3 coding rate. */
341 : uint8_t codingRate = RADIOLIB_LR_FHSS_CR_2_3;
342 : /*! \brief Whether to use narrow (3.9 kHz) or wide (25.39 kHz) grid spacing. Defaults to true (narrow/non-FCC) grid. */
343 : bool narrowGrid = true;
344 : /*! \brief Output power in dBm. Defaults to 10 dBm. */
345 : int8_t power = 10;
346 : };
347 :
348 : struct ConfigFLRC_t {
349 : /*! \brief Carrier frequency in MHz. Defaults to 434.0 MHz. */
350 : float frequency = 434.0;
351 : /*! \brief FLRC bit rate in kbps. Defaults to 650 kbps. */
352 : float bitRate = 650.0;
353 : /*! \brief FLRC coding rate. Defaults to RADIOLIB_FLRC_CR_2_3 (coding rate 2/3). */
354 : uint8_t codingRate = RADIOLIB_FLRC_CR_2_3;
355 : /*! \brief Output power in dBm. Defaults to 10 dBm. */
356 : int8_t power = 10;
357 : /*! \brief FLRC preamble length in bits. Defaults to 16 bits. */
358 : uint16_t preambleLength = 16;
359 : /*! \brief Time-bandwidth product of the Gaussian filter to be used for shaping. Defaults to 0.5. */
360 : uint8_t dataShaping = RADIOLIB_SHAPING_0_5;
361 : };
362 :
363 : struct ConfigBLE_t {
364 : /*! \brief Carrier frequency in MHz. Defaults to 2400.0 MHz. */
365 : float frequency = 2400.0;
366 : /*! \brief BLE bit rate in kbps. Defaults to 800 kbps. */
367 : uint16_t bitRate = 800;
368 : /*! \brief BLE frequency deviation in kHz. Defaults to 400.0 kHz. */
369 : float frequencyDeviation = 400.0;
370 : /*! \brief Output power in dBm. Defaults to 10 dBm. */
371 : int8_t power = 10;
372 : /*! \brief Time-bandwidth product of the Gaussian filter to be used for shaping. Defaults to 0.5. */
373 : uint8_t dataShaping = RADIOLIB_SHAPING_0_5;
374 : };
375 :
376 : /*!
377 : \defgroup module_config_vars Module Hardware Configuration Variables
378 : \brief A centralized list of all module configurations which are not part of the various Config_t structures.
379 : When changing these values it has to be done prior to radio initialization using the begin() method!
380 : */
381 :
382 : /*!
383 : \class PhysicalLayer
384 :
385 : \brief Provides common interface for protocols that run on %LoRa/FSK modules, such as RTTY or LoRaWAN.
386 : Also extracts some common module-independent methods. Using this interface class allows to use the protocols
387 : on various modules without much code duplicity. Because this class is used mainly as interface,
388 : all of its virtual members must be implemented in the module class.
389 : */
390 : class PhysicalLayer {
391 : public:
392 :
393 : /*! \brief Frequency step of the synthesizer in Hz. */
394 : float freqStep;
395 :
396 : /*! \brief Maximum length of packet that can be received by the module. */
397 : size_t maxPacketLength;
398 :
399 : /*!
400 : \brief Whether to reset the module on startup. Setting to false allows to restore radio operation
401 : by calling begin after deep sleep mode on some platforms (like ESP32).
402 : \ingroup module_config_vars
403 : */
404 : bool resetOnStartup = true;
405 :
406 : // constructor
407 :
408 : /*!
409 : \brief Default constructor.
410 : */
411 : PhysicalLayer();
412 :
413 : /*!
414 : \brief Default destructor.
415 : */
416 50 : virtual ~PhysicalLayer() = default;
417 :
418 : // basic methods
419 :
420 : #if defined(RADIOLIB_BUILD_ARDUINO)
421 : /*!
422 : \brief Arduino Flash String transmit method.
423 : \param str Pointer to Arduino Flash String that will be transmitted.
424 : \param addr Node address to transmit the packet to. Only used in FSK mode.
425 : \returns \ref status_codes
426 : */
427 : int16_t transmit(__FlashStringHelper* fstr, uint8_t addr = 0);
428 :
429 : /*!
430 : \brief Arduino String transmit method.
431 : \param str Address of Arduino string that will be transmitted.
432 : \param addr Node address to transmit the packet to. Only used in FSK mode.
433 : \returns \ref status_codes
434 : */
435 : int16_t transmit(String& str, uint8_t addr = 0);
436 : #endif
437 :
438 : /*!
439 : \brief C-string transmit method.
440 : \param str C-string that will be transmitted.
441 : \param addr Node address to transmit the packet to. Only used in FSK mode.
442 : \returns \ref status_codes
443 : */
444 : int16_t transmit(const char* str, uint8_t addr = 0);
445 :
446 : /*!
447 : \brief Binary transmit method. Must be implemented in module class.
448 : \param data Binary data that will be transmitted.
449 : \param len Length of binary data to transmit (in bytes).
450 : \param addr Node address to transmit the packet to. Only used in FSK mode.
451 : \returns \ref status_codes
452 : */
453 : virtual int16_t transmit(const uint8_t* data, size_t len, uint8_t addr = 0);
454 :
455 : #if defined(RADIOLIB_BUILD_ARDUINO)
456 : /*!
457 : \brief Arduino String receive method.
458 : \param str Address of Arduino String to save the received data.
459 : \param len Expected number of characters in the message. Leave as 0 if expecting a unknown size packet.
460 : \param timeout Reception timeout in milliseconds. If set to 0,
461 : timeout period will be calculated automatically based on the radio configuration.
462 : \returns \ref status_codes
463 : */
464 : int16_t receive(String& str, size_t len = 0, RadioLibTime_t timeout = 0);
465 : #endif
466 :
467 : /*!
468 : \brief Sets module to sleep.
469 : \returns \ref status_codes
470 : */
471 : virtual int16_t sleep();
472 :
473 : /*!
474 : \brief Sets module to standby.
475 : \returns \ref status_codes
476 : */
477 : virtual int16_t standby();
478 :
479 : /*!
480 : \brief Sets module to a specific standby mode.
481 : \returns \ref status_codes
482 : */
483 : virtual int16_t standby(uint8_t mode);
484 :
485 : /*!
486 : \brief Sets module to received mode using its default configuration.
487 : \returns \ref status_codes
488 : */
489 : virtual int16_t startReceive();
490 :
491 : /*!
492 : \brief Interrupt-driven receive method. A DIO pin will be activated when full packet is received.
493 : Must be implemented in module class.
494 : \param timeout Raw timeout value. Some modules use this argument to specify operation mode
495 : (single vs. continuous receive).
496 : \param irqFlags Sets the IRQ flags.
497 : \param irqMask Sets the mask of IRQ flags that will trigger the radio interrupt pin.
498 : \param len Packet length, needed for some modules under special circumstances (e.g. LoRa implicit header mode).
499 : \returns \ref status_codes
500 : */
501 : virtual int16_t startReceive(uint32_t timeout, RadioLibIrqFlags_t irqFlags = RADIOLIB_IRQ_RX_DEFAULT_FLAGS, RadioLibIrqFlags_t irqMask = RADIOLIB_IRQ_RX_DEFAULT_MASK, size_t len = 0);
502 :
503 : /*!
504 : \brief Binary receive method. Must be implemented in module class.
505 : \param data Pointer to array to save the received binary data.
506 : \param len Packet length, needed for some modules under special circumstances (e.g. LoRa implicit header mode).
507 : \param timeout Reception timeout in milliseconds. If set to 0,
508 : timeout period will be calculated automatically based on the radio configuration.
509 : \returns \ref status_codes
510 : */
511 : virtual int16_t receive(uint8_t* data, size_t len, RadioLibTime_t timeout = 0);
512 :
513 : #if defined(RADIOLIB_BUILD_ARDUINO)
514 : /*!
515 : \brief Interrupt-driven Arduino String transmit method. Unlike the standard transmit method, this one is non-blocking.
516 : Interrupt pin will be activated when transmission finishes.
517 : \param str Address of Arduino String that will be transmitted.
518 : \param addr Node address to transmit the packet to. Only used in FSK mode.
519 : \returns \ref status_codes
520 : */
521 : int16_t startTransmit(String& str, uint8_t addr = 0);
522 : #endif
523 :
524 : /*!
525 : \brief Interrupt-driven Arduino String transmit method. Unlike the standard transmit method, this one is non-blocking.
526 : Interrupt pin will be activated when transmission finishes.
527 : \param str C-string that will be transmitted.
528 : \param addr Node address to transmit the packet to. Only used in FSK mode.
529 : \returns \ref status_codes
530 : */
531 : int16_t startTransmit(const char* str, uint8_t addr = 0);
532 :
533 : /*!
534 : \brief Interrupt-driven binary transmit method.
535 : \param data Binary data that will be transmitted.
536 : \param len Length of binary data to transmit (in bytes).
537 : \param addr Node address to transmit the packet to. Only used in FSK mode.
538 : \returns \ref status_codes
539 : */
540 : virtual int16_t startTransmit(const uint8_t* data, size_t len, uint8_t addr = 0);
541 :
542 : /*!
543 : \brief Clean up after transmission is done.
544 : \returns \ref status_codes
545 : */
546 : virtual int16_t finishTransmit();
547 :
548 : /*!
549 : \brief Clean up after reception is done.
550 : \returns \ref status_codes
551 : */
552 : virtual int16_t finishReceive();
553 :
554 : #if defined(RADIOLIB_BUILD_ARDUINO)
555 : /*!
556 : \brief Reads data that was received after calling startReceive method.
557 : \param str Address of Arduino String to save the received data.
558 : \param len Expected number of characters in the message. When set to 0, the packet length will be retrieved
559 : automatically. When more bytes than received are requested, only the number of bytes requested will be returned.
560 : \returns \ref status_codes
561 : */
562 : int16_t readData(String& str, size_t len = 0);
563 : #endif
564 :
565 : /*!
566 : \brief Reads data that was received after calling startReceive method.
567 : \param data Pointer to array to save the received binary data.
568 : \param len Number of bytes that will be read. When set to 0, the packet length will be retrieved automatically.
569 : When more bytes than received are requested, only the number of bytes requested will be returned.
570 : \returns \ref status_codes
571 : */
572 : virtual int16_t readData(uint8_t* data, size_t len);
573 :
574 : /*!
575 : \brief Enables direct transmission mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module class.
576 : While in direct mode, the module will not be able to transmit or receive packets. Can only be activated in FSK mode.
577 : \param frf 24-bit raw frequency value to start transmitting at. Required for quick frequency shifts in RTTY.
578 : \returns \ref status_codes
579 : */
580 : virtual int16_t transmitDirect(uint32_t frf = 0);
581 :
582 : /*!
583 : \brief Enables direct reception mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module class.
584 : While in direct mode, the module will not be able to transmit or receive packets. Can only be activated in FSK mode.
585 : \returns \ref status_codes
586 : */
587 : virtual int16_t receiveDirect();
588 :
589 : // configuration methods
590 :
591 : /*!
592 : \brief Sets carrier frequency. Must be implemented in module class.
593 : \param freq Carrier frequency to be set in MHz.
594 : \returns \ref status_codes
595 : */
596 : virtual int16_t setFrequency(float freq);
597 :
598 : /*!
599 : \brief Sets FSK bit rate. Only available in FSK mode. Must be implemented in module class.
600 : \param br Bit rate to be set (in kbps).
601 : \returns \ref status_codes
602 : */
603 : virtual int16_t setBitRate(float br);
604 :
605 : /*!
606 : \brief Sets FSK frequency deviation from carrier frequency. Only available in FSK mode.
607 : Must be implemented in module class.
608 : \param freqDev Frequency deviation to be set (in kHz).
609 : \returns \ref status_codes
610 : */
611 : virtual int16_t setFrequencyDeviation(float freqDev);
612 :
613 : /*!
614 : \brief Sets GFSK data shaping. Only available in FSK mode. Must be implemented in module class.
615 : \param sh Shaping to be set. See \ref config_shaping for possible values.
616 : \returns \ref status_codes
617 : */
618 : virtual int16_t setDataShaping(uint8_t sh);
619 :
620 : /*!
621 : \brief Sets FSK data encoding. Only available in FSK mode. Must be implemented in module class.
622 : \param encoding Encoding to be used. See \ref config_encoding for possible values.
623 : \returns \ref status_codes
624 : */
625 : virtual int16_t setEncoding(uint8_t encoding);
626 :
627 : /*!
628 : \brief Set IQ inversion. Must be implemented in module class if the module supports it.
629 : \param enable True to use inverted IQ, false for non-inverted.
630 : \returns \ref status_codes
631 : */
632 : virtual int16_t invertIQ(bool enable);
633 :
634 : /*!
635 : \brief Set output power. Must be implemented in module class if the module supports it.
636 : \param power Output power in dBm. The allowed range depends on the module used.
637 : \returns \ref status_codes
638 : */
639 : virtual int16_t setOutputPower(int8_t power);
640 :
641 : /*!
642 : \brief Check if output power is configurable. Must be implemented in module class if the module supports it.
643 : \param power Output power in dBm. The allowed range depends on the module used.
644 : \param clipped Clipped output power value to what is possible within the module's range.
645 : \returns \ref status_codes
646 : */
647 : virtual int16_t checkOutputPower(int8_t power, int8_t* clipped);
648 :
649 : /*!
650 : \brief Set sync word. Must be implemented in module class if the module supports it.
651 : \param sync Pointer to the sync word.
652 : \param len Sync word length in bytes. Maximum length depends on the module used.
653 : \returns \ref status_codes
654 : */
655 : virtual int16_t setSyncWord(uint8_t* sync, size_t len);
656 :
657 : /*!
658 : \brief Set preamble length. Must be implemented in module class if the module supports it.
659 : \param len Preamble length in bytes. Maximum length depends on the module used.
660 : \returns \ref status_codes
661 : */
662 : virtual int16_t setPreambleLength(size_t len);
663 :
664 : /*!
665 : \brief Set data rate. Must be implemented in module class if the module supports it.
666 : \param dr Data rate struct.
667 : \param modem The modem corresponding to the requested datarate (FSK, LoRa or LR-FHSS).
668 : Defaults to currently active modem if not supplied.
669 : \returns \ref status_codes
670 : */
671 : virtual int16_t setDataRate(DataRate_t dr, ModemType_t modem = RADIOLIB_MODEM_NONE);
672 :
673 : /*!
674 : \brief Check the data rate can be configured by this module. Must be implemented in module class if the module supports it.
675 : \param dr Data rate struct.
676 : \param modem The modem corresponding to the requested datarate (FSK, LoRa or LR-FHSS).
677 : Defaults to currently active modem if not supplied.
678 : \returns \ref status_codes
679 : */
680 : virtual int16_t checkDataRate(DataRate_t dr, ModemType_t modem = RADIOLIB_MODEM_NONE);
681 :
682 : /*!
683 : \brief Query modem for the packet length of received payload. Must be implemented in module class.
684 : \param update Update received packet length. Will return cached value when set to false.
685 : \returns Length of last received packet in bytes.
686 : */
687 : virtual size_t getPacketLength(bool update = true);
688 :
689 : /*!
690 : \brief Gets RSSI (Received Signal Strength Indicator) of the last received packet.
691 : \returns RSSI of the last received packet in dBm.
692 : */
693 : virtual float getRSSI();
694 :
695 : /*!
696 : \brief Gets SNR (Signal to Noise Ratio) of the last received packet. Only available for LoRa modem.
697 : \returns SNR of the last received packet in dB.
698 : */
699 : virtual float getSNR();
700 :
701 : /*!
702 : \brief Calculate the expected time-on-air for a given modem, data rate, packet configuration and payload size.
703 : \param modem Modem type.
704 : \param dr Data rate.
705 : \param pc Packet config.
706 : \param len Payload length in bytes.
707 : \returns Expected time-on-air in microseconds.
708 : */
709 : virtual RadioLibTime_t calculateTimeOnAir(ModemType_t modem, DataRate_t dr, PacketConfig_t pc, size_t len);
710 :
711 : /*!
712 : \brief Get expected time-on-air for a given size of payload
713 : \param len Payload length in bytes.
714 : \returns Expected time-on-air in microseconds.
715 : */
716 : virtual RadioLibTime_t getTimeOnAir(size_t len);
717 :
718 : /*!
719 : \brief Calculate the timeout value for this specific module / series
720 : (in number of symbols or units of time).
721 : \param timeoutUs Timeout in microseconds to listen for.
722 : \returns Timeout value in a unit that is specific for the used module.
723 : */
724 : virtual RadioLibTime_t calculateRxTimeout(RadioLibTime_t timeoutUs);
725 :
726 : /*!
727 : \brief Convert from radio-agnostic IRQ flags to radio-specific flags.
728 : \param irq Radio-agnostic IRQ flags.
729 : \returns Flags for a specific radio module.
730 : */
731 : uint32_t getIrqMapped(RadioLibIrqFlags_t irq);
732 :
733 : /*!
734 : \brief Check whether a specific IRQ bit is set (e.g. RxTimeout, CadDone).
735 : \param irq IRQ type to check, one of RADIOLIB_IRQ_*.
736 : \returns 1 when requested IRQ is set, 0 when it is not or RADIOLIB_ERR_UNSUPPORTED if the IRQ is not supported.
737 : */
738 : int16_t checkIrq(RadioLibIrqType_t irq);
739 :
740 : /*!
741 : \brief Set interrupt on specific IRQ bit(s) (e.g. RxTimeout, CadDone).
742 : Keep in mind that not all radio modules support all RADIOLIB_IRQ_ flags!
743 : \param irq Flags to set, multiple bits may be enabled. IRQ to enable corresponds to the bit index (RadioLibIrq_t).
744 : For example, if bit 0 is enabled, the module will enable its RADIOLIB_IRQ_TX_DONE (if it is supported).
745 : \returns \ref status_codes
746 : */
747 : int16_t setIrq(RadioLibIrqFlags_t irq);
748 :
749 : /*!
750 : \brief Clear interrupt on a specific IRQ bit (e.g. RxTimeout, CadDone).
751 : Keep in mind that not all radio modules support all RADIOLIB_IRQ_ flags!
752 : \param irq Flags to set, multiple bits may be enabled. IRQ to enable corresponds to the bit index (RadioLibIrq_t).
753 : For example, if bit 0 is enabled, the module will enable its RADIOLIB_IRQ_TX_DONE (if it is supported).
754 : \returns \ref status_codes
755 : */
756 : int16_t clearIrq(RadioLibIrqFlags_t irq);
757 :
758 : /*!
759 : \brief Read currently active IRQ flags.
760 : Must be implemented in module class.
761 : \returns IRQ flags.
762 : */
763 : virtual uint32_t getIrqFlags();
764 :
765 : /*!
766 : \brief Set interrupt on DIO1 to be sent on a specific IRQ bit (e.g. RxTimeout, CadDone).
767 : Must be implemented in module class.
768 : \param irq Module-specific IRQ flags.
769 : \returns \ref status_codes
770 : */
771 : virtual int16_t setIrqFlags(uint32_t irq);
772 :
773 : /*!
774 : \brief Clear interrupt on a specific IRQ bit (e.g. RxTimeout, CadDone).
775 : Must be implemented in module class.
776 : \param irq Module-specific IRQ flags.
777 : \returns \ref status_codes
778 : */
779 : virtual int16_t clearIrqFlags(uint32_t irq);
780 :
781 : /*!
782 : \brief Interrupt-driven channel activity detection method. Interrupt will be activated
783 : when packet is detected. Must be implemented in module class.
784 : \returns \ref status_codes
785 : */
786 : virtual int16_t startChannelScan();
787 :
788 : /*!
789 : \brief Interrupt-driven channel activity detection method. interrupt will be activated
790 : when packet is detected. Must be implemented in module class.
791 : \param config Scan configuration structure. Interpretation depends on currently active modem.
792 : \returns \ref status_codes
793 : */
794 : virtual int16_t startChannelScan(const ChannelScanConfig_t &config);
795 :
796 : /*!
797 : \brief Read the channel scan result
798 : \returns \ref status_codes
799 : */
800 : virtual int16_t getChannelScanResult();
801 :
802 : /*!
803 : \brief Check whether the current communication channel is free or occupied. Performs CAD for LoRa modules,
804 : or RSSI measurement for FSK modules.
805 : \returns RADIOLIB_CHANNEL_FREE when channel is free,
806 : RADIOLIB_PREAMBLE_DETECTEDwhen occupied or other \ref status_codes.
807 : */
808 : virtual int16_t scanChannel();
809 :
810 : /*!
811 : \brief Check whether the current communication channel is free or occupied. Performs CAD for LoRa modules,
812 : or RSSI measurement for FSK modules.
813 : \param config Scan configuration structure. Interpretation depends on currently active modem.
814 : \returns RADIOLIB_CHANNEL_FREE when channel is free,
815 : RADIOLIB_PREAMBLE_DETECTEDwhen occupied or other \ref status_codes.
816 : */
817 : virtual int16_t scanChannel(const ChannelScanConfig_t &config);
818 :
819 : /*!
820 : \brief Get truly random number in range 0 - max.
821 : \param max The maximum value of the random number (non-inclusive).
822 : \returns Random number.
823 : */
824 : int32_t random(int32_t max);
825 :
826 : /*!
827 : \brief Get truly random number in range min - max.
828 : \param min The minimum value of the random number (inclusive).
829 : \param max The maximum value of the random number (non-inclusive).
830 : \returns Random number.
831 : */
832 : int32_t random(int32_t min, int32_t max);
833 :
834 : /*!
835 : \brief Get one truly random byte from RSSI noise. Must be implemented in module class.
836 : \returns TRNG byte.
837 : */
838 : virtual uint8_t randomByte();
839 :
840 : /*!
841 : \brief Configure module parameters for direct modes. Must be called prior to "ham" modes like RTTY or AX.25.
842 : Only available in FSK mode.
843 : \returns \ref status_codes
844 : */
845 : int16_t startDirect();
846 :
847 : #if !RADIOLIB_EXCLUDE_DIRECT_RECEIVE
848 : /*!
849 : \brief Set sync word to be used to determine start of packet in direct reception mode.
850 : \param syncWord Sync word bits.
851 : \param len Sync word length in bits. Set to zero to disable sync word matching.
852 : \returns \ref status_codes
853 : */
854 : int16_t setDirectSyncWord(uint32_t syncWord, uint8_t len);
855 :
856 : /*!
857 : \brief Set interrupt service routine function to call when data bit is received in direct mode.
858 : Must be implemented in module class.
859 : \param func Pointer to interrupt service routine.
860 : */
861 : virtual void setDirectAction(void (*func)(void));
862 :
863 : /*!
864 : \brief Function to read and process data bit in direct reception mode. Must be implemented in module class.
865 : \param pin Pin on which to read.
866 : */
867 : virtual void readBit(uint32_t pin);
868 :
869 : /*!
870 : \brief Get the number of direct mode bytes currently available in buffer.
871 : \returns Number of available bytes.
872 : */
873 : int16_t available();
874 :
875 : /*!
876 : \brief Forcefully drop synchronization.
877 : */
878 : void dropSync();
879 :
880 : /*!
881 : \brief Get data from direct mode buffer.
882 : \param drop Drop synchronization on read - next reading will require waiting for the sync word again.
883 : Defaults to true.
884 : \returns Byte from direct mode buffer.
885 : */
886 : uint8_t read(bool drop = true);
887 : #endif
888 :
889 : /*!
890 : \brief Sets interrupt service routine to call when a packet is received.
891 : \param func ISR to call.
892 : */
893 : virtual void setPacketReceivedAction(void (*func)(void));
894 :
895 : /*!
896 : \brief Clears interrupt service routine to call when a packet is received.
897 : */
898 : virtual void clearPacketReceivedAction();
899 :
900 : /*!
901 : \brief Sets interrupt service routine to call when a packet is sent.
902 : \param func ISR to call.
903 : */
904 : virtual void setPacketSentAction(void (*func)(void));
905 :
906 : /*!
907 : \brief Clears interrupt service routine to call when a packet is sent.
908 : */
909 : virtual void clearPacketSentAction();
910 :
911 : /*!
912 : \brief Sets interrupt service routine to call when a channel scan is finished.
913 : \param func ISR to call.
914 : */
915 : virtual void setChannelScanAction(void (*func)(void));
916 :
917 : /*!
918 : \brief Clears interrupt service routine to call when a channel scan is finished.
919 : */
920 : virtual void clearChannelScanAction();
921 :
922 : /*!
923 : \brief Set modem for the radio to use. Will perform full reset and reconfigure the radio
924 : using its default parameters.
925 : \param modem Modem type to set. Not all modems are implemented by all radio modules!
926 : \returns \ref status_codes
927 : */
928 : virtual int16_t setModem(ModemType_t modem);
929 :
930 : /*!
931 : \brief Get modem currently in use by the radio.
932 : \param modem Pointer to a variable to save the retrieved configuration into.
933 : \returns \ref status_codes
934 : */
935 : virtual int16_t getModem(ModemType_t* modem);
936 :
937 : /*!
938 : \brief Stage mode of the radio to be launched later using launchMode.
939 : \param mode Radio mode to prepare.
940 : \param cfg Configuration of this mode (mode-dependent).
941 : \returns \ref status_codes
942 : */
943 : virtual int16_t stageMode(RadioModeType_t mode, RadioModeConfig_t* cfg);
944 :
945 : /*!
946 : \brief Launch previously staged mode.
947 : \returns \ref status_codes
948 : */
949 : virtual int16_t launchMode();
950 :
951 : #if RADIOLIB_INTERRUPT_TIMING
952 :
953 : /*!
954 : \brief Set function to be called to set up the timing interrupt.
955 : For details, see https://github.com/jgromes/RadioLib/wiki/Interrupt-Based-Timing
956 : \param func Setup function to be called, with one argument (pulse length in microseconds).
957 : */
958 : void setInterruptSetup(void (*func)(uint32_t));
959 :
960 : /*!
961 : \brief Set timing interrupt flag.
962 : For details, see https://github.com/jgromes/RadioLib/wiki/Interrupt-Based-Timing
963 : */
964 : void setTimerFlag();
965 :
966 : #endif
967 :
968 : /*!
969 : \brief Calculates sleep and wake cycles for startReceiveDutyCycle methods so that the receiver should not miss any messages.
970 : Useful only for LoRa modems.
971 : \param txPreLen Expected preamble length of the messages to receive.
972 : If set to zero, the receiver preamble length will be used.
973 : This value cannot exceed the configured preamble length. If the sender preamble length is variable, set the
974 : maximum expected length by calling setPreambleLength(maximumExpectedLength) prior to this method, and use the
975 : minimum expected length here.
976 : \param rxPreLen Currently configured preamble length of the receiver (this radio).
977 : \param minSymbols Ensure that the unit will catch at least this many symbols of any preamble of the specified senderPreambleLength.
978 : To reliably latch a preamble, the receiver requires 8 symbols for SF7-12 and 12 symbols for SF5-6.
979 : If set to zero, the minimum required symbols will be used.
980 : \param dr Pointer to structure holding LoRa data rate information (only spreading factor and bandwidth are used).
981 : \param wakePeriod Pointer to variable where the calculated wake period in microseconds will be stored.
982 : \param sleePeriod Pointer to variable where the calculated sleep period in microseconds will be stored.
983 : \returns \ref status_codes
984 : */
985 : int16_t calculateRxDutyCycle(size_t txPreLen, size_t rxPreLen, uint16_t minSymbols, DataRate_t* dr, uint32_t* wakePeriod, uint32_t* sleepPeriod);
986 :
987 : #if !RADIOLIB_GODMODE
988 : protected:
989 : #endif
990 : uint32_t irqMap[10] = { 0 };
991 : RadioModeType_t stagedMode = RADIOLIB_RADIO_MODE_NONE;
992 :
993 : #if !RADIOLIB_EXCLUDE_DIRECT_RECEIVE
994 : void updateDirectBuffer(uint8_t bit);
995 : #endif
996 :
997 : #if !RADIOLIB_GODMODE
998 : private:
999 : #endif
1000 :
1001 : #if !RADIOLIB_EXCLUDE_DIRECT_RECEIVE
1002 : uint8_t bufferBitPos = 0;
1003 : uint8_t bufferWritePos = 0;
1004 : uint8_t bufferReadPos = 0;
1005 : uint8_t buffer[RADIOLIB_STATIC_ARRAY_SIZE] = { 0 };
1006 : uint32_t syncBuffer = 0;
1007 : uint32_t directSyncWord = 0;
1008 : uint8_t directSyncWordLen = 0;
1009 : uint32_t directSyncWordMask = 0;
1010 : bool gotSync = false;
1011 : #endif
1012 :
1013 : virtual Module* getMod() = 0;
1014 :
1015 : // allow specific classes access the private getMod method
1016 : friend class AFSKClient;
1017 : friend class RTTYClient;
1018 : friend class MorseClient;
1019 : friend class HellClient;
1020 : friend class SSTVClient;
1021 : friend class AX25Client;
1022 : friend class FSK4Client;
1023 : friend class PagerClient;
1024 : friend class BellClient;
1025 : friend class FT8Client;
1026 : friend class LoRaWANNode;
1027 : friend class M17Client;
1028 : };
1029 :
1030 : #endif
|
