Merge pull request #39 from sparkfun/feature/16-bit-data-support

Merge in latest changes into development. 

From the above discussion - only missing the naming pattern change

Author: gigapod

README.md

@@ -1,3 +1,4 @@
+![SparkFun ToolKit](docs/images/gh-banner-2025-banner-toolkit.png "SparkFun Toolkit")
 # SparkFun Toolkit Arduino Library
 
 ![Toolkit Tests Builds](https://github.com/sparkfun/SparkFun_Toolkit/actions/workflows/compile-sketch.yml/badge.svg)

docs/images/gh-banner-2025-banner-toolkit.png

@@ -31,7 +31,6 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 // Arduino Libraries.
 
 // Just include the toolkit headers
-
-#include <sfeTk/sfeToolkit.h>
 #include "sfeTkArdI2C.h"
-#include "sfeTkArdSPI.h"
+#include "sfeTkArdSPI.h"
+#include "sfeTkArduino.h"

src/SparkFun_Toolkit.h

@@ -27,7 +27,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #pragma once
 
-#include "sfeTkError.h"
+#include "sfeToolkit.h"
 #include <stddef.h>
 
 /**
@@ -52,7 +52,7 @@ const sfeTkError_t kSTkErrBusTimeout = kSTkErrFail * (kSTkErrBaseBus + 2);
 const sfeTkError_t kSTkErrBusNoResponse = kSTkErrFail * (kSTkErrBaseBus + 3);
 
 /**
- * @brief Returned when the data to be sent is too long or recieved is too short.
+ * @brief Returned when the data to be sent is too long or received is too short.
  */
 const sfeTkError_t kSTkErrBusDataTooLong = kSTkErrFail * (kSTkErrBaseBus + 4);
 
@@ -86,6 +86,12 @@ const sfeTkError_t kSTkErrBusNotEnabled = kSTkErrBaseBus + 8;
 class sfeTkIBus
 {
   public:
+    /**
+     * @brief Constructor
+     */
+    sfeTkIBus() {
+        _byteOrder = sftk_system_byteorder();
+    }
     /**--------------------------------------------------------------------------
      *  @brief Send a single byte to the device*
      *  @param data Data to write.
@@ -96,7 +102,7 @@ class sfeTkIBus
     virtual sfeTkError_t writeByte(uint8_t data) = 0;
 
     /**--------------------------------------------------------------------------
-     *  @brief Send a word to the device. 
+     *  @brief Send a word to the device.
      *  @param data Data to write.
      *
      *  @retval sfeTkError_t -  kSTkErrOk on successful execution.
@@ -125,6 +131,12 @@ class sfeTkIBus
      */
     virtual sfeTkError_t writeRegisterByte(uint8_t devReg, uint8_t data) = 0;
 
+    // Overload version
+    sfeTkError_t writeRegister(uint8_t devReg, uint8_t data)
+    {
+        return writeRegisterByte(devReg, data);
+    }
+
     /**--------------------------------------------------------------------------
      * @brief Write a single word (16 bit) to the given register
      *
@@ -136,6 +148,12 @@ class sfeTkIBus
      */
     virtual sfeTkError_t writeRegisterWord(uint8_t devReg, uint16_t data) = 0;
 
+    // Overload version
+    sfeTkError_t writeRegister(uint8_t devReg, uint16_t data)
+    {
+        return writeRegisterWord(devReg, data);
+    }
+
     /**--------------------------------------------------------------------------
      *  @brief Writes a number of bytes starting at the given register's address.
      *
@@ -148,6 +166,12 @@ class sfeTkIBus
      */
     virtual sfeTkError_t writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length) = 0;
 
+    // Overload version
+    sfeTkError_t writeRegister(uint8_t devReg, const uint8_t *data, size_t length)
+    {
+        return writeRegisterRegion(devReg, data, length);
+    }
+
     /**--------------------------------------------------------------------------
      *  @brief Writes a number of bytes starting at the given register's 16-bit address.
      *
@@ -160,6 +184,29 @@ class sfeTkIBus
      */
     virtual sfeTkError_t writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length) = 0;
 
