7.5. Revision History¶

This section covers both the revision history for this documentation and for the MCAF itself.

7.5.1. MCAF Documentation Revision History¶

Revision	Date	Notes
0.1	2016 Sep 29	Preliminary draft
0.2	2016 Nov 8	Clarifications, glossary, and other minor edits
0.3	2016 Dec 15	Edits based on staff review
1.00	2017 Feb 7	Added subsection on thread safety Corrected `MCAF_` prefix in documentation
2.0.1	2017 Oct 9	Fixed test harness documentation issues Corrected block diagram (DC link compensation in wrong place) Added updates for MCAF R2
2.0.2	2018 Jul 2	Corrected scaling factor information
3.0.1	2018 Nov 6	Updated for MCAF R3
3.0.2	2018 Nov 7	Added code generation section Added pwm duty cycle section from existing internal documentation Minor edits based on staff review
4.0.1	2019 Jul 15	Updated for MCAF R4: Added Quadrature encoder support section Added Back-EMF synchronization sections Added Startup section Added Parameter customization section
5.0.1	2019 Feb 19	Updated for MCAF R5: Added Position and Velocity Estimation section Added Angle-tracking Phase-locked Loop (ATPLL) section Added AN1292 Phase-locked Loop (PLL) section Updated HAL section to cover ADC timing and dsPIC33CK support Added test harness section on Pause at end of open-loop startup Updated customizable parameters section Minor edits based on staff review
6.0.1	2020 Oct 5	Updated for MCAF R6: Added Sampling Rate and PWM Frequency Implications section Added Current loop tuning section Added Motion Control API (MCAPI) section Added Flux control section Added Dead-time Compensation section Added introductory section on FOC Rewrote section Integration with Custom Code to reflect MCAPI Updated HAL section to include the implication of differences in PWM deadtime behavior between dsPIC33E and dsPIC33C Updated Usage statistics for MCAF R6 section Updated customizable parameters section Minor edits based on staff review

7.5.2. MCAF Revision History¶

In brief:

Revision	Date	Notes
R1 RC12	2017 Feb 28	Initial release as part of motorBench^® Development Suite 1.15
R2 RC9	2017 Sep 29	Internal release: Added support for overmodulation Added support for DC link compensation Added support for wider range of low-voltage motors Scaling factors updated All voltages now use scaling factor of maximum ADC input for the DC link; R1 used \(24V/\sqrt{3}\) for FOC voltages Mechanical velocity now uses 1.5 times maximum motor velocity; R1 used 30000 electrical RPM Updated HAL for future MCHV-2 support Updated Motor Control Library Numerous minor fixes
R3 RC14	2018 Oct 4	Release intended as part of motorBench^® Development Suite 2.0 Supports use of MCC for system / oscillator module Completed support for MCHV-2 HAL Other minor fixes
R4 RC12	2019 Jun 21	Release intended as part of motorBench^® Development Suite 2.15 MCC peripheral support Parameter customization Quadrature encoder support Added new startup method (Weathervane startup) Other minor fixes
R5 RC11	2020 Feb 7	Release intended as part of motorBench^® Development Suite 2.25 dsPIC33CK support Customize page improvements Angle-tracking Phase-locked Loop (ATPLL) Other minor fixes and improvements
R6 RC8	2020 Aug 25	Release intended as part of motorBench^® Development Suite 2.35 Added device support for new devices in dsPIC33CK series (dsPIC33CK64MC105, dsPIC33CK64MP105) Added `flux_control` module with support for flux weakening (FW) and maximum torque per ampere (MTPA) Added Motion Control API (MCAPI) Added dead-time compensation Redesigned board service module Other minor fixes and improvements

In detail:

7.5.2.1. MCAF R2 RC9¶

7.5.2.1.1. Modules added/removed¶

atan2cordic was removed (not required by any other modules)
board_service, filter, and units added

7.5.2.1.2. Core FOC¶

The inverse Clarke transform has been replaced by its conventional variant. (MCAF R1 had swapped \(\alpha\) and \(\beta\))
Space vector modulation with phase-shifted inputs has been replaced by an implementation of zero-sequence modulation that includes clipping in order to implement overmodulation.

7.5.2.1.3. Overmodulation¶

Overmodulation support has been added.

7.5.2.1.4. DC link compensation¶

DC link compensation support has been added.

