MT2523 API Reference  LinkIt SDK v4
PWM

This section introduces the Pulse-Width Modulation(PWM) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, PWM function groups, enums, structures and functions. More...

Overview

This section introduces the Pulse-Width Modulation(PWM) APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, PWM function groups, enums, structures and functions.

Terms and acronyms

Terms Details
PWM Pulse-Width Modulation. PWM is a modulation technique used to encode a message into a pulsing signal. For more information, please refer to PWM in Wikipedia .

Supported features

Software architecture of PWM

  1. PWM polling mode architecture.
    Call hal_pwm_init() function to initialize the PWM source clock, then call hal_pwm_set_frequency() function to set the PWM frequency and get the total counter of the hardware. Total counter is PWM counter internal value at specified frequency. The duty cycle is calculated as the product of application's duty ratio and total counter. Duty ratio is the ratio of duty counter over the total counter.
    Call hal_pwm_set_duty_cycle() function to set the PWM duty cycle. Call hal_pwm_start() function to trigger PWM execution.
    Call hal_pwm_get_frequency() and hal_pwm_get_duty_cycle() functions if the current frequency and duty cycle need to be retrieved.
    Call hal_pwm_get_running_status() function to get the PWM status, either busy or idle. Call hal_pwm_stop() function to stop the PWM execution.
    Polling mode architecture is similar to the polling mode architecture in HAL overview. See HAL Driver Model for polling mode architecture.

How to use this driver

Functions

hal_pwm_status_t hal_pwm_init (hal_pwm_channel_t pwm_channel, hal_pwm_source_clock_t source_clock)
 This function initializes the PWM hardware source clock. More...
 
hal_pwm_status_t hal_pwm_deinit (hal_pwm_channel_t pwm_channel)
 This function deinitializes the PWM hardware. More...
 
hal_pwm_status_t hal_pwm_set_frequency (hal_pwm_channel_t pwm_channel, uint32_t frequency, uint32_t *total_count)
 This function sets the PWM frequency and retrieves total count of the PWM hardware at the specified frequency. More...
 
hal_pwm_status_t hal_pwm_set_duty_cycle (hal_pwm_channel_t pwm_channel, uint32_t duty_cycle)
 This function sets the PWM duty cycle. More...
 
hal_pwm_status_t hal_pwm_start (hal_pwm_channel_t pwm_channel)
 This function starts the PWM execution. More...
 
hal_pwm_status_t hal_pwm_stop (hal_pwm_channel_t pwm_channel)
 This function stops the PWM execution. More...
 
hal_pwm_status_t hal_pwm_get_frequency (hal_pwm_channel_t pwm_channel, uint32_t *frequency)
 This function gets current frequency of the PWM, the unit of frequency is Hz. More...
 
hal_pwm_status_t hal_pwm_get_duty_cycle (hal_pwm_channel_t pwm_channel, uint32_t *duty_cycle)
 This function gets the current duty cycle of the PWM. More...
 
hal_pwm_status_t hal_pwm_get_running_status (hal_pwm_channel_t pwm_channel, hal_pwm_running_status_t *running_status)
 This function gets the current status of PWM. More...
 
hal_pwm_status_t hal_pwm_set_advanced_config (hal_pwm_channel_t pwm_channel, hal_pwm_advanced_config_t advanced_config)
 This function sets the PWM advanced configuration. More...
 

Modules

 Enum
 

Function Documentation

hal_pwm_status_t hal_pwm_deinit ( hal_pwm_channel_t  pwm_channel)

This function deinitializes the PWM hardware.

Parameters
[in]pwm_channelis the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
Returns
To indicate whether this function call is successful or not. If the return value is HAL_PWM_STATUS_OK, the operation completed successfully. If the return value is HAL_PWM_STATUS_INVALID_PARAMETER, a wrong parameter is given. The parameter needs to be verified.
Example
For a sample code, please refer to How to use this driver.
See also
hal_pwm_init()
hal_pwm_status_t hal_pwm_get_duty_cycle ( hal_pwm_channel_t  pwm_channel,
uint32_t *  duty_cycle 
)

This function gets the current duty cycle of the PWM.

Parameters
[in]pwm_channelis the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[out]*duty_cycleis PWM hardware duty cycle, which is calculated as a product of application's duty ratio and hardware 's total count.
Returns
To indicate whether this function call is successful or not. If the return value is HAL_PWM_STATUS_OK, the operation completed successfully. If the return value is HAL_PWM_STATUS_INVALID_PARAMETER, a wrong parameter is given. The parameter needs to be verified.
Example
For a sample code, please refer to How to use this driver.
See also
hal_pwm_set_duty_cycle()
hal_pwm_status_t hal_pwm_get_frequency ( hal_pwm_channel_t  pwm_channel,
uint32_t *  frequency 
)

This function gets current frequency of the PWM, the unit of frequency is Hz.

Parameters
[in]pwm_channelis the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[out]frequencyis PWM output frequency.
Returns
To indicate whether this function call is successful or not. If the return value is HAL_PWM_STATUS_OK, the operation completed successfully. If the return value is HAL_PWM_STATUS_INVALID_PARAMETER, a wrong parameter is given. The parameter needs to be verified.
Example
For a sample code, please refer to How to use this driver.
See also
hal_pwm_set_frequency()
hal_pwm_status_t hal_pwm_get_running_status ( hal_pwm_channel_t  pwm_channel,
hal_pwm_running_status_t running_status 
)

