Driver to send and receive unaddressed, unreliable datagrams via a Semtech SX126X family LoRa capable radio transceiver. More...

#include <RH_SX126x.h>

Inheritance diagram for RH_SX126x:

Classes
struct	ModemConfig
	Defines register values for a set of modem configuration registers. More...

struct	RadioPinConfig

struct	RadioPinConfigEntry

Public Types
enum	PacketType { PacketTypeLoRa = 0 , PacketTypeGFSK }
	Packet types the modem can be configured for. More...

enum	ModemConfigChoice { LoRa_Bw125Cr45Sf128 = 0 , LoRa_Bw500Cr45Sf128 , LoRa_Bw31_25Cr48Sf512 , LoRa_Bw125Cr48Sf4096 , LoRa_Bw125Cr45Sf2048 }

enum	RadioPinConfigMode { RadioPinConfigMode_EOT = 0 , RadioPinConfigMode_IDLE , RadioPinConfigMode_RX , RadioPinConfigMode_TX_LOW_POWER , RadioPinConfigMode_TX_HIGH_POWER }

Public Types inherited from RHGenericDriver
enum	RHMode { RHModeInitialising = 0 , RHModeSleep , RHModeIdle , RHModeTx , RHModeRx , RHModeCad }
	Defines different operating modes for the transport hardware. More...

Public Member Functions
	RH_SX126x (uint8_t slaveSelectPin=SS, uint8_t interruptPin=2, uint8_t busyPin=RH_INVALID_PIN, uint8_t resetPin=RH_INVALID_PIN, RHGenericSPI &spi=hardware_spi, RadioPinConfig *radioPinConfig=nullptr)

virtual bool	init ()

bool	printRegisters (uint16_t address, uint8_t count)

bool	setModemRegisters (const ModemConfig *config)

bool	setModemConfig (ModemConfigChoice index)

virtual bool	available ()

virtual bool	recv (uint8_t buf, uint8_t len)

virtual bool	send (const uint8_t *data, uint8_t len)

void	setPreambleLength (uint16_t bytes)

virtual uint8_t	maxMessageLength ()

bool	setFrequency (float centre, bool calibrate=true)

void	setModeIdle ()

void	setModeRx ()

void	setModeTx ()

virtual bool	setTxPower (int8_t power)

virtual bool	sleep ()

virtual bool	isChannelActive ()

int	lastSNR ()

void	setRadioPinConfig (RadioPinConfig *config)

bool	setTxContinuous ()

uint8_t	getStatus ()
	Read and return the radio status byte.

Public Member Functions inherited from RHSPIDriver
	RHSPIDriver (uint8_t slaveSelectPin=SS, RHGenericSPI &spi=hardware_spi)

bool	init ()

uint8_t	spiRead (uint8_t reg)

uint8_t	spiWrite (uint8_t reg, uint8_t val)

uint8_t	spiBurstRead (uint8_t reg, uint8_t *dest, uint8_t len)

uint8_t	spiBurstWrite (uint8_t reg, const uint8_t *src, uint8_t len)

void	setSlaveSelectPin (uint8_t slaveSelectPin)

void	spiUsingInterrupt (uint8_t interruptNumber)

Public Member Functions inherited from RHGenericDriver
	RHGenericDriver ()
	Constructor.

virtual	~RHGenericDriver ()
	Generic destructor to prevent warnings when objects are dynamically allocated.

virtual bool	init ()

virtual bool	available ()=0

virtual bool	recv (uint8_t buf, uint8_t len)=0

virtual bool	send (const uint8_t *data, uint8_t len)=0

virtual uint8_t	maxMessageLength ()=0

virtual void	waitAvailable (uint16_t polldelay=0)

virtual bool	waitPacketSent ()

virtual bool	waitPacketSent (uint16_t timeout)

virtual bool	waitAvailableTimeout (uint16_t timeout, uint16_t polldelay=0)

virtual bool	waitCAD ()

void	setCADTimeout (unsigned long cad_timeout)

virtual bool	isChannelActive ()

virtual void	setThisAddress (uint8_t thisAddress)

virtual void	setHeaderTo (uint8_t to)

virtual void	setHeaderFrom (uint8_t from)

virtual void	setHeaderId (uint8_t id)

virtual void	setHeaderFlags (uint8_t set, uint8_t clear=RH_FLAGS_APPLICATION_SPECIFIC)

virtual void	setPromiscuous (bool promiscuous)

virtual uint8_t	headerTo ()

virtual uint8_t	headerFrom ()

virtual uint8_t	headerId ()

virtual uint8_t	headerFlags ()

virtual int16_t	lastRssi ()

virtual RHMode	mode ()

virtual void	setMode (RHMode mode)
	Sets the operating mode of the transport. More...

virtual bool	sleep ()

virtual uint16_t	rxBad ()

virtual uint16_t	rxGood ()

virtual uint16_t	txGood ()

Protected Member Functions
virtual bool	waitUntilNotBusy ()

