Motor Control Boards Description

1. Introduction

This document specifies the formats used to describe the boards and the other hardware items that are involved in the configuration of a Motor Control application. These descriptions are used by ST Motor Control Workbench to let users configure their Motor Control application and to produce a software project that implement it in accordance with the hardware elements that make it.

From the Motor Control Workbench perspective, the hardware of a Motor Control application is built by combining the following elements:

• An STM32 MCU that executes the software of the Motor Control Application
• A Control Stage that hosts the STM32 device. The control stage embeds all the electronics needed to operate the MCU and may also optionally offer other features that cab be of interest in a Motor Control Application: buttons, potentiometers or even current sensing circuitry. .
• One of more Power stages that host all the power electronics needed to drive on or more motors: Mosfets, drivers, current sensing and B-EMF sensing circuitries...
• Motors and their optional speed and position sensors

It is the duty of ST Motor Control Workbench to properly connect these elements together and to configure the MCU according to their characteristics.

These elements are arranged into boards that users plug together to make a motor control application. Control Boards embed an MCU and a Control Stage. Power Boards embed a Power Stage. Control and Power boards provide connectors so that they can be connected to one another.

In ST board portfolio, several, incompatible connectors exist. To be able to connect Control and Power boards despite incompatible connectors, Bridge boards are provided.

Finally, Inverter Boards feature an MCU, a Control and one or more Power stages on a single board.

This document specifies the formats for describing Control Boards, Power Boards, Inverter Boards and Bridges. It may later be extended to cover Motors as well.

2. General concepts

A typical motor control application is built by plugging a motor into a power board which is in turn plugged into control board on which an STM32 MCU is soldered. Alternatively, a motor can be plugged into an inverter board on which an STM32 MCU is soldered. Sometimes, if the connectors available on the Control and the Power board differ and are not compatible, an adaptor board (a bridge) is used to connect them together. These three motor control application topologies are depicted in the figure below.

File:C:\Users\frq02147\OneDrive - STMicroelectronics\Documents\02 Projects\Motor Control\01 Specifications\MC Workbench\Boards Connection\mc hw configurations.png

2.1. Features

All these boards offer features that can be used by the STM32 MCU.

Some of these features are quite general and can be useful in many different applications, like potentiometers for instance. Others are very specific to a narrow set of applications like Hall sensors based current sensing circuitries that specifically target motor control.

Some are very simple and require very little MCU resources like push buttons for instance that can be handled by almost any single GPIO of an STM32 device. Others can be a lot more complex and require the use of more advanced MCU functions. A good example of this is the Motor Phases Voltage Generation feature that require an Advanced Timer, three of its channels and six MCU pins (to drive both the high and the low sides of the bridge).

But all these features have one key thing in common: they consist in a hardware implementation tied to pins of the MCU via one or more signals. To be properly used, these signals need to be connected to pins of the STM32 MCU that lead to peripherals that can handle them.

So, the main purpose of boards descriptions is to list the features provided by the boards, describe their characteristics (the signals they offer as interface and the parameters that define them) and how they can find their ways to MCU pins .

2.2. Hardware Variants

Each feature implemented on a board serves a purpose: a Button is meant for triggering events on the MCU, a Potentiometer allows for providing an input value to the MCU and the CurrentSensing feature aims at measuring the currents flowing through the phases of a motor, just to give a few examples.

In board descriptions, features are named and identified after that purpose. However, there are often several different ways of implementing a feature, each with its own parameters and its own set of signals.

A Hardware Variant is a specific hardware implementation of a feature implemented on a board. So describing a feature on a board actually means describing the hardware variant implemented on that board. For example, the CurrentSensing feature can be implemented by measuring the voltage across shunt resistors. The feature can be implemented with three shunt resistors, one per phase or with only a single shunt resistor. These two different hardware implementations are described by different hardware variants that define different signals.

A board can implement several different hardware variants for a given feature. For instance the X-NUCLEO-IHM16M1 power board implement both a single-shunt and a three-shunt current sensing hardware variant. This is reflected in board descriptions that list all the hardware variant available for the implemented features.

2.3. Signals

Signals are the physical interface that features provide, (usually) with the MCU. The signals defined by a feature (i.e by a hardware variant of a feature) on a board are meant to be handled by the MCU. They can be an input of the MCU as the voltage across a shunt that can be read by an ADC peripheral or they can be an output of the MCU like a GPIO used to switch a relay, for instance.

Signals have a nature and a name. This nature tells what the signal is used for and it determines how it should be handled. The name identifies a signal and so its exact role in the feature and its nature.

