1// Copyright (C) 2016 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qmagnetometer.h"
5#include "qmagnetometer_p.h"
6
7QT_BEGIN_NAMESPACE
8
9IMPLEMENT_READING(QMagnetometerReading)
10
11/*!
12 \class QMagnetometerReading
13 \ingroup sensors_reading
14 \inmodule QtSensors
15 \since 5.1
16
17 \brief The QMagnetometerReading class represents one reading from the
18 magnetometer.
19
20 \section2 QMagnetometerReading Units
21 The magnetometer returns magnetic flux density values along 3 axes.
22 The scale of the values is teslas. The axes are arranged as follows.
23
24 \image sensors-coordinates2.jpg
25
26 The magnetometer can report on either raw magnetic flux values or geomagnetic flux values.
27 By default it returns raw magnetic flux values. The QMagnetometer::returnGeoValues property
28 must be set to return geomagnetic flux values.
29
30 The primary difference between raw and geomagnetic values is that extra processing
31 is done to eliminate local magnetic interference from the geomagnetic values so they
32 represent only the effect of the Earth's magnetic field. This process is not perfect
33 and the accuracy of each reading may change.
34
35 The image below shows the difference between geomagnetic (on the left) and raw (on the right)
36 readings for a phone that is being subjected to magnetic interference.
37
38 \image sensors-geo-vs-raw-magnetism.jpg
39
40 The accuracy of each reading is measured as a number from 0 to 1.
41 A value of 1 is the highest level that the device can support and 0 is
42 the worst.
43
44 \section2 Calibration
45 If the device is reporting low accuracy, then calibration might be needed before acceptable measurements
46 can be provided.
47 Basic calibration can usually be done by either rotating your device in a figure of eight, or by
48 rotating the device along each of its three axes. For more information, check your device's
49 documentation on how to calibrate the magnetic sensor.
50*/
51
52/*!
53 \property QMagnetometerReading::x
54 \brief the raw magnetic flux density on the X axis.
55
56 Measured as teslas.
57 \sa {QMagnetometerReading Units}
58*/
59
60qreal QMagnetometerReading::x() const
61{
62 return d->x;
63}
64
65/*!
66 Sets the raw magnetic flux density on the X axis to \a x.
67*/
68void QMagnetometerReading::setX(qreal x)
69{
70 d->x = x;
71}
72
73/*!
74 \property QMagnetometerReading::y
75 \brief the raw magnetic flux density on the Y axis.
76
77 Measured as teslas.
78 \sa {QMagnetometerReading Units}
79*/
80
81qreal QMagnetometerReading::y() const
82{
83 return d->y;
84}
85
86/*!
87 Sets the raw magnetic flux density on the Y axis to \a y.
88*/
89void QMagnetometerReading::setY(qreal y)
90{
91 d->y = y;
92}
93
94/*!
95 \property QMagnetometerReading::z
96 \brief the raw magnetic flux density on the Z axis.
97
98 Measured as teslas.
99 \sa {QMagnetometerReading Units}
100*/
101
102qreal QMagnetometerReading::z() const
103{
104 return d->z;
105}
106
107/*!
108 Sets the raw magnetic flux density on the Z axis to \a z.
109*/
110void QMagnetometerReading::setZ(qreal z)
111{
112 d->z = z;
113}
114
115/*!
116 \property QMagnetometerReading::calibrationLevel
117 \brief the accuracy of the reading.
118
119 Measured as a value from 0 to 1 with higher values being better.
120
121 Note that this only changes when measuring geomagnetic flux density.
122 Raw magnetic flux readings will always have a value of 1.
123 \sa {QMagnetometerReading Units}, {Calibration}
124*/
125
126qreal QMagnetometerReading::calibrationLevel() const
127{
128 return d->calibrationLevel;
129}
130
131/*!
132 Sets the accuracy of the reading to \a calibrationLevel.
133*/
134void QMagnetometerReading::setCalibrationLevel(qreal calibrationLevel)
135{
136 d->calibrationLevel = calibrationLevel;
137}
138
139// =====================================================================
140
141/*!
142 \class QMagnetometerFilter
143 \ingroup sensors_filter
144 \inmodule QtSensors
145 \since 5.1
146
147 \brief The QMagnetometerFilter class is a convenience wrapper around QSensorFilter.
148
149 The only difference is that the filter() method features a pointer to QMagnetometerReading
150 instead of QSensorReading.
151*/
152
153/*!
154 \fn QMagnetometerFilter::filter(QMagnetometerReading *reading)
155
156 Called when \a reading changes. Returns false to prevent the reading from propagating.
157
158 \sa QSensorFilter::filter()
159*/
160
161bool QMagnetometerFilter::filter(QSensorReading *reading)
162{
163 return filter(reading: static_cast<QMagnetometerReading*>(reading));
164}
165
166char const * const QMagnetometer::sensorType("QMagnetometer");
167
168/*!
169 \class QMagnetometer
170 \ingroup sensors_type
171 \inmodule QtSensors
172 \since 5.1
173
174 \brief The QMagnetometer class is a convenience wrapper around QSensor.
175
176 The only behavioural difference is that this class sets the type properly.
177
178 This class also features a reading() function that returns a QMagnetometerReading instead of a QSensorReading.
179
180 For details about how the sensor works, see \l QMagnetometerReading.
181
182 \sa QMagnetometerReading
183*/
184
185/*!
186 Construct the sensor as a child of \a parent.
187*/
188QMagnetometer::QMagnetometer(QObject *parent)
189 : QSensor(QMagnetometer::sensorType, *new QMagnetometerPrivate, parent)
190{
191}
192
193/*!
194 Destroy the sensor. Stops the sensor if it has not already been stopped.
195*/
196QMagnetometer::~QMagnetometer()
197{
198}
199
200/*!
201 \fn QMagnetometer::reading() const
202
203 Returns the reading class for this sensor.
204
205 \sa QSensor::reading()
206*/
207
208QMagnetometerReading *QMagnetometer::reading() const
209{
210 return static_cast<QMagnetometerReading*>(QSensor::reading());
211}
212
213/*!
214 \property QMagnetometer::returnGeoValues
215 \brief a value indicating if geomagnetic values should be returned.
216
217 Set to true to return geomagnetic flux density.
218 Set to false (the default) to return raw magnetic flux density.
219
220 The property must be set before calling start().
221*/
222
223bool QMagnetometer::returnGeoValues() const
224{
225 Q_D(const QMagnetometer);
226 return d->returnGeoValues;
227}
228
229void QMagnetometer::setReturnGeoValues(bool returnGeoValues)
230{
231 Q_D(QMagnetometer);
232 if (d->returnGeoValues != returnGeoValues) {
233 d->returnGeoValues = returnGeoValues;
234 emit returnGeoValuesChanged(returnGeoValues);
235 }
236}
237
238QT_END_NAMESPACE
239
240#include "moc_qmagnetometer.cpp"
241

source code of qtsensors/src/sensors/qmagnetometer.cpp