7.5.2.1.5. Expanded range of supported motors¶

Parameter generation tested under a wide range of motor parameters to identify and correct range issues.
Several shift counts changed to be selected at code generation time (rather than a fixed Q15).
Several time delay values (mostly in startup and stall detection) changed to utilize 32-bit counts, so that longer time constants can be supported.
Some of the PLL calculations were rewritten to prevent overflow.

7.5.2.1.6. Scaling factors and operating range¶

The scaling factors for voltages have been unified to one value based on maximum DC link voltage.
The scaling factor for motor velocity has been changed to be 1.5 times the base speed of the motor; the capability has been added in MCAF to override this from motorBench^® Development Suite, although as of motorBench^® Development Suite revision 1.35 this is not yet possible.
Minimum operating speed is now set based on the minimum electrical frequency selected in motorBench^® Development Suite.

7.5.2.1.7. Fault detection¶

The torque angle method of stall detection was rewritten to improve accuracy over a wider range of motors.
The Ed method of stall detection was adjusted to remove low-pass filtering that was hindering stall detection with some motors.
The monitor module was rewritten as a simple state machine to avoid unintentional behavior.

7.5.2.1.8. Test Harness¶

Added ability to force state change (e.g. STOPPING → STOPPED )

7.5.2.1.9. HAL¶

Added new interfaces for TMR1 (hardware timer 1)
Added additional functions for UART1
Refactored some of the Application Interfaces in BSP, moved LED and test-point related interfaces to HAF
Added a new board service module

7.5.2.1.10. Motor Control Library¶

The version of the Motor Control Library included with MCAF R2 has added a number of new functions, including zero sequence modulation with clipping, and the conventional Inverse Clarke transform.

Please do not use this version of the Motor Control Library in other projects outside the MCAF.

7.5.2.1.11. Miscellaneous¶

MCAF version information (“R2/RC9” along with a commit id and build date) has been added to all C source files outside of the libraries.

7.5.2.2. MCAF R3 RC14¶

Note to the reader: starting with this release, you may see issue tracker keys listed in the revision history in parentheses, such as DB_MC-97. These are present to assist Microchip staff in referring to more detailed information as necessary.

7.5.2.2.1. Modules added/removed¶

The meas_curr module, written in assembly, has been combined with some functionality of the foc module to form a new adc_compensation module written in C. (DB_MC-97, DB_MC-675)

7.5.2.2.2. MCC compatibility¶

MCAF is now compatible with the MCC system module including oscillator setup. (DB_MC-1679, DB_MC-1688, DB_MC-1689, DB_MC-1690)

The former traps and main modules of MCAF have been renamed mcaf_traps and mcaf_main. (DB_MC-1685, DB_MC-1686)
There is now an mcaf_main.h as well to include function declarations. (DB_MC-1846)
MCAF is no longer responsible for producing main(); instead, the MCC main() function now calls into MCAF for initialization and the main loop.
MCAF has yielded responsibility to MCC for generating configuration bits
MCAF has yielded responsibility to MCC for oscillator configuration (DB_MC-1849)
Some functions in the HAL have been renamed with an MCAF_ prefix to avoid name conflicts with MCC-generated HAL functions.

MCAF is still not compatible with other modules from MCC, including the ADC, UART, and PWM. The HAL within MCAF takes responsibility for configuring and using these modules.

See the documentation for the HAL for more information.

7.5.2.2.3. MCHV-2 and MCHV-3 compatibility¶

The HAL generated by MCAF is now fully compatible with the MCHV-2 and MCHV-3 development boards. (MCAF R2 did contain the required HAL functions for MCHV-2/MCHV-3 but always generated code for MCLV-2.)

7.5.2.2.4. Scaling factors and operating range¶

The continuous rated inverter current as entered in motorBench^® Development Suite is now exactly equal to the maximum dq-frame commanded current amplitude. In MCAF R2, there was a 0.824 derating factor applied. (DB_MC-1307)

7.5.2.2.5. ADC compensation¶

The ADC current gain matrix is now generated dynamically. In MCAF R2 it was fixed to support unmodified MCLV-2 boards. It now can handle arbitrary gains setup in motorBench^® Development Suite. (DB_MC-1332)

7.5.2.2.6. Core FOC¶

