Line data Source code
1 : // SPDX-FileCopyrightText: 2022-2025 Paul Colby <git@colby.id.au>
2 : // SPDX-License-Identifier: LGPL-3.0-or-later
3 :
4 : /*!
5 : * \file
6 : * Defines the MultimeterService and MultimeterServicePrivate classes.
7 : */
8 :
9 : #include <qtpokit/multimeterservice.h>
10 : #include "multimeterservice_p.h"
11 : #include "pokitproducts_p.h"
12 : #include "../stringliterals_p.h"
13 :
14 : #include <QDataStream>
15 : #include <QIODevice>
16 : #include <QtEndian>
17 :
18 : QTPOKIT_BEGIN_NAMESPACE
19 : DOKIT_USE_STRINGLITERALS
20 :
21 : /*!
22 : * \class MultimeterService
23 : *
24 : * The MultimeterService class accesses the `Multimeter` service of Pokit devices.
25 : */
26 :
27 : /*!
28 : * \cond internal
29 : * \enum MultimeterService::Mode
30 : * \pokitApi The following enumeration values are as-yet undocumented by Pokit Innovations.
31 : * [\@pcolby](https://github.com/pcolby) reverse-engineered them as part of the
32 : * [dokit](https://github.com/pcolby/dokit) project.
33 : * * Mode::Capacitance
34 : * * Mode::ExternalTemperature
35 : * \endcond
36 : */
37 :
38 : /// Returns \a mode as a user-friendly string.
39 8000 : QString MultimeterService::toString(const Mode &mode)
40 3024 : {
41 11024 : switch (mode) {
42 1920 : case Mode::Idle: return tr("Idle");
43 880 : case Mode::DcVoltage: return tr("DC voltage");
44 880 : case Mode::AcVoltage: return tr("AC voltage");
45 880 : case Mode::DcCurrent: return tr("DC current");
46 880 : case Mode::AcCurrent: return tr("AC current");
47 880 : case Mode::Resistance: return tr("Resistance");
48 880 : case Mode::Diode: return tr("Diode");
49 1608 : case Mode::Continuity: return tr("Continuity");
50 880 : case Mode::Temperature: return tr("Temperature");
51 880 : case Mode::Capacitance: return tr("Capacitance");
52 152 : case Mode::ExternalTemperature: return tr("External temperature");
53 3024 : }
54 144 : return QString();
55 3024 : }
56 :
57 : /// Returns \a range as a user-friendly string, or a null QString if \a mode has no ranges.
58 7600 : QString MultimeterService::toString(const PokitProduct product, const quint8 range, const Mode mode)
59 3240 : {
60 10840 : switch (mode) {
61 504 : case Mode::Idle:
62 504 : break;
63 1424 : case Mode::DcVoltage:
64 576 : case Mode::AcVoltage:
65 1856 : return VoltageRange::toString(product, range);
66 1712 : case Mode::DcCurrent:
67 576 : case Mode::AcCurrent:
68 1856 : return CurrentRange::toString(product, range);
69 1232 : case Mode::Resistance:
70 1232 : return ResistanceRange::toString(product, range);
71 144 : case Mode::Diode:
72 432 : case Mode::Continuity:
73 720 : case Mode::Temperature:
74 720 : break;
75 928 : case Mode::Capacitance:
76 928 : return CapacitanceRange::toString(product, range);
77 144 : case Mode::ExternalTemperature:
78 144 : break;
79 3240 : }
80 1368 : return QString();
81 3240 : }
82 :
83 : /// Returns \a range as a user-friendly string, or a null QString if \a mode has no ranges.
84 6800 : QString MultimeterService::toString(const quint8 range, const Mode mode) const
85 2520 : {
86 9320 : return toString(*pokitProduct(), range, mode);
87 2520 : }
88 :
89 : /*!
90 : * Returns the maximum value for \a range, or 0 if \a range is not a known value for \a product's \a mode.
91 : */
92 1600 : quint32 MultimeterService::maxValue(const PokitProduct product, const quint8 range, const Mode mode)
93 1440 : {
94 3040 : switch (mode) {
95 144 : case Mode::Idle:
96 144 : break;
97 320 : case Mode::DcVoltage:
98 288 : case Mode::AcVoltage:
99 608 : return VoltageRange::maxValue(product, range);
100 608 : case Mode::DcCurrent:
101 288 : case Mode::AcCurrent:
102 608 : return CurrentRange::maxValue(product, range);
103 608 : case Mode::Resistance:
104 608 : return ResistanceRange::maxValue(product, range);
105 0 : case Mode::Diode:
106 0 : case Mode::Continuity:
107 144 : case Mode::Temperature:
108 144 : break;
109 304 : case Mode::Capacitance:
110 304 : return CapacitanceRange::maxValue(product, range);
111 144 : case Mode::ExternalTemperature:
112 144 : break;
113 1440 : }
114 432 : return 0;
115 1440 : }
116 :
117 : /*!
118 : * Returns the maximum value for \a range, or 0 \a range is not a known value for the current \a product's \a mode.
119 : */
120 800 : quint32 MultimeterService::maxValue(const quint8 range, const Mode mode) const
121 720 : {
122 1520 : return maxValue(*pokitProduct(), range, mode);
123 720 : }
124 :
125 : /*!
126 : * Constructs a new Pokit service with \a parent.
127 : */
128 5840 : MultimeterService::MultimeterService(QLowEnergyController * const controller, QObject * parent)
129 8584 : : AbstractPokitService(new MultimeterServicePrivate(controller, this), parent)
130 3240 : {
131 :
132 9080 : }
133 :
134 : /*!
135 : * \cond internal
136 : * Constructs a new Pokit service with \a parent, and private implementation \a d.
137 : */
138 0 : MultimeterService::MultimeterService(
139 0 : MultimeterServicePrivate * const d, QObject * const parent)
140 0 : : AbstractPokitService(d, parent)
141 0 : {
142 :
143 0 : }
144 : /// \endcond
145 :
146 80 : bool MultimeterService::readCharacteristics()
147 72 : {
148 152 : return readReadingCharacteristic();
149 72 : }
150 :
151 : /*!
152 : * Read the `Multimeter` service's `Reading` characteristic.
153 : *
154 : * Returns `true` is the read request is successfully queued, `false` otherwise (ie if the
155 : * underlying controller it not yet connected to the Pokit device, or the device's services have
156 : * not yet been discovered).
157 : *
158 : * Emits readingRead() if/when the characteristic has been read successfully.
159 : */
160 125 : bool MultimeterService::readReadingCharacteristic()
161 144 : {
162 144 : Q_D(MultimeterService);
163 304 : return d->readCharacteristic(CharacteristicUuids::reading);
164 144 : }
165 :
166 : /*!
167 : * Configures the Pokit device's multimeter mode.
168 : *
169 : * Returns `true` if the write request was successfully queued, `false` otherwise.
170 : *
171 : * Emits settingsWritten() if/when the \a settings have been written successfully.
172 : */
173 80 : bool MultimeterService::setSettings(const Settings &settings)
174 72 : {
175 72 : Q_D(const MultimeterService);
176 72 : const QLowEnergyCharacteristic characteristic =
177 152 : d->getCharacteristic(CharacteristicUuids::settings);
178 152 : if (!characteristic.isValid()) {
179 72 : return false;
180 72 : }
181 :
182 0 : const QByteArray value = MultimeterServicePrivate::encodeSettings(settings);
183 0 : if (value.isNull()) {
184 0 : return false;
185 0 : }
186 :
187 0 : d->service->writeCharacteristic(characteristic, value);
188 0 : return (d->service->error() != QLowEnergyService::ServiceError::CharacteristicWriteError);
189 80 : }
190 :
191 : /*!
192 : * Returns the most recent value of the `Multimeter` service's `Reading` characteristic.
193 : *
194 : * The returned value, if any, is from the underlying Bluetooth stack's cache. If no such value is
195 : * currently available (ie the serviceDetailsDiscovered signal has not been emitted yet), then the
196 : * returned MultimeterService::Reading::value member will be a quiet NaN, which can be checked like:
197 : *
198 : * ```
199 : * const MultimeterService::Reading reading = multimeterService->reading();
200 : * if (qIsNaN(reading.value)) {
201 : * // Handle failure.
202 : * }
203 : * ```
204 : */
205 80 : MultimeterService::Reading MultimeterService::reading() const
206 72 : {
207 72 : Q_D(const MultimeterService);
208 72 : const QLowEnergyCharacteristic characteristic =
209 152 : d->getCharacteristic(CharacteristicUuids::reading);
210 152 : return (characteristic.isValid()) ? MultimeterServicePrivate::parseReading(characteristic.value())
211 232 : : Reading{ MeterStatus::Error, std::numeric_limits<float>::quiet_NaN(), Mode::Idle, 0 };
212 152 : }
213 :
214 : /*!
215 : * Enables client-side notifications of meter readings.
216 : *
217 : * This is an alternative to manually requesting individual reads via readReadingCharacteristic().
218 : *
219 : * Returns `true` is the request was successfully submitted to the device queue, `false` otherwise.
220 : *
221 : * Successfully read values (if any) will be emitted via the readingRead() signal.
222 : */
223 80 : bool MultimeterService::enableReadingNotifications()
224 72 : {
225 72 : Q_D(MultimeterService);
226 152 : return d->enableCharacteristicNotificatons(CharacteristicUuids::reading);
227 72 : }
228 :
229 : /*!
230 : * Disables client-side notifications of meter readings.
231 : *
232 : * Instantaneous reads can still be fetched by readReadingCharacteristic().
233 : *
234 : * Returns `true` is the request was successfully submitted to the device queue, `false` otherwise.
235 : */
236 80 : bool MultimeterService::disableReadingNotifications()
237 72 : {
238 72 : Q_D(MultimeterService);
239 152 : return d->disableCharacteristicNotificatons(CharacteristicUuids::reading);
240 72 : }
241 :
242 : /*!
243 : * \fn MultimeterService::readingRead
244 : *
245 : * This signal is emitted when the `Reading` characteristic has been read successfully.
246 : *
247 : * \see readReadingCharacteristic
248 : */
249 :
250 : /*!
251 : * \fn MultimeterService::settingsWritten
252 : *
253 : * This signal is emitted when the `Settings` characteristic has been written successfully.
254 : *
255 : * \see setSettings
256 : */
257 :
258 : /*!
259 : * \cond internal
260 : * \class MultimeterServicePrivate
261 : *
262 : * The MultimeterServicePrivate class provides private implementation for MultimeterService.
263 : */
264 :
265 : /*!
266 : * \internal
267 : * Constructs a new MultimeterServicePrivate object with public implementation \a q.
268 : */
269 3285 : MultimeterServicePrivate::MultimeterServicePrivate(
270 5840 : QLowEnergyController * controller, MultimeterService * const q)
271 8584 : : AbstractPokitServicePrivate(MultimeterService::serviceUuid, controller, q)
272 3240 : {
273 :
274 6525 : }
275 :
276 : /*!
277 : * Returns \a settings in the format Pokit devices expect.
278 : */
279 320 : QByteArray MultimeterServicePrivate::encodeSettings(const MultimeterService::Settings &settings)
280 288 : {
281 288 : static_assert(sizeof(settings.mode) == 1, "Expected to be 1 byte.");
282 288 : static_assert(sizeof(settings.range) == 1, "Expected to be 1 byte.");
283 288 : static_assert(sizeof(settings.updateInterval) == 4, "Expected to be 4 bytes.");
284 :
285 460 : QByteArray value;
286 608 : QDataStream stream(&value, QIODevice::WriteOnly);
287 608 : stream.setByteOrder(QDataStream::LittleEndian);
288 608 : stream.setFloatingPointPrecision(QDataStream::SinglePrecision); // 32-bit floats, not 64-bit.
289 608 : stream << (quint8)settings.mode << settings.range << settings.updateInterval;
290 :
291 288 : Q_ASSERT(value.size() == 6);
292 608 : return value;
293 608 : }
294 :
295 : /*!
296 : * Parses the `Reading` \a value into a MultimeterService::Reading struct.
297 : */
298 400 : MultimeterService::Reading MultimeterServicePrivate::parseReading(const QByteArray &value)
299 360 : {
300 515 : MultimeterService::Reading reading{
301 360 : MultimeterService::MeterStatus::Error,
302 360 : std::numeric_limits<float>::quiet_NaN(),
303 360 : MultimeterService::Mode::Idle, 0
304 360 : };
305 :
306 975 : if (!checkSize(u"Reading"_s, value, 7, 7)) {
307 242 : return reading;
308 144 : }
309 :
310 429 : reading.status = MultimeterService::MeterStatus(value.at(0));
311 585 : reading.value = qFromLittleEndian<float>(value.mid(1,4).constData());
312 429 : reading.mode = static_cast<MultimeterService::Mode>(value.at(5));
313 429 : reading.range = static_cast<quint8>(value.at(6));
314 456 : return reading;
315 360 : }
316 :
317 : /*!
318 : * Implements AbstractPokitServicePrivate::characteristicRead to parse \a value, then emit a
319 : * specialised signal, for each supported \a characteristic.
320 : */
321 80 : void MultimeterServicePrivate::characteristicRead(const QLowEnergyCharacteristic &characteristic,
322 : const QByteArray &value)
323 72 : {
324 152 : AbstractPokitServicePrivate::characteristicRead(characteristic, value);
325 :
326 72 : Q_Q(MultimeterService);
327 152 : if (characteristic.uuid() == MultimeterService::CharacteristicUuids::reading) {
328 0 : Q_EMIT q->readingRead(parseReading(value));
329 0 : return;
330 0 : }
331 :
332 152 : if (characteristic.uuid() == MultimeterService::CharacteristicUuids::settings) {
333 0 : qCWarning(lc).noquote() << tr("Settings characteristic is write-only, but somehow read")
334 0 : << serviceUuid << characteristic.name() << characteristic.uuid();
335 0 : return;
336 0 : }
337 :
338 370 : qCWarning(lc).noquote() << tr("Unknown characteristic read for Multimeter service")
339 242 : << serviceUuid << characteristic.name() << characteristic.uuid();
340 72 : }
341 :
342 : /*!
343 : * Implements AbstractPokitServicePrivate::characteristicWritten to parse \a newValue, then emit a
344 : * specialised signal, for each supported \a characteristic.
345 : */
346 80 : void MultimeterServicePrivate::characteristicWritten(const QLowEnergyCharacteristic &characteristic,
347 : const QByteArray &newValue)
348 72 : {
349 152 : AbstractPokitServicePrivate::characteristicWritten(characteristic, newValue);
350 :
351 72 : Q_Q(MultimeterService);
352 152 : if (characteristic.uuid() == MultimeterService::CharacteristicUuids::settings) {
353 0 : Q_EMIT q->settingsWritten();
354 0 : return;
355 0 : }
356 :
357 152 : if (characteristic.uuid() == MultimeterService::CharacteristicUuids::reading) {
358 0 : qCWarning(lc).noquote() << tr("Reading characteristic is read/notify, but somehow written")
359 0 : << serviceUuid << characteristic.name() << characteristic.uuid();
360 0 : return;
361 0 : }
362 :
363 370 : qCWarning(lc).noquote() << tr("Unknown characteristic written for Multimeter service")
364 242 : << serviceUuid << characteristic.name() << characteristic.uuid();
365 72 : }
366 :
367 : /*!
368 : * Implements AbstractPokitServicePrivate::characteristicChanged to parse \a newValue, then emit a
369 : * specialised signal, for each supported \a characteristic.
370 : */
371 80 : void MultimeterServicePrivate::characteristicChanged(const QLowEnergyCharacteristic &characteristic,
372 : const QByteArray &newValue)
373 72 : {
374 152 : AbstractPokitServicePrivate::characteristicChanged(characteristic, newValue);
375 :
376 72 : Q_Q(MultimeterService);
377 152 : if (characteristic.uuid() == MultimeterService::CharacteristicUuids::settings) {
378 0 : qCWarning(lc).noquote() << tr("Settings characteristic is write-only, but somehow updated")
379 0 : << serviceUuid << characteristic.name() << characteristic.uuid();
380 0 : return;
381 0 : }
382 :
383 152 : if (characteristic.uuid() == MultimeterService::CharacteristicUuids::reading) {
384 0 : Q_EMIT q->readingRead(parseReading(newValue));
385 0 : return;
386 0 : }
387 :
388 370 : qCWarning(lc).noquote() << tr("Unknown characteristic notified for Multimeter service")
389 242 : << serviceUuid << characteristic.name() << characteristic.uuid();
390 72 : }
391 :
392 : /// \endcond
393 :
394 : QTPOKIT_END_NAMESPACE
|
