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

Support polling mode.
The PWM generates the fixed waveform at the specified frequency and duty. The application can query current frequency and duty of the polling mode. The PWM does not support interrupt mode.

Software architecture of PWM

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

Using PWM in polling mode.
Calculate the PWM frequency and duty cycle at fixed source clock. Assuming the source clock is 32kHz and the applicaton needs a waveform at 200Hz frequency and 50% duty ratio.The calculations of division clock, total count and duty cycle are based on the formuals as shown below.
1. division_clock = source_clock/division
2. total_count = division_clock/frequency
3. duty_cycle = (total_count*duty_ratio)/100
4. Set count to PWM_COUNT register
5. Set duty_cycle to PWM_THRES register

Step1: Call hal_gpio_init() to init the pin.
Step2: Call hal_pinmux_set_function() to set the pwm pinmux if the EPT is not in use.
Step3: Call hal_pwm_init() to initialize the PWM source clock.
Step4: Call hal_pwm_set_advanced_config() to select clock division, this is set as default and the configuration is optional.
Step5: Call hal_pwm_set_frequency() to set frequency and get total count of the PWM hardware at the specific frequency.
Step6: Call hal_pwm_set_duty_cycle() to set duty cycle according to total count and application's duty ratio.
Step7: Call hal_pwm_start() to trigger PWM at a specified frequency and duty count values.
Step8: Call hal_pwm_get_frequency() to get the current frenquency.
Step9: Call hal_pwm_get_duty_cycle() to get the current duty_cycle.
Step10: Call hal_pwm_stop()to stop the PWM.
Step11: Call hal_pwm_deinit() to deinitialize the PWM.
Sample code:
hal_pwm_advanced_config_t division = HAL_PWM_CLOCK_DIVISION_2;
uint32_t duty_ratio = 50; //The range from 0 to 100.
uint32_t frequency = 200;
hal_pwm_source_clock_t source_clock = HAL_PWM_CLOCK_32KHZ;
hal_gpio_init(HAL_GPIO_35);
//function index = HAL_GPIO_35_PWM5; for more information about pinmux please refernence hal_pinmux_define.h
hal_pinmux_set_function(HAL_GPIO_35, function_index);//Set the GPIO pinmux.
//Initialize the PWM source clock.
if(HAL_PWM_STATUS_OK != hal_pwm_init(HAL_PWM_5, source_clock)) {
//error handle
}
if(HAL_PWM_STATUS_OK != hal_pwm_set_advanced_config(HAL_PWM_5, division);) {
//error handle
}
//Set the frequency and get total count of the PWM hardware at the specific frequency.
if(HAL_PWM_STATUS_OK != hal_pwm_set_frequency(HAL_PWM_5, frequency, &total_count)) {
//error handle
}
duty_cycle = (total_count * duty_ratio)/100; //duty_cycle is calcauted as a product of application's duty_ratio and hardware's total_count.
//Enable PWM to start the timer.
if(HAL_PWM_STATUS_OK != hal_pwm_set_duty_cycle(HAL_PWM_5, duty_cycle)) {
//error handle
}
hal_pwm_start(HAL_PWM_5); //Trigger PWM execution.
//...
hal_pwm_get_frequency(HAL_PWM_5, &frequency);
hal_pwm_get_duty_cycle(HAL_PWM_5, &duty_cycle);
//...
hal_pwm_stop(HAL_PWM_5); //Stop the PWM.
hal_pwm_deinit(HAL_PWM_5); //Deinitialize the PWM.

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_channel is 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_channel	is the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[out]	*duty_cycle	is 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_channel	is the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[out]	frequency	is 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_channel	is the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[out]	running_status	is 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_channel	is the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[in]	source_clock	is 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_channel	is the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[in]	advanced_config	is 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_channel	is the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[in]	duty_cycle	is 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_channel	is the PWM channel number. For more details about the parameter, please refer to hal_pwm_channel_t.
[in]	frequency	is the PWM output frequency.
[out]	total_count	is 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_channel is 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_channel is 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()

Overview

Terms and acronyms

Supported features

Software architecture of PWM

How to use this driver

Functions

Modules

Function Documentation