From 9749083573db2e1d0a5ee5cf8ad34737ee47c376 Mon Sep 17 00:00:00 2001 From: jgromes Date: Sat, 22 Apr 2023 18:50:12 +0200 Subject: [PATCH] [MOD] Use compact Doxygen and stop using reserved format --- src/Module.cpp | 50 +++++++++---------- src/Module.h | 131 ++++++++----------------------------------------- 2 files changed, 45 insertions(+), 136 deletions(-) diff --git a/src/Module.cpp b/src/Module.cpp index 21f37a97..db3b56f2 100644 --- a/src/Module.cpp +++ b/src/Module.cpp @@ -7,16 +7,16 @@ #if defined(RADIOLIB_BUILD_ARDUINO) #include "ArduinoHal.h" -Module::Module(uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio) : _cs(cs), _irq(irq), _rst(rst), _gpio(gpio) { +Module::Module(uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio) : csPin(cs), irqPin(irq), rstPin(rst), gpioPin(gpio) { this->hal = new ArduinoHal(); } -Module::Module(uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio, SPIClass& spi, SPISettings spiSettings) : _cs(cs), _irq(irq), _rst(rst), _gpio(gpio) { +Module::Module(uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio, SPIClass& spi, SPISettings spiSettings) : csPin(cs), irqPin(irq), rstPin(rst), gpioPin(gpio) { this->hal = new ArduinoHal(spi, spiSettings); } #endif -Module::Module(RadioLibHal *hal, uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio) : _cs(cs), _irq(irq), _rst(rst), _gpio(gpio) { +Module::Module(RadioLibHal *hal, uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio) : csPin(cs), irqPin(irq), rstPin(rst), gpioPin(gpio) { this->hal = hal; } @@ -27,18 +27,17 @@ Module::Module(const Module& mod) { Module& Module::operator=(const Module& mod) { this->SPIreadCommand = mod.SPIreadCommand; this->SPIwriteCommand = mod.SPIwriteCommand; - this->_cs = mod._cs; - this->_irq = mod._irq; - this->_rst = mod._rst; - this->_gpio = mod._gpio; - + this->csPin = mod.csPin; + this->irqPin = mod.irqPin; + this->rstPin = mod.rstPin; + this->gpioPin = mod.gpioPin; return(*this); } void Module::init() { this->hal->init(); - this->hal->pinMode(_cs, this->hal->GpioModeOutput); - this->hal->digitalWrite(_cs, this->hal->GpioLevelHigh); + this->hal->pinMode(csPin, this->hal->GpioModeOutput); + this->hal->digitalWrite(csPin, this->hal->GpioLevelHigh); } void Module::term() { @@ -138,7 +137,7 @@ void Module::SPItransfer(uint8_t cmd, uint16_t reg, uint8_t* dataOut, uint8_t* d this->hal->spiBeginTransaction(); // pull CS low - this->hal->digitalWrite(this->_cs, this->hal->GpioLevelLow); + this->hal->digitalWrite(this->csPin, this->hal->GpioLevelLow); // send SPI register address with access command if(this->SPIaddrWidth <= 8) { @@ -176,7 +175,7 @@ void Module::SPItransfer(uint8_t cmd, uint16_t reg, uint8_t* dataOut, uint8_t* d RADIOLIB_VERBOSE_PRINTLN(); // release CS - this->hal->digitalWrite(this->_cs, this->hal->GpioLevelHigh); + this->hal->digitalWrite(this->csPin, this->hal->GpioLevelHigh); // end SPI transaction this->hal->spiEndTransaction(); @@ -242,16 +241,16 @@ int16_t Module::SPItransferStream(uint8_t* cmd, uint8_t cmdLen, bool write, uint // ensure GPIO is low uint32_t start = this->hal->millis(); - while(this->hal->digitalRead(this->_gpio)) { + while(this->hal->digitalRead(this->gpioPin)) { this->hal->yield(); if(this->hal->millis() - start >= timeout) { - this->hal->digitalWrite(this->_cs, this->hal->GpioLevelLow); + this->hal->digitalWrite(this->csPin, this->hal->GpioLevelLow); return(RADIOLIB_ERR_SPI_CMD_TIMEOUT); } } // pull NSS low - this->hal->digitalWrite(this->_cs, this->hal->GpioLevelLow); + this->hal->digitalWrite(this->csPin, this->hal->GpioLevelLow); // start transfer this->hal->spiBeginTransaction(); @@ -303,13 +302,13 @@ int16_t Module::SPItransferStream(uint8_t* cmd, uint8_t cmdLen, bool write, uint // stop transfer this->hal->spiEndTransaction(); - this->hal->digitalWrite(this->_cs, this->hal->GpioLevelHigh); + this->hal->digitalWrite(this->csPin, this->hal->GpioLevelHigh); // wait for GPIO to go high and then low if(waitForGpio) { this->hal->delayMicroseconds(1); uint32_t start = this->hal->millis(); - while(this->hal->digitalRead(this->_gpio)) { + while(this->hal->digitalRead(this->gpioPin)) { this->hal->yield(); if(this->hal->millis() - start >= timeout) { state = RADIOLIB_ERR_SPI_CMD_TIMEOUT; @@ -352,7 +351,7 @@ int16_t Module::SPItransferStream(uint8_t* cmd, uint8_t cmdLen, bool write, uint void Module::waitForMicroseconds(uint32_t start, uint32_t len) { #if defined(RADIOLIB_INTERRUPT_TIMING) (void)start; - if((this->TimerSetupCb != nullptr) && (len != this->_prevTimingLen)) { + if((this->TimerSetupCb != nullptr) && (len != this->prevTimingLen)) { _prevTimingLen = len; this->TimerSetupCb(len); } @@ -471,25 +470,26 @@ void Module::setRfSwitchPins(uint32_t rxEn, uint32_t txEn) { const uint32_t pins[] = { rxEn, txEn, RADIOLIB_NC, }; + // This must be static, since setRfSwitchTable stores a reference. static const RfSwitchMode_t table[] = { - {MODE_IDLE, {this->hal->GpioLevelLow, this->hal->GpioLevelLow}}, - {MODE_RX, {this->hal->GpioLevelHigh, this->hal->GpioLevelLow}}, - {MODE_TX, {this->hal->GpioLevelLow, this->hal->GpioLevelHigh}}, + { MODE_IDLE, {this->hal->GpioLevelLow, this->hal->GpioLevelLow} }, + { MODE_RX, {this->hal->GpioLevelHigh, this->hal->GpioLevelLow} }, + { MODE_TX, {this->hal->GpioLevelLow, this->hal->GpioLevelHigh} }, END_OF_MODE_TABLE, }; setRfSwitchTable(pins, table); } void Module::setRfSwitchTable(const uint32_t (&pins)[3], const RfSwitchMode_t table[]) { - memcpy(_rfSwitchPins, pins, sizeof(_rfSwitchPins)); - _rfSwitchTable = table; + memcpy(this->rfSwitchPins, pins, sizeof(this->rfSwitchPins)); + this->rfSwitchTable = table; for(size_t i = 0; i < RFSWITCH_MAX_PINS; i++) this->hal->pinMode(pins[i], this->hal->GpioModeOutput); } const Module::RfSwitchMode_t *Module::findRfSwitchMode(uint8_t mode) const { - const RfSwitchMode_t *row = _rfSwitchTable; + const RfSwitchMode_t *row = this->rfSwitchTable; while (row && row->mode != MODE_END_OF_TABLE) { if (row->mode == mode) return row; @@ -508,7 +508,7 @@ void Module::setRfSwitchState(uint8_t mode) { // set pins const uint32_t *value = &row->values[0]; for(size_t i = 0; i < RFSWITCH_MAX_PINS; i++) { - uint32_t pin = _rfSwitchPins[i]; + uint32_t pin = this->rfSwitchPins[i]; if (pin != RADIOLIB_NC) this->hal->digitalWrite(pin, *value); ++value; diff --git a/src/Module.h b/src/Module.h index dccc038d..03163d15 100644 --- a/src/Module.h +++ b/src/Module.h @@ -22,7 +22,6 @@ /*! \class Module - \brief Implements all common low-level methods to control the wireless module. Every module class contains one private instance of this class. */ @@ -72,30 +71,20 @@ class Module { #if defined(RADIOLIB_BUILD_ARDUINO) /*! \brief Arduino Module constructor. Will use the default SPI interface and automatically initialize it. - \param cs Arduino pin to be used as chip select. - \param irq Arduino pin to be used as interrupt/GPIO. - \param rst Arduino pin to be used as hardware reset for the module. - \param gpio Arduino pin to be used as additional interrupt/GPIO. */ Module(uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio = RADIOLIB_NC); /*! \brief Arduino Module constructor. Will not attempt SPI interface initialization. - \param cs Arduino pin to be used as chip select. - \param irq Arduino pin to be used as interrupt/GPIO. - \param rst Arduino pin to be used as hardware reset for the module. - \param gpio Arduino pin to be used as additional interrupt/GPIO. - \param spi SPI interface to be used, can also use software SPI implementations. - \param spiSettings SPI interface settings. */ Module(uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio, SPIClass& spi, SPISettings spiSettings = RADIOLIB_DEFAULT_SPI_SETTINGS); @@ -103,35 +92,30 @@ class Module { /*! \brief Module constructor. - \param hal A Hardware abstraction layer instance. An ArduinoHal instance for example. - \param cs Pin to be used as chip select. - \param irq Pin to be used as interrupt/GPIO. - \param rst Pin to be used as hardware reset for the module. - \param gpio Pin to be used as additional interrupt/GPIO. */ Module(RadioLibHal *hal, uint32_t cs, uint32_t irq, uint32_t rst, uint32_t gpio = RADIOLIB_NC); /*! \brief Copy constructor. - \param mod Module instance to copy. */ Module(const Module& mod); /*! \brief Overload for assignment operator. - \param frame rvalue Module. */ Module& operator=(const Module& mod); // public member variables - + /*! + \brief Hardware abstraction layer to be used. + */ RadioLibHal* hal = NULL; /*! @@ -216,189 +200,127 @@ class Module { /*! \brief SPI read method that automatically masks unused bits. This method is the preferred SPI read mechanism. - \param reg Address of SPI register to read. - \param msb Most significant bit of the register variable. Bits above this one will be masked out. - \param lsb Least significant bit of the register variable. Bits below this one will be masked out. - \returns Masked register value or status code. */ int16_t SPIgetRegValue(uint16_t reg, uint8_t msb = 7, uint8_t lsb = 0); /*! \brief Overwrite-safe SPI write method with verification. This method is the preferred SPI write mechanism. - \param reg Address of SPI register to write. - \param value Single byte value that will be written to the SPI register. - \param msb Most significant bit of the register variable. Bits above this one will not be affected by the write operation. - \param lsb Least significant bit of the register variable. Bits below this one will not be affected by the write operation. - \param checkInterval Number of milliseconds between register writing and verification reading. Some registers need up to 10ms to process the change. - \param checkMask Mask of bits to check, only bits set to 1 will be verified. - \returns \ref status_codes */ 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); /*! \brief SPI burst read method. - \param reg Address of SPI register to read. - \param numBytes Number of bytes that will be read. - \param inBytes Pointer to array that will hold the read data. */ void SPIreadRegisterBurst(uint16_t reg, size_t numBytes, uint8_t* inBytes); /*! \brief SPI basic read method. Use of this method is reserved for special cases, SPIgetRegValue should be used instead. - \param reg Address of SPI register to read. - \returns Value that was read from register. */ uint8_t SPIreadRegister(uint16_t reg); /*! \brief SPI burst write method. - \param reg Address of SPI register to write. - \param data Pointer to array that holds the data that will be written. - \param numBytes Number of bytes that will be written. */ void SPIwriteRegisterBurst(uint16_t reg, uint8_t* data, size_t numBytes); /*! \brief SPI basic write method. Use of this method is reserved for special cases, SPIsetRegValue should be used instead. - \param reg Address of SPI register to write. - \param data Value that will be written to the register. */ void SPIwriteRegister(uint16_t reg, uint8_t data); /*! \brief SPI single transfer method. - \param cmd SPI access command (read/write/burst/...). - \param reg Address of SPI register to transfer to/from. - \param dataOut Data that will be transfered from master to slave. - \param dataIn Data that was transfered from slave to master. - \param numBytes Number of bytes to transfer. */ void SPItransfer(uint8_t cmd, uint16_t reg, uint8_t* dataOut, uint8_t* dataIn, size_t numBytes); /*! \brief Method to check the result of last SPI stream transfer. - \returns \ref status_codes */ int16_t SPIcheckStream(); /*! \brief Method to perform a read transaction with SPI stream. - \param cmd SPI operation command. - \param data Data that will be transferred from slave to master. - \param numBytes Number of bytes to transfer. - \param waitForGpio Whether to wait for some GPIO at the end of transfer (e.g. BUSY line on SX126x/SX128x). - \param verify Whether to verify the result of the transaction after it is finished. - \returns \ref status_codes */ int16_t SPIreadStream(uint8_t cmd, uint8_t* data, size_t numBytes, bool waitForGpio = true, bool verify = true); /*! \brief Method to perform a read transaction with SPI stream. - \param cmd SPI operation command. - \param cmdLen SPI command length in bytes. - \param data Data that will be transferred from slave to master. - \param numBytes Number of bytes to transfer. - \param waitForGpio Whether to wait for some GPIO at the end of transfer (e.g. BUSY line on SX126x/SX128x). - \param verify Whether to verify the result of the transaction after it is finished. - \returns \ref status_codes */ int16_t SPIreadStream(uint8_t* cmd, uint8_t cmdLen, uint8_t* data, size_t numBytes, bool waitForGpio = true, bool verify = true); /*! \brief Method to perform a write transaction with SPI stream. - \param cmd SPI operation command. - \param data Data that will be transferred from master to slave. - \param numBytes Number of bytes to transfer. - \param waitForGpio Whether to wait for some GPIO at the end of transfer (e.g. BUSY line on SX126x/SX128x). - \param verify Whether to verify the result of the transaction after it is finished. - \returns \ref status_codes */ int16_t SPIwriteStream(uint8_t cmd, uint8_t* data, size_t numBytes, bool waitForGpio = true, bool verify = true); /*! \brief Method to perform a write transaction with SPI stream. - \param cmd SPI operation command. - \param cmdLen SPI command length in bytes. - \param data Data that will be transferred from master to slave. - \param numBytes Number of bytes to transfer. - \param waitForGpio Whether to wait for some GPIO at the end of transfer (e.g. BUSY line on SX126x/SX128x). - \param verify Whether to verify the result of the transaction after it is finished. - \returns \ref status_codes */ int16_t SPIwriteStream(uint8_t* cmd, uint8_t cmdLen, uint8_t* data, size_t numBytes, bool waitForGpio = true, bool verify = true); /*! \brief SPI single transfer method for modules with stream-type SPI interface (SX126x, SX128x etc.). - \param cmd SPI operation command. - \param cmdLen SPI command length in bytes. - \param write Set to true for write commands, false for read commands. - \param dataOut Data that will be transfered from master to slave. - \param dataIn Data that was transfered from slave to master. - \param numBytes Number of bytes to transfer. - \param waitForGpio Whether to wait for some GPIO at the end of transfer (e.g. BUSY line on SX126x/SX128x). - \param timeout GPIO wait period timeout in milliseconds. - \returns \ref status_codes */ 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); @@ -407,31 +329,27 @@ class Module { /*! \brief Access method to get the pin number of SPI chip select. - \returns Pin number of SPI chip select configured in the constructor. */ - uint32_t getCs() const { return(_cs); } + uint32_t getCs() const { return(csPin); } /*! \brief Access method to get the pin number of interrupt/GPIO. - \returns Pin number of interrupt/GPIO configured in the constructor. */ - uint32_t getIrq() const { return(_irq); } + uint32_t getIrq() const { return(irqPin); } /*! \brief Access method to get the pin number of hardware reset pin. - \returns Pin number of hardware reset pin configured in the constructor. */ - uint32_t getRst() const { return(_rst); } + uint32_t getRst() const { return(rstPin); } /*! \brief Access method to get the pin number of second interrupt/GPIO. - \returns Pin number of second interrupt/GPIO configured in the constructor. */ - uint32_t getGpio() const { return(_gpio); } + uint32_t getGpio() const { return(gpioPin); } /*! \brief Some modules contain external RF switch controlled by pins. @@ -516,14 +434,12 @@ class Module { void setRfSwitchTable(const uint32_t (&pins)[RFSWITCH_MAX_PINS], const RfSwitchMode_t table[]); /*! - * \brief Find a mode in the RfSwitchTable. - * - * \param 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. - */ + \brief Find a mode in the RfSwitchTable. + \param 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. + */ const RfSwitchMode_t *findRfSwitchMode(uint8_t mode) const; /*! @@ -537,7 +453,6 @@ class Module { Note that in interrupt timing mode, it is up to the user to set up the timing interrupt! \param start Waiting start timestamp, in microseconds. - \param len Waiting duration, in microseconds; */ void waitForMicroseconds(uint32_t start, uint32_t len); @@ -554,22 +469,16 @@ class Module { /*! \brief Function to dump data as hex into the debug port. - \param data Data to dump. - \param len Number of bytes to dump. - \param width Word width (1 for uint8_t, 2 for uint16_t, 4 for uint32_t). - \param be Print multi-byte data as big endian. Defaults to false. */ static void hexdump(uint8_t* data, size_t len, uint32_t offset = 0, uint8_t width = 1, bool be = false); /*! \brief Function to dump device registers as hex into the debug port. - \param start First address to dump. - \param len Number of bytes to dump. */ void regdump(uint16_t start, size_t len); @@ -581,17 +490,17 @@ class Module { #if !defined(RADIOLIB_GODMODE) private: #endif - uint32_t _cs = RADIOLIB_NC; - uint32_t _irq = RADIOLIB_NC; - uint32_t _rst = RADIOLIB_NC; - uint32_t _gpio = RADIOLIB_NC; + uint32_t csPin = RADIOLIB_NC; + uint32_t irqPin = RADIOLIB_NC; + uint32_t rstPin = RADIOLIB_NC; + uint32_t gpioPin = RADIOLIB_NC; // RF switch pins and table - uint32_t _rfSwitchPins[RFSWITCH_MAX_PINS] = { RADIOLIB_NC, RADIOLIB_NC, RADIOLIB_NC }; - const RfSwitchMode_t *_rfSwitchTable = nullptr; + uint32_t rfSwitchPins[RFSWITCH_MAX_PINS] = { RADIOLIB_NC, RADIOLIB_NC, RADIOLIB_NC }; + const RfSwitchMode_t *rfSwitchTable = nullptr; #if defined(RADIOLIB_INTERRUPT_TIMING) - uint32_t _prevTimingLen = 0; + uint32_t prevTimingLen = 0; #endif };