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 : /*!
250 : \class PhysicalLayer
251 :
252 : \brief Provides common interface for protocols that run on %LoRa/FSK modules, such as RTTY or LoRaWAN.
253 : Also extracts some common module-independent methods. Using this interface class allows to use the protocols
254 : on various modules without much code duplicity. Because this class is used mainly as interface,
255 : all of its virtual members must be implemented in the module class.
256 : */
257 : class PhysicalLayer {
258 : public:
259 :
260 : /*! \brief Frequency step of the synthesizer in Hz. */
261 : float freqStep;
262 :
263 : /*! \brief Maximum length of packet that can be received by the module. */
264 : size_t maxPacketLength;
265 :
266 : // constructor
267 :
268 : /*!
269 : \brief Default constructor.
270 : */
271 : PhysicalLayer();
272 :
273 : /*!
274 : \brief Default destructor.
275 : */
276 50 : virtual ~PhysicalLayer() = default;
277 :
278 : // basic methods
279 :
280 : #if defined(RADIOLIB_BUILD_ARDUINO)
281 : /*!
282 : \brief Arduino Flash String transmit method.
283 : \param str Pointer to Arduino Flash String that will be transmitted.
284 : \param addr Node address to transmit the packet to. Only used in FSK mode.
285 : \returns \ref status_codes
286 : */
287 : int16_t transmit(__FlashStringHelper* fstr, uint8_t addr = 0);
288 :
289 : /*!
290 : \brief Arduino String transmit method.
291 : \param str Address of Arduino string that will be transmitted.
292 : \param addr Node address to transmit the packet to. Only used in FSK mode.
293 : \returns \ref status_codes
294 : */
295 : int16_t transmit(String& str, uint8_t addr = 0);
296 : #endif
297 :
298 : /*!
299 : \brief C-string transmit method.
300 : \param str C-string that will be transmitted.
301 : \param addr Node address to transmit the packet to. Only used in FSK mode.
302 : \returns \ref status_codes
303 : */
304 : int16_t transmit(const char* str, uint8_t addr = 0);
305 :
306 : /*!
307 : \brief Binary transmit method. Must be implemented in module class.
308 : \param data Binary data that will be transmitted.
309 : \param len Length of binary data to transmit (in bytes).
310 : \param addr Node address to transmit the packet to. Only used in FSK mode.
311 : \returns \ref status_codes
312 : */
313 : virtual int16_t transmit(const uint8_t* data, size_t len, uint8_t addr = 0);
314 :
315 : #if defined(RADIOLIB_BUILD_ARDUINO)
316 : /*!
317 : \brief Arduino String receive method.
318 : \param str Address of Arduino String to save the received data.
319 : \param len Expected number of characters in the message. Leave as 0 if expecting a unknown size packet.
320 : \param timeout Reception timeout in milliseconds. If set to 0,
321 : timeout period will be calculated automatically based on the radio configuration.
322 : \returns \ref status_codes
323 : */
324 : int16_t receive(String& str, size_t len = 0, RadioLibTime_t timeout = 0);
325 : #endif
326 :
327 : /*!
328 : \brief Sets module to sleep.
329 : \returns \ref status_codes
330 : */
331 : virtual int16_t sleep();
332 :
333 : /*!
334 : \brief Sets module to standby.
335 : \returns \ref status_codes
336 : */
337 : virtual int16_t standby();
338 :
339 : /*!
340 : \brief Sets module to a specific standby mode.
341 : \returns \ref status_codes
342 : */
343 : virtual int16_t standby(uint8_t mode);
344 :
345 : /*!
346 : \brief Sets module to received mode using its default configuration.
347 : \returns \ref status_codes
348 : */
349 : virtual int16_t startReceive();
350 :
351 : /*!
352 : \brief Interrupt-driven receive method. A DIO pin will be activated when full packet is received.
353 : Must be implemented in module class.
354 : \param timeout Raw timeout value. Some modules use this argument to specify operation mode
355 : (single vs. continuous receive).
356 : \param irqFlags Sets the IRQ flags.
357 : \param irqMask Sets the mask of IRQ flags that will trigger the radio interrupt pin.
358 : \param len Packet length, needed for some modules under special circumstances (e.g. LoRa implicit header mode).
359 : \returns \ref status_codes
360 : */
361 : 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);
362 :
363 : /*!
364 : \brief Binary receive method. Must be implemented in module class.
365 : \param data Pointer to array to save the received binary data.
366 : \param len Packet length, needed for some modules under special circumstances (e.g. LoRa implicit header mode).
367 : \param timeout Reception timeout in milliseconds. If set to 0,
368 : timeout period will be calculated automatically based on the radio configuration.
369 : \returns \ref status_codes
370 : */
371 : virtual int16_t receive(uint8_t* data, size_t len, RadioLibTime_t timeout = 0);
372 :
373 : #if defined(RADIOLIB_BUILD_ARDUINO)
374 : /*!
375 : \brief Interrupt-driven Arduino String transmit method. Unlike the standard transmit method, this one is non-blocking.
376 : Interrupt pin will be activated when transmission finishes.
377 : \param str Address of Arduino String that will be transmitted.
378 : \param addr Node address to transmit the packet to. Only used in FSK mode.
379 : \returns \ref status_codes
380 : */
381 : int16_t startTransmit(String& str, uint8_t addr = 0);
382 : #endif
383 :
384 : /*!
385 : \brief Interrupt-driven Arduino String transmit method. Unlike the standard transmit method, this one is non-blocking.
386 : Interrupt pin will be activated when transmission finishes.
387 : \param str C-string that will be transmitted.
388 : \param addr Node address to transmit the packet to. Only used in FSK mode.
389 : \returns \ref status_codes
390 : */
391 : int16_t startTransmit(const char* str, uint8_t addr = 0);
392 :
393 : /*!
394 : \brief Interrupt-driven binary transmit method.
395 : \param data Binary data that will be transmitted.
396 : \param len Length of binary data to transmit (in bytes).
397 : \param addr Node address to transmit the packet to. Only used in FSK mode.
398 : \returns \ref status_codes
399 : */
400 : virtual int16_t startTransmit(const uint8_t* data, size_t len, uint8_t addr = 0);
401 :
402 : /*!
403 : \brief Clean up after transmission is done.
404 : \returns \ref status_codes
405 : */
406 : virtual int16_t finishTransmit();
407 :
408 : /*!
409 : \brief Clean up after reception is done.
410 : \returns \ref status_codes
411 : */
412 : virtual int16_t finishReceive();
413 :
414 : #if defined(RADIOLIB_BUILD_ARDUINO)
415 : /*!
416 : \brief Reads data that was received after calling startReceive method.
417 : \param str Address of Arduino String to save the received data.
418 : \param len Expected number of characters in the message. When set to 0, the packet length will be retrieved
419 : automatically. When more bytes than received are requested, only the number of bytes requested will be returned.
420 : \returns \ref status_codes
421 : */
422 : int16_t readData(String& str, size_t len = 0);
423 : #endif
424 :
425 : /*!
426 : \brief Reads data that was received after calling startReceive method.
427 : \param data Pointer to array to save the received binary data.
428 : \param len Number of bytes that will be read. When set to 0, the packet length will be retrieved automatically.
429 : When more bytes than received are requested, only the number of bytes requested will be returned.
430 : \returns \ref status_codes
431 : */
432 : virtual int16_t readData(uint8_t* data, size_t len);
433 :
434 : /*!
435 : \brief Enables direct transmission mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module class.
436 : While in direct mode, the module will not be able to transmit or receive packets. Can only be activated in FSK mode.
437 : \param frf 24-bit raw frequency value to start transmitting at. Required for quick frequency shifts in RTTY.
438 : \returns \ref status_codes
439 : */
440 : virtual int16_t transmitDirect(uint32_t frf = 0);
441 :
442 : /*!
443 : \brief Enables direct reception mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module class.
444 : While in direct mode, the module will not be able to transmit or receive packets. Can only be activated in FSK mode.
445 : \returns \ref status_codes
446 : */
447 : virtual int16_t receiveDirect();
448 :
449 : // configuration methods
450 :
451 : /*!
452 : \brief Sets carrier frequency. Must be implemented in module class.
453 : \param freq Carrier frequency to be set in MHz.
454 : \returns \ref status_codes
455 : */
456 : virtual int16_t setFrequency(float freq);
457 :
458 : /*!
459 : \brief Sets FSK bit rate. Only available in FSK mode. Must be implemented in module class.
460 : \param br Bit rate to be set (in kbps).
461 : \returns \ref status_codes
462 : */
463 : virtual int16_t setBitRate(float br);
464 :
465 : /*!
466 : \brief Sets FSK frequency deviation from carrier frequency. Only available in FSK mode.
467 : Must be implemented in module class.
468 : \param freqDev Frequency deviation to be set (in kHz).
469 : \returns \ref status_codes
470 : */
471 : virtual int16_t setFrequencyDeviation(float freqDev);
472 :
473 : /*!
474 : \brief Sets GFSK data shaping. Only available in FSK mode. Must be implemented in module class.
475 : \param sh Shaping to be set. See \ref config_shaping for possible values.
476 : \returns \ref status_codes
477 : */
478 : virtual int16_t setDataShaping(uint8_t sh);
479 :
480 : /*!
481 : \brief Sets FSK data encoding. Only available in FSK mode. Must be implemented in module class.
482 : \param encoding Encoding to be used. See \ref config_encoding for possible values.
483 : \returns \ref status_codes
484 : */
485 : virtual int16_t setEncoding(uint8_t encoding);
486 :
487 : /*!
488 : \brief Set IQ inversion. Must be implemented in module class if the module supports it.
489 : \param enable True to use inverted IQ, false for non-inverted.
490 : \returns \ref status_codes
491 : */
492 : virtual int16_t invertIQ(bool enable);
493 :
494 : /*!
495 : \brief Set output power. Must be implemented in module class if the module supports it.
496 : \param power Output power in dBm. The allowed range depends on the module used.
497 : \returns \ref status_codes
498 : */
499 : virtual int16_t setOutputPower(int8_t power);
500 :
501 : /*!
502 : \brief Check if output power is configurable. Must be implemented in module class if the module supports it.
503 : \param power Output power in dBm. The allowed range depends on the module used.
504 : \param clipped Clipped output power value to what is possible within the module's range.
505 : \returns \ref status_codes
506 : */
507 : virtual int16_t checkOutputPower(int8_t power, int8_t* clipped);
508 :
509 : /*!
510 : \brief Set sync word. Must be implemented in module class if the module supports it.
511 : \param sync Pointer to the sync word.
512 : \param len Sync word length in bytes. Maximum length depends on the module used.
513 : \returns \ref status_codes
514 : */
515 : virtual int16_t setSyncWord(uint8_t* sync, size_t len);
516 :
517 : /*!
518 : \brief Set preamble length. Must be implemented in module class if the module supports it.
519 : \param len Preamble length in bytes. Maximum length depends on the module used.
520 : \returns \ref status_codes
521 : */
522 : virtual int16_t setPreambleLength(size_t len);
523 :
524 : /*!
525 : \brief Set data rate. Must be implemented in module class if the module supports it.
526 : \param dr Data rate struct.
527 : \param modem The modem corresponding to the requested datarate (FSK, LoRa or LR-FHSS).
528 : Defaults to currently active modem if not supplied.
529 : \returns \ref status_codes
530 : */
531 : virtual int16_t setDataRate(DataRate_t dr, ModemType_t modem = RADIOLIB_MODEM_NONE);
532 :
533 : /*!
534 : \brief Check the data rate can be configured by this module. Must be implemented in module class if the module supports it.
535 : \param dr Data rate struct.
536 : \param modem The modem corresponding to the requested datarate (FSK, LoRa or LR-FHSS).
537 : Defaults to currently active modem if not supplied.
538 : \returns \ref status_codes
539 : */
540 : virtual int16_t checkDataRate(DataRate_t dr, ModemType_t modem = RADIOLIB_MODEM_NONE);
541 :
542 : /*!
543 : \brief Query modem for the packet length of received payload. Must be implemented in module class.
544 : \param update Update received packet length. Will return cached value when set to false.
545 : \returns Length of last received packet in bytes.
546 : */
547 : virtual size_t getPacketLength(bool update = true);
548 :
549 : /*!
550 : \brief Gets RSSI (Recorded Signal Strength Indicator) of the last received packet.
551 : \returns RSSI of the last received packet in dBm.
552 : */
553 : virtual float getRSSI();
554 :
555 : /*!
556 : \brief Gets SNR (Signal to Noise Ratio) of the last received packet. Only available for LoRa modem.
557 : \returns SNR of the last received packet in dB.
558 : */
559 : virtual float getSNR();
560 :
561 : /*!
562 : \brief Calculate the expected time-on-air for a given modem, data rate, packet configuration and payload size.
563 : \param modem Modem type.
564 : \param dr Data rate.
565 : \param pc Packet config.
566 : \param len Payload length in bytes.
567 : \returns Expected time-on-air in microseconds.
568 : */
569 : virtual RadioLibTime_t calculateTimeOnAir(ModemType_t modem, DataRate_t dr, PacketConfig_t pc, size_t len);
570 :
571 : /*!
572 : \brief Get expected time-on-air for a given size of payload
573 : \param len Payload length in bytes.
574 : \returns Expected time-on-air in microseconds.
575 : */
576 : virtual RadioLibTime_t getTimeOnAir(size_t len);
577 :
578 : /*!
579 : \brief Calculate the timeout value for this specific module / series
580 : (in number of symbols or units of time).
581 : \param timeoutUs Timeout in microseconds to listen for.
582 : \returns Timeout value in a unit that is specific for the used module.
583 : */
584 : virtual RadioLibTime_t calculateRxTimeout(RadioLibTime_t timeoutUs);
585 :
586 : /*!
587 : \brief Convert from radio-agnostic IRQ flags to radio-specific flags.
588 : \param irq Radio-agnostic IRQ flags.
589 : \returns Flags for a specific radio module.
590 : */
591 : uint32_t getIrqMapped(RadioLibIrqFlags_t irq);
592 :
593 : /*!
594 : \brief Check whether a specific IRQ bit is set (e.g. RxTimeout, CadDone).
595 : \param irq IRQ type to check, one of RADIOLIB_IRQ_*.
596 : \returns 1 when requested IRQ is set, 0 when it is not or RADIOLIB_ERR_UNSUPPORTED if the IRQ is not supported.
597 : */
598 : int16_t checkIrq(RadioLibIrqType_t irq);
599 :
600 : /*!
601 : \brief Set interrupt on specific IRQ bit(s) (e.g. RxTimeout, CadDone).
602 : Keep in mind that not all radio modules support all RADIOLIB_IRQ_ flags!
603 : \param irq Flags to set, multiple bits may be enabled. IRQ to enable corresponds to the bit index (RadioLibIrq_t).
604 : For example, if bit 0 is enabled, the module will enable its RADIOLIB_IRQ_TX_DONE (if it is supported).
605 : \returns \ref status_codes
606 : */
607 : int16_t setIrq(RadioLibIrqFlags_t irq);
608 :
609 : /*!
610 : \brief Clear interrupt on a specific IRQ bit (e.g. RxTimeout, CadDone).
611 : Keep in mind that not all radio modules support all RADIOLIB_IRQ_ flags!
612 : \param irq Flags to set, multiple bits may be enabled. IRQ to enable corresponds to the bit index (RadioLibIrq_t).
613 : For example, if bit 0 is enabled, the module will enable its RADIOLIB_IRQ_TX_DONE (if it is supported).
614 : \returns \ref status_codes
615 : */
616 : int16_t clearIrq(RadioLibIrqFlags_t irq);
617 :
618 : /*!
619 : \brief Read currently active IRQ flags.
620 : Must be implemented in module class.
621 : \returns IRQ flags.
622 : */
623 : virtual uint32_t getIrqFlags();
624 :
625 : /*!
626 : \brief Set interrupt on DIO1 to be sent on a specific IRQ bit (e.g. RxTimeout, CadDone).
627 : Must be implemented in module class.
628 : \param irq Module-specific IRQ flags.
629 : \returns \ref status_codes
630 : */
631 : virtual int16_t setIrqFlags(uint32_t irq);
632 :
633 : /*!
634 : \brief Clear interrupt on a specific IRQ bit (e.g. RxTimeout, CadDone).
635 : Must be implemented in module class.
636 : \param irq Module-specific IRQ flags.
637 : \returns \ref status_codes
638 : */
639 : virtual int16_t clearIrqFlags(uint32_t irq);
640 :
641 : /*!
642 : \brief Interrupt-driven channel activity detection method. Interrupt will be activated
643 : when packet is detected. Must be implemented in module class.
644 : \returns \ref status_codes
645 : */
646 : virtual int16_t startChannelScan();
647 :
648 : /*!
649 : \brief Interrupt-driven channel activity detection method. interrupt will be activated
650 : when packet is detected. Must be implemented in module class.
651 : \param config Scan configuration structure. Interpretation depends on currently active modem.
652 : \returns \ref status_codes
653 : */
654 : virtual int16_t startChannelScan(const ChannelScanConfig_t &config);
655 :
656 : /*!
657 : \brief Read the channel scan result
658 : \returns \ref status_codes
659 : */
660 : virtual int16_t getChannelScanResult();
661 :
662 : /*!
663 : \brief Check whether the current communication channel is free or occupied. Performs CAD for LoRa modules,
664 : or RSSI measurement for FSK modules.
665 : \returns RADIOLIB_CHANNEL_FREE when channel is free,
666 : RADIOLIB_PREAMBLE_DETECTEDwhen occupied or other \ref status_codes.
667 : */
668 : virtual int16_t scanChannel();
669 :
670 : /*!
671 : \brief Check whether the current communication channel is free or occupied. Performs CAD for LoRa modules,
672 : or RSSI measurement for FSK modules.
673 : \param config Scan configuration structure. Interpretation depends on currently active modem.
674 : \returns RADIOLIB_CHANNEL_FREE when channel is free,
675 : RADIOLIB_PREAMBLE_DETECTEDwhen occupied or other \ref status_codes.
676 : */
677 : virtual int16_t scanChannel(const ChannelScanConfig_t &config);
678 :
679 : /*!
680 : \brief Get truly random number in range 0 - max.
681 : \param max The maximum value of the random number (non-inclusive).
682 : \returns Random number.
683 : */
684 : int32_t random(int32_t max);
685 :
686 : /*!
687 : \brief Get truly random number in range min - max.
688 : \param min The minimum value of the random number (inclusive).
689 : \param max The maximum value of the random number (non-inclusive).
690 : \returns Random number.
691 : */
692 : int32_t random(int32_t min, int32_t max);
693 :
694 : /*!
695 : \brief Get one truly random byte from RSSI noise. Must be implemented in module class.
696 : \returns TRNG byte.
697 : */
698 : virtual uint8_t randomByte();
699 :
700 : /*!
701 : \brief Configure module parameters for direct modes. Must be called prior to "ham" modes like RTTY or AX.25.
702 : Only available in FSK mode.
703 : \returns \ref status_codes
704 : */
705 : int16_t startDirect();
706 :
707 : #if !RADIOLIB_EXCLUDE_DIRECT_RECEIVE
708 : /*!
709 : \brief Set sync word to be used to determine start of packet in direct reception mode.
710 : \param syncWord Sync word bits.
711 : \param len Sync word length in bits. Set to zero to disable sync word matching.
712 : \returns \ref status_codes
713 : */
714 : int16_t setDirectSyncWord(uint32_t syncWord, uint8_t len);
715 :
716 : /*!
717 : \brief Set interrupt service routine function to call when data bit is received in direct mode.
718 : Must be implemented in module class.
719 : \param func Pointer to interrupt service routine.
720 : */
721 : virtual void setDirectAction(void (*func)(void));
722 :
723 : /*!
724 : \brief Function to read and process data bit in direct reception mode. Must be implemented in module class.
725 : \param pin Pin on which to read.
726 : */
727 : virtual void readBit(uint32_t pin);
728 :
729 : /*!
730 : \brief Get the number of direct mode bytes currently available in buffer.
731 : \returns Number of available bytes.
732 : */
733 : int16_t available();
734 :
735 : /*!
736 : \brief Forcefully drop synchronization.
737 : */
738 : void dropSync();
739 :
740 : /*!
741 : \brief Get data from direct mode buffer.
742 : \param drop Drop synchronization on read - next reading will require waiting for the sync word again.
743 : Defaults to true.
744 : \returns Byte from direct mode buffer.
745 : */
746 : uint8_t read(bool drop = true);
747 : #endif
748 :
749 : /*!
750 : \brief Configure DIO pin mapping to get a given signal on a DIO pin (if available).
751 : \param pin Pin number onto which a signal is to be placed.
752 : \param value The value that indicates which function to place on that pin. See chip datasheet for details.
753 : \returns \ref status_codes
754 : */
755 : virtual int16_t setDIOMapping(uint32_t pin, uint32_t value);
756 :
757 : /*!
758 : \brief Sets interrupt service routine to call when a packet is received.
759 : \param func ISR to call.
760 : */
761 : virtual void setPacketReceivedAction(void (*func)(void));
762 :
763 : /*!
764 : \brief Clears interrupt service routine to call when a packet is received.
765 : */
766 : virtual void clearPacketReceivedAction();
767 :
768 : /*!
769 : \brief Sets interrupt service routine to call when a packet is sent.
770 : \param func ISR to call.
771 : */
772 : virtual void setPacketSentAction(void (*func)(void));
773 :
774 : /*!
775 : \brief Clears interrupt service routine to call when a packet is sent.
776 : */
777 : virtual void clearPacketSentAction();
778 :
779 : /*!
780 : \brief Sets interrupt service routine to call when a channel scan is finished.
781 : \param func ISR to call.
782 : */
783 : virtual void setChannelScanAction(void (*func)(void));
784 :
785 : /*!
786 : \brief Clears interrupt service routine to call when a channel scan is finished.
787 : */
788 : virtual void clearChannelScanAction();
789 :
790 : /*!
791 : \brief Set modem for the radio to use. Will perform full reset and reconfigure the radio
792 : using its default parameters.
793 : \param modem Modem type to set. Not all modems are implemented by all radio modules!
794 : \returns \ref status_codes
795 : */
796 : virtual int16_t setModem(ModemType_t modem);
797 :
798 : /*!
799 : \brief Get modem currently in use by the radio.
800 : \param modem Pointer to a variable to save the retrieved configuration into.
801 : \returns \ref status_codes
802 : */
803 : virtual int16_t getModem(ModemType_t* modem);
804 :
805 : /*!
806 : \brief Stage mode of the radio to be launched later using launchMode.
807 : \param mode Radio mode to prepare.
808 : \param cfg Configuration of this mode (mode-dependent).
809 : \returns \ref status_codes
810 : */
811 : virtual int16_t stageMode(RadioModeType_t mode, RadioModeConfig_t* cfg);
812 :
813 : /*!
814 : \brief Launch previously staged mode.
815 : \returns \ref status_codes
816 : */
817 : virtual int16_t launchMode();
818 :
819 : #if RADIOLIB_INTERRUPT_TIMING
820 :
821 : /*!
822 : \brief Set function to be called to set up the timing interrupt.
823 : For details, see https://github.com/jgromes/RadioLib/wiki/Interrupt-Based-Timing
824 : \param func Setup function to be called, with one argument (pulse length in microseconds).
825 : */
826 : void setInterruptSetup(void (*func)(uint32_t));
827 :
828 : /*!
829 : \brief Set timing interrupt flag.
830 : For details, see https://github.com/jgromes/RadioLib/wiki/Interrupt-Based-Timing
831 : */
832 : void setTimerFlag();
833 :
834 : #endif
835 :
836 : #if !RADIOLIB_GODMODE
837 : protected:
838 : #endif
839 : uint32_t irqMap[10] = { 0 };
840 : RadioModeType_t stagedMode = RADIOLIB_RADIO_MODE_NONE;
841 :
842 : #if !RADIOLIB_EXCLUDE_DIRECT_RECEIVE
843 : void updateDirectBuffer(uint8_t bit);
844 : #endif
845 :
846 : #if !RADIOLIB_GODMODE
847 : private:
848 : #endif
849 :
850 : #if !RADIOLIB_EXCLUDE_DIRECT_RECEIVE
851 : uint8_t bufferBitPos = 0;
852 : uint8_t bufferWritePos = 0;
853 : uint8_t bufferReadPos = 0;
854 : uint8_t buffer[RADIOLIB_STATIC_ARRAY_SIZE] = { 0 };
855 : uint32_t syncBuffer = 0;
856 : uint32_t directSyncWord = 0;
857 : uint8_t directSyncWordLen = 0;
858 : uint32_t directSyncWordMask = 0;
859 : bool gotSync = false;
860 : #endif
861 :
862 : virtual Module* getMod() = 0;
863 :
864 : // allow specific classes access the private getMod method
865 : friend class AFSKClient;
866 : friend class RTTYClient;
867 : friend class MorseClient;
868 : friend class HellClient;
869 : friend class SSTVClient;
870 : friend class AX25Client;
871 : friend class FSK4Client;
872 : friend class PagerClient;
873 : friend class BellClient;
874 : friend class FT8Client;
875 : friend class LoRaWANNode;
876 : friend class M17Client;
877 : };
878 :
879 : #endif
|
