Implements all common low-level methods to control the wireless module. Every module class contains one private instance of this class. More...

#include <Module.h>

Inheritance diagram for Module:

Classes
struct	RfSwitchMode_t
	Description of RF switch pin states for a single mode. See setRfSwitchTable for details. More...

struct	SPIConfig_t
	SPI configuration structure. More...

Public Types
enum	OpMode_t { MODE_END_OF_TABLE = 0 , MODE_IDLE , MODE_RX , MODE_TX }
	Constants to use in a mode table set be setRfSwitchTable. These constants work for most radios, but some radios define their own constants to be used instead. More...

enum	BitWidth_t { BITS_0 = 0 , BITS_8 = 8 , BITS_16 = 16 , BITS_32 = 32 }

typedef int16_t(*	SPIparseStatusCb_t) (uint8_t in)
	Callback for parsing SPI status.

typedef int16_t(*	SPIcheckStatusCb_t) (Module *mod)
	Callback for validation SPI status.

Public Member Functions
	Module (RadioLibHal *hal, uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio=RADIOLIB_NC)
	Module constructor. More...

	Module (const Module &mod)
	Copy constructor. More...

Module &	operator= (const Module &mod)
	Overload for assignment operator. More...

void	init ()
	Initialize low-level module control.

void	term ()
	Terminate low-level module control.

int16_t	SPIgetRegValue (uint32_t reg, uint8_t msb=7, uint8_t lsb=0)
	SPI read method that automatically masks unused bits. This method is the preferred SPI read mechanism. More...

int16_t	SPIsetRegValue (uint32_t reg, uint8_t value, uint8_t msb=7, uint8_t lsb=0, uint8_t checkInterval=2, uint8_t checkMask=0xFF)
	Overwrite-safe SPI write method with verification. This method is the preferred SPI write mechanism. More...

void	SPIreadRegisterBurst (uint32_t reg, size_t numBytes, uint8_t *inBytes)
	SPI burst read method. More...

uint8_t	SPIreadRegister (uint32_t reg)
	SPI basic read method. Use of this method is reserved for special cases, SPIgetRegValue should be used instead. More...

void	SPIwriteRegisterBurst (uint32_t reg, uint8_t *data, size_t numBytes)
	SPI burst write method. More...

void	SPIwriteRegister (uint32_t reg, uint8_t data)
	SPI basic write method. Use of this method is reserved for special cases, SPIsetRegValue should be used instead. More...

void	SPItransfer (uint16_t cmd, uint32_t reg, uint8_t dataOut, uint8_t dataIn, size_t numBytes)
	SPI single transfer method. More...

int16_t	SPIcheckStream ()
	Method to check the result of last SPI stream transfer. More...

int16_t	SPIreadStream (uint16_t cmd, uint8_t *data, size_t numBytes, bool waitForGpio=true, bool verify=true)
	Method to perform a read transaction with SPI stream. More...

int16_t	SPIreadStream (uint8_t cmd, uint8_t cmdLen, uint8_t data, size_t numBytes, bool waitForGpio=true, bool verify=true)
	Method to perform a read transaction with SPI stream. More...

int16_t	SPIwriteStream (uint16_t cmd, uint8_t *data, size_t numBytes, bool waitForGpio=true, bool verify=true)
	Method to perform a write transaction with SPI stream. More...

int16_t	SPIwriteStream (uint8_t cmd, uint8_t cmdLen, uint8_t data, size_t numBytes, bool waitForGpio=true, bool verify=true)
	Method to perform a write transaction with SPI stream. More...

int16_t	SPItransferStream (const uint8_t cmd, uint8_t cmdLen, bool write, uint8_t dataOut, uint8_t *dataIn, size_t numBytes, bool waitForGpio)
	SPI single transfer method for modules with stream-type SPI interface (SX126x, SX128x etc.). More...

uint32_t	getCs () const
	Access method to get the pin number of SPI chip select. More...

uint32_t	getIrq () const
	Access method to get the pin number of interrupt/GPIO. More...

