• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Light
2
3## Introduction
4
5 The light driver model provides APIs for the upper-layer light hardware service layer to control lights, including obtaining the light type, setting the lighting mode and blinking effect, and turning on or off a light. This model implements functionalities such as cross-OS migration and differentiated configurations based on the Hardware Driver Foundation (HDF) to achieve the goal of "one-time development for cross-system deployment" of the light driver.
6
7**Figure 1** Light driver model
8
9![Light driver model](figures/light_driver_model.png)
10
11## Directory Structure
12
13The directory structure of the light module is as follows:
14
15```
16/drivers/peripheral/misc/light
17├── hal              # HAL code
18│   ├── include      # HAL header files
19│   └── src          # HAL code implementation
20├── interfaces       # Driver capability APIs provided for upper-layer services
21│   └── include      # APIs exposed externally
22└── test             # Test code
23    └── unittest     # Unit test code
24```
25
26## Usage
27
28### Available APIs
29
30The light driver model provides APIs to obtain information about all the lights in the system and dynamically set the blinking mode and duration. The light hardware service calls the **GetLightInfo** method to obtain basic information about the light and calls the **TurnOnLight** method to make the light blinking. The following table describes these APIs.
31
32**Table 1** Major APIs of the light module
33
34| API                                                      | Description                                                    |
35| ------------------------------------------------------------ | ------------------------------------------------------------ |
36| int32_t (*GetLightInfo)(struct LightInfo **lightInfo, uint32_t *count) | Obtains information about all lights in the system. **lightInfo** indicates the double pointer to the basic light information. **count** indicates the pointer to the number of lights.|
37| int32_t (*TurnOnLight)(uint32_t type, struct LightEffect *effect) | Turns on available lights in the list based on the specified light type. **type** indicates the light type, and **effect** indicates the pointer to the blinking effect.|
38| int32_t (*TurnOffLight)(uint32_t type)                       | Turns off available lights in the light list based on the specified light type. **type** indicates the light type.                                          |
39
40### How to Use
41
42The following provides the sample code for the small system.
43
44```c++
45#include "light_if.h"
46
47void LightSample(void)
48{
49	int32_t ret;
50    static struct LightInfo *g_lightInfo = nullptr;
51    static uint32_t g_count = 0;
52    const int32_t g_onTime = 500;
53    const int32_t g_offTime = 500;
54    const int32_t LIGHT_WAIT_TIME = 30;
55    const int32_t g_minLightType = LIGHT_TYPE_NONE;
56    const int32_t g_maxLightType = LIGHT_TYPE_BUTT;
57    struct LightEffect effect;
58
59	/* Create a LightInterface instance. */
60    struct LightInterface *g_lightDev = NewLightInterfaceInstance();
61    if (g_lightDev == NULL) {
62        return;
63    }
64	/* Obtain the list of lights supported by the device. */
65 	ret = g_lightDev->GetLightInfo(&g_lightInfo, &g_count);
66
67    /* Turn on the available lights of the specified color in the list and make it steady on. */
68    effect.lightBrightness = 0x80000000; // Brightness value. The most significant bit indicates the color. Bits16–31 for red, bits 8–15 for green, and bits 0–7 for blue. */
69    effect.flashEffect.flashMode = LIGHT_FLASH_NONE;
70
71    for (i = 0; i < g_count; ++i) {
72        ret = g_lightDev->TurnOnLight(g_lightInfo[i].lightType, &effect);
73        EXPECT_EQ(0, ret);
74
75        OsalSleep(LIGHT_WAIT_TIME);
76
77        ret = g_lightDev->TurnOffLight(g_lightInfo[i].lightType);
78        EXPECT_EQ(0, ret);
79    }
80    /* Turn on the available lights of the specified color in the list and make it blinking. */
81    effect.lightBrightness = 0x80000000;
82    effect.flashEffect.flashMode = LIGHT_FLASH_TIMED;
83    effect.flashEffect.onTime = g_onTime;    // Light on time in a blinking period, in ms
84    effect.flashEffect.offTime = g_offTime;    // Light off time in a blinking period, in ms
85
86    for (i = 0; i < g_count; ++i) {
87        ret = g_lightDev->TurnOnLight(g_lightInfo[i].lightType, &effect);
88        EXPECT_EQ(0, ret);
89
90        OsalSleep(LIGHT_WAIT_TIME);
91
92        ret = g_lightDev->TurnOffLight(g_lightInfo[i].lightType);
93        EXPECT_EQ(0, ret);
94    }
95
96    /* Turn off the light of the specified type in the light list. */
97    ret = g_lightDev->TurnOffLight(lightType);
98    EXPECT_EQ(0, ret);
99
100    /* Release the LightInterface instance. */
101    if (g_lightDev != nullptr) {
102        FreeLightInterfaceInstance();
103        g_lightDev = nullptr;
104    }
105}
106```
107
108## Repositories Involved
109
110[Drive Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/driver.md)
111
112[drivers_framework](https://gitee.com/openharmony/drivers_framework/blob/master/README.md)
113
114[drivers_adapter](https://gitee.com/openharmony/drivers_adapter/blob/master/README.md)
115
116[drivers_adapter_khdf_linuk](https://gitee.com/openharmony/drivers_adapter_khdf_linux/blob/master/README.md)
117[drivers_peripheral](https://gitee.com/openharmony/drivers_peripheral)
118
119[drivers_interface](https://gitee.com/openharmony/drivers_interface)
120