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

Use PWM with polling mode.
How to calculate PWM frequency and duty cycle at fixed souce clock. Assuming the crystal(XTAL) oscillator runs at 40MHz. and the applicaton needs a waveform at 2kHz frequency and 50% duty ratio.The calculations of division clock, total count and duty cycle are based on the formuals as shown below.
1. total_count = source_clock/frequency
2. duty_ cycle = (total_count*duty_ratio)/100
3. PWM_ON duration = duty_cycle
4. PWM_OFF duration = total_count-PWM_ON duration
5. Set PWM_ON duration to PWM_PARAM register 0~15 bit
6. Set PWM_OFF duration to PWM_PARAM register 16~31 bit

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_frequency() to set frequency and get total count of the PWM hardware at the specific frequency.
Step5: Call hal_pwm_set_duty_cycle() to set duty cycle according to total count and application's duty ratio.
Step6: Call hal_pwm_start() to trigger PWM at a specified frequency and duty count values.
Step7: Call hal_pwm_get_frequency() to get the current frenquency.
Step8: Call hal_pwm_get_duty_cycle() to get the current duty_cycle.
Step9: Call hal_pwm_stop()to stop the PWM.
Step10: Call hal_pwm_deinit() to deinitialize the PWM.
Sample code:
uint32_t duty_ratio = 50; //The range from 0 to 100.
hal_pwm_source_clock_t source_clock = HAL_PWM_CLOCK_40MHZ;
uint32_t frequency = 2000;
hal_gpio_init(HAL_GPIO_0);
//function index = HAL_GPIO_0_PWM0; for more information about pinmux please refernence hal_pinmux_define.h
hal_pinmux_set_function(HAL_GPIO_0, function_index);//Set the GPIO pinmux.
//Initialize the PWM source clock.
if(HAL_PWM_STATUS_OK != hal_pwm_init(source_clock)) {
//error handle
}
//Sets frequency and gets total count of the PWM hardware at the specific frequency.
if(HAL_PWM_STATUS_OK != hal_pwm_set_frequency(HAL_PWM_0, 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_0, duty_cycle)) {
//error handle
}
hal_pwm_start(HAL_PWM_0); //Trigger PWM execution.
//...
hal_pwm_get_frequency(HAL_PWM_0, &frequency);
hal_pwm_get_duty_cycle(HAL_PWM_0, &duty_cycle);
//...
hal_pwm_stop(HAL_PWM_0); //Stop the PWM.
hal_pwm_deinit(); //Deinitialize the PWM.

Functions
hal_pwm_status_t	hal_pwm_init (hal_pwm_source_clock_t source_clock)
	This function initializes the PWM hardware source clock. More...

hal_pwm_status_t	hal_pwm_deinit (void)
	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...

Modules
	Enum

Function Documentation

hal_pwm_status_t hal_pwm_deinit ( void )

This function deinitializes the PWM hardware.

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_source_clock_t source_clock )

This function initializes the PWM hardware source clock.

Parameters

[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) / 0XFFFF
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_2MHZ, the minimum frequency that we can set is 30 Hz;
if we choose the clock of HAL_PWM_CLOCK_40MHZ, the minimum frequency that we can set is 610 Hz;

Warning: For this chip, all the PWM channel is using the same clock once this function has been called.

See also: hal_pwm_deinit()

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