As an example, the figure below shows the DrivingHighAndLowSides hardware variant of the PhaseVoltageGeneration feature. This hardware variant defines six signals: PWM_CHU_H , PWM_CHU_L , PWM_CHV_H , PWM_CHV_L , PWM_CHW_H and PWM_CHW_L that the MCU drives to control the high and low sides switches of phase driving bridges.

File:C:\Users\frq02147\OneDrive - STMicroelectronics\Documents\02 Projects\Motor Control\01 Specifications\MC Workbench\Boards Connection\PWMGeneration.png

The six signals transport a low voltage, PWM signal that is produced by the PWM Output of a Timer peripheral embedded in the MCU. This is their nature (in this specific case, they all have the same one). The role of PWM_CHU_H is to drive the high side switch of phase U of a Motor. That of PWM_CHV_L is to drive the low side switch of phase V of the motor. The workbench knows the names of the signals defined by each hardware variant of each feature and uses this knowledge to configure the application properly according to the role and nature of each of them.

The implementation of this hardware variant also uses other physical signals like Bus and 0 Volt supplies (VBus and 0 V) or the U , V and W phase lines. However, none of them are plugged into the MCU, so they are not included in the descriptions.

The next figure shows the DrivingHighSidesAndThreeEnables hardware variant of the same feature. Although it defines the same number of signals, the variant differs from the previous one and some of the signals do not have the same nature. They need to be handled differently by the MCU which requires a different hardware variant. Here, the role of PWM_CHU is to drive phase U of the motor globally leaving the precise driving of the high and low side switches to the driver. And the role of PWM_CHV_EN is to enable or disable the driving of phase V.

File:C:\Users\frq02147\OneDrive - STMicroelectronics\Documents\02 Projects\Motor Control\01 Specifications\MC Workbench\Boards Connection\PWMGenerationEN.png

2.4. Terminals and Pins

Signals must to be routed to MCU pins in order to be used. An important aspect of the description of a signal is to specify how it can be connected to the MCU.

Control boards and inverters host an STM32 MCU. So, the descriptions of the signals of the features they implement specify the MCU pins to which they are connected. In this case, signals are directly linked to the MCU by the description.

On the other hand, Power boards do not host an STM32. The signals of features they implement lead to the terminals of the connector present on these boards. So the descriptions of signals on these board specify connector terminals instead of MCU pins.

These signals can then be linked to pins of the MCU thanks to the connector that is also present on Control Boards and the description of the routing between the terminals of this connector and the pins of the MCU.

2.5. Connectors and bridges

Control and Power boards need to be physically connected to build a Motor Control application. To that end they feature one or more connectors.

Connectors define terminals to which signals and MCU pins are linked. Connectors on control boards link their terminals to MCU pins. Connectors on power boards link to signals of the features implemented on these power boards. These links are specified in the descriptions of the boards. When a power board is plugged on a control board, the signals of the features it implements can be routed to pins of the MCU through the connector used for the plugging.

Different connector topologies identified by a connector type in the descriptions. For two boards to be plugged together, they must to be equipped with connectors of the same type. If that is not the case, bridges exist that may allow for the boards to be plugged anyway.

Bridges descriptions specify the mapping between the terminals of two connector topologies.

2.6. Connection

So, the hardware of a motor control application is built by combining an MCU, a control Stage, one or more power stages and as many motors. From the Workbench point of view, this amounts to connecting a selection of cards (and motors) which are described as per this specification.

This connection procedure is an important step in the generation of the firmware of a motor control subsystem. It consists in checking if each of the combined features provided by the hardware can be used by the firmware and how.

A feature can be used if at least one of its hardware variants is implemented in the hardware and can be used. And a hardware variant of a feature can be used if all the signals it defines can be properly connected to the MCU. Several conditions are required for a signal to be properly connected to the MCU:

• The signal must be physically connected to a pin of the MCU. This connection can be done directly or through the use of connectors and bridges. The descriptions of the boards provide all the information for assessing this physical connection.
• The pin of the MCU to which the signal is connected must be accessible to a peripheral that can process the signal. For instance, a signal transporting the measure of a current flowing through the phase of a motor needs to be processed by an ADC. The descriptions of the MCU (that are outside the scope of this document) provide the information needed for that.
• The firmware must be able to configure and use the peripheral connected to the signal. For instance the PWM signals of the phase voltage generation feature need to be plugged to specific channels of specific instances of MCU Timer peripherals for the firmware to be able to use them. And these requirements of the firmware on signals extend to hardware variants as a whole: to carry on with the phase voltage generation feature, all the PWM driving signals need to be routed to the same Timer. Signals are not independent... These requirements are known to the workbench and outside of the scope of the descriptions of the board.