+    // Overload version
+    sfeTkError_t writeRegister(uint16_t devReg, const uint8_t *data, size_t length)
+    {
+        return writeRegister16Region(devReg, data, length);
+    }
+
+    /**--------------------------------------------------------------------------
+     *  @brief Writes a number of uint16's starting at the given register's 16-bit address.
+     *
+     *  @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
+     *
+     */
+    virtual sfeTkError_t writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length) = 0;
+
+    // Overload version
+    sfeTkError_t writeRegister(uint16_t devReg, const uint16_t *data, size_t length)
+    {
+        return writeRegister16Region16(devReg, data, length);
+    }
     /**--------------------------------------------------------------------------
      *  @brief Read a single byte from the given register
      *
@@ -171,6 +218,12 @@ class sfeTkIBus
      */
     virtual sfeTkError_t readRegisterByte(uint8_t devReg, uint8_t &data) = 0;
 
+    // Overload version
+    sfeTkError_t readRegister(uint8_t devReg, uint8_t &data)
+    {
+        return readRegisterByte(devReg, data);
+    }
+
     /**--------------------------------------------------------------------------
      *  @brief Read a single word (16 bit) from the given register
      *
@@ -181,6 +234,12 @@ class sfeTkIBus
      */
     virtual sfeTkError_t readRegisterWord(uint8_t devReg, uint16_t &data) = 0;
 
+    // Overload version
+    sfeTkError_t readRegister(uint8_t devReg, uint16_t &data)
+    {
+        return readRegisterWord(devReg, data);
+    }
+
     /**--------------------------------------------------------------------------
      *  @brief Reads a block of data from the given register.
      *
@@ -194,6 +253,12 @@ class sfeTkIBus
      */
     virtual sfeTkError_t readRegisterRegion(uint8_t reg, uint8_t *data, size_t numBytes, size_t &readBytes) = 0;
 
+    // Overload version
+    sfeTkError_t readRegister(uint8_t reg, uint8_t *data, size_t numBytes, size_t &readBytes)
+    {
+        return readRegisterRegion(reg, data, numBytes, readBytes);
+    }
+
     /**--------------------------------------------------------------------------
      *  @brief Reads a block of data from the given 16-bit register address.
      *
@@ -206,6 +271,58 @@ class sfeTkIBus
      *
      */
     virtual sfeTkError_t readRegister16Region(uint16_t reg, uint8_t *data, size_t numBytes, size_t &readBytes) = 0;
+
+    // Overload version
+    sfeTkError_t readRegister(uint16_t reg, uint8_t *data, size_t numBytes, size_t &readBytes)
+    {
+        return readRegister16Region(reg, data, numBytes, readBytes);
+    }
+    /**--------------------------------------------------------------------------
+     *  @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[out] readBytes - number of bytes read
+     *
+     *   @retval int returns kSTkErrOk on success, or kSTkErrFail code
+     *
+     */
+    virtual sfeTkError_t readRegister16Region16(uint16_t reg, uint16_t *data, size_t numBytes, size_t &readBytes) = 0;
+
+    // Overload version
+    sfeTkError_t readRegister(uint16_t reg, uint16_t *data, size_t numBytes, size_t &readBytes)
+    {
+        return readRegister16Region16(reg, data, numBytes, readBytes);
+    }
+
+    virtual uint8_t type(void)
+    {
+        return 0;
+    }
+    /**
+     * @brief Set the byte order for multi-byte data transfers
+     *
+     * @param order The byte order to set - set to either SFTK_MSBFIRST or SFTK_LSBFIRST. The default is SFTK_LSBFIRST
+     *
+     */
+    void setByteOrder(sfeTKByteOrder order)
+    {
+        _byteOrder = order;
+    }
+
+    /**
+     * @brief Get the current byte order
+     *
+     * @retval The current byte order
+     */
+    sfeTKByteOrder byteOrder(void)
+    {
+        return _byteOrder;
+    }
+
+  protected:
+    /** flag to manage byte swapping */
+    sfeTKByteOrder _byteOrder;
 };
 
-//};

src/sfeTk/sfeTkIBus.h

@@ -34,6 +34,8 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  * The I2C bus interface extends the IBus interface and adds the ability to set and get the I2C
  * address and stop flag.
  */
