acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

PhysicalLayer.h (10881B)

      1 #if !defined(_RADIOLIB_PHYSICAL_LAYER_H)
      2 #define _RADIOLIB_PHYSICAL_LAYER_H
      3 
      4 #include "../../TypeDef.h"
      5 #include "../../Module.h"
      6 
      7 /*!
      8   \class PhysicalLayer
      9 
     10   \brief Provides common interface for protocols that run on %LoRa/FSK modules, such as RTTY or LoRaWAN. Also extracts some common
     11   module-independent methods. Using this interface class allows to use the protocols on various modules without much code duplicity.
     12   Because this class is used mainly as interface, all of its virtual members must be implemented in the module class.
     13 */
     14 class PhysicalLayer {
     15   public:
     16 
     17     // constructor
     18 
     19     /*!
     20       \brief Default constructor.
     21 
     22       \param freqStep Frequency step of the synthesizer in Hz.
     23 
     24       \param maxPacketLength Maximum length of packet that can be received by the module.
     25     */
     26     PhysicalLayer(float freqStep, size_t maxPacketLength);
     27 
     28     // basic methods
     29 
     30     /*!
     31       \brief Arduino Flash String transmit method.
     32 
     33       \param str Pointer to Arduino Flash String that will be transmitted.
     34 
     35       \param addr Node address to transmit the packet to. Only used in FSK mode.
     36 
     37       \returns \ref status_codes
     38     */
     39     int16_t transmit(__FlashStringHelper* fstr, uint8_t addr = 0);
     40 
     41     /*!
     42       \brief Arduino String transmit method.
     43 
     44       \param str Address of Arduino string that will be transmitted.
     45 
     46       \param addr Node address to transmit the packet to. Only used in FSK mode.
     47 
     48       \returns \ref status_codes
     49     */
     50     int16_t transmit(String& str, uint8_t addr = 0);
     51 
     52     /*!
     53       \brief C-string transmit method.
     54 
     55       \param str C-string that will be transmitted.
     56 
     57       \param addr Node address to transmit the packet to. Only used in FSK mode.
     58 
     59       \returns \ref status_codes
     60     */
     61     int16_t transmit(const char* str, uint8_t addr = 0);
     62 
     63     /*!
     64       \brief Binary transmit method. Must be implemented in module class.
     65 
     66       \param data Binary data that will be transmitted.
     67 
     68       \param len Length of binary data to transmit (in bytes).
     69 
     70       \param addr Node address to transmit the packet to. Only used in FSK mode.
     71 
     72       \returns \ref status_codes
     73     */
     74     virtual int16_t transmit(uint8_t* data, size_t len, uint8_t addr = 0) = 0;
     75 
     76     /*!
     77       \brief Arduino String receive method.
     78 
     79       \param str Address of Arduino String to save the received data.
     80 
     81       \param len Expected number of characters in the message. Leave as 0 if expecting a unknown size packet
     82 
     83       \returns \ref status_codes
     84     */
     85     int16_t receive(String& str, size_t len = 0);
     86 
     87     /*!
     88       \brief Sets module to standby.
     89 
     90       \returns \ref status_codes
     91     */
     92     virtual int16_t standby() = 0;
     93 
     94     /*!
     95       \brief Binary receive method. Must be implemented in module class.
     96 
     97       \param data Pointer to array to save the received binary data.
     98 
     99       \param len Number of bytes that will be received. Must be known in advance for binary transmissions.
    100 
    101       \returns \ref status_codes
    102     */
    103     virtual int16_t receive(uint8_t* data, size_t len) = 0;
    104 
    105     /*!
    106       \brief Interrupt-driven Arduino String transmit method. Unlike the standard transmit method, this one is non-blocking.
    107       Interrupt pin will be activated when transmission finishes.
    108 
    109       \param str Address of Arduino String that will be transmitted.
    110 
    111       \param addr Node address to transmit the packet to. Only used in FSK mode.
    112 
    113       \returns \ref status_codes
    114     */
    115     int16_t startTransmit(String& str, uint8_t addr = 0);
    116 
    117     /*!
    118       \brief Interrupt-driven Arduino String transmit method. Unlike the standard transmit method, this one is non-blocking.
    119       Interrupt pin will be activated when transmission finishes.
    120 
    121       \param str C-string that will be transmitted.
    122 
    123       \param addr Node address to transmit the packet to. Only used in FSK mode.
    124 
    125       \returns \ref status_codes
    126     */
    127     int16_t startTransmit(const char* str, uint8_t addr = 0);
    128 
    129     /*!
    130       \brief Interrupt-driven binary transmit method.
    131 
    132       \param data Binary data that will be transmitted.
    133 
    134       \param len Length of binary data to transmit (in bytes).
    135 
    136       \param addr Node address to transmit the packet to. Only used in FSK mode.
    137 
    138       \returns \ref status_codes
    139     */
    140     virtual int16_t startTransmit(uint8_t* data, size_t len, uint8_t addr = 0) = 0;
    141 
    142     /*!
    143       \brief Reads data that was received after calling startReceive method.
    144 
    145       \param str Address of Arduino String to save the received data.
    146 
    147       \param len Expected number of characters in the message. When set to 0, the packet length will be retreived automatically.
    148       When more bytes than received are requested, only the number of bytes requested will be returned.
    149 
    150       \returns \ref status_codes
    151     */
    152     int16_t readData(String& str, size_t len = 0);
    153 
    154     /*!
    155       \brief Reads data that was received after calling startReceive method.
    156 
    157       \param data Pointer to array to save the received binary data.
    158 
    159       \param len Number of bytes that will be read. When set to 0, the packet length will be retreived automatically.
    160       When more bytes than received are requested, only the number of bytes requested will be returned.
    161 
    162       \returns \ref status_codes
    163     */
    164     virtual int16_t readData(uint8_t* data, size_t len) = 0;
    165 
    166     /*!
    167       \brief Enables direct transmission mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module class.
    168       While in direct mode, the module will not be able to transmit or receive packets. Can only be activated in FSK mode.
    169 
    170       \param frf 24-bit raw frequency value to start transmitting at. Required for quick frequency shifts in RTTY.
    171 
    172       \returns \ref status_codes
    173     */
    174     virtual int16_t transmitDirect(uint32_t frf = 0) = 0;
    175 
    176     /*!
    177       \brief Enables direct reception mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module class.
    178       While in direct mode, the module will not be able to transmit or receive packets. Can only be activated in FSK mode.
    179 
    180       \returns \ref status_codes
    181     */
    182     virtual int16_t receiveDirect() = 0;
    183 
    184     // configuration methods
    185 
    186     /*!
    187       \brief Sets FSK frequency deviation from carrier frequency. Allowed values depend on bit rate setting and must be lower than 200 kHz.
    188       Only available in FSK mode. Must be implemented in module class.
    189 
    190       \param freqDev Frequency deviation to be set (in kHz).
    191 
    192       \returns \ref status_codes
    193     */
    194     virtual int16_t setFrequencyDeviation(float freqDev) = 0;
    195 
    196     /*!
    197       \brief Sets GFSK data shaping. Only available in FSK mode. Must be implemented in module class.
    198 
    199       \param sh Shaping to be set. See \ref config_shaping for possible values.
    200 
    201       \returns \ref status_codes
    202     */
    203     virtual int16_t setDataShaping(uint8_t sh) = 0;
    204 
    205     /*!
    206       \brief Sets FSK data encoding. Only available in FSK mode. Must be implemented in module class.
    207 
    208       \param enc Encoding to be used. See \ref config_encoding for possible values.
    209 
    210       \returns \ref status_codes
    211     */
    212     virtual int16_t setEncoding(uint8_t encoding) = 0;
    213 
    214     /*!
    215       \brief Gets the module frequency step size that was set in constructor.
    216 
    217       \returns Synthesizer frequency step size in Hz.
    218     */
    219     float getFreqStep() const;
    220 
    221     /*!
    222       \brief Query modem for the packet length of received payload. Must be implemented in module class.
    223 
    224       \param update Update received packet length. Will return cached value when set to false.
    225 
    226       \returns Length of last received packet in bytes.
    227     */
    228     virtual size_t getPacketLength(bool update = true) = 0;
    229 
    230     /*!
    231       \brief Get truly random number in range 0 - max.
    232 
    233       \param max The maximum value of the random number (non-inclusive).
    234 
    235       \returns Random number.
    236     */
    237     int32_t random(int32_t max);
    238 
    239     /*!
    240       \brief Get truly random number in range min - max.
    241 
    242       \param min The minimum value of the random number (inclusive).
    243 
    244       \param max The maximum value of the random number (non-inclusive).
    245 
    246       \returns Random number.
    247     */
    248     int32_t random(int32_t min, int32_t max);
    249 
    250     /*!
    251       \brief Get one truly random byte from RSSI noise. Must be implemented in module class.
    252 
    253       \returns TRNG byte.
    254     */
    255     virtual uint8_t randomByte() = 0;
    256 
    257     /*!
    258       \brief Configure module parameters for direct modes. Must be called prior to "ham" modes like RTTY or AX.25. Only available in FSK mode.
    259 
    260       \returns \ref status_codes
    261     */
    262     int16_t startDirect();
    263 
    264     #if !defined(RADIOLIB_EXCLUDE_DIRECT_RECEIVE)
    265     /*!
    266       \brief Set sync word to be used to determine start of packet in direct reception mode.
    267 
    268       \param syncWord Sync word bits.
    269 
    270       \param len Sync word length in bits. Set to zero to disable sync word matching.
    271 
    272       \returns \ref status_codes
    273     */
    274     int16_t setDirectSyncWord(uint32_t syncWord, uint8_t len);
    275 
    276     /*!
    277       \brief Set interrupt service routine function to call when data bit is receveid in direct mode. Must be implemented in module class.
    278 
    279       \param func Pointer to interrupt service routine.
    280     */
    281     virtual void setDirectAction(void (*func)(void)) = 0;
    282 
    283     /*!
    284       \brief Function to read and process data bit in direct reception mode. Must be implemented in module class.
    285 
    286       \param pin Pin on which to read.
    287     */
    288     virtual void readBit(RADIOLIB_PIN_TYPE pin) = 0;
    289 
    290     /*!
    291       \brief Get the number of direct mode bytes currently available in buffer.
    292 
    293       \returns Number of available bytes.
    294     */
    295     int16_t available();
    296 
    297     /*!
    298       \brief Get data from direct mode buffer.
    299 
    300       \returns Byte from direct mode buffer.
    301     */
    302     uint8_t read();
    303     #endif
    304 
    305     /*!
    306       \brief Configure DIO pin mapping to get a given signal on a DIO pin (if available).
    307 
    308       \param pin Pin number onto which a signal is to be placed.
    309 
    310       \param value The value that indicates which function to place on that pin. See chip datasheet for details.
    311 
    312       \returns \ref status_codes
    313     */
    314     virtual int16_t setDIOMapping(RADIOLIB_PIN_TYPE pin, uint8_t value);
    315 
    316 #if !defined(RADIOLIB_EXCLUDE_DIRECT_RECEIVE)
    317   protected:
    318     void updateDirectBuffer(uint8_t bit);
    319 #endif
    320 
    321 #if !defined(RADIOLIB_GODMODE)
    322   private:
    323 #endif
    324     float _freqStep;
    325     size_t _maxPacketLength;
    326 
    327     #if !defined(RADIOLIB_EXCLUDE_DIRECT_RECEIVE)
    328     uint8_t _bufferBitPos;
    329     uint8_t _bufferWritePos;
    330     uint8_t _bufferReadPos;
    331     uint8_t _buffer[RADIOLIB_STATIC_ARRAY_SIZE];
    332     uint32_t _syncBuffer;
    333     uint32_t _directSyncWord;
    334     uint8_t _directSyncWordLen;
    335     uint32_t _directSyncWordMask;
    336     bool _gotSync;
    337     #endif
    338 
    339     virtual Module* getMod() = 0;
    340 
    341     // allow specific classes access the private getMod method
    342     friend class AFSKClient;
    343     friend class RTTYClient;
    344     friend class MorseClient;
    345     friend class HellClient;
    346     friend class SSTVClient;
    347     friend class AX25Client;
    348     friend class FSK4Client;
    349 };
    350 
    351 #endif