diff --git a/docs/ar_ibus.md b/docs/ar_ibus.md index 560b567..187f3cf 100644 --- a/docs/ar_ibus.md +++ b/docs/ar_ibus.md @@ -131,7 +131,7 @@ The general pattern for a device driver implementation that uses the SparkFun To The first step is to implement a core, platform independent version of the driver that communicates to the target device using the methods of a ```sfeTkIBus``` interface. By limiting use to the IBus interface, the core implementation can use any bus type or platform that implements the sfeTkIBus interface. ->[!IMPORTANT] +> [!IMPORTANT] > At this level, the driver is only using a ```sfeTkIBus``` interface, not any specific bus implementation. This driver has the following unique functionality: @@ -141,12 +141,12 @@ This driver has the following unique functionality: #### Simple Example of an Independent Driver Implementation ->[!NOTE] +> [!NOTE] > This code is **pseudo-code**, used to demonstrate the key concepts of the implementation pattern. This implementation would take the following form: -```c++ +```cpp class myDriverClass { @@ -205,7 +205,7 @@ The following is an example of an I2C class in Arduino based on the previous pla > [!NOTE] > If your device supports repeated starts, make sure to include ```_theI2CBus.setStop(false)``` in your begin function. Otherwise this can cause issues with your device. -```c++ +```cpp class myArduinoDriverI2C : public myDriverClass { @@ -246,7 +246,7 @@ The following is a SPI version of the driver implemented in Arduino. While simil > [!NOTE] > This class implements a ```isConnected()``` method that just calls the superclasses ```checkDeviceID()``` method to determine if the device is available on the bus. -```c++ +```cpp class myArduinoDriveSPI : public myDriverClass { diff --git a/library.properties b/library.properties index 3269264..5201f0f 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=SparkFun Toolkit -version=0.9.1 +version=0.9.2 author=SparkFun Electronics maintainer=SparkFun Electronics sentence=A utility library that other SparkFun libraries can take advantage of. diff --git a/src/sfeTk/sfeTkError.h b/src/sfeTk/sfeTkError.h index 8d79240..3f00841 100644 --- a/src/sfeTk/sfeTkError.h +++ b/src/sfeTk/sfeTkError.h @@ -32,7 +32,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * General Concept * A SparkFun Toolkit error system. The goal is to keep this simple. * - * This mimics a vareity of systems, using an int type for error codes, + * This mimics a variety of systems, using an int type for error codes, * where: * 0 = okay * -1 = general failure diff --git a/src/sfeTk/sfeTkIBus.h b/src/sfeTk/sfeTkIBus.h index 6b13758..c6ca7ab 100644 --- a/src/sfeTk/sfeTkIBus.h +++ b/src/sfeTk/sfeTkIBus.h @@ -87,14 +87,33 @@ class sfeTkIBus { public: /**-------------------------------------------------------------------------- - * @brief Write a single byte to the device* - * @param data Data to write.* + * @brief Send a single byte to the device* + * @param data Data to write. * * @retval sfeTkError_t - kSTkErrOk on successful execution. * */ virtual sfeTkError_t writeByte(uint8_t data) = 0; + /**-------------------------------------------------------------------------- + * @brief Send a word to the device. + * @param data Data to write. + * + * @retval sfeTkError_t - kSTkErrOk on successful execution. + * + */ + virtual sfeTkError_t writeWord(uint16_t data) = 0; + + /**-------------------------------------------------------------------------- + * @brief Send an array of data to the device. + * @param data Data to write. + * @param length - length of data. + * + * @retval sfeTkError_t - kSTkErrOk on successful execution. + * + */ + virtual sfeTkError_t writeRegion(const uint8_t *data, size_t length) = 0; + /**-------------------------------------------------------------------------- * @brief Write a single byte to the given register * @@ -120,9 +139,9 @@ class sfeTkIBus /**-------------------------------------------------------------------------- * @brief Writes a number of bytes starting at the given register's address. * - * @param devAddr The device's address/pin - * param devReg The device's register's address. - * @param data Data to write. + * @param devReg The device's register's address. + * @param data Data to write. + * @param length - length of data * * @retval sfeTkError_t kSTkErrOk on successful execution * @@ -132,9 +151,9 @@ class sfeTkIBus /**-------------------------------------------------------------------------- * @brief Writes a number of bytes starting at the given register's 16-bit address. * - * @param devAddr The device's 16-bit address/pin - * param devReg The device's register's address. - * @param data Data to write. + * @param devReg The device's register's address. + * @param data Data to write. + * @param length - length of data * * @retval sfeTkError_t kSTkErrOk on successful execution * @@ -145,7 +164,7 @@ class sfeTkIBus * @brief Read a single byte from the given register * * @param devReg The device's register's address. - * @param data Data to read. + * @param data Data to read. * * @retval sfeTkError_t - kSTkErrOk on successful execution. * @@ -165,8 +184,7 @@ class sfeTkIBus /**-------------------------------------------------------------------------- * @brief Reads a block of data from the given register. * - * @param devAddr The device's I2C address. - * @param devReg The device's register's address. + * @param reg The device's register's address. * @param data Data to write. * @param numBytes - length of data * @param[out] readBytes - number of bytes read diff --git a/src/sfeTkArdI2C.cpp b/src/sfeTkArdI2C.cpp index 076807b..ab7b20a 100644 --- a/src/sfeTkArdI2C.cpp +++ b/src/sfeTkArdI2C.cpp @@ -87,7 +87,7 @@ sfeTkError_t sfeTkArdI2C::ping() //--------------------------------------------------------------------------------- // writeByte() // -// Writes a single byte to the device. +// Writes a single byte to the device, without indexing to a register. // // Returns true on success, false on failure // @@ -102,6 +102,33 @@ sfeTkError_t sfeTkArdI2C::writeByte(uint8_t dataToWrite) return _i2cPort->endTransmission() == 0 ? kSTkErrOk : kSTkErrFail; } +//--------------------------------------------------------------------------------- +// writeWord() +// +// Writes a word to the device, without indexing to a register. +// +// Returns true on success, false on failure +// +sfeTkError_t sfeTkArdI2C::writeWord(uint16_t dataToWrite) +{ + if (!_i2cPort) + return kSTkErrBusNotInit; + + return writeRegion((uint8_t *)&dataToWrite, sizeof(uint16_t)); +} + +//--------------------------------------------------------------------------------- +// writeRegion() +// +// Writes a word to the device, without indexing to a register. +// +// Returns true on success, false on failure +// +sfeTkError_t sfeTkArdI2C::writeRegion(const uint8_t *data, size_t length) +{ + return writeRegisterRegionAddress(nullptr, 0, data, length) == 0 ? kSTkErrOk : kSTkErrFail; +} + //--------------------------------------------------------------------------------- // writeRegisterByte() // @@ -152,7 +179,10 @@ sfeTkError_t sfeTkArdI2C::writeRegisterRegionAddress(uint8_t *devReg, size_t reg return kSTkErrBusNotInit; _i2cPort->beginTransmission(address()); - _i2cPort->write(devReg, regLength); + + if(devReg != nullptr && regLength > 0) + _i2cPort->write(devReg, regLength); + _i2cPort->write(data, (int)length); return _i2cPort->endTransmission() ? kSTkErrFail : kSTkErrOk; @@ -183,7 +213,7 @@ sfeTkError_t sfeTkArdI2C::writeRegister16Region(uint16_t devReg, const uint8_t * return writeRegisterRegionAddress((uint8_t *)&devReg, 2, data, length); } -//--------------------------------------------------------------------------------- + /** * @brief Reads an array of bytes to a register on the target address. Supports any address size diff --git a/src/sfeTkArdI2C.h b/src/sfeTkArdI2C.h index 1a843f2..dc73432 100644 --- a/src/sfeTkArdI2C.h +++ b/src/sfeTkArdI2C.h @@ -84,6 +84,8 @@ class sfeTkArdI2C : public sfeTkII2C /** @brief - address version of the init method + + @param addr The address of the device */ sfeTkError_t init(uint8_t addr); @@ -91,6 +93,7 @@ class sfeTkArdI2C : public sfeTkII2C @brief Method sets up the required I2C settings. @param wirePort Port for I2C communication. + @param addr The address of the device @param bInit This flag tracks whether the bus has been initialized. @retval kSTkErrOk on successful execution. @@ -106,7 +109,7 @@ class sfeTkArdI2C : public sfeTkII2C sfeTkError_t ping(); /** - @brief Write a single byte to the device + @brief Sends a single byte to the device @note sfeTkIBus interface method @param data Data to write. @@ -115,6 +118,27 @@ class sfeTkArdI2C : public sfeTkII2C */ sfeTkError_t writeByte(uint8_t data); + /** + @brief Sends a word to the device. + @note sfeTkIBus interface method + + @param data Data to write. + + @retval returns kStkErrOk on success + */ + sfeTkError_t writeWord(uint16_t data); + + /** + @brief Sends a block of data to the device. + @note sfeTkIBus interface method + + @param data Data to write. + @param length - length of data + + @retval returns kStkErrOk on success + */ + sfeTkError_t writeRegion(const uint8_t *data, size_t length); + /** @brief Write a single byte to the given register @note sfeTkIBus interface method @@ -145,6 +169,7 @@ class sfeTkArdI2C : public sfeTkII2C @param devReg The device's register's address. @param data Data to write. + @param length - length of data @retval kStkErrOk on success */ @@ -153,9 +178,9 @@ class sfeTkArdI2C : public sfeTkII2C /** @brief Writes a number of bytes starting at the given register's 16-bit address. - @param devAddr The device's 16-bit address/pin - param devReg The device's register's address. + @param devReg The device's register's address - 16 bit. @param data Data to write. + @param length - length of data @retval sfeTkError_t kSTkErrOk on successful execution @@ -168,7 +193,7 @@ class sfeTkArdI2C : public sfeTkII2C @note sfeTkIBus interface method @param devReg The device's register's address. - @param data Data to read. + @param[out] data Data to read. @retval kStkErrOk on success */ @@ -180,7 +205,7 @@ class sfeTkArdI2C : public sfeTkII2C @note sfeTkIBus interface method @param devReg The device's register's address. - @param data Data to read. + @param[out] data Data to read. @retval kSTkErrOk on success */ @@ -193,8 +218,8 @@ class sfeTkArdI2C : public sfeTkII2C @note This method is virtual to allow it to be overridden to support a device that requires a unique impl @param devReg The device's register's address. - @param data Data being read. - @param numBytes Number of bytes to read. + @param[out] data Data buffer to read into + @param numBytes Number of bytes to read/length of data buffer @param[out] readBytes - Number of bytes read @@ -206,8 +231,8 @@ class sfeTkArdI2C : public sfeTkII2C @brief Reads a block of data from the given 16-bit register address. @param reg The device's 16 bit register's address. - @param data Data to write. - @param numBytes - length of data + @param data Data buffer to read into + @param numBytes - Number of bytes to read/length of data buffer @param[out] readBytes - number of bytes read @retval int returns kSTkErrOk on success, or kSTkErrFail code diff --git a/src/sfeTkArdSPI.cpp b/src/sfeTkArdSPI.cpp index 15fcd60..276e3eb 100644 --- a/src/sfeTkArdSPI.cpp +++ b/src/sfeTkArdSPI.cpp @@ -82,7 +82,7 @@ sfeTkError_t sfeTkArdSPI::init(bool bInit) } //--------------------------------------------------------------------------------- -// writeRegisterByte() +// writeByte() // // Writes a single byte to the device. // @@ -108,6 +108,46 @@ sfeTkError_t sfeTkArdSPI::writeByte(uint8_t dataToWrite) return kSTkErrOk; } +//--------------------------------------------------------------------------------- +// writeWord() +// +// Writes a word to the device without indexing to a register. +// +// Returns kSTkErrOk on success +// +sfeTkError_t sfeTkArdSPI::writeWord(uint16_t dataToWrite) +{ + return writeRegion((uint8_t *)&dataToWrite, sizeof(uint8_t)) > 0; +} + + +//--------------------------------------------------------------------------------- +// writeRegion() +// +// Writes an array of data to the device without indexing to a register. +// +// Returns kSTkErrOk on success +// +sfeTkError_t sfeTkArdSPI::writeRegion(const uint8_t *dataToWrite, size_t length) +{ + + if (!_spiPort) + return kSTkErrBusNotInit; + + _spiPort->beginTransaction(_sfeSPISettings); + // Signal communication start + digitalWrite(cs(), LOW); + + for (size_t i = 0; i < length; i++) + _spiPort->transfer(*dataToWrite++); + + // End communication + digitalWrite(cs(), HIGH); + _spiPort->endTransaction(); + + return kSTkErrOk; +} + //--------------------------------------------------------------------------------- // writeRegisterByte() // @@ -164,6 +204,7 @@ sfeTkError_t sfeTkArdSPI::writeRegisterRegion(uint8_t devReg, const uint8_t *dat // Signal communication start digitalWrite(cs(), LOW); + _spiPort->transfer(devReg); for (size_t i = 0; i < length; i++) @@ -278,4 +319,4 @@ sfeTkError_t sfeTkArdSPI::readRegister16Region(uint16_t devReg, uint8_t *data, s readBytes = numBytes; return kSTkErrOk; -} \ No newline at end of file +} diff --git a/src/sfeTkArdSPI.h b/src/sfeTkArdSPI.h index 3e48178..113853e 100644 --- a/src/sfeTkArdSPI.h +++ b/src/sfeTkArdSPI.h @@ -54,8 +54,7 @@ class sfeTkArdSPI : public sfeTkISPI /** @brief Copy constructor for Arduino SPI bus object of the toolkit - @param spiPort Port for SPI communication. - @param busSPISettings Settings for speed, endianness, and spi mode of the SPI bus. + @param rhs source of the copy operation */ sfeTkArdSPI(sfeTkArdSPI const &rhs) : sfeTkISPI(), _spiPort{rhs._spiPort}, _sfeSPISettings{rhs._sfeSPISettings} { @@ -64,7 +63,7 @@ class sfeTkArdSPI : public sfeTkISPI /** @brief Assignment copy operator for Arduino SPI bus object of the toolkit - @param rsh The right hand side of the assignment. + @param rhs The right hand side of the assignment. @return sfeTkArdSPI& - The left hand side of the assignment. */ sfeTkArdSPI &operator=(const sfeTkArdSPI &rhs) @@ -78,12 +77,21 @@ class sfeTkArdSPI : public sfeTkISPI @brief Method sets up the required SPI settings. @note This function provides a default SPI Port. - @param bInit This flag tracks whether the bus has been initialized. + @param bInit Init the device - default is false. @retval sfeTkError_t - kSTkErrOk on success */ sfeTkError_t init(bool bInit = false); + /** + @brief Method sets up the required SPI settings. + @note This function provides a default SPI Port. + + @param csPin The CS Pin for the device + @param bInit Init the device - default is false. + + @retval sfeTkError_t - kSTkErrOk on success + */ sfeTkError_t init(uint8_t csPin, bool bInit = false); /** @@ -91,6 +99,7 @@ class sfeTkArdSPI : public sfeTkISPI @param spiPort Port for SPI communication. @param busSPISettings Settings for speed, endianness, and spi mode of the SPI bus. + @param csPin The CS Pin for the device @param bInit This flag tracks whether the bus has been initialized. @retval sfeTkError_t - kSTkErrOk on success @@ -106,6 +115,25 @@ class sfeTkArdSPI : public sfeTkISPI */ sfeTkError_t writeByte(uint8_t data); + /** + @brief Write a word to the device without indexing to a register. + + @param data Data to write. + + @retval sfeTkError_t - kSTkErrOk on success + */ + sfeTkError_t writeWord(uint16_t data); + + /** + @brief Write an array of data to the device without indexing to a register. + + @param data Data to write + @param length Length of Data + + @retval sfeTkError_t - kSTkErrOk on success + */ + sfeTkError_t writeRegion(const uint8_t *data, size_t length); + /** @brief Write a single byte to the given register @@ -132,6 +160,7 @@ class sfeTkArdSPI : public sfeTkISPI @param devReg The device's register's address. @param data Data to write. + @param length - length of data @retval sfeTkError_t - kSTkErrOk on success */ @@ -143,6 +172,7 @@ class sfeTkArdSPI : public sfeTkISPI @param devReg The device's register's address. @param data Data to write. + @param length - length of data @retval sfeTkError_t - kSTkErrOk on success */ @@ -152,7 +182,7 @@ class sfeTkArdSPI : public sfeTkISPI @brief Read a single byte from the given register @param devReg The device's register's address. - @param data Data to read. + @param[out] data Data to read. @retval sfeTkError_t - kSTkErrOk on success */ @@ -162,7 +192,7 @@ class sfeTkArdSPI : public sfeTkISPI @brief read a single word to the given register @param devReg The device's register's address. - @param data Data to write. + @param[out] data Data to write. @retval sfeTkError_t - true on success */ @@ -172,9 +202,9 @@ class sfeTkArdSPI : public sfeTkISPI @brief Reads a block of data from the given register. @note This method is virtual to allow it to be overridden to support a device that requires a unique impl - @param devReg The device's register's address. - @param data Data to write. - @param numBytes - length of data + @param reg The device's register's address. + @param[out] data Data buffer to read into + @param numBytes - length of data/size of data buffer @param[out] readBytes - Number of bytes read @retval sfeTkError_t - true on success @@ -185,9 +215,9 @@ class sfeTkArdSPI : public sfeTkISPI @brief Reads a block of data from the given register. @note This method is virtual to allow it to be overridden to support a device that requires a unique impl - @param devReg The device's register's 16 bit address. - @param data Data to write. - @param numBytes - length of data + @param reg The device's register's 16 bit address. + @param[out] data Data buffer to read into + @param numBytes - Length of data to read/size of data buffer @param[out] readBytes - Number of bytes read @retval sfeTkError_t - true on success