uint32_t	getRst () const
	Access method to get the pin number of hardware reset pin. More...

uint32_t	getGpio () const
	Access method to get the pin number of second interrupt/GPIO. More...

void	setRfSwitchPins (uint32_t rxEn, uint32_t txEn)
	Some modules contain external RF switch controlled by pins. This function gives RadioLib control over those pins to automatically switch between various modes: When idle both pins will be LOW, during TX the `txEn` pin will be HIGH, during RX the `rxPin` will be HIGH. More...

void	setRfSwitchTable (const uint32_t(&pins)[RFSWITCH_MAX_PINS], const RfSwitchMode_t table[])
	Some modules contain external RF switch controlled by pins. This function gives RadioLib control over those pins to automatically switch between various modes. More...

const RfSwitchMode_t *	findRfSwitchMode (uint8_t mode) const
	Find a mode in the RfSwitchTable. More...

void	setRfSwitchState (uint8_t mode)
	Set RF switch state. More...

void	waitForMicroseconds (RadioLibTime_t start, RadioLibTime_t len)
	Wait for time to elapse, either using the microsecond timer, or the TimerFlag. Note that in interrupt timing mode, it is up to the user to set up the timing interrupt! More...

Public Attributes
RadioLibHal *	hal = NULL
	Hardware abstraction layer to be used.

SPIConfig_t	spiConfig
	SPI configuration structure. The default configuration corresponds to register-access modules, such as SX127x. More...

Static Public Attributes
static const size_t	RFSWITCH_MAX_PINS = 5
	The maximum number of pins supported by the RF switch code. Note: It is not recommended to use this constant in your sketch when defining a rfswitch pins array, to prevent issues when this value is ever increased and such an array gets extra zero elements (that will be interpreted as pin 0).

Detailed Description

Implements all common low-level methods to control the wireless module. Every module class contains one private instance of this class.

Member Enumeration Documentation

◆ OpMode_t

enum Module::OpMode_t

Constants to use in a mode table set be setRfSwitchTable. These constants work for most radios, but some radios define their own constants to be used instead.

See setRfSwitchTable for details.

Enumerator
MODE_END_OF_TABLE	End of table marker, use END_OF_MODE_TABLE constant instead. Value is zero to ensure zero-initialized mode ends the table.
MODE_IDLE	Idle mode.
MODE_RX	Receive mode.
MODE_TX	Transmission mode.

Constructor & Destructor Documentation

◆ Module() [1/2]

Module::Module	(	RadioLibHal *	hal,
		uint32_t	cs,
		uint32_t	irq,
		uint32_t	rst,
		uint32_t	gpio = `RADIOLIB_NC`
	)

Module constructor.

Parameters

hal	A Hardware abstraction layer instance. An ArduinoHal instance for example.
cs	Pin to be used as chip select.
irq	Pin to be used as interrupt/GPIO.
rst	Pin to be used as hardware reset for the module.
gpio	Pin to be used as additional interrupt/GPIO.

◆ Module() [2/2]

Module::Module ( const Module & mod )

Copy constructor.

Parameters

mod	Module instance to copy.

Member Function Documentation

◆ findRfSwitchMode()

const Module::RfSwitchMode_t * Module::findRfSwitchMode ( uint8_t mode ) const

Find a mode in the RfSwitchTable.

Parameters

mode	The mode to find.

Returns: A pointer to the RfSwitchMode_t struct in the table that matches the passed mode. Returns nullptr if no rfswitch pins are configured, or the passed mode is not listed in the table.

◆ getCs()

uint32_t Module::getCs ( ) const

inline

Access method to get the pin number of SPI chip select.

Returns: Pin number of SPI chip select configured in the constructor.

◆ getGpio()

uint32_t Module::getGpio ( ) const

inline

Access method to get the pin number of second interrupt/GPIO.

Returns: Pin number of second interrupt/GPIO configured in the constructor.

◆ getIrq()

uint32_t Module::getIrq ( ) const

inline

Access method to get the pin number of interrupt/GPIO.

Returns: Pin number of interrupt/GPIO configured in the constructor.

