6.6.5. Creating a custom board configuration

Copy the starter board definition into a text editor, save it to your local disk with a filename of your choice and then follow the procedure in Figure 6.10.

../../_images/custom-board-creation.svg

Figure 6.10 Procedure for creating a custom board cofiguration.

  1. Change existing values. Detailed guidance is provided below in Modifying the starter board definition.

  2. Add new sections to completely define the custom board. Detailed guidance is provided below in Adding new features to the board definition.

  3. Import custom board file in motorBench® Development Suite.

  4. Review board properties in Configure → Board.

Alternatively — export one of the Microchip development boards and edit this board definition file as necessary to match the custom board design.

6.6.5.1. Starter board file

The starter board file provides the bare minimum content required by motorBench. Visit the motorBench release repository to obtain a copy of the starter board file.

6.6.5.2. Modifying the starter board definition

Change the device

Update characteristics.device to the specific digital signal controller device on your board.

Note

Make sure that the device selected in your MPLAB® X project matches this device.

Change default PWM frequency

Update characteristics.pwm.frequency.default to the desired PWM frequency in Hz.

Used for the initial value of the PWM frequency system parameter after this board is selected.

Note

Within characteristics.pwm.frequency, default must be between minimum and maximum:
minimum \(\le\) default \(\le\) maximum.

Change default DC link voltage

Update characteristics.voltage.dcLink.default to the desired DC link voltage.

Used for the initial value of the nominal DC link voltage system parameter after this board is selected.

Note

Within characteristics.voltage.dcLink, default must be between minimum and maximum:
minimum \(\le\) default \(\le\) maximum.

Change full-scale measurement range

Update the following items to the full scale measurement capabilities of your board:

  • characteristics.current.dcLink.fullscale

  • characteristics.current.phase.fullscale

  • characteristics.voltage.dcLink.fullscale

  • characteristics.voltage.phase.fullscale

Change PWM fault configuration

The PWM fault signal, if asserted, automatically shuts down PWM channels in the event of an externally-detected fault such as an overcurrent or overvoltage. To configure MCAF for a PWM fault signal, update the source and polarity properties of peripherals.pwm.fault.

Note

See PWM fault section of custom board schema for more information.

Specification for the polarity property is required only if source is not none.

Change PWM channel to motor phase mapping

Update peripherals.pwm.generators to change the mapping between motor phases A, B, and C, and the appropriate PWM generators. For example: if phase A is generated by PWM3, phase B by PWM4, phase C by PWM1, then the board definition should contain:

peripherals:
  pwm:
    generators:
      a: 3
      b: 4
      c: 1
Change current sense channel support

Update peripherals.adc.current to add or remove channels, as appropriate. This defines the ADC inputs that can potentially be used for current sensing.

For example, the LVMC 33CK board contains all four channels:

peripherals:
  adc:
    current:
      a:
        channel: AN0
        inverted: true
        signed: true
      b:
        channel: AN1
        inverted: true
        signed: true
      c:
        channel: AN10
        inverted: true
        signed: true
      dcLink:
        channel: AN4
        inverted: false
        signed: true

Note

motorBench/MCAF support several configurations for current measurement:

  • Triple-channel current sense (A, B, C)

  • Dual-channel current sense (A, B only)

  • Single-channel current sense (DC link)

See Current polarity conventions to determine whether inverted should be true or false for the channels on your board.

Change oscillator configuration

Update peripherals.oscillator.clockSource to one of the valid clock source options listed in the custom board schema.

6.6.5.3. Adding new features to the board definition

Add UART pin mapping

Add a new section uart.pins under peripherals and specify the pin mapping for RX and TX signals in the following format:

peripherals:
  uart:
    pins:
      RX: "R<port><number>"
      TX: "R<port><number>"

Note

Only one instance of UART is supported and this UART will be used by MCAF specifically for real time diagnostics.

Add new custom ADC channels

Add a new section custom under peripherals.adc and insert custom analog channels as a map object in a specification format as shown:

custom:
  <channelName>:
    channel: ANx
    signed: <true/false>

Example custom analog channel specification for two analog channels:

peripherals:
  adc:
    current:
        ...
    voltage:
        ...
    custom:
      sineInput:
        channel: AN2
        signed: true
      cosineInput:
        channel: AN3
        signed: true

Note

Custom name <channelName> should be a valid C identifier (no spaces or special characters except underscore).

Add new custom GPIOs

Add a new peripheral section gpio under peripherals and insert custom GPIO channels as shown below:

<customGpioName>:
  pin: <port name>
  direction: <input/output>
  polarity: <active-high/active-low>

Pin, direction, and polarity are the minimum set of properties required to specify a GPIO channel.

If needed, the following additional GPIO properties may be included in the GPIO channel specification:

<customGpioName>:
  pin: <port name>
  direction: <input/output>
  polarity: <active-high/active-low>
  openDrain: <true/false>
  weakPullUp: <true/false>
  weakPullDown: <true/false>
  startHigh: <true/false>

The configuration below is an example specification of a custom GPIO on pin RA1, configured as output, active-high, with a weak pullup resistor.

peripherals:
  gpio:
    customgpio1:
      pin: RA1
      direction: output
      polarity: active-high
      weakPullUp: true

Note

Custom name <customGpioName> must be a valid C identifier (no spaces or special characters except underscore).

Add internal comparator configuration

Add a new peripheral section comparator under peripherals and insert the following configuration:

source: CMP<instance><muxinput>
inverted: <true/false>
threshold: <fraction>

Source, inverted and threshold are mandatory fields required to specify the comparator completely.

The configuration below is an example specification of CMP1 configured to compare the analog signal at its mux input “C” with the internal DAC reference of (0.95*Add) and output a non-inverted logic signal:

peripherals:
  comparator:
    source: CMP1C
    inverted: false
    threshold: 0.95

Note

Currently, motorBench allows the specification for only one internal comparator.

Add internal op amp configuration

Add a new peripheral section opamp under peripherals with the following configuration:

enabled:
  - <numbertoenable>
  - <numbertoenable>
  - <numbertoenable>

Example specification that enables internal op amps 1 and 3:

peripherals:
  opamp:
    enabled:
      - 1
      - 3
Add QEI configuration

Add a new peripheral section qei under peripherals with the following configuration:

pins:
  A: <port for phase-A>
  B: <port for phase-B>
  Z: <port for index pulse>

If QEI configuration is specified, then phase-A and phase-B are mandatory while index (Z) is optional.

Following is an example specification that enables QEI on port pins RC12, RC13 and RC14 for phase-A, phase-B and Index inputs, respectively.

peripherals:
  qei:
    pins:
      A: RC12
      B: RC13
      Z: RC14

Note

Currently, motorBench allows the specification for only one instance of the QEI peripheral.

Add inverter bridge temperature sensor configuration

Add a new section other under peripherals.adc with the following configuration:

bridgeTemperature:
  channel: ANx
  signed: <true/false>
  offset: <voltage>
  gain: <fraction>

For example, the dsPIC33CK LVMC board includes an MCP9700 temperature sensor, and the corresponding board definition includes:

peripherals:
  adc:
    other:
      bridgeTemperature:
        channel: AN12
        signed: false
        offset: 0.5
        gain: 0.50354

Note

MCAF temperature sensor support is limited to linear temperature sensors at this time. These sensors are commonly specified at 10 mV/°C with a given voltage offset at 0 °C; for example the MCP9700 is specified as 10 mV/°C with 500mV offset at 0 °C.

bridgeTemperature.offset is represented in terms of voltage [V] at 0 °C.

bridgeTemperature.gain is the ADC gain needed to scale temperature to 0.01 °C/count, after the full ADC range is mapped to the range 0 – 65535 counts. For AVdd = 3.3V, an increase in 1 °C → 10 mV → 0.01 V / 3.3 V × 65536 = 198.594 counts. To scale this to 100 counts per °C, we need to multiply by 100 / 198.594 = 0.50354. In general, the formula for bridgeTemperature.gain \(G_T\) is

(6.2)\[G_T = \frac{100 AV_{dd}}{2^{16} K_V}\]

where \(K_V\) is the voltage gain of the temperature sensor per °C. As another example, the MCP9701 is specified as 19.5 mV/°C, with a 400 mV offset, so a board definition with the MCP9701 and analog supply voltage AVdd = 3.3V should contain \(G_T = \frac{100 \cdot 3.3}{65536 \cdot 0.0195}\) = 0.25823:

peripherals:
  adc:
    other:
      bridgeTemperature:
        offset: 0.4
        gain: 0.25823
Add configuration for a SiP device

Add a new section under characteristics with the following configuration:

device: dsPIC33CDV[C/L][64/256]M[P/C]XXX
  gateDriver:
    device: MCP8021
    configuration:
      sleepMode: <standby/sleep>
      shortCircuitDetect: <true/false>
      underVoltageLockout: <true/false>
    pins:
      RX: R<port><number>
      TX: R<port><number>
      fault: R<port><number>
      outputEnable: R<port><number>

For example, a board with a dsPIC33CDVC256MP506 device is configured:

characteristics:
  device: dsPIC33CDVC256MP506
  gateDriver:
    device: MCP8021
    configuration:
      sleepMode: standby
      shortCircuitDetect: false
      underVoltageLockout: false
    pins:
      RX: RC12
      TX: RC12
      fault: RB12
      outputEnable: RB13

Note