+const uint8_t kBusTypeI2C = 0x01;
+
 class sfeTkII2C : public sfeTkIBus
 {
   public:
@@ -109,6 +111,11 @@ class sfeTkII2C : public sfeTkIBus
      */
     static constexpr uint8_t kNoAddress = 0;
 
+    virtual uint8_t type(void)
+    {
+        return kBusTypeI2C;
+    }
+
   private:
     uint8_t _address;
     bool _stop;

src/sfeTk/sfeTkII2C.h

@@ -34,6 +34,8 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  *
  * The SPI bus interface extends the IBus interface and adds the ability to set and get the CS pin.
  */
+
+const uint8_t kBusTypeSPI = 0x02;
 class sfeTkISPI : public sfeTkIBus
 {
   public:
@@ -82,6 +84,11 @@ class sfeTkISPI : public sfeTkIBus
     */
     static constexpr uint8_t kNoCSPin = 0;
 
+    virtual uint8_t type(void)
+    {
+        return kBusTypeSPI;
+    }
+
   private:
     /** The internal storage of the _cs value*/
     uint8_t _cs;

src/sfeTk/sfeTkISPI.h

@@ -0,0 +1,75 @@
+// File: sfeToolkit.cpp
+//
+// General impl file for the SparkFun Toolkit
+/*
+
+The MIT License (MIT)
+
+Copyright (c) 2024 SparkFun Electronics
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions: The
+above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED
+"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*/
+#include "sfeToolkit.h"
+
+// THIS IS A PLACEHOLDER FILE for now
+#ifdef ARDUINO
+#include <Arduino.h>
+#endif
+//---------------------------------------------------------------------------------
+/**
+ * @brief C function - Runtime check for system byte order
+ */
+sfeTKByteOrder sftk_system_byteorder(void)
+{
+    uint16_t i = 1;
+    return *((uint8_t *)&i) == 0 ? sfeTKByteOrder::BigEndian : sfeTKByteOrder::LittleEndian;
+}
+
+//---------------------------------------------------------------------------------
+/**
+ * @brief to catch 8 bit calls for byte swap
+ *
+ */
+uint8_t sftk_byte_swap(uint8_t i)
+{
+    return i;
+}
+//---------------------------------------------------------------------------------
+/**
+ * @brief function - Byte swap a 16 bit value
+ */
+uint16_t sftk_byte_swap(uint16_t i)
+{
+    // Use the fast intrinsic if available
+#if defined(__clang__) || defined(__GNUC__)
+    return __builtin_bswap16(i);
+#else
+    return (i << 8) | (i >> 8);
+#endif
+}
+
+//---------------------------------------------------------------------------------
+/**
+ * @brief function - Byte swap a 32 bit value
+ */
+uint32_t sftk_byte_swap(uint32_t i)
+{
+#if defined(__clang__) || defined(__GNUC__)
+    return __builtin_bswap32(i);
+#else
+    return ((i << 24) & 0xff000000) | ((i << 8) & 0x00ff0000) | ((i >> 8) & 0x0000ff00) | ((i >> 24) & 0x000000ff);
+#endif
+}

src/sfeTk/sfeToolkit.cpp

@@ -6,7 +6,7 @@
 
 The MIT License (MIT)
 
-Copyright (c) 2023 SparkFun Electronics
+Copyright (c) 2024 SparkFun Electronics
 
 Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the "Software"),
@@ -26,7 +26,36 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 #pragma once
 
+#include <stdint.h>
+
 /**
     @brief Common include file for the core of the SparkFun Electronics Toolkit
 */
 #include "sfeTkError.h"
+
+
+// byte order types/enum
+enum class sfeTKByteOrder : uint8_t
+{
+    BigEndian = 0x01,
+    LittleEndian = 0x02
+};
+
+// Note - toolkit *functions* start with sftk_ to avoid name collisions
+
+// Function to determine the byte order of the system
+sfeTKByteOrder sftk_system_byteorder(void);
+
+uint8_t sftk_byte_swap(uint8_t i);
+uint16_t sftk_byte_swap(uint16_t i);
+uint32_t sftk_byte_swap(uint32_t i);
+
+
+// Area for platform specific implementations. The interface/functions are 
+// defined here, with the expectation that the platform provides the implementation.
+
+// delay in milliseconds
+void sftk_delay_ms(uint32_t ms);
+
+// ticks in milliseconds
+uint32_t sftk_ticks_ms(void);