# 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

## 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

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)