bool	sendCommand (uint8_t command, uint8_t data[], uint8_t len)
	Send a command with multi-byte data to the radio.

bool	sendCommand (uint8_t command, uint8_t value)
	Send a command with a single data byte to the radio.

bool	sendCommand (uint8_t command)
	Send a command without any data to the radio.

bool	getCommand (uint8_t command, uint8_t data[], uint8_t len)
	Send a command to the radio and get a multi-byte respose.

bool	readRegisters (uint16_t address, uint8_t data[], uint8_t len)
	Read multiple registers from the radio.

uint8_t	readRegister (uint16_t address)
	Read and return a single register byte from the radio.

bool	writeRegisters (uint16_t address, uint8_t data[], uint8_t len)
	Write multibyte data to the given register and sunbsequent registers.

bool	writeRegister (uint16_t address, uint8_t data)
	Write a single byte to the given register.

bool	writeBuffer (uint8_t offset, const uint8_t data[], uint8_t len)
	Write multibyte data to the radio IO buffer at the current buffer address.

bool	writeBuffer (uint8_t offset, const char *text)
	Write a single byte to the radio IO bufferat the current buffer address.

bool	readBuffer (uint8_t offset, uint8_t data[], uint8_t len)
	Read multibyte data from the radio IO buffer at the current buffer address.

bool	setPaConfig (uint8_t paDutyCycle, uint8_t hpMax, uint8_t deviceSel, uint8_t paLut)
	Set the radio Power Amplifier configuration.

bool	setTxParams (uint8_t power, uint8_t rampTime)
	Set the radio power output. CAUTION: for internal use only. Users should use setTxPower()

bool	clearDeviceErrors ()
	Clear the radio error byte.

bool	setDIO2AsRfSwitchCtrl (bool value)

bool	setRxFallbackMode (uint8_t mode)
	Sets the mode that the radio will change to after a transmit or receive is complete.

bool	setModulationParameters (uint8_t p1, uint8_t p2, uint8_t p3, uint8_t p4, uint8_t p5, uint8_t p6, uint8_t p7, uint8_t p8)
	Set the low-level registers for any desired modulation scheme.

bool	setModulationParametersLoRa (uint8_t sf, float bw, uint8_t cr, bool ldro)
	Set the low-level registers for the desired LoRA modulation scheme.

bool	setModulationParametersGFSK (uint32_t br, uint8_t sh, uint8_t rxBw, uint32_t freqDev)
	Set the low-level registers for the desired GFSK modulation scheme.

bool	calibrate (uint8_t calib_param)
	Cause the radio to calibrate all its sections at the currently selected frequency.

bool	calibrateImage (uint8_t f1, uint8_t f2)
	Allows the user to calibrate the image rejection of the device for the device operating frequency band.

bool	setLoRaSyncWord (uint16_t sync)
	Set the 16 bit LoRa sync word.

bool	setOCPConfiguration (uint8_t setting)
	Set the radio power amplifier over-current protection.

bool	setDIO3AsTcxoCtrl (uint8_t voltage, uint32_t delay)

bool	setTCXO (float voltage, uint32_t delay)
	Set the voltage to use for the TCXO oven.

bool	setPacketParams (uint8_t p1, uint8_t p2, uint8_t p3, uint8_t p4, uint8_t p5, uint8_t p6, uint8_t p7, uint8_t p8, uint8_t p9)
	Low level function to set the radio packet confiuration.

bool	setPacketParametersLoRa (uint8_t payload_length)
	Set the necessary radio packet parameters for a forthcoming transmission of payload_length bytes.

bool	setBufferBaseAddress (uint8_t txbase, uint8_t rxbase)
	Low level function to set the address wherge the next radBuffer or writeBuffer will occur.

bool	setSleep (uint8_t config)
	Set the radio to sleep mode. Automatically configures the radio control pins to the configuration RadioPinConfigMode_IDLE.

bool	setStandby (uint8_t config)
	Set the radio to sleep mode. Automatically configures the radio control pins to the configuration RadioPinConfigMode_IDLE.

bool	setTx (uint32_t timeout)

bool	setCad ()
	Starts the radio in Clear Air Detect (CAD) mode. CAUTION: NOT YET WORKING, always retuns false.

bool	setRx (uint32_t timeout)
	Set the radio to receive mode. Automatically configures the radio control pins to the configuration RadioPinConfigMode_RX.

bool	setRxBoostMode (bool boost, bool retain)
	Sets whether radios receiver gain boost should be enabled instead of the default power saving mode.

bool	setRegulatorMode (uint8_t mode)

bool	setDioIrqParams (uint16_t irqmask, uint16_t dio1mask, uint16_t dio2mask, uint16_t dio3mask)
	Configures the conditions under which the radio will enable an interrupt, and for which DIO pins.

bool	clearIrqStatus (uint16_t mask)
	Clear the radio IRQ state.

