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.

Motor Control application topologies

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:STM32 MC BoardDesc 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:STM32 MC BoardDesc 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": 1, /* descriptipon 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 array 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": 125, /* 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".

A Power Board implements the power electronics needed to drive one or more motors. It does not host an STM32 MCU and thus needs to be plugged to a control board for the motor control features it implements to be used. So a power board must provide at least one connector.

On a Power Board, a connector is considered an entry point for driving a motor. Beyond this entry point, the power board provides its features. This has three consequences for the description format:

• The connector, as outlined for Control Boards descriptions, only represents a subset of the description needs when it comes to dealing with power boards. So, Power Boards do not describe connectors but rather motorDrives that slightly differs from the notion of a Connector object. See the Motor Drive object section for full details.
• A Connector leads to the power electronics designed to drive one motor. A Power Board can drive as many motors as it provides connectors (and so Motor Drives).
• All the features of a power board are Connector dependent and so Motor Drive dependent. Indeed, the features implemented on a power board are connected to the MCU of the Control Board through the connector of the motor drive. The main purpose behind the description of a Motor Drive provided in power boards is to group the description of the features provided by the board.

A Power Board description adds the following property to the common ones:

• motorDrives: An array of Motor Drive objects. Each motor drive object groups the features installed on the board that are accessible through the connector is represents. A control board shall provide at least one connector. So, this array must not be empty.

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

{
	"motorDrives": [ /*...*/ ]
}

3.5. Inverter

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

Inverters consist in an MCU, a control stage and one or more power stages. They can be seen as a control board on which one or more power boards are plugged. As such, the description of an Inverter is a mix of control and power boards descriptions.

Like a Control Board, an Inverter hosts one STM32 MCU. And this MCU is described the same way as in a control board.

Like a Power Board, an Inverter implements one or more Motor Drives each having the features needed to drive one motor. And these Motor Drives are described the same way as in a power board, in a motorDrives array, to one exception though: an inverter board may implement both motor drives and connectors. An example of this is the STEVAL-IHM034V2 inverter that features one motor drive with all the required power electronics and one Motor Control connector that allows for plugging another power board. Still, Inverter boards use Motor Drives objects for description and handle this specific case with them.

Finally, still like a Control Board, an Inverter can implement features that are connector independent. In the context of an Inverter, such features do not relate to any of the Motor Drive implemented on the board. Theses are described in a features array placed at the root of the description object.

So, an Inverter Board description 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
• motorDrives: An array of Motor Drive objects. Each motor drive object groups the features installed on the board that are accessible through the connector is represents. An inverter shall provide at least one connector. So, this array 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 inverter. Each Feature object in the array describe one such feature implemented on the board. This array is empty for an inverter that does not provide any connector independent feature.

A skeleton of an inverter 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": 125, /* MCU frequency */
    
    "features": [ /*...*/ ],

	"motorDrives": [ /*...*/ ]
}

3.6. Bridge

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

A bridge is an adapter between two types of connectors. Its purpose is to allows for connecting a control and a power board that are equipped with different connectors.

Bridges have a direction: they have a power board side and a control board side that cannot be exchanged. Both sides provides connectors: power side connectors on the power board side and control side connectors on the control board side. A power side connector of a bridge must not be connected to a control board and a control side connector must not be connected to a power board. Bridges may feature several power side connectors that can each lead to several control side connectors.

Describing a Bridge consists in describing all the power side connectors it implements. The description of a power side connector mainly consists in listing and describing the control side connectors it leads to. Finally, each control side connector describes the associations between its terminals and that of the related power connector.

A Bridge description object adds the following property to the common ones:

• powerSideConnectors: an array of Power Side Connector objects. Each element in this array describe a connector provided by the bridge and meant to be plugged to a power board. A bridge provides at least one such connector, so this array cannot be empty.

3.6.1. Power Side Connector object

A Power Side Connector object describes one connector meant to be plugged to a power board. It provides the following properties:

