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

Public Types
enum	OpMode_t { MODE_END_OF_TABLE = 0 , MODE_IDLE , MODE_RX , MODE_TX }

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

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 (uint16_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 (uint16_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 (uint16_t reg, size_t numBytes, uint8_t *inBytes)
	SPI burst read method. More...

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

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

void	SPIwriteRegister (uint16_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 (uint8_t cmd, uint16_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 (uint8_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 (uint8_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 (uint8_t cmd, uint8_t cmdLen, bool write, uint8_t dataOut, uint8_t *dataIn, size_t numBytes, bool waitForGpio, uint32_t timeout)
	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 (uint32_t start, uint32_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...

void	regdump (uint16_t start, size_t len)
	Function to dump device registers as hex into the debug port. More...

Static Public Member Functions
static uint8_t	flipBits (uint8_t b)
	Function to reflect bits within a byte.

static uint16_t	flipBits16 (uint16_t i)
	Function to reflect bits within an integer.

static void	hexdump (uint8_t *data, size_t len, uint32_t offset=0, uint8_t width=1, bool be=false)
	Function to dump data as hex into the debug port. More...

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

uint8_t	SPIreadCommand = 0b00000000
	Basic SPI read command. Defaults to 0x00.

uint8_t	SPIwriteCommand = 0b10000000
	Basic SPI write command. Defaults to 0x80.

uint8_t	SPInopCommand = 0x00
	Basic SPI no-operation command. Defaults to 0x00.

uint8_t	SPIstatusCommand = 0x00
	Basic SPI status read command. Defaults to 0x00.

uint8_t	SPIaddrWidth = 8
	SPI address width. Defaults to 8, currently only supports 8 and 16-bit addresses.

bool	SPIstreamType = false
	Whether the SPI interface is stream-type (e.g. SX126x) or register-type (e.g. SX127x). Defaults to register-type SPI interfaces.

int16_t	SPIstreamError = RADIOLIB_ERR_UNKNOWN
	The last recorded SPI stream error.

SPIparseStatusCb_t	SPIparseStatusCb = nullptr
	Callback to function that will parse the module-specific status codes to RadioLib status codes. Typically used for modules with SPI stream-type interface (e.g. SX126x/SX128x).

Static Public Attributes
static const size_t	RFSWITCH_MAX_PINS = 3
	The maximum number of pins supported by the RF switch code. More...

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

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.

◆ hexdump()

void Module::hexdump	(	uint8_t *	data,
		size_t	len,
		uint32_t	offset = `0`,
		uint8_t	width = `1`,
		bool	be = `false`
	)

static

Function to dump data as hex into the debug port.

Parameters

data	Data to dump.
len	Number of bytes to dump.
width	Word width (1 for uint8_t, 2 for uint16_t, 4 for uint32_t).
be	Print multi-byte data as big endian. Defaults to false.

◆ operator=()

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

Overload for assignment operator.

Parameters

frame rvalue Module.

◆ regdump()

void Module::regdump	(	uint16_t	start,
		size_t	len
	)

Function to dump device registers as hex into the debug port.

Parameters

start	First address to dump.
len	Number of bytes to dump.

◆ 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	(	uint16_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 ( uint16_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	(	uint16_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	(	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

◆ SPIreadStream() [2/2]

int16_t Module::SPIreadStream	(	uint8_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

◆ SPIsetRegValue()

int16_t Module::SPIsetRegValue	(	uint16_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	(	uint8_t	cmd,
		uint16_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 transfered from master to slave.
dataIn	Data that was transfered from slave to master.
numBytes	Number of bytes to transfer.

◆ SPItransferStream()

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

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 transfered from master to slave.
dataIn	Data that was transfered 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).
timeout	GPIO wait period timeout in milliseconds.

Returns: Status Codes

◆ SPIwriteRegister()

void Module::SPIwriteRegister	(	uint16_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	(	uint16_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	(	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

◆ SPIwriteStream() [2/2]

int16_t Module::SPIwriteStream	(	uint8_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

◆ waitForMicroseconds()

void Module::waitForMicroseconds	(	uint32_t	start,
		uint32_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

◆ RFSWITCH_MAX_PINS

const size_t Module::RFSWITCH_MAX_PINS = 3

static

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).

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

src/Module.h
src/Module.cpp

Classes

Public Types

Public Member Functions

Static 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()

◆ hexdump()

◆ operator=()

◆ regdump()

◆ 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

◆ RFSWITCH_MAX_PINS