uint16_t	getIrqStatus ()
	Return the radio IRQ state.

uint8_t	getPacketType ()
	return the current packet type

void	setInvertIQ (bool invertIQ)

bool	fixPAClamping (bool enable)
	Per SX1262_datasheet.pdf Rev 1.2 section 15.2, this fixes an error in the radio Power Amplifier clamping.

virtual bool	setupInterruptHandler ()
	Do whatever is necesary to establish the interrupt handler. Subclasses may have different needs. More...

void	handleInterrupt ()

void	validateRxBuf ()
	Examine the revceive buffer to determine whether the message is for this node.

void	clearRxBuf ()
	Clear our local receive buffer.

virtual bool	modeWillChange (RHMode)

virtual bool	setRadioPinsForMode (RadioPinConfigMode mode)

virtual RadioPinConfigEntry *	findRadioPinConfigEntry (RadioPinConfigMode mode)
	Find the pin configuration entry for a desired radio mode.

Protected Member Functions inherited from RHSPIDriver
virtual void	beginTransaction ()

virtual void	endTransaction ()

virtual void	selectSlave ()

virtual void	deselectSlave ()

Additional Inherited Members
Static Public Member Functions inherited from RHGenericDriver
static void	printBuffer (const char prompt, const uint8_t buf, uint8_t len)

Protected Attributes inherited from RHSPIDriver
RHGenericSPI &	_spi
	Reference to the RHGenericSPI instance to use to transfer data with the SPI device.

uint8_t	_slaveSelectPin
	The pin number of the Slave Select pin that is used to select the desired device.

Protected Attributes inherited from RHGenericDriver
volatile RHMode	_mode
	The current transport operating mode.

uint8_t	_thisAddress
	This node id.

bool	_promiscuous
	Whether the transport is in promiscuous mode.

volatile uint8_t	_rxHeaderTo
	TO header in the last received mesasge.

volatile uint8_t	_rxHeaderFrom
	FROM header in the last received mesasge.

volatile uint8_t	_rxHeaderId
	ID header in the last received mesasge.

volatile uint8_t	_rxHeaderFlags
	FLAGS header in the last received mesasge.

uint8_t	_txHeaderTo
	TO header to send in all messages.

uint8_t	_txHeaderFrom
	FROM header to send in all messages.

uint8_t	_txHeaderId
	ID header to send in all messages.

uint8_t	_txHeaderFlags
	FLAGS header to send in all messages.

volatile int16_t	_lastRssi
	The value of the last received RSSI value, in some transport specific units.

volatile uint16_t	_rxBad
	Count of the number of bad messages (eg bad checksum etc) received.

volatile uint16_t	_rxGood
	Count of the number of successfully transmitted messaged.

volatile uint16_t	_txGood
	Count of the number of bad messages (correct checksum etc) received.

volatile bool	_cad
	Channel activity detected.

unsigned int	_cad_timeout
	Channel activity timeout in ms.

Detailed Description

Driver to send and receive unaddressed, unreliable datagrams via a Semtech SX126X family LoRa capable radio transceiver.

Works with NiceRF LoRa1262-915 and Teensy 3.1. Will probably work with any other SX1262 module.

Overview

This class provides basic functions for sending and receiving unaddressed, unreliable datagrams of arbitrary length to 251 octets per packet.

Manager classes may use this class to implement reliable, addressed datagrams and streams, mesh routers, repeaters, translators etc.

Naturally, for any 2 radios to communicate that must be configured to use the same frequency and modulation scheme.

Predefined modulation schemes are available for various LoRa modulation speeds and bandwidths. GFSK modulation is also supported.

The SX126x family of radio chips are availabel as discrete comonents with an SPI interface. In some hardware (eg the STM32WLE5xx STM32WLE4xx processors) the radio is built into a microprocessor.

Packet Format

All messages sent and received by this RH_SX126x Driver conform to this packet format, which is compatible with RH_RF95:

LoRa mode:
8 symbol PREAMBLE
Explicit header with header CRC (default CCITT, handled internally by the radio)
4 octets HEADER: (TO, FROM, ID, FLAGS)
0 to 251 octets DATA
CRC (default CCITT, handled internally by the radio)

Interrupts

The RH_SX126x driver uses interrupts to react to events in the radio, such as the reception of a new packet, or the completion of transmission of a packet. The driver configures the radio so the required interrupt is generated by the radio's DIO1 pin. The RH_SX126x driver interrupt service routine reads status from and writes data to the the radio module via an SPI interface. It is very important therefore, that if you are using the RH_SX126x driver with another SPI based deviced, that you disable interrupts while you transfer data to and from that other device. Use cli() to disable interrupts and sei() to reenable them. (however note that the RH_STM32WLx subclass uses the dedicated internal SPI interface that is connected only to the radio).

Memory

The RH_SX126x driver requires non-trivial amounts of memory. The sample programs all compile to about 35 kbytes each, which will fit in the flash proram memory of most Arduinos. However, the RAM requirements are more critical. Therefore, you should be vary sparing with RAM use in programs that use the RH_SX126x driver.

