Release/v01.00.00

.github/workflows/build-deploy-ghpages.yml

@@ -1,4 +1,4 @@
-name: Build Documentation and Deploy
+name: Documentation
 
 on:
   push:

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)
@@ -6,38 +7,102 @@
 ![GitHub (Pre-)Release Date](https://img.shields.io/github/release-date-pre/sparkfun/SparkFun_Toolkit)
 ![Documentation Build](https://github.com/sparkfun/SparkFun_Toolkit/actions/workflows/build-deploy-ghpages.yml/badge.svg)
 
-The SparkFun Toolkit provides a common set of core functionality for use across the SparkFun Arduino Driver library. Instead of each device driver library implementing it's own communication layers, error types and design, the SparkFun Toolkit library is used.
+The SparkFun Toolkit provides a common set of core functionality for use across the spectrum of SparkFun developed embedded libraries and applications. It provides a well tested, extensively used, and abstract foundational layer of functionality to use across a wide-range of solutions. 
+
+This, the first iteration of the SparkFun Toolkit focuses on device communication - namely the communication between a embedded microprocessor and a peripheral devices. Focusing on the *communication bus* aspect of embedded development, the toolkit simplifies system development by providing a proven bus implementation, as well as a set of abstract interfaces that enable rapid development of multi-bus type implementations. 
+
+In addition to providing a set of common device bus communication functionality, the SparkFun Toolkit is structure to provide a *platform independent* solution. While the initial implementation targets Arduino development, the architecture is patterned to define a common core of functionality and interfaces that are platform agnostic. Use of the SparkFun Toolkit within a non-Arduino, c++ environment, requires the implementation of small set of platform specific functionality. 
 
 ## Motivation
 
-Often, the same core functionality is implemented with a majority of our Arduino libraries, each implementation providing the same functionality, but implemented differently. The result is solutions that have different quirks, and impossible to maintain/support effectively. The SparkFun Toolkit solves this issue.
+Often, the same core functionality is implemented within a majority of our Arduino libraries, with each implementation providing the same functionality, but implemented differently.  The result of this are different solutions that delivery the same functionality, but each have  their unique quirks and behavior oddities. As this implementation patter expands, it becomes impossible to maintain/support effectively. 
+
+An example of this is software libraries provided in support of the SparkFun qwiic ecosystem. With over 200 sensors, input devices and accessories, the implementation and maintenance of the driver communication layers are difficult burden that the SparkFun Toolkit addresses. 
+
+## The SparkFun Toolkit
 
 The SparkFun Toolkit provides a single implementation of common functionality used in the software developed for SparkFun boards. Initially targeted  at the Arduino development environment, the SparkFun Toolkit delivers the following benefits:
 
 * Use a well-tested and validated implementation
 * Reduce development effort
 * Implement functionality following a common structure
+* Designed following a platform independent architectural pattern
 * Set the foundation for future enhancements - as the capabilities of the toolkit grow, these features become available with little to any implementation effort.
 
+### General Architecture
+
+Implemented using C++, the SparkFun toolkit follows a simple two layered approach in it's design: A core foundational layer, and a platform specific layer. 
+
+```mermaid
+---
+title: General Architecture Structure
+---
+classDiagram
+    class CoreToolkit["Core Toolkit Interfaces"] 
+    class PlatformOne["Platform Implementation"]
+    CoreToolkit <|-- PlatformOne
+
+```
+And as additional plaforms are added, they also implement/inherit from the SparkFun Toolkit Core.
+```mermaid
+---
+title: Multi-Platform Structure
+---
+classDiagram
+    class CoreToolkit["Core Toolkit Interfaces"]
+    class PlatformOne["Platform One"]
+    class PlatformTwo["Platform Two"]
+
+    CoreToolkit <|-- PlatformOne
+    CoreToolkit <|-- PlatformTwo
+```
+
+When using the SparkFun Toolkit, the intent is for the implementation to follow the same pattern: A platform independent layer that works with the SparkFun Toolkit core, and a platform specific layer that utilizes the SparkFun Toolkit platform specific implementation. 
+
+```mermaid
+---
+title: Application Structure
+---
+classDiagram
+    direction TD
+    note for ApplicationCore "Application Logic"
+    class ApplicationCore["Application Core"]
+    class CoreToolkit["Core Toolkit Interfaces"] 
+
+    note for CoreToolkit "SparkFun Toolkit"
+    class ApplicationPlatform["Application Platform"]
+    style ApplicationPlatform fill:#909090
+    class PlatformOne["Platform Implementation"]
+    style PlatformOne fill:#909090
+
+    CoreToolkit <|-- PlatformOne
+    ApplicationCore <--> Application Platform
+
+```
+
+If/when the application is moved to another platform, just the platform specific logic needs implementation. 
+
 ## Documentation
 
-The SparkFun Toolkit Development documentation is available [here](https://docs.sparkfun.com/SparkFun_Toolkit)
+The SparkFun Toolkit Development documentation is available [here](https://docs.sparkfun.com/SparkFun_Toolkit). This includes doxygen generated class/API documentation, as well as additional architectural details.
+
+## Examples
+
+The best way to understand and use the SparkFun Toolkit is to see it being used on other libraries. For our SparkFun developed libraries and firmware that use the SparkFun Toolkit, their associated github repositories are tagged with [sparkfun-toolkit](https://github.com/topics/sparkfun-toolkit) tag. 
+
 
 ## Installation and Use
 
 To use the SparkFun Toolkit directly, or in library development kit is installable via the Arduino Library Manager - search for `SparkFun ToolKit` within the Arduino Library Manager to install.
 
 However, for solutions that use the SparkFun Toolkit, it is installed automatically during the Arduino library installation process, by marking the Toolkit as a dependency when publishing your library.
 
-To mark the `SparkFun Toolkit` as a dependency, add the following line to the `library.properties` file for your library.
+To mark the `SparkFun Toolkit` as a dependency, add the following line to the `library.properties` file for your library. 
 
 ```INI
-depends=SparkFun Toolkit
+depends=SparkFun Toolkit (>=1.0.0)
 ```
 
-## Examples
-
-The following Arduino Libraries are making use of the SparkFun Toolkit:
+> [!NOTE]
+> A version indicator is included to ensure your library uses the correct version of the toolkit.
 
-* [SparkFun Qwiic Pulsed Coherent Radar Sensor XM125](https://github.com/sparkfun/SparkFun_Qwiic_XM125_Arduino_Library)
-* [SparkFun Qwiic AS7331 Spectral UV Sensor](https://github.com/sparkfun/SparkFun_AS7331_Arduino_Library)

docs/ar_ibus.md

@@ -35,35 +35,32 @@ The key class to support this pattern are:
 
 | | |
 |------|-------|
-|**sfeTkIBus** | A virtual C++ class that device the bus ```sfeTkIBus``` interface |
-|**sfeTkII2C** | Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for I2C devices|
-|**sfeTkISPI** | Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for SPI devices |
+|**sfTkIBus** | A virtual C++ class that device the bus ```sfeTkIBus``` interface |
+|**sfTkII2C** | Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for I2C devices|
+|**sfTkISPI** | Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for SPI devices |
 
-### The sfeTkIBus Interface
+### The sfTkIBus Interface
 
 The key to meeting the goals of the Toolkit is the IBus interface. This interface defines the  methods used to communicate with a device. The setup, configuration and implementation of this interface is performed by platform specific implementations of the interface.
 
-The interface methods:
+The bus implements methods that perform the following
 
 | Method| Definition |
 |------|-------|
-|**writeRegisterByte** | Write a byte of data to a particular register of a device |
-|**writeRegisterWord** | Write a word of data to a particular register of a device |
-|**writeRegisterRegion** | Write an array of data to a particular register of a device|
-|**readRegisterByte** | Read a byte of data from a particular register of a device |
-|**readRegisterWord** | Read a word of data from a particular register of a device |
-|**readRegisterRegion** | Read an array of data from a particular register of a device |
+|**writeRegister(...)** | Overloaded set of methods to write data to a specified register|
+|**readRegister(...)** | Overloaded set of methods to read data from a specified register|
+|**writeData(...)** | An overloaded set of methods to write data directly to the device|
+
+Additionally a set of explicitly named methods for different core types are provided.
 
 > [!NOTE]
 > This interface only defines the methods to read and write data on the given bus. Any address, or bus specific settings is provided/implemented by the implementation/specialization of this interface.
 
-The Inteface diagram for the ```sfeTkIBus``` is:
-
-![IIBus Interface](images/tk_uml_ibus.png)
+Specific details for this class are detailed [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_i_bus.html)
 
-### The sfeTkII2C Implementation
+### The sfTkII2C Implementation
 
-This class sub-classes from the ```sfeTkIBus``` interface adding additional functionally focused on supporting an I2C implementation. This class does not implement the IIBus interface, so it's abstract, but the class adds the additional functionality.
+This class sub-classes from the ```sfTkIBus``` interface adding additional functionally focused on supporting an I2C implementation. This class does not implement the IIBus interface, so it's abstract, but the class adds the additional functionality.
 
 | Method| Definition |
 |------|-------|
@@ -72,15 +69,13 @@ This class sub-classes from the ```sfeTkIBus``` interface adding additional func
 |**address** | Returns the address used by this I2C object |
 
 > [!NOTE]
-> The ```sfeTkII2C``` class manages the device address for the I2C bus. As such, each I2C device instantiates/uses an instance of the ```sfeTkII2C``` class.
+> The ```sfTkII2C``` class manages the device address for the I2C bus. As such, each I2C device instantiates/uses an instance of the ```sfTkII2C``` class.
 
-The class diagram for the ```sfeTkII2C``` interface is the following:
-
-![II2C Class Diagram](images/tk_uml_ii2c.png)
+The details for the ```sfeTkII2C``` interface are [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_i_i2_c.html)
 
 ### The sfeTkISPI Implementation
 
-This class sub-classes from the ```sfeTkIBus``` interface adding additional functionally focused on supporting an SPI implementation. This interface provides the additional functionality.
+This class sub-classes from the ```sfTkIBus``` interface adding additional functionally focused on supporting an SPI implementation. This interface provides the additional functionality.
 
 | Method| Definition |
 |------|-------|
@@ -90,53 +85,47 @@ This class sub-classes from the ```sfeTkIBus``` interface adding additional func
 > [!NOTE]
 > The ```sfeTkISPI``` class manages CS Pin for the SPI bus. As such, each SPI device instantiates/uses an instance of the ```sfeTkISPI``` class.
 
-The class diagram of these base class interfaces/implementation:
-
-![ISPI Class Diagram](images/tk_uml_ispi.png)
+The details for the ```sfTkII2C``` interface are [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_i_s_p_i.html)
 
-## sfeTkIBus - Arduino Implementation
+## sfTkIBus - Arduino Implementation
 
-The initial implementation of the toolkit IBus interface is for the Arduino environment. This implementation consists of two classes, ```sfeTkArdI2C``` and ```sfeTkArdSPI```, each of which sub-class from their respective bus type interfaces within the core toolkit.
+The initial implementation of the toolkit IBus interface is for the Arduino environment. This implementation consists of two classes, ```sfTkArdI2C``` and ```sfTkArdSPI```, each of which sub-class from their respective bus type interfaces within the core toolkit.
 
 These driver implementations provide the platform specific implementation for the toolkit bus interfaces, supporting the methods defined by the interfaces, as well as contain and manage the platform specific settings and attributes for each bus type.
 
 > [!IMPORTANT]
 > The intent is that each user of an particular - a device in most cases - contains an instance of the specific bus class.
 
-### The sfeTkArdI2C Class
+### The sfTkArdI2C Class
 
-This class provides the Arduino implementation of I2C in the SparkFun Toolkit. It implements the methods of the ```sfeTkIBus``` and ```sfeTkII2C``` interfaces, as well as manages any Arduino specific state.
+This class provides the Arduino implementation of I2C in the SparkFun Toolkit. It implements the methods of the ```sfTkIBus``` and ```sfTkII2C``` interfaces, as well as manages any Arduino specific state.
 
-The class diagram for the sfeTkArdI2C class:
+Details for this class are located [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_ard_i2_c.html)
 
-![Arduino I2C Class Diagram](images/tk_uml_ardi2c.png)
+### The sfTkArdSPI Class
 
-### The sfeTkArdSPI Class
+This class provides the Arduino implementation of SPI in the SparkFun Toolkit. It implements the methods of the ```sfTkIBus``` and ```sfTkISPI``` interfaces, as well as manages any Arduino specific state for the SPI bus - namely the SPISettings class.
 
-This class provides the Arduino implementation of SPI in the SparkFun Toolkit. It implements the methods of the ```sfeTkIBus``` and ```sfeTkISPI``` interfaces, as well as manages any Arduino specific state for the SPI bus - namely the SPISettings class.
+Before each use of the SPI bus, the methods of the ```sfTkArdSPI``` uses an internal SPISettings class to ensure the SPI bus is operating in the desired mode for the device.
 
-Before each use of the SPI bus, the methods of the ```sfeTkArdSPI``` uses an internal SPISettings class to ensure the SPI bus is operating in the desired mode for the device.
+Details for this class are located [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_ard_s_p_i.html)
 
-The class diagram for the sfeTkArdSPI class:
+## sfTkIBus Use
 
-![Arduino SPI Class Diagram](images/tk_uml_ardspi.png)
-
-## sfeTkIBus Use
-
-The general steps when using the sfeTkIBus in device development are outlined in the following steps. This example uses the Arduino implementation of the bus.
+The general steps when using the sfTkIBus in device development are outlined in the following steps. This example uses the Arduino implementation of the bus.
 
 The general pattern for a device driver implementation that uses the SparkFun Toolkit is the following:
 
 ### Implement a Platform Independent Driver
 
-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.
+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 ```sfTkIBus``` interface. By limiting use to the IBus interface, the core implementation can use any bus type or platform that implements the sfeTkIBus interface.
 
 > [!IMPORTANT]
-> At this level, the driver is only using a ```sfeTkIBus``` interface, not any specific bus implementation.
+> At this level, the driver is only using a ```sfTkIBus``` interface, not any specific bus implementation.
 
 This driver has the following unique functionality:
 
-1) A method to set the object that implements the ```sfeTkIBus``` interface object should use. Since
+1) A method to set the object that implements the ```sfTkIBus``` interface object should use or sets the bus in a ```begin()``` method.
 1) If the device supports identification capabilities, the driver provides this functionality.
 
 #### Simple Example of an Independent Driver Implementation
@@ -152,36 +141,42 @@ class myDriverClass
 {
 public:
 
-    myDriverClass(uint8_t address) : _addr{address}, _theBus{nullptr}{}
+    myDriverClass() : _theBus{nullptr}{}
 
-    bool begin()
+    sfTkError_t begin(sfTkBus *theBus = nullptr)
     {
         // initialize things ...
 
-        return true;
-    }
-    void setCommunicationBus(sfeTkIBus *theBus)
-    {
+        if (_theBus == nullptr)
+            return ksfTkErrFail;
+
         _theBus = theBus;
+        return ksfTkErrOk;
     }
 
-    bool updateDeviceData(uint8_t *data, size_t len)
+    sfTkError_t updateDeviceData(uint8_t *data, size_t len)
     {
         if (!_theBus || !data || len == 0)
-            return false;
+            return ksfTkErrFail;
 
-        sfeTkError_t status = _theBus->writeRegisterRegion(THE_REG, data, len);
+        return _theBus->writeRegister(THE_REG, data, len);
 
         return (status == kSTkErrOk);
     }
 
-    bool checkDeviceID()
+    sfTkError_t checkDeviceID()
     {
         // do some device ID checks in registers ...etc
-        return true;
+        return kSTkErrOk;
     }
+    // and additional methods for the driver ..
+    sfTkError_t doSomethingA(int32_t);
+    sfTkError_t getValueA(uint32_t&);
+    sfTkError_t setPropertyB(double);
+
+
 private:
-    uint8_t _addr;
+
     sfeTkIBus *_theBus;
 };
 ```
@@ -213,29 +208,27 @@ class myArduinoDriverI2C : public myDriverClass
     myArduinoDriverI2C()
     {}
 
-    bool begin()
+    bool begin(const uint8_t address = SF_BMV080_DEFAULT_ADDRESS, TwoWire &wirePort = Wire)
     {
-        if (_theI2CBus.init(MY_DEVICE_ADDRESS) != kSTkErrOk)
+        if (_theI2CBus.init(wirePOrt, MY_DEVICE_ADDRESS) != ksfTkErrOk)
             return false;
 
         // OPTIONAL: If your device supports repeat starts.
         _theI2CBus.setStop(false);
 
-        setCommunicationBus(&_theI2CBus);
-
-        return myDriverClass::begin();
+        return myDriverClass::begin(&_theI2CBus);
     }
 
     bool isConnected()
     {
-        if (_theI2CBus.ping() != kSTkErrOk)
+        if (_theI2CBus.ping() != ksfTkErrOk)
             return false;
 
-        return checkDeviceID();
+        return checkDeviceID() == kstTkErrOk;
     }
 
 private:
-   sfeTkArdI2C _theI2CBus;
+   sfTkArdI2C _theI2CBus;
 };
 ```
 
@@ -254,27 +247,30 @@ class myArduinoDriveSPI : public myDriverClass
     myArduinoDriverSPI()
     {}
 
-    bool begin()
+    bool begin(uint8_t csPin, SPIClass &spiPort = SPI,
+               SPISettings spiSettings = SPISettings(4000000, MSBFIRST, SPI_MODE0))
+
     {
-        SPISettings spiSettings = SPISettings(4000000, MSBFIRST, SPI_MODE3);
 
-        if (_theSPIBus.init(SPI, spiSettings, MY_DEFAULT_CS, true) != kSTkErrOk)
+        if (_theSPIBus.init(spiPort, spiSettings, csPin, true) != ksfTkErrOk)
             return false;
-        setCommunicationBus(&_theSPIBus);
 
-        return myDriverClass::begin();
+        return myDriverClass::begin(&_theSPIBus) == ksfTkErrOk;
     }
 
     bool isConnected()
     {
-        return checkDeviceID();
+        return checkDeviceID() == ksfTkErrOk;
     }
 
 private:
-   sfeTkArdSPI _theSPIBus;
+   sfTkArdSPI _theSPIBus;
 };
 ```
 
+> [!IMPORTANT]
+>The I2C and SPI versions of the driver just manage the specific bus setup and  initialization - beyond that, the core class, which ***only*** operates using the bus interface class forms the core of both implementations. 
+
 ## Summary
 
 In summary, the SparkFun Toolkit Bus Interface sets a standard that device drivers can implement against without concern for platform or bus type. Using common interface implementation patterns, the implementation delivers on the goals for this subsystem - namely: