# 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

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

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 estimtaor (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)