Merge pull request #38 from sparkfun/main

Bring develop up to main

Author: gigapod

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
 {

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.

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

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

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

src/sfeTkArdI2C.h

@@ -84,13 +84,16 @@ class sfeTkArdI2C : public sfeTkII2C
 
     /**
         @brief - address version of the init method
+
+        @param addr The address of the device
     */
     sfeTkError_t init(uint8_t addr);
 
     /**
         @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

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;
-}
+}