getting started with the stspin32f0 foc firmware … · at the end of the compilation and provided...

December 2016 DocID030110 Rev 1 1/20

20

UM2152User manual

Getting started with the STSPIN32F0 FOC firmware exampleSTSW-SPIN3201

Introduction

This document presents how to use the STSW-SPIN3201 firmware example. In association with the evaluation board STEVAL-SPIN3201, this firmware allows to control a 3-phase permanent magnet motor with field-oriented control algorithms in sensorless operations. The STEVAL-SPIN3201 board is designed around the STSPIN32F0, a 3-phase controller with an integrated STM32, and implements 3-shunt resistors as current reading topology.

This document does not details the FOC and sensorless algorithms, the MC API, and the motor control workbench. This information is provided in the UM1052: “STM32F PMSM single/dual FOC SDK v4.3” which is available on www.st.com.

www.st.com

http://www.st.com

Contents UM2152

2/20 DocID030110 Rev 1

Contents

1 Acronyms and abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 STSW-SPIN3201 FW presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2 Package content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2.1 Common folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2.2 Docs folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2.3 Web folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

3 System setup guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.1 Hardware setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.2 Loading the pre-compiled firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3.3 Building and loading a customized firmware . . . . . . . . . . . . . . . . . . . . . . . 7

3.3.1 How to build with IAR IDE? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3.3.2 How to build with Keil µVision IDE? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3.3.3 How to build with system workbench for STM32? . . . . . . . . . . . . . . . . . . 9

3.4 Loading the firmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.5 Using the demonstration applications . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.5.1 Standalone mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.5.2 Connected mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.6 Settings customization with the MC workbench . . . . . . . . . . . . . . . . . . . . 14

3.6.1 Motor section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3.6.2 Power stage section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.6.3 Drive Management section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.6.4 Control stage section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

4 Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

DocID030110 Rev 1 3/20

UM2152 Acronyms and abbreviations

20

1 Acronyms and abbreviations

Table 1. Acronyms and abbreviations

Acronym Description

API Application programming interface

BLDC Brushless direct current

CMSIS Cortex® Microcontroller Software Interface Standard

FOC Field-oriented control

FW Firmware

GUI Graphical user interface

IDE Integrated development environment

MC Motor control

MCU Microcontroller unit

PMSM Permanent magnet synchronous motor

RTOS Real time operating system

SDK Software development kit

STSW-SPIN3201 FW presentation UM2152

4/20 DocID030110 Rev 1

2 STSW-SPIN3201 FW presentation

2.1 Overview

The STSW-SPIN3201 firmware is a customization of the STM32 PMSM FOC FW library, a part of the STM32 PMSM FOC software development kit (STSW-STM32100). It is dedicated to the support of the STEVAL-SPIN3201 evaluation board. It proposes two utilization modes:

A connected mode where the motor is dynamically driven via UART communications by the ST motor control workbench GUI. This GUI is not included in the STSW-SPIN3201 package but it is distributed with the STM32 PMSM FOC SDK (STSW-STM32100).

A standalone mode where the motor is driven only with the user keys and the potentiometer available on the board.

For both these modes, the ST motor control workbench can be used to compute the setting parameters according to your application and to generate the associated header files.

2.2 Package content

The STSW-SPIN3201 package is provided under the form of a zip file. Once unzipped, three main subfolders are available: Common, Docs, Web.

2.2.1 Common folder

Its content can be classified in two categories:

The source code of the standard STM32 library (all the subfolders which are prefixed by the STM32)

The CMSIS files from ARM®. These files are a vendor-independent hardware abstraction layer for the Cortex™-M processor series.

2.2.2 Docs folder

This folder contains the help documentation of the STM32 PMSM FOC SDK.

DocID030110 Rev 1 5/20

UM2152 STSW-SPIN3201 FW presentation

20

2.2.3 Web folder

It contains the interface files for:

The STM32 PMSM motor control software library in the subfolder: MCLibrary. The MC library implements the FOC algorithms. The interface of this library is detailed in the “STM32 FOC PMSM FW library developer Help file.chm” file (in the Docs folder) by searching for the “STM32_PMSM_MC_Library”.

The STM32 PMSM motor control software API in the subfolder: MCApplication. This API offers a set of commands that can be given from a user level in order to execute the motor control actions. The content of this API is explained in the “STM32 FOC PMSM FW library v4_3 developer Help file.chm” file (in the Docs folder) by searching for the “STM32_PMSM_MC_Application”.