PLL now uses motor.valphabetaOut rather than motor.valphabeta. (DB_MC-1164) The difference between these state variables is that motor.valphabeta represents the intended value of \(V_{\alpha\beta}\) prior to zero-sequence modulation, whereas motor.valphabetaOut represents the best estimate of the actual \(V_{\alpha\beta}\) based on calculating from PWM duty cycles. The two are identical except when the current controller enters into overmodulation. See also MCAF_ComputeVAlphaBetaAtOutput().

7.5.2.2.7. Fault detection¶

Torque angle stall detection has been disabled by default. (DB_MC-1732) See supervisory errata for more information.
MCAF_VarianceDetectx16Decimate() has been renamed MCAF_VarianceDetectx16PostDecimation() for clarity. (DB_MC-846)

7.5.2.2.8. Test Harness¶

Added ability to cause stack overflow. (DB_MC-1708)
Added delay loop for commutation overrides. (DB_MC-1280)
DC link compensation can be disabled by setting the corresponding override bit. (DB_MC-1168)

7.5.2.2.9. HAL¶

Added additional functions for the QEI and PWM modules
Removed configuration bits and oscillator initialization
Renamed functions in pin_manager, interrupt_manager, and mcc modules with MCAF_ prefix to avoid name conflicts with MCC-generated HAL functions.

7.5.2.2.10. Motor Control Library¶

A minor error in the inline assembly in MC_adjust_zero_sequence has been fixed. (DB_MC-1403) This manifested as a build failure (Error: Invalid operands specified ('add w0,[w15-10],w8').) when building with -O0; as a reminder, please note that MCAF requires optimization level -O1 or higher to meet timing constraints.

No other changes have been made.

Updated documentation for the MC Library is not yet available.

Please do not use this version of the Motor Control Library in other projects outside the MCAF.

7.5.2.2.11. Code generation¶

Improved code generation error messages when an out-of-range error is encountered. (DB_MC-1435)
Improved internal mechanisms for calculating parameters in code generation. (DB_MC-1706, DB_MC-1760)
Overvoltage and undervoltage margins are now set to 2V for MCLV-2 and 20V for MCHV-2. (DB_MC-1734) Future versions of motorBench^® Development Suite will allow these values to be edited.

7.5.2.2.12. Auxiliary reports¶

The list of derived parameters in aux-files/report.html has been expanded. (DB_MC-1178)
Reports in aux-files/ now include traceability to the corresponding MCAF version. (DB_MC-1364)
Updated KaTeX to a more recent version. (DB_MC-1517)
Fixed a bug in report.xml, specifically a missing close tag (DB_MC-1572)
The file report.xml has been renamed report.xml.txt to avoid triggering an error in MCC. (DB_MC-1868)

7.5.2.2.13. Miscellaneous¶

MCAF version information has been updated to “R3/RC14”.
MCAF copyright date updated to 2018. (DB_MC-1788)
Types header files have been pulled out of the ui and startup modules – there is now a ui_types.h and startup_types.h. (DB_MC-470)
Certain state variables have been updated from int16_t to an appropriate units typedef such as MCAF_U_VELOCITY, MCAF_U_VOLTAGE_ALPHABETA, MCAF_U_DIMENSIONLESS_SINCOS, etc. (DB_MC-1199, DB_MC-1281)
Removed unused FindLeadingOne() function from the util module. (DB_MC-1169)
Unused MINSPEEDINRPM removed. (DB_MC-808)

7.5.2.3. MCAF R4 RC12¶

7.5.2.3.1. Modules added/removed¶

The commutation/qei_sync module has been added for Back-EMF synchronization
The pll module has been moved to commutation/pll
The qei module has been moved to commutation/qei
The watchdog module has been temporarily renamed mcaf_watchdog until a conflict with MCC can be resolved. (DB_MC-2175)

7.5.2.3.2. MCC compatibility¶

MCAF peripheral and system initialization code generation is completely handled by MCC. The only exception to this is the QEI peripheral as this is not supported by MCC yet. (DB_MC-2146)

HAF functions have been added to use new MCC PWM APIs. (DB_MC-2089)
HAF function for retrieving interrupt vector number has been added.

See the documentation for the HAL for more information.

7.5.2.3.3. Quadrature encoder support¶

