1. Introduction
STM32 microcontrollers offer the performance of the industry-standard Arm® Cortex®-M cores running either field-oriented control (FOC) or 6-step modes, widely used in motor-control applications such as high-performance drives for air conditioning, home appliances, drones, building and industrial automation, medical, and e-bike. The STM32 motor-control software development kit (MC SDK) is part of the STMicroelectronics motor-control ecosystem, which offers a wide range of hardware and software solutions for motor-control applications. It is referenced as X-CUBE-MCSDK according to the software license agreement applied. It includes the:
- ST MC firmware library for permanent-magnet synchronous motor (PMSM) and Brushless DC (BLDC)
- ST MC workbench software tool, a graphical user interface for the configuration of MC SDK firmware library parameters, including the ST motor profiler tool and the ST motor pilot.
The STM32 motor-control software development kit allows evaluation of the performance of STM32 microcontrollers in applications driving one or two three-phase motors within the STM32 ecosystem. The ST MC workbench software tool runs on a PC. It reduces design time and effort when configuring the STM32 MCU firmware library. Through its graphical user interface, it can generate all the configuration files needed for an application. In addition, ST MC workbench interfaces with STM32CubeMX to take advantage of its ecosystem and customize embedded applications.
2. General information
The MC SDK is used for the development of motor-control applications running on STM32 32-bit microcontrollers based on the Arm® Cortex®-M processor. Table 1 presents the definition of acronyms that are relevant for a better understanding of this document.
| Acronym | Description |
|---|---|
| GUI | Graphical user interface |
| IDE | Integrated development environment |
| FOC | Field-oriented control |
| FW | Firmware |
| MC | Motor control |
| MC WB | Motor-control workbench (STMicroelectronics software tool) |
| MP | Motor Profiler (STMicroelectronics software tool) |
| PMSM | Permanent-magnet synchronous motor |
| PWM | Pulse-width modulation |
| SDK | Software development kit |
| BLDC | Brushless DC |
3. Motor-control ecosystem setup
A suitable ST motor-control ecosystem environment includes:
- A PC running the needed MC software tools
- STM32CubeIDE or a third-party IDE
- A third-party ANSI C-compiler
- A JTAG/SWD interface for debugging and programming
- An STMicroelectronics application board with one of the STM32 microcontrollers supported. It drives the power stage and features:
- PWM outputs to a gate driver
- ADC channels to measure currents and voltages
- DC bus voltage
- A three-phase PMSM motor or BLDC motor
- A power supply
Refer to the STM32 motor-control software development kit (MC SDK) data brief at www.st.com/content/st_com/en/ecosystems/stm32-motor-control-ecosystem.html and the release note for more details
3.1. Software tool setup
The STMicroelectronics motor-control ecosystem runs on a PC with Windows® 10. The following PC software tools are correctly installed:
- ST MC workbench (v6.0 or later)
- STM32CubeMX (v6.5.0 or later)
- STM32CubeProgrammer
- Any supported IDE:
- IAR Embedded Workbench® for Arm® (v8.4/v8.5)
- STM32CubeIDE
- Keil® MDK tools (v5.24.2 or later)
- STM32 motor-control SDK v6.0 tools user manual
- STM32CubeMX for STM32 configuration and initialization C code generation user manual
- STM32 ST-LINK utility software description user manual
Refer to the respective user manuals for proper installation.
3.2. Hardware setup
The connection of the STMicroelectronics application board to the PC requires a USB Type-A connector. Refer to the description of the application board for details on the USB cable. A dedicated description card is delivered with each STMicroelectronics application board for proper installation. For more details, refer to the user manual of the board available at www.st.com. The selected hardware can be one of the three setups:
- The complete MC Kit P-NUCLEO-IHM03 (NUCLEO-G431RB, X-NUCLEO-IHM16M1, GBM2804H-100T) link
- One of the complete inverter boards, for instance, the B-G431B-ESC1
- Any STM32 Nucleo or Evaluation board combined with one of the ST power boards that include the MC connector or morpho connector, whether it is a Nucleo or an Evaluation board
4. Getting started
4.1. Hardware connection
Connect a USB cable between the PC and the STMicroelectronics application board and the JTAG/SWD programming cable if it is different from the USB cable.
4.2. Motor Profiler
The Motor Profiler is a tool that automatically measures the electrical parameters of PMSM motors. The specification of an electric motor may not be known and is determined in less than a minute. The algorithm determines the motor parameters needed to configure the STM32 MCU firmware library: stator resistance Rs, stator inductance Ls, back EMF constant, motor inertia, and friction. It allows you to save the configurations you made. This tool is not mandatory to build the project, it is intended if you do not know the motor parameters or if you need to have better precision. Open the Motor Profiler tool either by:
- Using its dedicated button in the ST MC workbench as shown in Figure 1
- Running it directly from the installation folder tree as shown in Figure 2
When you are in the Motor Profiler tool, The first step to do is to select the boards we are using by clicking on the Select Boards button: It displays the list of supported boards as shown in Figure 3. Select the STMicroelectronics application board setup. As an example, Figure 3 shows the selection of the NUCLEO-F302R8 and the X-NUCLEO-IHM07M1 boards.
After hardware setup selection, fill in the parameter fields with the motor information:
- The number of pole pairs of the motor (mandatory field)
- The Max Speed of the motor (optional field). By default, the ST Motor Profiler tool searches for the maximum allowed speed the hardware setup used.
- The Max Current allowed by the motor (optional field). By default, it is the maximum peak current that can be delivered by the hardware setup.
- The nominal DC bus voltage used by the hardware setup (optional field). By default, it is the power supply stage as either the bus voltage for low voltage applications (DC voltage) or the RMS value for high voltage applications (AC voltage).
- The magnetic built-in type (mandatory field). By default, the SM-PMSM is selected.
- The Ld/Lq ratio (mandatory field) only when I-PMSM built-in is selected as shown in Figure 5
Once the previous step is complete, connect the target and start the profile. The profiler can recover parameters such as the stator resistor, the max current, the max speed, the friction, and the inertia. You have on the diagram, the necessary motor parameters (see Figure 6). You can save the motor profile by entering a name and a description, then access the workbench tool. You see the name of your backup (with all the output parameters) with a small blue icon, which represents the motor setup coming from the Motor Profiler Tool, in the list of motors.
4.3. Workbench
After clicking on the workbench icon, you arrive on the home page. You can either choose recent projects, click on the button “New project”, load a project, or take example projects as you can see in Figure 7. Provide hardware setup information in the New Project window once it appears as shown in Figure 8.
A new project lets you create a project with a wizard-style interface. The first step for a new project specifies the project name (which is optional, if none is selected you are prompted to select a name when you save your project) and a project description to identify the project. The second step is to fill in the hardware you want. Depending on the hardware selection, the wizard steps change:
- Custom: If you opt for custom hardware, you must fill parameters of the motor, power, and control boards. You can follow steps 1, 2, and 3 below.
- Kit: If you opt for an ST Kit, you must select the one you want from the list of kits. You can follow steps 1 and 4 below.
- Inverter: If you opt for an inverter solution, you must select a motor and an inverter solution. You can follow steps 1 and 5 below.
The paragraph below is a description of the existing steps.
- The motor section: In the Motor step you can select the motor for your solution. The list of motors is a list of motors available from application assets, all saved motors from the previous workbench version, and the motor profiler. Each motor is represented as a card where there is some electrical and mechanical information. If the motor setting comes from the profiler application a blue icon on the right side of the card is shown and a pop-up displays the profiled information.
- The power board section: The power step is a list of available power boards. They are sorted by taking into account the selection of the previous motor. The most compatible power board is listed first. Non-compatible boards are then displayed with a yellow warning icon.
- The control board section: After power board selection, the control board can be selected. In the same way, control boards are sorted by taking into account the compatibility with the selected power board (the compatibility depends on the motor-control connector available in power and control). If the two boards cannot be connected directly, a yellow warning appears on the card. If you select two boards that cannot be connected directly, another step (bridge) appears to allow the connection between power and control.
- The Kit section: You only see this section if you choose the Kit solution. Here, you just need to select the one you want from the list of kits. The kit is a complete solution available on the ST website and it is a set of motor, power, and control boards
- The Inverter section: You only see this section if you choose the Inverter solution. Here, you just need to select the one you want from the list of Inverters. The inverter is a board combining both the power and the control board.
It is important to fill in all the sections, you cannot create a project if one is missing as you can see in figure 9.
When all new project steps are completed, you can press the button “Ok” and the project is created. You can see that once you have saved your project, it appears on the home page in the recent project list card. The number of motors is indicated by the card, as the algorithm (FOC or 6-Step) and the project hardware type. Depending on whether you choose the FOC or 6-step algorithm, you do not have the same display and the same configuration mainly in the Drive settings section.
The main project view is displayed when a project or example is loaded or when a new project is created. The following parts are available:
- Toolbar
- Home: to leave the current project and return to the Home Page
- Save: Save the current project
- Generate: to generate the firmware source code
- Motor Pilot: to run the motor pilot tool
- Left bar
- this is a list of the available steps for the project. it is also managed as a kind of checklist
- Main view
- Block diagram of the project with all available parts such as AC input, inrush current, bus voltage, bus sensing, U, V, W driver, temperature sensing … Any block is active and by clicking on it, the application goes to the relative step, it also contains some configuration information.
- You have several parameters on the upper side, there is the project hardware-specific information
- MCU which displays information about pin usage and conflicts by clicking on it
- Control board information
- Power board information
To give you complete control over your project, a wizard helps you while building your project. The wizard is a guided tour of the project. some mains concepts are listed here:
- The sequence of sections: Each section is influenced by the previous sections but not the reverse.
- Each editable field must have a default value: if you do not specify an explicit value for a field, a valid one is provided by the tool.
- The set of default values and explicit values must be consistent: In case of errors, the wizard cannot update the project content.
Finally, from the toolbar, you can click on the button “Generate the project”. A window helps you to choose the IDE to use and the drive type appears. Modify the settings if you want and then click on “Generate”. A project for the specific toolchain is provided and the firmware can be compiled, and the board is flashed.
More information about the ST MC workbench is provided in the STM32 motor-control SDK v6.0 tools user manual.
4.4. Motor-control project compilation
After generating from the workbench, the project is generated for STM32CubeMX but also the IDE. You can:
- Open your IDE and open the source code of your project (If you have enough knowledge to modify the configurations of the peripherals of the motor control, you can open STM32CubeMX, make your modifications then regenerate the project. However, be very careful when modifying the configurations because it is very sensitive).
Once you are in the IDE application and that you have your generated source code open, you can, if you want, add custom code in the users’ sections. When you regenerate the code, the code remains there. However, any custom code added outside the users’ sections is deleted. The next step is to run the code: Download the embedded application to the target from the IDE. If the ST/LINK is correctly installed, this is straightforward to perform. And after that, it is time to test your application.
4.5. Motor pilot
The STM32 MC motor pilot is a control and monitoring PC tool. The serial communication between the motor-control firmware and the PC is managed with the STM32 motor pilot. The motor pilot tool allows us to send basic commands such as start and stop, setting target speed, and clearing fault conditions. You have several parameters and options to test your motor. Open the motor pilot tool either by:
- Using its dedicated button in the ST MC workbench as shown in Figure 1
- Running directly from the installation folder tree as shown in Figure 2
When you are in the motor pilot tool, the first step to do is to connect your board by selecting the correct port. After that click on connect and then you can monitor your motor
After the connection is established, you can click on the Start Motor button to run the motor, monitor the motor speed, and then click on the Stop Motor button to stop the motor.
You can select the speed control or the torque control and test other parameters. When the motor is spinning, you can view the graphs and get recordings of those graphs. You can select the parameters that interest you as input to your graphs.
- Click on the "Plot" button
- Right-click to select the register you want to plot:
More information about the ST MC motor pilot is provided in the STM32 motor-control SDK v6.0 tools user manual.
5. Precaution of use and restrictions
The motor profiling algorithm is intended for rapid evaluation of the ST MC solution. It can be used to drive any three-phase PMSM without any specific instrument or special skill. Although the measurements performed are not as precise as with proper instrumentation, ST Motor Profiler measurements are optimized when:
- The stator resistance is greater than 1 Ω
- The stator inductance is greater than 1 mH
Moreover, it is important to choose the appropriate hardware according to the characteristics of the motor. For instance, the maximum current of the motor must match the maximum current of the board as closely as possible. The ST Motor Profiler may be used only with compatible STMicroelectronics evaluation boards
Warning: Use the ST Motor Profiler tool to refer to the list of supported systems.
6. Revision history
| Date | Revision | Changes |
|---|---|---|
| 01/03/2022 | 1 | Initial release |