• type: a string that identifies the type of the connector being described. See section Connectors for a list of the possible values.
• name: a string that names and identify the instance of the connector on the bridge. This name can be displayed to Workbench users and allows for avoiding confusion between connectors on the board. For instance, the description of a bridge that would feature two connectors of type MotorControlConnector would assign them different names so that users can distinguish them. The value of the name identifies a physical connector present on the bridge.
• controlSideConnectors: An array of Control Side Connector objects. Each element of this array describes a control side connector which terminals can be relayed to terminals of the Power Side Connector object. The purpose of a bridge is to bind power side and control side connectors, so this array cannot be empty.

As a Motor Control application is built around exactly one STM32 MCU, a power board can only be connected to one control board. So, only one Control Side Connector object or a bridge can be used in a Motor Control application. The controlSideConnectors array presents a set of alternatives from which at most one is to be chosen for a given application.

3.6.2. Control Side Connector object

A Control Side Connector object describes one connector meant to be plugged to a control board. It provides the following properties:

• type: a string that identifies the type of the connector being described. See section Connectors for a list of the possible values.
• name: a string that names and identify the instance of the connector on the bridge. This name can be displayed to Workbench users and allows for avoiding confusion between connectors on the board. For instance, the description of a bridge that would feature two connectors of type MotorControlConnector would assign them different names so that users can distinguish them. The value of the name identifies a physical connector present on the bridge.
• powerTerminals: an object describing the mapping between the terminals of the connector described by the Control Side Connector object and the terminals of the connector described by the Power Side Connector object to which it belongs. Properties of the powerTerminals object are named after terminals of the power side connector. Each describe the mapping of the terminal it is named after. These properties are arrays of Pin and Terminal objects that list the terminals of the control side connector onto which the power side connector terminals they are named after are mapped.
  

Only power side connector terminals that are mapped onto control side connector terminals need to be described. Properties of the powerTerminals object that are named after non mapped terminal are implicitly set to an empty array, so there is no need to explicitly set them in the description.

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

{
    /* ... */
    "powerSideConnectors": [
        {
            "name": "<user displayed unique power connector name>",
            "type": "<connector type>",
            
            "controlSideConnectors": [
                {
                    "name": "<user displayed unique control connector name>",
            		"type": "<connector type>",
                    "powerTerminals": { 
                        "<Power Terminal n>": [ /* ... */ ],
                        /* ... */ 
                    }
                }, 
                /* ... */
            ]
        },
        /* ... */
    ]
}

3.7. Connector object

A Connector object describes the routing between the terminals of a connector installed on a control board and the pins of the MCU hosted on this board. For each terminal, this routing can be direct or it can go through the electronics of connector dependent features implemented on the board. In both cases the routing of terminals is described in a terminals object that describes their connection to MCU pins. If the control board implements features that depend on a connector (see the Control Board section), these are described in the features property of the related Connector object.

A control board can provide more than one connector, of any type.

A Connector object provides the following properties:

• type: a string that identifies the type of the connector being described. See section Connectors for a list of the possible values.
• name: a string that names and identify the instance of the connector on the control board. This name can be displayed to Workbench users and allows for avoiding confusion between connectors on the board. For instance, the description of a control board that would feature two connectors of type MotorControlConnector would assign them different names so that users can distinguish them. The value of the name identifies a physical connector present on the bridge.
• terminals: an object describing the mapping between the terminals of the connector described by the Connector object and the pins of the MCU. The properties of the terminals object are named after terminals of the connector. Each consists in an array of Pin and Terminal objects that lists the pins of the MCU to which the terminal it is named after is connected.
  

Only terminals that are connected to the MCU need to be described. For each terminal that is not connected to the MCU, an implicit Property named after it exists and is set to an empty array, so there is no need to explicitly define it.

• features: An array of Feature objects. Features depending on the connector shall be described in this array. A feature depends on the connector if it relies on signals connected through the connector to be used. In other words, a feature depends on the connector is it cannot be used even if nothing is plugged to the connector. Each Feature object in the array describe one such feature implemented on the board. This array is empty and does not need to be explicitly defined if no such feature exist for the connector. In such a case the features array is defined implicitly and set to an empty array.

