AMCLIB User's Guide
ARM® Cortex® M4
Document Number: CM4AMCLIBUG
Rev. 2, 10/2015
AMCLIB User's Guide, Rev. 2, 10/2015
2
Freescale Semiconductor, Inc.
Contents
Section number
Title
Page
Chapter 1
Library
1.1
Introduction.................................................................................................................................................................... 5
1.2
Library integration into project (Kinetis Design Studio) .............................................................................................. 7
1.3
Library integration into project (Keil µVision) ............................................................................................................. 15
1.4
Library integration into project (IAR Embedded Workbench) ..................................................................................... 23
Chapter 2
Algorithms in detail
2.1
AMCLIB_TrackObsrv................................................................................................................................................... 31
2.2
AMCLIB_AngleTrackObsrv..........................................................................................................................................35
2.3
AMCLIB_PMSMBemfObsrvDQ...................................................................................................................................41
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
3
AMCLIB User's Guide, Rev. 2, 10/2015
4
Freescale Semiconductor, Inc.
Chapter 1
Library
1.1 Introduction
1.1.1 Overview
This user's guide describes the Advanced Motor Control Library (AMCLIB) for the
family of ARM Cortex M4 core-based microcontrollers. This library contains optimized
functions.
1.1.2 Data types
AMCLIB supports several data types: (un)signed integer, fractional, and accumulator.
The integer data types are useful for general-purpose computation; they are familiar to
the MPU and MCU programmers. The fractional data types enable powerful numeric and
digital-signal-processing algorithms to be implemented. The accumulator data type is a
combination of both; that means it has the integer and fractional portions.
The following list shows the integer types defined in the libraries:
•
•
•
•
Unsigned 16-bit integer —<0 ; 65535> with the minimum resolution of 1
Signed 16-bit integer —<-32768 ; 32767> with the minimum resolution of 1
Unsigned 32-bit integer —<0 ; 4294967295> with the minimum resolution of 1
Signed 32-bit integer —<-2147483648 ; 2147483647> with the minimum resolution
of 1
The following list shows the fractional types defined in the libraries:
• Fixed-point 16-bit fractional —<-1 ; 1 - 2-15> with the minimum resolution of 2-15
• Fixed-point 32-bit fractional —<-1 ; 1 - 2-31> with the minimum resolution of 2-31
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
5
Introduction
The following list shows the accumulator types defined in the libraries:
• Fixed-point 16-bit accumulator —<-256.0 ; 256.0 - 2-7> with the minimum
resolution of 2-7
• Fixed-point 32-bit accumulator —<-65536.0 ; 65536.0 - 2-15> with the minimum
resolution of 2-15
1.1.3 API definition
AMCLIB uses the types mentioned in the previous section. To enable simple usage of the
algorithms, their names use set prefixes and postfixes to distinguish the functions'
versions. See the following example:
f32Result = MLIB_Mac_F32lss(f32Accum, f16Mult1, f16Mult2);
where the function is compiled from four parts:
•
•
•
•
MLIB—this is the library prefix
Mac—the function name—Multiply-Accumulate
F32—the function output type
lss—the types of the function inputs; if all the inputs have the same type as the
output, the inputs are not marked
The input and output types are described in the following table:
Table 1-1. Input/output types
Type
Output
Input
frac16_t
F16
s
frac32_t
F32
l
acc32_t
A32
a
1.1.4 Supported compilers
AMCLIB for the ARM Cortex M4 core is written in C language. The library is built and
tested using the following compilers:
• Kinetis Design Studio
• IAR Embedded Workbench
• Keil µVision
For the Kinetis Design Studio, the library is delivered in the amclib.a file.
AMCLIB User's Guide, Rev. 2, 10/2015
6
Freescale Semiconductor, Inc.
Chapter 1 Library
For the IAR Embedded Workbench, the library is delivered in the amclib.a file.
For the Keil µVision, the library is delivered in the amclib.lib file.
The interfaces to the algorithms included in this library are combined into a single public
interface include file, amclib.h. This is done to lower the number of files required to be
included in your application.
1.1.5 Special issues
1. The equations describing the algorithms are symbolic. If there is positive 1, the
number is the closest number to 1 that the resolution of the used fractional type
allows. If there are maximum or minimum values mentioned, check the range
allowed by the type of the particular function version.
2. The library functions that round the result (the API contains Rnd) round to nearest
(half up).
1.2 Library integration into project (Kinetis Design Studio)
This section provides a step-by-step guide on how to quickly and easily include AMCLIB
into an empty project using Kinetis Design Studio. The example uses the Freescale
MK40DX256xxx10 part and the default installation path (C:\Freescale\FSLESL
\CM4_FSLESL_4.2_KDS) is supposed. If you have a different installation path, use that
path instead.
1.2.1 New project
To start working on an application, create a new project. If the project already exists and
is opened, skip to the next section. Follow the steps given below to create a new project.
1. Launch Kinetis Design Studio.
2. Select File > New > Kinetis Design Studio Project so that the New Kinetis Design
Studio Project dialog appears.
3. Type the name of the project, for example, MyProject01.
4. If you don't use the default location, untick the Use default location checkbox, and
type the path where you want to create the project folder; for example, C:
\KDSProjects\MyProject01, and click Next. See Figure 1-1.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
7
Library integration into project (Kinetis Design Studio)
Figure 1-1. Project name and location
5. Expand the tree by clicking Processors, and then Kinetis K > MK40 > MK40D, and
click MK40DX256xxx10. Click Finish. See Figure 1-2.
Figure 1-2. Processor selection
The newly created project is now visible in the left-hand part of the Kinetis Design
Studio. See Figure 1-3.
Figure 1-3. Project folder
AMCLIB User's Guide, Rev. 2, 10/2015
8
Freescale Semiconductor, Inc.
Chapter 1 Library
1.2.2 Library path variable
To make the library integration easier, create a variable that will hold the information
about the library path.
1. Right-click the MyProject01 node in the left-hand part and click Properties, or select
Project > Properties from the menu. A project properties dialog appears.
2. Expand the Resource node and click Linked Resources. See Figure 1-4.
Figure 1-4. Project properties
3. Click the New… button in the right-hand side.
4. In the dialog that appears (see Figure 1-5), type this variable name into the Name
box: FSLESL_LOC.
5. Select the library parent folder by clicking Folder…, or just type the following path
into the Location box: C:\Freescale\FSLESL\CM4_FSLESL_4.2_KDS. Click OK.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
9
Library integration into project (Kinetis Design Studio)
Figure 1-5. New variable
6. Create such variable for the environment. Expand the C/C++ Build node and click
Environment.
7. Click the Add… button in the right-hand side.
8. In the dialog that appears (see Figure 1-6), type this variable name into the Name
box: FSLESL_LOC.
9. Type the library parent folder path into the Value box: C:\Freescale\FSLESL
\CM4_FSLESL_4.2_KDS.
10. Tick the Add to all configurations box to use this variable in all configurations. See
Figure 1-6.
11. Click OK.
12. In the previous dialog, click OK.
Figure 1-6. Environment variable
AMCLIB User's Guide, Rev. 2, 10/2015
10
Freescale Semiconductor, Inc.
Chapter 1 Library
1.2.3 Library folder addition
To use the library, add it into the Project tree dialog.
1. Right-click the MyProject01 node in the left-hand part and click New > Folder, or
select File > New > Folder from the menu. A dialog appears.
2. Click Advanced to show the advanced options.
3. To link the library source, select the option Link to alternate location (Linked
Folder).
4. Click Variables..., select the FSLESL_LOC variable in the dialog, click OK, and/or
type the variable name into the box. See Figure 1-7.
5. Click Finish, and you will see the library folder linked in the project. See Figure 1-8.
Figure 1-7. Folder link
Figure 1-8. Projects libraries paths
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
11
Library integration into project (Kinetis Design Studio)
1.2.4 Library path setup
AMCLIB requires MLIB and GFLIB and GMCLIB to be included too. The following
steps show how to include all dependent modules:
1. Right-click the MyProject01 node in the left-hand part and click Properties, or select
Project > Properties from the menu. A project properties dialog appears.
2. Expand the C/C++ General node, and click Paths and Symbols.
3. In the right-hand dialog, select the Library Paths tab. See Figure 1-10.
4. Click the Add… button on the right, and a dialog appears.
5. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box by adding the following (see Figure 1-9): ${FSLESL_LOC}\MLIB.
6. Click OK, and then click the Add… button.
7. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box by adding the following: ${FSLESL_LOC}\GFLIB.
8. Click OK, and then click the Add… button.
9. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box by adding the following: ${FSLESL_LOC}\GMCLIB.
10. Click OK, and then click the Add… button.
11. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box by adding the following: ${FSLESL_LOC}\AMCLIB.
12. Click OK, and the paths will be visible in the list. See Figure 1-10.
Figure 1-9. Library path inclusion
AMCLIB User's Guide, Rev. 2, 10/2015
12
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-10. Library paths
13. After adding the library paths, add the library files. Click the Libraries tab. See
Figure 1-12.
14. Click the Add… button on the right, and a dialog appears.
15. Type the following into the File text box (see Figure 1-11): :mlib.a
16. Click OK, and then click the Add… button.
17. Type the following into the File text box: :gflib.a
18. Click OK, and then click the Add… button.
19. Type the following into the File text box: :gmclib.a
20. Click OK, and then click the Add… button.
21. Type the following into the File text box: :amclib.a
22. Click OK, and you will see the libraries added in the list. See Figure 1-12.
Figure 1-11. Library file inclusion
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
13
Library integration into project (Kinetis Design Studio)
Figure 1-12. Libraries
23. In the right-hand dialog, select the Includes tab, and click GNU C in the Languages
list . See Figure 1-14.
24. Click the Add… button on the right, and a dialog appears. See Figure 1-13.
25. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box to be: ${FSLESL_LOC}\MLIB\Include
26. Click OK, and then click the Add… button.
27. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box to be: ${FSLESL_LOC}\GFLIB\Include
28. Click OK, and then click the Add… button.
29. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box to be: ${FSLESL_LOC}\GMCLIB\Include
30. Click OK, and then click the Add… button.
31. Look for the FSLESL_LOC variable by clicking Variables…, and then finish the
path in the box to be: ${FSLESL_LOC}\AMCLIB\Include
32. Click OK, and you will see the paths added in the list. See Figure 1-14. Click OK.
Figure 1-13. Library include path addition
AMCLIB User's Guide, Rev. 2, 10/2015
14
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-14. Compiler setting
Type the #include syntax into the code. Include the library into the main.c file. In the lefthand dialog, open the Sources folder of the project, and double-click the main.c file.
After the main.c file opens up, include the following lines in the #include section:
#include
#include
#include
#include
"mlib.h"
"gflib.h"
"gmclib.h"
"amclib.h"
When you click the Build icon (hammer), the project will be compiled without errors.
1.3 Library integration into project (Keil µVision)
This section provides a step-by-step guide on how to quickly and easily include AMCLIB
into an empty project using Keil µVision. This example uses the Freescale
MKV46F256xxx15 part, and the default installation path (C:\Freescale\FSLESL
\CM4_FSLESL_4.2_KEIL) is supposed. If you have a different installation path, use that
path instead.
1.3.1 Freescale pack installation
If the compiler has never been used to create any Freescale MCU-based projects before,
check whether the Freescale MCU pack for the particular device is installed. Follow these
steps:
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
15
Library integration into project (Keil µVision)
1. Launch Keil µVision.
2. In the main menu, go to Project > Manage > Pack Installer….
3. In the left-hand dialog (under the Devices tab), expand the All Devices > Freescale
node.
4. Look for a line called "KVxx Series" and click it.
5. In the right-hand dialog (under the Packs tab), expand the Device Specific node.
6. Look for a node called "Keil::Kinetis_KVxx_DFP." If there are the Install or Update
options, click the button to install/update the package. See Figure 1-15.
7. When installed, the button has the "Up to date" title. Now close the Pack Installer.
Figure 1-15. Pack Installer
1.3.2 New project
To start working on an application, create a new project. If the project already exists and
is opened, skip to the next section. Follow these steps to create a new project:
1. Launch Keil µVision.
2. In the main menu, select Project > New µVision Project…, and the Create New
Project dialog appears.
3. Navigate to the folder where you want to create the project, for example C:
\KeilProjects\MyProject01. Type the name of the project, for example MyProject01.
Click Save. See Figure 1-16.
AMCLIB User's Guide, Rev. 2, 10/2015
16
Freescale Semiconductor, Inc.
Chapter 1 Library
4.
5.
6.
7.
Figure 1-16. Create New Project dialog
In the next dialog, select the Software Packs in the very first box.
Type 'kv4' into the Search box, so that the device list is reduced to the KV4x devices.
Expand the KV4x node.
Click the MKV46F256xxx15 node, and then click OK. See Figure 1-17.
Figure 1-17. Select Device dialog
8. In the next dialog, expand the Device node, and tick the box next to the Startup node.
See Figure 1-18.
9. Expand the CMSIS node, and tick the box next to the CORE node.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
17
Library integration into project (Keil µVision)
Figure 1-18. Manage Run-Time Environment dialog
10. Click OK, and a new project is created. The new project is now visible in the lefthand part of Keil µVision. See Figure 1-19.
Figure 1-19. Project
11. In the main menu, go to Project > Options for Target 'Target1'…, and a dialog
appears.
12. Select the Target tab.
13. Select Not Used in the Floating Point Hardware option. See Figure 1-19.
Figure 1-20. FPU
AMCLIB User's Guide, Rev. 2, 10/2015
18
Freescale Semiconductor, Inc.
Chapter 1 Library
1.3.3 Linking the files into the project
AMCLIB requires MLIB and GFLIB and GMCLIB to be included too. The following
steps show how to include all dependent modules.
To include the library files in the project, create groups and add them.
1. Right-click the Target 1 node in the left-hand part of the Project tree, and select Add
Group… from the menu. A new group with the name New Group is added.
2. Click the newly created group, and press F2 to rename it to FSLESL.
3. Right-click the FSLESL node, and select Add Existing Files to Group 'FSLESL'…
from the menu.
4. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_KEIL\MLIB\Include, and select the mlib.h file. If the file does
not appear, set the Files of type filter to Text file. Click Add. See Figure 1-21.
Figure 1-21. Adding .h files dialog
5. Navigate to the parent folder C:\Freescale\FSLESL\CM4_FSLESL_4.2_KEIL
\MLIB, and select the mlib.lib file. If the file does not appear, set the Files of type
filter to Library file. Click Add. See Figure 1-22.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
19
Library integration into project (Keil µVision)
Figure 1-22. Adding .lib files dialog
6. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_KEIL\GFLIB\Include, and select the gflib.h file. If the file does
not appear, set the Files of type filter to Text file. Click Add.
7. Navigate to the parent folder C:\Freescale\FSLESL\CM4_FSLESL_4.2_KEIL
\GFLIB, and select the gflib.lib file. If the file does not appear, set the Files of type
filter to Library file. Click Add.
8. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_KEIL\GMCLIB\Include, and select the gmclib.h file. If the file
does not appear, set the Files of type filter to Text file. Click Add.
9. Navigate to the parent folder C:\Freescale\FSLESL\CM4_FSLESL_4.2_KEIL
\GMCLIB, and select the gmclib.lib file. If the file does not appear, set the Files of
type filter to Library file. Click Add.
10. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_KEIL\AMCLIB\Include, and select the amclib.h file. If the file
does not appear, set the Files of type filter to Text file. Click Add.
11. Navigate to the parent folder C:\Freescale\FSLESL\CM4_FSLESL_4.2_KEIL
\AMCLIB, and select the amclib.lib file. If the file does not appear, set the Files of
type filter to Library file. Click Add.
12. Now, all necessary files are in the project tree; see Figure 1-23. Click Close.
AMCLIB User's Guide, Rev. 2, 10/2015
20
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-23. Project workspace
1.3.4 Library path setup
The following steps show the inclusion of all dependent modules.
1. In the main menu, go to Project > Options for Target 'Target1'…, and a dialog
appears.
2. Select the C/C++ tab. See Figure 1-24.
3. In the Include Paths text box, type the following paths (if there are more paths, they
must be separated by ';') or add them by clicking the … button next to the text box:
• "C:\Freescale\FSLESL\CM4_FSLESL_4.2_KEIL\MLIB\Include"
• "C:\Freescale\FSLESL\CM4_FSLESL_4.2_KEIL\GFLIB\Include"
• "C:\Freescale\FSLESL\CM4_FSLESL_4.2_KEIL\GMCLIB\Include"
• "C:\Freescale\FSLESL\CM4_FSLESL_4.2_KEIL\AMCLIB\Include"
4. Click OK.
5. Click OK in the main dialog.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
21
Library integration into project (Keil µVision)
Figure 1-24. Library path addition
Type the #include syntax into the code. Include the library into a source file. In the new
project, it is necessary to create a source file:
1. Right-click the Source Group 1 node, and Add New Item to Group 'Source Group
1'… from the menu.
2. Select the C File (.c) option, and type a name of the file into the Name box, for
example 'main.c'. See Figure 1-25.
AMCLIB User's Guide, Rev. 2, 10/2015
22
Freescale Semiconductor, Inc.
Chapter 1 Library
Figure 1-25. Adding new source file dialog
3. Click Add, and a new source file is created and opened up.
4. In the opened source file, include the following lines into the #include section, and
create a main function:
#include
#include
#include
#include
"mlib.h"
"gflib.h"
"gmclib.h"
"amclib.h"
int main(void)
{
while(1);
}
When you click the Build (F7) icon, the project will be compiled without errors.
1.4 Library integration into project (IAR Embedded
Workbench)
This section provides a step-by-step guide on how to quickly and easily include the
AMCLIB into an empty project using IAR Embedded Workbench. This example uses the
Freescale MKV46F256xxx15 part, and the default installation path (C:\Freescale
\FSLESL\CM4_FSLESL_4.2_IAR) is supposed. If you have a different installation path,
then use that path instead.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
23
Library integration into project (IAR Embedded Workbench)
1.4.1 New project
To start working on an application, create a new project. If the project already exists and
is opened, skip to the next section. Perform these steps to create a new project:
1. Launch IAR Embedded Workbench.
2. In the main menu, select Project > Create New Project… so that the "Create New
Project" dialog appears. See Figure 1-26.
Figure 1-26. Create New Project dialog
3. Expand the C node in the tree, and select the "main" node. Click OK.
4. Navigate to the folder where you want to create the project, for example, C:
\IARProjects\MyProject01. Type the name of the project, for example, MyProject01.
Click Save, and a new project is created. The new project is now visible in the lefthand part of IAR Embedded Workbench. See Figure 1-27.
Figure 1-27. New project
5. In the main menu, go to Project > Options…, and a dialog appears.
AMCLIB User's Guide, Rev. 2, 10/2015
24
Freescale Semiconductor, Inc.
Chapter 1 Library
6. In the Target tab, select the Device option, and click the button next to the dialog to
select the MCU. In this example, select Freescale > KV4x > Freescale
MKV46F256xxx15. Select None in the FPU option. Click OK. See Figure 1-28.
Figure 1-28. Options dialog
1.4.2 Library path variable
To make the library integration easier, create a variable that will hold the information
about the library path.
1. In the main menu, go to Tools > Configure Custom Argument Variables…, and a
dialog appears.
2. Click the New Group button, and another dialog appears. In this dialog, type the
name of the group PATH, and click OK. See Figure 1-29.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
25
Library integration into project (IAR Embedded Workbench)
Figure 1-29. New Group
3. Click on the newly created group, and click the Add Variable button. A dialog
appears.
4. Type this name: FSLESL_LOC
5. To set up the value, look for the library by clicking the '…' button, or just type the
installation path into the box: C:\Freescale\FSLESL\CM4_FSLESL_4.2_IAR. Click
OK.
6. In the main dialog, click OK. See Figure 1-30.
Figure 1-30. New variable
1.4.3 Linking the files into the project
AMCLIB requires MLIB and GFLIB and GMCLIB to be included too. The following
steps show the inclusion of all dependent modules.
To include the library files into the project, create groups and add them.
AMCLIB User's Guide, Rev. 2, 10/2015
26
Freescale Semiconductor, Inc.
Chapter 1 Library
1. Go to the main menu Project > Add Group…
2. Type FSLESL, and click OK.
3. Click on the newly created node FSLESL, go to Project > Add Group…, and create a
MLIB subgroup.
4. Click on the newly created node MLIB, and go to the main menu Project > Add
Files… See Figure 1-32.
5. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_IAR\MLIB\Include, and select the mlib.h file. (If the file does
not appear, set the file-type filter to Source Files.) Click Open. See Figure 1-31.
6. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_IAR\MLIB, and select the mlib.a file. If the file does not
appear, set the file-type filter to Library / Object files. Click Open.
Figure 1-31. Add Files dialog
7. Click on the FSLESL node, go to Project > Add Group…, and create a GFLIB
subgroup.
8. Click on the newly created node GFLIB, and go to the main menu Project > Add
Files….
9. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_IAR\GFLIB\Include, and select the gflib.h file. (If the file does
not appear, set the file-type filter to Source Files.) Click Open.
10. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_IAR\GFLIB, and select the gflib.a file. If the file does not
appear, set the file-type filter to Library / Object files. Click Open.
11. Click on the FSLESL node, go to Project > Add Group…, and create a GMCLIB
subgroup.
12. Click on the newly created node GMCLIB, and go to the main menu Project > Add
Files….
13. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_IAR\GMCLIB\Include, and select the gmclib.h file. If the file
does not appear, set the file-type filter to Source Files. Click Open.
14. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_IAR\GMCLIB, and select the gmclib.a file. If the file does not
appear, set the file-type filter to Library / Object files. Click Open.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
27
Library integration into project (IAR Embedded Workbench)
15. Click on the FSLESL node, go to Project > Add Group…, and create an AMCLIB
subgroup.
16. Click on the newly created node AMCLIB, and go to the main menu Project > Add
Files….
17. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_IAR\AMCLIB\Include, and select the amclib.h file. If the file
does not appear, set the file-type filter to Source Files. Click Open.
18. Navigate into the library installation folder C:\Freescale\FSLESL
\CM4_FSLESL_4.2_IAR\AMCLIB, and select the amclib.a file. If the file does not
appear, set the file-type filter to Library / Object files. Click Open.
19. Now you will see the files added in the workspace. See Figure 1-32.
Figure 1-32. Project workspace
1.4.4 Library path setup
The following steps show the inclusion of all dependent modules:
1. In the main menu, go to Project > Options…, and a dialog appears.
2. In the left-hand column, select C/C++ Compiler.
3. In the right-hand part of the dialog, click on the Preprocessor tab (it can be hidden in
the right; use the arrow icons for navigation).
4. In the text box (at the Additional include directories title), type the following folder
(using the created variable):
• $FSLESL_LOC$\MLIB\Include
• $FSLESL_LOC$\GFLIB\Include
• $FSLESL_LOC$\GMCLIB\Include
• $FSLESL_LOC$\AMCLIB\Include
AMCLIB User's Guide, Rev. 2, 10/2015
28
Freescale Semiconductor, Inc.
Chapter 1 Library
5. Click OK in the main dialog. See Figure 1-33.
Figure 1-33. Library path adition
Type the #include syntax into the code. Include the library included into the main.c file.
In the workspace tree, double-click the main.c file. After the main.c file opens up, include
the following lines into the #include section:
#include
#include
#include
#include
"mlib.h"
"gflib.h"
"gmclib.h"
"amclib.h"
When you click the Make icon, the project will be compiled without errors.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
29
Library integration into project (IAR Embedded Workbench)
AMCLIB User's Guide, Rev. 2, 10/2015
30
Freescale Semiconductor, Inc.
Chapter 2
Algorithms in detail
2.1 AMCLIB_TrackObsrv
The AMCLIB_TrackObsrv function calculates a tracking observer for the determination
of angular speed and position of the input error functional signal. The tracking-observer
algorithm uses the phase-locked-loop mechanism. It is recommended to call this function
at every sampling period. It requires a single input argument as a phase error. A phasetracking observer with a standard PI controller used as the loop compensator is shown in
Figure 2-1.
Figure 2-1. Block diagram of proposed PLL scheme for position estimation
The depicted tracking observer structure has the following transfer function:
Equation 1
The controller gains Kp and Ki are calculated by comparing the characteristic polynomial
of the resulting transfer function to a standard second-order system polynomial.
The essential equations for implementation of the tracking observer according to the
block scheme in Figure 2-1 are as follows:
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
31
AMCLIB_TrackObsrv
Equation 2
Equation 3
where:
•
•
•
•
•
•
•
•
KP is the proportional gain
KI is the integral gain
Ts is the sampling period [s]
e(k) is the position error in step k
ω(k) is the rotor speed [rad / s] in step k
ω(k - 1) is the rotor speed [rad / s] in step k - 1
θ(k) is the rotor angle [rad] in step k
θ(k - 1) is the rotor angle [rad] in step k - 1
In the fractional arithmetic, Equation 1 on page 31 and Equation 2 on page 32 are as
follows:
Equation 4
Equation 5
where:
•
•
•
•
•
•
•
esc(k) is the scaled position error in step k
ωsc(k) is the scaled rotor speed [rad / s] in step k
ωsc(k - 1) is the scaled rotor speed [rad / s] in step k - 1
θsc(k) is the scaled rotor angle [rad] in step k
θsc(k - 1) is the scaled rotor angle [rad] in step k - 1
ωmax is the maximum speed
θmax is the maximum rotor angle (typically)
2.1.1 Available versions
The function is available in the following versions:
• Fractional output - the output is the fractional portion of the result; the result is
within the range <-1 ; 1).
AMCLIB User's Guide, Rev. 2, 10/2015
32
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The available versions of the AMCLIB_TrackObsrv function are shown in the following
table:
Table 2-1. Init versions
Function name
AMCLIB_TrackObsrvInit_F16
Init angle
frac16_t
Parameters
AMCLIB_TRACK_OBSRV_T_F32 *
Result type
void
The input is a 16-bit fractional value of the angle normalized to the range <-1 ; 1) that
represents an angle (in radians) within the range <-π ; π).
Table 2-2. Function versions
Function name
AMCLIB_TrackObsrv_F16
Input type
frac16_t
Parameters
AMCLIB_TRACK_OBSRV_T_F32 *
Result type
frac16_t
Tracking observer with a 16-bit fractional position error input divided by π. The output
from the obsever is a 16-bit fractional position normalized to the range <-1 ; 1) that
represents an angle (in radians) within the range <-π ; π).
2.1.2 AMCLIB_TRACK_OBSRV_T_F32
Variable name
Input
type
Description
f32Theta
frac32_t
Estimated position as the output of the second numerical integrator. The parameter is
within the range <-1 ; 1). Controlled by the algorithm.
f32Speed
frac32_t
Estimated speed as the output of the first numerical integrator. The parameter is within the
range <-1 ; 1). Controlled by the algorithm.
f32I_1
frac32_t
State variable in the controller part of the observer; integral part at step k - 1. The
parameter is within the range <-1 ; 1). Controlled by the algorithm.
f16IGain
frac16_t
The observer integral gain is set up according to Equation 4 on page 32 as:
The parameter is a 16-bit fractional type within the range <0 ; 1). Set by the user.
i16IGainSh
int16_t
The observer integral gain shift takes care of keeping the f16IGain variable within the
fractional range <-1 ; 1). The shift is determined as:
The parameter is a 16-bit integer type within the range <-15 ; 15>. Set by the user.
f16PGain
frac16_t
The observer proportional gain is set up according to Equation 4 on page 32 as:
The parameter is a 16-bit fractional type within the range <0 ; 1). Set by the user.
i16PGainSh
int16_t
The observer proportional gain shift takes care of keeping the f16PGain variable within the
fractional range <-1 ; 1). The shift is determined as:
Table continues on the next page...
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
33
AMCLIB_TrackObsrv
Variable name
Input
type
Description
The parameter is a 16-bit integer type within the range <-15 ; 15>. Set by the user.
f16ThGain
frac16_t
The observer gain for the output position integrator is set up according to Equation 5 on
page 32 as:
The parameter is a 16-bit fractional type within the range <0 ; 1). Set by the user.
i16ThGainSh
int16_t
The observer gain shift for the position integrator takes care of keeping the f16ThGain
variable within the fractional range <-1 ; 1). The shift is determined as:
The parameter is a 16-bit integer type within the range <-15 ; 15>. Set by the user.
2.1.3 Declaration
The available AMCLIB_TrackObsrvInit functions have the following declarations:
void AMCLIB_TrackObsrvInit_F16(frac16_t f16ThetaInit, AMCLIB_TRACK_OBSRV_T_F32 *psCtrl)
The available AMCLIB_TrackObsrv functions have the following declarations:
frac16_t AMCLIB_TrackObsrv_F16(frac16_t f16Error, AMCLIB_TRACK_OBSRV_T_F32 *psCtrl)
2.1.4 Function use
The use of the AMCLIB_TrackObsrv function is shown in the following example:
#include "amclib.h"
static AMCLIB_TRACK_OBSRV_T_F32 sTo;
static frac16_t
f16ThetaError;
static frac16_t
f16PositionEstim;
void Isr(void);
void main(void)
{
sTo.f16IGain
sTo.i16IGainSh
sTo.f16PGain
sTo.i16PGainSh
sTo.f16ThGain
sTo.i16ThGainSh
=
=
=
=
=
=
FRAC16(0.6434);
-9;
FRAC16(0.6801);
-2;
FRAC16(0.6400);
-4;
AMCLIB_TrackObsrvInit_F16(FRAC16(0.0), &sTo);
f16ThetaError
= FRAC16(0.5);
AMCLIB User's Guide, Rev. 2, 10/2015
34
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
}
/* Periodical function or interrupt */
void Isr(void)
{
/* Tracking observer calculation */
f16PositionEstim = AMCLIB_TrackObsrv_F16(f16ThetaError, &sTo);
}
2.2 AMCLIB_AngleTrackObsrv
The AMCLIB_TrackObsrv function calculates an angle-tracking observer for
determination of angular speed and position of the input signal. It requires two input
arguments as sine and cosine samples. The practical implementation of the angle-tracking
observer algorithm is described below.
The angle-tracking observer compares values of the input signals - sin(θ), cos(θ) with
their corresponding estimations. As in any common closed-loop systems, the intent is to
minimize the observer error towards zero value. The observer error is given here by
subtracting the estimated resolver rotor angle from the actual rotor angle.
The tracking-observer algorithm uses the phase-locked loop mechanism. It is
recommended to call this function at every sampling period. It requires a single input
argument as phase error. A phase-tracking observer with standard PI controller used as
the loop compensator is shown in Figure 2-2.
Figure 2-2. Block diagram of proposed PLL scheme for position estimation
Note that the mathematical expression of the observer error is known as the formula of
the difference between two angles:
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
35
AMCLIB_AngleTrackObsrv
Equation 6
If the deviation between the estimated and the actual angle is very small, then the
observer error may be expressed using the following equation:
Equation 7
The primary benefit of the angle-tracking observer utilization, in comparison with the
trigonometric method, is its smoothing capability. This filtering is achieved by the
integrator and the proportional and integral controllers, which are connected in series and
closed by a unit feedback loop. This block diagram tracks the actual rotor angle and
speed, and continuously updates their estimations. The angle-tracking observer transfer
function is expressed as follows:
Equation 8
The characteristic polynomial of the angle-tracking observer corresponds to the
denominator of the following transfer function:
Appropriate dynamic behavior of the angle-tracking observer is achieved by the
placement of the poles of characteristic polynomial. This general method is based on
matching the coefficients of characteristic polynomial with the coefficients of a general
second-order system.
The analog integrators in the previous figure (marked as 1 / s) are replaced by an
equivalent of the discrete-time integrator using the backward Euler integration method.
The discrete-time block diagram of the angle-tracking observer is shown in the following
figure:
AMCLIB User's Guide, Rev. 2, 10/2015
36
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Figure 2-3. Block scheme of discrete-time tracking observer
The essential equations for implementating the angle-tracking observer (according to this
block scheme) are as follows:
Equation 9
Equation 10
Equation 11
Equation 12
where:
•
•
•
•
•
•
•
•
•
•
K1 is the integral gain of the I controller
K2 is the proportional gain of the PI controller
Ts is the sampling period [s]
e(k) is the position error in step k
ω(k) is the rotor speed [rad / s] in step k
ω(k - 1) is the rotor speed [rad / s] in step k - 1
a(k) is the integral output of the PI controler [rad / s] in step k
a(k - 1) is the integral output of the PI controler [rad / s] in step k - 1
θ(k) is the rotor angle [rad] in step k
θ(k - 1) is the rotor angle [rad] in step k - 1
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
37
AMCLIB_AngleTrackObsrv
• θ̂(k) is the estimated rotor angle [rad] in step k
• θ̂(k - 1) is the estimated rotor angle [rad] in step k - 1
In the fractional arithmetic, Equation 9 on page 37 to Equation 12 on page 37 are as
follows:
Equation 13
Equation 14
Equation 15
where:
•
•
•
•
•
•
•
•
•
•
•
esc(k) is the scaled position error in step k
ωsc(k) is the scaled rotor speed [rad / s] in step k
ωsc(k - 1) is the scaled rotor speed [rad / s] in step k - 1
asc(k) is the integral output of the PI controler [rad / s] in step k
asc(k - 1) is the integral output of the PI controler [rad / s] in step k - 1
θsc(k) is the scaled rotor angle [rad] in step k
θsc(k - 1) is the scaled rotor angle [rad] in step k - 1
θ̂sc(k) is the scaled rotor angle [rad] in step k
θ̂sc(k - 1) is the scaled rotor angle [rad] in step k - 1
ωmax is the maximum speed
θmax is the maximum rotor angle (typicaly π)
2.2.1 Available versions
The function is available in the following versions:
• Fractional output - the output is the fractional portion of the result; the result is
within the range <-1 ; 1).
AMCLIB User's Guide, Rev. 2, 10/2015
38
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
The available versions of the AMCLIB_AngleTrackObsrv function are shown in the
following table:
Table 2-3. Init versions
Function name
Init angle
AMCLIB_AngleTrackObsrvInit_F16
frac16_t
Parameters
AMCLIB_ANGLE_TRACK_OBSRV_T_F32 *
Result
type
void
The input is a 16-bit fractional value of the angle normalized to the range <-1 ; 1)
that represents an angle in (radians) within the range <-π ; π).
Table 2-4. Function versions
Function name
AMCLIB_AngleTrackObsrv_F16
Input type
Parameters
GMCLIB_2COOR_SINCOS_T_F16 *
Result
type
AMCLIB_ANGLE_TRACK_OB frac16_t
SRV_T_F32 *
Angle-tracking observer with a two-componenent (sin/cos) 16-bit fractional position
input within the range <-1 ; 1). The output from the obsever is a 16-bit fractional
position normalized to the range <-1 ; 1) that represents an angle (in radians) within
the range <-π ; π).
2.2.2 AMCLIB_ANGLE_TRACK_OBSRV_T_F32
Variable name
Input
type
Description
f32Speed
frac32_t
Estimated speed as the output of the first numerical integrator. The parameter is within the
range <-1 ; 1). Controlled by the AMCLIB_AngleTrackObsrv_F16 algorithm; cleared by the
AMCLIB_AngleTrackObsrvInit_F16 function.
f32A2
frac32_t
Output of the second numerical integrator. The parameter is within the range <-1 ; 1).
Controlled by the AMCLIB_AngleTrackObsrv_F16 and AMCLIB_AngleTrackObsrvInit_F16
algorithms.
f16Theta
frac16_t
Estimated position as the output of the observer. The parameter is normalized to the range
<-1 ; 1) that represents an angle (in radians) within the range <-π ; π). Controlled by the
AMCLIB_AngleTrackObsrv_F16 and AMCLIB_AngleTrackObsrvInit_F16 algorithms.
f16SinEstim
frac16_t
Sine of the estimated position as the output of the actual step. Keeps the sine of the
position for the next step. The parameter is within the range <-1 ; 1). Controlled by the
AMCLIB_AngleTrackObsrv_F16 and AMCLIB_AngleTrackObsrvInit_F16 algorithms.
f16CosEstim
frac16_t
Cosine of the estimated position as the output of the actual step. Keeps the cosine of the
position for the next step. The parameter is within the range <-1 ; 1). Controlled by the
AMCLIB_AngleTrackObsrv_F16 and AMCLIB_AngleTrackObsrvInit_F16 algorithms.
f16K1Gain
frac16_t
Observer K1 gain is set up according to Equation 13 on page 38 as:
The parameter is a 16-bit fractional type within the range <0 ; 1). Set by the user.
Table continues on the next page...
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
39
AMCLIB_AngleTrackObsrv
Variable name
i16K1GainSh
Input
type
int16_t
Description
Observer K2 gain shift takes care of keeping the f16K1Gain variable within the fractional
range <-1 ; 1). The shift is determined as:
The parameter is a 16-bit integer type within the range <-15 ; 15>. Set by the user.
f16K2Gain
frac16_t
Observer K2 gain is set up according to Equation 15 on page 38 as:
The parameter is a 16-bit fractional type within the range <0 ; 1). Set by the user.
i16K2GainSh
int16_t
Observer K2 gain shift takes care of keeping the f16K2Gain variable within the fractional
range <-1 ; 1). The shift is determined as:
The parameter is a 16-bit integer type within the range <-15 ; 15>. Set by the user.
f16A2Gain
frac16_t
Observer A2 gain for the output position is set up according to Equation 14 on page 38 as:
The parameter is a 16-bit fractional type within the range <0 ; 1). Set by the user.
i16A2GainSh
int16_t
Observer A2 gain shift for the position integrator takes care of keeping the f16A2Gain
variable within the fractional range <-1 ; 1). The shift is determined as:
The parameter is a 16-bit integer type within the range <-15 ; 15>. Set by the user.
2.2.3 Declaration
The available AMCLIB_AngleTrackObsrvInit functions have the following declarations:
void AMCLIB_AngleTrackObsrvInit_F16(frac16_t f16ThetaInit, AMCLIB_ANGLE_TRACK_OBSRV_T_F32
*psCtrl)
The available AMCLIB_AngleTrackObsrv functions have the following declarations:
frac16_t AMCLIB_AngleTrackObsrv_F16(const GMCLIB_2COOR_SINCOS_T_F16 *psAnglePos,
AMCLIB_ANGLE_TRACK_OBSRV_T_F32 *psCtrl)
2.2.4 Function use
The use of the AMCLIB_AngleTrackObsrvInit and AMCLIB_AngleTrackObsrv
functions is shown in the following example:
AMCLIB User's Guide, Rev. 2, 10/2015
40
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
#include "amclib.h"
static AMCLIB_ANGLE_TRACK_OBSRV_T_F32 sAto;
static GMCLIB_2COOR_SINCOS_T_F16 sAnglePos;
static frac16_t
f16PositionEstim, f16PositionInit;
void Isr(void);
void main(void)
{
sAto.f16K1Gain
sAto.i16K1GainSh
sAto.f16K2Gain
sAto.i16K2GainSh
sAto.f16A2Gain
sAto.i16A2GainSh
=
=
=
=
=
=
FRAC16(0.6434);
-9;
FRAC16(0.6801);
-2;
FRAC16(0.6400);
-4;
f16PositionInit = FRAC16(0.0);
AMCLIB_AngleTrackObsrvInit_F16(f16PositionInit, &sAto);
}
sAnglePos.f16Sin
sAnglePos.f16Cos
= FRAC16(0.0);
= FRAC16(1.0);
/* Periodical function or interrupt */
void Isr(void)
{
/* Angle tracking observer calculation */
f16PositionEstim = AMCLIB_AngleTrackObsrv_F16(&sAnglePos, &sAto);
}
2.3 AMCLIB_PMSMBemfObsrvDQ
The AMCLIB_PMSMBemfObsrvDQ function calculates the algorithm of back-electromotive force observer in a rotating reference frame. The method for estimating the rotor
position and angular speed is based on the mathematical model of an interior PMSM
motor with an extended electro-motive force function, which is realized in an estimated
quasi-synchronous reference frame γ-δ as shown in Figure 2-4.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
41
AMCLIB_PMSMBemfObsrvDQ
Figure 2-4. The estimated and real rotor dq synchronous reference frames
The back-EMF observer detects the generated motor voltages induced by the permanent
magnets. A tracking observer uses the back-EMF signals to calculate the position and
speed of the rotor. The transformed model is then derived as follows:
Equation 16
where:
•
•
•
•
•
•
•
•
RS is the stator resistance
LD and LQ are the D-axis and Q-axis inductances
Ψm is the back-EMF constant
ωr is the angular electrical rotor speed
uγ and uδ are the estimated stator voltages
iγ and iδ are the estimated stator currents
θerror is the error between the actual D-Q frame and the estimated frame position
s is the operator of the derivative
The block diagram of the observer in the estimated reference frame is shown in Figure
2-5. The observer compensator is substituted by a standard PI controller. As shown in
Figure 2-5, the observer model and hence also the PI controller gains in both axes are
identical to each other.
AMCLIB User's Guide, Rev. 2, 10/2015
42
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Figure 2-5. Block diagram of proposed Luenberger-type stator current observer acting
as state filter for back-EMF
The position estimation can now be performed by extracting the θerror term from the
model, and adjusting the position of the estimated reference frame to achieve θerror = 0.
Because the θerror term is only included in the saliency-based EMF component of both uγ
and uδ axis voltage equations, the Luenberger-based disturbance observer is designed to
observe the uγ and uδ voltage components. The position displacement information θerror
is then obtained from the estimated back-EMFs as follows:
Equation 17
The estimated position can be obtained by driving the position of the estimated
reference frame to achieve zero displacement θerror = 0. The phase-locked-loop
mechanism can be adopted, where the loop compensator ensures correct tracking of the
actual rotor flux position by keeping the error signal θerror zeroed, θerror = 0.
A perfect match between the actual and estimated motor model parameters is assumed,
and then the back-EMF transfer function can be simplified as follows:
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
43
AMCLIB_PMSMBemfObsrvDQ
Equation 18
The appropriate dynamic behavior of the back-EMF observer is achieved by the
placement of the poles of the stator current observer characteristic polynomial. This
general method is based on matching the coefficients of the characteristic polynomial
with the coefficients of the general second-order system.
The back-EMF observer is a Luenberger-type observer with a motor model, which is
implemented using the backward Euler transformation as follows:
Equation 19
where:
•
•
•
•
•
•
•
i(k) = [iγ, iδ] is the stator current vector in the actual step
i(k - 1) = [iγ, iδ] is the stator current vector in the previous step
u(k) = [uγ, uδ] is the stator voltage vector in the actual step
e(k) = [eγ, eδ] is the stator back-EMF voltage vector in the actual step
i'(k) = [iγ, -iδ] is the complementary stator current vector in the actual step
ωe(k) is the electrical angular speed in the actual step
TS is the sampling time [s]
This equation is transformed into the fractional arithmetic as follows:
Equation 20
where:
•
•
•
•
•
•
•
•
•
•
isc(k) = [iγ, iδ] is the scaled stator current vector in the actual step
isc(k - 1) = [iγ, iδ] is the scaled stator current vector in the previous step
usc(k) = [uγ, uδ] is the scaled stator voltage vector in the actual step
esc(k) = [eγ, eδ] is the scaled stator back-EMF voltage vector in the actual step
i'sc(k) = [iγ, -iδ] is the scaled complementary stator current vector in the actual step
ωesc(k) is the scaled electrical angular speed in the actual step
imax is the maximum current [A]
emax is the maximum back-EMF voltage [V]
umax is the maximum stator voltage [V]
ωmax is the maximum electrical angular speed in [rad / s]
AMCLIB User's Guide, Rev. 2, 10/2015
44
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
If the Luenberger-type stator current observer is properly designed in the stationary
reference frame, the back-EMF can be estimated as a disturbance produced by the
observer controller. However, this is only valid when the back-EMF term is not included
in the observer model. The observer is a closed-loop current observer, therefore it acts as
a state filter for the back-EMF term.
The estimate of the extended EMF term can be derived from Equation 18 on page 44 as
follows:
Equation 21
The observer controller can be designed by comparing the closed-loop characteristic
polynomial with that of a standard second-order system as follows:
Equation 22
where:
•
•
•
•
ω0 is the natural frequency of the closed-loop system (loop bandwith)
ξ is the loop attenuation
KP is the proporional gain
kI is the integral gain
2.3.1 Available versions
This function is available in the following versions:
• Fractional output - the output is the fractional portion of the result; the result is
within the range <-1 ; 1). The parameters use the accumulator types.
• Accumulator output with floating-point inputs - the output is the accumulator result;
the result is within the range <-1 ; 1). The inputs are 32-bit single precision floatingpoint values.
The available versions of the AMCLIB_PMSMBemfObsrvDQ function are shown in the
following table:
Table 2-5. Init versions
Function name
AMCLIB_PMSMBemfObsrvDQInit_F16
Parameters
AMCLIB_BEMF_OBSRV_DQ_T_A32 *
Result type
void
Initialization does not have any input.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
45
AMCLIB_PMSMBemfObsrvDQ
Table 2-6. Function versions
Function name
Input/output type
Input
AMCLIB_PMSMBemfObsrvDQ_F16
Result type
GMCLIB_2COOR_DQ_T_F16 *
frac16_t
GMCLIB_2COOR_DQ_T_F16 *
frac16_t
Parameters
AMCLIB_BEMF_OBSRV_DQ_T_A32 *
Back-EMF observer with a 16-bit fractional input D-Q current and voltage, and
a 16-bit electrical speed. All are within the range <-1 ; 1).
2.3.2 AMCLIB_BEMF_OBSRV_DQ_T_A32 type description
Variable name
Data type
Description
sEObsrv
GMCLIB_2COOR_DQ_T_ Estimated back-EMF voltage structure.
F32
sIObsrv
GMCLIB_2COOR_DQ_T_ Estimated current structure.
F32
sCtrl
f32ID_1
frac32_t
State variable in the alpha part of the observer, integral part
at step k - 1. The variable is within the range <-1 ; 1).
f32IQ_1
frac32_t
State variable in the beta part of the observer, integral part
at step k - 1. The variable is within the range <-1 ; 1).
a32PGain
acc32_t
The observer proportional gain is set up according to
Equation 22 on page 45 as:
The parameter is within the range <0 ; 65536.0). Set by the
user.
a32IGain
acc32_t
The observer integral gain is set up according to Equation
22 on page 45 as:
The parameter is within the range <0 ; 65536.0). Set by the
user.
a32IGain
acc32_t
The current coefficient gain is set up according to Equation
20 on page 44 as:
The parameter is within the range <0 ; 65536.0). Set by the
user.
a32UGain
acc32_t
The voltage coefficient gain is set up according to Equation
20 on page 44 as:
Table continues on the next page...
AMCLIB User's Guide, Rev. 2, 10/2015
46
Freescale Semiconductor, Inc.
Chapter 2 Algorithms in detail
Variable name
Data type
Description
The parameter is within the range <0 ; 65536.0). Set by the
user.
a32WIGain
acc32_t
The angular speed coefficient gain is set up according to
Equation 20 on page 44 as:
The parameter is within the range <0 ; 65536.0). Set by the
user.
a32EGain
acc32_t
The back-EMF coefficient gain is set up according to
Equation 20 on page 44 as:
The parameter is within the range <0 ; 65536.0). Set by the
user.
f16Error
frac16_t
Output - estimated phase error between a real D / Q frame
system and an estimated D / Q reference system. The error
is within the range <-1 ; 1).
2.3.3 Declaration
The available AMCLIB_PMSMBemfObsrvDQInit functions have the following
declarations:
void AMCLIB_PMSMBemfObsrvDQInit_F16(AMCLIB_BEMF_OBSRV_DQ_T_A32 *psCtrl)
The available AMCLIB_PMSMBemfObsrvDQ functions have the following
declarations:
frac16_t AMCLIB_PMSMBemfObsrvDQ_F16(const GMCLIB_2COOR_DQ_T_F16 *psIDQ, const
GMCLIB_2COOR_DQ_T_F16 *psUDQ, frac16_t f16Speed, AMCLIB_BEMF_OBSRV_DQ_T_A32 *psCtrl)
2.3.4 Function use
The use of the AMCLIB_PMSMBemfObsrvDQ function is shown in the following
example:
#include "amclib.h"
static GMCLIB_2COOR_DQ_T_F16
sIdq, sUdq;
static AMCLIB_BEMF_OBSRV_DQ_T_A32 sBemfObsrv;
static frac16_t f16Speed, f16Error;
void Isr(void);
void main (void)
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
47
AMCLIB_PMSMBemfObsrvDQ
{
sBemfObsrv.sCtrl.a32PGain= ACC32(1.697);
sBemfObsrv.sCtrl.a32IGain= ACC32(0.134);
sBemfObsrv.a32IGain = ACC32(0.986);
sBemfObsrv.a32UGain = ACC32(0.170);
sBemfObsrv.a32WIGain= ACC32(0.110);
sBemfObsrv.a32EGain = ACC32(0.116);
/* Initialization of the observer's structure */
AMCLIB_PMSMBemfObsrvDQInit_F16(&sBemfObsrv);
}
sIdq.f16D
sIdq.f16Q
sUdq.f16D
sUdq.f16Q
=
=
=
=
FRAC16(0.05);
FRAC16(0.1);
FRAC16(0.2);
FRAC16(-0.1);
/* Periodical function or interrupt */
void Isr(void)
{
/* BEMF Observer calculation */
f16Error = AMCLIB_PMSMBemfObsrvDQ_F16(&sIdq, &sUdq, f16Speed, &sBemfObsrv);
}
AMCLIB User's Guide, Rev. 2, 10/2015
48
Freescale Semiconductor, Inc.
Appendix A
Library types
A.1 bool_t
The bool_t type is a logical 16-bit type. It is able to store the boolean variables with two
states: TRUE (1) or FALSE (0). Its definition is as follows:
typedef unsigned short bool_t;
The following figure shows the way in which the data is stored by this type:
Table A-1. Data storage
15
14
13
12
11
10
9
Value
TRUE
FALSE
8
7
6
5
4
3
2
1
Logi
cal
Unused
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
1
0
0
1
0
0
0
0
0
0
To store a logical value as bool_t, use the FALSE or TRUE macros.
A.2 uint8_t
The uint8_t type is an unsigned 8-bit integer type. It is able to store the variables within
the range <0 ; 255>. Its definition is as follows:
typedef unsigned char int8_t;
The following figure shows the way in which the data is stored by this type:
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
49
uint16_t
Table A-2. Data storage
7
6
5
4
Value
2
1
0
1
1
1
1
1
1
0
0
1
1
Integer
1
255
3
1
1
1
F
0
11
0
F
0
0
1
0
0
0
124
1
B
1
1
1
1
7
1
159
0
C
0
1
1
1
9
F
A.3 uint16_t
The uint16_t type is an unsigned 16-bit integer type. It is able to store the variables
within the range <0 ; 65535>. Its definition is as follows:
typedef unsigned short uint16_t;
The following figure shows the way in which the data is stored by this type:
Table A-3. Data storage
15
14
13
12
11
10
9
8
Value
65535
5
15518
40768
7
6
5
4
3
2
1
0
1
1
1
1
1
1
0
0
0
1
0
1
1
0
0
0
Integer
1
1
0
0
1
1
1
1
0
0
0
0
F
0
1
0
1
0
0
0
0
F
1
1
1
1
1
0
1
0
1
0
5
0
1
1
1
9
1
F
F
0
C
0
9
1
0
3
1
1
F
0
0
1
1
0
1
E
0
4
0
0
0
0
A.4 uint32_t
AMCLIB User's Guide, Rev. 2, 10/2015
50
Freescale Semiconductor, Inc.
Appendix A Library types
The uint32_t type is an unsigned 32-bit integer type. It is able to store the variables
within the range <0 ; 4294967295>. Its definition is as follows:
typedef unsigned long uint32_t;
The following figure shows the way in which the data is stored by this type:
Table A-4. Data storage
31
24 23
16 15
Value
8 7
0
Integer
4294967295
F
F
F
F
F
F
F
F
2147483648
8
0
0
0
0
0
0
0
55977296
0
3
5
6
2
5
5
0
3451051828
C
D
B
2
D
F
3
4
A.5 int8_t
The int8_t type is a signed 8-bit integer type. It is able to store the variables within the
range <-128 ; 127>. Its definition is as follows:
typedef char int8_t;
The following figure shows the way in which the data is stored by this type:
Table A-5. Data storage
7
Value
127
-128
60
-97
6
5
4
Sign
0
3
2
1
1
1
1
1
0
0
0
0
0
1
0
0
0
0
0
1
1
0
1
1
1
1
3
1
1
F
8
0
0
Integer
7
1
1
0
C
0
1
1
9
1
F
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
51
int16_t
A.6 int16_t
The int16_t type is a signed 16-bit integer type. It is able to store the variables within the
range <-32768 ; 32767>. Its definition is as follows:
typedef short int16_t;
The following figure shows the way in which the data is stored by this type:
Table A-6. Data storage
15
Value
32767
-32768
15518
-24768
14
13
12
11
10
9
8
Sign
7
6
5
4
3
2
1
0
1
1
1
1
1
1
1
0
0
1
0
0
0
Integer
0
1
1
1
1
1
7
1
0
0
0
0
0
0
1
0
1
F
0
0
0
0
0
1
1
1
3
1
1
F
8
0
1
0
1
1
0
1
0
0
0
0
0
0
1
0
C
9
F
0
0
1
1
1
9
1
1
0
1
F
E
0
0
0
0
4
0
A.7 int32_t
The int32_t type is a signed 32-bit integer type. It is able to store the variables within the
range <-2147483648 ; 2147483647>. Its definition is as follows:
typedef long int32_t;
The following figure shows the way in which the data is stored by this type:
Table A-7. Data storage
31
Value
24 23
16 15
S
8 7
0
Integer
2147483647
7
F
F
F
F
F
F
F
-2147483648
8
0
0
0
0
0
0
0
55977296
0
3
5
6
2
5
5
0
-843915468
C
D
B
2
D
F
3
4
AMCLIB User's Guide, Rev. 2, 10/2015
52
Freescale Semiconductor, Inc.
Appendix A Library types
A.8 frac8_t
The frac8_t type is a signed 8-bit fractional type. It is able to store the variables within
the range <-1 ; 1). Its definition is as follows:
typedef char frac8_t;
The following figure shows the way in which the data is stored by this type:
Table A-8. Data storage
7
Value
0.99219
-1.0
0.46875
-0.75781
6
5
4
3
Sign
2
1
0
1
1
1
0
0
0
0
1
1
Fractional
0
1
1
1
1
7
1
0
F
0
0
0
0
8
0
0
0
1
1
1
1
3
1
0
C
0
1
1
1
9
F
To store a real number as frac8_t, use the FRAC8 macro.
A.9 frac16_t
The frac16_t type is a signed 16-bit fractional type. It is able to store the variables within
the range <-1 ; 1). Its definition is as follows:
typedef short frac16_t;
The following figure shows the way in which the data is stored by this type:
Table A-9. Data storage
15
Value
0.99997
-1.0
14
13
12
11
10
9
8
Sign
0
6
5
4
3
2
1
0
1
1
1
1
1
1
1
0
0
Fractional
1
1
1
1
1
7
1
7
0
1
1
1
F
0
0
0
0
F
0
0
0
0
F
0
0
0
0
Table continues on the next page...
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
53
frac32_t
Table A-9. Data storage (continued)
8
0.47357
-0.75586
0
0
0
1
1
1
1
3
1
0
0
0
0
1
0
C
0
1
1
1
9
0
0
1
1
1
9
1
1
0
1
F
1
0
0
0
E
0
0
0
0
4
0
To store a real number as frac16_t, use the FRAC16 macro.
A.10 frac32_t
The frac32_t type is a signed 32-bit fractional type. It is able to store the variables within
the range <-1 ; 1). Its definition is as follows:
typedef long frac32_t;
The following figure shows the way in which the data is stored by this type:
Table A-10. Data storage
31
Value
24 23
16 15
S
8 7
0
Fractional
0.9999999995
7
F
F
F
F
F
F
F
-1.0
8
0
0
0
0
0
0
0
0.02606645970
0
3
5
6
2
5
5
0
-0.3929787632
C
D
B
2
D
F
3
4
To store a real number as frac32_t, use the FRAC32 macro.
A.11 acc16_t
The acc16_t type is a signed 16-bit fractional type. It is able to store the variables within
the range <-256 ; 256). Its definition is as follows:
typedef short acc16_t;
The following figure shows the way in which the data is stored by this type:
AMCLIB User's Guide, Rev. 2, 10/2015
54
Freescale Semiconductor, Inc.
Appendix A Library types
Table A-11. Data storage
15
Value
255.9921875
-256.0
1.0
-1.0
13.7890625
-89.71875
14
13
12
Sign
11
10
9
8
7
6
5
4
Integer
0
1
1
1
1
1
0
0
0
0
8
0
0
0
1
0
0
0
1
1
1
1
0
0
0
0
0
1
0
1
D
1
1
1
0
0
0
0
0
0
0
0
0
1
0
0
0
1
0
0
0
0
0
0
1
0
0
0
0
0
0
8
1
0
1
8
1
1
1
0
0
1
1
6
0
0
F
0
F
0
1
0
0
1
0
1
1
0
1
1
F
0
0
F
0
1
0
0
1
1
F
0
2
Fractional
1
7
3
0
1
0
0
1
E
1
1
0
0
3
5
1
0
0
1
2
4
To store a real number as acc16_t, use the ACC16 macro.
A.12 acc32_t
The acc32_t type is a signed 32-bit accumulator type. It is able to store the variables
within the range <-65536 ; 65536). Its definition is as follows:
typedef long acc32_t;
The following figure shows the way in which the data is stored by this type:
Table A-12. Data storage
31
Value
24 23
S
16 15
8 7
Integer
0
Fractional
65535.999969
7
F
F
F
F
F
F
F
-65536.0
8
0
0
0
0
0
0
0
1.0
0
0
0
0
8
0
0
0
-1.0
F
F
F
F
8
0
0
0
23.789734
0
0
0
B
E
5
1
6
-1171.306793
F
D
B
6
5
8
B
C
To store a real number as acc32_t, use the ACC32 macro.
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
55
GMCLIB_3COOR_T_F16
A.13 GMCLIB_3COOR_T_F16
The GMCLIB_3COOR_T_F16 structure type corresponds to the three-phase stationary
coordinate system, based on the A, B, and C components. Each member is of the frac16_t
data type. The structure definition is as follows:
typedef struct
{
frac16_t f16A;
frac16_t f16B;
frac16_t f16C;
} GMCLIB_3COOR_T_F16;
The structure description is as follows:
Table A-13. GMCLIB_3COOR_T_F16 members description
Type
Name
Description
frac16_t
f16A
A component; 16-bit fractional type
frac16_t
f16B
B component; 16-bit fractional type
frac16_t
f16C
C component; 16-bit fractional type
A.14 GMCLIB_2COOR_ALBE_T_F16
The GMCLIB_2COOR_ALBE_T_F16 structure type corresponds to the two-phase
stationary coordinate system, based on the Alpha and Beta orthogonal components. Each
member is of the frac16_t data type. The structure definition is as follows:
typedef struct
{
frac16_t f16Alpha;
frac16_t f16Beta;
} GMCLIB_2COOR_ALBE_T_F16;
The structure description is as follows:
Table A-14. GMCLIB_2COOR_ALBE_T_F16 members description
Type
Name
Description
frac16_t
f16Apha
α-component; 16-bit fractional type
frac16_t
f16Beta
β-component; 16-bit fractional type
AMCLIB User's Guide, Rev. 2, 10/2015
56
Freescale Semiconductor, Inc.
Appendix A Library types
A.15 GMCLIB_2COOR_DQ_T_F16
The GMCLIB_2COOR_DQ_T_F16 structure type corresponds to the two-phase rotating
coordinate system, based on the D and Q orthogonal components. Each member is of the
frac16_t data type. The structure definition is as follows:
typedef struct
{
frac16_t f16D;
frac16_t f16Q;
} GMCLIB_2COOR_DQ_T_F16;
The structure description is as follows:
Table A-15. GMCLIB_2COOR_DQ_T_F16 members description
Type
Name
Description
frac16_t
f16D
D-component; 16-bit fractional type
frac16_t
f16Q
Q-component; 16-bit fractional type
A.16 GMCLIB_2COOR_DQ_T_F32
The GMCLIB_2COOR_DQ_T_F32 structure type corresponds to the two-phase rotating
coordinate system, based on the D and Q orthogonal components. Each member is of the
frac32_t data type. The structure definition is as follows:
typedef struct
{
frac32_t f32D;
frac32_t f32Q;
} GMCLIB_2COOR_DQ_T_F32;
The structure description is as follows:
Table A-16. GMCLIB_2COOR_DQ_T_F32 members description
Type
Name
Description
frac32_t
f32D
D-component; 32-bit fractional type
frac32_t
f32Q
Q-component; 32-bit fractional type
A.17 GMCLIB_2COOR_SINCOS_T_F16
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
57
FALSE
The GMCLIB_2COOR_SINCOS_T_F16 structure type corresponds to the two-phase
coordinate system, based on the Sin and Cos components of a certain angle. Each
member is of the frac16_t data type. The structure definition is as follows:
typedef struct
{
frac16_t f16Sin;
frac16_t f16Cos;
} GMCLIB_2COOR_SINCOS_T_F16;
The structure description is as follows:
Table A-17. GMCLIB_2COOR_SINCOS_T_F16 members description
Type
Name
Description
frac16_t
f16Sin
Sin component; 16-bit fractional type
frac16_t
f16Cos
Cos component; 16-bit fractional type
A.18 FALSE
The FALSE macro serves to write a correct value standing for the logical FALSE value
of the bool_t type. Its definition is as follows:
#define FALSE
((bool_t)0)
#include "mlib.h"
static bool_t bVal;
void main(void)
{
bVal = FALSE;
}
/* bVal = FALSE */
A.19 TRUE
The TRUE macro serves to write a correct value standing for the logical TRUE value of
the bool_t type. Its definition is as follows:
#define TRUE
((bool_t)1)
#include "mlib.h"
static bool_t bVal;
AMCLIB User's Guide, Rev. 2, 10/2015
58
Freescale Semiconductor, Inc.
Appendix A Library types
void main(void)
{
bVal = TRUE;
}
/* bVal = TRUE */
A.20 FRAC8
The FRAC8 macro serves to convert a real number to the frac8_t type. Its definition is as
follows:
#define FRAC8(x) ((frac8_t)((x) < 0.9921875 ? ((x) >= -1 ? (x)*0x80 : 0x80) : 0x7F))
The input is multiplied by 128 (=27). The output is limited to the range <0x80 ; 0x7F>,
which corresponds to <-1.0 ; 1.0-2-7>.
#include "mlib.h"
static frac8_t f8Val;
void main(void)
{
f8Val = FRAC8(0.187);
}
/* f8Val = 0.187 */
A.21 FRAC16
The FRAC16 macro serves to convert a real number to the frac16_t type. Its definition is
as follows:
#define FRAC16(x) ((frac16_t)((x) < 0.999969482421875 ? ((x) >= -1 ? (x)*0x8000 : 0x8000) :
0x7FFF))
The input is multiplied by 32768 (=215). The output is limited to the range <0x8000 ;
0x7FFF>, which corresponds to <-1.0 ; 1.0-2-15>.
#include "mlib.h"
static frac16_t f16Val;
void main(void)
{
f16Val = FRAC16(0.736);
}
/* f16Val = 0.736 */
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
59
FRAC32
A.22 FRAC32
The FRAC32 macro serves to convert a real number to the frac32_t type. Its definition is
as follows:
#define FRAC32(x) ((frac32_t)((x) < 1 ? ((x) >= -1 ? (x)*0x80000000 : 0x80000000) :
0x7FFFFFFF))
The input is multiplied by 2147483648 (=231). The output is limited to the range
<0x80000000 ; 0x7FFFFFFF>, which corresponds to <-1.0 ; 1.0-2-31>.
#include "mlib.h"
static frac32_t f32Val;
void main(void)
{
f32Val = FRAC32(-0.1735667);
}
/* f32Val = -0.1735667 */
A.23 ACC16
The ACC16 macro serves to convert a real number to the acc16_t type. Its definition is as
follows:
#define ACC16(x) ((acc16_t)((x) < 255.9921875 ? ((x) >= -256 ? (x)*0x80 : 0x8000) : 0x7FFF))
The input is multiplied by 128 (=27). The output is limited to the range <0x8000 ;
0x7FFF> that corresponds to <-256.0 ; 255.9921875>.
#include "mlib.h"
static acc16_t a16Val;
void main(void)
{
a16Val = ACC16(19.45627);
}
/* a16Val = 19.45627 */
A.24 ACC32
The ACC32 macro serves to convert a real number to the acc32_t type. Its definition is as
follows:
AMCLIB User's Guide, Rev. 2, 10/2015
60
Freescale Semiconductor, Inc.
#define ACC32(x) ((acc32_t)((x) < 65535.999969482421875 ? ((x) >= -65536 ? (x)*0x8000 :
0x80000000) : 0x7FFFFFFF))
The input is multiplied by 32768 (=215). The output is limited to the range
<0x80000000 ; 0x7FFFFFFF>, which corresponds to <-65536.0 ; 65536.0-2-15>.
#include "mlib.h"
static acc32_t a32Val;
void main(void)
{
a32Val = ACC32(-13.654437);
}
/* a32Val = -13.654437 */
AMCLIB User's Guide, Rev. 2, 10/2015
Freescale Semiconductor, Inc.
61
AMCLIB User's Guide, Rev. 2, 10/2015
62
Freescale Semiconductor, Inc.
How to Reach Us:
Home Page:
freescale.com
Web Support:
freescale.com/support
Information in this document is provided solely to enable system and
software implementers to use Freescale products. There are no express
or implied copyright licenses granted hereunder to design or fabricate
any integrated circuits based on the information in this document.
Freescale reserves the right to make changes without further notice to
any products herein.
Freescale makes no warranty, representation, or guarantee regarding
the suitability of its products for any particular purpose, nor does
Freescale assume any liability arising out of the application or use of
any product or circuit, and specifically disclaims any and all liability,
including without limitation consequential or incidental damages.
“Typical” parameters that may be provided in Freescale data sheets
and/or specifications can and do vary in different applications, and
actual performance may vary over time. All operating parameters,
including “typicals,” must be validated for each customer application by
customer's technical experts. Freescale does not convey any license
under its patent rights nor the rights of others. Freescale sells products
pursuant to standard terms and conditions of sale, which can be found
at the following address: www.freescale.com/salestermsandconditions.
Freescale and the Freescale logo are trademarks of Freescale
Semiconductor, Inc. ARM and Cortex are the registered trademarks of
ARM Limited, in EU and/or elsewhere. ARM logo is the trademark of
ARM Limited. All rights reserved. All other product or service names are
the property of their respective owners.
© 2015 Freescale Semiconductor, Inc.
Document Number CM4AMCLIBUG
Revision 2, 10/2015