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.
11
+
12
+
By using the SparkFun Toolkit, Arduino drivers achieve the following benefits:
13
+
14
+
* Use a well-tested and validated implementation
15
+
* Reduce development effort
16
+
* Implement functionality following a common structure
17
+
* Set the foundation for future enhancements - as the capabilities of the toolkit grow, these features become available with little to any implementation effort.
18
+
19
+
## Current Status
20
+
21
+
### December 2023
22
+
23
+
The SparkFun Toolkit is available as a *Beta* release, with the intent of testing and validation by SparkFun. The community are free to use this toolkit with the understanding that interfaces, types and class structures could change.
24
+
25
+
### Documentation
26
+
27
+
|||
28
+
|---|---|
29
+
|[Bus Implementation](docs/ar_ibus.md) | The architecture and use of the Tookkit Communication Bus Interface
Copy file name to clipboardExpand all lines: docs/ar_ibus.md
+61-20Lines changed: 61 additions & 20 deletions
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,26 @@
1
-
# Overview - Device Bus interface - sfeTkIBus
1
+
# Overview - Device Bus Interface - sfeTkIBus
2
2
3
3
One of the foundational capabilities of the SparkFun Toolkit is bus communication with devices. This is a common task almost all libraries implement using their own implementation for I2C, SPI or UART bus communication.
4
4
5
5
For bus communication, the SparkFun Toolkit is designed to provide a common implementation for use across all SparkFun libraries. Additionally, the bus architecture is modeled on a *driver* pattern, separating the individual bus setup/configuration from data communication, enabling a single device implementation to easily support a variety of device bus types.
6
6
7
-
The key goals set for the Bus implementation in the Toolkit include:
7
+
### The Bus Interface Design Pattern
8
+
9
+
This pattern allows an application to develop against the common bus interface without regard to the underlying bus type or implementation. This *plug-in* nature of this model enables core application reuse across a range of bus devices. What to use a different bus type? Just use a different driver.
10
+
11
+
This pattern is show in the following diagram:
12
+
13
+
14
+
15
+
This pattern extends across different platforms, allowing a common platform independent application core to utilize platform specific bus drivers.
16
+
17
+
18
+
19
+
The platform dependant drivers implement the core Bus Interface (IBus) for communication, with platform specific setup and management left to the underlying implementation. Since the application core only works with the Bus Interface, if implemented correctly, the same core works across different bus types and across different development environments.
20
+
21
+
## Goals
22
+
23
+
For the initial implementation the key goals set for the Bus implementation in the Toolkit include:
8
24
9
25
* Separate device setup from device communication
10
26
* Define a common bus interface for use across a variety of common device bus types
@@ -13,7 +29,7 @@ The key goals set for the Bus implementation in the Toolkit include:
13
29
14
30
## Architecture Overview
15
31
16
-
To meet the goals for this subsystem, the Flux framework follows a ***Driver Pattern***, defining a common interface for bus communication. Device drivers are designed around this interface, leaving bus configuration and implementation to platform specific implementation.
32
+
As outlined above, the SparkFun Toolkit follows a ***Driver Pattern***, defining a common interface for bus communication. Device drivers are designed around this interface, leaving bus configuration and implementation to platform specific implementation.
17
33
18
34
The key class to support this pattern are:
19
35
@@ -41,9 +57,13 @@ The interface methods:
41
57
> [!NOTE]
42
58
> 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.
43
59
60
+
The Inteface diagram for the ```sfeTkIBus``` is:
61
+
62
+
63
+
44
64
### The sfeTkII2C Implementation
45
65
46
-
This class sub-classes from the ```sfeTkIBus``` interface adding additional functionally focused on supporting an I2C implementation. This interface provides the additional functionality.
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.
47
67
48
68
| Method| Definition |
49
69
|------|-------|
@@ -54,6 +74,10 @@ This class sub-classes from the ```sfeTkIBus``` interface adding additional func
54
74
> [!NOTE]
55
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.
56
76
77
+
The class diagram for the ```sfeTkII2C``` interface is the following:
78
+
79
+
80
+
57
81
### The sfeTkISPI Implementation
58
82
59
83
This class sub-classes from the ```sfeTkIBus``` interface adding additional functionally focused on supporting an SPI implementation. This interface provides the additional functionality.
@@ -68,31 +92,35 @@ This class sub-classes from the ```sfeTkIBus``` interface adding additional func
68
92
69
93
The class diagram of these base class interfaces/implementation:
70
94
71
-
95
+
72
96
73
-
## sfeTkIIBus - Arduino Implementation
97
+
## sfeTkIBus - Arduino Implementation
74
98
75
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.
76
100
77
101
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.
78
102
79
103
> [!IMPORTANT]
80
-
> The intent is that each user of an particular bus - a device in most cases - contains an instance of the specific bus object.
104
+
> The intent is that each user of an particular - a device in most cases - contains an instance of the specific bus class.
81
105
82
-
The class diagram for the Arduino implementation is as follows:
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.
85
109
86
-
### The sfeTkArdI2C Class
110
+
The class diagram for the sfeTkArdI2C class:
87
111
88
-
This class provides the Arduino implementation of I2C in the SparkFun Toolkit. It implements the methods of the ```sfeTkIIBus``` and ```sfeTkII2C``` interfaces, as well as manages any Arduino specific state.
112
+
89
113
90
114
### The sfeTkArdSPI Class
91
115
92
-
This class provides the Arduino implementation of SPI in the SparkFun Toolkit. It implements the methods of the ```sfeTkIIBus``` and ```sfeTkISPI``` interfaces, as well as manages any Arduino specific state for the SPI bus - namely the SPISettings class.
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.
93
117
94
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.
95
119
120
+
The class diagram for the sfeTkArdSPI class:
121
+
122
+
123
+
96
124
## sfeTkIBus Use
97
125
98
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.
@@ -101,7 +129,7 @@ The general pattern for a device driver implementation that uses the SparkFun To
101
129
102
130
### Implement a Platform Independent Driver
103
131
104
-
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 ```sfeTkIIBus``` interface.
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.
105
133
106
134
>[!IMPORTANT]
107
135
> At this level, the driver is only using a ```sfeTkIBus``` interface, not any specific bus implementation.
@@ -111,7 +139,10 @@ This driver has the following unique functionality:
111
139
1) A method to set the object that implements the ```sfeTkIBus``` interface object should use. Since
112
140
1) If the device supports identification capabilities, the driver provides this functionality.
113
141
114
-
#### SImple Example of an Independent Driver Implementation
142
+
#### Simple Example of an Independent Driver Implementation
143
+
144
+
>[!NOTE]
145
+
> This code is **pseudo-code**, used to demonstrate the key concepts of the implementation pattern.
115
146
116
147
This implementation would take the following form:
if (!_theSPIBus.init(SPI, spiSettings, MY_DEFAULT_CS, true))
254
+
if (_theSPIBus.init(SPI, spiSettings, MY_DEFAULT_CS, true) != kSTkErrOk)
223
255
return false;
224
256
setCommunicationBus(&_theSPIBus);
225
257
@@ -235,3 +267,12 @@ private:
235
267
sfeTkArdSPI _theSPIBus;
236
268
};
237
269
```
270
+
271
+
## Summary
272
+
273
+
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:
274
+
275
+
* Separate device setup from device communication
276
+
* Define a common bus interface for use across a variety of common device bus types
277
+
* Deliver support for both SPI and I2C bus types initially, focusing on Arduino
278
+
* Structure the bus/toolkit implementation such that it's platform independent
0 commit comments