The STM32 PMSM motor control user interface library API in the subfolder: UILibrary. The user interface library manages the interactions between the user and the MC library by using the motor control software interface API. This API is described in the “STM32 FOC PMSM FW library v4_3 developer Help file.chm” file (in the Docs folder) by searching for the “STM32_PMSM_UI_Library”.

The Web folder also includes the “SystemDriveParams” subfolder containing the configurations files. These are the files which are automatically generated by the ST MC workbench according to the board and motor configuration.

The “Utilities” subfolder contains the MC workbench example project file: SDK43x-STEVAL-SPIN3201-BullRunning.stmcx. It corresponds to a setup with the STEVAL-SPIN3201 board in association with the Bull-Running BR2804-1700 kV motor.

All the IDEs project files and the code of the demonstration application (main.c, stm32f0xx_it.c/h…) are located in the Project folder.

Last but not least, the Binaries folder contains a pre-compiled binary file performing the standalone mode (EWARM_STEVAL_SPIN3201_BullRunning_Potentiometer.bin) and a pre-compiled binary file for the usage of the board with the MC workbench (EWARM_STEVAL_SPIN3201_BullRunning_MCWorkbench.bin). Both the binaries are dedicated to a setup with the STEVAL-SPIN3201 board in association with the Bull-Running BR2804-1700 kV motor.

System setup guide UM2152

6/20 DocID030110 Rev 1

3 System setup guide

3.1 Hardware setup

To use the firmware example in its default configuration, it is required to have:

One STEVAL-SPIN3201 board

One Bull-Running BR2804-1700 kV brushless motor. A different motor can be used varying the respective settings via the MC workbench (see Section 3.6 on page 14). In this case the firmware must be rebuilt (see Section 3.3).

A 12 V DC power supply. In any case the board supports a power range between 8 V and 45 V. If the supply voltage is changed, this new setting must be applied to the FOC library via the MC workbench (see Section 3.6). In this case the firmware must be rebuilt (see Section 3.3).

A USB cable with a mini-B connector.

Figure 1. STEVAL-SPIN3201 board with a Bull-Running motor

3.2 Loading the pre-compiled firmware

Once the hardware setup is ready, it is necessary to load the board with firmware.

One of the default binaries from the “Web\Binaries” folder can be loaded using the process described in Section 3.4 on page 10.

DocID030110 Rev 1 7/20

UM2152 System setup guide

20

3.3 Building and loading a customized firmware

It is possible to customize the firmware via one of the supported different IDEs:

µVision of the ARM Keil Microcontroller Development Kit (MDK-ARM) toolchain (V5.17 or newer)

IAR embedded workbench for the ARM (EWARM) toolchain (V7.50 or newer) which is provided by IAR Systems®

System workbench for the STM32, a GCC toolchain based on Eclipse and provided by AC6.

Note: The firmware must be rebuilt every time the configuration files of the FOC library are changed as, for example, the characteristics of the target motor or the supply voltage of the application is changed.

The Section 3.3.1, Section 3.3.2, and Section 3.3.3 describe how to build the firmware in each of these environments.

3.3.1 How to build with IAR IDE?

To load the project, just open the workspace by using the following file:

\Web\Project\EWARM\STSPIN32F0_Workspace.eww

Figure 2. STSPIN32F0 workspace under IAR IDE

The workspace is composed of two projects:

The STSPIN32F0_MC Library - STSPIN32F0_SINGLE_DRIVE which contains all the files which are related to the FOC library.

The STSPIN32F0_UserProject - the STEVAL-SPIN3201 which contains the user files which are related to the application, the user interface and of course the main.c file.

To build both projects, go to the menu: “Project->Batch build”. Then select “Rebuild All”.


8/20 DocID030110 Rev 1

At the end of the compilation and provided the board is correctly supplied and that the evaluation board is connected to the PC through the USB cable, it is possible to download the binary and start debugging by the menu: “Project->Download and Debug”.

After the build command, you can also directly download the binary file that you get here:

\Web\Project\EWARM\UserProject\STEVAL-SPIN3201\Exe\STSPIN32F0_UserProject.bin by using the procedure described in Section 3.4.

3.3.2 How to build with Keil µVision IDE?

Start by opening the multi-projects workspace via the file:

\Web\Project\MDK-ARM\ STSPIN32F0_MC Library.uvmpw