Support quadrature encoders as a primary position and velocity estimator (DB_MC-812)
Velocity estimated from the QEI, for use by the velocity control loop, has been corrected to use the filtered velocity \(\hat\omega_{LPF}\) rather than the unfiltered velocity \(\hat\omega\). (DB_MC-2254)
Added QEI index capture support (DB_MC-2078)

7.5.2.3.4. Parameter customization support¶

Added ability to adjust key MCAF parameters within the motorBench^® Development Suite user interface. (DB_MC-2156, DB_MC-2057)

7.5.2.3.5. Startup¶

Added “weathervane” startup method (DB_MC-1039)
Fixed bug where startup state machine was initialized to SSM_COMPLETE state at device reset (DB_MC-2094)

7.5.2.3.6. Core FOC¶

Refactored commutation module to support multiple estimators (DB_MC-2076)

7.5.2.3.7. Code generation¶

Fixed error in startup hold time calculation so that 32-bit values are now supported (DB_MC-2120)

7.5.2.3.8. Test Harness¶

Added ability to control slew rates with slow commutation steps (DB_MC-2113)
Corrected state initialization when entering a test mode (DB_MC-2107)
Fixed uninitialized overrideCommutationDelay (DB_MC-1918)

7.5.2.3.9. Style and readability¶

Startup currents in the startup_params module have been renamed for clarify (DB_MC-2227):
- INITIALTORQUE → MCAF_STARTUP_CURRENT_INITIAL
- FINALTORQUE → MCAF_STARTUP_CURRENT
Updated util.h to add assembly comments to inline assembly, for traceability (DB_MC-2011)
Consistency in MCAF identifier naming:
- Estimator types changed to MCAF_ESTIMATOR_XYZ_T from MCAF_XYZ_ESTIMATOR_T (DB_MC-2091)
- Estimator functions changed to MCAF_EstimatorXYZStep() from MCAF_XYZEstimatorStep() (DB_MC-2093)

7.5.2.4. MCAF R5 RC11¶

7.5.2.4.1. Modules added/removed¶

The commutation/atpll module has been added for Angle-tracking Phase-locked Loop (ATPLL)

7.5.2.4.2. MCC compatibility and dsPIC33CK support¶

MCAF R5 now supports dsPIC33CK devices. (DB_MC-2399) See the documentation for the HAL for more information.

7.5.2.4.3. HAL¶

Moved FCY definition out of ui.c and into HAL (DB_MC-436); utilized MCC-generated value to reflect actual choice of oscillator frequency (DB_MC-821)
Improved proper encapsulation of device-specific issues through Hardware Access Functions layer (DB_MC-2368)
Other miscellaneous improvements – see HAL for more information.

7.5.2.4.4. Diagnostics¶

Updated X2CScope library
- Added dsPIC33CK support. (DB_MC-2420)
- Now allows application to specify buffer (DB_MC-801)
- Recompiled with -O3 (DB_MC-804)

7.5.2.4.5. Quadrature encoder support¶

Improve parameter management of pullout synchronization method (DB_MC-2255)
Clarified and corrected angle units in QEI tracking loop (DB_MC-2521)

7.5.2.4.6. ATPLL support¶

Added angle-tracking PLL (ATPLL) sensorless estimator. (DB_MC-1547)

7.5.2.4.7. Miscellaneous sensorless estimator issues¶

Categorized ATPLL and PLL estimator state variables to help distinguish core algorithm state from auxiliary state used for logging (DB_MC-2579, DB_MC-2580)
Clarified ATPLL and PLL inductance identifiers and units (DB_MC-2601)
Fixed issue involving estimator initialization, and provided initialization hooks for all sensorless estimators (DB_MC-2576)

7.5.2.4.8. Startup¶

Improved naming of STARTUP_THETA_ERROR_STEP to STARTUP_THETA_ERROR_CONVERGE_RATE (DB_MC-2388)
Improve support for slower transitions to closed-loop in Classic startup (DB_MC-2513)
Fixed small residual thetaError values in Classic startup (DB_MC-2529)
Fixed proper assignment of thetaError in Weathervane startup (DB_MC-2628)
Fixed initialization of startup counter in Weathervane startup (DB_MC-2535)
Allow nonzero ALIGN time (DB_MC-2510)

7.5.2.4.9. Test Harness¶

Corrected units of overrideOmegaElectrical (DB_MC-2543)
Added feature to allow open-loop mode in test harness after normal startup (DB_MC-1527)