◆ getRst()

uint32_t Module::getRst ( ) const

inline

Access method to get the pin number of hardware reset pin.

Returns: Pin number of hardware reset pin configured in the constructor.

◆ operator=()

Module & Module::operator= ( const Module & mod )

Overload for assignment operator.

Parameters

mod	rvalue Module.

◆ setRfSwitchPins()

void Module::setRfSwitchPins	(	uint32_t	rxEn,
		uint32_t	txEn
	)

Some modules contain external RF switch controlled by pins. This function gives RadioLib control over those pins to automatically switch between various modes: When idle both pins will be LOW, during TX the txEn pin will be HIGH, during RX the rxPin will be HIGH.

Radiolib will automatically set the pin mode and value of these pins, so do not control them from the sketch.

When more than two pins or more control over the output values are needed, use the setRfSwitchTable() function.

Parameters

rxEn	RX enable pin.
txEn	TX enable pin.

◆ setRfSwitchState()

void Module::setRfSwitchState ( uint8_t mode )

Set RF switch state.

Parameters

mode	The mode to set. This must be one of the MODE_ constants, or a radio-specific constant.

◆ setRfSwitchTable()

void Module::setRfSwitchTable	(	const uint32_t(&)	pins[RFSWITCH_MAX_PINS],
		const RfSwitchMode_t	table[]
	)

Some modules contain external RF switch controlled by pins. This function gives RadioLib control over those pins to automatically switch between various modes.

Radiolib will automatically set the pin mode and value of these pins, so do not control them from the sketch.

Parameters

pins	A reference to an array of pins to control. This should always be an array of 3 elements. If you need less pins, use RADIOLIB_NC for the unused elements.
table	A reference to an array of pin values to use for each supported mode. Each element is an RfSwitchMode_T struct that lists the mode for which it applies and the values for each of the pins passed in the pins argument respectively.

The pins array will be copied into the Module object, so the original array can be deallocated after this call. However, a reference to the table array will be stored, so that array must remain valid as long RadioLib is being used.

The mode field in each table row should normally use any of the MODE_* constants from the Module::OpMode_t enum. However, some radios support additional modes and will define their own OpMode_t enum.

The length of the table is variable (to support radios that add additional modes), so the table must always be terminated with the special END_OF_MODE_TABLE value.

Normally all modes should be listed in the table, but for some radios, modes can be omitted to indicate they are not supported (e.g. when a radio has a high power and low power TX mode but external circuitry only supports low power). If applicable, this is documented in the radio class itself.

Example

For example, on a board that has an RF switch with an enable pin connected to PA0 and a TX/RX select pin connected to PA1:

// In global scope, define the pin array and mode table
static const uint32_t rfswitch_pins[] =
                       {PA0,  PA1,  RADIOLIB_NC};
static const Module::RfSwitchMode_t rfswitch_table[] = {
  {Module::MODE_IDLE,  {LOW,  LOW}},
  {Module::MODE_RX,    {HIGH, LOW}},
  {Module::MODE_TX,    {HIGH, HIGH}},
   Module::END_OF_MODE_TABLE,
};
 
void setup() {
  ...
  // Then somewhere in setup, pass them to radiolib
  radio.setRfSwitchTable(rfswitch_pins, rfswitch_table);
  ...
}

◆ SPIcheckStream()

int16_t Module::SPIcheckStream ( )

Method to check the result of last SPI stream transfer.

Returns: Status Codes

◆ SPIgetRegValue()

int16_t Module::SPIgetRegValue	(	uint32_t	reg,
		uint8_t	msb = `7`,
		uint8_t	lsb = `0`
	)

SPI read method that automatically masks unused bits. This method is the preferred SPI read mechanism.

Parameters

reg	Address of SPI register to read.
msb	Most significant bit of the register variable. Bits above this one will be masked out.
lsb	Least significant bit of the register variable. Bits below this one will be masked out.

Returns: Masked register value or status code.

◆ SPIreadRegister()

uint8_t Module::SPIreadRegister ( uint32_t reg )

