# 3.1. Architectural Overview

The overall goals of the MCAF code are

- to spin a motor based on simple user inputs
- to detect and report fault conditions
- to be modular and maintainable
- to be a clear example to Microchip customers for a motor control Application using dsPIC® DSC devices
- to make efficient use of available CPU time in resource-limited devices

This section will describe an overview of how these goals are met.

## 3.1.1. How to Spin a Motor (In Brief)

The MCAF spins a motor using a velocity control loop, with an inner current loop using field-oriented control (FOC) to manage motor current and torque. Sensorless estimation techniques are used to estimate motor position for commutation and velocity control. User input is provided with a potentiometer and buttons to start and stop the motor, or to reverse direction. A state machine is used to control the transitions between these different modes of operation.

The motor startup process involves so-called “open-loop” operation. When the motor is at rest or moving very slowly, the sensorless estimator is not accurate enough; instead, a special set of states is provided to manage startup, in which commutation is forced at a desired acceleration rate, and the velocity control loop is disabled.

Monitoring algorithms run continuously, to detect a motor stall and other abnormal conditions such as overcurrent or overvoltage. These conditions disable the motor controller. The controller will automatically restart, if possible; otherwise, a fault code will be displayed.

More detailed descriptions are provided in appropriate sections.

## 3.1.2. Modules and Components

The MCAF is based on a modular design, and consists of a number of components that work together. We use the terms module and component in specific ways in the MCAF:

- module refers to a specific set of 1-3 source code files with a common base name, and a specific responsibility.
- component refers to some number of modules that comprise a high-level set of features.

For example, the field-oriented control (FOC) component, covering velocity and current control, contains these modules:

- `foc` — top-level FOC
    - `foc.c`
    - `foc.h`
    - `foc_types.h`
- `sat_PI` — PI loop saturation management
    - `sat_PI.c`
    - `sat_PI.h`
    - `sat_PI_types.h`
- `parameters/foc_params` — FOC tuning parameters
    - `parameters/foc_params.h`
- `parameters/sat_PI_params` — saturation parameters
    - `parameters/sat_PI_params.h`

Figure 3.1 shows the MCAF components, with arrows designating component dependencies:

Figure 3.1 Components of Motor Control Application Framework

### 3.1.2.1. High-level component descriptions

At a high level, a short description of these components is given below; more details are provided in appropriate subsections. Note: because this is a general motor control framework, most components have more than one implementation option, including some that are intended for the future but which have not yet been implemented.

Modules within these components can be found in a description of the components that contain them, and can also be located by name in the index under “modules”.

- Main Application: The main application depends on a number of components to do its job. It is the one in charge: with limited exceptions, it handles all scheduling and interactions with the hardware, and takes output from one component for use in another, so that the individual components do not need to have inter-component dependencies.
- ADC Calibration and Compensation: Handles offset and gain compensation for ADC readings. May also include computation of offset and gain coefficients during calibration times.
- State Machine: Controls state-dependent behavior of the application that changes over time because of different conditions. In a motor control application, this usually covers the actions that occur when the motor is disabled, starting up, running, and shutting down.
- Field-Oriented Control (FOC):
  - Velocity Control: Most motor control applications involve a velocity control loop that attempts to control the motor to achieve a given desired speed. (Some use a position control loop, typically as an outer loop around a velocity controller; this is a feature that may be added in the future.)
  - Current Control: Most motor control algorithms require a current control loop to manage motor torque and/or current. (Some do not; instead the main velocity controller outputs duty cycle directly. Support for these systems may be added in the future.) The application framework will initially support FOC of a permanent-magnet synchronous motor, but may also support FOC of induction motors, six-step control, direct torque control, etc. as needed.
- Commutation and Estimation: All permanent-magnet synchronous motors (PMSM), switched-reluctance motors (SR), AC induction motors (ACIM), and stepper motors require AC waveforms and control of which motor terminals receive current at any given time; the only exception are DC motors with a built-in commutator. The functions of commutation and estimation are to examine the available inputs and come up with estimates of motor position, velocity, and/or commutation angle. The commutation angle determines which phases should receive current. This component may consist of several alternative implementations:
  - Sensorless estimators (PLL, SMO, etc.)
  - Hall sensor commutation and estimation
  - Quadrature encoder commutation and estimation
  - Resolver commutation and estimation
  - Forced commutation: this is typically used in startup for a system with a sensorless estimator, and includes the management of transition between forced commutation and closed-loop commutation.
- Test Harness: this provides the ability to modify the normal modes of operation of the commutation and current controllers, and apply test disturbance signals.
- Supervisory Algorithms: There are a number of additional algorithms that can be used to enhance reliability or performance, including
  - Overvoltage/undervoltage detection
  - Overcurrent detection
  - Thermal management
  - Stall detection and recovery
  - Saturation and antiwindup management (if not already present in the velocity and current controllers)
  - Adaptive estimators (e.g. online resistance estimation)
  - Field weakening
  - Maximum torque per ampere controllers
- External Interface: Manages the interface with the outside world. This includes either a user interface (pushbuttons/knobs) or programmatic control through a communications interface.
- Diagnostic Kernel: Allows real-time diagnostics and testing through interaction with an external host PC. The Motor Control Applications team at Microchip uses this to debug and test motor control algorithms.
- Hardware Abstraction Layer: Handles all hardware-specific functions through a well-defined interface common across multiple processors and platforms. The only components that interact with the HAL are the main (top-level) application and the state machine. Other components are given access to system state variables which are used as a way to exchange data with the HAL.

## 3.1.3. Software Design Principles for Modular and Maintainable Code

In addition to organizing the MCAF code into modules, there are a number of other design principles we followed, in order to increase modularity, maintainability, and readability, which may not be immediately apparent. These are outlined briefly below, and described in later sections. Overall we aimed to be consistent throughout the codebase, so that it is easier for engineers to become familiar with the way it works.

- Naming convention — MCAF follows a consistent naming convention to improve clarity and reduce the possibility of collision with customer code.
- State management — the way that state variables are structured, allocated, and accessed facilitates modularity.
- Configuration parameters — there are many different configuration parameters in the MCAF, and these are organized to make them accessible to, but separate from, the corresponding modules, so that they can be easily changed but their associated code remains constant
- Scheduling and Optimization — MCAF aims to make efficient use of embedded CPU time, but still maintain a modular architecture
- State machines — to implement complex behaviors, the MCAF uses intentionally-designed state machines and run-to-completion scheduling to avoid accidental side effects.