6.2. Code Generation¶
6.2.1. Relationship with motorBench® Development Suite and MCC¶
MPLAB® Code Configurator (MCC) can be used with motorBench® Development Suite as a plugin library for MCC. Each version of motorBench® Development Suite contains a firmware package which allows generation of a particular version of MCAF.
Since MCAF R4, all peripheral and system initialization code is produced by MCC not MCAF. The only exception to this is the QEI peripheral as this is not supported by MCC yet. This requires setting certain peripheral, oscillator, and configuration settings in MCC. See the motorBench® Development Suite help documentation and release notes for more information.
When MCC supports the QEI peripheral MCAF will no longer be responsible for the generation of any peripheral and/or system initialization code. This way MCAF can leverage MCC to broaden its support for devices and hardware.
6.2.2. Configurable parameters¶
Generated files in the parameters directory contain configurable parameters
that are computed from information entered or derived in motorBench® Development Suite and MPLAB® Code Configurator.
Microchip is investigating methods of making these parameter calculations more transparent and more easily manipulated if necessary.
A full table of configurable parameters is given in the file aux-files/parameters.html
which looks somewhat like the following excerpt:
| Key | Symbol | Intended Value | Units | Description |
|---|---|---|---|---|
| foc (10 items) | Field-oriented control (FOC) parameters | |||
foc.kii |
\(K_{ii}\) | 6.371e+02 | V/A/s | Current loop integral gain |
foc.kip |
\(K_{ip}\) | 0.4160799 | V/A | Current loop proportional gain |
foc.kwi |
\(K_{\omega i}\) | 0.5869318 | A/rad | Velocity loop integral gain |
foc.kwp |
\(K_{\omega p}\) | 0.0355454 | A/(rad/s) | Velocity loop proportional gain |
foc.mcafCurrentCtrlDOutLimit |
1.0000000 | line-to-line | Limit for output line-to-line voltage of d-axis current controller, expressed as a fraction of DC link voltage | |
This shows the real-world engineering values for each configuration parameter. The corresponding parameters file looks like this, containing fixed-point integer values along with a C comment detailing the conversion to fixed-point:
//************** PI Coefficients **************
//// Current loop
// phase margin = 80 deg
// PI phase at crossover = 45.000 deg
// crossover frequency = 1.531 k rad/s (243.680 Hz)
/* Current loop proportional gain */
#define KIP 2272 // Q15( 0.06934) = +416.01562 mV/A = +416.07990 mV/A - 0.0154%
#define KIP_Q 15
/* Current loop integral gain */
#define KII 174 // Q15( 0.00531) = +637.20703 V/A/s = +637.05425 V/A/s + 0.0240%
#define KII_Q 15
//// Velocity loop
// phase margin = 65 deg
// PI phase at crossover = 10.000 deg
// crossover frequency = 93.645 rad/s (14.904 Hz)
/* Velocity loop proportional gain */
#define KWP 12422 // Q13( 1.51636) = +35.54401 mA/(rad/s) = +35.54544 mA/(rad/s) - 0.0040%
#define KWP_Q 13
/* Velocity loop integral gain */
#define KWI 820 // Q15( 0.02502) = +586.58211 mA/rad = +586.93179 mA/rad - 0.0596%
#define KWI_Q 15
...
/* Limit for output line-to-line voltage of d-axis current controller, expressed as a fraction of DC link voltage */
#define MCAF_CURRENT_CTRL_D_OUT_LIMIT 18919 // Q15( 0.57736) = +1.00002 line-to-line = +1.00000 line-to-line + 0.0020%
Parameter names are given in “camelCase” except in the C header file where they are converted to
all-capitals with underscores separating words, for example foc.mcafCurrentCtrlDOutLimit
is converted to MCAF_CURRENT_CTRL_D_OUT_LIMIT in the foc_params.h file.
6.2.2.1. Out-of-range errors¶
In rare circumstances the configuration parameters may produce errors during code generation. This can result from motor parameters that may be extremely small or large values compared to typical motors. In this case, code generation will fail and an error message will be shown in MPLAB® Code Configurator. (Please read the release notes of motorBench® Development Suite for more information on how these messages are displayed.)
A typical out-of-range error message looks like this:
ValueError: Value 'kip' out of range: 345.055 Q8.8 = 4140.66 V/A
In this instance, the code generation engine attempted to convert a real-world value of 4140.66 V/A into a Q8 representation of 345.055, which is too large; Q8 supports only ± 128.
Microchip is investigating methods of providing guidelines for troubleshooting and correcting out-of-range errors;
in the interim, if you encounter an out-of-range error, please contact motorbench-support@microchip.com for assistance.
6.2.3. Source file organization¶
Each source file begins with a header that looks like this:
/**
* foc.c
*
* main field-oriented-control code
*
* Component: FOC
*/
/* *********************************************************************
*
* Motor Control Application Framework
* R3/RC14 (commit 90529, build on 2018 Oct 04)
*
* (c) 2018 Microchip Technology Inc. and its subsidiaries. You may use
* this software and any derivatives exclusively with Microchip products.
*
...
These are two comment blocks.
The first one is used for some computer-assisted documentation, and contains the filename, a brief description, and the component name.
The second comment block contains the MCAF version (for example, R3 = release 3, RC14 = release candidate 14), commit ID, and build date, along with the copyright notice.
In general, code for each module is divided
into two or three files, for example the foc module:
- compilation unit (
foc.c) — contains C-callable function definitions - header files:
- main header file (
foc.h) — contains function declarations and inline function implementations - types header file (
foc_types.h) — contains type definitions separate from function declarations
- main header file (
With the exception of the types header file, this is a typical organization in C code. Types header files were separated to help remove unnecessary dependencies between modules, so that state variables could be allocated without pulling in additional modules as dependencies.
6.2.4. Auxiliary reports¶
MCAF includes a few additional files generated in the aux-files directory:
parameters.html— a table of configurable parameters.report.html— a table of motor parameters and metrics. In the event you need assistance in troubleshooting behavior of a particular motor, please provide this file to Microchip staff so they can better understand the motor’s characteristics. Derived parameters or metrics like \(\tau_e = L_s/R_s\) and \(\tau_{m1} = JR_s/\frac{3}{2}{K_e}^2\) and \(\alpha_J = \tau_{m1}/\tau_e\) can help explain some observations or guide experienced motor control engineers to point out certain challenges of working with that particular motor. Time constants like the electrical time constant \(\tau_e\) and the mechanical time constant \(\tau_{m1}\) can help illustrate the time scale of electrical and mechanical dynamics. The normalized inertia \(\alpha_J\) is the ratio of these two time constants and can highlight whether a system has a small inertia (\(\alpha_J < 2\)) in which case electrical and mechanical dynamics are not well-separated and can lead to control stability challenges, or a large inertia (\(\alpha_J \gg 1\)) in which case slow velocity control loops are to be expected.report.json— machine-readable motor parameter values, in JSON format.report.xml.txt— machine-readable motor parameter values, in XML format.
These files are experimental. Any comments or suggestions on improving the content of these files are welcome; please send them to motorbench-support@microchip.com.