SPI basic read method. Use of this method is reserved for special cases, SPIgetRegValue should be used instead.

Parameters

reg	Address of SPI register to read.

Returns: Value that was read from register.

◆ SPIreadRegisterBurst()

void Module::SPIreadRegisterBurst	(	uint32_t	reg,
		size_t	numBytes,
		uint8_t *	inBytes
	)

SPI burst read method.

Parameters

reg	Address of SPI register to read.
numBytes	Number of bytes that will be read.
inBytes	Pointer to array that will hold the read data.

◆ SPIreadStream() [1/2]

int16_t Module::SPIreadStream	(	uint16_t	cmd,
		uint8_t *	data,
		size_t	numBytes,
		bool	waitForGpio = `true`,
		bool	verify = `true`
	)

Method to perform a read transaction with SPI stream.

Parameters

cmd	SPI operation command.
data	Data that will be transferred from slave to master.
numBytes	Number of bytes to transfer.
waitForGpio	Whether to wait for some GPIO at the end of transfer (e.g. BUSY line on SX126x/SX128x).
verify	Whether to verify the result of the transaction after it is finished.

Returns: Status Codes

◆ SPIreadStream() [2/2]

int16_t Module::SPIreadStream	(	uint8_t *	cmd,
		uint8_t	cmdLen,
		uint8_t *	data,
		size_t	numBytes,
		bool	waitForGpio = `true`,
		bool	verify = `true`
	)

Method to perform a read transaction with SPI stream.

Parameters

cmd	SPI operation command.
cmdLen	SPI command length in bytes.
data	Data that will be transferred from slave to master.
numBytes	Number of bytes to transfer.
waitForGpio	Whether to wait for some GPIO at the end of transfer (e.g. BUSY line on SX126x/SX128x).
verify	Whether to verify the result of the transaction after it is finished.

Returns: Status Codes

◆ SPIsetRegValue()

int16_t Module::SPIsetRegValue	(	uint32_t	reg,
		uint8_t	value,
		uint8_t	msb = `7`,
		uint8_t	lsb = `0`,
		uint8_t	checkInterval = `2`,
		uint8_t	checkMask = `0xFF`
	)

Overwrite-safe SPI write method with verification. This method is the preferred SPI write mechanism.

Parameters

reg	Address of SPI register to write.
value	Single byte value that will be written to the SPI register.
msb	Most significant bit of the register variable. Bits above this one will not be affected by the write operation.
lsb	Least significant bit of the register variable. Bits below this one will not be affected by the write operation.
checkInterval	Number of milliseconds between register writing and verification reading. Some registers need up to 10ms to process the change.
checkMask	Mask of bits to check, only bits set to 1 will be verified.

Returns: Status Codes

◆ SPItransfer()

void Module::SPItransfer	(	uint16_t	cmd,
		uint32_t	reg,
		uint8_t *	dataOut,
		uint8_t *	dataIn,
		size_t	numBytes
	)

SPI single transfer method.

Parameters

cmd	SPI access command (read/write/burst/...).
reg	Address of SPI register to transfer to/from.
dataOut	Data that will be transferred from master to slave.
dataIn	Data that was transferred from slave to master.
numBytes	Number of bytes to transfer.

◆ SPItransferStream()

int16_t Module::SPItransferStream	(	const uint8_t *	cmd,
		uint8_t	cmdLen,
		bool	write,
		uint8_t *	dataOut,
		uint8_t *	dataIn,
		size_t	numBytes,
		bool	waitForGpio
	)

SPI single transfer method for modules with stream-type SPI interface (SX126x, SX128x etc.).

Parameters

cmd	SPI operation command.
cmdLen	SPI command length in bytes.
write	Set to true for write commands, false for read commands.
dataOut	Data that will be transferred from master to slave.
dataIn	Data that was transferred from slave to master.
numBytes	Number of bytes to transfer.
waitForGpio	Whether to wait for some GPIO at the end of transfer (e.g. BUSY line on SX126x/SX128x).

Returns: Status Codes

