1/*
2 SPDX-FileCopyrightText: 2006-2007 Kevin Ottens <ervin@kde.org>
3 SPDX-FileCopyrightText: 2012 Lukas Tinkl <ltinkl@redhat.com>
4 SPDX-FileCopyrightText: 2014 Kai Uwe Broulik <kde@privat.broulik.de>
5
6 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
7*/
8
9#ifndef SOLID_BATTERY_H
10#define SOLID_BATTERY_H
11
12#include <solid/solid_export.h>
13
14#include <solid/deviceinterface.h>
15
16namespace Solid
17{
18class BatteryPrivate;
19class Device;
20
21/*!
22 * \class Solid::Battery
23 * \inheaderfile Solid/Battery
24 * \inmodule Solid
25 *
26 * \brief This device interface is available on batteries.
27 */
28class SOLID_EXPORT Battery : public DeviceInterface
29{
30 Q_OBJECT
31
32 /*!
33 * \property Solid::Battery::present
34 */
35 Q_PROPERTY(bool present READ isPresent NOTIFY presentStateChanged)
36
37 /*!
38 * \property Solid::Battery::type
39 */
40 Q_PROPERTY(BatteryType type READ type CONSTANT)
41
42 /*!
43 * \property Solid::Battery::chargePercent
44 */
45 Q_PROPERTY(int chargePercent READ chargePercent NOTIFY chargePercentChanged)
46
47 /*!
48 * \property Solid::Battery::capacity
49 */
50 Q_PROPERTY(int capacity READ capacity NOTIFY capacityChanged)
51
52 /*!
53 * \property Solid::Battery::cycleCount
54 */
55 Q_PROPERTY(int cycleCount READ cycleCount NOTIFY cycleCountChanged)
56
57 /*!
58 * \property Solid::Battery::rechargeable
59 */
60 Q_PROPERTY(bool rechargeable READ isRechargeable CONSTANT)
61
62 /*!
63 * \property Solid::Battery::powerSupply
64 */
65 Q_PROPERTY(bool powerSupply READ isPowerSupply NOTIFY powerSupplyStateChanged)
66
67 /*!
68 * \property Solid::Battery::chargeState
69 */
70 Q_PROPERTY(ChargeState chargeState READ chargeState NOTIFY chargeStateChanged)
71
72 /*!
73 * \property Solid::Battery::timeToEmpty
74 */
75 Q_PROPERTY(qlonglong timeToEmpty READ timeToEmpty NOTIFY timeToEmptyChanged)
76
77 /*!
78 * \property Solid::Battery::timeToFull
79 */
80 Q_PROPERTY(qlonglong timeToFull READ timeToFull NOTIFY timeToFullChanged)
81
82 /*!
83 * \property Solid::Battery::energy
84 */
85 Q_PROPERTY(double energy READ energy NOTIFY energyChanged)
86
87 /*!
88 * \property Solid::Battery::energyFull
89 */
90 Q_PROPERTY(double energyFull READ energyFull NOTIFY energyFullChanged)
91
92 /*!
93 * \property Solid::Battery::energyFullDesign
94 */
95 Q_PROPERTY(double energyFullDesign READ energyFullDesign NOTIFY energyFullDesignChanged)
96
97 /*!
98 * \property Solid::Battery::energyRate
99 */
100 Q_PROPERTY(double energyRate READ energyRate NOTIFY energyRateChanged)
101
102 /*!
103 * \property Solid::Battery::voltage
104 */
105 Q_PROPERTY(double voltage READ voltage NOTIFY voltageChanged)
106
107 /*!
108 * \property Solid::Battery::temperature
109 */
110 Q_PROPERTY(double temperature READ temperature NOTIFY temperatureChanged)
111
112 /*!
113 * \property Solid::Battery::technology
114 */
115 Q_PROPERTY(Technology technology READ technology CONSTANT)
116
117 /*!
118 * \property Solid::Battery::serial
119 */
120 Q_PROPERTY(QString serial READ serial CONSTANT)
121
122 /*!
123 * \property Solid::Battery::remainingTime
124 */
125 Q_PROPERTY(qlonglong remainingTime READ remainingTime NOTIFY remainingTimeChanged)
126 Q_DECLARE_PRIVATE(Battery)
127 friend class Device;
128
129public:
130 /*!
131 * This enum type defines the type of the device holding the battery
132 *
133 * \value PdaBattery A battery in a Personal Digital Assistant
134 * \value UpsBattery A battery in an Uninterruptible Power Supply
135 * \value PrimaryBattery A primary battery for the system (for example laptop battery)
136 * \value MouseBattery A battery in a mouse
137 * \value KeyboardBattery A battery in a keyboard
138 * \value KeyboardMouseBattery A battery in a combined keyboard and mouse
139 * \value CameraBattery A battery in a camera
140 * \value PhoneBattery A battery in a phone
141 * \value MonitorBattery A battery in a monitor
142 * \value GamingInputBattery A battery in a gaming input device (for example a wireless game pad)
143 * \value[since 5.54] BluetoothBattery A generic Bluetooth device battery (if its type isn't known, a Bluetooth mouse would normally show up as a
144 * MouseBattery)
145 * \value[since 5.88] TabletBattery A battery in a graphics tablet or pen
146 * \value[since 6.0] HeadphoneBattery A battery in a headphone
147 * \value[since 6.0] HeadsetBattery A battery in a headset
148 * \value[since 6.0] TouchpadBattery A battery in a touchpad. This is how the Dualsense Wireless Controller is categorized
149 * \value[since 6.21] WearableBattery A battery for a wearable device, watch...
150 * \value UnknownBattery A battery in an unknown device
151 */
152 enum BatteryType {
153 UnknownBattery,
154 PdaBattery,
155 UpsBattery,
156 PrimaryBattery,
157 MouseBattery,
158 KeyboardBattery,
159 KeyboardMouseBattery,
160 CameraBattery,
161 PhoneBattery,
162 MonitorBattery,
163 GamingInputBattery,
164 BluetoothBattery,
165 TabletBattery,
166 HeadphoneBattery,
167 HeadsetBattery,
168 TouchpadBattery,
169 WearableBattery,
170 };
171 Q_ENUM(BatteryType)
172
173 /*!
174 * This enum type defines charge state of a battery
175 *
176 * \value NoCharge Battery charge is stable, not charging or discharging or the state is Unknown
177 * \value Charging Battery is charging
178 * \value Discharging Battery is discharging
179 * \value FullyCharged The battery is fully charged; a battery not necessarily charges up to 100%
180 */
181 enum ChargeState { NoCharge, Charging, Discharging, FullyCharged };
182 Q_ENUM(ChargeState)
183
184 /*!
185 * Technology used in the battery
186 *
187 * \value UnknownTechnology Unknown
188 * \value LithiumIon Lithium ion
189 * \value LithiumPolymer Lithium polymer
190 * \value LithiumIronPhosphate Lithium iron phosphate
191 * \value LeadAcid Lead acid
192 * \value NickelCadmium Nickel cadmium
193 * \value NickelMetalHydride Nickel metal hydride
194 */
195 enum Technology {
196 UnknownTechnology = 0,
197 LithiumIon,
198 LithiumPolymer,
199 LithiumIronPhosphate,
200 LeadAcid,
201 NickelCadmium,
202 NickelMetalHydride,
203 };
204 Q_ENUM(Technology)
205
206private:
207 /*!
208 * Creates a new Battery object.
209 *
210 * You generally won't need this. It's created when necessary using
211 * Device::as().
212 *
213 * \a backendObject the device interface object provided by the backend
214 * \sa Solid::Device::as()
215 */
216 SOLID_NO_EXPORT explicit Battery(QObject *backendObject);
217
218public:
219 ~Battery() override;
220
221 /*!
222 * Get the Solid::DeviceInterface::Type of the Battery device interface.
223 * \sa Solid::DeviceInterface::Type
224 */
225 static Type deviceInterfaceType()
226 {
227 return DeviceInterface::Battery;
228 }
229
230 /*!
231 * Indicates if this battery is currently present in its bay.
232 *
233 * Returns \c true if the battery is present, \c false otherwise
234 */
235 bool isPresent() const;
236
237 /*!
238 * Returns the type of device holding this battery.
239 *
240 * \sa Solid::Battery::BatteryType
241 */
242 Solid::Battery::BatteryType type() const;
243
244 /*!
245 * Returns the current charge level of the battery normalised
246 * to percent.
247 */
248 int chargePercent() const;
249
250 /*!
251 * Returns the battery capacity normalised to percent,
252 * meaning how much energy can it hold compared to what it is designed to.
253 *
254 * The capacity of the battery will reduce with age.
255 * A capacity value less than 75% is usually a sign that you should renew your battery.
256 *
257 * \since 4.11
258 */
259 int capacity() const;
260
261 /*!
262 * Retrieves the number of charge cycles this battery has experienced so far,
263 * or -1 if this information is unavailable.
264 *
265 * Returns the number of charge cycles
266 * \since 6.9
267 */
268 int cycleCount() const;
269
270 /*!
271 * Indicates if the battery is rechargeable.
272 */
273 bool isRechargeable() const;
274
275 /*!
276 * Indicates if the battery is powering the machine.
277 */
278 bool isPowerSupply() const;
279
280 /*!
281 * Retrieves the current charge state of the battery. It can be in a stable
282 * state (no charge), charging or discharging.
283 *
284 * \sa Solid::Battery::ChargeState
285 */
286 Solid::Battery::ChargeState chargeState() const;
287
288 /*!
289 * Time (in seconds) until the battery is empty.
290 *
291 * \since 5.0
292 */
293 qlonglong timeToEmpty() const;
294
295 /*!
296 * Time (in seconds) until the battery is full.
297 *
298 * \since 5.0
299 */
300 qlonglong timeToFull() const;
301
302 /*!
303 * Retrieves the technology used to manufacture the battery.
304 *
305 * \sa Solid::Battery::Technology
306 */
307 Solid::Battery::Technology technology() const;
308
309 /*!
310 * Amount of energy (measured in Wh) currently available in the power source.
311 */
312 double energy() const;
313
314 /*!
315 * Amount of energy (measured in Wh) the battery has when it is full.
316 * \since 5.7
317 */
318 double energyFull() const;
319
320 /*!
321 * Amount of energy (measured in Wh) the battery should have by design hen it is full.
322 *
323 * Returns amount of battery energy when full by design in Wh
324 * \since 5.7
325 */
326 double energyFullDesign() const;
327
328 /*!
329 * Amount of energy being drained from the source, measured in W.
330 * If positive, the source is being discharged, if negative it's being charged.
331 */
332 double energyRate() const;
333
334 /*!
335 * Voltage in the Cell or being recorded by the meter.
336 */
337 double voltage() const;
338
339 /*!
340 * The temperature of the battery in degrees Celsius.
341 * \since 5.0
342 */
343 double temperature() const;
344
345 /*!
346 * The serial number of the battery
347 * \since 5.0
348 */
349 QString serial() const;
350
351 /*!
352 * Retrieves the current estimated remaining time (in seconds) of the system batteries
353 * \since 5.8
354 */
355 qlonglong remainingTime() const;
356
357Q_SIGNALS:
358 /*!
359 * This signal is emitted if the battery gets plugged in/out of the
360 * battery bay.
361 *
362 * \a newState the new plugging state of the battery
363 *
364 * \a udi the UDI of the battery with thew new plugging state
365 */
366 void presentStateChanged(bool newState, const QString &udi);
367
368 /*!
369 * This signal is emitted when the charge percent value of this
370 * battery has changed.
371 *
372 * \a value the new charge percent value of the battery
373 *
374 * \a udi the UDI of the battery with the new charge percent
375 */
376 void chargePercentChanged(int value, const QString &udi);
377
378 /*!
379 * This signal is emitted when the capacity of this battery has changed.
380 *
381 * \a value the new capacity of the battery
382 *
383 * \a udi the UDI of the battery with the new capacity
384 * \since 4.11
385 */
386 void capacityChanged(int value, const QString &udi);
387
388 /*!
389 * This signal is emitted when the number of charge cycles of the
390 * battery has changed.
391 *
392 * \a value the new number of charge cycles of the battery
393 *
394 * \a udi the UDI of the battery with the new number of charge cycles
395 *
396 * \since 6.9
397 */
398 void cycleCountChanged(int value, const QString &udi);
399
400 /*!
401 * This signal is emitted when the power supply state of the battery
402 * changes.
403 *
404 * \a newState the new power supply state
405 *
406 * \a udi the UDI of the battery with the new power supply state
407 * \since 4.11
408 */
409 void powerSupplyStateChanged(bool newState, const QString &udi);
410
411 /*!
412 * This signal is emitted when the charge state of this battery
413 * has changed.
414 *
415 * \a newState the new charge state of the battery
416 *
417 * \a udi the UDI of the battery with the new charge state
418 */
419 void chargeStateChanged(int newState, const QString &udi = QString());
420
421 /*!
422 * This signal is emitted when the time until the battery is empty
423 * has changed.
424 *
425 * \a time the new remaining time
426 *
427 * \a udi the UDI of the battery with the new remaining time
428 * \since 5.0
429 */
430 void timeToEmptyChanged(qlonglong time, const QString &udi);
431
432 /*!
433 * This signal is emitted when the time until the battery is full
434 * has changed.
435 *
436 * \a time the new remaining time
437 *
438 * \a udi the UDI of the battery with the new remaining time
439 * \since 5.0
440 */
441 void timeToFullChanged(qlonglong time, const QString &udi);
442
443 /*!
444 * This signal is emitted when the energy value of this
445 * battery has changed.
446 *
447 * \a energy the new energy value of the battery
448 *
449 * \a udi the UDI of the battery with the new energy value
450 */
451 void energyChanged(double energy, const QString &udi);
452
453 /*!
454 * This signal is emitted when the energy full value of this
455 * battery has changed.
456 *
457 * \a energy the new energy full value of the battery
458 *
459 * \a udi the UDI of the battery with the new energy full value
460 */
461 void energyFullChanged(double energy, const QString &udi);
462
463 /*!
464 * This signal is emitted when the energy full design value of this
465 * battery has changed.
466 *
467 * \a energy the new energy full design value of the battery
468 *
469 * \a udi the UDI of the battery with the new energy full design value
470 */
471 void energyFullDesignChanged(double energy, const QString &udi);
472
473 /*!
474 * This signal is emitted when the energy rate value of this
475 * battery has changed.
476 *
477 * If positive, the source is being discharged, if negative it's being charged.
478 *
479 * \a energyRate the new energy rate value of the battery
480 *
481 * \a udi the UDI of the battery with the new charge percent
482 */
483 void energyRateChanged(double energyRate, const QString &udi);
484
485 /*!
486 * This signal is emitted when the voltage in the cell has changed.
487 *
488 * \a voltage the new voltage of the cell
489 *
490 * \a udi the UDI of the battery with the new voltage
491 * \since 5.0
492 */
493 void voltageChanged(double voltage, const QString &udi);
494
495 /*!
496 * This signal is emitted when the battery temperature has changed.
497 *
498 * \a temperature the new temperature of the battery in degrees Celsius
499 *
500 * \a udi the UDI of the battery with the new temperature
501 * \since 5.0
502 */
503 void temperatureChanged(double temperature, const QString &udi);
504
505 /*!
506 * This signal is emitted when the estimated battery remaining time changes.
507 *
508 * \a time the new remaining time
509 *
510 * \a udi the UDI of the battery with the new remaining time
511 * \since 5.8
512 */
513 void remainingTimeChanged(qlonglong time, const QString &udi);
514};
515}
516
517#endif
518

source code of solid/src/solid/devices/frontend/battery.h