Figure 3. STSPIN32F0 workspace under Keil IDE

It includes two projects:

The STSPIN32F0_MC library which contains all the files which are related to the FOC library.

The STSPIN32F0_USerProject which contains the user files which are related to the application, the user interface and of course the main.c file.

To build the two projects, go to the menu: “Project->Batch build”. Then, select “Rebuild”.

DocID030110 Rev 1 9/20


20

After the compilation, you can go to the menu Flash->Download to load the binary providing the board is correctly supplied and that the evaluation board is connected to the PC through the USB cable.

If you want to debug, go to the menu “Debug->Start/Stop debug Session”.

After the build command, you can also directly download the binary file that you get here:

\Web\Project\MDK-ARM\UserProject\STEVAL-SPIN3201\STEVAL-SPIN3201.bin by using the procedure described in Section 3.4.

3.3.3 How to build with system workbench for STM32?

First, open the system workbench for the STM32. In the workspace launcher window, set “\Web\Project\AC6” as the workspace.

Then, go to the menu “File->Import->General->Existing Projects into Workspace”. Set “[yourPath]\Web\Project\AC6” as the root directory and select to import the two projects “STSPIN32F0_MC Library” and “STSPIN32F0_UserProject” before clicking on the “Finish” button.

Figure 4. STSPIN32F0 workspace under system workbench for STM32

After the projects importation, you can build them via the menu “Project->Build All”.

Once the compilation is completed, select the “STSPIN32F0_UserProject” and press “F5” to make a refresh of the folder tree. A folder “Binaries” should appear with an “.elf” file inside. Right-click on it, select “debug as AC6 STM32 C/C++ Application”. This will flash the binary and start the debug window.

You can also directly download the binary file that you get here:

\Web\Project\AC6\STSPIN32F0_UserProject\STEVAL-SPIN3201\ STSPIN32F0_UserProject.bin by using the procedure described in Section 3.4.


10/20 DocID030110 Rev 1

3.4 Loading the firmware

The easiest way to load a new firmware into the device is to copy the binary file into the mass storage interface provided by the ST-LINK, for example to drag and drop it into the disk.

Following the procedure:

First time only: install the STLINK V2-1 drivers that can be downloaded from the ST website (STSW-LINK009).

Connect the evaluation board to a PC with the USB cable.

Supply the evaluation board through the Vin connector (J2) with a DC voltage within the operative range (8 V - 45 V).

A new drive named “SPIN32F0” should appear in the list of removable storages.

Delete all the files on this drive (for example “DETAILS.TXT” file). This step is not mandatory but it is recommended when the binary size is close to the 32 Kbytes maximum limit of the STSPIN32F0 (this is the case of the example binaries). Otherwise, the firmware loading can fail.

Copy the binary file into the root of the drive. The red/green LED of the ST-LINK starts blinking. Then refresh your file explorer: if the binary file has disappeared and no error log file has been generated, the binary file has been successfully loaded.

Reset the board to start the loaded firmware.

3.5 Using the demonstration applications

3.5.1 Standalone mode

In the standalone mode, the provided evaluation board is correctly power supplied and the three phases of the motor are correctly connected to the board, pushing the “USER1” key the motor will start to move. The potentiometer (R6) can be used to dynamically adjust motor speed. With the default configuration, the speed can be adjusted between 800 RPM and 12000 RPM.

To stop the motor, just press the “USER1” button once more.

If an error occurs while the motor is running, the LED of the “USER2” key is turned on and the motor stops. Pushing the “USER1” button again clears the failure.

DocID030110 Rev 1 11/20


20

Figure 5. User interface of the STEVAL-SPIN3201 board

3.5.2 Connected mode

In the connected mode, the provided evaluation board is correctly power supplied and the three phases of the motor are correctly connected to the board, the device can be controlled through the monitor embedded in the MC workbench application.

To use the demonstration application with the MC workbench, it is recommended to disable the possibility to set the speed via the potentiometer. For this purpose, just disable the line: #define EXAMPLE_POTENTIOMETER in the main.c file. Then recompile and download the new binary as described in Section 3.2 on page 6.

Connect the board to the PC with a USB cable, start the MC workbench and open the project file included:

\Web\Utilities\WB_Projects\SDK43x\ SDK43x-STEVAL-SPIN3201-BullRunning.stmcx.

Then click, on the “Open Monitor” icon: .

A new window is opened where the serial port and the baudrate must be selected. By default, the demonstration application uses a baudrate of 115200 bps.

