1 Overview This document describes how to install and use the medium voltage H-bridge (MVHB) software driver. This driver supports and provides high-level software solution for following analog parts: MC33926: single H-bridge, brushed DC motor driver, 5.0 V to 28 V, 5.0 A, 20 khz MC33931: single H-bridge, brushed DC motor driver, 5.0 V to 28 V, 5.0 A, 11 khz MC33932: dual H-bridge, stepper/brushed DC motor driver, 5.0 V to 28 V, 5.0 A, 11 khz MC34931(S): single H-bridge, brushed DC motor driver, 5.0 V to 36 V, 5.0 A, 11 khz/20 khz MC34932(S): dual H-bridge, stepper/brushed DC motor driver, 5.0 V to 36 V, 5.0 A, 11 khz/20 khz NXP offers Tower and Freedom board solutions based on these chips, namely TWRMC-MVHB1EVB (for MC33926 and MC33932), FRDM-33931-EVB, FRDM-34931-EVB and FRDM-34931S-EVB boards. See the related user guide and datasheet for detailed information. 2 MCU compatibility 2.1 Peripheral requirements Peripherals and resource requirements critical to the MCU s ability to handle a given part are as follows: TPM/FTM timer is required in case of speed control of DC brushed motors and in case of stepper motor control. Moreover, all pins used as timer channel outputs must be connected to the same timer instance. GPIOs are required for device enable, disable and input control pins (EN, D1, EN/D2, INV, SLEW) and for output signal generation (in GPIO mode). Depending on the user application, other resources (ADC pin for current feedback measurement) may be required. See the example projects provided. 2.2 Supported devices The MC33926, MC33931 and MC33932 are monolithic H-bridge power ICs designed primarily for automotive electronic throttle control, but are applicable to any low-voltage DC servo motor control application within the current and voltage limits stated in the specification.
The MC34931(S) and MC34932(S) are monolithic H-bridge power ICs designed primarily for DC brushed and servo motor driver applications within the current and voltage limits stated in the specification. Common device features are as follows: 3.0 V and 5.0 V TTL / CMOS logic compatible inputs Each H-bridge is able to control inductive loads with currents up to 5.0 A peak Automatic thermal back-off, peak current limiting (6.5 A ±1.5 A) ensures continuous high availability operation Drain-to-Source on resistance RDS(on) (typ.) 120 mω Real-time load current monitoring (analog feedback current mirror) Sleep mode with low current draw See Table 1 for difference between these models. Table 1. Device features Device model No. of H-bridges Operating voltage Maximum PWM frequency MC33926 Single 8.0 to 28 V 20 khz MC33931 Single 8.0 to 28 V 11 khz MC33932 Dual 8.0 to 28 V 11 khz MC34931 Single 5.0 to 36 V 11 khz MC34931S Single 5.0 to 36 V 20 khz MC34932 Dual 5.0 to 36 V 11 khz MC34932S Dual 5.0 to 36 V 20 khz 2.3 Supported MCUs The medium voltage H-bridge software driver supports S32K144 MCU and various Kinetis MCUs; some of the MCU evaluation boards are listed in Table 2. The listed MCUs are a subset of MCUs supported by the Kinetis-SDK (software development kit) layer. This driver is built on AML (analog middleware layer), which creates API abstraction layer for used SDK. This allows to additionally extend support for different layer similar to SDK without need to change the medium voltage H-bridge software driver itself. Current implementation includes abstraction for KSDK 2.x and S32 SDK. Table 2. Supported MCU evaluation boards Supported EVBs SDK release FRDM-KL25Z SDK 2.0 FRDM-K64F SDK 2.1 TWR-KL25Z48M SDK 2.0 TWR-K64F120M SDK 2.1 S32K144EVB-Q100 S32 SDK 1.0 See Table 3 for pin compatibility between FRDM-34931S-EVB board and selected MCUs. GPIOs for enable and disable pins (ENBL, DIS) are recommended (to change the device mode to sleep), but could be connected with jumpers directly to power and ground, so the device is active permanently. 2 / 35
Feedback pin FB is optional and it could be used to measure the current. Status flag is optional too. Note DEVKIT-TRANSLT board is needed between S32K144EVB-Q100 and FRDM-34931S-EVB. Table 3. Pin compatibility for selected MCU evaluation boards and FRDM34931SEVB Board / Pins Required Recommended Optional IN1 IN2 D1 EN / D2_B FB SF_B FRDM-KL25Z PTA5 PTC8 PTA2 PTE0 PTB0 PTB3 FRDM-K64F PTA2 PTC2 PTC17 PTE25 PTB2 PTB11 S32K144EVB-Q100 + DEVKIT-TRANSLT board PTC5 Wire connection to PTD1 PTA3 Wire connection to PTD0 PTD4 PTB1 Pin compatibility between Tower board TWR-MC-MVHB1EVB and selected MCUs for MC33926 is shown in Table 4 and in Table 5 for MC33932 device. Table 4. Pin compatibility for selected MCU Tower boards and TWR-MC-MVHB1EVB for MC33926 device Board / Pins Required Recommended Optional IN1 IN2 D1 EN D2_B FB SF_B SLEW INV TWR-KL25Z48M PTD4 PTD5 PTC7 PTD3 PTE0 PTB3 PTD1 PTD2 PTD0 TWR-K64F120M PTA7 PTD5 PTE11 PTD3 PTE0 PTB7 PTD1 PTD2 PTD0 Table 5. Pin compatibility for selected MCU Tower boards and TWR-MC-MVHB1EVB for MC33932 device Board / Pins Required Recommended Optional IN1 IN2 IN3 IN4 D1 EN1 / D2_B D3 EN2 / D4_B FB_A FB_B SFA_B SFB_B TWR-KL25Z48M PTE24 PTC2 PTC3 PTC4 PTC9 PTB10 PTB9 PTE31 PTE23 PTE22 PTC6 PTC5 TWR-K64F120M PTC1 PTC2 PTC3 PTC4 PTC15 PTC12 PTC13 PTC14 3 Freedom/Tower boards settings 3.1 Freedom evaluation boards The FRDM-33931S-EVB / FRDM-34931S-EVB / FRDM-34931-EVB consists of an Hbridge, a parallel interface, power conditioning circuitry, and a set of two input select jumpers. All +3.3 V VDD power required by the board is obtained via the parallel interface. Warning: To avoid damaging the board, the following restrictions must be observed: The motor supply voltage (VPWR) must be at least 5.0 V, but must not exceed 40 V. The peak operating current of the load must not exceed 5.0 A. The safe configuration routine is as follows: 1. Connect the FRDM-34931S-EVB or FRDM-34931-EVB to the MCU evaluation board. 2. Set jumper configuration. For recommended configuration, see Table 6. 3. With the power switched off, attach the DC power supply to the VPWR and GND screw connector terminals on the evaluation board. 4. Attach one set of coils of the brushed motor to OUT 1 and OUT 2 screw connector terminals on the evaluation board. 3 / 35
Table 6. Recommended jumper configuration for FRDM34931SEVB Jumper JP1 JP2 JP3 JP4 JP5 JP6 JP7 Position short 1-2 short 1-2 1-2 short short Description U2-5V VDD-3V3 FB-GND D1-IO13 EN/D2_B-IO8 IN1-PWM1 IN2-PWM2 Figure 1 illustrates the hardware configuration. Figure 1. Freedom board configuration 3.2 Tower peripheral module When configured as a Tower platform module, the TWR-MC-MVHB1EVB must be used in conjunction with another Tower MCU evaluation board. The following procedure describes how to set up the hardware when the TWR-MCMVHB1EVB is configured to drive three DC brushed motors. 1. Assemble the NXP Tower platform by sliding the TWR-MC-MVHB1EVB elevator connectors into the top slots on the Tower Elevator modules. Insert the Tower MCU evaluation board in the Tower Elevator modules in a set of slots below the TWR-MCMVHB1EVB. 2. Set jumper JP6 to 3V3 position. 3. Connect the USB cable between the PC and the USB port on the Tower MCU evaluation board. 4 / 35
4. Connect the MC33932 Channel A load to connector J1 (OUT2 and OUT1) and the MC33932 Channel B load to connector J2 (OUT4 and OUT3) on the TWR-MCMVHB1EVB evaluation board. These two loads could be either two DC motors or one stepper motor. 5. Connect the MC33932 8.0 V to 28 V DC power supply to connector J3 (PWR-IN) on the evaluation board. 6. Connect the MC33926 load to connector J4 (OUT2 and OUT1) on the TWR-MCMVHB1EVB evaluation board. 7. Connect the MC33926 8.0 V to 28 V DC power supply to connector J5 (PWR-IN) on the evaluation board. Figure 2 illustrates the Tower system configuration. Figure 2. Tower system configuration 4 This section provides an overview of the functionality, settings and usage of the driver (configuration and functions). For additional information, see the API programmer s guide (included in the MVHB software driver zip file) and the comments embedded in the code. 5 / 35
4.1 Configuring the driver The configuration structure shown in Figure 3 is the user interface available for configuring the driver and the device. User must add the appropriate values into the mvhb_device_data_t structure to configure the device. There are two configurations brushconfig mvhb_brush_config_t and stepperconfig mvhb_stepper_config_t, but only one of them is used, depending on the application. Device data structure is a part of driver configuration structure (mvhb_drv_config_t), which contains used pins and settings. This driver configuration structure is passed to the initialization function at start up. Figure 3. Driver configuration Note that medium voltage H-bridge driver supports both stepper and DC brushed motor control and a lot of medium voltage H-bridge chips (devices). Therefore, not all variables need to be filled for each type of usage. Depending on the application, it is necessary to 6 / 35
enable pins like Feedback (FB) to measure current or Status Flag (SF_B) to get status of device and fill configuration structure. MC33926 device has specific pins like Input Invert (INV) and Slew Rate (SLEW) which can be configured to use. MC33926 has separate Disable 2 pin (D2_B) which must be filled in driver configuration. In order to use medium voltage H-bridge software driver for one/two DC brushed motor control, mvhbmotorbrushed value must be set to motortype item in mvhb_device_data_t structure. Other required settings are brushpwmfrequency in case of speed control, brushconfig for A, B or both used H-bridge interfaces and secondarybridgeused in case of device with two H-bridge interfaces. In order to use medium H-bridge software driver for stepper motor control, mvhbmotorstepper value must be set to motortype item in mvhb_device_data_t structure. Other required settings are in mvhb_stepper_config_t structure. Structure mvhb_stepper_data_t is used internally only and it does not have to be changed by user. Note that the stepper motor cannot be controlled by device with one H-bridge interface only. Pin intended to control the motor can be either PWM channel outputs or GPIO pins. This option must be set into inputpins item in mvhb_drv_config and appropriate GPIO pin instances and indexes should be stored in the same structure. There are following limitations for PWM/GPIO pin control: DC brushed motor (state control): There is no limitation for pin muxing DC brushed motor (speed control): At least one pin per motor must be controlled by PWM output Stepper motor (full-stepping mode): All four pins must be configured as GPIO Utilized timer instance, timer channels and other timer settings should be stored in tmrinstance item and tmr_mvhb_config_t structure. Timer prescale should be chosen to ensure the minimal (131 khz) and maximal (1.0 MHz) counter frequency. Note that timer periphery is used if either stepper motor is controlled or at least one output pin of DC brushed motor is controlled by PWM. For detailed description of user configuration structure, see programmer s guide. 4.2 Driver API This medium voltage H-bridge software driver provides API that can be used for dynamic real-time configuration of device in user code. For summary of available functions, see Table 7. Table 7. API Function Description GetDefaultConfig Gets the default configuration of the device Init Initializes the device SetMode Sets the operational mode of the device GetStatusFlag Reads status pin of the bridge GetCurrentMeasurement It is intended for measuring of H-bridge output current OnCounterRestart Routine function on counter restart DC Brushed motor InvertInputPins Inverts output value of INV pins (only MC33926) 7 / 35
Function Description SetSlewPin Controls SELW pin (only MC33926) SetDirection Sets direction of brush motor SetRecirculation Sets low/high-side recirculation of the H-bridge RotateFull Spins the motor in desired direction at full speed RotateProportional Spins the motor in desired direction and at desired speed Stepper motor AlignRotor Align the rotor to full-step position SetFullStepSpeed Set speed of full-step mode SetAccelerationRamp Sets acceleration ramp MoveSteps Moves the motor by specified number of full-steps GetFullStepPosition Returns the current full-step position ResetFullStepPosition Sets counter of full-steps to zero MoveContinual Moves motor continually in full-step mode StopContinualMovement Stop continual movement of stepper motor DisableMotor Sets IN pins output value to LOW MCU peripherals configuration ConfigureAdc Configures ADC for usage with this driver ConfigureGpio Configures GPIO for usage with this driver ConfigureTimer Configures Timer for usage with this driver For detailed description of software driver API (function signatures, parameters) see programmer s guide (included in the medium voltage H-bridge software driver zip file). 4.3 Low-level drivers This section describes the low-level MCU peripheral drivers used by the medium voltage H-bridge software driver. The medium voltage H-bridge software driver depends on these low-level drivers for functions such as control and measure. Because the medium voltage H-bridge software driver is built on AML, it has access to a subset of low-level drivers supported by the underlying SDK. Most analog devices require 2 that some of the SPI, I C, Timer, ADC and GPIO drivers are configured on the MCU side. The AML layer unifies the API for these selected drivers, making the embedded software driver portable across SDKs. Figure 4 illustrates the software driver architecture in terms of control and other functions. The timer/gpio usage for input pins (IN1, IN2, IN3, IN4) depends on the configuration. 8 / 35
Figure 4. Driver architecture 4.4 Required driver setup In order to execute correctly, the medium voltage H-bridge software driver requires the following: In the file aml/common_aml.h, the SDK_VERSION parameter must indicate which SDK is being used. All pins and peripherals need to be set in the driver configuration structure in mvhb/ mvhb.h. 4.5 Implementation notes Main feature of medium voltage H-bridge software driver is motor control. Typical implementation is to control DC brushed motor or stepper motor. 4.5.1 Brushed motor Driver allows several different pin configurations for brushed motor control using PWM or GPIO. Speed control is done using PWM and state control using GPIO or PWM. The PWM and GPIO pins could be combined for saving timer resources. Balance between saving resources and motor control limitation is up to user. These configuration options are the same for second H-bridge. Table 8 summarizes possible control options. Table 8. Motor control limitations according to pin and device configurations State Speed GPIO-GPIO GPIO-PWM PWM-GPIO PWM-PWM Rotate full Rotate proportional X X X X X X X X X X X Pin configurations Full functionality is reached with timer pins at least on one input pin otherwise there are limitations in speed control. Figure 5 describes motor control approach. It shows how motor runs in Forward and Reverse direction and how motor breaks in Free-Wheel High or Free-Wheel Low. Full H-bridge mode drives motor in low-side recirculation when motor running and motor breaks using high-side recirculation. 9 / 35
Figure 5. Motor control using OUT1 and OUT2 Table 9 summarizes possible Free-Wheeling settings according to driver configuration, where Max is max offset of counter period. PWM is offset for PWM duty. H is GPIO set to High. L is GPIO set to low. Zero is 0 counter offset. Table 9. Free-Wheeling using PWM generation or GPIO control mode Pin configurations Direction OUT1 High, OUT2 Low OUT1 Low, OUT2 High OUT1 Low, OUT2 Low (low-side) OUT1 High, OUT2 High (high-side) OUT1 OUT2 OUT1 OUT2 OUT1 OUT2 OUT1 OUT2 GPIO - PWM H Max - PWM L PWM L 0 H Max PWM - GPIO PWM L Max PWM H 0 L Max H PWM - PWM low-side PWM 0 0 PWM 0 0 PWM - PWM high-side Max Max - PWM Max - PWM Max Max Max 4.5.2 Stepper motor The medium voltage H-bridge software driver is designed to control a two phase bipolar stepper motor. Because a stepper motor uses electrical commutation to rotate, it requires a dual H-bridge device. The basic control method is full-stepping which fully powers each coil in sequence. In full-step mode, you can control motor speed, direction, acceleration and deceleration and the position of the stepper motor. The following application notes apply to stepper motor control: The medium voltage H-bridge software driver was tested with a core clock frequency ranging from 20 MHz (minimum value) to 120 MHz. The acceleration and deceleration ramp of the stepper motor is computed in real-time using integer arithmetic. This solution is based on the article Generate stepper-motor speed profiles in real time" (Austin, David. 2005). The stepper motor holds its position (coils are powered) after motor movement is completed. Use method DisableMotor to set H-bridge outputs to LOW (coils are not powered). The FTM or TPM timer device is needed by the stepper control logic. The AlignRotor function affects the position of the motor. This function executes four full-steps. As mentioned above, it is possible to generate a full-stepping signal by using four GPIO pins. The signal generated by the MCU (inputs of H-bridge device) is shown in Figure 6. 10 / 35
The voltage levels applied to the coils of the stepper motor are depicted in Figure 7. Note that the voltage is applied to both coils at the same time. Figure 6. Signals of logic input pins generated by the MCU in Full-step mode Figure 7. Output of H-bridge device in Full-step mode 5 Installing the software This section describes installation of Kinetis Design Studio and S32 Design Studio for ARM and how to use this software driver built on SDK for application development. Kinetis-SDK is a comprehensive collection of software enablements that support NXP microcontroller development. For more information, click www.nxp.com/ksdk. 11 / 35
5.1 Installing Kinetis Design Studio This procedure explains how to obtain and install the latest version of Kinetis Design Studio (version 3.2.0 in this guide). The procedure for S32 Design Studio installation is similar. Note: The driver and some examples in the driver package are intended for Kinetis Design Studio 3.2.0 (and above). If Kinetis Design Studio 3.2.0 is already installed on the system, skip this section. 1. Obtain the latest Kinetis Design Studio 3.2.0 installer file from the NXP website: www.nxp.com/kds. OR Obtain the S32 Design Studio installer file from the NXP website: www.nxp.com/ S32DS. 2. Run the executable file and follow the instructions. 3. When the installation is complete, click Help -> Check for Updates in Design Studio to install all the available updates. 5.2 Downloading the SDK library This step is necessary only when you create a new Kinetis-SDK project, the selected MCU s low-level drivers must be copied into the project s working directory. The example projects listed in Table 10 include the required drivers. In addition, the S32 Design Studio SDK library is distributed with a complete IDE and requires no manual driver additions. The MCUXpresso SDK Builder is a tool that allows you to download a customized SDK based on your specific evaluation platform or Kinetis MCU. To download the Kinetis SDK, click http://mcuxpresso.nxp.com/. For a list of all MCU s supported by SDK, click http://community.nxp.com/docs/ DOC-329783. 12 / 35
5.3 Downloading the software driver and example projects To download the latest version of the medium voltage H-bridge software driver and the example projects, do the following: 1. Go to the NXP website http://www.nxp.com/medium-voltage-hbridge-sdk. 2. Download the zip file containing the software driver and the example projects. 3. Unzip the file and check to see that the folder contains the files listed in Table 10. Table 10. Content of the zip file Folder name Folder contents KDS_Examples Example project folder for Kinetis Design Studio 3.2.0 or newer MVHB_KL25_FRDM34931SEVB This example project shows how to setup the device for controlling the brushed motor and how to set device mode, direction, speed, recirculation side and measure current feedback with FRDM-KL25Z board. Functions SetMode, RotateFull, RotateProportional, SetDirection, SetRecirculationSide and GetCurrentMeasurement are used in this example project. MVHB_K64F_FRDM34931SEVB This example project shows how to setup the device for controlling the brushed motor and how to set device mode, direction, speed and recirculation side with FRDMK64F board. Functions SetMode, RotateFull, RotateProportional, SetDirection and SetRecirculationSide are used in this example project. TWR_K64_MVHB_MC33926_Brushed This example project shows how to setup the device for controlling the brushed motor and how to set device mode, direction, speed, recirculation side and measure current feedback with TWR-K64F120M board. Functions SetMode, RotateFull, RotateProportional, SetDirection and SetRecirculationSide are used in this example project. TWR_K64_MVHB_MC33932_Brushed This example project shows how to setup the device for controlling two brushed motors and how to set device mode, direction, speed, recirculation side and measure current feedback with TWR-K64F120M board. Functions SetMode, RotateFull, RotateProportional, SetDirection and SetRecirculationSide are used in this example project. TWR_K64_MVHB_MC33932_Stepper This example project shows how to setup the device for controlling the stepper motor and how to set full step speed and acceleration ramp and it shows how to move step or continual and disable motor with TWR-K64F120M board. Functions SetAccelerationRamp, SetFullStepSpeed, MoveSteps, MoveContinual, StopContinualMovement and DisableMotor are used in this example project. TWR_KL25Z48M_MVHB_MC33926_Brushed This example project shows how to setup the device for controlling the brushed motor and how to set device mode, direction, speed, recirculation side and measure current feedback with TWR-KL25Z48M board. Functions SetMode, RotateFull, RotateProportional, SetDirection, SetRecirculationSide and GetCurrentMeasurement are used in this example project. 13 / 35
Folder name Folder contents TWR_KL25Z48M_MVHB_MC33932_Brushed This example project shows how to setup the device for controlling two brushed motor and how to set device mode, direction, speed, recirculation side and measure current feedback with TWR-KL25Z48M board. Functions SetMode, RotateFull, RotateProportional, SetDirection, SetRecirculationSide and GetCurrentMeasurement are used in this example project. TWR_KL25Z48M_MVHB_MC33932_Stepper This example project shows how to setup the device for controlling the stepper motor and how to set full step speed and acceleration ramp and it shows how to move step or continual and measure current feedback with TWR-KL25Z48M board. Functions SetAccelerationRamp, SetFullStepSpeed, MoveSteps, MoveContinual, StopContinualMovement, GetCurrentMeasurement and DisableMotor are used in this example project. S32_Examples MVHB_S32K144_FRDM34931SEVB This example project shows how to setup the device for controlling the brushed motor and how to set device mode, direction, speed, recirculation side and measure current feedback with S32K144EVB-Q100. Functions SetMode, RotateFull, RotateProportional, SetDirection, SetRecirculationSide and GetCurrentMeasurement are used in this example project. Note that this example is not full supported by S32K144EVB-Q100 board and is necessary to use DEVKIT-TRANSLT board and wire connection. Programmer_Guide API Programmer s Guide SDK_SW_Driver folder. This folder contains two subfolders aml and mvhb. Note that files in mvhb folder depend relatively on files in a ml folder. 5.4 Import an example project into Kinetis Design Studio The following steps show how to import an example from the zip file into Kinetis Design Studio. The procedure for importing an example project into S32 Design Studio for ARM is similar. The only difference is that S32 DS examples are located in S32_Examples folder instead of KDS_Examples folder. 1. In Kinetis Design Studio menu bar, click File->Import In the pop-up window, select General->Existing Projects into Workspace, and then click Next. 14 / 35
2. Click Browse and locate the folder where you unzipped the example files. Find the folder KDS_Examples and select a project to import. Then click OK. 3. With your project now loaded in the Select root directory box, click Copy projects into workspace checkbox. Then click Finish. The project is now in the Kinetis Design Studio workspace where you can build and run it. 15 / 35
5.5 Creating a new project with medium voltage H-bridge software driver If you choose not to use the example projects, the following instructions describe how to create and setup a new project that uses medium voltage H-bridge SDK software driver. To create a new project, do the following: 1. In the Kinetis Design Studio menu bar, select File -> New -> Kinetis SDK 2.x Project. When the Select Kinetis SDK 2.x box opens, enter a project name in the text box, select path to SDK 2.x library, and then click Next. Before creating a new project, make sure to download SDK package for your MCU (see Section 5.2 "Downloading the SDK library"). 2. In the Select Kinetis Processor or board dialog box, select the MCU class or board your project is using (MKL27Z64xxx4 is selected). Then click Next. 16 / 35
3. The following figure shows the Project Explorer panel and main.c content after creation of a new project. All of the needed files are placed in dedicated folders like board, CMSIS, drivers, source, startup and utilities. For detailed description of SDK project folder structure, see KSDK 2.x user guide. 5.5.1 Adding the medium voltage H-bridge software driver to the project This section describes how to add the medium voltage H-bridge software driver to the project. 1. Copy the content of SDK_SW_Driver to the Sources folder in your newly created project. The list of copied files is shown in the following figure. 17 / 35
2. In main.c, add line which is highlighted in the following figure to get access to the medium voltage H-bridge software driver in user code. 18 / 35
5.5.2 Setting up the project Once the new project has been created and the medium voltage H-bridge software driver has been added to it, the project must be set up. 1. In order to get the medium voltage H-bridge software driver to run on the selected MCU, you must edit the board/pin_mux.c file to configure the TPM/FTM timer and GPIO pins being used. This entails making the correct MCU pin selections (see Section 2.3 "Supported MCUs") and then muxing them as needed. Use one of the example projects as a template for this step. The pin muxing muxing on KL25Z is shown in the following figure. 2. Create a variable of type mvhb_drv_config_t that is passed to all used functions. This variable stores MCU peripheral configuration and medium voltage H-bridge software driver configuration. This variable must be accessible during run-time and should be declared either in the main() function or as a global variable. 3. Configure the medium voltage H-bridge. With the exception of the MVHB_GetDefaultConfig function, change individual items as needed. Note that this configuration structure is mapped internally to the device register array with respect to the selected model. 4. Set up the MCU peripherals to be used with the medium voltage H-bridge software driver. There are two options: Use the provided MVHB_ConfigureAdc, MVHB_ConfigureTimer and MVHB_ConfigureGpio functions for necessary configuration Handle peripheral initialization The following figure shows typical settings for the KL25Z. 19 / 35
5. The medium voltage H-bridge initialization function should be called in the end. User must pass reference to MCU peripherals and device configuration, which are part of driver data structure. 20 / 35
5.5.3 Writing an application code All application code must reside in the source folder in the project directory. The code in main.c can be modified but the original comments related to usage directions must be retained. When the medium voltage H-bridge SDK software driver is configured properly, the prepared functions can be used to construct an application. See the API programmer s guide (included in the medium voltage H-bridge software driver zip file) for function signatures and required parameters. Also review the source/ mvhb/mvhb.h header file, which contains prototypes for all available functions. Figure 8 provides an example of user application code after the above procedure has been completed. The example assumes that the user has already configured pin muxing, MCU peripherals and the medium voltage H-bridge device itself (part of the code from BOARD_InitPins to MVHB_Init). The code comments indicate what occurs at each step of the execution flow. For more complex medium voltage H-bridge use cases, see example projects. 21 / 35
Figure 8. Example user application code with medium voltage H-bridge software driver 22 / 35
5.5.4 Compiling, downloading and debugging To compile a project, click the compile icon in the toolbar (see Figure 9). Figure 9. Compiling the project The process for downloading an application on board in Kinetis Design Studio may differ according to used MCU board. If you have any question, see Kinetis Design Studio user guide. To download and debug on FRDM-KL25Z MCU board, do the following: 1. Click the arrow next to the debug icon in the toolbar and select Debug Configurations. 2. In the Debug Configurations dialog box, click SHB_KL27Z_Debug_PNE under GDB PEMicro Interface Debugging. 3. Make sure that C/C++ Application contains path to.elf file of the project. 4. Click the Debugger tab and set Interface option to OpenSDA Embedded Debug USB Port. Then click Refresh button next to the Port setting to update list of available USB ports. 23 / 35
5. Make sure that the Target is set to KL25Z128M4. If not, change the target with use of the Select Device button. Click the button, in Select Target Device dialog box, go to NXP -> KL2x -> KL25Z128M4 and confirm with Select button. 6. Then click Debug. Kinetis Design Studio downloads and launches the program on board. 5.6 Creating a new project with medium voltage H-bridge software driver in S32 Design Studio for ARM If you choose not to use the example projects, the following instructions describe how to create and setup a new project for S32K144 MCU that uses medium voltage H-bridge software driver. To create a new project in S32 Design Studio for ARM, do the following: 1. In the S32 Design Studio menu bar, select File -> New -> New S32DS Project. 24 / 35
2. When the New S32DS Project box opens, enter a project name in the text box, choose S32K144 processor in Elf S32DS project tab and click Next. Select NewLib Nano library, S32K144_SDK_gcc (version 1.0.0) SDK and then click Next. 3. The following figure shows the Project Explorer panel and main.c content after creation of a new project. Project includes only startup code and minimal driver set from S32K144 SDK. 25 / 35
5.6.1 Adding the medium voltage H-bridge software driver to the project This section describes how to add the medium voltage H-bridge software driver to the project. 1. Copy the content of SDK_SW_Driver to the Sources folder in your newly created project. The list of copied files is shown in the following figure. 2. In aml/common_aml.h, set SDK_S32 as definition of SDK_VERSION. 26 / 35
3. In main.c, add line which is highlighted in the following figure to get access to the medium voltage H-bridge software driver in user code. 4. The medium voltage H-bridge software driver requires the FTM, ADC and GPIO SDK drivers. In order to generate them into the project, click twice on the ftm, adc and gpio_hal components in Components Library window. After these components are included in the project, they are shown in Components window. Click Generate Processor Expert Code icon in the same window to include the selected drivers in the project. 27 / 35
5.6.2 Setting up the project Once the new project has been created and the medium voltage H-bridge software driver has been added to it, the project must be set up. 1. In order to get the medium voltage H-bridge software driver to run on S32K144, PinSettings component must be edited to configure the FTM, ADC and GPIO pins being used. This entails making the correct MCU pin selections (see Section 2.3 "Supported MCUs") and then muxing them as needed. Use one of the example projects as a template for this step. The following figure shows FTM2 pin muxing. 2. In order to get the medium voltage H-bridge software driver to run on S32K144, check the clock_manager component settings if the peripheral clock to FTM2 is enabled and provides frequency in allowed range for FTM2 periphery. The following figure shows the location of peripheral clock settings. 28 / 35
3. In Components window, click Generate Processor Expert Code icon to generate component settings in Generated_Code folder. 4. In main.c, add lines highlighted in the following figure to change the clock configuration and mux the pins according to the settings generated from the components. 5. Create a variable of type mvhb_drv_config_t that is passed to all used functions. This variable stores MCU peripheral configuration and medium voltage H-bridge software driver configuration. This variable must be accessible during run-time and should be declared either in the main() function or as a global variable. 6. Configure the medium voltage H-bridge as needed. All individual items can be changed as needed. 7. There are two options to set up the MCU peripherals used with medium voltage Hbridge software driver: Use the provided MVHB_ConfigureAdc, MVHB_ConfigureTimer and MVHB_ConfigureGpio functions for necessary configuration 29 / 35
Handle peripheral initialization by Processor Expert component setting The following figure shows typical settings for the S32K144. 8. The medium voltage H-bridge initialization function should be called in the end. User must pass reference to MCU peripherals and device configuration, which are part of driver data structure. 30 / 35
5.6.3 Writing an application code All application code must reside in the Sources folder in the project directory. The code in main.c can be modified but the original comments related to usage directions must be retained. When the medium voltage H-bridge SDK software driver is configured properly, use all of the prepared functions to construct your own application. See the API programmer s guide (included in the medium voltage software driver zip file) for function signatures and required parameters. Also review the Sources/mvhb/mvhb.h header file, which contains prototypes for all available functions. For complex medium voltage H-bridge use cases, see example projects. 5.6.4 Compiling, downloading and debugging To compile a project, click the compile icon in the toolbar (see Figure 10). Figure 10. Compiling the project The process for downloading an application on board in S32 Design Studio for ARM may differ according to used MCU board. If you have any question, see S32 Design Studio for ARM user guide. To download and debug on S32K144EVB-Q100 MCU board, do the following: 1. Click the arrow next to the debug icon in the toolbar and select Debug Configurations. 2. In the Debug Configurations dialog box, select one of the existing configurations with project name under GDB SEGGER J-Link Interface Debugging. 3. Make sure that C/C++ Application contains path to.elf file of the project in Main tab of Debug Configuration window. 4. Select appropriate debug interface and USBport in the Debugger tab of Debug Configuration window. 5. Apply changes and then click Debug. S32 Design Studio for ARM downloads and launches the program on board. 31 / 35
6 References The following URLs reference related NXP products and application solutions: NXP.com support pages Description URL TWR-MC-MVHB1EVB Tool summary page http://www.nxp.com/twr-mc-mvhb1evb FRDM-33931-EVB Tool summary page http://www.nxp.com/frdm-33931-evb FRDM-34931-EVB Tool summary page http://www.nxp.com/frdm-34931-evb FRDM-34931S-EVB Tool summary page http://www.nxp.com/frdm-34931s-evb Medium voltage H-bridge software driver Tool summary page http://www.nxp.com/medium-voltage-hbridge-sdk MCUXpresso SDK Builder MCUXpresso SDK Builder https://mcuxpresso.nxp.com/en/builder Kinetis Design Studio IDE Tool summary page http://www.nxp.com/kds S32 Design Studio IDE Tool summary page http://www.nxp.com/s32ds 7 Contact information Visit http://www.nxp.com/support for a list of phone numbers within your region. Visit http://www.nxp.com/warranty to submit a request for tool warranty. 8 Revision history Revision history Rev Date Description v.1.0 20170705 Initial version 32 / 35
9 Legal information 9.1 Definitions Draft The document is a draft version only. The content is still under internal review and subject to formal approval, which may result in modifications or additions. does not give any representations or warranties as to the accuracy or completeness of information included herein and shall have no liability for the consequences of use of such information. 9.2 Disclaimers Limited warranty and liability Information in this document is believed to be accurate and reliable. However, does not give any representations or warranties, expressed or implied, as to the accuracy or completeness of such information and shall have no liability for the consequences of use of such information. takes no responsibility for the content in this document if provided by an information source outside of. In no event shall NXP Semiconductors be liable for any indirect, incidental, punitive, special or consequential damages (including - without limitation - lost profits, lost savings, business interruption, costs related to the removal or replacement of any products or rework charges) whether or not such damages are based on tort (including negligence), warranty, breach of contract or any other legal theory. Notwithstanding any damages that customer might incur for any reason whatsoever, aggregate and cumulative liability towards customer for the products described herein shall be limited in accordance with the Terms and conditions of commercial sale of NXP Semiconductors. Right to make changes reserves the right to make changes to information published in this document, including without limitation specifications and product descriptions, at any time and without notice. This document supersedes and replaces all information supplied prior to the publication hereof. Suitability for use products are not designed, authorized or warranted to be suitable for use in life support, life-critical or safety-critical systems or equipment, nor in applications where failure or malfunction of an product can reasonably be expected to result in personal injury, death or severe property or environmental damage. and its suppliers accept no liability for inclusion and/or use of products in such equipment or applications and therefore such inclusion and/or use is at the customer s own risk. Applications Applications that are described herein for any of these products are for illustrative purposes only. makes no representation or warranty that such applications will be suitable for the specified use without further testing or modification. Customers are responsible for the design and operation of their applications and products using products, and accepts no liability for any assistance with applications or customer product design. It is customer s sole responsibility to determine whether the NXP Semiconductors product is suitable and fit for the customer s applications and products planned, as well as for the planned application and use of customer s third party customer(s). Customers should provide appropriate design and operating safeguards to minimize the risks associated with their applications and products. does not accept any liability related to any default, damage, costs or problem which is based on any weakness or default in the customer s applications or products, or the application or use by customer s third party customer(s). Customer is responsible for doing all necessary testing for the customer s applications and products using products in order to avoid a default of the applications and the products or of the application or use by customer s third party customer(s). NXP does not accept any liability in this respect. Suitability for use in automotive applications This NXP Semiconductors product has been qualified for use in automotive applications. Unless otherwise agreed in writing, the product is not designed, authorized or warranted to be suitable for use in life support, life-critical or safety-critical systems or equipment, nor in applications where failure or malfunction of an product can reasonably be expected to result in personal injury, death or severe property or environmental damage. and its suppliers accept no liability for inclusion and/or use of products in such equipment or applications and therefore such inclusion and/or use is at the customer's own risk. Export control This document as well as the item(s) described herein may be subject to export control regulations. Export might require a prior authorization from competent authorities. Evaluation products This product is provided on an as is and with all faults basis for evaluation purposes only., its affiliates and their suppliers expressly disclaim all warranties, whether express, implied or statutory, including but not limited to the implied warranties of non-infringement, merchantability and fitness for a particular purpose. The entire risk as to the quality, or arising out of the use or performance, of this product remains with customer. In no event shall, its affiliates or their suppliers be liable to customer for any special, indirect, consequential, punitive or incidental damages (including without limitation damages for loss of business, business interruption, loss of use, loss of data or information, and the like) arising out the use of or inability to use the product, whether or not based on tort (including negligence), strict liability, breach of contract, breach of warranty or any other theory, even if advised of the possibility of such damages. Notwithstanding any damages that customer might incur for any reason whatsoever (including without limitation, all damages referenced above and all direct or general damages), the entire liability of, its affiliates and their suppliers and customer s exclusive remedy for all of the foregoing shall be limited to actual damages incurred by customer based on reasonable reliance up to the greater of the amount actually paid by customer for the product or five dollars (US$5.00). The foregoing limitations, exclusions and disclaimers shall apply to the maximum extent permitted by applicable law, even if any remedy fails of its essential purpose. Translations A non-english (translated) version of a document is for reference only. The English version shall prevail in case of any discrepancy between the translated and English versions. 9.3 Trademarks Notice: All referenced brands, product names, service names and trademarks are the property of their respective owners. Kinetis is a trademark of NXP B.V. NXP is a trademark of NXP B.V. 33 / 35
Tables Tab. 1. Tab. 2. Tab. 3. Tab. 4. Tab. 5. Device features... 2 Supported MCU evaluation boards... 2 Pin compatibility for selected MCU evaluation boards and FRDM34931SEVB... 3 Pin compatibility for selected MCU Tower boards and TWR-MC-MVHB1EVB for MC33926 device... 3 Pin compatibility for selected MCU Tower boards and TWR-MC-MVHB1EVB for MC33932 device... 3 Tab. 6. Tab. 7. Tab. 8. Tab. 9. Tab. 10. Recommended jumper configuration for FRDM34931SEVB...4 API...7 Motor control limitations according to pin and device configurations...9 Free-Wheeling using PWM generation or GPIO control mode... 10 Content of the zip file...13 Figures Fig. 1. Fig. 2. Fig. 3. Fig. 4. Fig. 5. Fig. 6. Freedom board configuration... 4 Tower system configuration... 5 Driver configuration... 6 Driver architecture... 9 Motor control using OUT1 and OUT2...10 Signals of logic input pins generated by the MCU in Full-step mode... 11 Fig. 7. Fig. 8. Fig. 9. Fig. 10. Output of H-bridge device in Full-step mode...11 Example user application code with medium voltage H-bridge software driver... 22 Compiling the project... 23 Compiling the project... 31 34 / 35
Contents 1 2 2.1 2.2 2.3 3 3.1 3.2 4 4.1 4.2 4.3 4.4 4.5 4.5.1 4.5.2 5 5.1 5.2 5.3 5.4 5.5 5.5.1 5.5.2 5.5.3 5.5.4 5.6 5.6.1 5.6.2 5.6.3 5.6.4 6 7 8 9 Overview... 1 MCU compatibility...1 Peripheral requirements... 1 Supported devices... 1 Supported MCUs... 2 Freedom/Tower boards settings...3 Freedom evaluation boards... 3 Tower peripheral module...4...5 Configuring the driver... 6 Driver API... 7 Low-level drivers...8 Required driver setup... 9 Implementation notes... 9 Brushed motor... 9 Stepper motor...10 Installing the software... 11 Installing Kinetis Design Studio... 12 Downloading the SDK library...12 Downloading the software driver and example projects... 13 Import an example project into Kinetis Design Studio... 14 Creating a new project with medium voltage H-bridge software driver... 16 Adding the medium voltage H-bridge software driver to the project... 17 Setting up the project... 19 Writing an application code... 21 Compiling, downloading and debugging... 23 Creating a new project with medium voltage H-bridge software driver in S32 Design Studio for ARM... 24 Adding the medium voltage H-bridge software driver to the project... 26 Setting up the project... 28 Writing an application code... 31 Compiling, downloading and debugging... 31 References... 32 Contact information... 32 Revision history... 32 Legal information... 33 Please be aware that important notices concerning this document and the product(s) described herein, have been included in section 'Legal information'. NXP B.V. 2017. All rights reserved. For more information, please visit: http://www.nxp.com For sales office addresses, please send an email to: salesaddresses@nxp.com Date of release: 5 July 2017