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 and multi-system deployment" of the light driver. [Figure 1](#lightmodel) shows the light driver model.
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. The figure below shows the light driver model.
**Figure 1** Light driver model
...
...
@@ -13,7 +13,7 @@ The light driver model provides APIs for the upper-layer light hardware service
### Working Principles
[Figure 2](#lightworking) shows how the light driver works.
The figure below shows how the light driver works.
**Figure 2** How light driver works
...
...
@@ -24,43 +24,35 @@ The following uses the Hi3516D V300 development board powered by the standard sy
1. The light driver reads the light device management configuration from **Light Host** in the **device_info.hcs** file.
2. The light driver reads the light data configuration from the **light_config.hcs** file.
3. The light driver parses information about the light device management configuration and associates with the corresponding device driver.
4. The client delivers the Light Stub control to the server.
5. The server invokes the Light Stub control.
4. The light proxy delivers an instruction to the light stub.
5. The light stub delivers an instruction to the light controller.
6. The light abstract driver interface is started.
## Development Guidelines
### When to Use
Light control is widely used in daily life. For example, a light is blinking when a mobile phone receives a short message or has low battery level, and a light changes its colors based on the device charging status. These actions are implemented by calling the APIs provided by the light driver model.
Light control is widely used in daily life. For example, a light is blinking when a mobile phone receives an SMS message or has low battery level, and a light changes its colors based on the device charging status. These actions are implemented by calling the APIs provided by the light driver model.
### Available APIs
[Table 1](#light_driver_apis) describes the APIs provided by the light driver model.
The 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 table below describes the APIs of the light driver model.
| int32_t (*GetLightInfo)(struct LightInfo **lightInfo, uint32_t *count) | Obtains information about all lights in the system. **lightInfo** indicates the pointer to the basic light information. **count** indicates the pointer to the number of lights.|
| 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 effect.|
| int32_t (*TurnOffLight)(uint32_t type) | Turns off available lights in the light list based on the specified light type. |
| 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.|
| 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.|
| 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. |
### How to Develop
1. Based on the HDF and the driver entry, complete the light abstract driver development (using the **Bind**, **Init**, **Release**, and **Dispatch** functions), resource configuration, and HCS parsing. Configure the light driver device information.
3. Parse the device attribute information and registers, and register them with the light device management module.
3. Call related APIs to obtain the light type, turn on and off lights, and create and delete the timer based on the blinking mode.
### Development Example
This example shows how to load and start the light driver based on the HDF driver model. For details about the working principles, see [HDF Driver Development Guide](driver-hdf-development.md). In this example, the communication interface mode of the light driver is GPIO.
1. Initialize the light driver.
1. Based on the HDF and the driver entry, complete the light abstract driver development (using the **Bind**, **Init**, **Release**, and **Dispatch** functions), resource configuration, and HCS parsing. Configure the light driver device information.
- Call **HDF_INIT** to register the driver entry with the HDF. Generally, the HDF calls the **Bind** function and then the **Init** function to load the driver. If **Init** fails to be called, the HDF calls **Release** to release driver resources and exit.
The light driver model uses HDF configuration source (HCS). For details about HCS fields, see [Configuration Management](https://gitee.com/openharmony/docs/blob/master/en/device-dev/driver/driver-hdf-manage.md).
The light driver entry is defined as follows:
```c
/* Register the light entry data structure object. */
struct HdfDriverEntry g_lightDriverEntry = {
...
...
@@ -70,10 +62,10 @@ This example shows how to load and start the light driver based on the HDF drive
.Init = InitLightDriver, // Initialize the light driver.
.Release = ReleaseLightDriver, // Release the light resources.
};
// Call HDF_INIT to register the driver entry with the HDF. The HDF calls the Bind function and then the Init function to load a driver. If Init fails to be called, the HDF calls Release to release driver resources and exit. */
/* Call HDF_INIT to register the driver entry with the HDF. The HDF calls the Bind function and then the Init function to load a driver. If Init fails to be called, the HDF calls Release to release driver resources and exit. */
HDF_INIT(g_lightDriverEntry);
```
- Develop the light abstract driver. Specifically, implement the **Bind**, **Init**, **Release**, and **Dispatch** functions.
```c
...
...
@@ -159,16 +151,15 @@ This example shows how to load and start the light driver based on the HDF drive
(void)OsalMemFree(drvData);
g_lightDrvData = NULL;
}
```
- The light device management module dispatches light device APIs in the system. During the system startup process, the HDF loads the device management driver from the HCS of the light host.
```hcs
```
/* Light device HCS */
device_light :: device {
device0 :: deviceNode {
policy = 2; // Driver service dispatch policy (0: no service is provided; 1: services are dispatched to the kernel mode; 2: services are dispatched to both the kernel mode and user mode)
policy = 2; // Driver service dispatch policy (0: no service is dispatched; 1: services are dispatched to the kernel mode; 2: services are dispatched to both the kernel mode and user mode)
priority = 100; // Light driver startup priority. The value ranges from 0 to 200. A larger value indicates a lower priority. The value 100 is recommended. If the priorities are the same, the device loading sequence cannot be ensured.
preload = 0; // Field for specifying whether to load the driver. The value 0 means to load the driver, and 2 means the opposite.
permission = 0664; // Permission for the driver to create a device node.
...
...
@@ -176,70 +167,42 @@ This example shows how to load and start the light driver based on the HDF drive
serviceName = "hdf_light"; // Service name of the driver, which must be unique.
deviceMatchAttr = "hdf_light_driver"; // Keyword for matching the private data of the driver. The value must be the same as that of match_attr in the private data configuration table of the driver.
}
}
```
2.Allocate resources and parse the HCS.
2.Parse the device attribute information and registers, and register them with the light device management module.
- The light effect model uses the HCS. For details about HCS fields, see [Configuration Management](https://gitee.com/openharmony/docs/blob/master/en/device-dev/driver/driver-hdf-manage.md).
```hcs
/* Light data configuration template (light_config.hcs) */