A Connector object always describes one full physical connector.

3.8. Motor Drive object

A Motor Drive object describes the connection between the features implemented on a board to drive one motor and either a connector or an MCU. It is used in power boards and in inverters descriptions. A Motor Drive object then describes one power stage. Additionally, a Motor Drive object can also be used to describe the connections between terminals of a connector and the pins of the MCU of an inverter.

In power boards descriptions, a Motor Drive object provides the parameters that define its operating range and a description of the features implemented on the board with the connection of their signals to terminals of the connector.

A Motor Drive object in an inverter board description does the same thing except that the signals of the features it describes are connected to pins of the MCU. Inverter boards may also optionally provide connectors to plug external power boards in addition to the power stages they embed. Such connectors are handled with Motor Drive objects that describe the routing between the terminals of the connectors to the pins of the MCU.

The structure of a Motor Drive object is very similar to that of a Connector object. It defines the following properties:

• name: a string that names and identify the instance of the motor drive on the board. This name can be displayed to Workbench users and should be chosen in order to allow an easy an unambiguous identification of the motor drive on the board.
• connectorType: a string that identifies the type of the connector leading to the power stage being described. See section Connectors for a list of the possible values. In the case where the Motor Drive object does not lead to a connector (which is common for an inverter), this property shall be set to an empty string. If this property is not set in a description, it is implicitly defined to an empty string.
• terminals: If the connectorType property is not an empty string, this property is set to an object describing the connections between the terminals of the connector described by the Motor Drive object and the pins of the MCU. The properties of the terminals object are named after terminals of the connector. Each consists in an array of Pin and Terminal objects that lists the pins of the MCU to which the terminal it is named after is connected.
  

Only terminals that are connected to the MCU need to be described. For each terminal that is not connected to the MCU, an implicit Property named after it exists and is set to an empty array, so there is no need to explicitly define it.
If the connectorType property is not defined or is set to an empty string, the terminals property is set to an empty object. If this property is not set in a description, it is implicitly defined to an empty string.

• features: An array of Feature objects. Features implemented in the power stage shall be described in this array. This array is empty and does not need to be explicitly defined in if no feature is to be described. This can be the case if the connectorType is not empty and no connector dependent feature is implemented for the connector referenced by the Motor Drive object. In such a case the features array is defined implicitly and set to an empty array.

3.9. Feature object

A Feature object advertises the presence of a feature on a board and groups the descriptions of hardware variants of this feature that the board implements. The type of the feature described by a Feature object is set in the type property of the object. All the hardware variants which descriptions are grouped within a Feature object must describe implementations of that feature.

A Feature object describes one instance of a feature on a board. There can be several instances of a given feature on the same board that can be used simultaneously. Each is then described in its own Feature object. A good example of this is the Button feature. Many ST Eval boards feature several buttons and each need to be described to be used,

On another side, an instance of a Feature may provide several, alternative, hardware implementations. In this configuration, only one of them can be used in a given application. These are described as hardware variants in the hwVariants array of the the Feature object. An example is the Current Sensing Feature of the X-NUCLEO-IHM07M1 board that provides both a three-shunt and a one-shunt implementation that share the same circuitry. Only one of them can be used at any given time and the choice is made by the user thanks to dedicated jumpers on the board.

A feature object provides the following properties:

• type: a string that identifies the type of the feature described by the Feature object. This string is normative and known to the Workbench. It uniquely identifies the nature of the feature. Known features are specified in the Features Specification section along with the string that identifies their type.
• name: Name of the feature described by the Feature object. This uniquely identifies the instance of the feature described on the board where the object is defined. If several instances of a feature can coexist in a given board (or in a motor control application), then several instances, with the same type but different names can be described in a board. Some features are mandatory to build a motor control application, some are not. This is known to the Workbench that deduces it from the choices of the users.
• hwVariants: an array of Hardware variant objects. Each element of the array describes a hardware variant of the feature supported by the board. A Hardware variants of a feature is an actual implementation of that feature. So, if a feature is implemented, there must be at least one hardware feature described and so, this array cannot be empty. The hardware variants described in this array represent alternative implementations of the Feature, from which one and only one is to be chosen for the feature to be used. Hardware variants are identified by their type. In the current version of this specification, there must not be two hardware variants of the same type in this array.

