RadioLib Universal wireless communication library for Arduino

Module.h
1 #if !defined(_RADIOLIB_MODULE_H)
2 #define _RADIOLIB_MODULE_H
3
4 #include "TypeDef.h"
5 #include "Hal.h"
6
7 #if defined(RADIOLIB_BUILD_ARDUINO)
8 #include <SPI.h>
9 #endif
10
11 #if defined(STM32WLxx)
12 #include <SubGhz.h>
13 #endif
14
19 #define END_OF_MODE_TABLE { Module::MODE_END_OF_TABLE, {} }
20
21 // default timeout for SPI transfers
22 #define RADIOLIB_MODULE_SPI_TIMEOUT (1000)
23
30 #define RADIOLIB_MODULE_SPI_COMMAND_READ (0)
31
33 #define RADIOLIB_MODULE_SPI_COMMAND_WRITE (1)
34
36 #define RADIOLIB_MODULE_SPI_COMMAND_NOP (2)
37
39 #define RADIOLIB_MODULE_SPI_COMMAND_STATUS (3)
40
51 #define RADIOLIB_MODULE_SPI_WIDTH_ADDR (0)
52
54 #define RADIOLIB_MODULE_SPI_WIDTH_CMD (1)
55
57 #define RADIOLIB_MODULE_SPI_WIDTH_STATUS (2)
58
68 class Module {
69 public:
77 static const size_t RFSWITCH_MAX_PINS = 3;
78
84 struct RfSwitchMode_t {
86 uint8_t mode;
87
89 uint32_t values[RFSWITCH_MAX_PINS];
90 };
91
100 enum OpMode_t {
105 MODE_END_OF_TABLE = 0,
106
108 MODE_IDLE,
109
111 MODE_RX,
112
114 MODE_TX,
115 };
116
117 #if defined(RADIOLIB_BUILD_ARDUINO)
125 Module(uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio = RADIOLIB_NC);
126
136 Module(uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio, SPIClass& spi, SPISettings spiSettings = RADIOLIB_DEFAULT_SPI_SETTINGS);
137 #endif
138
147 Module(RadioLibHal *hal, uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio = RADIOLIB_NC);
148
153 Module(const Module& mod);
154
159 Module& operator=(const Module& mod);
160
161 // public member variables
163 RadioLibHal* hal = NULL;
164
166 typedef int16_t (*SPIparseStatusCb_t)(uint8_t in);
167
169 typedef int16_t (*SPIcheckStatusCb_t)(Module* mod);
170
171 enum BitWidth_t {
172 BITS_0 = 0,
173 BITS_8 = 8,
174 BITS_16 = 16,
175 BITS_32 = 32,
176 };
177
182 struct SPIConfig_t {
184 bool stream;
185
187 int16_t err;
188
190 uint16_t cmds[4];
191
193 BitWidth_t widths[3];
194
196 uint8_t statusPos;
197
199 SPIparseStatusCb_t parseStatusCb;
200
202 SPIcheckStatusCb_t checkStatusCb;
203 };
204
206 SPIConfig_t spiConfig = {
207 .stream = false,
208 .err = RADIOLIB_ERR_UNKNOWN,
209 .cmds = { 0x00, 0x80, 0x00, 0x00 },
210 .widths = { Module::BITS_8, Module::BITS_0, Module::BITS_8 },
211 .statusPos = 0,
212 .parseStatusCb = nullptr,
213 .checkStatusCb = nullptr,
214 };
215
216 #if RADIOLIB_INTERRUPT_TIMING
217
221 typedef void (*TimerSetupCb_t)(uint32_t len);
222
226 TimerSetupCb_t TimerSetupCb = nullptr;
227
231 volatile bool TimerFlag = false;
232
233 #endif
234
235 // basic methods
236
240 void init();
241
245 void term();
246
247 // SPI methods
248
256 int16_t SPIgetRegValue(uint32_t reg, uint8_t msb = 7, uint8_t lsb = 0);
257
268 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);
269
276 void SPIreadRegisterBurst(uint32_t reg, size_t numBytes, uint8_t* inBytes);
277
283 uint8_t SPIreadRegister(uint32_t reg);
284
291 void SPIwriteRegisterBurst(uint32_t reg, uint8_t* data, size_t numBytes);
292
298 void SPIwriteRegister(uint32_t reg, uint8_t data);
299
308 void SPItransfer(uint16_t cmd, uint32_t reg, uint8_t* dataOut, uint8_t* dataIn, size_t numBytes);
309
314 int16_t SPIcheckStream();
315
325 int16_t SPIreadStream(uint16_t cmd, uint8_t* data, size_t numBytes, bool waitForGpio = true, bool verify = true);
326
337 int16_t SPIreadStream(uint8_t* cmd, uint8_t cmdLen, uint8_t* data, size_t numBytes, bool waitForGpio = true, bool verify = true);
338
348 int16_t SPIwriteStream(uint16_t cmd, uint8_t* data, size_t numBytes, bool waitForGpio = true, bool verify = true);
349
360 int16_t SPIwriteStream(uint8_t* cmd, uint8_t cmdLen, uint8_t* data, size_t numBytes, bool waitForGpio = true, bool verify = true);
361
374 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);
375
376 // pin number access methods
377
382 uint32_t getCs() const { return(csPin); }
383
388 uint32_t getIrq() const { return(irqPin); }
389
394 uint32_t getRst() const { return(rstPin); }
395
400 uint32_t getGpio() const { return(gpioPin); }
401
418 void setRfSwitchPins(uint32_t rxEn, uint32_t txEn);
419
482 void setRfSwitchTable(const uint32_t (&pins)[RFSWITCH_MAX_PINS], const RfSwitchMode_t table[]);
483
491 const RfSwitchMode_t *findRfSwitchMode(uint8_t mode) const;
492
497 void setRfSwitchState(uint8_t mode);
498
506 void waitForMicroseconds(uint32_t start, uint32_t len);
507
514 static uint32_t reflect(uint32_t in, uint8_t bits);
515
516 #if RADIOLIB_DEBUG
525 static void hexdump(const char* level, uint8_t* data, size_t len, uint32_t offset = 0, uint8_t width = 1, bool be = false);
526
533 void regdump(const char* level, uint16_t start, size_t len);
534 #endif
535
536 #if RADIOLIB_DEBUG and defined(RADIOLIB_BUILD_ARDUINO)
537 static size_t serialPrintf(const char* format, ...);
538 #endif
539
540 #if !RADIOLIB_GODMODE
541 private:
542 #endif
543 uint32_t csPin = RADIOLIB_NC;
544 uint32_t irqPin = RADIOLIB_NC;
545 uint32_t rstPin = RADIOLIB_NC;
546 uint32_t gpioPin = RADIOLIB_NC;
547
548 // RF switch pins and table
549 uint32_t rfSwitchPins[RFSWITCH_MAX_PINS] = { RADIOLIB_NC, RADIOLIB_NC, RADIOLIB_NC };
550 const RfSwitchMode_t *rfSwitchTable = nullptr;
551
552 #if RADIOLIB_INTERRUPT_TIMING
553 uint32_t prevTimingLen = 0;
554 #endif
555 };
556
557 #endif
Module
Implements all common low-level methods to control the wireless module. Every module class contains o...
Definition: Module.h:68
Module::RFSWITCH_MAX_PINS
static const size_t RFSWITCH_MAX_PINS
The maximum number of pins supported by the RF switch code. Note: It is not recommended to use this c...
Definition: Module.h:77
Module::SPIcheckStatusCb_t
int16_t(* SPIcheckStatusCb_t)(Module *mod)
Callback for validation SPI status.
Definition: Module.h:169
Module::SPIwriteRegisterBurst
void SPIwriteRegisterBurst(uint32_t reg, uint8_t *data, size_t numBytes)
SPI burst write method.
Definition: Module.cpp:138
Module::SPIgetRegValue
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...
Definition: Module.cpp:55
Module::spiConfig
SPIConfig_t spiConfig
SPI configuration structure. The default configuration corresponds to register-access modules,...
Definition: Module.h:206
Module::hal
RadioLibHal * hal
Hardware abstraction layer to be used.
Definition: Module.h:163
Module::term
void term()
Terminate low-level module control.
Definition: Module.cpp:50
Module::waitForMicroseconds
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...
Definition: Module.cpp:435
Module::reflect
static uint32_t reflect(uint32_t in, uint8_t bits)
Function to reflect bits within a byte.
Definition: Module.cpp:453
Module::operator=
Module & operator=(const Module &mod)
Overload for assignment operator.
Definition: Module.cpp:33
Module::getGpio
uint32_t getGpio() const
Access method to get the pin number of second interrupt/GPIO.
Definition: Module.h:400
Module::findRfSwitchMode
const RfSwitchMode_t * findRfSwitchMode(uint8_t mode) const
Find a mode in the RfSwitchTable.
Definition: Module.cpp:573
Module::OpMode_t
OpMode_t
Constants to use in a mode table set be setRfSwitchTable. These constants work for most radios,...
Definition: Module.h:100
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::MODE_END_OF_TABLE
@ MODE_END_OF_TABLE
End of table marker, use END_OF_MODE_TABLE constant instead. Value is zero to ensure zero-initialized...
Definition: Module.h:105
Module::SPIcheckStream
int16_t SPIcheckStream()
Method to check the result of last SPI stream transfer.
Definition: Module.cpp:288
Module::SPIwriteRegister
void SPIwriteRegister(uint32_t reg, uint8_t data)
SPI basic write method. Use of this method is reserved for special cases, SPIsetRegValue should be us...
Definition: Module.cpp:154
Module::setRfSwitchPins
void setRfSwitchPins(uint32_t rxEn, uint32_t txEn)
Some modules contain external RF switch controlled by pins. This function gives RadioLib control over...
Definition: Module.cpp:550
Module::Module
Module(RadioLibHal *hal, uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio=RADIOLIB_NC)
Module constructor.
Definition: Module.cpp:25
Module::SPIparseStatusCb_t
int16_t(* SPIparseStatusCb_t)(uint8_t in)
Callback for parsing SPI status.
Definition: Module.h:166
Module::getCs
uint32_t getCs() const
Access method to get the pin number of SPI chip select.
Definition: Module.h:382
Module::SPItransfer
void SPItransfer(uint16_t cmd, uint32_t reg, uint8_t *dataOut, uint8_t *dataIn, size_t numBytes)
SPI single transfer method.
Definition: Module.cpp:170
Module::SPIreadRegister
uint8_t SPIreadRegister(uint32_t reg)
SPI basic read method. Use of this method is reserved for special cases, SPIgetRegValue should be use...
Definition: Module.cpp:120
Module::getIrq
uint32_t getIrq() const
Access method to get the pin number of interrupt/GPIO.
Definition: Module.h:388
Module::setRfSwitchTable
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...
Definition: Module.cpp:566
Module::SPItransferStream
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....
Definition: Module.cpp:311
Module::SPIreadRegisterBurst
void SPIreadRegisterBurst(uint32_t reg, size_t numBytes, uint8_t *inBytes)
SPI burst read method.
Definition: Module.cpp:104
Module::init
void init()
Initialize low-level module control.
Definition: Module.cpp:43
Module::getRst
uint32_t getRst() const
Access method to get the pin number of hardware reset pin.
Definition: Module.h:394
Module::SPIreadStream
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.
Definition: Module.cpp:232
Module::SPIsetRegValue
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.
Definition: Module.cpp:65
Module::SPIwriteStream
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.
Definition: Module.cpp:260
Module::setRfSwitchState
void setRfSwitchState(uint8_t mode)
Set RF switch state.
Definition: Module.cpp:583
RadioLibHal
Hardware abstraction library base interface.
Definition: Hal.h:13
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
Module::RfSwitchMode_t
Description of RF switch pin states for a single mode. See setRfSwitchTable for details.
Definition: Module.h:84
Module::RfSwitchMode_t::mode
uint8_t mode
RF switching mode, one of OpMode_t or a custom radio-defined value.
Definition: Module.h:86
Module::RfSwitchMode_t::values
uint32_t values[RFSWITCH_MAX_PINS]
Output pin values.
Definition: Module.h:89
Module::SPIConfig_t
SPI configuration structure.
Definition: Module.h:182
Module::SPIConfig_t::stream
bool stream
Whether the SPI module is stream-type (SX126x/8x) or registrer access type (SX127x,...
Definition: Module.h:184
Module::SPIConfig_t::cmds
uint16_t cmds[4]
SPI commands.
Definition: Module.h:190
Module::SPIConfig_t::statusPos
uint8_t statusPos
Byte position of status command in SPI stream.
Definition: Module.h:196
Module::SPIConfig_t::widths
BitWidth_t widths[3]
Bit widths of SPI addresses, commands and status bytes.
Definition: Module.h:193
Module::SPIConfig_t::parseStatusCb
SPIparseStatusCb_t parseStatusCb
Callback for parsing SPI status.
Definition: Module.h:199
Module::SPIConfig_t::checkStatusCb
SPIcheckStatusCb_t checkStatusCb
Callback for validation SPI status.
Definition: Module.h:202
Module::SPIConfig_t::err
int16_t err
Last recorded SPI error - only updated for modules that return status during SPI transfers.
Definition: Module.h:187