Release Notes for ST Motor Pilot

Copyright © 2022 STMicroelectronics

The ST Motor Pilot is a new control and monitoring PC tool that will replace the Monitor currently delivered with the Workbench. It is built on a brand new communication protocol that allows for faster and more reliable communication while consuming less MIPS from the MCU. With this protocol, internal Motor Control signals can be monitored in real time with no or controlled subsampling.

Known Limitations

This is an official version of the tool. It still lacks many features and it did not reach yet product maturity level. Among these:

• Only single drive applications are currently supported
• The Datalog service cannot stream Medium frequency task data yet (such as the Motor State or the measured speed for instance). This is not implemented in the current firmware.
• PFC is not supported yet
• Registers cannot be modified from the Registers view.
• The configuration discovery feature is only available for FOC embedded Motor Control Applications. It will soon be extended to cover Six-Step and ACIM embedded Applications.

Update History

v0.9.20 / 18-Jan-2022

Main Changes

Version 0.9.20 of the Motor Pilot provides new features and fixes bugs of version 0.9.8.

Features added to the Motor Pilot

• Added GUI support for the CPU load measurement mechanism. When enabled in the firmware, the measurements can be retrieved in the UI of the Pilot or plotted in a graph. See CPU load measurement feature below for more details.
• Auto scaling in plots is now performed automatically when a signal is added to or removed from the plot. It can also still be done manually by clicking the "Auto Scale" button in plot windows.
• Added the "Reset GUI to Default" item in the "GUI" menu that loads the default QML Application of the version of the Pilot being used.
• Enabled the use of custom baudrates to connect to a board with UART.

Issues fixed on the Motor Pilot

• Improved the overall stability of the tool
• Fixed an issue with the timestamps of Datalog records
• Fixed an issue with the Datalog recording after a windows restore
• Fixed an issue with the X Y axis label switch in XY plots
• Fixed an issue that sometimes prevented a correct update of the GUI on a change of board connection status
• Fixed an issue with DAC feature
• Fixed a resolution issue on some HDPI displays

CPU load measurement feature

This mechanism needs to be activated in the firmware, at project generation time. Refer to the documentation of the firmware for more information on this topic. the Pilot reports whether the MCU load measurement feature is activated in the "MC Configuration" panel.

To retrieve the measurements, three registers of the Motor Control Protocol are provided. The Motor Pilot can be used to get and to plot them:

• PERF_CPU_LOAD: its value reflects the latest CPU load measurement available
• PERF_MIN_CPU_LOAD: set to the minimum CPU load measured in the session
• PERF_MAX_CPU_LOAD: set to the maximum CPU load measured in the session

The performance measurement counts the cumulative number of processor cycles spent in the High and Medium frequency tasks during a Medium Frequency Task period (typically 1 ms, see the Execution rate parameter of the Speed regulator panel in the Workbench). The values of the registers represent the ratio between the measured number of cycles and the total number of cycles in a period, expressed in percent.

v0.9.8 / 14-Sep-2021

Main Changes

Version 0.9.8 of the Motor Pilot provides new features and fixes bugs of version 0.9.7:

• Fixed a synchronization problem when plotting data in multiple windows
• Reintroduced the SimpleApp.qml application that had been mistakenly removed from 5.Y.2
• Raise all window when click on Pilot
• Added Link/unlink control between plot
• It is now possible to double click to autoscale plots
• Fixed an issue with Auto scale in XY plot
• Fixed a performance issue showing when a high number of buffers is being used
• Fixed board connections issues

v0.9.7 / 22-July-2021

Main changes

Version 0.9.7 of ST Motor Pilot provides new features and fixes bugs of version 0.9.2. Here are the new features :

• multiple plot for datalog and a new YX plot
• register selection for ASYNC plot available
• Position Control Application (PositionControlApp.qml)
• divider values Ki/Kp can be now modified through pilot registers
• 6-STEP algorithm Application (defaultApp_6STEP.qml)

It fixes also the following issues:

• some connection issues
• no more issue when the pilot crashes while plot are opened, no more misalignment exists between plot and registers list
• DAC feature usage on single shunt configuration
• Update Register list file for 6-STEP

Loading a Motor Control Application in the Pilot

ST Motor Pilot is delivered with several Applications that customize the Graphical User Interface visible in the Application tab:

