You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
10
+
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.
11
+
12
+
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.
13
+
14
+
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.
11
15
12
16
## Motivation
13
17
14
-
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.
18
+
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.
19
+
20
+
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.
21
+
22
+
## The SparkFun Toolkit
15
23
16
24
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:
17
25
18
26
* Use a well-tested and validated implementation
19
27
* Reduce development effort
20
28
* Implement functionality following a common structure
29
+
* Designed following a platform independent architectural pattern
21
30
* Set the foundation for future enhancements - as the capabilities of the toolkit grow, these features become available with little to any implementation effort.
22
31
32
+
### General Architecture
33
+
34
+
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.
35
+
36
+
```mermaid
37
+
---
38
+
title: General Architecture Structure
39
+
---
40
+
classDiagram
41
+
class CoreToolkit["Core Toolkit Interfaces"]
42
+
class PlatformOne["Platform Implementation"]
43
+
CoreToolkit <|-- PlatformOne
44
+
45
+
```
46
+
And as additional plaforms are added, they also implement/inherit from the SparkFun Toolkit Core.
47
+
```mermaid
48
+
---
49
+
title: Multi-Platform Structure
50
+
---
51
+
classDiagram
52
+
class CoreToolkit["Core Toolkit Interfaces"]
53
+
class PlatformOne["Platform One"]
54
+
class PlatformTwo["Platform Two"]
55
+
56
+
CoreToolkit <|-- PlatformOne
57
+
CoreToolkit <|-- PlatformTwo
58
+
```
59
+
60
+
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.
61
+
62
+
```mermaid
63
+
---
64
+
title: Application Structure
65
+
---
66
+
classDiagram
67
+
direction TD
68
+
note for ApplicationCore "Application Logic"
69
+
class ApplicationCore["Application Core"]
70
+
class CoreToolkit["Core Toolkit Interfaces"]
71
+
72
+
note for CoreToolkit "SparkFun Toolkit"
73
+
class ApplicationPlatform["Application Platform"]
74
+
style ApplicationPlatform fill:#909090
75
+
class PlatformOne["Platform Implementation"]
76
+
style PlatformOne fill:#909090
77
+
78
+
CoreToolkit <|-- PlatformOne
79
+
ApplicationCore <--> Application Platform
80
+
81
+
```
82
+
83
+
If/when the application is moved to another platform, just the platform specific logic needs implementation.
84
+
23
85
## Documentation
24
86
25
-
The SparkFun Toolkit Development documentation is available [here](https://docs.sparkfun.com/SparkFun_Toolkit)
87
+
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.
88
+
89
+
## Examples
90
+
91
+
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.
92
+
26
93
27
94
## Installation and Use
28
95
29
96
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.
30
97
31
98
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.
32
99
33
-
To mark the `SparkFun Toolkit` as a dependency, add the following line to the `library.properties` file for your library.
100
+
To mark the `SparkFun Toolkit` as a dependency, add the following line to the `library.properties` file for your library.
34
101
35
102
```INI
36
-
depends=SparkFun Toolkit
103
+
depends=SparkFun Toolkit (>=1.0.0)
37
104
```
38
105
39
-
## Examples
40
-
41
-
The following Arduino Libraries are making use of the SparkFun Toolkit:
106
+
> [!NOTE]
107
+
> A version indicator is included to ensure your library uses the correct version of the toolkit.
Copy file name to clipboardExpand all lines: docs/ar_ibus.md
+65-69Lines changed: 65 additions & 69 deletions
Original file line number
Diff line number
Diff line change
@@ -35,35 +35,32 @@ The key class to support this pattern are:
35
35
36
36
|||
37
37
|------|-------|
38
-
|**sfeTkIBus**| A virtual C++ class that device the bus ```sfeTkIBus``` interface |
39
-
|**sfeTkII2C**| Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for I2C devices|
40
-
|**sfeTkISPI**| Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for SPI devices |
38
+
|**sfTkIBus**| A virtual C++ class that device the bus ```sfeTkIBus``` interface |
39
+
|**sfTkII2C**| Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for I2C devices|
40
+
|**sfTkISPI**| Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for SPI devices |
41
41
42
-
### The sfeTkIBus Interface
42
+
### The sfTkIBus Interface
43
43
44
44
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.
45
45
46
-
The interface methods:
46
+
The bus implements methods that perform the following
47
47
48
48
| Method| Definition |
49
49
|------|-------|
50
-
|**writeRegisterByte**| Write a byte of data to a particular register of a device |
51
-
|**writeRegisterWord**| Write a word of data to a particular register of a device |
52
-
|**writeRegisterRegion**| Write an array of data to a particular register of a device|
53
-
|**readRegisterByte**| Read a byte of data from a particular register of a device |
54
-
|**readRegisterWord**| Read a word of data from a particular register of a device |
55
-
|**readRegisterRegion**| Read an array of data from a particular register of a device |
50
+
|**writeRegister(...)**| Overloaded set of methods to write data to a specified register|
51
+
|**readRegister(...)**| Overloaded set of methods to read data from a specified register|
52
+
|**writeData(...)**| An overloaded set of methods to write data directly to the device|
53
+
54
+
Additionally a set of explicitly named methods for different core types are provided.
56
55
57
56
> [!NOTE]
58
57
> 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.
59
58
60
-
The Inteface diagram for the ```sfeTkIBus``` is:
61
-
62
-
59
+
Specific details for this class are detailed [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_i_bus.html)
63
60
64
-
### The sfeTkII2C Implementation
61
+
### The sfTkII2C Implementation
65
62
66
-
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.
63
+
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.
67
64
68
65
| Method| Definition |
69
66
|------|-------|
@@ -72,15 +69,13 @@ This class sub-classes from the ```sfeTkIBus``` interface adding additional func
72
69
|**address**| Returns the address used by this I2C object |
73
70
74
71
> [!NOTE]
75
-
> The ```sfeTkII2C``` class manages the device address for the I2C bus. As such, each I2C device instantiates/uses an instance of the ```sfeTkII2C``` class.
72
+
> The ```sfTkII2C``` class manages the device address for the I2C bus. As such, each I2C device instantiates/uses an instance of the ```sfTkII2C``` class.
76
73
77
-
The class diagram for the ```sfeTkII2C``` interface is the following:
78
-
79
-
74
+
The details for the ```sfeTkII2C``` interface are [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_i_i2_c.html)
80
75
81
76
### The sfeTkISPI Implementation
82
77
83
-
This class sub-classes from the ```sfeTkIBus``` interface adding additional functionally focused on supporting an SPI implementation. This interface provides the additional functionality.
78
+
This class sub-classes from the ```sfTkIBus``` interface adding additional functionally focused on supporting an SPI implementation. This interface provides the additional functionality.
84
79
85
80
| Method| Definition |
86
81
|------|-------|
@@ -90,53 +85,47 @@ This class sub-classes from the ```sfeTkIBus``` interface adding additional func
90
85
> [!NOTE]
91
86
> The ```sfeTkISPI``` class manages CS Pin for the SPI bus. As such, each SPI device instantiates/uses an instance of the ```sfeTkISPI``` class.
92
87
93
-
The class diagram of these base class interfaces/implementation:
94
-
95
-
88
+
The details for the ```sfTkII2C``` interface are [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_i_s_p_i.html)
96
89
97
-
## sfeTkIBus - Arduino Implementation
90
+
## sfTkIBus - Arduino Implementation
98
91
99
-
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.
92
+
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.
100
93
101
94
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.
102
95
103
96
> [!IMPORTANT]
104
97
> The intent is that each user of an particular - a device in most cases - contains an instance of the specific bus class.
105
98
106
-
### The sfeTkArdI2C Class
99
+
### The sfTkArdI2C Class
107
100
108
-
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.
101
+
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.
109
102
110
-
The class diagram for the sfeTkArdI2C class:
103
+
Details for this class are located [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_ard_i2_c.html)
111
104
112
-
105
+
### The sfTkArdSPI Class
113
106
114
-
### The sfeTkArdSPI Class
107
+
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.
115
108
116
-
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.
109
+
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.
117
110
118
-
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.
111
+
Details for this class are located [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_ard_s_p_i.html)
119
112
120
-
The class diagram for the sfeTkArdSPI class:
113
+
## sfTkIBus Use
121
114
122
-
123
-
124
-
## sfeTkIBus Use
125
-
126
-
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.
115
+
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.
127
116
128
117
The general pattern for a device driver implementation that uses the SparkFun Toolkit is the following:
129
118
130
119
### Implement a Platform Independent Driver
131
120
132
-
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.
121
+
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.
133
122
134
123
> [!IMPORTANT]
135
-
> At this level, the driver is only using a ```sfeTkIBus``` interface, not any specific bus implementation.
124
+
> At this level, the driver is only using a ```sfTkIBus``` interface, not any specific bus implementation.
136
125
137
126
This driver has the following unique functionality:
138
127
139
-
1) A method to set the object that implements the ```sfeTkIBus``` interface object should use. Since
128
+
1) A method to set the object that implements the ```sfTkIBus``` interface object should use or sets the bus in a ```begin()``` method.
140
129
1) If the device supports identification capabilities, the driver provides this functionality.
141
130
142
131
#### Simple Example of an Independent Driver Implementation
>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.
273
+
278
274
## Summary
279
275
280
276
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:
0 commit comments