# 5.2.3.1. Implementation issues common to all methods

## 5.2.3.1.1. API of `qei_sync`

Each of the back-emf synchronization methods has been designed to meet the following API for all methods:

- The generated code is located in the `qei_sync` module

- Dependencies of the `qei_sync` module

  - It may depend on the `startup` and `qei` modules
  - There are no dependencies on the `system_state` or `commutation` modules
  - It does not access any HAL functions directly

- State data of the `qei_sync` module

  - is located in `motor.estimator.qei.sync`
  - has type `MCAF_QEI_SYNC_T`
  - `motor.estimator.qei.sync.complete` is a flag that denotes whether back-emf synchronization is complete. To re-run the synchronization, set this flag to `false` using the real-time diagnostic software.

- Methods

  - `MCAF_EstimatorQeiSyncInit()` — initialization function, runs once

  - `MCAF_EstimatorQeiSyncStep()` — update function, runs in control ISR, returns action flags to influence startup behavior in certain states. These action flags are only valid in startup states with a status code of `MSST_ALIGN` or `MSST_SPIN`. The return value can contain any of the following bit flags:

    > - `MESACT_DELAY` — startup state machine will be delayed, and remain in its current state
    > - `MESACT_SET_CURRENT `` --- ``MCAF_EstimatorQeiSyncOverrideCurrent()` will be called
    > - `MESACT_SET_ANGLE` — `MCAF_EstimatorQeiSyncOverrideAngle()` will be called
    > - `MESACT_SET_FREQUENCY – ``MCAF_EstimatorQeiSyncOverrideFrequency()` will be called

  - `MCAF_EstimatorQeiSyncIsComplete()` — returns whether synchronization is complete

  - `MCAF_EstimatorQeiSyncGetCommutationOffset()` — returns commutation offset computed by the `qei_sync` module. This result is only required to be valid if synchronization is complete (otherwise this function’s return value should be considered invalid)

- Override handlers

  The handler functions listed below are special methods that get called during appropriate stages of the startup sequence. A pointer to specific data is provided by the caller. This facilitates modularity by eliminating coupling between the `startup` and `qei_sync` modules; intercommunication is performed in the `commutation` module.

  Each handler has the option to change data or not, and is generally declared `inline static` so that an empty handler function would be optimized out.

  Method | Applicable state | Behavior
  `MCAF_EstimatorQeiSyncOverrideCurrent()` | `MSST_SPIN` | Can set current
  `MCAF_EstimatorQeiSyncOverrideAngle()` | `MSST_ALIGN` | Can set the applied electrical angle
  `MCAF_EstimatorQeiSyncOverrideFrequency()` | `MSST_ALIGN` | Can set the applied electrical frequency

## 5.2.3.1.2. Important data elements

The following data members are available, regardless of which `qei_sync` method is used:

- `motor.estimator.qei.position.commutationOffset` — controls commutation offset, which is the angle added to the raw electrical angle from the encoder before it is used for commutation. This can be modified using a real-time diagnostic tool to adjust the commutation offset while the motor is running. Any such changes should be slow: maximum recommended step size is 11 electrical degrees (2000 counts). Step changes larger than this may cause the control loops in FOC to lose synchronism.
- `motor.estimator.qei.position.commutationOffsetFromIndex` — this is a convenience calculation provided at the end of back-emf synchronization, and it measures the commutation offset relative to the index position within one electrical cycle. When using a motor with an encoder that has an index pulse, the values of `commutationOffsetFromIndex` will be fairly consistent, independent of the starting position of the motor when the QEI peripheral is enabled.