Select the COM port corresponding to the evaluation board and then click on the “Connect” icon: .


12/20 DocID030110 Rev 1

Figure 6. MC workbench interface for UART driving

Using the buttons on the right side, respective commands are sent to the motor driving algorithm. If an error occurs, the respective LED on the left side is turned on. Any operation is not allowed until the failure is not cleared using the “Fault Ack” button.

The “Advanced” and “Registers” tabs can be used to dynamically adjust the parameters of the FOC algorithm.

Depending on the sensorless algorithms enabled, the PWMs frequency of the bridges and the execution rate of the torque regulators, the MCU available resources could be insufficient to guarantee the stability of the UART communications. In this case, the workbench will display an error message.

To avoid this, you can first try to reduce the UART baudrate down to 9600 bps. To perform this, you need to modify the configuration parameters by going to the “Control Stage->Digital I/O” menu as in Figure 7.

DocID030110 Rev 1 13/20


20

Figure 7. Baudrate field in the digital I/O window

Then, you need to generate the configurations files and to recompile. Do not forget to also modify the baudrate in the monitor window of the MC workbench.

If you still face UART-connexions problems, you have to reduce the numbers of MIPS used by the FOC library. In this purpose, go to the main window of the MC workbench and click on the “Drive Management” menu. The following window should appear:

Figure 8. Drive management window of the MC workbench

Then, you will have to reduce the bridges PWM frequency (red box in Figure 8) and/or decrease the torque and flux regulators execution rate by increasing the PWM periods (blue


14/20 DocID030110 Rev 1

box in Figure 8). Once done, you can generate the new configurations files and follow the procedure which is described in Section 3.6. The drawback is that the resolution of the FOC algorithms will be reduced.

3.6 Settings customization with the MC workbench

The MC workbench can be used to set the parameters of the FOC library depending of your motor and application.

As long as the STEVAL-SPIN3201 is used, the MC workbench project file can be used as a starting point:

\Web\Utilities\WB_Projects\SDK43x\ SDK43x-STEVAL-SPIN3201-BullRunning.stmcx.

Once a new setting is defined, press the “Generation” icon .

These will generate 4 configurations files in the folder indicated in the menu “Tools->Output Folder Options”. These files:

Control stage parameters.h

Drive parameters.h

PMSM motor parameters.h

Power stage parameters.h

need then to be copied in the folder \Web\SystemDriveParams\ before doing a new compilation and a new FW download.

3.6.1 Motor section

If a different motor is used, the respective parameters must be updated in the “Motor” section clicking on the “M” box.

Figure 9. Motor menu of the MC workbench

DocID030110 Rev 1 15/20


20

Figure 10. Motor parameters window of the MC workbench

3.6.2 Power stage section

The parameters set via the “Power Stage” section are strictly hardware dependent and must be changed only if the hardware of the board is modified (changing MOSFETs, adjusting the gain of the sensing circuitry, etc.).


16/20 DocID030110 Rev 1

3.6.3 Drive Management section

Then, you will have to go to the Drive Managements menu.

Figure 11. Drive Management menu of the MC workbench

In this menu, the main parameters that you may have to change are indicated in red color in the boxes of Figure 12, Figure 13, and Figure 14.

DocID030110 Rev 1 17/20


20

Figure 12. Speed/Position Feedback Management window of the MC workbench

Figure 13. Drive Settings window of the MC workbench


18/20 DocID030110 Rev 1

Figure 14. Start-up parameters window of the MC workbench

3.6.4 Control stage section

The parameters in the “Control stage” section set the mapping of the STM32 peripherals and they should not be changed as long as the STEVAL-SPIN3201 board is used.

DocID030110 Rev 1 19/20

UM2152 Revision history

20

4 Revision history

Table 2. Document revision history

Date Revision Changes

05-Dec-2016 1 Initial release.

UM2152

20/20 DocID030110 Rev 1

IMPORTANT NOTICE – PLEASE READ CAREFULLY

STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.

Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of Purchasers’ products.

No license, express or implied, to any intellectual property right is granted by ST herein.

Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.

ST and the ST logo are trademarks of ST. All other product or service names are the property of their respective owners.

Information in this document supersedes and replaces information previously supplied in any prior versions of this document.

© 2016 STMicroelectronics – All rights reserved

getting started with the stspin32f0 foc firmware … · at the end of the compilation and provided...

Documents