Merge pull request #48 from sparkfun/main

Pull develop up to main.

Author: SFE-Brudnerd

.github/workflows/compile-sketch.yml

@@ -4,7 +4,10 @@ on:
   push:
     branches:
       - main
-  #- pull_request
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
 
 
 jobs:
@@ -101,11 +104,10 @@ jobs:
           libraries: |
             - source-path: ./
           sketch-paths: |
-            - tests
+            - examples/Example_01_TestCompile
           enable-warnings-report: true
           enable-deltas-report: true
           verbose: true
 
     # outputs:
     #   report-artifact-name: ${{ steps.report-artifact-name.outputs.report-artifact-name }}
-

README.md

@@ -33,52 +33,15 @@ The SparkFun Toolkit provides a single implementation of common functionality us
 
 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
+![Core Architecture](docs/images/rm_img_01.png)
 
-```
-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
-```
+And as additional platforms are added, they also implement/inherit from the SparkFun Toolkit Core.
 
-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. 
+![Multi-Platform Structure](docs/images/rm_img_02.png)
 
-```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
+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. 
 
-```
+![Application Structure](docs/images/rm_img_03.png)
 
 If/when the application is moved to another platform, just the platform specific logic needs implementation. 
 

docs/images/rm_img_01.png

@@ -6,6 +6,8 @@
 
 sfTkArdI2C myI2C;
 sfTkArdSPI mySPI;
