LCOV - code coverage report
Current view: top level - src/lib - pokitdevice.cpp (source / functions) Coverage Total Hit
Project: Dokit Lines: 93.8 % 194 182
Version: Functions: 95.7 % 23 22

            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 PokitDevice and PokitDevicePrivate classes.
       7              :  */
       8              : 
       9              : #include <qtpokit/pokitdevice.h>
      10              : 
      11              : #include <qtpokit/calibrationservice.h>
      12              : #include <qtpokit/dataloggerservice.h>
      13              : #include <qtpokit/deviceinfoservice.h>
      14              : #include <qtpokit/dsoservice.h>
      15              : #include <qtpokit/multimeterservice.h>
      16              : #include <qtpokit/statusservice.h>
      17              : 
      18              : #include "pokitdevice_p.h"
      19              : #include "../stringliterals_p.h"
      20              : 
      21              : #include <QMutexLocker>
      22              : 
      23              : QTPOKIT_BEGIN_NAMESPACE
      24              : DOKIT_USE_STRINGLITERALS
      25              : 
      26              : /*!
      27              :  * \class PokitDevice
      28              :  *
      29              :  * The PokitDevice class simplifies Pokit device access.
      30              :  *
      31              :  * It does this by wrapping QLowEnergyController to provide:
      32              :  * * convenient Pokit service factory methods (dataLogger(), deviceInformation(), dso(),
      33              :      multimeter() and status()); and
      34              :  * * consistent debug logging of QLowEnergyController events.
      35              :  *
      36              :  * But this class is entirely optional, in that all features of all other QtPokit classes can be
      37              :  * used without this class.  It's just a (meaningful) convenience.
      38              :  */
      39              : 
      40              : /*!
      41              :  * Constructs a new Pokit device controller wrapper for \a deviceInfo, with \a parent.
      42              :  *
      43              :  * Though not strictly necessary, \a deviceInfo should normally come from a
      44              :  * PokitDiscoveryAgent instance (or a QBluetoothDeviceDiscoveryAgent), otherwise connection
      45              :  * is likely to fail with QLowEnergyController::UnknownRemoteDeviceError.
      46              :  */
      47         2720 : PokitDevice::PokitDevice(const QBluetoothDeviceInfo &deviceInfo, QObject *parent)
      48         3536 :     : QObject(parent), d_ptr(new PokitDevicePrivate(this))
      49          816 : {
      50          816 :     Q_D(PokitDevice);
      51         3536 :     d->setController(QLowEnergyController::createCentral(deviceInfo, this));
      52         3536 : }
      53              : 
      54              : /*!
      55              :  * Constructs a new Pokit device controller wrapper for \a controller, with \a parent.
      56              :  */
      57         1360 : PokitDevice::PokitDevice(QLowEnergyController *controller, QObject *parent)
      58         2008 :     : QObject(parent), d_ptr(new PokitDevicePrivate(this))
      59          888 : {
      60          888 :     Q_D(PokitDevice);
      61         2248 :     d->setController(controller);
      62         2248 : }
      63              : 
      64              : /*!
      65              :  * \cond internal
      66              :  * Constructs a new Pokit device controller wrapper with \a parent, and private implementation \a d.
      67              :  *
      68              :  * Derived classes using this constructor should use PokitDevicePrivate::setController to assign
      69              :  * the BLE controller as some point.
      70              :  */
      71            0 : PokitDevice::PokitDevice(PokitDevicePrivate * const d, QObject * const parent)
      72            0 :     : QObject(parent), d_ptr(d)
      73            0 : {
      74              : 
      75            0 : }
      76              : /// \endcond
      77              : 
      78              : /*!
      79              :  * Destroys this PokitDevice object.
      80              :  */
      81         6800 : PokitDevice::~PokitDevice()
      82         1704 : {
      83         5784 :     delete d_ptr;
      84         8504 : }
      85              : 
      86              : /*!
      87              :  * Returns a non-const pointer to the controller used to access the Pokit device.
      88              :  */
      89         5120 : QLowEnergyController * PokitDevice::controller()
      90         1568 : {
      91         1568 :     Q_D(PokitDevice);
      92         6688 :     return d->controller;
      93         1568 : }
      94              : 
      95              : /*!
      96              :  * Returns a const pointer to the controller used to access the Pokit device.
      97              :  */
      98           80 : const QLowEnergyController * PokitDevice::controller() const
      99           56 : {
     100           56 :     Q_D(const PokitDevice);
     101          136 :     return d->controller;
     102           56 : }
     103              : 
     104              : /// \cond
     105              : #define QTPOKIT_INTERNAL_GET_SERVICE(typeName, varName) \
     106         2160 :     Q_D(PokitDevice);                                 \
     107         2160 :     const QMutexLocker scopedLock(&d->varName##Mutex);\
     108         2160 :     if (d->varName == nullptr) {                      \
     109         1152 :         d->varName = new typeName(d->controller);     \
     110         1152 :     }                                                 \
     111         2160 :     return d->varName                                 \
     112              : /// \endcond
     113              : 
     114              : /*!
     115              :  * Returns a pointer to a CalibrationService instance that uses this device's controller for access.
     116              :  *
     117              :  * This is a convenience function, that always returns the same pointer (for this PokitDevice
     118              :  * instance), but the service itself is lazily created (in a threadsafe manner) on the first
     119              :  * invocation of this function.
     120              :  */
     121          320 : CalibrationService * PokitDevice::calibration()
     122          224 : {
     123          972 :     QTPOKIT_INTERNAL_GET_SERVICE(CalibrationService, calibration);
     124          224 : }
     125              : 
     126              : /*!
     127              :  * Returns a pointer to a DataLoggerService instance that uses this device's controller for access.
     128              :  *
     129              :  * This is a convenience function, that always returns the same pointer (for this PokitDevice
     130              :  * instance), but the service itself is lazily created (in a threadsafe manner) on the first
     131              :  * invocation of this function.
     132              :  */
     133          320 : DataLoggerService * PokitDevice::dataLogger()
     134          224 : {
     135          972 :     QTPOKIT_INTERNAL_GET_SERVICE(DataLoggerService, dataLogger);
     136          224 : }
     137              : 
     138              : /*!
     139              :  * Returns a pointer to DeviceInformationService instance that uses this device's controller for
     140              :  * access.
     141              :  *
     142              :  * This is a convenience function, that always returns the same pointer (for this PokitDevice
     143              :  * instance), but the service itself is lazily created (in a threadsafe manner) on the first
     144              :  * invocation of this function.
     145              :  */
     146         2240 : DeviceInfoService * PokitDevice::deviceInformation()
     147          800 : {
     148         6036 :     QTPOKIT_INTERNAL_GET_SERVICE(DeviceInfoService, deviceInfo);
     149          800 : }
     150              : 
     151              : /*!
     152              :  * Returns a pointer to DsoService instance that uses this device's controller for access.
     153              :  *
     154              :  * This is a convenience function, that always returns the same pointer (for this PokitDevice
     155              :  * instance), but the service itself is lazily created (in a threadsafe manner) on the first
     156              :  * invocation of this function.
     157              :  */
     158          320 : DsoService * PokitDevice::dso()
     159          224 : {
     160          972 :     QTPOKIT_INTERNAL_GET_SERVICE(DsoService, dso);
     161          224 : }
     162              : 
     163              : /*!
     164              :  * Returns a pointer to MultimeterService instance that uses this device's controller for access.
     165              :  *
     166              :  * This is a convenience function, that always returns the same pointer (for this PokitDevice
     167              :  * instance), but the service itself is lazily created (in a threadsafe manner) on the first
     168              :  * invocation of this function.
     169              :  */
     170          320 : MultimeterService * PokitDevice::multimeter()
     171          224 : {
     172          972 :     QTPOKIT_INTERNAL_GET_SERVICE(MultimeterService, multimeter);
     173          224 : }
     174              : 
     175              : /*!
     176              :  * Returns a pointer to StatusService instance that uses this device's controller for access.
     177              :  *
     178              :  * This is a convenience function, that always returns the same pointer (for this PokitDevice
     179              :  * instance), but the service itself is lazily created (in a threadsafe manner) on the first
     180              :  * invocation of this function.
     181              :  */
     182         1120 : StatusService * PokitDevice::status()
     183          464 : {
     184         3082 :     QTPOKIT_INTERNAL_GET_SERVICE(StatusService, status);
     185          464 : }
     186              : #undef QTPOKIT_INTERNAL_GET_SERVICE
     187              : 
     188              : /*!
     189              :  * Returns a human-readable name for the \a uuid service, or a null QString if unknown.
     190              :  *
     191              :  * This is equivalent to QBluetoothUuid::serviceClassToString() but for services provided by Pokit
     192              :  * devices.
     193              :  */
     194          800 : QString PokitDevice::serviceToString(const QBluetoothUuid &uuid)
     195          560 : {
     196          560 :     static const QHash<QBluetoothUuid, QString> hash{
     197          668 :         { CalibrationService::serviceUuid, tr("Calibration") },
     198          640 :         { DataLoggerService::serviceUuid,  tr("Data Logger") },
     199          640 :         { DsoService::serviceUuid,         tr("DSO") },
     200          640 :         { MultimeterService::serviceUuid,  tr("Multimeter") },
     201          640 :         { StatusService::ServiceUuids::pokitMeter, tr("Status (Pokit Meter)") },
     202          640 :         { StatusService::ServiceUuids::pokitPro,   tr("Status (Pokit Pro)") },
     203          560 :         { DeviceInfoService::serviceUuid,
     204          720 :             QBluetoothUuid::serviceClassToString(QBluetoothUuid::ServiceClassUuid::DeviceInformation) },
     205              : 
     206              :         // The following are not specifically supported by this library, but strings provided for nicer debug output.
     207          560 :         { QBluetoothUuid::ServiceClassUuid::GenericAccess,
     208          720 :             QBluetoothUuid::serviceClassToString(QBluetoothUuid::ServiceClassUuid::GenericAccess) },
     209          560 :         { QBluetoothUuid::ServiceClassUuid::GenericAttribute,
     210          720 :             QBluetoothUuid::serviceClassToString(QBluetoothUuid::ServiceClassUuid::GenericAttribute) },
     211          695 :         { QBluetoothUuid(u"1d14d6ee-fd63-4fa1-bfa4-8f47b42119f0"_s), tr("OTA Firmware Update") },
     212         2305 :     };
     213         1410 :     return hash.value(uuid);
     214          560 : }
     215              : 
     216              : /*!
     217              :  * Returns a human-readable name for the \a uuid characteristic, or a null QString if unknown.
     218              :  *
     219              :  * This is equivalent to QBluetoothUuid::characteristicToString() but for characteristics provided
     220              :  * by Pokit devices.
     221              :  */
     222         1760 : QString PokitDevice::charcteristicToString(const QBluetoothUuid &uuid)
     223         1232 : {
     224         1232 :     static const QHash<QBluetoothUuid, QString> hash{
     225         1340 :         { CalibrationService::CharacteristicUuids::temperature, tr("Temperature") },
     226         1312 :         { CalibrationService::CharacteristicUuids::getParam,    tr("Get Param") },
     227         1312 :         { CalibrationService::CharacteristicUuids::setParam,    tr("Set Param") },
     228              : 
     229         1312 :         { DataLoggerService::CharacteristicUuids::metadata, tr("Metadata") },
     230         1312 :         { DataLoggerService::CharacteristicUuids::reading,  tr("Reading") },
     231         1312 :         { DataLoggerService::CharacteristicUuids::settings, tr("Settings") },
     232              : 
     233         1312 :         { DsoService::CharacteristicUuids::metadata, tr("Metadata") },
     234         1312 :         { DsoService::CharacteristicUuids::reading,  tr("Reading") },
     235         1312 :         { DsoService::CharacteristicUuids::settings, tr("Settings") },
     236              : 
     237         1312 :         { MultimeterService::CharacteristicUuids::reading,  tr("Reading") },
     238         1312 :         { MultimeterService::CharacteristicUuids::settings, tr("Settings") },
     239              : 
     240         1312 :         { StatusService::CharacteristicUuids::deviceCharacteristics, tr("Device Characteristics") },
     241         1312 :         { StatusService::CharacteristicUuids::flashLed,              tr("Flash LED") },
     242         1312 :         { StatusService::CharacteristicUuids::name,                  tr("Name") },
     243         1312 :         { StatusService::CharacteristicUuids::status,                tr("Status") },
     244         1312 :         { StatusService::CharacteristicUuids::torch,                 tr("Torch") },
     245         1312 :         { StatusService::CharacteristicUuids::buttonPress,           tr("Button Press") },
     246              : 
     247         1232 :         { DeviceInfoService::CharacteristicUuids::firmwareRevision,
     248         1392 :             QBluetoothUuid::characteristicToString(QBluetoothUuid::CharacteristicType::FirmwareRevisionString) },
     249         1232 :         { DeviceInfoService::CharacteristicUuids::hardwareRevision,
     250         1392 :             QBluetoothUuid::characteristicToString(QBluetoothUuid::CharacteristicType::HardwareRevisionString) },
     251         1232 :         { DeviceInfoService::CharacteristicUuids::manufacturerName,
     252         1392 :             QBluetoothUuid::characteristicToString(QBluetoothUuid::CharacteristicType::ManufacturerNameString) },
     253         1232 :         { DeviceInfoService::CharacteristicUuids::modelNumber,
     254         1392 :             QBluetoothUuid::characteristicToString(QBluetoothUuid::CharacteristicType::ModelNumberString) },
     255         1232 :         { DeviceInfoService::CharacteristicUuids::softwareRevision,
     256         1392 :             QBluetoothUuid::characteristicToString(QBluetoothUuid::CharacteristicType::SoftwareRevisionString) },
     257         1232 :         { DeviceInfoService::CharacteristicUuids::serialNumber,
     258         1392 :             QBluetoothUuid::characteristicToString(QBluetoothUuid::CharacteristicType::SerialNumberString) },
     259              : 
     260              :         // The next two are not specifically supported by this library, but strings provided for nicer debug output.
     261         1367 :         { QBluetoothUuid(u"f7bf3564-fb6d-4e53-88a4-5e37e0326063"_s), tr("OTA Control") },
     262         1367 :         { QBluetoothUuid(u"984227f3-34fc-4045-a5d0-2c581f81a153"_s), tr("OTA Data Transfer") },
     263         5137 :     };
     264         3102 :     return hash.value(uuid);
     265         1232 : }
     266              : 
     267              : /*!
     268              :  * \cond internal
     269              :  * \class PokitDevicePrivate
     270              :  *
     271              :  * The PokitDevicePrivate class provides private implementation for PokitDevice.
     272              :  */
     273              : 
     274              : /*!
     275              :  * Constructs a new PokitDevicePrivate object with public implementation \a q.
     276              :  */
     277         5544 : PokitDevicePrivate::PokitDevicePrivate(PokitDevice * const q) : q_ptr(q)
     278         1704 : {
     279              : 
     280         5784 : }
     281              : 
     282              : /*!
     283              :  * Sets \a newController to be used for accessing Pokit devices.
     284              :  *
     285              :  * If a controller has already been set (and is not the same pointer), then the previous controller
     286              :  * will be disconnected, and replaced with \a newController.
     287              :  *
     288              :  * This function will not take ownership of the new controller. The caller is responsible for
     289              :  * ensuring that \a newContorller remains valid for the lifetime of this instance, or until this
     290              :  * function is used again to replace \a newController with another one (which may be a nullptr).
     291              :  *
     292              :  * \see controller
     293              :  * \see PokitDevice::controller()
     294              :  */
     295         4640 : void PokitDevicePrivate::setController(QLowEnergyController * newController)
     296         1872 : {
     297         6512 :     if (newController == this->controller) {
     298         3007 :         qCDebug(lc).noquote() << tr("Controller already set to:") << newController;
     299         1905 :         return;
     300          936 :     }
     301              : 
     302         4056 :     if (this->controller) {
     303          399 :         qCDebug(lc).noquote() << tr("Disconnecting signals from previous controller:")
     304            0 :             << controller;
     305          312 :         disconnect(this->controller, nullptr, this, nullptr);
     306           72 :     }
     307              : 
     308         5187 :     qCDebug(lc).noquote() << tr("Setting new controller:") << newController;
     309         4056 :     this->controller = newController;
     310         4056 :     if (!newController) {
     311           48 :         return; // Don't bother continuing to connect if new controller is null.
     312           48 :     }
     313              : 
     314         4921 :     qCDebug(lc).noquote() << tr(R"(Set new controller "%1" (%2) at (%3).)").arg(
     315            0 :         controller->remoteName(), controller->remoteDeviceUuid().toString(),
     316            0 :         controller->remoteAddress().toString());
     317              : 
     318         3848 :     connect(controller, &QLowEnergyController::connected,
     319         1813 :             this, &PokitDevicePrivate::connected);
     320              : 
     321         3848 :     connect(controller, &QLowEnergyController::connectionUpdated,
     322         1813 :             this, &PokitDevicePrivate::connectionUpdated);
     323              : 
     324         3848 :     connect(controller, &QLowEnergyController::disconnected,
     325         1813 :             this, &PokitDevicePrivate::disconnected);
     326              : 
     327         3848 :     connect(controller, &QLowEnergyController::discoveryFinished,
     328         1813 :             this, &PokitDevicePrivate::discoveryFinished);
     329              : 
     330              : 
     331         3848 :     connect(controller,
     332          333 :     #if (QT_VERSION < QT_VERSION_CHECK(6, 2, 0))
     333          333 :         QOverload<QLowEnergyController::Error>::of(&QLowEnergyController::error),
     334              :     #else
     335          555 :         &QLowEnergyController::errorOccurred,
     336          555 :     #endif
     337         1813 :         this, &PokitDevicePrivate::errorOccurred);
     338              : 
     339              : 
     340         3848 :     connect(controller, &QLowEnergyController::serviceDiscovered,
     341         1813 :             this, &PokitDevicePrivate::serviceDiscovered);
     342              : 
     343         3848 :     connect(controller, &QLowEnergyController::stateChanged,
     344         2738 :             this, &PokitDevicePrivate::stateChanged);
     345          888 : }
     346              : 
     347              : /*!
     348              :  * Handle connected signals.
     349              :  */
     350          240 : void PokitDevicePrivate::connected() const
     351           72 : {
     352          312 :     if (controller == nullptr) {
     353          512 :         qCCritical(lc).noquote() << tr("PokitDevicePrivate::connected slot invoked without a controller.");
     354          150 :         return; // Just to avoid the nullptr dereference below.
     355           48 :     }
     356          133 :     qCDebug(lc).noquote() << tr(R"(Connected to "%1" (%2) at (%3).)").arg(
     357            0 :         controller->remoteName(), controller->remoteDeviceUuid().toString(),
     358            0 :         controller->remoteAddress().toString());
     359           24 : }
     360              : 
     361              : /*!
     362              :  * Handle connectionUpdated signals.
     363              :  */
     364           80 : void PokitDevicePrivate::connectionUpdated(const QLowEnergyConnectionParameters &newParameters) const
     365           56 : {
     366          165 :     qCDebug(lc).noquote() << tr("Connection updated:") << newParameters.latency()
     367            0 :         << newParameters.minimumInterval() << newParameters.maximumInterval()
     368            0 :         << newParameters.supervisionTimeout();
     369          136 : }
     370              : 
     371              : /*!
     372              :  * Handle disconnected signals.
     373              :  */
     374           80 : void PokitDevicePrivate::disconnected() const
     375           56 : {
     376          165 :     qCDebug(lc).noquote() << tr("Device disconnected.");
     377          136 : }
     378              : 
     379              : /*!
     380              :  * Handle discoveryFinished signals.
     381              :  */
     382           80 : void PokitDevicePrivate::discoveryFinished() const
     383           56 : {
     384          165 :     qCDebug(lc).noquote() << tr("Service discovery finished.");
     385          136 : }
     386              : 
     387              : /*!
     388              :  * Handle error signals.
     389              :  */
     390           80 : void PokitDevicePrivate::errorOccurred(QLowEnergyController::Error newError) const
     391           56 : {
     392          165 :     qCDebug(lc).noquote() << tr("Controller error:") << newError;
     393          136 : }
     394              : 
     395              : /*!
     396              :  * Handle serviceDiscovered signals.
     397              :  */
     398           80 : void PokitDevicePrivate::serviceDiscovered(const QBluetoothUuid &newService) const
     399           56 : {
     400          165 :     qCDebug(lc).noquote() << tr(R"(Service discovered: %1 "%2")")
     401            0 :         .arg(newService.toString(), PokitDevice::serviceToString(newService));
     402          136 : }
     403              : 
     404              : /*!
     405              :  * Handle stateChanged signals.
     406              :  */
     407           80 : void PokitDevicePrivate::stateChanged(QLowEnergyController::ControllerState state) const
     408           56 : {
     409          165 :     qCDebug(lc).noquote() << tr("State changed to:") << state;
     410          136 : }
     411              : 
     412              : /// \endcond
     413              : 
     414              : QTPOKIT_END_NAMESPACE
        

Generated by: LCOV version 2.3.1-1