This function gets the current status of PWM.

Parameters
[in]pwm_channelis the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[out]running_statusis PWM busy or idle status, For details about this parameter, please refer to hal_pwm_running_status_t .
Returns
To indicate whether this function call is successful or not. If the return value is HAL_PWM_STATUS_OK, the operation completed successfully. If the return value is HAL_PWM_STATUS_INVALID_PARAMETER, a wrong parameter is given. The parameter needs to be verified.
Example
For a sample code, please refer to How to use this driver.
hal_pwm_status_t hal_pwm_init ( hal_pwm_channel_t  pwm_channel,
hal_pwm_source_clock_t  source_clock 
)

This function initializes the PWM hardware source clock.

Parameters
[in]pwm_channelis the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[in]source_clockis the PWM source clock. For more details about the parameter, please refer to hal_pwm_source_clock_t.
Returns
To indicate whether this function call is successful or not. If the return value is HAL_PWM_STATUS_OK, the operation completed successfully. If the return value is HAL_PWM_STATUS_INVALID_PARAMETER, a wrong parameter is given. The parameter needs to be verified.
Example
For a sample code, please refer to How to use this driver.
Note
There are some limitations about the minimum frequency that we can set if we choose the related source clock list in hal_pwm_source_clock_t, and the caculation formula is as follows:
The minimum frequency = ( the chosen source clock) / ( 0X1FFF * advanced_config )
For example:
if we choose the clock of HAL_PWM_CLOCK_32KHZ, the minimum frequency that we can set is 0.5 Hz;
if we choose the clock of HAL_PWM_CLOCK_13MHZ, the minimum frequency that we can set is 199 Hz;
Warning
For this chip, we can config the PWM channel and the related clock, which means different PWM channels can use the different clock.
See also
hal_pwm_deinit()
hal_pwm_status_t hal_pwm_set_advanced_config ( hal_pwm_channel_t  pwm_channel,
hal_pwm_advanced_config_t  advanced_config 
)

This function sets the PWM advanced configuration.

Parameters
[in]pwm_channelis the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[in]advanced_configis PWM source clock division value, For more details about this parameter, please refer to hal_pwm_advanced_config_t.
Returns
To indicate whether this function call is successful or not. If the return value is HAL_PWM_STATUS_OK, the operation completed successfully. If the return value is HAL_PWM_STATUS_INVALID_PARAMETER, a wrong parameter is given. The parameter needs to be verified.
Example
For a sample code, please refer to How to use this driver.
hal_pwm_status_t hal_pwm_set_duty_cycle ( hal_pwm_channel_t  pwm_channel,
uint32_t  duty_cycle 
)

This function sets the PWM duty cycle.

Parameters
[in]pwm_channelis the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[in]duty_cycleis the PWM hardware duty cycle, which is calculated as a product of application's duty ratio and hardware 's total count.
Returns
To indicate whether this function call is successful or not. If the return value is HAL_PWM_STATUS_OK, the operation completed successfully. If the return value is HAL_PWM_STATUS_INVALID_PARAMETER, a wrong parameter is given. The parameter needs to be verified.
Example
For a sample code, please refer to How to use this driver.
See also
hal_pwm_get_duty_cycle()
hal_pwm_status_t hal_pwm_set_frequency ( hal_pwm_channel_t  pwm_channel,
uint32_t  frequency,
uint32_t *  total_count 
)

This function sets the PWM frequency and retrieves total count of the PWM hardware at the specified frequency.

Parameters
[in]pwm_channelis the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[in]frequencyis the PWM output frequency.
[out]total_countis PWM hardware total count, the value of this parameter varies based on the given PWM frequency.
Returns
To indicate whether this function call is successful or not. If the return value is HAL_PWM_STATUS_OK, the operation completed successfully. If the return value is HAL_PWM_STATUS_INVALID_PARAMETER, a wrong parameter is given. The parameter needs to be verified.
Example
For a sample code, please refer to How to use this driver.
hal_pwm_status_t hal_pwm_start ( hal_pwm_channel_t  pwm_channel)

This function starts the PWM execution.

Parameters
[in]pwm_channelis the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
Returns
To indicate whether this function call is successful or not. If the return value is HAL_PWM_STATUS_OK, the operation completed successfully. If the return value is HAL_PWM_STATUS_INVALID_PARAMETER, a wrong parameter is given. The parameter needs to be verified.
Example
For a sample code, please refer to How to use this driver.
See also
hal_pwm_stop()
hal_pwm_status_t hal_pwm_stop ( hal_pwm_channel_t  pwm_channel)

This function stops the PWM execution.

Parameters
[in]pwm_channelis PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
Returns
To indicate whether this function call is successful or not. If the return value is HAL_PWM_STATUS_OK, the operation completed successfully. If the return value is HAL_PWM_STATUS_INVALID_PARAMETER, a wrong parameter is given. The parameter needs to be verified.
Example
For a sample code, please refer to How to use this driver.
See also
hal_pwm_start()