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
|
/****************************************************************************
**
** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtsensors-cpp.html
\title QtSensors C++ API
\brief Information about the QtSensors C++ API
\tableofcontents
\section1 Sensor Types
On a device there can be many types of sensors. Not all of the types that the QtSensors API
supports may be available. There may also be types available that are not defined in the
QtSensors API. The types of sensors available on a device is found using the
\l QSensor::sensorTypes() function.
For a list of built-in sensor types, see the \l{Sensor Classes} section below.
\section1 Common Conventions
Unless otherwise specified, QtSensors uses the
\l{http://en.wikipedia.org/wiki/Cartesian_coordinate_system}{Right Hand Cartesian coordinate system}.
\image sensors-coordinates.jpg
To allow for measurements in all 6 directions, negative values are used.
\image sensors-coordinates2.jpg
Where rotation around an axis is used, the rotation shall be expressed as a Right Hand rotation.
\image sensors-coordinates3.jpg
In general, sensor data is oriented to the top of the device. If values are to be displayed on
the screen the values may need to be transformed so that they match the user interface orientation. A sensor
may define its data as being oriented to the UI. This will be noted in the documentation for the
sensor.
\image sensors-sides2.jpg
\section1 Using a Sensor
The life cycle of a QSensor is typically:
\list
\o Create an instance of QSensor or one of its sub-classes on the stack or heap.
\o Setup as required by the application.
\o Start receiving values.
\o Sensor data is used by the application.
\o Stop receiving values.
\endlist
Here is an example of creating a sensor on the heap and on the stack.
\snippet snippets/sensors/creating.cpp Creating a sensor
\section1 Accessing sensor data in a generic fashion
The preferred way to deal with sensor data is via the \l{Reading Classes}.
However, sometimes this may not be possible. For example, you may be deploying
an application to a device that has a new sensor type but no C++ header
describing the reading class is available.
Thanks to Qt's property system you can still access the sensor data. You need to know
3 pieces of information in order to do this:
\list
\o The sensor type.
\o The property name or index.
\o The property type or a comparable type.
\endlist
For example, here is an example of how you can access a property of the accelerometer.
This code does not require any compile-time links to \l QAccelerometer or
\l QAccelerometerReading.
\snippet snippets/sensors/start.cpp Starting a sensor
You can discover all of this information at runtime too. The sensor_explorer example
shows you information about available sensors.
\section1 Front end, back end
The QtSensors API has a front end, for application developers to use and a back end,
where device implementors write code to access their hardware. As an application
developer you do not need to access the back end though it may be useful to understand
how it works.
Commands from the application are delivered through QSensor and then down to the
device plugin. Data comes back through the QSensorReading class.
\image sensors-overview.png
More information about the back end can be found in \l{QtSensors Backend}.
\section1 Main Classes
The primary classes that make up the QtSensors API.
\annotatedlist sensors_main
\section1 Reading Classes
The best way to access sensor data is via one of these classes.
\annotatedlist sensors_reading
\section1 Sensor Classes
These classes provide convenience wrappers that reduce the need for casting.
Each of these classes represents a sensor type that the QtSensors API knows
about. Note that additional types may be made available at run-time. See
\l{Sensor Types} for more information.
\annotatedlist sensors_type
\section1 Filter Classes
As with the sensor classes, these provide convenience wrappers that reduce
the need for casting.
\annotatedlist sensors_filter
*/
|
