Pulse width modulation (PWM) is a method used to digitally encode analog signal levels and convert them into pulses. It can be used for motor control and backlight brightness adjustment.
## Overview
Pulse width modulation (PWM) is a technology that digitally encodes analog signal levels and converts them into pulses. It can be used for motor control and backlight brightness adjustment.
The PWM APIs provide a set of functions for operating a PWM device, including those for:
- Opening or closing a PWM device handle
The PWM APIs provide a set of functions for operating a PWM device, including those for:
- Obtaining and releasing a PWM device handle
- Setting the PWM period, signal ON-state time, and polarity
- Setting the PWM period, signal ON-state time, and polarity
| duty | Time that a signal is in the ON state, in ns.|
| duty | Time that a signal is in the ON state, in ns.|
| period | Time for a signal to complete an on-and-off cycle, in ns.|
| period | Time for a signal to complete an on-and-off cycle, in ns.|
| number | Number of square waves to generate. A positive value indicates the number of square waves to generate. The value <b>0</b> means to generate square waves repeatedly.|
| number | Number of square waves to generate.<br>- Positive value: indicates the number of square waves to generate.<br>- **0**: indicates that square waves are generated continuously.|
| polarity | PWM signal polarity, which can be **PWM\_NORMAL\_POLARITY** or **PWM\_INVERTED\_POLARITY**.|
| polarity | PWM signal polarity, which can be positive or reverse.|
| status | PWM device status, which can be enabled or disabled.|
| status | PWM device status, which can be enabled or disabled.|
| Operating PWM handles| - **PwmOpen**: opens the device handle of a PWM device.<br>- **PwmClose**: closes the device handle of a PWM device.|
<tbody><trheight="19"style="height:14.25pt">
| Enabling or disabling PWM| - **PwmEnable**: enables a PWM device.<br>- **PwmDisable**: disables a PWM device.|
| Setting PWM| - **PwmSetPeriod**: sets the PWM period.<br>- **PwmSetDuty**: sets the signal ON-state time.<br>- **PwmSetPolarity**: sets the PWM signal polarity.|
During the OS startup process, the driver management module loads the PWM driver based on the configuration file. Then, the PWM driver detects the PWM device and initializes the driver.
[Figure 1](#fig1_PWM_des) shows the general process of using the PWM module.
**Figure 1** Process of using the PWM module<aname="fig1_PWM_des"></a>
### How to Use
The figure below shows the general process of using the PWM.
**Figure 1** Process of using the PWM module
![](figures/process-of-using-PWM.png)
![](figures/process-of-using-PWM.png)
### Opening a PWM Device Handle<a name="section3.2_PWM_des"></a>
### Opening a PWM Device Handle
Before performing operations on a PWM device, call **PwmOpen** to open the device handle.
Before performing operations on a PWM device, call **PwmOpen** to open the device handle.
```c
```
DevHandle PwmOpen(uint32_t num);
DevHandle PwmOpen(uint32_t num);
```
```
**Table 3** PwmOpen
**Table 3** Description of PwmOpen
<aname="table3_PWM_des"></a>
| Parameter| Description|
| **Parameter**| **Description**|
| ---------- | ----------------------- |
| -------- | -------- |
| num | PWM device number.|
| num | PWM device number.|
| **Return Value** | **Description**|
| **Return Value** | **Description**|
| handle | Handle of the PWM device obtained.|
| handle | Handle of the PWM device obtained.|
| NULL | The operation fails.|
| NULL | The operation fails. |
Example: Open the device handle of PWM device 0.
```c
```
uint32_t num = 0; /* PWM device number. */
uint32_t num = 0; /* PWM device number. */
DevHandle handle = NULL;
DevHandle handle = NULL;
...
@@ -128,48 +87,49 @@ if (handle == NULL) {
...
@@ -128,48 +87,49 @@ if (handle == NULL) {
}
}
```
```
### Closing a PWM Device Handle<a name="section3.3_PWM_des"></a>
Close a PWM device to release resources.
### Closing a PWM Device Handle
```c
Call **PwmClose()** to close a PWM device handle to release resources.
voidPwmClose(DevHandlehandle);
```
**Table 4** PwmClose
<aname="table4_PWM_des"></a>
```
voidPwmClose(DevHandle handle);
```
| Parameter| Description|
**Table 4** Description of PwmClose
| ------ | ----------- |
| handle | PWM device handle to close.|
| **Parameter**| **Description**|
| -------- | -------- |
| handle | PWM device handle to close. |
```c
```
/* Close a PWM device handle. */
/* Close a PWM device handle. */
PwmClose(handle);
PwmClose(handle);
```
```
### Enabling a PWM Device<a name="section3.4_PWM_des"></a>
Enable a PWM device.
### Enabling a PWM Device
Call **PwmEnable()** to enable a PWM device.
```c
```
int32_t PwmEnable(DevHandle handle);
int32_t PwmEnable(DevHandle handle);
```
```
**Table 5** PwmEnable
**Table 5** Description of PwmEnable
<aname="table5_PWM_des"></a>
| **Parameter**| **Description**|
| -------- | -------- |
| Parameter| Description|
| handle | PWM device handle. |
| ---------- | -------------- |
| handle | PWM device handle.|
| **Return Value** | **Description** |
| **Return Value** | **Description** |
| 0 | The operation is successful.|
| 0 | The operation is successful. |
| Negative number| The operation fails.|
| Negative number | The operation fails. |
```c
```
int32_t ret;
int32_t ret;
/* Enable a PWM device. */
/* Enable a PWM device. */
...
@@ -179,26 +139,27 @@ if (ret != 0) {
...
@@ -179,26 +139,27 @@ if (ret != 0) {
}
}
```
```
### Disabling a PWM Device<a name="section3.5_PWM_des"></a>
Disable a PWM device.
### Disabling a PWM Device
Call **PwmDisable()** to disable a PWM device.
```c
```
int32_t PwmDisable(DevHandle handle);
int32_t PwmDisable(DevHandle handle);
```
```
**Table 6** PwmDisable
**Table 6** Description of PwmDisable
<aname="table6_PWM_des"></a>
| **Parameter**| **Description**|
| -------- | -------- |
| Parameter| Description|
| handle | PWM device handle. |
| ---------- | -------------- |
| handle | PWM device handle.|
| **Return Value** | **Description** |
| **Return Value** | **Description** |
| 0 | The operation is successful.|
| 0 | The operation is successful.|
| Negative number| The operation fails.|
| Negative number | The operation fails. |
```c
```
int32_t ret;
int32_t ret;
/* Disable a PWM device. */
/* Disable a PWM device. */
...
@@ -208,27 +169,28 @@ if (ret != 0) {
...
@@ -208,27 +169,28 @@ if (ret != 0) {
}
}
```
```
### Setting the PWM Period<a name="section3.6_PWM_des"></a>