/
PLUGIN-GUIDE
241 lines (148 loc) · 10.9 KB
/
PLUGIN-GUIDE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
###
### INSTRUCTIONS FOR WRITING PLUG-INS FOR SENSOR FRAMEWORK
###
### 10.03.2011
###
##
## DISCLAIMER
##
These instructions apply to sensord-0.6.41 tagged in
http://meego.gitorious.org/meego-middleware/sensorfw/
Node interfaces in earlier version may differ.
##
## PLUG-INS
##
A plug-in for sensor framework can provide one (or more) of the following:
1) Device adaptor
2) Chain
3) Sensor
4) Filter
Device adaptors are responsible for interfacing the framework with data sources (generally device drivers). Adaptors are connected to chains or sensors, which contain a varying number of filters. Filters are used for calculating things from received samples. Sensors provide an interface to the resulting data for client applications, while chains are used as internal datasources for calculations shared by several sensors.
##
## WRITING A PLUG-IN
##
A plug-in by itself is responsible for very few things. It contains an adaptor/sensor/chain/filter (or several), and introduces them to SensorManager.
In addition, plug-ins may specify that they need another plug-in for functioning. E.g. orientationchain (provides device orientation calculations) requires accelerometeradaptor (provides data from accelerometer) to function.
Plugin dependencies are based on meta-names. Any plugin that requires, e.g. sampleplugin, will specify the dependency as 'sampleplugin'. In reality, with varying platforms the real plugin could be called sampleplugin-ascii, sampleplugin-superior, sampleplugin-inputdev, etc. See the section 'configuration files' for further details.
The naming convention is roughly:
<type_of_sensor><type_of_node>plugin-<specifier>
For adaptors, the specifier has been agreed to be related to the type of underlying driver interface. Thus, we could for example have:
accelerometeradaptorplugin-inputdev
Not all plugins currently adhere to these rules, and there is no clear rule on what to use for the <specifier> in cases other than adaptors.
See the commented codes in examples/*/*plugin.[h|cpp] for plug-in construction.
##
## WRITING AN ADAPTOR
##
A device adaptors is responsible for reading data from a source (usually a device driver interface) and pushing it into the processing chain in sensor framework.
The easiest way to create a new device adaptor is to extend SysfsAdaptor. The base class will then handle most things as long as the adaptor class itself provides the interface specific details.
What needs to be implemented:
* Select busypoll or interrupt based approach
* Create and name an outputbuffer(s).
* Function for reading and propagating data.
* Specify metadata
## Interrupt based or busypoll
Files can be monitored either in SelectMode or IntervalMode. SelectMode uses epoll() to monitor for interrupts, while IntervalMode just busypolls with specified delay. Using SelectMode is encouraged due to power saving reasons as long as driver interface provides interrupts.
In case the driver interface provides possibility to control hardware sampling frequency (implies SelectMode), interval() and setInterval() should be reimplemented to make use of the functionality.
In case the driver initiates hardware measurement when the interface is read, the IntervalMode handles everything related to interval handling already (except specifying the allowed values).
## Buffers
An adaptor can have any number of output buffers. Usually there is only one, but if an adaptor monitors several filehandles, or a filehandle provides more than one type of output, it might occasionally make sense to provide several output buffers. The buffers are named and are searched by listeners based on the name.
## Reading data from driver
SysfsAdaptor provides method addPath() for registering filehandles for listening. The path can also be set as constructor parameter. There can be any number of paths added, but mode of the adaptor will be the same for all of them, as well as the interval setting.
Whenever a registered filehandle has new data (signalled either by interrupt or by timeout), processSample(int pathId, int fd) gets called. Data can be read from fd, and pathId is used to separate which file the handle points to.
The function should be implemented to read data from fd and propagate it to listeners by writing to buffer.
## Metadata
Metadata for adaptors should represent the capabilities of the hardware and driver.
See section 'Metadata' at the end for generic details.
See examples/sampleadaptor/* for adaptor construction.
##
## WRITING A FILTER
##
A filter is responsible for processing data.
A new filter should be created by inheriting from QObject and Filter.
Then what need to be implemented are:
* In the header file
- Override the static factoryMethod() function and return a new instance of the filter
- Define a private filter() function which can be called anything, as long as it matches the name in class constructor
* Implement the filter() function in the source file and do the necessary filtering operation there
See examples/samplefilter/* for filter construction.
##
## WRITING A SENSOR
##
To create a new sensor, the following four steps should be done
* implementation of AbstractSensorChannel
* implementation of AbstractSensorChannelAdaptor
* implementation of AbstractSensorChannelInterface
* implementation of datatypes if sensor introduces new ones
AbstractSensorChannel is the end-node in the sensor graph.
AbstractSensorChannelAdaptor is the DBus interface of the sensor.
AbstractSensorChannelInterface is the client API for managing sensor through DBus and reading datastream from the socket.
See examples/samplesensor/* for sensor channel construction.
##
## WRITING A CHAIN
##
A chain is responsible for adapting filters into the data flow between an adaptor and a sensor.
A new chain is created by inheriting from AbstractChain.
Then what need to be implemented are:
* In the header file
- Override the static factoryMethod() function and return a new instance of the chain
* In the constructor
- Get an instance of SensorManager
- Get a pointer (refcounted) to the adaptor from sensor manager
- Create a reader for the adaptor
- Create and name output buffer
- Create a new bin and add elements into it with names
- Make connections between the elements in the Bin
- Connect the reader to the adaptor
- Setup metadata
* Do the cleaning up in the destructor
* Override start() function to start chain
* Override stop() function to stop chain
See examples/samplechain/* for chain construction.
##
## METADATA
##
Each node (adaptor/chain/sensor, not filters) should define metadata for itself. The following things are included:
* Description
* Interval range(s)
* Data range(s)
* Standby override sources (sort of metadata)
* Buffer size
* Buffer interval
## Description
Description should provide a human readable string that describes what is the output from the node.
## Interval range(s)
Interval ranges define the possible rates at which this node can provide output. They are given with min/max pairs, where any value between min and max is allowed. Resolution parameter is ignored.
Base class takes care of queuing and sorting the interval requests. Each node just needs to provide accepted ranges and set/get methods. Interval is specified as milliseconds between samples. The real used value will be the smallest value, ensuring that data is measured as fast as required. This behavior can be modified for a node, in case smallest == fastest does not apply for its sources.
For adaptors, the interval should represent the real capabilities of the hardware and driver.
Chains and sensors have more possibilities. In simplest case, they just delegate the interval for the source node by using setIntervalSource(). Then any requests are directly moved to the source node.
If a node has more than one source whose output affect the rate of the output for the node itself, setInterval() and interval() should be reimplemented to merge the requests into wanted rate.
## Data range(s)
Data ranges tell the possible min and max values and accuracy of measurements. Setting them closely resembles interval setting. The largest difference is that datarates are set with first-come-first-serve basis. The first requester of data range gets to keep the setting.
Currently there are no examples of sensors that would make use of multiple dataranges. For the sake of information, the rates should be described with introduceAvailableDataRange() or taken from a source with setIntervalSource().
## Standby override
Default behavior is to turn off all sensors when display goes blank.
Client can request a sensor to stay on in such a case by setting the standbyOverride -property to true. In practise, nodes specify which sources should stay on with addStandbyOverrideSource().
In adaptors, display blank will result in all filehandles being released. Setting the property to true prevents this from happening.
The property should be used with care and only when required in order to minimize power consumption.
## Buffer size and interval
Buffering means two things:
* sensor driver of chip may have internal buffer for storing data. In that case adaptor will implement setBufferSize() virtual function to configure the driver and implement getAvailableBufferSizes() virtual function to list available buffer sizes.
* if adaptor doesn't support buffering then sensorfw uses internal buffering to send data in bursts to the clients. These modes are mutually exclusive for single sensor.
Buffer interval can be used to configure the time limit for long we will wait for buffer to get full before flushing the content to the user. For driver/chip supported interval handling adaptor will implement setBufferInterval() virtual function to configure the driver and implement getAvailableBufferIntervals() virtual function to list available intervals.
By default buffering is disabled for client sessions.
##
## CONFIGURATION FILES
##
Sensorfw supports multiple configuration files. There are two locations:
(1) /etc/sensorfw/sensord.conf
(2) /etc/sensorfw/sensord.conf.d/
Any option set in (1) will override options set in any of the files in (2). Files in (2) are processed in alpha-numerical order, and later files can override settings from earlier files. Using double-digits as the beginning of the filename for clarity is encouraged.
Configuration files contain sections for different HW. These sections should connect plugin metanames (sampleadaptor) with the real plugin that should be used (sampleadaptor-inputdev). The configuration file also contains option 'deviceId', which specifies which section should be used. This will be removed once we have automatic detection of underlying HW in place.
The structure of the configuration files is likely to change in the future to contain better separation between different platforms.
##
## FURTHER INFORMATION
##
If you have questions that are not clear from the text and codes, please don't hesitate to ask us.
Cheerios,
Timo Rongas <ext-timo.2.rongas@nokia.com>
Shenghua Liu <ext-shenghua.1.liu@nokia.com>