The following additional parameters of MCP8021 are pre-configured by motorBench/ MCAF and cannot be modified directly. See section on configuration for more infomration.

driverDeadTime: 250
driverBlankingTime: 4000
overcurrentLimit: 1.0

Note: All SiP devices come with a single gate driver option, the MCP8021, and the pin connections between the microcontroller and the gate driver device are hard-wired.

Add gate driver configuration for MCP8021

Add a new section under characteristics with the following configuration:

gateDriver:
  device: MCP8021
  configuration:
    sleepMode: <standby/sleep>
    shortCircuitDetect: <true/false>
    underVoltageLockout: <true/false>
  pins:
    RX: R<port><number>
    TX: R<port><number>
    fault: R<port><number>
    outputEnable: R<port><number>

For example, a board with dsPIC33CK256MP508 and MCP8021 gate driver has the following configuration:

characteristics:
  device: dsPIC33CK256MP508
  gateDriver:
    device: MCP8021
    configuration:
      sleepMode: standby
      shortCircuitDetect: false
      underVoltageLockout: false
    pins:
      RX: RB8
      TX: RB9
      fault: RB4
      outputEnable: RA2

Note

The following additional parameters of MCP8021 are pre-configured by motorBench/ MCAF and cannot be modified directly. See section on configuration for more infomration.

driverDeadTime: 250
driverBlankingTime: 4000
overcurrentLimit: 1.0
Add gate driver configuration for MCP8022

Add a new section under characteristics with the following configuration:

gateDriver:
  device: MCP8022
  configuration:
    sleepMode: <standby/sleep>
    shortCircuitDetect: <true/false>
    underVoltageLockout: <true/false>
    opampEnabledDuringDeviceStandby: <true/false>
  pins:
    RX: R<port><number>
    TX: R<port><number>
    fault: R<port><number>
    outputEnable: R<port><number>

For example, a board with dsPIC33CK256MP508 and MCP8022 gate driver has the following configuration:

characteristics:
  device: dsPIC33CK256MP508
  gateDriver:
    device: MCP8022
    configuration:
      sleepMode: standby
      shortCircuitDetect: false
      underVoltageLockout: false
      opampEnabledDuringDeviceStandby: true
    pins:
      RX: RB8
      TX: RB9
      fault: RB4
      outputEnable: RA2

Note

The following additional parameters of MCP8022 are pre-configured by motorBench/ MCAF and cannot be modified directly. See section on configuration for more infomration.

driverDeadTime: 250
driverBlankingTime: 4000
overcurrentLimit: 1.0
Add gate driver configuration for MCP8027

Add a new section under characteristics with the following configuration:

gateDriver:
  device: MCP8027
  configuration:
    sleepMode: <standby/sleep>
    shortCircuitDetect: <true/false>
    underVoltageLockout: <true/false>
    linPullUpsEnabled: <true/false>
    dacReference: <voltage>
  pins:
    RX: R<port><number>
    TX: R<port><number>
    fault: R<port><number>
    outputEnable: R<port><number>

For example, a board with dsPIC33CK256MP508 and MCP8027 gate driver has the following configuration:

characteristics:
  device: dsPIC33CK256MP508
  gateDriver:
    device: MCP8027
    configuration:
      sleepMode: standby
      shortCircuitDetect: false
      underVoltageLockout: false
      linPullUpsEnabled: false
      dacReference: 1.872
    pins:
      RX: RB8
      TX: RB9
      fault: RB4
      outputEnable: RA2

Note

The following additional parameters of MCP8027 are pre-configured by motorBench/ MCAF and cannot be modified directly. See section on configuration for more infomration.

driverDeadTime: 250
driverBlankingTime: 4000
overcurrentLimit: 1.0
Add PWM swap configuration for boards where PWMxH and PWMxL are swapped

Add a new section peripherals.pwm.outputSwap with following configuration:

peripherals:
  pwm:
    outputSwap:
      a: <true/false>
      b: <true/false>
      c: <true/false>

For example, the following configuration will swap PWMxH and PWMxL outputs for PWM generators assigned to phase A and phase B.

peripherals:
  pwm:
    outputSwap:
      a: true
      b: true
      c: false

6.6.5.4. Custom boards without pushbuttons or potentiometer

Real-time diagnostics software such as X2Cscope allows boards without pushbuttons or a potentiometer to control a motor while using the sample application.

  1. Connect to the board with real-time diagnostics.

  2. Set app.hardwareUiEnabled to 0. This will disable user interface functionality in the MCAF sample application.

  3. Update motor.apiData.velocityReference to set the velocity of the motor. This Q15 integer value is scaled by the full-scale velocity \(ω_{u}\) of the motor, set in the Customize page. The reference velocity will saturate between the minimum and maximum velocity values (\(ω_{min}\) and \(ω_{max}\)) set in the Customize page.

  4. Set motor.apiData.runMotorRequest to 1 to start the motor. MCAF will attempt to start the motor, and motor.apiData.runMotorRequest will be reset to 0.

  5. Set motor.apiData.stopMotorRequest to 1 to stop the motor. MCAF will stop the motor, and motor.apiData.stopMotorRequest will be reset to 0.