+sfTkArdUART myUART;
+sfTkArdUARTBus myUARTBus(myUART);
 
 void setup()
 {

docs/images/rm_img_02.png

@@ -1,5 +1,5 @@
 name=SparkFun Toolkit
-version=1.0.0
+version=1.1.0
 author=SparkFun Electronics
 maintainer=SparkFun Electronics
 sentence=A utility library that other SparkFun libraries can take advantage of.

docs/images/rm_img_03.png

@@ -21,4 +21,5 @@
 // Just include the toolkit headers
 #include "sfTkArdI2C.h"
 #include "sfTkArdSPI.h"
+#include "sfTkArdUART.h"
 #include "sfTkArduino.h"

tests/test_bus01/test_bus01.ino renamed to examples/Example_01_TestCompile/Example_01_TestCompile.ino

@@ -0,0 +1,115 @@
+/**
+ * @file sfTkISerial.h
+ * @brief Header file for the SparkFun Toolkit Base Serial Interface Definition.
+ *
+ * This file contains the interface declaration for basic serial read/write.
+ *
+ * @author SparkFun Electronics
+ * @date 2025
+ * @copyright Copyright (c) 2025, SparkFun Electronics Inc. This project is released under the MIT License.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+// clang-format off
+#include "sfTkError.h"
+// clang-format on
+
+/**
+ * @brief A base value for serial errors. All serial errors are greater than this value, in the 2000 range
+ *
+ */
+const sfTkError_t ksfTkErrBaseSerial = 0x2000;
+
+/**
+ * @brief Error code for when a serial system is not initalized.
+ */
+const sfTkError_t ksfTkErrSerialNotInit = ksfTkErrFail * (ksfTkErrBaseSerial + 1);
+
+/**
+ * @brief Returned when a serial interface times out.
+ *
+ */
+const sfTkError_t ksfTkErrSerialTimeout = ksfTkErrFail * (ksfTkErrBaseSerial + 2);
+
+/**
+ * @brief Returned when a serial interface does not respond.
+ *
+ */
+const sfTkError_t ksfTkErrSerialNoResponse = ksfTkErrFail * (ksfTkErrBaseSerial + 3);
+
+/**
+ * @brief Returned when the data to be sent is too long or received is too short.
+ *
+ */
+const sfTkError_t ksfTkErrSerialDataTooLong = ksfTkErrFail * (ksfTkErrBaseSerial + 4);
+
+/**
+ * @brief Returned when the serial settings are null, invalid, or on set/initialized.
+ *
+ */
+const sfTkError_t ksfTkErrSerialNullSettings = ksfTkErrFail * (ksfTkErrBaseSerial + 5);
+
+/**
+ * @brief Returned when the buffer is null or invalid.
+ *
+ */
+const sfTkError_t ksfTkErrSerialNullBuffer = ksfTkErrFail * (ksfTkErrBaseSerial + 6);
+
+/**
+ * @brief Returned when the bus is under read. Warning.
+ *
+ */
+const sfTkError_t ksfTkErrSerialUnderRead = ksfTkErrBaseSerial + 7;
+
+class sfTkISerial
+{
+  public:
+    sfTkISerial() = default;
+    virtual ~sfTkISerial() = default;
+
+    /**
+     * @brief Writes an array of bytes to the serial interface.
+     *
+     * @param data The data to write
+     * @param length The length of the data buffer
+     * @return sfTkError_t Returns ksfTkErrOk on success, or ksfTkErrFail code
+     */
+    virtual sfTkError_t write(const uint8_t *data, size_t length) = 0;
+
+    /**
+     * @brief Writes a single byte to the serial interface.
+     *
+     * @param data The data to write
+     * @return sfTkError_t Returns ksfTkErrOk on success, or ksfTkErrFail code
+     */
+    virtual sfTkError_t write(const uint8_t data)
+    {
+        return write(&data, sizeof(data));
+    }
+
+    /**
+     * @brief Reads an array of bytes from the serial interface
+     *
+     * @param data The data buffer to read into
+     * @param length The length of the data buffer
+     * @param readBytes[out] The number of bytes read
+     * @return sfTkError_t Returns ksfTkErrOk on success, or ksfTkErrFail code
+     */
+    virtual sfTkError_t read(uint8_t *data, size_t length, size_t &readBytes) = 0;
+
+    /**
+     * @brief Read a single byte from the serial interface
+     *
+     * @param data Byte to be read
+     * @return sfTkError_t Returns ksfTkErrOk on success, or ksfTkErrFail code
+     */
+    virtual sfTkError_t read(uint8_t &data)
+    {
+        size_t nRead;
+
+        return read(&data, sizeof(data), nRead);
+    }
+};

library.properties

@@ -0,0 +1,117 @@
+/**
+ * @file sfTkISerialBus.h
+ * @brief Header file for the SparkFun Toolkit Base Serial Bus Interface Definition.
+ *
+ * This file contains the interface declaration for connecting sfTkISerial to the sfTkIBus.
+ *
+ * @author SparkFun Electronics
+ * @date 2025
+ * @copyright Copyright (c) 2025, SparkFun Electronics Inc. This project is released under the MIT License.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+
+#pragma once
+
+// clang-format off
+#include "sfTkError.h"
+#include "sfTkIBus.h"
+#include "sfTkISerial.h"
+// clang-format on
+
+const uint8_t ksfTkBusTypeSerialBus = 0x03;
+
+class sfTkISerialBus : sfTkIBus
+{
+  public:
+    /**
+     * @brief Constructor for the serial bus
+     *
+     */
+    sfTkISerialBus()
+    {
+    }
+
+    virtual ~sfTkISerialBus() = default;
+
+    /**
+     * @brief Writes an array of bytes to the serial interface.
+     *
+     * @param data The data to write
+     * @param length The length of the data buffer
+     * @return sfTkError_t Returns ksfTkErrOk on success, or ksfTkErrFail code
+     */
+    virtual sfTkError_t write(const uint8_t *data, size_t length) = 0;
+
+    /**
+     * @brief Writes an array of bytes to a register on the target address. Supports any address size
+     *
+     * @param devReg The device's register's address - can be any size, If nullptr, address is not sent
+     * @param regLength The length of the register address. If 0, address is not sent
+     * @param data The data to write
+     * @param length The length of the data buffer
+     * @return sfTkError_t Returns ksfTkErrOk on success, or ksfTkErrFail code
+     */
+    virtual sfTkError_t writeRegister(uint8_t *devReg, size_t regLength, const uint8_t *data, size_t length) override
+    {
+
+        // Do we have a register? If so write it, else skip.
+        if (devReg != nullptr && regLength > 0)
+            write(devReg, regLength);
+
+        // Write the data.
+        return write(data, length);
+    }
+
+    /**
+     * @brief Read an array of bytes from the serial interface
+     *
+     * @param data The data buffer to read into
+     * @param length The length of the data buffer
+     * @param readBytes[out] The number of bytes read
+     * @return sfTkError_t Returns ksfTkErrOk on success, or ksfTkErrFail code
+     */
+    virtual sfTkError_t read(uint8_t *data, size_t length, size_t &readBytes) = 0;
+
+    /**
+     * @brief Reads an array of bytes to a register on the target address. Supports any address size
+     *
+     * @param devReg The device's register's address - can be any size
+     * @param regLength The length of the register address
+     * @param data The data to buffer to read into
+     * @param numBytes The length of the data buffer
+     * @param readBytes[out] The number of bytes read
+     * @return sfTkError_t Returns ksfTkErrOk on success, or ksfTkErrFail code
+     */
+    virtual sfTkError_t readRegister(uint8_t *devReg, size_t regLength, uint8_t *data, size_t numBytes,
+                                     size_t &readBytes) override
+    {
+        // Buffer valid?
+        if (!data)
+            return ksfTkErrBusNullBuffer;
+
+        sfTkError_t retVal = ksfTkErrOk;
+
+        // Do we have a register? If so, write it, else skip.
+        if (devReg != nullptr && regLength > 0)
+            retVal = write(devReg, regLength);
+
+        if (retVal != ksfTkErrOk)
+            return retVal;
+
+        // Read the data.
+        retVal = read(data, numBytes, readBytes);
+
+        return retVal;
+    }
+
+    /**
+     * @brief Get the type of the object
+     *
+     * @return uint8_t The type of the object
+     */
+    virtual uint8_t type(void) override
+    {
+        return ksfTkBusTypeSerialBus;
+    }
+};