RadioLib Universal wireless communication library for Arduino

Classes | Public Types | Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | List of all members
Module Class Reference

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

## Static Public Member Functions
static uint32_t | reflect (uint32_t in, uint8_t bits)
| Function to reflect bits within a byte. 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 = 3
| 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.

## ◆ reflect()

uint32_t Module::reflect | ( | uint32_t | in,
|  | uint8_t | bits
| ) |  |
| static

Function to reflect bits within a byte.

Parameters

  in | The input to reflect.
  bits | Number of bits to reflect.

Returns
  The reflected input.

## ◆ 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);
...
}
Module::MODE_TX
@ MODE_TX
Transmission mode.
Definition: Module.h:114
Module::MODE_IDLE
@ MODE_IDLE
Idle mode.
Definition: Module.h:108
Module::MODE_RX
@ MODE_RX
Receive mode.
Definition: Module.h:111
Module::RfSwitchMode_t
Description of RF switch pin states for a single mode. See setRfSwitchTable for details.
Definition: Module.h:84

## ◆ 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 | ( | 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 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).
  timeout | GPIO wait period timeout in milliseconds.

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

## ◆ 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,
}
RADIOLIB_ERR_UNKNOWN
#define RADIOLIB_ERR_UNKNOWN
There was an unexpected, unknown error. If you see this, something went incredibly wrong....
Definition: TypeDef.h:110

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