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
Copy file name to clipboardExpand all lines: docs/ar_ibus.md
+65-92Lines changed: 65 additions & 92 deletions
Original file line number
Diff line number
Diff line change
@@ -8,29 +8,6 @@ For bus communication, the SparkFun Toolkit is designed to provide a common impl
8
8
9
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
10
11
-
```mermaid
12
-
---
13
-
title: Design Pattern Bus Interface
14
-
---
15
-
classDiagram
16
-
class MyApplication
17
-
18
-
class IBus
19
-
<<Interface>> IBus
20
-
IBus : writeData(...)
21
-
IBus : readRegister(...)
22
-
IBus : writeRegister(...)
23
-
24
-
MyApplication --> IBus
25
-
26
-
IBus <|-- IBusType
27
-
28
-
note for MyApplication "Application/library that <br>uses the IBus Interface"
29
-
note for IBus "Defines the bus interface"
30
-
note for IBusType "Specific implementation type <br> methods [I2C, SPI, UART,...]"
31
-
32
-
```
33
-
34
11
This pattern is show in the following diagram:
35
12
36
13
@@ -58,35 +35,32 @@ The key class to support this pattern are:
58
35
59
36
|||
60
37
|------|-------|
61
-
|**sfeTkIBus**| A virtual C++ class that device the bus ```sfeTkIBus``` interface |
62
-
|**sfeTkII2C**| Sub-class of the ```sfeTkIIBus``` interface, it provides an interface for I2C devices|
63
-
|**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 |
64
41
65
-
### The sfeTkIBus Interface
42
+
### The sfTkIBus Interface
66
43
67
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.
68
45
69
-
The interface methods:
46
+
The bus implements methods that perform the following
70
47
71
48
| Method| Definition |
72
49
|------|-------|
73
-
|**writeRegisterByte**| Write a byte of data to a particular register of a device |
74
-
|**writeRegisterWord**| Write a word of data to a particular register of a device |
75
-
|**writeRegisterRegion**| Write an array of data to a particular register of a device|
76
-
|**readRegisterByte**| Read a byte of data from a particular register of a device |
77
-
|**readRegisterWord**| Read a word of data from a particular register of a device |
78
-
|**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.
79
55
80
56
> [!NOTE]
81
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.
82
58
83
-
The Inteface diagram for the ```sfeTkIBus``` is:
84
-
85
-
59
+
Specific details for this class are detailed [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_i_bus.html)
86
60
87
-
### The sfeTkII2C Implementation
61
+
### The sfTkII2C Implementation
88
62
89
-
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.
90
64
91
65
| Method| Definition |
92
66
|------|-------|
@@ -95,15 +69,13 @@ This class sub-classes from the ```sfeTkIBus``` interface adding additional func
95
69
|**address**| Returns the address used by this I2C object |
96
70
97
71
> [!NOTE]
98
-
> 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.
99
73
100
-
The class diagram for the ```sfeTkII2C``` interface is the following:
101
-
102
-
74
+
The details for the ```sfeTkII2C``` interface are [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_i_i2_c.html)
103
75
104
76
### The sfeTkISPI Implementation
105
77
106
-
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.
107
79
108
80
| Method| Definition |
109
81
|------|-------|
@@ -113,53 +85,47 @@ This class sub-classes from the ```sfeTkIBus``` interface adding additional func
113
85
> [!NOTE]
114
86
> The ```sfeTkISPI``` class manages CS Pin for the SPI bus. As such, each SPI device instantiates/uses an instance of the ```sfeTkISPI``` class.
115
87
116
-
The class diagram of these base class interfaces/implementation:
117
-
118
-
88
+
The details for the ```sfTkII2C``` interface are [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_i_s_p_i.html)
119
89
120
-
## sfeTkIBus - Arduino Implementation
90
+
## sfTkIBus - Arduino Implementation
121
91
122
-
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.
123
93
124
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.
125
95
126
96
> [!IMPORTANT]
127
97
> The intent is that each user of an particular - a device in most cases - contains an instance of the specific bus class.
128
98
129
-
### The sfeTkArdI2C Class
130
-
131
-
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.
99
+
### The sfTkArdI2C Class
132
100
133
-
The class diagram for the sfeTkArdI2C class:
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.
134
102
135
-
103
+
Details for this class are located [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_ard_i2_c.html)
136
104
137
-
### The sfeTkArdSPI Class
105
+
### The sfTkArdSPI Class
138
106
139
-
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.
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.
140
108
141
-
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.
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.
142
110
143
-
The class diagram for the sfeTkArdSPI class:
111
+
Details for this class are located [here](https://docs.sparkfun.com/SparkFun_Toolkit/classsf_tk_ard_s_p_i.html)
144
112
145
-
113
+
## sfTkIBus Use
146
114
147
-
## sfeTkIBus Use
148
-
149
-
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.
150
116
151
117
The general pattern for a device driver implementation that uses the SparkFun Toolkit is the following:
152
118
153
119
### Implement a Platform Independent Driver
154
120
155
-
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.
156
122
157
123
> [!IMPORTANT]
158
-
> 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.
159
125
160
126
This driver has the following unique functionality:
161
127
162
-
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.
163
129
1) If the device supports identification capabilities, the driver provides this functionality.
164
130
165
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
+
301
274
## Summary
302
275
303
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