# RadioLib: src/protocols/PhysicalLayer/PhysicalLayer.h Source File

PhysicalLayer.h
#if !defined(_RADIOLIB_PHYSICAL_LAYER_H)
#define _RADIOLIB_PHYSICAL_LAYER_H
#include "../../TypeDef.h"
#include "../../Module.h"
// common IRQ values - the IRQ flags in RadioLibIrqFlags_t arguments are offset by this value
enum RadioLibIrqType_t {
RADIOLIB_IRQ_TX_DONE = 0x00,
RADIOLIB_IRQ_RX_DONE = 0x01,
RADIOLIB_IRQ_PREAMBLE_DETECTED = 0x02,
RADIOLIB_IRQ_SYNC_WORD_VALID = 0x03,
RADIOLIB_IRQ_HEADER_VALID = 0x04,
RADIOLIB_IRQ_HEADER_ERR = 0x05,
RADIOLIB_IRQ_CRC_ERR = 0x06,
RADIOLIB_IRQ_CAD_DONE = 0x07,
RADIOLIB_IRQ_CAD_DETECTED = 0x08,
RADIOLIB_IRQ_TIMEOUT = 0x09,
RADIOLIB_IRQ_NOT_SUPPORTED = 0x1F, // this must be the last value, intentionally set to 31
};
// some commonly used default values - defined here to ensure all modules have the same default behavior
#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))
#define RADIOLIB_IRQ_RX_DEFAULT_MASK ((1UL << RADIOLIB_IRQ_RX_DONE))
#define RADIOLIB_IRQ_CAD_DEFAULT_FLAGS ((1UL << RADIOLIB_IRQ_CAD_DETECTED) | (1UL << RADIOLIB_IRQ_CAD_DONE))
#define RADIOLIB_IRQ_CAD_DEFAULT_MASK ((1UL << RADIOLIB_IRQ_CAD_DETECTED) | (1UL << RADIOLIB_IRQ_CAD_DONE))
struct LoRaRate_t {
uint8_t spreadingFactor;
float bandwidth;
uint8_t codingRate;
};
struct FSKRate_t {
float bitRate;
float freqDev;
};
union DataRate_t {
LoRaRate_t lora;
FSKRate_t fsk;
};
struct CADScanConfig_t {
uint8_t symNum;
uint8_t detPeak;
uint8_t detMin;
uint8_t exitMode;
RadioLibTime_t timeout;
RadioLibIrqFlags_t irqFlags;
RadioLibIrqFlags_t irqMask;
};
struct RSSIScanConfig_t {
float limit;
};
union ChannelScanConfig_t {
CADScanConfig_t cad;
RSSIScanConfig_t rssi;
};
class PhysicalLayer {
public:
// constructor
PhysicalLayer(float step, size_t maxLen);
// basic methods
#if defined(RADIOLIB_BUILD_ARDUINO)
int16_t transmit(__FlashStringHelper* fstr, uint8_t addr = 0);
int16_t transmit(String& str, uint8_t addr = 0);
#endif
int16_t transmit(const char* str, uint8_t addr = 0);
virtual int16_t transmit(const uint8_t* data, size_t len, uint8_t addr = 0);
#if defined(RADIOLIB_BUILD_ARDUINO)
int16_t receive(String& str, size_t len = 0);
#endif
virtual int16_t sleep();
virtual int16_t standby();
virtual int16_t standby(uint8_t mode);
virtual int16_t startReceive();
virtual int16_t startReceive(uint32_t timeout, RadioLibIrqFlags_t irqFlags, RadioLibIrqFlags_t irqMask, size_t len);
virtual int16_t receive(uint8_t* data, size_t len);
#if defined(RADIOLIB_BUILD_ARDUINO)
int16_t startTransmit(String& str, uint8_t addr = 0);
#endif
int16_t startTransmit(const char* str, uint8_t addr = 0);
virtual int16_t startTransmit(const uint8_t* data, size_t len, uint8_t addr = 0);
virtual int16_t finishTransmit();
#if defined(RADIOLIB_BUILD_ARDUINO)
int16_t readData(String& str, size_t len = 0);
#endif
virtual int16_t readData(uint8_t* data, size_t len);
virtual int16_t transmitDirect(uint32_t frf = 0);
virtual int16_t receiveDirect();
// configuration methods
virtual int16_t setFrequency(float freq);
virtual int16_t setBitRate(float br);
virtual int16_t setFrequencyDeviation(float freqDev);
virtual int16_t setDataShaping(uint8_t sh);
virtual int16_t setEncoding(uint8_t encoding);
virtual int16_t invertIQ(bool enable);
virtual int16_t setOutputPower(int8_t power);
virtual int16_t checkOutputPower(int8_t power, int8_t* clipped);
virtual int16_t setSyncWord(uint8_t* sync, size_t len);
virtual int16_t setPreambleLength(size_t len);
virtual int16_t setDataRate(DataRate_t dr);
virtual int16_t checkDataRate(DataRate_t dr);
float getFreqStep() const;
virtual size_t getPacketLength(bool update = true);
virtual float getRSSI();
virtual float getSNR();
virtual RadioLibTime_t getTimeOnAir(size_t len);
virtual RadioLibTime_t calculateRxTimeout(RadioLibTime_t timeoutUs);
uint32_t getIrqMapped(RadioLibIrqFlags_t irq);
int16_t checkIrq(RadioLibIrqType_t irq);
int16_t setIrq(RadioLibIrqFlags_t irq);
int16_t clearIrq(RadioLibIrqFlags_t irq);
virtual uint32_t getIrqFlags();
virtual int16_t setIrqFlags(uint32_t irq);
virtual int16_t clearIrqFlags(uint32_t irq);
virtual int16_t startChannelScan();
virtual int16_t startChannelScan(const ChannelScanConfig_t &config);
virtual int16_t getChannelScanResult();
virtual int16_t scanChannel();
virtual int16_t scanChannel(ChannelScanConfig_t config);
int32_t random(int32_t max);
int32_t random(int32_t min, int32_t max);
virtual uint8_t randomByte();
int16_t startDirect();
#if !RADIOLIB_EXCLUDE_DIRECT_RECEIVE
int16_t setDirectSyncWord(uint32_t syncWord, uint8_t len);
virtual void setDirectAction(void (*func)(void));
virtual void readBit(uint32_t pin);
int16_t available();
void dropSync();
uint8_t read(bool drop = true);
#endif
virtual int16_t setDIOMapping(uint32_t pin, uint32_t value);
virtual void setPacketReceivedAction(void (*func)(void));
virtual void clearPacketReceivedAction();
virtual void setPacketSentAction(void (*func)(void));
virtual void clearPacketSentAction();
virtual void setChannelScanAction(void (*func)(void));
virtual void clearChannelScanAction();
#if RADIOLIB_INTERRUPT_TIMING
void setInterruptSetup(void (*func)(uint32_t));
void setTimerFlag();
#endif
#if !RADIOLIB_GODMODE
protected:
#endif
uint32_t irqMap[10] = { 0 };
#if !RADIOLIB_EXCLUDE_DIRECT_RECEIVE
void updateDirectBuffer(uint8_t bit);
#endif
#if !RADIOLIB_GODMODE
private:
#endif
float freqStep;
size_t maxPacketLength;
#if !RADIOLIB_EXCLUDE_DIRECT_RECEIVE
uint8_t bufferBitPos = 0;
uint8_t bufferWritePos = 0;
uint8_t bufferReadPos = 0;
uint8_t buffer[RADIOLIB_STATIC_ARRAY_SIZE] = { 0 };
uint32_t syncBuffer = 0;
uint32_t directSyncWord = 0;
uint8_t directSyncWordLen = 0;
uint32_t directSyncWordMask = 0;
bool gotSync = false;
#endif
virtual Module* getMod() = 0;
// allow specific classes access the private getMod method
friend class AFSKClient;
friend class RTTYClient;
friend class MorseClient;
friend class HellClient;
friend class SSTVClient;
friend class AX25Client;
friend class FSK4Client;
friend class PagerClient;
friend class BellClient;
friend class FT8Client;
friend class LoRaWANNode;
};
#endif
AFSKClient
Client for audio-based transmissions. Requires Arduino tone() function, and a module capable of direc...
Definition: AFSK.h:16
AX25Client
Client for AX25 communication.
Definition: AX25.h:233
BellClient
Client for Bell modem communication. The public interface is the same as Arduino Serial.
Definition: BellModem.h:57
FSK4Client
Client for FSK-4 communication. The public interface is the same as Arduino Serial.
Definition: FSK4.h:15
HellClient
Client for Hellschreiber transmissions.
Definition: Hellschreiber.h:90
LoRaWANNode
LoRaWAN-compatible node (class A device).
Definition: LoRaWAN.h:524
Module
Implements all common low-level methods to control the wireless module. Every module class contains o...
Definition: Module.h:65
MorseClient
Client for Morse Code communication. The public interface is the same as Arduino Serial.
Definition: Morse.h:93
PagerClient
Client for Pager communication.
Definition: Pager.h:62
PhysicalLayer
Provides common interface for protocols that run on LoRa/FSK modules, such as RTTY or LoRaWAN....
Definition: PhysicalLayer.h:123
PhysicalLayer::invertIQ
virtual int16_t invertIQ(bool enable)
Set IQ inversion. Must be implemented in module class if the module supports it.
Definition: PhysicalLayer.cpp:249
PhysicalLayer::clearChannelScanAction
virtual void clearChannelScanAction()
Clears interrupt service routine to call when a channel scan is finished.
Definition: PhysicalLayer.cpp:529
PhysicalLayer::checkOutputPower
virtual int16_t checkOutputPower(int8_t power, int8_t *clipped)
Check if output power is configurable. Must be implemented in module class if the module supports it.
Definition: PhysicalLayer.cpp:259
PhysicalLayer::startReceive
virtual int16_t startReceive()
Sets module to received mode using its default configuration.
Definition: PhysicalLayer.cpp:131
PhysicalLayer::randomByte
virtual uint8_t randomByte()
Get one truly random byte from RSSI noise. Must be implemented in module class.
Definition: PhysicalLayer.cpp:404
PhysicalLayer::finishTransmit
virtual int16_t finishTransmit()
Clean up after transmission is done.
Definition: PhysicalLayer.cpp:160
PhysicalLayer::checkIrq
int16_t checkIrq(RadioLibIrqType_t irq)
Check whether a specific IRQ bit is set (e.g. RxTimeout, CadDone).
Definition: PhysicalLayer.cpp:325
PhysicalLayer::setFrequencyDeviation
virtual int16_t setFrequencyDeviation(float freqDev)
Sets FSK frequency deviation from carrier frequency. Only available in FSK mode. Must be implemented ...
Definition: PhysicalLayer.cpp:234
PhysicalLayer::getPacketLength
virtual size_t getPacketLength(bool update=true)
Query modem for the packet length of received payload. Must be implemented in module class.
Definition: PhysicalLayer.cpp:290
PhysicalLayer::setPacketSentAction
virtual void setPacketSentAction(void(*func)(void))
Sets interrupt service routine to call when a packet is sent.
Definition: PhysicalLayer.cpp:517
PhysicalLayer::setDIOMapping
virtual int16_t setDIOMapping(uint32_t pin, uint32_t value)
Configure DIO pin mapping to get a given signal on a DIO pin (if available).
Definition: PhysicalLayer.cpp:503
PhysicalLayer::readData
virtual int16_t readData(uint8_t *data, size_t len)
Reads data that was received after calling startReceive method.
Definition: PhysicalLayer.cpp:209
PhysicalLayer::dropSync
void dropSync()
Forcefully drop synchronization.
Definition: PhysicalLayer.cpp:427
PhysicalLayer::transmit
int16_t transmit(const char *str, uint8_t addr=0)
C-string transmit method.
Definition: PhysicalLayer.cpp:52
PhysicalLayer::read
uint8_t read(bool drop=true)
Get data from direct mode buffer.
Definition: PhysicalLayer.cpp:434
PhysicalLayer::getTimeOnAir
virtual RadioLibTime_t getTimeOnAir(size_t len)
Get expected time-on-air for a given size of payload.
Definition: PhysicalLayer.cpp:303
PhysicalLayer::checkDataRate
virtual int16_t checkDataRate(DataRate_t dr)
Check the data rate can be configured by this module. Must be implemented in module class if the modu...
Definition: PhysicalLayer.cpp:281
PhysicalLayer::getChannelScanResult
virtual int16_t getChannelScanResult()
Read the channel scan result.
Definition: PhysicalLayer.cpp:364
PhysicalLayer::clearPacketSentAction
virtual void clearPacketSentAction()
Clears interrupt service routine to call when a packet is sent.
Definition: PhysicalLayer.cpp:521
PhysicalLayer::setSyncWord
virtual int16_t setSyncWord(uint8_t *sync, size_t len)
Set sync word. Must be implemented in module class if the module supports it.
Definition: PhysicalLayer.cpp:265
PhysicalLayer::setDataRate
virtual int16_t setDataRate(DataRate_t dr)
Set data. Must be implemented in module class if the module supports it.
Definition: PhysicalLayer.cpp:276
PhysicalLayer::clearPacketReceivedAction
virtual void clearPacketReceivedAction()
Clears interrupt service routine to call when a packet is received.
Definition: PhysicalLayer.cpp:513
PhysicalLayer::calculateRxTimeout
virtual RadioLibTime_t calculateRxTimeout(RadioLibTime_t timeoutUs)
Calculate the timeout value for this specific module / series (in number of symbols or units of time)...
Definition: PhysicalLayer.cpp:308
PhysicalLayer::setIrq
int16_t setIrq(RadioLibIrqFlags_t irq)
Set interrupt on specific IRQ bit(s) (e.g. RxTimeout, CadDone). Keep in mind that not all radio modul...
Definition: PhysicalLayer.cpp:333
PhysicalLayer::setPreambleLength
virtual int16_t setPreambleLength(size_t len)
Set preamble length. Must be implemented in module class if the module supports it.
Definition: PhysicalLayer.cpp:271
PhysicalLayer::startDirect
int16_t startDirect()
Configure module parameters for direct modes. Must be called prior to "ham" modes like RTTY or AX....
Definition: PhysicalLayer.cpp:408
PhysicalLayer::setFrequency
virtual int16_t setFrequency(float freq)
Sets carrier frequency. Must be implemented in module class.
Definition: PhysicalLayer.cpp:224
PhysicalLayer::setDirectSyncWord
int16_t setDirectSyncWord(uint32_t syncWord, uint8_t len)
Set sync word to be used to determine start of packet in direct reception mode.
Definition: PhysicalLayer.cpp:442
PhysicalLayer::startTransmit
int16_t startTransmit(const char *str, uint8_t addr=0)
Interrupt-driven Arduino String transmit method. Unlike the standard transmit method,...
Definition: PhysicalLayer.cpp:149
PhysicalLayer::getFreqStep
float getFreqStep() const
Gets the module frequency step size that was set in constructor.
Definition: PhysicalLayer.cpp:286
PhysicalLayer::transmitDirect
virtual int16_t transmitDirect(uint32_t frf=0)
Enables direct transmission mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module ...
Definition: PhysicalLayer.cpp:215
PhysicalLayer::getRSSI
virtual float getRSSI()
Gets RSSI (Recorded Signal Strength Indicator) of the last received packet.
Definition: PhysicalLayer.cpp:295
PhysicalLayer::available
int16_t available()
Get the number of direct mode bytes currently available in buffer.
Definition: PhysicalLayer.cpp:423
PhysicalLayer::receive
virtual int16_t receive(uint8_t *data, size_t len)
Binary receive method. Must be implemented in module class.
Definition: PhysicalLayer.cpp:112
PhysicalLayer::scanChannel
virtual int16_t scanChannel()
Check whether the current communication channel is free or occupied. Performs CAD for LoRa modules,...
Definition: PhysicalLayer.cpp:368
PhysicalLayer::setDirectAction
virtual void setDirectAction(void(*func)(void))
Set interrupt service routine function to call when data bit is received in direct mode....
Definition: PhysicalLayer.cpp:493
PhysicalLayer::clearIrqFlags
virtual int16_t clearIrqFlags(uint32_t irq)
Clear interrupt on a specific IRQ bit (e.g. RxTimeout, CadDone). Must be implemented in module class.
Definition: PhysicalLayer.cpp:350
PhysicalLayer::setEncoding
virtual int16_t setEncoding(uint8_t encoding)
Sets FSK data encoding. Only available in FSK mode. Must be implemented in module class.
Definition: PhysicalLayer.cpp:244
PhysicalLayer::standby
virtual int16_t standby()
Sets module to standby.
Definition: PhysicalLayer.cpp:122
PhysicalLayer::random
int32_t random(int32_t max)
Get truly random number in range 0 - max.
Definition: PhysicalLayer.cpp:377
PhysicalLayer::readBit
virtual void readBit(uint32_t pin)
Function to read and process data bit in direct reception mode. Must be implemented in module class.
Definition: PhysicalLayer.cpp:497
PhysicalLayer::setOutputPower
virtual int16_t setOutputPower(int8_t power)
Set output power. Must be implemented in module class if the module supports it.
Definition: PhysicalLayer.cpp:254
PhysicalLayer::receiveDirect
virtual int16_t receiveDirect()
Enables direct reception mode on pins DIO1 (clock) and DIO2 (data). Must be implemented in module cla...
Definition: PhysicalLayer.cpp:220
PhysicalLayer::PhysicalLayer
PhysicalLayer(float step, size_t maxLen)
Default constructor.
Definition: PhysicalLayer.cpp:4
PhysicalLayer::setChannelScanAction
virtual void setChannelScanAction(void(*func)(void))
Sets interrupt service routine to call when a channel scan is finished.
Definition: PhysicalLayer.cpp:525
PhysicalLayer::startChannelScan
virtual int16_t startChannelScan()
Interrupt-driven channel activity detection method. Interrupt will be activated when packet is detect...
Definition: PhysicalLayer.cpp:355
PhysicalLayer::getIrqMapped
uint32_t getIrqMapped(RadioLibIrqFlags_t irq)
Convert from radio-agnostic IRQ flags to radio-specific flags.
Definition: PhysicalLayer.cpp:313
PhysicalLayer::setDataShaping
virtual int16_t setDataShaping(uint8_t sh)
Sets GFSK data shaping. Only available in FSK mode. Must be implemented in module class.
Definition: PhysicalLayer.cpp:239
PhysicalLayer::setPacketReceivedAction
virtual void setPacketReceivedAction(void(*func)(void))
Sets interrupt service routine to call when a packet is received.
Definition: PhysicalLayer.cpp:509
PhysicalLayer::setBitRate
virtual int16_t setBitRate(float br)
Sets FSK bit rate. Only available in FSK mode. Must be implemented in module class.
Definition: PhysicalLayer.cpp:229
PhysicalLayer::getSNR
virtual float getSNR()
Gets SNR (Signal to Noise Ratio) of the last received packet. Only available for LoRa modem.
Definition: PhysicalLayer.cpp:299
PhysicalLayer::sleep
virtual int16_t sleep()
Sets module to sleep.
Definition: PhysicalLayer.cpp:118
PhysicalLayer::getIrqFlags
virtual uint32_t getIrqFlags()
Read currently active IRQ flags. Must be implemented in module class.
Definition: PhysicalLayer.cpp:341
PhysicalLayer::setIrqFlags
virtual int16_t setIrqFlags(uint32_t irq)
Set interrupt on DIO1 to be sent on a specific IRQ bit (e.g. RxTimeout, CadDone). Must be implemented...
Definition: PhysicalLayer.cpp:345
PhysicalLayer::clearIrq
int16_t clearIrq(RadioLibIrqFlags_t irq)
Clear interrupt on a specific IRQ bit (e.g. RxTimeout, CadDone). Keep in mind that not all radio modu...
Definition: PhysicalLayer.cpp:337
RTTYClient
Client for RTTY communication. The public interface is the same as Arduino Serial.
Definition: RTTY.h:17
SSTVClient
Client for SSTV transmissions.
Definition: SSTV.h:121
RadioLibTime_t
unsigned long RadioLibTime_t
Type used for durations in RadioLib.
Definition: TypeDef.h:616
RadioLibIrqFlags_t
uint32_t RadioLibIrqFlags_t
Type used for radio-agnostic IRQ flags. IRQ to enable corresponds to the bit index (RadioLibIrq_t)....
Definition: TypeDef.h:622
CADScanConfig_t
Channel scan configuration interpretation in case LoRa CAD is used.
Definition: PhysicalLayer.h:71
CADScanConfig_t::timeout
RadioLibTime_t timeout
Timeout in microseconds.
Definition: PhysicalLayer.h:85
CADScanConfig_t::detPeak
uint8_t detPeak
Number of peak detection symbols.
Definition: PhysicalLayer.h:76
CADScanConfig_t::symNum
uint8_t symNum
Number of symbols to consider signal present.
Definition: PhysicalLayer.h:73
CADScanConfig_t::exitMode
uint8_t exitMode
Exit mode after signal detection is complete - module-specific value.
Definition: PhysicalLayer.h:82
CADScanConfig_t::irqFlags
RadioLibIrqFlags_t irqFlags
Optional IRQ flags to set, bits offset by the value of RADIOLIB_IRQ_.
Definition: PhysicalLayer.h:88
CADScanConfig_t::irqMask
RadioLibIrqFlags_t irqMask
Optional IRQ mask to set, bits offset by the value of RADIOLIB_IRQ_.
Definition: PhysicalLayer.h:91
CADScanConfig_t::detMin
uint8_t detMin
Number of minimum detection symbols.
Definition: PhysicalLayer.h:79
FSKRate_t
Data rate structure interpretation in case FSK is used.
Definition: PhysicalLayer.h:47
FSKRate_t::bitRate
float bitRate
FSK bit rate in kbps.
Definition: PhysicalLayer.h:49
FSKRate_t::freqDev
float freqDev
FSK frequency deviation in kHz.
Definition: PhysicalLayer.h:52
LoRaRate_t
Data rate structure interpretation in case LoRa is used.
Definition: PhysicalLayer.h:32
LoRaRate_t::spreadingFactor
uint8_t spreadingFactor
LoRa spreading factor.
Definition: PhysicalLayer.h:34
LoRaRate_t::bandwidth
float bandwidth
LoRa bandwidth in kHz.
Definition: PhysicalLayer.h:37
LoRaRate_t::codingRate
uint8_t codingRate
LoRa coding rate.
Definition: PhysicalLayer.h:40
RSSIScanConfig_t
Channel scan configuration interpretation in case RSSI threshold is used.
Definition: PhysicalLayer.h:98
RSSIScanConfig_t::limit
float limit
RSSI limit in dBm.
Definition: PhysicalLayer.h:100
ChannelScanConfig_t
Common channel scan configuration structure.
Definition: PhysicalLayer.h:107
ChannelScanConfig_t::rssi
RSSIScanConfig_t rssi
Interpretation for modems that use RSSI threshold.
Definition: PhysicalLayer.h:112
ChannelScanConfig_t::cad
CADScanConfig_t cad
Interpretation for modems that use CAD (usually LoRa modems)
Definition: PhysicalLayer.h:109
DataRate_t
Common data rate structure.
Definition: PhysicalLayer.h:59
DataRate_t::lora
LoRaRate_t lora
Interpretation for LoRa modems.
Definition: PhysicalLayer.h:61
DataRate_t::fsk
FSKRate_t fsk
Interpretation for FSK modems.
Definition: PhysicalLayer.h:64