The properties defined here are common to all the features. Specific features may add other properties in order to provide parameters that are specific to their nature.

3.9.1. Hardware Variant object

A Hardware Variant object describes the parameters and the signals that define a hardware variant of a feature. Which signals and parameters are to be described are defined for each hardware variant. See the Features Specification section for a complete description of all known hardware variants.

A hardware variant object provides the following common properties that are defined for all hardware variant object types:

• type: a string that identifies the type of the hardware variant described by the Hardware Variant object. This string is normative and known to the Workbench. It uniquely identifies the nature of the hardware variant. Known hardware variants are specified in the Features Specification section along with the string that identifies their type.
• help: A short text string that explains what to do to activate the variant of this feature. This string is meant to be displayed to users so that they know what conditions (and possibly modifications) need to be done to their board for the hardware variant to be used.
• signals: an object describing all the signals defined by the hardware variant. This object defines one property for each signal; the name of the property is the name of the signal. Each of these properties is an array of Pin and Terminal objects that lists the pins of the MCU or the terminals of a connector to which the signal is connected. Whether the Pins and Terminal objects describe MCU pins or connector terminals depends on the context in which the enclosing Feature object is defined.

A skeleton of a feature description is presented below.

{
    "name": "<user displayed unique name of the feature>",
    "type": "<feature type>",
    
    "hwVariants": [
        {
            "type": "<hardware variant type>",
            "help": "...",
            
            "signals": {
                "signal X": [ /* ... */ ]
            }
        }
    ]
}

3.10. Pin and Terminal object

A Pin and Terminal object specifies either an MCU pin or a terminal of a connector with all the information needed to connect it properly. It provides the following properties:

• name: A string that names the MCU pin or the connector terminal. MCU pins are named as per the MCU reference manual. Terminals of a connector are named according to the nomenclature defined in the Connectors section below.
• cost: A positive integer that measures how "difficult" it is to use the pin or the terminal represented by the object. It is 0 if there is nothing to do to use the pin for this signal; it is non-zero if there is a modification to make on the board for the pin/terminal to be used. This can be a jumper to move, solder bridges to close or to open, a 0-Ohm resistor to solder or to unsolder...
  

This field is optional. If not present in a description, its value is assumed to be 0.

• help: A short text that states what to do to use the pin/terminal

In all the description formats specified in this document, Pin and Terminal objects are used in arrays.

Alternative and equipotential. Cost = 0 means equipotential. Cost != 0 means alternative.

cost compares to default configuration.

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.

5. Connectors

5.1. Morpho 64 Connector

There are several morpho connectors. The most used one, when it comes to motor control, is the "Morpho 64" found on NUCLEO-64 boards. This is the one that is considered here under the morpho type name.

It is a 76 pins connector made of two dual-strip physical connectors, usually named CN7 and CN10 (but not always).

The pinning of morpho connectors is not fixed as they are mounted on boards that target many other applications than Motor Control. And there exists other Morpho connectors like the "Morpho 144" one found on bigger nucleo boards (e.g. the F746 Nucleo-144 board).
So, it is needed to provide a coherent and unique naming for these pins. As far as Motor Control is concerned, the pins of the connector are named MRx and MLx where x ranges from 1 to 38. MLx refers to the Left physical connector (usually CN7) while MRx refers to the Right physical connector (usually CN10). Left and right is determined by holding the board so that the physical connectors are vertical with pin 1 of each being at the top left corner of each connector.

The following figure shows the topology of this connector and the naming of its terminals. These names are used to refer to the terminals of this connector in Pin and Terminal objects.

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

5.2. Motor Control Connector

The Motor Control Connector is a 34 pins connector with a fixed assignment. It is identified by the MotorControlConnector type name. The following table depicts the topology of this connector and shows the assignment of signals to terminals.