6.5. Integration with Custom Code

6.5.1. Overview

The Motor Control Application Framework and the accompanying Sample Application are designed so that the code generated from motorBench® Development Suite may be used with no changes as a demonstration project with the following development boards:

Use of MCAF in other projects usually requires a manual effort to replace the sample application with a custom application. While MCAPI will allow the custom application to control and obtain feedback from the motor without needing to know the different components and modules of MCAF, this effort still requires the application developer to be aware of the timing and resource requirements of MCAF. See Scheduling and Optimization and Resource Usage for more information.

../_images/mcapi-block-diagram.svg

Figure 6.6 Block diagram showing the User Application relative to MCAPI

Note

Except for existing interfaces in mcapi.h and mcapi_types.h, the functions, modules, and components in MCAF are still subject to change, and as of MCAF R7, none of the interfaces within MCAF have been frozen. As a result of this, it is not recommended for a custom application to access any of MCAF components directly without using the MCAPI.

Finally: if integration with custom code is important to you, we encourage your feedback to help guide future development in this area. Please contact Microchip with any comments or suggestions.

6.5.2. Modifying the Main Application

The main application includes a sample application in mcaf_sample_application.c that implements a simple user interface to control the motor using the Motion Control API (MCAPI). All interfaces of the sample application have names starting with the APP_ prefix. This sample application may be modified or replaced with custom code.

The requirements for MCAF to work properly with the modified main application are as follows:

  • MCAF_MainInit() should be called at system startup after SYSTEM_Initialize()

  • MCAF_MainLoop() should be called at each iteration of the main loop. This does not have to be executed periodically, but the minimum repetition rate should be approximately 100Hz to service the various features.

  • The board handler function, MCAF_BoardServiceTasks(), should be called periodically at a rate that is defined by the UI service period in the Customize page of motorBench® Development Suite. For instance, this function may be called from an application timer ISR or a scheduler.

The requirements for a custom application to interface with MCAF are as follows:

  • An application initialization function should be set up to initialize pointers to the MCAPI_MOTOR_DATA and MCAF_BOARD_DATA data in MCAF. See APP_ApplicationInitialize() in mcaf_sample_application.c for an example.

  • The application initialization function should be called from MCAF_MainInit() in mcaf_main.c to initialize the application-MCAF interface.

  • Application should use MCAPI to interact with MCAF at runtime.

6.5.3. Modifying the FOC module

Because of tight coupling that remains in MCAF between the state machine, FOC, and supervisory algorithms, modifications to the FOC module are not recommended. This includes changes to the sensorless estimators, the PI controllers or the flux control module.

6.5.4. Using Custom Boards

Use of custom boards is not recommended with MCAF R7. The mechanism for operating motorBench® Development Suite with custom boards has not yet been completed. Support for custom boards requires updates to the Hardware Abstraction Layer, and an adjustment of the scaling factors used in motorBench® Development Suite and MCAF.

Manual adjustment of any parameter that is automatically computed by motorBench® Development Suite is not recommended.

6.5.5. Modifying the State Machine

Because of tight coupling that remains in MCAF R7 between the state machine, FOC, and supervisory algorithms, modifications to the state machine are not recommended.

6.5.6. Modifying the Supervisory Algorithms

Supervisory algorithms, with the exception of watchdog management, are subject to change in the upcoming revisions after MCAF R7. Due to this reason, modifications to this module are not recommended.

Watchdog management involves several areas of MCAF; to change this behavior, see the section on watchdog management and/or search the code for watchdog; the relevant sections are in the traps, ui, isr, and main modules.