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 dsPICDEM® MCLV‑2 Development Board, dsPICDEM® MCHV‑2 Development Board, and dsPICDEM® MCHV‑3 Development Board.

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.5 Block diagram showing the User Application relative to MCAPI

Please note: Except for MCAPI, the functions, modules, and components in MCAF are still subject to change, and as of MCAF R6, 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 motorbench-support@microchip.com 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 Motion Control API (MCAPI). All interfaces of the sample application have names starting with the APP_ prefix. This sample application needs to be replaced by custom code.

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

  • Allocate MCAF_MOTOR_DATA for the motor state variables, and MCAF_SYSTEM_DATA for the overall system. Pointers to these need to be passed into the various MCAF_ functions, with the exception of the ADC ISR, which has no arguments but still needs to know where to access its data.
  • MCAF_MainInit() should be called at system startup
  • 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 customizable parameter Ui service period in Customize page of motorBench® Development Suite. For instance, this function may be called from the Application timer ISR.

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 R6. 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 R6 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 R6. 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.