◆ SPIwriteRegister()

void Module::SPIwriteRegister	(	uint32_t	reg,
		uint8_t	data
	)

SPI basic write method. Use of this method is reserved for special cases, SPIsetRegValue should be used instead.

Parameters

reg	Address of SPI register to write.
data	Value that will be written to the register.

◆ SPIwriteRegisterBurst()

void Module::SPIwriteRegisterBurst	(	uint32_t	reg,
		uint8_t *	data,
		size_t	numBytes
	)

SPI burst write method.

Parameters

reg	Address of SPI register to write.
data	Pointer to array that holds the data that will be written.
numBytes	Number of bytes that will be written.

◆ SPIwriteStream() [1/2]

int16_t Module::SPIwriteStream	(	uint16_t	cmd,
		uint8_t *	data,
		size_t	numBytes,
		bool	waitForGpio = `true`,
		bool	verify = `true`
	)

Method to perform a write transaction with SPI stream.

Parameters

cmd	SPI operation command.
data	Data that will be transferred from master to slave.
numBytes	Number of bytes to transfer.
waitForGpio	Whether to wait for some GPIO at the end of transfer (e.g. BUSY line on SX126x/SX128x).
verify	Whether to verify the result of the transaction after it is finished.

Returns: Status Codes

◆ SPIwriteStream() [2/2]

int16_t Module::SPIwriteStream	(	uint8_t *	cmd,
		uint8_t	cmdLen,
		uint8_t *	data,
		size_t	numBytes,
		bool	waitForGpio = `true`,
		bool	verify = `true`
	)

Method to perform a write transaction with SPI stream.

Parameters

cmd	SPI operation command.
cmdLen	SPI command length in bytes.
data	Data that will be transferred from master to slave.
numBytes	Number of bytes to transfer.
waitForGpio	Whether to wait for some GPIO at the end of transfer (e.g. BUSY line on SX126x/SX128x).
verify	Whether to verify the result of the transaction after it is finished.

Returns: Status Codes

◆ waitForMicroseconds()

void Module::waitForMicroseconds	(	RadioLibTime_t	start,
		RadioLibTime_t	len
	)

Wait for time to elapse, either using the microsecond timer, or the TimerFlag. Note that in interrupt timing mode, it is up to the user to set up the timing interrupt!

Parameters

start	Waiting start timestamp, in microseconds.
len	Waiting duration, in microseconds;

Member Data Documentation

◆ spiConfig

SPIConfig_t Module::spiConfig

Initial value:

= {
      .stream = false,
      .err = RADIOLIB_ERR_UNKNOWN,
      .cmds = { 0x00, 0x80, 0x00, 0x00 },
      .widths = { Module::BITS_8, Module::BITS_0, Module::BITS_8 },
      .statusPos = 0,
      .parseStatusCb = nullptr,
      .checkStatusCb = nullptr,
      .timeout = 1000,
    }

SPI configuration structure. The default configuration corresponds to register-access modules, such as SX127x.

The documentation for this class was generated from the following files:

src/Module.h
src/Module.cpp

Classes

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ OpMode_t

Constructor & Destructor Documentation

◆ Module() [1/2]

◆ Module() [2/2]

Member Function Documentation

◆ findRfSwitchMode()

◆ getCs()

◆ getGpio()

◆ getIrq()

◆ getRst()

◆ operator=()

◆ setRfSwitchPins()

◆ setRfSwitchState()

◆ setRfSwitchTable()

Example

◆ SPIcheckStream()

◆ SPIgetRegValue()

◆ SPIreadRegister()

◆ SPIreadRegisterBurst()

◆ SPIreadStream() [1/2]

◆ SPIreadStream() [2/2]

◆ SPIsetRegValue()

◆ SPItransfer()

◆ SPItransferStream()

◆ SPIwriteRegister()

◆ SPIwriteRegisterBurst()

◆ SPIwriteStream() [1/2]

◆ SPIwriteStream() [2/2]

◆ waitForMicroseconds()

Member Data Documentation

◆ spiConfig