Compatibility with RH_RF95

The predefined modulation schemes have been show to interoperate with the RH_RF95 driver with similarly named modulation schemes.

For example the (default) RH_SX126x::LoRa_Bw125Cr45Sf128 is compatible with the (default) RH_RF95::Bw125Cr45Sf128.

The RH_SX126x driver sets the LoRa Sync word to 0x1424, which is compatible with single byte 0x12 default for RH_RF95. https://forum.lora-developers.semtech.com/t/sx1272-and-sx1262-lora-sync-word-compatibility/988/13

Transmitter Power

We measured the RF power output from a Wio-E5 mini at 868.0 MHz, with the radio set to continuous CW transmission using setTxContinuous(). On this chip that implies the high power amplifier. We set various power outputs with setTxPower() from -9 to 22 and measured the RF output power with a HP 5342A Microwave Frequency Counter. Note that the drivers setTxPower() sets the optimum transmitter control registers per section 13.1.14.1 of the datasheet SX1262_datasheet.pdf

Program power              Measured power
     dBm                      dBm
    -9                       -5.0
                     -2.9
                      6.9
                      8.9
                     13.3
                     14.1
                     14.6
                     16.7
                     17.3
                     17.8
                     18.7
                     19.4

With the transmitter frequency set to 868.0 MHz, the actual centre frequency measured with the HP 5342A Microwave Frequency Counter on 2 instances of Wio-E5 mini were 867.999826 and 867.999652 MHz.

Differences between models

SX126x compatible chips are available in at least 4 types:

-SX1261 Has only one (low power) PA, -17 to +15 dBm

-SX1262 Has only one (high power) PA, -9 to +22 dBm

-SX1268 Has 2 PAs, low power (-17 to +15 dBm) and high power (-9 to +22 dBm)

-STM32WLE5JC has 2 PAs, low power (-17 to +15 dBm) and high power (-9 to +22 dBm).

Even if the radio has 2 PAs, depending on your radio module, maybe only one is connected. It also includes a dedicated SPI interface for the radio plus some internllay connected reset and interrupt pins

Some radio modules might also include an antenna switch, and the driver MUST be configured so that it knows how to turn any control pins on and off for receiving and transmitting. See setRadioPinConfig().

Configuring the driver for your particular type of radio

You will almost certainly have to configure this driver to suit the particular radio hardware in your system. Its boring but you MUST pay attention to this otherwise you may not be able to transmit or receive successfully.

This issues you will have to consider are:

What model radio do you have?
What SPI bus is the radio connected to?
Is there a TCXO to configure?
What pin is used for the SPI slave select for the radio chip?
Is the radio reset pin connected to the CPU?
Are there any pins required to be set to control the external radio interface, such as RF switches, external PAs etc,

If you are using a ST Microelectronics STM32WLE5xx or STM32WLE4xx processors and its built in radio, you can use the RH_STM32WLx and ignore most or all of these issues.

Range

No range tests have yet been conducted.

Connecting SX126x modules to Arduino

Note, if you are using a STM32WLE5JC, see the intructions for that in RH_STM32WLx.h

Connecting a NiceRF LoRa1262-915 to a Teensy 3.1:

https://www.nicerf.com/lora-module/915mhz-lora-module-lora1262.html

We got one on a breakout board which already has a small helical antenna connected. The module appears to contain a 3.3V TCXO, nd an antenna switch connected to DIO2 You should be able to use a similar pinout for any 3.3V Arduino compatible board.

                Teensy 3.1    G-Nice RF LoRa1262-915
                GND----------GND   (Ground)
                3V3----------VCC   (3.3V in)
            pin D7-----------DIO1  (radio interrupt request out, active high)
            pin D8-----------BUSY  (radio busy output, active high)
            pin D9-----------NRESET (radio reset in: pulled low for 2ms at startup)
         SS pin D10----------NSS   (chip select in)
        SCK pin D13----------SCK   (SPI clock in)
       MOSI pin D11----------MOSI  (SPI Data in)
       MISO pin D12----------MISO  (SPI Data out)
                
With these connections you can then use the constructor:
 
RH_SX126x driver(SS, 7, 8, 9);

RAKwireless RAK4360/RAK4361

RHHardwareSPI uses the default LoRa radio SPI pins as defined by the platform. You can use the contructor:

RH_SX126x driver(42, 47, 46, 38); // NSS, DIO1, BUSY, NRESET

Member Enumeration Documentation

◆ ModemConfigChoice

enum RH_SX126x::ModemConfigChoice