The connection of the boards of a motor control application is complete if all the features needed for it can be connected. Which features need to be connected depend on the choices made for its design. For instance, an application using the FOC drive technique requires at least the the PhaseVoltageGeneration, the CurrentSensing and the SpeedAndPositionSensing features while a Six-Step only requires the PhaseVoltageGeneration and the SpeedAndPositionSensing features. In addition, the designers may choose to add other features to the application such as the VBusSensing or OverCurrentProtection or the Button features.

2.7. Syntax

The low level syntactic format used in the descriptions is JSON.

Each of the hardware elements specified here, control board, power board, inverter or bridge, is defined in a single JSON object. The nature of the element being described is stated in a type attribute of this object. The Motor Control Workbench expects that each hardware element be described in its own file.

2.8. Summary

TBCompleted

3. Formats Specification

3.1. Format version

This document specifies version 3 of the Motor Control Boards description format.

3.2. Common structure

Each hardware element (Power boards, Control Boards, Inverters and Bridges) is described in its own file by a single JSON object. A file describing a board contains exactly one JSON object and only this JSON object. Such a JSON object is named a description object.

Here is an example of the minimal structure of a description object:

{
    "type": "<board type>",
    "formatVersion": 3,
    "descVersion": <description version>,
    "name": "<board name>",
    
    "PN": "<Part Number>",
    "shortDescription": "...",
    "longDescription": "...",
    "link": "<URL>"

    ...
}

A description object must provide the following properties:

• The type property is specifies the type of the hardware element being described. Its value is a string. The following values are specified:
  • "control": the object describes a Control Board
  • "power": the object describes a Power Board
  • "inverter": the object describes an Inverter board
  • "bridge": the object describes a bridge

• The formatVersion property is an integer that specifies the version of the Motor Control Board description format to which the description object conforms. This property is used by the Workbench to properly decode the description.
• The descVersion property is an integer that states the version of the description. This version is incremented on updating a description (to fix an description bug or to describe a feature that was not yet described, or any other reason). It can be used to update a set of descriptions with newer versions.
• The name property is a string

The following property are optional and can be present in all description objects:

• "PN": a string that specify the part number of the board being described
• "shortDescription" and "longDescription": A short and a longer text that act respectively as a title and a description of the board being described meant to be displayed to users.
• "link": an URL pointing to a web page dedicated to the board being described

3.3. Control Board

A Control Board is described in a JSON object that has a type property set to "control".

A Control board hosts one STM32 MCU. It can implement features and it provides one or more connectors. Each connector can be used to plug a Power board. So, a control board providing two connectors can drive two motors.

Each connector present on a control board is described in a Connector object. Connector objects are put in a connectors array.

Some of the features implemented by a control board are independent of its connectors (they do not rely on signals coming from other boards plugged to them). These are described in a features array that contains one Feature object per feature.

Some other features can only be used in relation with a connector of the board. These are described in the Connector object they relate to. See the Connector Object. section below for all the details.

The MCU is referenced by the mcu property.

A control board description object adds the following properties to the common ones:

• mcu: a string that references the MCU. This reference is the part number of the STM32 including the package specifier and excluding the temperature one (replaced by an x). For instance: STM32G474QETx.
• clockSource: a string. TBD. See with WB team. Is this an enum?
• clockFrequency: an integer. TBD. See with WB team
• connectors: An array of Connector objects. Each Connector object describes an actual connector installed on the board. A control board shall provide at least one connector. So, this table must not be empty.
• features: An array of Feature objects. Connectors independent features shall be described in this array. A feature is connectors independent if it can be used even though nothing is plugged to any of the connectors of the control board. Each Feature object in the array describe one such feature implemented on the board. This array is empty for a control board that does not provide any connector independent feature.

A skeleton of a control board description is presented below. For the sake of brevity, the common properties are not shown as well as objects specified elsewhere.

{
	"mcu": "STM32<reference>x",
	"clockSource": "<clock source>",
	"clockFrequency": <MCU frequency>,
    
  "features": [ ... ],

	"connectors": [ ... ]
}

3.4. Power Board

A Power Board is described by a JSON object that has a type property set to "power".

3.6. Inverter

An Inverter is described by a JSON object that has a type property set to "inverter".

3.7. Bridge

A Bridge is described by a JSON object that has a type property set to "bridge".

3.8. Connector object

plenty

4. Features Specification

Names are normative

parameters

control / power / inverter

4.1. Motor Phases Current Sensing

This feature aims at measuring the currents flowing through the phases of a motor.