1# Power Consumption Statistics Customization
2
3## Overview
4
5### Introduction
6
7By default, OpenHarmony provides the power consumption statistics feature. However, the power consumption benchmarks vary according to hardware specifications of different products. To address this issue, OpenHarmony provides the power consumption statistics customization function, allowing you to customize power consumption benchmarks depending on your hardware specifications.
8
9### Basic Concepts
10
11Power consumption statistics: When a user uses a device, software and hardware services running on the device report usage events through [HiSysEvent](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-overview.md). The usage duration of software and hardware can be calculated based on these reported events. Then, the power consumption of the software and hardware can be calculated based on the hardware power consumption benchmarks.
12
13Power consumption benchmark: baseline power consumption (unit: mA) of the product hardware in various states, for example, the baseline power consumption when the camera is turned on and the baseline power consumption of the CPU at different frequencies.
14
15### Constraints
16
17The configuration path for power consumption statistics customization is subject to the [configuration policy](https://gitee.com/openharmony/customization_config_policy). In this development guide, `/vendor` is used as an example of the configuration path. During actual development, you need to modify the customization path based on the product configuration policy.
18
19## How to Develop
20
21### Setting Up the Environment
22
23**Hardware requirements:**
24
25Development board running the standard system, for example, the DAYU200 or Hi3516D V300 open source suite.
26
27**Environment requirements:**
28
29For details about the requirements on the Linux environment, see [Quick Start](../quick-start/quickstart-overview.md).
30
31### Getting Started with Development
32
33The following uses [DAYU200](https://gitee.com/openharmony/vendor_hihope/tree/master/rk3568) as an example to illustrate power consumption statistics customization.
34
351. Create the `battery_statistics` folder in the product directory [/vendor/hihope/rk3568](https://gitee.com/openharmony/vendor_hihope/tree/master/rk3568).
36
37
382. Create a target folder by referring to the [default folder of power consumption statistics configuration](https://gitee.com/openharmony/powermgr_battery_statistics/tree/master/services/profile), and install it in `//vendor/hihope/rk3568/battery_statistics`. The content is as follows:
39
40    ```shell
41    profile
42    ├── BUILD.gn           # BUILD.gn file
43    └── power_average.json # Configuration file for power consumption statistics, including the hardware power consumption benchmarks
44    ```
45
463. Write the custom `power_average.json` file by referring to the [power_average.json](https://gitee.com/openharmony/powermgr_battery_statistics/blob/master/services/profile/power_average.json) file in the default folder of power consumption statistics configuration. The following table describes the configuration items for power consumption benchmarks.
47
48    **Table 1** Description of the configuration items for power consumption benchmarks
49    | Configuration Item| Hardware Type| Data Type| Description|
50    |----------|------|---------|-------------------------------------------------------------------------|
51    | alarm_on | - | Double | Power consumption when the timer is triggered by the system or application once; that is, the baseline power consumption.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Number of triggering times x Power consumption benchmark|
52    | bluetooth_br_on | Bluetooth | Double | Baseline power consumption when Bluetooth is enabled.<br>- Power consumption type: hardware power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
53    | bluetooth_br_scan | Bluetooth | Double | Baseline power consumption for Bluetooth scanning.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
54    | bluetooth_ble_on | Bluetooth | Double | Baseline power consumption when Bluetooth Low Energy (BLE) is enabled.<br>- Power consumption type: hardware power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
55    | bluetooth_ble_scan | Bluetooth | Double | Baseline power consumption for Bluetooth Low Energy (BLE) scanning.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
56    | wifi_on | WIFI | Double | Baseline power consumption when Wi-Fi is enabled.<br>- Power consumption type: hardware power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
57    | wifi_scan | WIFI | Double | Power consumption when Wi-Fi scanning is performed once.<br>- Power consumption type: hardware power consumption<br>- Statistical method: Power consumption = Number of triggering times x Power consumption benchmark|
58    | radio_on | Phone | Double array| Baseline power consumption when the call service is enabled. The value is in array format and is used to configure the baseline power consumption for different signal strength levels. The default configuration provides the baseline power consumption for four signal strength levels.<br>- Power consumption type: hardware power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
59    | radio_data | Phone | Double array| Baseline power consumption when the network service is enabled. The value is in array format and is used to configure the baseline power consumption for different signal strength levels. The default configuration provides the baseline power consumption for four signal strength levels.<br>- Power consumption type: hardware power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
60    | camera_on | Camera | Double | Baseline power consumption when the camera is enabled.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
61    | flashlight_on | Flashlight | Double | Baseline power consumption when the flashlight is enabled.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
62    | gnss_on | GNSS | Double | Baseline power consumption when the Global Navigation Satellite System (GNSS) is enabled.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
63    | sensor_gravity_on | Gravity Sensor | Double | Baseline power consumption when the gravity sensor is enabled.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
64    | sensor_proximity_on | Proximity Sensor | Double | Baseline power consumption when the proximity sensor is enabled.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
65    | audio_on | Audio | Double | Baseline power consumption when the audio is enabled.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
66    | screen_on<br>screen_brightness | Screen | Double | **screen\_on**: baseline power consumption of the screen in the basic state (excluding power consumption generated by screen brightness).<br>**screen\_brightness**: baseline power consumption additionally required when the screen brightness increases by one level.<br>For example, if **screen_on** is **90**, **screen_brightness** is **2**, and the screen brightness is **100**, then the baseline power consumption is calculated as follows: 90 + 2 x 100 = 290.<br>- Power consumption type: hardware power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
67    | cpu_awake | CPU | Double | Baseline power consumption when the CPU wakes up the lock from the lock holding state.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
68    | cpu_idle | CPU | Double | Baseline power consumption when the CPU is in the idle state.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
69    | cpu_suspend | CPU | Double | Baseline power consumption when the CPU is in the sleep state.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
70    | cpu_active | CPU | Double | Baseline power consumption when the CPU is in the active state.<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
71    | cpu_clusters<br>cpu_speed_clusterX | CPU | Double array| **cpu\_clusters**: baseline power consumption of a CPU cluster. The value is in array format and is used to configure the baseline power consumption for different CPU clusters. The default configuration provides the baseline power consumption for three CPU clusters.<br>**cpu\_speed\_clusterX**: baseline power consumption of a CPU cluster at different frequencies, in array format. **X** indicates the sequence number. By default, its value ranges from **0** to **2**, corresponding to the size of the **cpu_clusters** array. For example, if the default size of the **cpu_clusters** array is **3**, the sequence number corresponds to the configuration items **cpu_speed_cluster0**, **cpu_speed_cluster1**, and **cpu_speed_cluster2**.<br>- Scalability: scalability of CPU clusters<br>- Power consumption type: software power consumption<br>- Statistical method: Power consumption = Usage duration x Power consumption benchmark|
72
73    >**NOTE**<br>The hardware type described in the table is the actual hardware name and does not represent the power consumption statistics type. For details about the power consumption statistics type, see [ConsumptionType](https://gitee.com/openharmony/docs/blob/master/en/application-dev/reference/apis/js-apis-batteryStatistics.md#consumptiontype).
74
754. Write the `BUILD.gn` file by referring to the [BUILD.gn](https://gitee.com/openharmony/powermgr_battery_statistics/blob/master/services/profile/BUILD.gn) file in the default folder of power consumption statistics configuration to pack the `power_average.json` file to the `//vendor/etc/profile` directory. The configuration is as follows:
76
77    ```shell
78    import("//build/ohos.gni")                  # Reference build/ohos.gni.
79
80    # Install power_average.json to /vendor/etc/profile/power_average.json
81    ohos_prebuilt_etc("power_average_config") { # Custom name, for example, power_average_config.
82        source = "power_average.json"
83        relative_install_dir = "profile"
84        install_images = [ chipset_base_dir ]   # Required configuration for installing the power_average_config file in the vendor directory, where chipset_base_dir = "vendor". If this field is left unspecified, the power_average_config file is installed in the system directory by default.
85        part_name = "product_rk3568"            # Set part_name to product_rk3568 for subsequent build.
86    }
87    ```
88
895. Add the build target to `module_list` in [ohos.build](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/ohos.build) in the `/vendor/hihope/rk3568` directory. For example:
90
91    ```json
92    {
93      "parts": {
94          "product_rk3568": {
95          "module_list": [
96              "//vendor/hihope/rk3568/default_app_config:default_app_config",
97              "//vendor/hihope/rk3568/image_conf:custom_image_conf",
98              "//vendor/hihope/rk3568/battery_statistics/profile:power_average_config", # Add the configuration for building of power_average_config.
99              "//vendor/hihope/rk3568/preinstall-config:preinstall-config",
100              "//vendor/hihope/rk3568/resourceschedule:resourceschedule",
101              "//vendor/hihope/rk3568/etc:product_etc_conf"
102          ]
103          }
104      },
105      "subsystem": "product_hihope"
106    }
107    ```
108
109    In the preceding code, `//vendor/hihope/rk3568/power/battery_statistics/` is the folder path, `profile` is the folder name, and `power_average_config` is the build target.
110
1116. Build the customized version by referring to [Quick Start](../quick-start/quickstart-overview.md).
112
113    ```shell
114    ./build.sh --product-name rk3568 --ccache
115    ```
116
1177. Burn the customized version to the DAYU200 development board.
118
119### Debugging and Verification
120
1211. After startup, run the following command to launch the shell command line:
122
123    ```shell
124    hdc shell
125    ```
126
1272. Run the following command to check whether the `power\_average\_config` file is successfully created in the `vendor` directory:
128
129    ```shell
130    ls -l /vendor/etc/profile/
131    ```
132
133    The `power\_average\_config` file is successfully created if it exists in `/vendor/etc/profile/`.
134
135    ```shell
136    # ls -l /vendor/etc/profile/
137    total 4
138    -rw-r--r-- 1 root root 1446 2023-03-26 16:47 power_average.json
139    #
140    ```
141
1423. If the `power_average_config` file is successfully created, run the following command to check whether the information in the `power_average_config` file in the `vendor` directory is consistent with the customized information:
143
144    ```shell
145    cat /vendor/etc/profile/power_average.json
146    ```
147
1484. If the information is consistent, run the following command to view the power consumption statistics:
149
150    ```shell
151    hidumper -s 3304 -a -poweraverage
152    ```
153
1545. Check the console output for the custom power consumption benchmark information.
155
156    For example, the default power consumption benchmark information is as follows:
157
158    ```shell
159    # hidumper -s 3304 -a -poweraverage
160
161    -------------------------------[ability]-------------------------------
162
163
164    ----------------------------------BatteryStatisticsService---------------------------------
165    POWER AVERAGE CONFIGATION DUMP:
166
167    ··· (Only the camera configuration is displayed here. Other information is omitted.)
168
169    camera_on : 810.000000
170
171    ······
172    ```
173
174    If the power consumption statistics benchmark is set to **camera_on:3000** (default value: **810**), the console output is as follows:
175
176    ```shell
177    # hidumper -s 3304 -a -poweraverage
178
179    -------------------------------[ability]-------------------------------
180
181
182    ----------------------------------BatteryStatisticsService---------------------------------
183    POWER AVERAGE CONFIGATION DUMP:
184
185    ··· (Only the camera configuration is displayed here. Other information is omitted.)
186
187    camera_on : 3000.000000 # Set the power consumption benchmark to "camera_on": 3000.
188
189    ······
190    ```
191
1926. Check whether the power consumption statistics are calculated according to the custom power consumption benchmark in the `power_average_config` file.
193
1947. You can use the [JS APIs](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.batteryStatistics.d.ts) or [Inner APIs](https://gitee.com/openharmony/powermgr_battery_statistics/blob/master/interfaces/inner_api/include/battery_stats_client.h) provided by the **batterystatistics** module to obtain detailed power consumption information and verify the custom power consumption benchmark.
195
196## Reference
197
198During development, you can refer to the [default power consumption statistics configuration](https://gitee.com/openharmony/powermgr_battery_statistics/blob/master/services/profile/power_average.json).
199
200Default packing path: `/system/etc/profile`
201
202Customization path: `/vendor/etc/profile`
203