6.6.6. Board definition file validation

When importing a custom board, motorBench validates the board definition to ensure it conforms to the custom board schema. If this validation fails, motorBench will display an error message detailing the error(s) reported.

6.6.7. Support for SiP devices with MCP8021 gate driver, and MCP802X gate drivers

MCAF supports smart gate drivers like the MCP802X series, through a Gate Driver firmware module, which manages tasks such as configuration, diagnostics, and fault handling. The gate driver can be used in MCAF by specifying the use of an MCP802X gate driver in the board definition file.

6.6.7.1. Overview

The Gate Driver Interface performs the following core functions:

  • Initialization: Applies the board configuration to the gate driver to prepare it for use.

  • Enable/Disable Control: Safely enable or disable the gate driver circuitry.

  • Periodic Servicing: Maintains communication with the gate driver during operation.

  • Fault Monitoring: Captures and stores fault conditions for diagnostics or shutdown protocols.

The hardware abstraction layer (HAL) provides these functions to high-level components of MCAF such as the system board service and state machine.

6.6.7.2. Integration with MCAF

MCAF includes the Gate Driver module when the board definition specifies a gate driver device.

  • During board initialization, the gate driver is configured.

  • During runtime servicing, MCAF performs periodic updates to the gate driver’s internal state and fault monitoring.

  • In the bootstrap sequence, the system waits until the gate driver communicates its readiness state before initiating bootstrap capacitor charging.

This ensures that the gate driver is ready for normal operation.

6.6.7.3. Configuration

motorBench® Development Suite automatically configures the MCP802X device with preset settings from the microcontroller.

Parameter

Summary

driverDeadTime

Sets the dead time between switching high-side and low-side MOSFETs to prevent shoot-through.

driverBlankingTime

Sets the interval during which the current sense comparator is disabled. This prevents false overcurrent or short-circuit detection due to switching noise.

shortCircuitDetection

Enables and configures short-circuit fault detection by monitoring the current sense inputs for rapid overcurrent conditions.

underVoltageLockOut

If the supply voltage drops below this defined threshold, the gate drive outputs are disabled to prevent improper operation.

overcurrentLimit

Configures the maximum allowable current level. If exceeded, the driver will shut down or limit current.

sleepMode

Internal circuits are powered down to reduce quiescent current. LIN wake-up and other wake conditions may be used to restore full operation.

opampEnabledDuringDeviceStandby

Allows the internal op-amps to remain active during standby mode, enabling external signal conditioning circuits to continue functioning when the main driver is inactive.

linPullUpsEnabled

Enables internal pull-up resistors on the LIN (Local Interconnect Network) bus pins.

dacReference

Configures the reference voltage for the internal DAC, which is used to set overcurrent threshold.

Note

The availability and behavior of the listed configuration parameters may vary between MCP8021, MCP8022, and MCP8027 devices. Refer to the specific device’s datasheet or board definition schema for detailed implementation and valid settings.

MCAF preconfigures the following parameters to ensure consistent behavior:

  • driverDeadTime: MCP802X does not insert symmetrical dead time. To avoid interference with microcontroller-generated dead time, MCAF configures the MCP802X to the minimum value (250 ns).

  • driverBlankingTime: Set to maximum (4000 ns) to ignore switching-induced current spikes.

  • overcurrentLimit: Set to 1.0 V, the highest allowed, leaving the effective overcurrent threshold to MCAF.

To override these defaults, use the MCP802X EasyView configuration within the MCC Melody application builder. The MCC Melody MCP802X interface supports custom configurations for the gate driver that can be selected as the default for motorBench.

6.6.7.4. System-level behavior

6.6.7.4.1. Initialization

The gate driver initialization routine configures all relevant control pins, communication parameters, and internal registers of the gate driver, then enables operation.

6.6.7.4.2. Bootstrap sequence

MCAF monitors the readiness state from gate driver before proceeding with bootstrap capacitor charging. This ensures proper high-side switching in designs that depend on charged bootstrap capacitors.

6.6.7.4.3. Runtime service

MCAF calls a gate driver service function periodically from the board service layer or main control loop. This maintains synchronization with the hardware, handles fault polling, and enables diagnostic features.

6.6.7.4.4. Fault handling

The gate driver module periodically reads and stores fault flags from the gate driver IC. This allows the system to detect and respond to undervoltage, overcurrent, or communication faults.