• The default app is tailored for driving motor control embedded applications that use the FOC driving technique. It is the application that is loaded by default when the Pilot is executed for the first time;
• The default 6Step app addresses motor control embedded applications that use the Six Step driving technique;
• The Position Control app that works with the Position Control example delivered with the Motor Control DSK.

These Applications consists in a file (with .qml extension so far) that can be loaded at run time in the Pilot. To load an application file, disconnect from the embedded Motor Control Application and activate the GUI -> Load GUI menu item. Navigate to the folder where the Motor Pilot is installed and then, down into the GUI sub folder. There, three applications are presented:

• default app: defaultApp.qml
• default 6Step app: defaultApp_6STEP.qml
• Position Control app: PositionControlApp.qml

If other *.qml files are present, they are either experimental pieces of UI that have not been removed from the release or UI components used by the applications that are not meant to be used alone. They probably do not work as intended or even work at all... use them at your own risks!

At startup, the Pilot loads the last application that was used, unless this is the first time that this version of the Pilot is executed. In this latter case, the defaultApp.qml application is loaded.

v0.9.2 / 3-May-2021

Version 0.9.2 of ST Motor Pilot is a bug fix release of version 0.9.0. It fixes the following issues:

• The Pilot would fail to update registers values from the embedded application in some situations. In such a case, information like the motor rotation speed, status and error information would not display.
• Fixed issues with the DAC output feature.
• Added many signals to the Datalog and the DAC output features. Among them, the observers, encoder and Hall sensors angles.

v0.9.0 / 23-Apr-2021

Initial release:

The Motor Pilot replaces the monitor part of the legacy Workbench and in addition, will offer new features.

One of them, the Datalog service, provides an oscilloscope-like display to plot, in real time, at high speed, data available to the firmware like the measured currents or I_q and I_d for instance. This feature is partially available with the Motor Pilot delivered with this release.

Another one is the possibility for any user to customize the GUI of the tool (the "Application", visible in the Application tab). Indeed, the Application is delivered as a script in a text file that can be easily modified and adapted to the users' needs. Documentation on this subject will be provided with future releases of the Pilot. in the current version, this feature is used to propose an Application dedicated to drive the Six-Step examples.

A third feature of interest is the automatic discovery of the configuration of the embedded Motor Control Application. The firmware features some specific registers that describe its configuration and provide the values of some of its parameters. These registers are read and decoded by the Pilot and the Application uses them to adapt its GUI.

Features and Usage of this release

The first version of the Motor Pilot User Interface is able to start and stop the motor and to set a speed or a torque ramp and to monitor a set of signals, such as VBUS, the temperature, the rotation speed, Iq, Id... It can also be used to tune the Rev up sequence. In short, it can already do most of what the Monitor of the Motor Control Workbench is doing (see the Known Limitations section above). In near future, additional features will be added.

The Motor Pilot communicates with the embedded application thanks to a new protocol, Motor Control Protocol v2. This protocol is currently available across serial ports such as the virtual COM ports over USB that are available with the STLink debug feature available on all Nucleo boards for instance.

On the first startup, the Pilot will load the default GUI a.k.a. the defaultApp. This Application is suitable to drive FOC single drive embedded Motor Control Applications. To start driving an embedded Motor Control Application, select the COM port to which it is connected, choose the Baudrate that was configured for that UART in the firmware and click the Connect button. Once the connection with the embedded application is established, a green check appears to the right of the Connect button and the version of the firmware is displayed, also in green, next to it. Then, the configuration of the embedded application is visible on the right of the UI under the "MC Configuration" title. Also, the big speed gauge at the center of the UI should display Min and Max values matching that of the embedded application and the VBUS one should also adapt its max value to that of the application. If that is not the case, disconnect and reconnect again. The speed gauge is only visible in SPEED mode. The Control Mode can be changed under the "Control" section, on the left of the UI by using the "Mode" drop down menu.

Advanced Configuration

Clicking the "Advanced Configuration" button lets a column appear on the right of the UI. This column allows for changing the parameters of the Observers and of the PIDs. It disappears if the button is clicked again.

If the "Advanced Configuration" column is not visible, extend the width of the window of the Motor Pilot to reveal it. There should be a horizontal slider on the UI but it does not always show. This is a known issue that will be addressed in a future release.

Using other Motor Pilot Applications

