1# System Brightness Customization
2
3## Overview
4
5### Introduction
6
7By default, the system brightness of OpenHarmony ranges from **0** to **255** (**0** indicates the minimum luminance and **255** the maximum). It is applicable to the entire system and all application windows. Due to hardware restrictions, some display devices are unable to support the system brightness range. To address this issue, OpenHarmony provides the function of customizing the system brightness range. This way, you can adjust the system brightness range based on the hardware specifications of the display devices.
8
9### Basic Concepts
10
11**System brightness**
12Global brightness of OpenHarmony. The customized brightness range is effective for all application windows.
13
14**Window brightness**
15Brightness of an application window. The customized brightness range is effective only for this application window. After a brightness is specified for an application window, its brightness is not affected by the system brightness.
16
17### Constraints
18
19The [sysparam](./subsys-boot-init-sysparam.md) module of OpenHarmony provides an easy-to-use key-value pair access interface for system services to configure service functions based on their own system parameters. The customization of the system brightness range is dependent on this feature.
20
21## How to Develop
22
23### Setting Up the Environment
24
25**Hardware requirements:**
26
27Development board running the standard system, for example, the DAYU200 or Hi3516D V300 open source suite.
28
29**Environment requirements:**
30
31For details about the requirements on the Linux environment, see [Quick Start](../quick-start/Readme-EN.md).
32
33### Getting Started with Development
34
351. In the target directory, create a target folder by referring to the [default brightness value configuration folder](https://gitee.com/openharmony/powermgr_display_manager/tree/master/service/etc). The content is as follows:
36
37    ```text
38    etc
39    ├── BUILD.gn
40    ├── display.para
41    ├── display.para.dac
42    ```
43
442. Write the customized **display.para** file by referring to the [**display.para** file](https://gitee.com/openharmony/powermgr_display_manager/blob/master/service/etc/display.para) in the default brightness range configuration folder. Include the customized brightness thresholds, for example, **max=150**, **default=75**, and **min=50**, into the file:
45
46    ```shell
47    # Brightness limits is 0-255.
48    const.display.brightness.min=50
49    const.display.brightness.default=75
50    const.display.brightness.max=150
51    ```
52
533. Write the customized **display.para.dac** file by referring to the [**display.para.dac** file](https://gitee.com/openharmony/powermgr_display_manager/blob/master/service/etc/display.para.dac) in the default brightness range configuration folder, so as to grant the permission required to access the customized configuration.
54
55    ```shell
56    const.display.brightness.="foundation:foundation:444"
57    ```
58
594. Write the customized **BUILD.gn** file by referring to the [**BUILD.gn** file](https://gitee.com/openharmony/powermgr_display_manager/blob/master/service/etc/BUILD.gn) in the default brightness range configuration folder. Then, put the **display.para** and **display.para.dac** files to the **/vendor/etc/param** directory. For example:
60
61    ```shell
62    import("//base/powermgr/display_manager/displaymgr.gni")
63    import("//build/ohos.gni")
64
65    ## Install display.para to /vendor/etc/param/display.para
66    ohos_prebuilt_etc("display.para") {
67    source = "display.para"
68    relative_install_dir = "param"
69    install_images = [ chipset_base_dir ]
70    part_name = "${displaymgr_part_name}"
71    subsystem_name = "powermgr"
72    }
73
74    ohos_prebuilt_etc("display.para.dac") {
75    source = "display.para.dac"
76    relative_install_dir = "param"
77    install_images = [ chipset_base_dir ]
78    part_name = "${displaymgr_part_name}"
79    subsystem_name = "powermgr"
80    }
81
82    group("param_files") {
83    deps = [
84        ":display.para",
85        ":display.para.dac",
86    ]
87    }
88    ```
89
905. Write the customized **bundle.json** file by referring to the [**bundle.json** file](https://gitee.com/openharmony/powermgr_display_manager/blob/master/bundle.json) in the default brightness range configuration folder, so as to compile the **BUILD.gn** file.
91
92    ```shell
93    "service_group": [ "//base/powermgr/display_manager/service/etc:param_files" ]
94    ```
95    In the preceding code, **//base/powermgr/display_manager/service** indicates the directory of the created folder, and **etc** indicates the folder name.
96
976. Build the customized version by referring to [Quick Start](../quick-start/Readme-EN.md). The following command uses DAYU200 as an example:
98
99    ```shell
100    ./build.sh --product-name rk3568 --ccache
101    ```
102
1037. Burn the customized version to the DAYU200 development board.
104
105### Debugging and Verification
106
1071. After startup, run the following command to launch the shell command line:
108
109    ```shell
110    hdc shell
111    ```
112
1132. Run the following command to check the console output:
114
115    ```shell
116    hidumper -s 3308 -a -a
117    ```
118
1193. Check the console output for the customized system brightness thresholds.
120
121    The default system brightness thresholds are as follows:
122
123    ```shell
124    ----------------------------------DisplayPowerManagerService---------------------------------
125    DISPLAY POWER MANAGER DUMP:
126    Display Id=0 State=2 Discount=1.000000 Brightness=102
127    DeviceBrightness=102
128    Support Ambient Light: FALSE
129    Auto Adjust Brightness: OFF
130    Brightness Limits: Max=255 Min=5 Default=102
131
132    ```
133
134    Assume that the system brightness thresholds are set to **Max=150 Min=50 Default=75**. The console output is as follows:
135
136    ```shell
137    # cd vendor/etc/param
138    # ls
139    display.para      thermal.para      usb.para.dac
140    display.para.dac  thermal.para.dac
141    # cat display.para
142    # Copyright (C) 2022 Huawei Device Co., Ltd.
143    # Licensed under the Apache License, Version 2.0 (the "License");
144    # you may not use this file except in compliance with the License.
145    # You may obtain a copy of the License at
146    #
147    #     http://www.apache.org/licenses/LICENSE-2.0
148    #
149    # Unless required by applicable law or agreed to in writing, software
150    # distributed under the License is distributed on an "AS IS" BASIS,
151    # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
152    # See the License for the specific language governing permissions and
153    # limitations under the License.
154
155    # Brightness limits is 0-255.
156    const.display.brightness.min=50
157    const.display.brightness.default=75
158    const.display.brightness.max=150#
159    #
160    # cd
161    # hidumper -s 3308 -a -a
162
163    -------------------------------[ability]-------------------------------
164
165
166    ----------------------------------DisplayPowerManagerService---------------------------------
167    DISPLAY POWER MANAGER DUMP:
168    Display Id=0 State=0 Discount=1.000000 Brightness=75
169    DeviceBrightness=75
170    Support Ambient Light: FALSE
171    Auto Adjust Brightness: OFF
172    Brightness Limits: Max=150 Min=50 Default=75
173
174    ```
175
1764. Set the system brightness thresholds to the customized values.
177
178## Reference
179
180For details about how to write the configuration file during system brightness customization, refer to the [default brightness range configuration file](https://gitee.com/openharmony/powermgr_display_manager/tree/master/service/etc).
181
182Default configuration:
183
184```shell
185# Brightness limits is 0-255.
186const.display.brightness.min=5
187const.display.brightness.default=102
188const.display.brightness.max=255
189```
190
191Packing directory: /system/etc/param
192