sparkfun/sparkfun_toolkit

Toolkit of common functionality for use within SparkFun Libraries

SparkFun Toolkit Arduino Library

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.

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.

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
• Set the foundation for future enhancements - as the capabilities of the toolkit grow, these features become available with little to any implementation effort.

Documentation

The SparkFun Toolkit Development documentation is available here

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.

depends=SparkFun Toolkit

Examples

The following Arduino Libraries are making use of the SparkFun Toolkit:

• SparkFun Qwiic Pulsed Coherent Radar Sensor XM125
• SparkFun Qwiic AS7331 Spectral UV Sensor

sparkfun_toolkit's Issues

Document the "Platform Neutral" approach to developing libraries using the toolkit.

Document and create examples (or point to existing libraries) that outline the design pattern the Toolkit library is intended for.

This overview document includes:

• Creating a C++ core for a library, that uses the Toolkit
• How the core is leveraged to implement an Arduino solution
• Examples of using this core library approach across different platforms, or bus types.

Define final SparkFun Arduino class name pattern

Current thoughts are:

SparkFun_[Upper_Camel_Snake_For_Product_Name]

Add I2C data buffer size setting to the Arduino I2C driver

Add a buffer property that is settable/gettable outside the Toolkit

Create an FreeRTOS set of examples to validate cross platform functionality

Besides Arduino examples, create a set of FreeRTOS examples to validate the "cross-platform" implementation of the technology.

Add error code system to the toolkit

Add a "toolkit" level error code / type system that follows common/standard patterns

Select a list of 10 existing SparkFun qwiic libraries to port over to the new toolkit

The list should include a wide range of libraries (old, new, popular) to provide a solid test and validation range for the new tool kit.

For each library selected

• Create an additional task in this project
• Port the library to this new system - In a New Branch
• Test all examples for that particular solution

Develop a prototype of the library for communication buses

Based on existing work

Create an Arduino Example that uses the toolkit to support three bus types with a single application logic implementation

Create an Arduino example that implements core functionality using the bus functionality provided by the toolkit.

The example should demonstrate using the same application logic across the different bus types supported by the toolkit.

Add content to the README of the Toolkit repo

Make sure the repo is identified as being beta and mostly for internal SparkFun use

Develop/write a general design document for the communication bus work

Place in a docs directory, written in markdown.

Goal - to evolve this as the project evolves -- and then place this in the final documentation for this project (GitHub Pages).

Use SPDX for license in source code files

Arduino-ify the project repository

Flesh out the contents of this repository - so it supports a "Arduino Library" structure

SPI doesn't compile on ESP32

SparkFun_Toolkit/src/sfe_bus.cpp

Line 231 in 6ee3c24

SPISettings spiSettings = SPISettings(3000000, MSBFIRST, SPI_MODE3);

MSBFIRST and SPI_MODE3 not defined, might need to `#include <Arduino.h>

Make the Toolkit public, publish to the Arduino library repo

Make the toolkit public, so we can use it in our libraries

Update the architecture document to reflect final impl

Naming scheme for the underlying toolkit

Use 'sfe' for the underlying object naming pattern.

Namely sfe[ObjectName

Integrate the Arduino I2C portion of the toolkit into one SparkFun Product and support product launch

For the first launch/beta of the toolkit, integrate and test it with one new SparkFun original library

Description: Create a library of common entitles/functionality for use across other SparkFun Libraries/Applications

Description

Design, develop and implement a foundational software library that implements support for common, embedded functionality. This library is intended to be a core foundational block for SparkFun software implementations, enabling the use of a single, well tested solution across all products. Today, for common capabilities, each new library implements its own version of the functionality – a option that is error prone and difficult to maintain. With a “toolkit” library, only one, well tested and validated implementation is used across all our solutions. Additionally, updates to the toolkit library are rapidly integrated into existing solution updates.

The key premise that makes this toolkit library possible, is the library dependency functionally supported by the development environments the library is used within. For example, when building a new SparkFun Arduino Library, the new library can mark the SparkFun Toolkit library as a dependency.

While the initial focus of this library is communication bus architectures, the capabilities of this library will expand over time to deliver a wide variety of capabilities.

Initial Focus - Communication Bus Functionality

The library is designed to deliver a common communication bus interface, that is shared across the various bus types supported. This common interface enables the implementation of capabilities, with little need to understand the underlying details of the bus architecture, or even which type of bus is being used.

This implementation should support the following communication bus types:

• I2C
• SPI
• UART/Serial

While the setup of each bus is different (initialization and definition), the data communication interface is the same, enabling common functionality use across different bus architectures

Use Scenarios

The general use case/scenario for the communication bus implementation of the Foundation library is:

• An Arduino Library developer includes the SparkFun Foundation library.
• The SparkFun Foundation library is marked as dependency, ensuring Arduino will install it automatically.
• The core functionality of the new library uses the common communication interface provided. Read and write operations are performed using methods on this common interface.
• The design of the library decouples the use of the bus implementation, from the creation of the bus specific object. This enables rapid creation of bus type specific solutions that all use the same core functionality.

Target Personas/Users

• Arduino library developers
• Internal SparkFun developers/employees

Key Functionality

• Presents communication bus interfaces using a single, common interface.
• C++ Implementation, with platform specific components (i.e. Arduino) provided, but part of the core architecture
• Initial platform is Arduino.

Design Considerations

• The foundation library functionality isolated using a C++ namespace.
• Focus on Arduino initially.
• Once a core implementation is available, test across a variety of existing SparkFun libraries to validate the implementation.
  • Once launched and available to the Arduino environment, these test libraries shall be updated to use the Foundation library.

Note that the implementation should follow the pattern delivered as part of these libraries:

• The SparkFun KX13X Library
• The SparkFun ISM330DHCX Library

Documentation

Delivered using GitHub Pages, the documentation should include:

• Design overview and diagrams
• Use examples.
• API Documentation

Product Launch

Once launched and in use internally, the launch shall be marked via a SparkFun blog post. The intent is for internal use, but there's nothing to prevent external use of this library