Choices for setModemConfig() for a selected subset of common data rates. If you need another configuration, determine the necessary settings and call setModemRegisters() with your desired settings. It might be helpful to use the LoRa calculator mentioned in http://www.semtech.com/images/datasheet/LoraDesignGuide_STD.pdf These are indexes into MODEM_CONFIG_TABLE. We strongly recommend you use these symbolic definitions and not their integer equivalents: its possible that new values will be introduced in later versions (though we will try to avoid it). Caution: if you are using slow packet rates and long packets with RHReliableDatagram or subclasses you may need to change the RHReliableDatagram timeout for reliable operations. Caution: for some slow rates nad with ReliableDatagrams you may need to increase the reply timeout with manager.setTimeout() to deal with the long transmission times. Caution: SX1276 family errata suggests alternate settings for some LoRa registers when 500kHz bandwidth is in use. See the Semtech SX1276/77/78 Errata Note. These are not implemented by RH_SX126x. In general, the LoRa_* configurations are compatible with the similarly named RH_RF95 configurations

Enumerator
LoRa_Bw125Cr45Sf128	Bw = 125 kHz, Cr = 4/5, Sf = 128chips/symbol, CRC on. Default medium range.
LoRa_Bw500Cr45Sf128	Bw = 500 kHz, Cr = 4/5, Sf = 128chips/symbol, CRC on. Fast+short range.
LoRa_Bw31_25Cr48Sf512	Bw = 31.25 kHz, Cr = 4/8, Sf = 512chips/symbol, CRC on. Slow+long range.
LoRa_Bw125Cr48Sf4096	Bw = 125 kHz, Cr = 4/8, Sf = 4096chips/symbol, low data rate, CRC on. Slow+long range.
LoRa_Bw125Cr45Sf2048	Bw = 125 kHz, Cr = 4/5, Sf = 2048chips/symbol, CRC on. Slow+long range.

◆ PacketType

enum RH_SX126x::PacketType

Packet types the modem can be configured for.

Enumerator
PacketTypeLoRa	Use LoRA packets.
PacketTypeGFSK	Use GFSK packets.

◆ RadioPinConfigMode

enum RH_SX126x::RadioPinConfigMode

Structures and enums for Tx/Rx pin configuration These structures allow you to specify what pins are to be automaticall set or cleared to control radio power amp and receivers and how there are to be set for each radio mode, IDLE, TX or RX. They can be used to automatically configure any RF switch or external power amp etc. You will probably need these to configure the driver for your specific hardware

Constructor & Destructor Documentation

◆ RH_SX126x()

RH_SX126x::RH_SX126x	(	uint8_t	slaveSelectPin = `SS`,
		uint8_t	interruptPin = `2`,
		uint8_t	busyPin = `RH_INVALID_PIN`,
		uint8_t	resetPin = `RH_INVALID_PIN`,
		RHGenericSPI &	spi = `hardware_spi`,
		RadioPinConfig *	radioPinConfig = `nullptr`
	)

Constructor. You can have multiple instances, but each instance must have its own interrupt and slave select pin. After constructing, you must call init() to initialise the interface and the radio module. A maximum of 3 instances can co-exist on one processor, provided there are sufficient distinct interrupt lines, one for each instance.

Parameters

[in]	slaveSelectPin	the Arduino pin number of the output to use to select the RH_RF22 before accessing it. Defaults to the normal SS pin for your Arduino (D10 for Diecimila, Uno etc, D53 for Mega, D10 for Maple)
[in]	interruptPin	The interrupt Pin number that is connected to the RFM DIO0 interrupt line. Defaults to pin 2, as required by Anarduino MinWirelessLoRa module. Caution: You must specify an interrupt capable pin. On many Arduino boards, there are limitations as to which pins may be used as interrupts. On Leonardo pins 0, 1, 2 or 3. On Mega2560 pins 2, 3, 18, 19, 20, 21. On Due and Teensy, any digital pin. On Arduino Zero from arduino.cc, any digital pin other than 4. On Arduino M0 Pro from arduino.org, any digital pin other than 2. On other Arduinos pins 2 or 3. See http://arduino.cc/en/Reference/attachInterrupt for more details. On Chipkit Uno32, pins 38, 2, 7, 8, 35. On other boards, any digital pin may be used.
[in]	busyPin	Pin number of pin connected to the radio's busy pin. The radio sets the busy pin high while it is busy If this is not set to RH_INVALID_PIN (the default) then this module will wait for the busy pin to go low before initialting the next SPI transfer. It is strongly recommended that you use this.
[in]	resetPin	Pin number of the pin connected to the radio's reset pin. If this is not set to RH_INVALID_PIN (the default) then this module will assert the reset pin low for 2 ms during init() in order to reset the radio. It is strongly recommended that you use this
[in]	spi	Pointer to the SPI interface object to use.
[in]	radioPinConfig	pinter to a strucure that describes what pins are to be automatically set when changing the radio mode. This can be used to configure any external RF switches, RF amplifiers etc. Defaults to the standard Arduino hardware SPI interface

Member Function Documentation

◆ available()

bool RH_SX126x::available ( )

virtual