To use another Motor Pilot GUI, disconnect from the embedded Motor Control Application and activate the File -> Open menu item. Navigate to the folder where the Motor Pilot is installed and then, down into the GUI sub folder. There, three applications are presented:

• defaultApp.qml: this is the default application, that is started on the first run of a new version of Motor Pilot;
• SimpleApp.qml: this is a simplified version of the former, with less controls
• SimpleAppMCPV2_6STEP.qml: this application id specifically designed to drive the Six Step examples delivered with the Motor Pilot.

If other *.qml files are present, they are experimental pieces of UI that have not been removed from the release. They probably do not work as intended or even work at all... use them at your own risks!

At startup, the Pilot loads the last application that was used, unless this is the first time that this version of the Pilot is executed. In this latter case, the defaultApp.qml application is loaded.

The Datalog service

The Pilot features the Datalog service: the periodic sending by the firmware, through the Motor Control Protocol, of buffers filled with data it has measured or produced. This allows for implementing an oscilloscope-like feature that is (partially) available in this version of the Pilot.

The data that can be sent in buffers via the Datalog service include data measured of produced by the firmware on the high frequency task like I_a and I_b for instance but also I_alpha, I_beta, I_q, I_d, V_q, V_d,... The full list of signals available in the current release of the Pilot is listed in the configuration pane of the Datalog service. Signals produced on the medium frequency task are not yet available to the Datalog service; they will be added in a subsequent version.

Signals streamed by the Datalog service can be plotted on the screen (the default) and they can also be recorded into a CSV formatted file for later processing with tools like Matlab(tm) for instance.

To configure and use the Datalog service, go to the "ASYNC config" tab. There, the Add Register button is used to add a signal to the Datalog. Currently, up to 6 signals can be streamed to the Pilot through the service. But the actual number of signals that can be streamed depends on several factors like the serial port baudrate and the High Frequency rate.

A High Frequency Rate set to 0 means that selected signals will be recorded in the transfer buffer on each PWM period. A Rate of 1 means they will be recorded every other PWM period... signals are pushed to the Datalog transfer buffer every Rate+1 PWM period. All selected signals are recorded on the same PWM period to keep the coherence between them.

Each signal is a 2-byte data. On the serial port, with the Motor Control Protocol, a byte is transferred with 10 bits: 1 start bit, 8 data bits and 1 stop bit. So, to give an example sending I_q and I_d, on every PWM frequency, with a 20 kHz PWM frequency, requires a throughput of:

With a High Frequency Rate of 1, the required throughput goes down to 200'000 bits per seconds. The actual needed throughput is slightly higher because the data are encapsulated in packets that add some extra bytes for transmission channel management.

On most series, the Motor Control Protocol v2 should reach a throughput of 1.8 Mbps. However, this baudrate may not be set by default in by the workbench. It can be changed in the Digital IO window, Serial Communication pane of the Workbench.

Another parameter of the Datalog is the "Maximum buffer size". This parameter sets the maximum amount of data that can be sent in one buffer. This number of byte is shared among all the signals that are selected for the Datalog. The bigger this parameter, the longer it will take to fill Datalog packets and thus the longer the delay between two Datalog messages. The "Maximum buffer size" parameter cannot be higher than the "Boar TX ASYNC Max Payload Size" capability that is listed above.

The availability of this service and the maximum available buffer size currently depend on the STM32 series used for the embedded application:

STSPIN devices based on STM32F0 are subject to the same limitation as the STM32F0 series. The STSPIN32G4 devices benefit from the same level of feature as the STM32G4 series.

The default Max buffer size is set by series. However, depending on the actual STM32 device and on the needs of the embedded application the amount of RAM available to the Datalog service may vary. Users can adjust this value by changing the value of the MCP_TX_ASYNC_PAYLOAD_MAX_A symbol defined in the parameters_conversion_*.h file of the generated project. Note that this value must be a multiple of 64.

Important note: When an error occurs in the application (e.g. a Speed Feedback error), the Datalog streaming is immediately stopped. All the data that are pending transmission in the current Datalog buffer are then lost. This issue is known and will be fixed in a future release of the FW so that the Datalog service can be used to investigate such issues.

License

This software package is licensed by ST under ST license SLA0048, the "License"; You may not use this package except in compliance with the License. You may obtain a copy of the License at: