Multi-Function Timer Pulse Unit 3 Three-Phase Motor Control Driver (r_mtu3_three_phase)

Functions
fsp_err_t	R_MTU3_THREE_PHASE_Open (three_phase_ctrl_t *const p_ctrl, three_phase_cfg_t const *const p_cfg)
fsp_err_t	R_MTU3_THREE_PHASE_Stop (three_phase_ctrl_t *const p_ctrl)
fsp_err_t	R_MTU3_THREE_PHASE_Start (three_phase_ctrl_t *const p_ctrl)
fsp_err_t	R_MTU3_THREE_PHASE_Reset (three_phase_ctrl_t *const p_ctrl)
fsp_err_t	R_MTU3_THREE_PHASE_DutyCycleSet (three_phase_ctrl_t *const p_ctrl, three_phase_duty_cycle_t *const p_duty_cycle)
fsp_err_t	R_MTU3_THREE_PHASE_CallbackSet (three_phase_ctrl_t *const p_ctrl, void(*p_callback)(timer_callback_args_t *), void const *const p_context, timer_callback_args_t *const p_callback_memory)
fsp_err_t	R_MTU3_THREE_PHASE_Close (three_phase_ctrl_t *const p_ctrl)

Detailed Description

Driver for 3-phase motor control using the MTU3 peripheral on RZ microprocessor. This module implements the Three-Phase Interface.

Overview

Multi-Function Timer Pulse Unit 3 (MTU3) Three-Phase driver provides basic functionality for synchronously starting and stopping three PWM channels for use in 3-phase motor control applications. A function is additionally provided to allow setting duty cycle values for all three channels, optionally with double-buffering.

Features

The MTU3 Three-Phase driver provides the following functions:

• Two channels of MTU3 (ch3/ch4, ch6/ch7) are used as a pair
• Synchronize 3 complementary PWM output signals
• Synchronously start, stop and reset the three complementary PWM output signals
• Set duty cycle on all three complementary PWM output signals with one function

Configuration

Build Time Configurations for r_mtu3_three_phase

The following build time configurations are defined in fsp_cfg/r_mtu3_three_phase_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Configurations for Timers > Three-Phase PWM (r_mtu3_three_phase)

This module can be added to the Stacks tab via New Stack > Timers > Three-Phase PWM (r_mtu3_three_phase).

Configuration	Options	Default	Description
General > Compare match value > Count upper limit	Value must be an integer between 0 and 0xFFFF	0	The count value of the apex of the triangle wave. Set to TGRA for MTU3 or MTU6.
General > Compare match value > PWM output (1 for MTU3, 4 for MTU6) compare	Value must be an integer between 0 and 0xFFFF	0	A count value that triggers the PWM output (1 for MTU3, 4 for MTU6). Set to TGRB on MTU3 or MTU6.
General > Compare match value > PWM output (2 for MTU4, 5 for MTU7) compare	Value must be an integer between 0 and 0xFFFF	0	A count value that triggers the PWM output (2 for MTU4, 5 for MTU7). Set to TGRA on MTU4 or MTU7.
General > Compare match value > PWM output (3 for MTU4, 6 for MTU7) compare	Value must be an integer between 0 and 0xFFFF	0	A count value that triggers the PWM output (3 for MTU4, 6 for MTU7). Set to TGRB on MTU4 or MTU7.
General > Name	Name must be a valid C symbol	g_three_phase0	Module name.
General > Channel	MTU3 and MTU4 MTU6 and MTU7	MTU3 and MTU4	Specify the hardware channel.
General > Mode	Complementary PWM mode 1 (transfer at crest) Complementary PWM mode 2 (transfer at trough) Complementary PWM mode 3 (transfer at crest and trough)	Complementary PWM mode 1 (transfer at crest)	Complementary PWM Mode..
General > Dead Time	Value must be an integer between 0 and 0xFFFF	0	A setting other than 0 enables the dead time setting. The selected channel determines which register (TDDRA or TDDRB) is set.
General > Buffer Mode	Single Buffer Double Buffer	Single Buffer	When Double Buffer is selected the 'duty_buffer' array in three_phase_duty_cycle_t is used as a buffer for the 'duty' array. This allows setting the duty cycle for the next two crest/trough events in asymmetric mode with only one call to R_MTU3_THREE_PHASE_DutyCycleSet..
General > Time Prescaler	Refer to the RZT Configuration tool for available options.	PCLKH divided by 1 (common ch)	Select time prescaler.
General > Clock Edge	Rising Falling Both	Rising	Select clock edge.
Output > Active level Select P	Low level High level	Low level	Output level selection with P and N bit.
Output > PWM Synchronous Output Enable	Disabled Enabled	Disabled	PWM Synchronous Output Enable.
Synchronous Clear Channel	Disabled MTU0 MTU1 MTU2 MTU3 MTU4 MTU6 MTU7	Disabled	Select synchronous clear channel.

Clock Configuration

Please refer to the Multi-Function Timer Pulse Unit 3 (r_mtu3) section for more information.

Pin Configuration

Please refer to the Multi-Function Timer Pulse Unit 3 (r_mtu3) section for more information.

Usage Notes

Warning

Be sure the MTIOC3(6)B/D,MTIOC4(7)A/C,B/D stop level and dead time values are set appropriately for your application before attempting to drive a motor. Failure to do so may result in damage to the motor drive circuitry and/or the motor itself if the timer is stopped by software.

Initial Setup

The following should be configured once the MTU3 Three-Phase module has been added to a project:

1. Set "Pin Output Support" in one of the MTU3 submodules to "Enabled with Extra Features"
2. Configure common settings in the MTU3 Three-Phase module properties
3. Set the crest and trough interrupt priority and callback function in MTU3 submodules (if desired)
4. Set the "Extra Features -> Output Disable" settings in each MTU3 submodule as needed for your application

Buffer Modes

There are two buffering modes available for duty cycle values - single- and double-buffered. In single buffer mode only the values specified in the duty array element of three_phase_duty_cycle_t are used by R_MTU3_THREE_PHASE_DutyCycleSet. At the next trough or crest event the output duty cycle will be internally updated to the set values.

In double buffer mode the duty_buffer array values are used as buffer values for the duty elements. Once passed to R_MTU3_THREE_PHASE_DutyCycleSet, the next trough or crest event will update the output duty cycle to the values specified in duty as before. However, at the following crest or trough event the output duty cycle will be updated to the values in duty_buffer. This allows the duty cycle for both sides of an asymmetric PWM waveform to be set at only one trough or crest event per period instead of at every event.

Examples

MTU3 Three-Phase Basic Example

This is a basic example of minimal use of the MTU3 Three-Phase module in an application. The duty cycle is updated at every timer trough with the previously loaded buffer value, then the duty cycle buffer is reloaded in the trough interrupt callback.

void mtu3_callback (timer_callback_args_t * p_args)
{
    fsp_err_t                err;
    three_phase_duty_cycle_t duty_cycle;

    if (TIMER_EVENT_TROUGH == p_args->event)
    {
        /* Update duty cycle values (example) */
        duty_cycle.duty[THREE_PHASE_CHANNEL_U] = mtu3_duty_counts(THREE_PHASE_CHANNEL_U);
        duty_cycle.duty[THREE_PHASE_CHANNEL_V] = mtu3_duty_counts(THREE_PHASE_CHANNEL_V);
        duty_cycle.duty[THREE_PHASE_CHANNEL_W] = mtu3_duty_counts(THREE_PHASE_CHANNEL_W);


        /* Update duty cycle values */
        err = R_MTU3_THREE_PHASE_DutyCycleSet(&g_mtu3_three_phase_ctrl, &duty_cycle);
        handle_error(err);

    }
    else
    {
        /* Handle crest event. */
    }
}

void mtu3_three_phase_basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;


    /* Initializes the module. */
    err = R_MTU3_THREE_PHASE_Open(&g_mtu3_three_phase_ctrl, &g_mtu3_three_phase_cfg);


    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);


    /* Start the timer. */
    (void) R_MTU3_THREE_PHASE_Start(&g_mtu3_three_phase_ctrl);

}

Data Structures
struct	mtu3_three_phase_extended_cfg_t
struct	mtu3_three_phase_instance_ctrl_t

Enumerations
enum	mtu3_three_phase_pwm_mode_t
enum	mtu3_three_phase_psye_t
enum	mtu3_three_phase_output_level_t
enum	mtu3_three_phase_synchronous_channel_t

---

Data Structure Documentation

mtu3_three_phase_extended_cfg_t

struct mtu3_three_phase_extended_cfg_t

MTU3 THREE PHASE extension features.

Data Fields
mtu3_three_phase_pwm_mode_t	pwm_mode
uint16_t	period_half	Period in raw timer counts / 2.
uint16_t	dead_time	dead time counts. if dead_time=0 , no dead time is generated
uint16_t	duty_val[3]	Duty value for MTU3(6).TGRB(D), MTU4(7).TGRA(C), MTU4(7).TGRB(D)
mtu3_three_phase_psye_t	period_out	MTIOC3(6)A Toggle output is disabled/enabled.
mtu3_three_phase_output_level_t	level	double buffer Duty
uint16_t	duty_double[3]	if double buffer , Duty value for MTU3(6).TGRDE, MTU4(7).TGRCE, MTU4(7).TGRDF
mtu3_three_phase_synchronous_channel_t	sync	Synchronous ch.

mtu3_three_phase_instance_ctrl_t

struct mtu3_three_phase_instance_ctrl_t

Channel control block. DO NOT INITIALIZE. Initialization occurs when three_phase_api_t::open is called.

Data Fields
uint32_t	open	Whether or not channel is open.
void *	p_reg[2]	Base register for PWM channels : MTU3/4 or MTU6/7.
R_MTU_Type *	p_reg_com	Base register for this channel(common ch)
uint32_t	channel	Channel of MTU3 channels used : MTU3 or MTU6.
three_phase_buffer_mode_t	buffer_mode	Single- or double-buffer mode.
three_phase_cfg_t const *	p_cfg	Pointer to initial configurations.

Enumeration Type Documentation

mtu3_three_phase_pwm_mode_t

enum mtu3_three_phase_pwm_mode_t

Complementary PWM Mode

Enumerator
MTU3_THREE_PHASE_PWM_MODE_1	transfer at crest
MTU3_THREE_PHASE_PWM_MODE_2	transfer at trough
MTU3_THREE_PHASE_PWM_MODE_3	transfer at crest and trough

mtu3_three_phase_psye_t

enum mtu3_three_phase_psye_t

PWM Synchronous Output Enable

Enumerator
MTU3_THREE_PHASE_PSYE_NO_SIGNAL	toggle output is disabled.
MTU3_THREE_PHASE_PSYE_TOGGLE	toggle output is enabled.

mtu3_three_phase_output_level_t

enum mtu3_three_phase_output_level_t

OUTPUT LEVEL

Enumerator
MTU3_THREE_PHASE_OUTPUT_LEVEL_ACTIVE_LOW	Active level is LOW.
MTU3_THREE_PHASE_OUTPUT_LEVEL_ACTIVE_HIGH	Active level is HIGH.

mtu3_three_phase_synchronous_channel_t

enum mtu3_three_phase_synchronous_channel_t

Timer Synchronous

Enumerator
MTU3_THREE_PHASE_SYNCHRONOUS_CHANNEL_DISABLE	No Synchronous Register.
MTU3_THREE_PHASE_SYNCHRONOUS_CHANNEL_0	Synchronous register is MTU0.
MTU3_THREE_PHASE_SYNCHRONOUS_CHANNEL_1	Synchronous register is MTU1.
MTU3_THREE_PHASE_SYNCHRONOUS_CHANNEL_2	Synchronous register is MTU2.
MTU3_THREE_PHASE_SYNCHRONOUS_CHANNEL_3	Synchronous register is MTU3.
MTU3_THREE_PHASE_SYNCHRONOUS_CHANNEL_4	Synchronous register is MTU4.
MTU3_THREE_PHASE_SYNCHRONOUS_CHANNEL_6	Synchronous register is MTU6.
MTU3_THREE_PHASE_SYNCHRONOUS_CHANNEL_7	Synchronous register is MTU7.

Function Documentation

R_MTU3_THREE_PHASE_Open()

fsp_err_t R_MTU3_THREE_PHASE_Open	(	three_phase_ctrl_t *const	p_ctrl,
		three_phase_cfg_t const *const	p_cfg
	)

Initializes the 3-phase timer module (and associated timers) and applies configurations. Implements three_phase_api_t::open.

Return values

FSP_SUCCESS	Initialization was successful.
FSP_ERR_ASSERTION	A required input pointer is NULL.
FSP_ERR_ALREADY_OPEN	Module is already open.
FSP_ERR_INVALID_CHANNEL	The requested channel is out of range.
FSP_ERR_INVALID_ARGUMENT	Period count is out of range. The sum of period count values and dead time is out of range. When ch3 is specified, set ch3 and ch4 in the "Timer Synchronous Register" setting. When ch6 is specified, set ch6 and ch7 in the "Timer Synchronous Register" setting.

R_MTU3_THREE_PHASE_Stop()

fsp_err_t R_MTU3_THREE_PHASE_Stop

(

three_phase_ctrl_t *const

p_ctrl

)

Stops all timers synchronously. Implements three_phase_api_t::stop.

Return values

FSP_SUCCESS	Timers successfully stopped.
FSP_ERR_ASSERTION	p_ctrl was NULL.
FSP_ERR_NOT_OPEN	The instance is not opened.

R_MTU3_THREE_PHASE_Start()

fsp_err_t R_MTU3_THREE_PHASE_Start

(

three_phase_ctrl_t *const

p_ctrl

)

Starts all timers synchronously. Implements three_phase_api_t::start.

Return values

FSP_SUCCESS	Timers successfully started.
FSP_ERR_ASSERTION	p_ctrl was NULL.
FSP_ERR_NOT_OPEN	The instance is not opened.

R_MTU3_THREE_PHASE_Reset()

fsp_err_t R_MTU3_THREE_PHASE_Reset

(

three_phase_ctrl_t *const

p_ctrl

)

Resets the counter values to 0. Implements three_phase_api_t::reset.

Return values

FSP_SUCCESS	Counters were reset successfully.
FSP_ERR_ASSERTION	p_ctrl was NULL.
FSP_ERR_NOT_OPEN	The instance is not opened.

R_MTU3_THREE_PHASE_DutyCycleSet()

fsp_err_t R_MTU3_THREE_PHASE_DutyCycleSet	(	three_phase_ctrl_t *const	p_ctrl,
		three_phase_duty_cycle_t *const	p_duty_cycle
	)

Sets duty cycle for all three timers. Implements three_phase_api_t::dutyCycleSet.

In symmetric PWM mode duty cycle values are reflected after the next trough. In asymmetric PWM mode values are reflected at the next trough OR crest, whichever comes first.

When double-buffering is enabled the values in three_phase_duty_cycle_t::duty_buffer are set to the double-buffer registers. When values are reflected the first time the single buffer values (three_phase_duty_cycle_t::duty) are used. On the second reflection the duty_buffer values are used. In asymmetric PWM mode this enables both count-up and count-down PWM values to be set at trough (or crest) exclusively.

Note

It is recommended to call this function in a high-priority callback to ensure that it is not interrupted and that no MTU3 events occur during setting that would result in a duty cycle buffer load operation.

Return values

FSP_SUCCESS	Duty cycle updated successfully.
FSP_ERR_ASSERTION	p_ctrl was NULL
FSP_ERR_NOT_OPEN	The instance is not opened.

R_MTU3_THREE_PHASE_CallbackSet()

fsp_err_t R_MTU3_THREE_PHASE_CallbackSet	(	three_phase_ctrl_t *const	p_ctrl,
		void(*)(timer_callback_args_t *)	p_callback,
		void const *const	p_context,
		timer_callback_args_t *const	p_callback_memory
	)

Updates the user callback for the MTU3 U-channel with the option to provide memory for the callback argument structure. Implements three_phase_api_t::callbackSet.

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.

R_MTU3_THREE_PHASE_Close()

fsp_err_t R_MTU3_THREE_PHASE_Close

(

three_phase_ctrl_t *const

p_ctrl

)

Stops counters, disables output pins, and clears internal driver data. Implements three_phase_api_t::close.

Return values

FSP_SUCCESS	Successful close.
FSP_ERR_ASSERTION	p_ctrl was NULL.
FSP_ERR_NOT_OPEN	The instance is not opened.