1 /*
2 * Copyright 2016-2022 The OSHI Project Contributors
3 * SPDX-License-Identifier: MIT
4 */
5 package oshi.hardware;
6
7 import java.time.LocalDate;
8
9 import oshi.annotation.concurrent.ThreadSafe;
10
11 /**
12 * The Power Source is one or more batteries with some capacity, and some state of charge/discharge
13 */
14 @ThreadSafe
15 public interface PowerSource {
16 /**
17 * Units of Battery Capacity
18 */
19 enum CapacityUnits {
20 /**
21 * MilliWattHours (mWh).
22 */
23 MWH,
24
25 /**
26 * MilliAmpHours (mAh). Should be multiplied by voltage to convert to mWh.
27 */
28 MAH,
29
30 /**
31 * Relative units. The specific units are not defined. The ratio of current/max capacity still represents state
32 * of charge and the ratio of max/design capacity still represents state of health.
33 */
34 RELATIVE;
35 }
36
37 /**
38 * Name of the power source at the Operating System level.
39 *
40 * @return The power source name, as reported by the operating system.
41 */
42 String getName();
43
44 /**
45 * Name of the power source at the device level.
46 *
47 * @return The power source name, as reported by the device itself.
48 */
49 String getDeviceName();
50
51 /**
52 * Estimated remaining capacity as a fraction of max capacity.
53 * <p>
54 * This is an estimated/smoothed value which should correspond to the Operating System's "percent power" display,
55 * and may not directly correspond to the ratio of {@link #getCurrentCapacity()} to {@link #getMaxCapacity()}.
56 *
57 * @return A value between 0.0 (fully drained) and 1.0 (fully charged)
58 */
59 double getRemainingCapacityPercent();
60
61 /**
62 * Estimated time remaining on the power source, in seconds, as reported by the operating system.
63 * <p>
64 * This is an estimated/smoothed value which should correspond to the Operating System's "battery time remaining"
65 * display, and will react slowly to changes in power consumption.
66 *
67 * @return If positive, seconds remaining. If negative, -1.0 (calculating) or -2.0 (unlimited)
68 */
69 double getTimeRemainingEstimated();
70
71 /**
72 * Estimated time remaining on the power source, in seconds, as reported by the battery. If the battery is charging,
73 * this value may represent time remaining to fully charge the battery.
74 * <p>
75 * Note that this value is not very accurate on some battery systems. The value may vary widely depending on present
76 * power usage, which could be affected by disk activity and other factors. This value will often be a higher value
77 * than {@link #getTimeRemainingEstimated()}.
78 *
79 * @return Seconds remaining to fully discharge or fully charge the battery.
80 */
81 double getTimeRemainingInstant();
82
83 /**
84 * Power Usage Rate of the battery, in milliWatts (mW).
85 *
86 * @return If positive, the charge rate. If negative, the discharge rate.
87 */
88 double getPowerUsageRate();
89
90 /**
91 * Voltage of the battery, in Volts.
92 *
93 * @return the battery voltage, or -1 if unknown.
94 */
95 double getVoltage();
96
97 /**
98 * Amperage of the battery, in milliAmperes (mA).
99 *
100 * @return the battery amperage. If positive, charging the battery. If negative, discharging the battery.
101 */
102 double getAmperage();
103
104 /**
105 * Reports whether the device is plugged in to an external power source.
106 *
107 * @return {@code true} if plugged in, {@code false} otherwise.
108 */
109 boolean isPowerOnLine();
110
111 /**
112 * Reports whether the battery is charging.
113 *
114 * @return {@code true} if the battery is charging, {@code false} otherwise.
115 */
116 boolean isCharging();
117
118 /**
119 * Reports whether the battery is discharging.
120 *
121 * @return {@code true} if the battery is discharging, {@code false} otherwise.
122 */
123 boolean isDischarging();
124
125 /**
126 * Reports =the units of {@link #getCurrentCapacity()}, {@link #getMaxCapacity()}, and {@link #getDesignCapacity()}
127 *
128 * @return The units of battery capacity.
129 */
130 CapacityUnits getCapacityUnits();
131
132 /**
133 * The current (remaining) capacity of the battery.
134 *
135 * @return The current capacity. Units are defined by {@link #getCapacityUnits()}.
136 */
137 int getCurrentCapacity();
138
139 /**
140 * The maximum capacity of the battery. When compared to design capacity, permits a measure of battery state of
141 * health. It is possible for max capacity to exceed design capacity.
142 *
143 * @return The maximum capacity. Units are defined by {@link #getCapacityUnits()}.
144 */
145 int getMaxCapacity();
146
147 /**
148 * The design (original) capacity of the battery. When compared to maximum capacity, permits a measure of battery
149 * state of health. It is possible for max capacity to exceed design capacity.
150 *
151 * @return The design capacity. Units are defined by {@link #getCapacityUnits()}.
152 */
153 int getDesignCapacity();
154
155 /**
156 * The cycle count of the battery, if known.
157 *
158 * @return The cycle count of the battery, or -1 if unknown.
159 */
160 int getCycleCount();
161
162 /**
163 * The battery chemistry (e.g., Lithium Ion).
164 *
165 * @return the battery chemistry.
166 */
167 String getChemistry();
168
169 /**
170 * The battery's date of manufacture.
171 * <p>
172 * Some battery manufacturers encode the manufacture date in the serial number. Parsing this value is operating
173 * system and battery manufacturer dependent, and is left to the user.
174 *
175 * @return the manufacture date, if available. May be {@code null}.
176 */
177 LocalDate getManufactureDate();
178
179 /**
180 * The name of the battery's manufacturer.
181 *
182 * @return the manufacturer name.
183 */
184 String getManufacturer();
185
186 /**
187 * The battery's serial number.
188 * <p>
189 * Some battery manufacturers encode the manufacture date in the serial number. Parsing this value is operating
190 * system and battery manufacturer dependent, and is left to the user.
191 *
192 * @return the serial number.
193 */
194 String getSerialNumber();
195
196 /**
197 * The battery's temperature, in degrees Celsius.
198 *
199 * @return the battery's temperature, or 0 if uknown.
200 */
201 double getTemperature();
202
203 /**
204 * Updates statistics on this battery.
205 *
206 * @return {@code true} if the update was successful. If {@code false} the battery statistics are unchanged.
207 */
208 boolean updateAttributes();
209 }