forks/RadioLibSmol
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[PHY] Use compact Doxygen

Browse source
This commit is contained in:
jgromes 2023-04-22 19:35:00 +02:00
parent 5ab24e05dd
commit 8722231ace
1 changed files with 18 additions and 95 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

113
src/protocols/PhysicalLayer/PhysicalLayer.h
View file

@ -7,9 +7,10 @@
/*! /*!
\class PhysicalLayer \class PhysicalLayer
\brief Provides common interface for protocols that run on %LoRa/FSK modules, such as RTTY or LoRaWAN. Also extracts some common \brief Provides common interface for protocols that run on %LoRa/FSK modules, such as RTTY or LoRaWAN.
module-independent methods. Using this interface class allows to use the protocols on various modules without much code duplicity. Also extracts some common module-independent methods. Using this interface class allows to use the protocols
Because this class is used mainly as interface, all of its virtual members must be implemented in the module class. on various modules without much code duplicity. Because this class is used mainly as interface,
all of its virtual members must be implemented in the module class.
*/ */
class PhysicalLayer { class PhysicalLayer {
public: public:
@ -18,9 +19,7 @@ class PhysicalLayer {
/*! /*!
\brief Default constructor. \brief Default constructor.
\param freqStep Frequency step of the synthesizer in Hz. \param freqStep Frequency step of the synthesizer in Hz.
\param maxPacketLength Maximum length of packet that can be received by the module. \param maxPacketLength Maximum length of packet that can be received by the module.
*/ */
PhysicalLayer(float freqStep, size_t maxPacketLength); PhysicalLayer(float freqStep, size_t maxPacketLength);
@ -30,22 +29,16 @@ class PhysicalLayer {
#if defined(RADIOLIB_BUILD_ARDUINO) #if defined(RADIOLIB_BUILD_ARDUINO)
/*! /*!
\brief Arduino Flash String transmit method. \brief Arduino Flash String transmit method.
\param str Pointer to Arduino Flash String that will be transmitted. \param str Pointer to Arduino Flash String that will be transmitted.
\param addr Node address to transmit the packet to. Only used in FSK mode. \param addr Node address to transmit the packet to. Only used in FSK mode.
\returns \ref status_codes \returns \ref status_codes
*/ */
int16_t transmit(__FlashStringHelper* fstr, uint8_t addr = 0); int16_t transmit(__FlashStringHelper* fstr, uint8_t addr = 0);
/*! /*!
\brief Arduino String transmit method. \brief Arduino String transmit method.
\param str Address of Arduino string that will be transmitted. \param str Address of Arduino string that will be transmitted.
\param addr Node address to transmit the packet to. Only used in FSK mode. \param addr Node address to transmit the packet to. Only used in FSK mode.
\returns \ref status_codes \returns \ref status_codes
*/ */
int16_t transmit(String& str, uint8_t addr = 0); int16_t transmit(String& str, uint8_t addr = 0);
@ -53,24 +46,17 @@ class PhysicalLayer {
/*! /*!
\brief C-string transmit method. \brief C-string transmit method.
\param str C-string that will be transmitted. \param str C-string that will be transmitted.
\param addr Node address to transmit the packet to. Only used in FSK mode. \param addr Node address to transmit the packet to. Only used in FSK mode.
\returns \ref status_codes \returns \ref status_codes
*/ */
int16_t transmit(const char* str, uint8_t addr = 0); int16_t transmit(const char* str, uint8_t addr = 0);
/*! /*!
\brief Binary transmit method. Must be implemented in module class. \brief Binary transmit method. Must be implemented in module class.
\param data Binary data that will be transmitted. \param data Binary data that will be transmitted.
\param len Length of binary data to transmit (in bytes). \param len Length of binary data to transmit (in bytes).
\param addr Node address to transmit the packet to. Only used in FSK mode. \param addr Node address to transmit the packet to. Only used in FSK mode.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t transmit(uint8_t* data, size_t len, uint8_t addr = 0); virtual int16_t transmit(uint8_t* data, size_t len, uint8_t addr = 0);
@ -78,11 +64,8 @@ class PhysicalLayer {
#if defined(RADIOLIB_BUILD_ARDUINO) #if defined(RADIOLIB_BUILD_ARDUINO)
/*! /*!
\brief Arduino String receive method. \brief Arduino String receive method.
\param str Address of Arduino String to save the received data. \param str Address of Arduino String to save the received data.
\param len Expected number of characters in the message. Leave as 0 if expecting a unknown size packet \param len Expected number of characters in the message. Leave as 0 if expecting a unknown size packet
\returns \ref status_codes \returns \ref status_codes
*/ */
int16_t receive(String& str, size_t len = 0); int16_t receive(String& str, size_t len = 0);
@ -90,47 +73,38 @@ class PhysicalLayer {
/*! /*!
\brief Sets module to sleep. \brief Sets module to sleep.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t sleep(); virtual int16_t sleep();
/*! /*!
\brief Sets module to standby. \brief Sets module to standby.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t standby(); virtual int16_t standby();
/*! /*!
\brief Sets module to a specific standby mode. \brief Sets module to a specific standby mode.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t standby(uint8_t mode); virtual int16_t standby(uint8_t mode);
/*! /*!
\brief Interrupt-driven receive method. A DIO pin will be activated when full packet is received. Must be implemented in module class. \brief Interrupt-driven receive method. A DIO pin will be activated when full packet is received.
Must be implemented in module class.
\param timeout Raw timeout value. Some modules use this argument to specify operation mode (single vs. continuous receive). \param timeout Raw timeout value. Some modules use this argument to specify operation mode
(single vs. continuous receive).
\param irqFlags Sets the IRQ flags. \param irqFlags Sets the IRQ flags.
\param irqMask Sets the mask of IRQ flags that will trigger the DIO pin. \param irqMask Sets the mask of IRQ flags that will trigger the DIO pin.
\param len Packet length, needed for some modules under special circumstances (e.g. LoRa implicit header mode). \param len Packet length, needed for some modules under special circumstances (e.g. LoRa implicit header mode).
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t startReceive(uint32_t timeout, uint16_t irqFlags, uint16_t irqMask, size_t len); virtual int16_t startReceive(uint32_t timeout, uint16_t irqFlags, uint16_t irqMask, size_t len);
/*! /*!
\brief Binary receive method. Must be implemented in module class. \brief Binary receive method. Must be implemented in module class.
\param data Pointer to array to save the received binary data. \param data Pointer to array to save the received binary data.
\param len Number of bytes that will be received. Must be known in advance for binary transmissions. \param len Number of bytes that will be received. Must be known in advance for binary transmissions.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t receive(uint8_t* data, size_t len); virtual int16_t receive(uint8_t* data, size_t len);
@ -139,11 +113,8 @@ class PhysicalLayer {
/*! /*!
\brief Interrupt-driven Arduino String transmit method. Unlike the standard transmit method, this one is non-blocking. \brief Interrupt-driven Arduino String transmit method. Unlike the standard transmit method, this one is non-blocking.
Interrupt pin will be activated when transmission finishes. Interrupt pin will be activated when transmission finishes.
\param str Address of Arduino String that will be transmitted. \param str Address of Arduino String that will be transmitted.
\param addr Node address to transmit the packet to. Only used in FSK mode. \param addr Node address to transmit the packet to. Only used in FSK mode.
\returns \ref status_codes \returns \ref status_codes
*/ */
int16_t startTransmit(String& str, uint8_t addr = 0); int16_t startTransmit(String& str, uint8_t addr = 0);
@ -152,31 +123,23 @@ class PhysicalLayer {
/*! /*!
\brief Interrupt-driven Arduino String transmit method. Unlike the standard transmit method, this one is non-blocking. \brief Interrupt-driven Arduino String transmit method. Unlike the standard transmit method, this one is non-blocking.
Interrupt pin will be activated when transmission finishes. Interrupt pin will be activated when transmission finishes.
\param str C-string that will be transmitted. \param str C-string that will be transmitted.
\param addr Node address to transmit the packet to. Only used in FSK mode. \param addr Node address to transmit the packet to. Only used in FSK mode.
\returns \ref status_codes \returns \ref status_codes
*/ */
int16_t startTransmit(const char* str, uint8_t addr = 0); int16_t startTransmit(const char* str, uint8_t addr = 0);
/*! /*!
\brief Interrupt-driven binary transmit method. \brief Interrupt-driven binary transmit method.
\param data Binary data that will be transmitted. \param data Binary data that will be transmitted.
\param len Length of binary data to transmit (in bytes). \param len Length of binary data to transmit (in bytes).
\param addr Node address to transmit the packet to. Only used in FSK mode. \param addr Node address to transmit the packet to. Only used in FSK mode.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t startTransmit(uint8_t* data, size_t len, uint8_t addr = 0); virtual int16_t startTransmit(uint8_t* data, size_t len, uint8_t addr = 0);
/*! /*!
\brief Clean up after transmission is done. \brief Clean up after transmission is done.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t finishTransmit(); virtual int16_t finishTransmit();
@ -184,12 +147,9 @@ class PhysicalLayer {
#if defined(RADIOLIB_BUILD_ARDUINO) #if defined(RADIOLIB_BUILD_ARDUINO)
/*! /*!
\brief Reads data that was received after calling startReceive method. \brief Reads data that was received after calling startReceive method.
\param str Address of Arduino String to save the received data. \param str Address of Arduino String to save the received data.
\param len Expected number of characters in the message. When set to 0, the packet length will be retreived
\param len Expected number of characters in the message. When set to 0, the packet length will be retreived automatically. automatically. When more bytes than received are requested, only the number of bytes requested will be returned.
When more bytes than received are requested, only the number of bytes requested will be returned.
\returns \ref status_codes \returns \ref status_codes
*/ */
int16_t readData(String& str, size_t len = 0); int16_t readData(String& str, size_t len = 0);
@ -197,12 +157,9 @@ class PhysicalLayer {
/*! /*!
\brief Reads data that was received after calling startReceive method. \brief Reads data that was received after calling startReceive method.
\param data Pointer to array to save the received binary data. \param data Pointer to array to save the received binary data.
\param len Number of bytes that will be read. When set to 0, the packet length will be retreived automatically. \param len Number of bytes that will be read. When set to 0, the packet length will be retreived automatically.
When more bytes than received are requested, only the number of bytes requested will be returned. When more bytes than received are requested, only the number of bytes requested will be returned.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t readData(uint8_t* data, size_t len); virtual int16_t readData(uint8_t* data, size_t len);
@ -210,9 +167,7 @@ class PhysicalLayer {
/*! /*!
\brief Enables direct transmission mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module class. \brief Enables direct transmission mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module class.
While in direct mode, the module will not be able to transmit or receive packets. Can only be activated in FSK mode. While in direct mode, the module will not be able to transmit or receive packets. Can only be activated in FSK mode.
\param frf 24-bit raw frequency value to start transmitting at. Required for quick frequency shifts in RTTY. \param frf 24-bit raw frequency value to start transmitting at. Required for quick frequency shifts in RTTY.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t transmitDirect(uint32_t frf = 0); virtual int16_t transmitDirect(uint32_t frf = 0);
@ -220,7 +175,6 @@ class PhysicalLayer {
/*! /*!
\brief Enables direct reception mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module class. \brief Enables direct reception mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module class.
While in direct mode, the module will not be able to transmit or receive packets. Can only be activated in FSK mode. While in direct mode, the module will not be able to transmit or receive packets. Can only be activated in FSK mode.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t receiveDirect(); virtual int16_t receiveDirect();
@ -229,109 +183,89 @@ class PhysicalLayer {
/*! /*!
\brief Sets carrier frequency. Must be implemented in module class. \brief Sets carrier frequency. Must be implemented in module class.
\param freq Carrier frequency to be set in MHz. \param freq Carrier frequency to be set in MHz.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t setFrequency(float freq); virtual int16_t setFrequency(float freq);
/*! /*!
\brief Sets FSK bit rate. Only available in FSK mode. Must be implemented in module class. \brief Sets FSK bit rate. Only available in FSK mode. Must be implemented in module class.
\param br Bit rate to be set (in kbps). \param br Bit rate to be set (in kbps).
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t setBitRate(float br); virtual int16_t setBitRate(float br);
/*! /*!
\brief Sets FSK frequency deviation from carrier frequency. Only available in FSK mode. Must be implemented in module class. \brief Sets FSK frequency deviation from carrier frequency. Only available in FSK mode.
Must be implemented in module class.
\param freqDev Frequency deviation to be set (in kHz). \param freqDev Frequency deviation to be set (in kHz).
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t setFrequencyDeviation(float freqDev); virtual int16_t setFrequencyDeviation(float freqDev);
/*! /*!
\brief Sets GFSK data shaping. Only available in FSK mode. Must be implemented in module class. \brief Sets GFSK data shaping. Only available in FSK mode. Must be implemented in module class.
\param sh Shaping to be set. See \ref config_shaping for possible values. \param sh Shaping to be set. See \ref config_shaping for possible values.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t setDataShaping(uint8_t sh); virtual int16_t setDataShaping(uint8_t sh);
/*! /*!
\brief Sets FSK data encoding. Only available in FSK mode. Must be implemented in module class. \brief Sets FSK data encoding. Only available in FSK mode. Must be implemented in module class.
\param enc Encoding to be used. See \ref config_encoding for possible values. \param enc Encoding to be used. See \ref config_encoding for possible values.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t setEncoding(uint8_t encoding); virtual int16_t setEncoding(uint8_t encoding);
/*! /*!
\brief Gets the module frequency step size that was set in constructor. \brief Gets the module frequency step size that was set in constructor.
\returns Synthesizer frequency step size in Hz. \returns Synthesizer frequency step size in Hz.
*/ */
float getFreqStep() const; float getFreqStep() const;
/*! /*!
\brief Query modem for the packet length of received payload. Must be implemented in module class. \brief Query modem for the packet length of received payload. Must be implemented in module class.
\param update Update received packet length. Will return cached value when set to false. \param update Update received packet length. Will return cached value when set to false.
\returns Length of last received packet in bytes. \returns Length of last received packet in bytes.
*/ */
virtual size_t getPacketLength(bool update = true); virtual size_t getPacketLength(bool update = true);
/*! /*!
\brief Gets RSSI (Recorded Signal Strength Indicator) of the last received packet. \brief Gets RSSI (Recorded Signal Strength Indicator) of the last received packet.
\returns RSSI of the last received packet in dBm. \returns RSSI of the last received packet in dBm.
*/ */
virtual float getRSSI(); virtual float getRSSI();
/*! /*!
\brief Gets SNR (Signal to Noise Ratio) of the last received packet. Only available for LoRa modem. \brief Gets SNR (Signal to Noise Ratio) of the last received packet. Only available for LoRa modem.
\returns SNR of the last received packet in dB. \returns SNR of the last received packet in dB.
*/ */
virtual float getSNR(); virtual float getSNR();
/*! /*!
\brief Get truly random number in range 0 - max. \brief Get truly random number in range 0 - max.
\param max The maximum value of the random number (non-inclusive). \param max The maximum value of the random number (non-inclusive).
\returns Random number. \returns Random number.
*/ */
int32_t random(int32_t max); int32_t random(int32_t max);
/*! /*!
\brief Get truly random number in range min - max. \brief Get truly random number in range min - max.
\param min The minimum value of the random number (inclusive). \param min The minimum value of the random number (inclusive).
\param max The maximum value of the random number (non-inclusive). \param max The maximum value of the random number (non-inclusive).
\returns Random number. \returns Random number.
*/ */
int32_t random(int32_t min, int32_t max); int32_t random(int32_t min, int32_t max);
/*! /*!
\brief Get one truly random byte from RSSI noise. Must be implemented in module class. \brief Get one truly random byte from RSSI noise. Must be implemented in module class.
\returns TRNG byte. \returns TRNG byte.
*/ */
virtual uint8_t randomByte(); virtual uint8_t randomByte();
/*! /*!
\brief Configure module parameters for direct modes. Must be called prior to "ham" modes like RTTY or AX.25. Only available in FSK mode. \brief Configure module parameters for direct modes. Must be called prior to "ham" modes like RTTY or AX.25.
Only available in FSK mode.
\returns \ref status_codes \returns \ref status_codes
*/ */
int16_t startDirect(); int16_t startDirect();
@ -339,32 +273,27 @@ class PhysicalLayer {
#if !defined(RADIOLIB_EXCLUDE_DIRECT_RECEIVE) #if !defined(RADIOLIB_EXCLUDE_DIRECT_RECEIVE)
/*! /*!
\brief Set sync word to be used to determine start of packet in direct reception mode. \brief Set sync word to be used to determine start of packet in direct reception mode.
\param syncWord Sync word bits. \param syncWord Sync word bits.
\param len Sync word length in bits. Set to zero to disable sync word matching. \param len Sync word length in bits. Set to zero to disable sync word matching.
\returns \ref status_codes \returns \ref status_codes
*/ */
int16_t setDirectSyncWord(uint32_t syncWord, uint8_t len); int16_t setDirectSyncWord(uint32_t syncWord, uint8_t len);
/*! /*!
\brief Set interrupt service routine function to call when data bit is receveid in direct mode. Must be implemented in module class. \brief Set interrupt service routine function to call when data bit is receveid in direct mode.
Must be implemented in module class.
\param func Pointer to interrupt service routine. \param func Pointer to interrupt service routine.
*/ */
virtual void setDirectAction(void (*func)(void)); virtual void setDirectAction(void (*func)(void));
/*! /*!
\brief Function to read and process data bit in direct reception mode. Must be implemented in module class. \brief Function to read and process data bit in direct reception mode. Must be implemented in module class.
\param pin Pin on which to read. \param pin Pin on which to read.
*/ */
virtual void readBit(uint32_t pin); virtual void readBit(uint32_t pin);
/*! /*!
\brief Get the number of direct mode bytes currently available in buffer. \brief Get the number of direct mode bytes currently available in buffer.
\returns Number of available bytes. \returns Number of available bytes.
*/ */
int16_t available(); int16_t available();
@ -376,9 +305,8 @@ class PhysicalLayer {
/*! /*!
\brief Get data from direct mode buffer. \brief Get data from direct mode buffer.
\param drop Drop synchronization on read - next reading will require waiting for the sync word again.
\param drop Drop synchronization on read - next reading will require waiting for the sync word again. Defautls to true. Defaults to true.
\returns Byte from direct mode buffer. \returns Byte from direct mode buffer.
*/ */
uint8_t read(bool drop = true); uint8_t read(bool drop = true);
@ -386,18 +314,14 @@ class PhysicalLayer {
/*! /*!
\brief Configure DIO pin mapping to get a given signal on a DIO pin (if available). \brief Configure DIO pin mapping to get a given signal on a DIO pin (if available).
\param pin Pin number onto which a signal is to be placed. \param pin Pin number onto which a signal is to be placed.
\param value The value that indicates which function to place on that pin. See chip datasheet for details. \param value The value that indicates which function to place on that pin. See chip datasheet for details.
\returns \ref status_codes \returns \ref status_codes
*/ */
virtual int16_t setDIOMapping(uint32_t pin, uint32_t value); virtual int16_t setDIOMapping(uint32_t pin, uint32_t value);
/*! /*!
\brief Sets interrupt service routine to call when DIO1 activates. \brief Sets interrupt service routine to call when DIO1 activates.
\param func ISR to call. \param func ISR to call.
*/ */
virtual void setDio1Action(void (*func)(void)); virtual void setDio1Action(void (*func)(void));
@ -412,7 +336,6 @@ class PhysicalLayer {
/*! /*!
\brief Set function to be called to set up the timing interrupt. \brief Set function to be called to set up the timing interrupt.
For details, see https://github.com/jgromes/RadioLib/wiki/Interrupt-Based-Timing For details, see https://github.com/jgromes/RadioLib/wiki/Interrupt-Based-Timing
\param func Setup function to be called, with one argument (pulse length in microseconds). \param func Setup function to be called, with one argument (pulse length in microseconds).
*/ */
void setInterruptSetup(void (*func)(uint32_t)); void setInterruptSetup(void (*func)(uint32_t));