|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-8B4CC1A0-1A39-4AF0-826B-8DDB9A837A27" xml:lang="en"><title>Sensors |
|
13 Framework Overview</title><shortdesc>The Sensors Framework consists of a sensor server and channel based |
|
14 client APIs for supporting an extensible set of sensor hardware. The sensor |
|
15 server defines a plug-in interface for adding sensor plug-ins for any type |
|
16 of sensor hardware. The channel APIs enable client applications to interact |
|
17 with the sensor hardware.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
18 <section id="GUID-AB7AB8C8-DEB2-445C-A216-1FE142592C7D-GENID-1-8-1-9-1-1-6-1-4-1-3-1-3-1"><title>Key Concepts |
|
19 and Terms</title><dl> |
|
20 <dlentry> |
|
21 <dt>Sensor Channel</dt> |
|
22 <dd><p>The sensor channel forms a medium of interaction between the sensor |
|
23 hardware and client applications. </p><p>The data from one physical sensor |
|
24 can be mapped to several channels. For example, the Sensor System handling |
|
25 an acceleration sensor can provide raw data on one channel and preprocessed |
|
26 tap events on another.</p></dd> |
|
27 </dlentry> |
|
28 <dlentry> |
|
29 <dt>Channel Properties</dt> |
|
30 <dd><p>Channel properties contain properties of a specific channel, such as |
|
31 data rate, availability, connection type and so on.</p></dd> |
|
32 </dlentry> |
|
33 <dlentry> |
|
34 <dt>Data item</dt> |
|
35 <dd><p>A data item is a discrete data package that contains sensor data or |
|
36 an event parsed from sensor data and related values, such as timestamp. Each |
|
37 channel provides a single type of data item only. </p></dd> |
|
38 </dlentry> |
|
39 <dlentry> |
|
40 <dt>Channel condition</dt> |
|
41 <dd><p> A value-operator pair targeting a single value inside a data item, |
|
42 indicated by an index. A condition is met when the channel data value in comparison |
|
43 with the condition value using condition operator is true. The conditions |
|
44 are gathered in condition sets.</p><p>There are two condition types: single |
|
45 limit conditions and range conditions. Range conditions are formed from two |
|
46 separate conditions, representing the lower and upper limits of the range.</p></dd> |
|
47 </dlentry> |
|
48 <dlentry> |
|
49 <dt>Channel Condition Set</dt> |
|
50 <dd><p>A set of channel conditions. Following are the two types of condition |
|
51 sets: <ul> |
|
52 <li><p>AND condition set: An AND condition is met only if a data value satisfies |
|
53 all conditions in the set.</p></li> |
|
54 <li><p>OR condition: An OR condition is met if a data value satisfies even |
|
55 one single condition in the set.</p></li> |
|
56 </ul></p></dd> |
|
57 </dlentry> |
|
58 </dl> </section> |
|
59 <section id="GUID-AB7AB8C8-DEB2-445C-A216-1FE142592C7D-GENID-1-8-1-9-1-1-6-1-4-1-3-1-3-2"><title>Description</title><p>The |
|
60 sensor server provides a plug-in interface (Sensor Definitions APIs) that |
|
61 enables platform developers to create sensor plug-ins for required sensors |
|
62 hardware. The sensor plug-ins enable the interaction between a client application |
|
63 and the sensor hardware through sensor channels. The Sensor Channel APIs provides |
|
64 access to each sensor channel.</p><p>One physical sensor can |
|
65 provide several different types of data. For example, the physical magnetometer |
|
66 can provide data for the Magnetometer channel and the Magnetic North channel. |
|
67 Each sensor channel has its own sensor channel data definition in the Sensor |
|
68 Definitions APIs that defines the format of the data package supplied by the |
|
69 sensor channel. The data definition can also define properties for each data |
|
70 item in the data package.</p><p>The sensor server facilitates the transfer |
|
71 of data from one sensor hardware to multiple clients simultaneously. It also |
|
72 resolves any contention between client applications for opening channels or |
|
73 configuring a sensor device.</p> </section> |
|
74 <section id="GUID-AB7AB8C8-DEB2-445C-A216-1FE142592C7D-GENID-1-8-1-9-1-1-6-1-4-1-3-1-3-3"> <title>APIs</title> |
|
75 <table id="GUID-4D61C176-6A42-4F06-96A2-950F6ACD1C25"> |
|
76 <tgroup cols="2"><colspec colname="col1" colwidth="0.44*"/><colspec colname="col2" colwidth="1.56*"/> |
|
77 <thead> |
|
78 <row> |
|
79 <entry>API</entry> |
|
80 <entry>Description</entry> |
|
81 </row> |
|
82 </thead> |
|
83 <tbody> |
|
84 <row> |
|
85 <entry>CSensrvChannelFinder</entry> |
|
86 <entry>The channel finder provides functions to search and find sensor channels |
|
87 that are supported by the Symbian device. </entry> |
|
88 </row> |
|
89 <row> |
|
90 <entry>CSensrvChannel</entry> |
|
91 <entry>The sensor channel provides functions to open and control a sensor |
|
92 channel.</entry> |
|
93 </row> |
|
94 <row> |
|
95 <entry>CSensrvChannelCondition</entry> |
|
96 <entry>The sensor channel provides functions for notifying when a specific |
|
97 condition is met.</entry> |
|
98 </row> |
|
99 <row> |
|
100 |
|
101 <entry>CSensrvChannelConditionSet</entry> |
|
102 <entry>The sensor channel condition set provides functions for adding one |
|
103 or more channel conditions to a condition set.</entry> |
|
104 </row> |
|
105 <row> |
|
106 <entry>MSensrvChannelListener</entry> |
|
107 <entry>The sensor channel listener is a callback interface that tracks for |
|
108 new channels installed on the Symbian device.</entry> |
|
109 </row> |
|
110 <row> |
|
111 <entry>MSensrvChannelConditionListener</entry> |
|
112 <entry>The sensor channel condition listener is a callback interface that |
|
113 notifies the clients when a condition-set is satisfied.</entry> |
|
114 </row> |
|
115 <row> |
|
116 <entry>MSensrvDataListener</entry> |
|
117 <entry>The sensor data listener is a callback interface that notifies the |
|
118 clients when the sensor data is available.</entry> |
|
119 </row> |
|
120 <row> |
|
121 <entry>MSensrvPropertyListener</entry> |
|
122 <entry>The sensor property listener is a callback interface that notifies |
|
123 the client when a channel property changes.</entry> |
|
124 </row> |
|
125 </tbody> |
|
126 </tgroup> |
|
127 </table> <fig id="GUID-90C26AB4-F003-444C-B9AF-422BB816557C"> |
|
128 <image href="GUID-600DCD27-ADC0-40D7-B061-1D44238363BA_d0e134835_href.png" placement="inline"/> |
|
129 </fig><p>A physical sensor can supply data to several sensor channels (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCSensrvChannel.html" format="application/java-archive"><codeph>CSensrvChannel</codeph></xref>) |
|
130 . A sensor channel provides data to an application in a channel-specific data |
|
131 format (for example, <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/Sensor_definitions_APIClassesIndexPage.html" format="application/java-archive"><codeph>TSensrvXyzData</codeph></xref>) through a callback to the <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classMSensrvDataListener.html#7ddce5c72a9d429ddb9e69f9e3a0a9b6" format="application/java-archive"><codeph>MSensrvDataListener::DataReceived()</codeph></xref> interface. A |
|
132 sensor channel has a single channel info item (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classTSensrvChannelInfo.html" format="application/java-archive"><codeph>TSensrvChannelInfo</codeph></xref>) that describes the channel in general. A sensor channel has multiple |
|
133 property items (<xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classTSensrvProperty.html" format="application/java-archive"><codeph>TSensrvProperty</codeph></xref>) |
|
134 that describe the channel in more detail. Each property item is referenced |
|
135 by a property id and an index.</p> </section> |
|
136 <section id="GUID-7D9F56F7-0301-4FCF-8D88-1DDC6688E9CB"><title>Typical Uses</title><p>Using |
|
137 the sensor channel APIs, you can perform the following operations:<ul> |
|
138 <li><p>List all the sensor channels that are available for a particular sensor |
|
139 type. For details, see <xref href="GUID-44FDDA27-1A5D-42B5-8DE0-D9E88EB75C93.dita">Querying |
|
140 for Sensor Channels</xref></p></li> |
|
141 <li><p>Receive and control periodic sensor data. </p>For details, see <xref href="GUID-BA0D9DA9-3B54-4964-A4D6-9ADA4DEB7231.dita">Receiving Data from Sensors</xref></li> |
|
142 <li><p>Configure sensor channels. </p> For details, see <xref href="GUID-BA0D9DA9-3B54-4964-A4D6-9ADA4DEB7231.dita">Retrieving |
|
143 Channel Properties</xref> and <xref href="GUID-0CA7F22E-59D7-4D65-9D6C-735E4E0F0454.dita">Setting |
|
144 Channel Properties</xref></li> |
|
145 <li><p>Receive notifications about sensor channel additions and removal. For |
|
146 details, see <xref href="GUID-09E44FE5-6BEE-49FF-8BBF-CBB3C066EE10.dita">Receiving |
|
147 Notifications about Channel Changes</xref></p></li> |
|
148 <li><p>Configure a sensor channel to support conditional listening. This means |
|
149 that you can configure it to notify you when the data on the channel matches |
|
150 some particular values, or exceeds specified boundaries. For details, see <xref href="GUID-60EE22AA-402D-4FC2-9AD1-B3AEF822E8DC.dita">Receiving Channel Data based |
|
151 on Conditions</xref>.</p></li> |
|
152 </ul></p></section> |
|
153 </conbody><related-links> |
|
154 <link href="GUID-4B709839-8EEF-4AD2-9868-9AF0176B1E5B.dita"><linktext>Using Sensor |
|
155 Channels APIs</linktext></link> |
|
156 <link href="GUID-64AC6F53-A9A5-46FD-BCC6-4A9BD8D4DB5C.dita"><linktext>Compensating |
|
157 Sensor Data for Display Orientation </linktext></link> |
|
158 </related-links></concept> |