Tests whether a new message is available from the Driver. On most drivers, this will also put the Driver into RHModeRx mode until a message is actually received by the transport, when it will be returned to RHModeIdle. This can be called multiple times in a timeout loop

Returns: true if a new, complete, error-free uncollected message is available to be retreived by recv()

Implements RHGenericDriver.

References RHGenericDriver::_mode, RHGenericDriver::RHModeTx, and setModeRx().

Referenced by recv().

◆ handleInterrupt()

void RH_SX126x::handleInterrupt ( )

protected

This is a low level function to handle the interrupts for one instance of RH_SX126x. Called automatically by isr*() Should not need to be called by user code.

References RHGenericDriver::_cad, RHGenericDriver::_lastRssi, RHGenericDriver::_mode, RHGenericDriver::_rxBad, RHGenericDriver::_txGood, clearIrqStatus(), clearRxBuf(), getCommand(), getIrqStatus(), PacketTypeGFSK, PacketTypeLoRa, readBuffer(), RHGenericDriver::RHModeCad, RHGenericDriver::RHModeRx, RHGenericDriver::RHModeTx, setModeIdle(), and validateRxBuf().

◆ init()

bool RH_SX126x::init ( )

virtual

Initialise the Driver transport hardware and software. Leaves the radio in idle mode, with default configuration of: 915.0MHz, 13dBm, Bw = 125 kHz, Cr = 4/5, Sf = 128chips/symbol, CRC on

Returns: true if initialisation succeeded.

Reimplemented from RHGenericDriver.

Reimplemented in RH_STM32WLx.

References calibrate(), clearDeviceErrors(), getStatus(), RHSPIDriver::init(), LoRa_Bw125Cr45Sf128, setDIO2AsRfSwitchCtrl(), setDioIrqParams(), setFrequency(), setLoRaSyncWord(), setModeIdle(), setModemConfig(), setRegulatorMode(), setRxFallbackMode(), setTCXO(), setTxPower(), and setupInterruptHandler().

◆ isChannelActive()

bool RH_SX126x::isChannelActive ( )

virtual

Use the radio's Channel Activity Detect (CAD) function to detect channel activity. Sets the SX126X radio into CAD mode and waits until CAD detection is complete. To be used in a listen-before-talk mechanism (Collision Avoidance) with a reasonable time backoff algorithm. This is called automatically by waitCAD(). NOT YET WORKING.

Returns: true if channel is in use.

Reimplemented from RHGenericDriver.

References RHGenericDriver::_cad, RHGenericDriver::_mode, modeWillChange(), RHGenericDriver::RHModeCad, and setCad().

◆ lastSNR()

int RH_SX126x::lastSNR ( )

Returns the Signal-to-noise ratio (SNR) of the last received message, as measured by the receiver.

Returns: SNR of the last received message in dB

◆ maxMessageLength()

uint8_t RH_SX126x::maxMessageLength ( )

virtual

Returns the maximum message length available in this Driver.

Returns: The maximum legal message length

Implements RHGenericDriver.

◆ modeWillChange()

virtual bool RH_SX126x::modeWillChange ( RHMode )

inlineprotectedvirtual

Called by RH_SX126x when the radio mode is about to change to a new setting. Can be used by subclasses to implement antenna switching etc.

Parameters

[in] mode RHMode the new mode about to take effect

Returns: true if the subclasses changes successful

Referenced by isChannelActive(), setModeIdle(), setModeRx(), setModeTx(), and sleep().

◆ printRegisters()

bool RH_SX126x::printRegisters	(	uint16_t	address,
		uint8_t	count
	)

Prints the value of selected radio chip registers to the Serial device if RH_HAVE_SERIAL is defined for the current platform For debugging purposes only.

Parameters

[in]	address	The register adddress of the first register to print
[in]	count	The number of registers to print

Returns: true on success

References readRegisters().

◆ recv()

bool RH_SX126x::recv	(	uint8_t *	buf,
		uint8_t *	len
	)

virtual

Turns the receiver on if it not already on. If there is a valid message available, copy it to buf and return true else return false. If a message is copied, *len is set to the length (Caution, 0 length messages are permitted). You should be sure to call this function frequently enough to not miss any messages It is recommended that you call it in your main loop.

Parameters

[in]	buf	Location to copy the received message
[in,out]	len	Pointer to the number of octets available in buf. The number be reset to the actual number of octets copied.

Returns: true if a valid message was copied to buf

Implements RHGenericDriver.

References available(), and clearRxBuf().

◆ send()

bool RH_SX126x::send	(	const uint8_t *	data,
		uint8_t	len
	)

virtual

Waits until any previous transmit packet is finished being transmitted with waitPacketSent(). Then optionally waits for Channel Activity Detection (CAD) to show the channnel is clear (if the radio supports CAD) by calling waitCAD(). Then loads a message into the transmitter and starts the transmitter. Note that a message length of 0 is permitted.

Parameters

[in]	data	Array of data to be sent
[in]	len	Number of bytes of data to send specify the maximum time in ms to wait. If 0 (the default) do not wait for CAD before transmitting.