7.5.2.4.10. motorBench^® Development Suite Customize page support¶

MCAF firmware package can now specify transfer functions used for autotuning in motorBench^® Development Suite. (DB_MC-2424)
Added “Advice” pane for guidance based on motor and system parameters. (DB_MC-2507)
Added display of normalized values in engineering units. (DB_MC-2519)
Included additional customizable parameters. (DB_MC-2351)
Support migration of existing data from previous version of motorBench^® Development Suite. (DB_MC-2650)

7.5.2.4.11. Motor Control Library¶

Upgraded to Motor Control Library 0.20

Adds support for dsPIC33CK devices
Back-ported additional functions used in MCAF R4

7.5.2.4.12. Auxiliary reports¶

Added section “Normalization factors used in fixed-point representation” (DB_MC-2049)

7.5.2.5. MCAF R6 RC8¶

7.5.2.5.1. Modules added/removed¶

Added Motion Control API module (DB_MC-796)
Added Flux Control module (DB_MC-2853)
Added Dead-time compensation module (DB_MC-1969)

7.5.2.5.2. Adjustable PWM frequency¶

Added support for adjusting PWM frequency and control frequency as a submultiple of the PWM frequency. (DB_MC-2720, DB_MC-2950) Please refer to Sampling Rate and PWM Frequency Implications for more information.

7.5.2.5.3. Motion Control API¶

Added support for Motion Control API to provide a high-level abstracted interface for custom applications to control and obtain feedback from the motor. (DB_MC-796)
Added a sample application that demonstrates the use of Motion Control API to implement a simple user interface with pushbuttons and the potentiometer.

7.5.2.5.4. Flux Control¶

Added support for flux weakening to extend velocity range. (DB_MC-2723)
Added support for maximum torque per ampere to improve torque and efficiency for IPM motors. (DB_MC-2724)
Refactored FOC with structural changes to support flux weakening and MTPA. (DB_MC-2861, DB_MC-2863) For more information, see Velocity loop current limit and Saturation and anti-windup.

7.5.2.5.5. Dead-time compensation¶

Added support for dead-time compensation to mitigate some of the effects of deadtime distortion. (DB_MC-1969)

7.5.2.5.6. dsPIC33CK support¶

Added support for dsPIC33CK64MP105 and dsPIC33CK64MC105 (DB_MC-2694, DB_MC-2693)

7.5.2.5.7. Board service module¶

Restructured to improve timing robustness and to interface with the Motion Control API. (DB_MC-2726, DB_MC-2728, DB_MC-2732) See board service module changes for more information.

7.5.2.5.8. Test Harness¶

Added feature to override d-axis current computation, preventing flux control module from changing it, and allowing it to be changed via real-time diagnostic tools. (DB_MC-2855)

7.5.2.5.9. motorBench^® Development Suite Customize page support¶

Added read-only parameter calculations such as Saliency ratio (DB_MC-2903)
Included additional customizable parameters. (DB_MC-2689, DB_MC-2750, DB_MC-2838, DB_MC-2879, DB_MC-2882, DB_MC-2905)

7.5.2.5.10. Improvements in modularity¶

All calls to MCC HAL are now made through HAF (DB_MC-2671)
Removed directly modifying registers to clear status bits (DB_MC-2696)
Refactored data flow interface for estimators and flux control module to reduce tight coupling (DB_MC-2854)
Refactored back-emf calculation for use by estimators and flux control module (DB_MC-2106)

7.5.2.5.11. Naming improvements¶

Improved names for PWM generators (DB_MC-2807)
Replaced inconsistent PI parameters (DB_MC-2857)
Removed NORM_ prefix from ATPLL constants (DB_MC-2712)
Rename test harness functions to use verb “Trigger” for clarification (TriggerSeizure, TriggerStackOverflow) (DB_MC-1720)
Addressed potential naming collision between PLL and ATPLL (DB_MC-2602)

7.5.2.5.12. Miscellaneous firmware issues¶

Improve how velocities are represented in generated code in parameters/* files (DB_MC-2915)
Removed unnecessary and added missing #include statements in several locations (DB_MC-1719)
Tracking loop Kp value can now vary between a Q8 - Q15 value (DB_MC-2688)
Fixed half-PWM-cycle short circuit across motor during entry to STOPPING state (DB_MC-2931)