Returns: true if the message length was valid and it was correctly queued for transmit. Return false if CAD was requested and the CAD timeout timed out before clear channel was detected.

Implements RHGenericDriver.

References RHGenericDriver::_txHeaderFlags, RHGenericDriver::_txHeaderFrom, RHGenericDriver::_txHeaderId, RHGenericDriver::_txHeaderTo, getStatus(), setBufferBaseAddress(), setModeIdle(), setModeTx(), setPacketParametersLoRa(), setTx(), RHGenericDriver::waitCAD(), RHGenericDriver::waitPacketSent(), and writeBuffer().

◆ setDIO2AsRfSwitchCtrl()

bool RH_SX126x::setDIO2AsRfSwitchCtrl ( bool value )

protected

Sets whether DIO2 is to be used to automatically control an external radio RF switch. Normall you should use the pinConfig in the constructor or setRadioPinConfig() to automatically control any radio control pins

References sendCommand().

Referenced by init().

◆ setDIO3AsTcxoCtrl()

bool RH_SX126x::setDIO3AsTcxoCtrl	(	uint8_t	voltage,
		uint32_t	delay
	)

protected

Configures the radio to use an external temperature controlled crystal oscillator (TCXO) and the oven voltage to use. For low level internal use only

References sendCommand().

Referenced by setTCXO().

◆ setFrequency()

bool RH_SX126x::setFrequency	(	float	centre,
		bool	calibrate = `true`
	)

Sets the transmitter and receiver centre frequency.

Parameters

[in]	centre	Frequency in MHz. 137.0 to 1020.0. Caution: RFM95/96/97/98 comes in several different frequency ranges, and setting a frequency outside that range of your radio will probably not work
	[i]	calibrate set true if the radio modules are to be automatically recalibrated for this frequency

Returns: true if the selected frquency centre is within range, and the radio frequency is successfully set

References calibrate(), calibrateImage(), and sendCommand().

Referenced by init().

◆ setInvertIQ()

void RH_SX126x::setInvertIQ ( bool invertIQ )

protected

From SX1262_datasheet.pdf: "When exchanging LoRa® packets with inverted IQ polarity, some packet losses may be observed for longer packet". THis function enables the workaround described in that section

◆ setModeIdle()

void RH_SX126x::setModeIdle ( )

If current mode is Rx or Tx changes it to Idle. If the transmitter or receiver is running, disables them.

References RHGenericDriver::_mode, modeWillChange(), RHGenericDriver::RHModeIdle, and setStandby().

Referenced by handleInterrupt(), init(), and send().

◆ setModemConfig()

bool RH_SX126x::setModemConfig ( ModemConfigChoice index )

Select one of the predefined modem configurations. If you need a modem configuration not provided here, use setModemRegisters() with your own ModemConfig. Caution: the slowest protocols may require a radio module with TCXO temperature controlled oscillator for reliable operation.

Parameters

[in] index The configuration choice.

Returns: true if index is a valid choice.

References setModemRegisters().

Referenced by init().

◆ setModemRegisters()

bool RH_SX126x::setModemRegisters ( const ModemConfig * config )

Sets all the registers required to configure the data modem in the radio, including the bandwidth, spreading factor etc. You can use this to configure the modem with custom configurations if none of the canned configurations in ModemConfigChoice suit you.

Parameters

[in] config A ModemConfig structure containing values for the modem configuration registers.

Returns: true if modem was successfully reconfigured

References RH_SX126x::ModemConfig::p1, RH_SX126x::ModemConfig::p2, RH_SX126x::ModemConfig::p3, RH_SX126x::ModemConfig::p4, RH_SX126x::ModemConfig::p5, RH_SX126x::ModemConfig::p6, RH_SX126x::ModemConfig::p7, RH_SX126x::ModemConfig::p8, PacketTypeGFSK, PacketTypeLoRa, sendCommand(), and setModulationParameters().

Referenced by setModemConfig().

◆ setModeRx()

void RH_SX126x::setModeRx ( )

If current mode is Tx or Idle, changes it to Rx. Starts the receiver in the SX126X/96/97/98.

References RHGenericDriver::_mode, modeWillChange(), RHGenericDriver::RHModeRx, setPacketParametersLoRa(), and setRx().

Referenced by available().

◆ setModeTx()

void RH_SX126x::setModeTx ( )

If current mode is Rx or Idle, changes it to Rx. F Starts the transmitter in the SX126X/96/97/98.

References RHGenericDriver::_mode, modeWillChange(), RHGenericDriver::RHModeTx, and setTx().

Referenced by send().

◆ setPreambleLength()

void RH_SX126x::setPreambleLength ( uint16_t bytes )

Sets the length of the preamble in bytes. Caution: this should be set to the same value on all nodes in your network. Default is 8. Sets the message preamble length in RH_SX126x_REG_??_PREAMBLE_?SB

Parameters

[in] bytes Preamble length in bytes.

◆ setRadioPinsForMode()

bool RH_SX126x::setRadioPinsForMode ( RadioPinConfigMode mode )

protectedvirtual

Sets the pins configured in radioPinConfig as required for the desired mode. Called just before the radio is set to the new mode.

Returns: true if succcessful, false is there is no radioPinConfig configuration, or no entry for the requested mode

References findRadioPinConfigEntry(), RHGenericDriver::mode(), RH_SX126x::RadioPinConfig::pinNumber, and RH_SX126x::RadioPinConfigEntry::pinState.

Referenced by setRx(), setSleep(), setStandby(), setTx(), and setTxContinuous().

◆ setRegulatorMode()

bool RH_SX126x::setRegulatorMode ( uint8_t mode )

protected

Sets the chip regulator mode to either LDO or DC-DC SMPS. Set to DC-DC SMPS by default

References RHGenericDriver::mode(), and sendCommand().

Referenced by init().

◆ setTx()

bool RH_SX126x::setTx ( uint32_t timeout )

protected

Set the radio to transmit mode. Automatically configures the radio control pins to the configuration required for the most recently requested power in setTxPower (RadioPinConfigMode_TX_HIGH_POWER or RadioPinConfigMode_TX_LOW_POWER )

References PacketTypeLoRa, readRegister(), sendCommand(), setRadioPinsForMode(), and writeRegister().

Referenced by send(), and setModeTx().

◆ setTxContinuous()

bool RH_SX126x::setTxContinuous ( )

Set the radio into continuous transmission mode. A carrier wave will be transmitted on the configured centre frequency until available(), recv() or send() are called CAUTION: use this only for testing in controlled conditions with a dummy load. It may be illegal for you to transmit a continuous carrier wave to air.

References sendCommand(), and setRadioPinsForMode().

◆ setTxPower()

bool RH_SX126x::setTxPower ( int8_t power )

virtual

Sets the transmitter power output level Be a good neighbour and set the lowest power level you need. Caution: legal power limits may apply in certain countries. After init(), the power will be set to 13dBm.

Parameters

[in] power Transmitter power level in dBm. For SX1261, limits are -17 to +15 dBm For SX1262, limits are -9 to +22 dBm For STM32WLx with low power PA configured by radioPinConfig, same as SX1261. For STM32WLx with high power PA configured by radioPinConfig, same as SX1262.

Returns: true if successful. Returns false if radioPinConfig has not been properly configured for the requested power setting

References findRadioPinConfigEntry(), fixPAClamping(), setPaConfig(), and setTxParams().

Referenced by init().

◆ setupInterruptHandler()

bool RH_SX126x::setupInterruptHandler ( )

protectedvirtual

Do whatever is necesary to establish the interrupt handler. Subclasses may have different needs.

Reimplemented in RH_STM32WLx.

References RHSPIDriver::spiUsingInterrupt().

Referenced by init().

◆ sleep()

bool RH_SX126x::sleep ( )

virtual

Sets the radio into low-power sleep mode. If successful, the transport will stay in sleep mode until woken by changing mode it idle, transmit or receive (eg by calling send(), recv(), available() etc) Caution: there is a time penalty as the radio takes a finite time to wake from sleep mode.

Returns: true if sleep mode was successfully entered.

Reimplemented from RHGenericDriver.

References RHGenericDriver::_mode, modeWillChange(), RHGenericDriver::RHModeSleep, and setSleep().

◆ waitUntilNotBusy()

bool RH_SX126x::waitUntilNotBusy ( )

protectedvirtual

Wait until the busy pin (if speecified in the contructor) is no longer low On timeout, prints an error to eSerial and returns false. Else returns true.

Reimplemented in RH_STM32WLx.

Referenced by clearRxBuf(), getCommand(), getStatus(), readBuffer(), readRegisters(), sendCommand(), writeBuffer(), and writeRegisters().

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

RH_SX126x.h
RH_SX126x.cpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ ModemConfigChoice

◆ PacketType

◆ RadioPinConfigMode

Constructor & Destructor Documentation

◆ RH_SX126x()

Member Function Documentation

◆ available()

◆ handleInterrupt()

◆ init()

◆ isChannelActive()

◆ lastSNR()

◆ maxMessageLength()

◆ modeWillChange()

◆ printRegisters()

◆ recv()

◆ send()

◆ setDIO2AsRfSwitchCtrl()

◆ setDIO3AsTcxoCtrl()

◆ setFrequency()

◆ setInvertIQ()

◆ setModeIdle()

◆ setModemConfig()

◆ setModemRegisters()

◆ setModeRx()

◆ setModeTx()

◆ setPreambleLength()

◆ setRadioPinsForMode()

◆ setRegulatorMode()

◆ setTx()

◆ setTxContinuous()

◆ setTxPower()

◆ setupInterruptHandler()

◆ sleep()

◆ waitUntilNotBusy()