NXP Semiconductors PMSMFRDMMCXN947 User manual

PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC
Motors
Rev. 0 — 5 December 2023 User guide
Document information
Information Content
Keywords FRDM-MCXN947 , PMSM, FOC, MCAT, MID, Motor control, Sensorless control, Speed control,
Servo control, Position control
Abstract This user guide describes the implementation of the motor-control software for 3-phase
Permanent Magnet Synchronous Motors.

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
1 Introduction
SDK motor control example user guide describes the implementation of the motor-control software for 3-phase
Permanent Magnet Synchronous Motors (PMSM) using following NXP platforms:
•FRDM-MCXN947
•Freedom Development Platform for Low-Voltage, 3-Phase PMSM Motor Control (FRDM-MC-LVPMSM)
The document is divided into several parts. Hardware setup, processor features, and peripheral settings are
described at the beginning of the document. The next part contains the PMSM project description and motor
control peripheral initialization. The last part describes user interface and additional example features.
Available motor control examples types with supported motors, and possible control methods are listed in
Table 1.
Possible control methods in SDK example
Example type Supported motor Scalar and
Voltage
Current FOC
(Torque)
Sensorless
Speed FOC
Sensored
Speed FOC
Sensored
Position FOC
Linix 45ZWN24-
40 (default motor) ✓ ✓ ✓ N/A N/A
pmsm_enc Teknic M-2310P
(with ENC) ✓ ✓ ✓ ✓ ✓
Table 1. Available example type, supported motors and control methods
SDK motor control example description:
• pmsm_enc - pmsm example uses float arithmetic, the example contains sensored and also sensorless field
oriented vector control (FOC). This example can be used for sensor and sensorless motor control application
both. Default motor configuration is tuned for the Linix 45ZWN24-40 motor.
The SDK motor control example contains several additional features:
• FreeMASTER pmsm_float_enc.pmpx project provides a simple and user-friendly way for algorithm tuning,
software control, debugging, and diagnostics.
• MCAT - Motor Control Application Tuning page based on the FreeMASTER runtime debugging tool.
• MID - Motor parameter identification.
The control software and the PMSM control theory, in general, are described in Sensorless PMSM Field-
Oriented Control (FOC) (document DRM148).
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
2 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
2 Hardware setup
The following chapter describes the used hardware and the setup needed for proper example working
2.1 Linix 45ZWN24-40 motor
The Linix 45ZWN24-40 motor is a low-voltage 3-phase permanent-magnet motor with hall sensor used in
PMSM applications. The motor parameters are listed in Table 2.
Characteristic Symbol Value Units
Rated voltage Vt 24 V
Rated speed - 4000 RPM
Rated torque T 0.0924 Nm
Rated power P 40 W
Continuous current Ics 2.34 A
Number of pole-pairs pp 2 -
Table 2. Linix 45ZWN24-40 motor parameters
Figure 1. Linix 45ZWN24-40 permanent magnet synchronous motor
The motor has two types of connectors (cables). The first cable has three wires and is designated to power the
motor. The second cable has five wires and is designated for the hall sensors’ signal sensing. For the PMSM
sensorless application, only the power input wires are needed.
2.2 Teknic M-2310P motor
The Teknic M-2310P-LN-04K motor is a low-voltage 3-phase permanent-magnet motor used in PMSM
applications. The motor has two feedback sensors (hall and encoder). For information on the wiring of feedback
sensors, see the data sheet on the manufacturer webpage. The motor parameters are listed in Table 3.
Characteristic Symbol Value Units
Rated voltage Vt 40 V
Rated speed - 6000 RPM
Table 3. Teknic M-2310P motor parameters
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
3 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
Characteristic Symbol Value Units
Rated torque T 0.247 Nm
Rated power P 170 W
Continuous current Ics 7.1 A
Number of pole-pairs pp 4 -
Table 3. Teknic M-2310P motor parameters...continued
Figure 2. Teknic M-2310P permanent magnet synchronous motor
For the sensorless control mode, you only need the power input wires. If used with the hall or encoder sensors,
connect the sensor wires to the NXP Freedom power stage.
1 DRAIN x3 P DRAIN 9 16AWG BLK PHASE R
Pin Color
Encoder wires
Motor phases(Wire entry view)
Signal ColorPin Signal
2 N/A N/A 10 16AWG RED PHASE S
3 GRN 11 16AWG WHT PHASE T
4 GRN/WHT 12 RED +5VDC IN
5 GRY/WHT 13 BRN ENC 1
6 DRAIN x1 14 ORN ENC B
7 BLK 15 BLU ENC A
16* ORN/WHT ENC B˜
8* BLU/WHT
COMM S-T
COMM R-S
COMM T-R
E DRAIN
GND
ENC A˜
9 10 11 12 13 14 15 16
1 2 3 4 5 6 7 8
Figure 3. Teknic motor connector type 1
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
4 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
R DRAIN x3 P DRAIN L GRY/WHT COMM T-R
Pin Color
Motor phases Encoder wires(Mating face shown)
Signal ColorPin
F
Signal
C 16AWG RED PHASE S U BRN ENC I
D 16AWG WHT G GRN COMM S-T
B 16AWG BLK T RED +5VDC IN
J BLU F* ORN/WHT ENC B˜
K* BLU/WHT V ORN ENC B
H GRN/WHT M DRAIN x1 E DRAIN
S BLK
PHASE T
PHASE R
ENC A
ENC A˜
COMM R-S
GND
G
A M
E
B
H
L
D R
C
J
K
P
T
U
S
V
N
Figure 4. Teknic motor connector type 2
2.3 FRDM-MC-LVPMSM
In a shield form factor, this evaluation board effectively turns an NXP Freedom development board or an
evaluation board into a complete motor-control reference design. It is compatible with existing NXP Freedom
development boards and evaluation boards. The Freedom motor-control headers are compatible with the
Arduino R3 pin layout.
The FRDM-MC-LVPMSM low-voltage, 3-phase Permanent Magnet Synchronous Motor (PMSM) Freedom
development platform board has a power supply input voltage of 24 VDC to 48 VDC with reverse polarity
protection circuitry. The auxiliary power supply of 5.5 VDC is created to supply the FRDM MCU boards. The
output current is up to 5 A RMS. The inverter itself is realized by a 3-phase bridge inverter (six MOSFETs) and a
3-phase MOSFET gate driver. The analog quantities (such as the 3-phase motor currents, DC-bus voltage, and
DC-bus current) are sensed on this board. There is also an interface for speed and position sensors (encoder,
hall). The block diagram of this complete NXP motor-control development kit is shown in Figure 5.
Figure 5. Motor-control development platform block diagram
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
5 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
FRDM-MC-LVPMSM Parts
Controller Card Parts
Power Supply
Polarity
24-48V
DC
Motor
15V
6xPWM
Ia, Ib, Ic
Udc, Idc
Enc, Hall
5.5V
3.3V
USB
JTAG
Protection
6x
MOSFET
Analog
Sensing
Encoder /
Hall
Encoder
Hall
Power
Supply
MOSFET
Predriver
FRDM-MC-LVPMSM Controler card
Target
MCU
Open
SDA
Buttons
LEDs
Accel
Therm
Figure 6. FRDM-MC-LVPMSM
The FRDM-MC-LVPMSM board does not require a complicated setup. For more information about the Freedom
development platform, see www.nxp.com.
Note:
There might be a wrong FRDM-MC-LVPMSM series in the market (series VV19520XXX). This series
is populated with 10 mOhm shunt resistors and noisy operational amplifiers which affect phase current
measurement. The mc_pmsm example is tuned for original FRDM-MC-LVPMSM board with 20 mOhm shunt
resistors.
2.4 FRDM-MCXN947
The FRDM-MCXN947 board consists of one MCXN947 device with a 64-Mbit external serial flash. The board
also features I3C temperature sensor, CAN PHY, Ethernet PHY, SDHC circuit, RGB LED, touch pad, high-speed
USB circuit, push buttons, and MCU-Link debug probe circuit. The board is compatible with the Arduino shield
modules and Mikroe click boards. The onboard MCU-Link debug probe is based on the LPC55S69 MCU.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
6 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
Jumper Setting Jumper Setting
J22 1-2 J24 1-2
Table 4. FRDM-MCXN947 jumper settings
All others jumpers are open.
For correct working of overcurrent protection, please, remove the R145 resistor.
2.4.1 Hardware assembling
1. Connect the FRDM-MC-LVPMSM shield on top of the FRDM-MCXN947 board (there is only one possible
option).
2. Connect the 3-phase motor wires to the screw terminals (J7) on the Freedom PMSM power stage.
3. Plug the USB cable from the USB host to the Debug USB connector J17 on the FRDM board.
4. Plug the 24-V DC power supply to the DC power connector on the Freedom PMSM power stage.
Figure 7. Assembled Freedome system
Note: The example has been tested on the board with schematic number: SCH-90818 REVB.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
7 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
3 Processors features and peripheral settings
This chapter describes the peripheral settings and application timing.
3.1 MCXN94x
The MCX N94x is based on dual high-performance Arm® Cortex®-M33 cores running up to 150 MHz, with
2MB of Flash with optional full ECC RAM, a DSP co-processor and an integrated eIQ Neutron NPU. The NPU
delivers up to 30x faster machine learning (ML) throughput compared to a CPU core alone enabling it to spend
less time awake and reducing overall power consumption.
The multicore design delivers improved system performance and reduced power consumption by enabling
smart, efficient distribution of workloads to the analog and digital peripherals. The devices are supported by the
MCUXpresso Developer Experience to optimize, ease and help accelerate embedded system development.
The MCX N94x family is geared toward industrial applications with a wider set of analog and motor control
peripherals.
For more information, see MCX N Series Microcontrollers web pages.
3.1.1 Hardware timing and synchronization
Correct and precise timing is crucial for motor-control applications. Therefore, the motor-control-dedicated
peripherals take care of the timing and synchronization on the hardware layer. In addition, you can set the PWM
frequencies as a multiple of the ADC interrupt (ADC ISR) frequency where the FOC algorithm is calculated. In
this case, the PWM frequency is equal to the FOC frequency.
Figure 8. Hardware timing and synchronization on MCXA153
•The top signal shows the PWM_AT (PWM phase A - top) and PWM_AB (PWM phase A - bottom). The dead
time is emphasized at the PWM top and PWM bottom signals.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
8 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
•The eFlexPWM submodule SM0 generates trigger 0 (ADC Trigger) when the counter counts to a value equal
to the VAL4 value. ADC Trigger is delayed of approximately Tdeatime/2. This delay ensures correct current
sampling at the duty cycles close to 100 %.
•When the ADC conversion is completed, the ADC_ISR (ADC interrupt) is entered. The FOC calculation is
done in this interrupt.
3.1.2 Peripheral settings
This section describes the peripherals used for the motor control. On MCXN94x, three submodules from the
enhanced FlexPWM (eFlexPWM) are used for 6-channel PWM generation and 12-bit ADC for the phase
currents and DC-bus voltage measurement. The eFlexPWM and ADC are synchronized via submodule 0 from
the eFlexPWM. The following settings are located in the mc_periph_init.c and peripherals.c files and
their header files.
3.1.2.1 PWM generation - FlexPWM1
•Six channels from three submodules are used for the 3-phase PWM generation. Submodule 0
generates the master reload at event every nth opportunity, depending on the user-defined macro
M1_FOC_FREQ_VS_PWM_FREQ.
•Submodules 1 and 2 get their clocks from submodule 0.
•The counters at submodules 1 and 2 are synchronized with the master reload signal from submodule 0.
•Submodule 0 is used for synchronization with ADC. The submodule generates the output trigger after the
PWM reload, when the counter counts to VAL4.
•Fault mode is enabled for channels A and B at submodules 0, 1, and 2 with automatic fault clearing.
Note: The PWM outputs are re-enabled at the first PWM reload after the fault input returns to zero.
•The PWM period (frequency) is determined by how long the counter takes to count from INIT to VAL1.
By default, INIT = -MODULO/2 and VAL1 = MODULO/2 -1 where MODULO = FastPeripheralClock /
M1_PWM_FREQ.
•Dead time insertion is enabled. Define the dead time length in the M1_PWM_DEADTIME macro.
3.1.2.2 Analog sensing - ADC0
ADC0 is used for the MC analog sensing of currents and DC-bus voltage.
•The ADC operate as 12-bit with the single-ended conversion and hardware trigger selected.
•ADC0 trigger source is the PWM submodule 0.
3.1.2.3 Peripheral interconnection for - XBAR
The crossbar is used to interconnect the trigger from the PWM to the ADC.
3.1.2.4 Slow-loop interrupt generation - CTIMER0
The Standard Counter or Timer CTIMER is used to generate the slow-loop interrupt.
•The slow loop is usually ten times slower than the fast loop. Therefore, the interrupt is generated after the
timer counter counts to MR[0] = kCLOCK_FroHf / M1_SLOW_LOOP_FREQ. The speed loop frequency is set in
the M1_SPEED_LOOP_FREQ macro and equals 1000 Hz.
•An interrupt (which serves the slow-loop period) is enabled and generated at the reload event.
3.1.2.5 Quadrature Decoder (ENC)
The QD module is used to sense the position and speed from the encoder sensor.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
9 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
•The direction of counting is set in the M1_POSPE_ENC_DIRECTION macro.
•The modulo counting and the modulus counting roll-over/under to increment/decrement revolution counter are
enabled.
3.2 CPU load and memory usage
The following information applies to the application built using one of the following IDE: MCUXpresso IDE,
IAR, or Keil MDK. The memory usage is calculated from the *.map linker file, including FreeMASTER recorder
buffer allocated in RAM. In the MCUXpresso IDE, the memory usage can be also seen after project build in the
Console window. The table below shows the maximum CPU load of the supported examples. The CPU load is
measured using the SYSTICK timer. The CPU load is dependent on the fast-loop (FOC calculation) and slow-
loop (speed loop) frequencies. The total CPU load is calculated using the following equations:
(1)
(2)
(3)
Where:
CPUfast = the CPU load taken by the fast loop
cyclesfast = the number of cycles consumed by the fast loop
ffast = the frequency of the fast-loop calculation
fCPU = CPU frequency
CPUslow = the CPU load taken by the slow loop
cyclesslow = the number of cycles consumed by the slow loop
fslow = the frequency of the slow-loop calculation
CPUtotal = the total CPU load consumed by the motor control
MCXN94x (Release configuration - speed control)
CPU load 19.5 %
Table 5. Maximum CPU load (fast loop)
FRDM-MCXN947 (Release configuration)
Readonly code memory 39 248 B
Readonly data memory 13 108 B
Readwrite rada memory 5 944 B
Table 6. Memory usage
Measured CPU load and memory usage applies to the application built using IAR IDE.
Note: Memory usage and maximum CPU load can differ depending on the used IDEs and settings.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
10 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
4 Project file and IDE workspace structure
All the necessary files are included in one package, which simplifies the distribution and decreases the size of
the final package. The directory structure of this package is simple, easy to use, and organized logically. The
folder structure used in the IDE differs from the structure of the PMSM package installation, but it uses the same
files. The different organization is chosen due to better manipulation of folders and files in workplaces and the
possibility of adding or removing files and directories. The pack_motor_<board_name> project includes all
the available functions and routines. This project serves for development and testing purposes.
4.1 PMSM project structure
The directory tree of the PMSM project is shown in below.
Figure 9. Directory tree
The main project folder pack_motor_<board_name>\boards\<board_name>\demo_apps\mc_pmsm
\pmsm_enc\ contains the following folders and files:
•iar: for the IAR Embedded Workbench IDE.
•armgcc: for the GNU Arm IDE.
•mdk: for the uVision Keil IDE.
•m1_pmsm_appconfig.h: contains the definitions of constants for the application control processes,
parameters of the motor and regulators, and the constants for other vector-control-related algorithms. When
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
11 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
you tailor the application for a different motor using the Motor Control Application Tuning (MCAT) tool, the tool
generates this file at the end of the tuning process.
•main.c: contains the basic application initialization (enabling interrupts), subroutines for accessing the MCU
peripherals, and interrupt service routines. The FreeMASTER communication is performed in the background
infinite loop.
•board.c: contains the functions for the UART, GPIO, and SysTick initialization.
•board.h: contains the definitions of the board LEDs, buttons, UART instance used for FreeMASTER, and so
on.
•clock_config.c and .h: contains the CPU clock setup functions. These files are going to be generated
by the clock tool in the future.
•mc_periph_init.c: contains the motor-control driver peripherals initialization functions that are specific for
the board and MCU used.
•mc_periph_init.h: header file for mc_periph_init.c. This file contains the macros for changing the
PWM period and the ADC channels assigned to the phase currents and board voltage.
•freemaster_cfg.h: the FreeMASTER configuration file containing the FreeMASTER communication and
features setup.
•pin_mux and .h: port configuration files. Generate these files in the pin tool.
•peripherals.c and .h: MCUXpresso Config Tool configuration files.
The main motor-control folder pack_motor_<board_name>\middleware\motor_control\ contains these
subfolders:
•pmsm: contains main PMSM motor-control functions.
•freemaster: contains the FreeMASTER project file pmsm_float_enc.pmpx. Open this file in the
FreeMASTER tool and use it to control the application. The folder also contains the auxiliary files for the
MCAT tool.
The pack_motor_imxrt1xxx\middleware\motor_control\pmsm\pmsm_float\ folder contains these
subfolders common to the other motor-control projects:
•mc_algorithms: contains the main control algorithms used to control the FOC and speed control loop.
•mc_cfg_template: contains templates for MCUXpresso Config Tool components.
•mc_drivers: contains the source and header files used to initialize and run motor-control applications.
•mc_identification: contains the source code for the automated parameter-identification routines of the
motor.
•mc_state_machine: contains the software routines that are executed when the application is in a particular
state or state transition.
•state_machine: contains the state machine functions for the FAULT, INITIALIZATION, STOP, and RUN
states.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
12 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
5 Motor-control peripheral initialization
The motor-control peripherals are initialized by calling the MCDRV_Init_M1() function during MCU startup
and before the peripherals are used. All initialization functions are in the mc_periph_init.c source file and
the mc_periph_init.h header file. The definitions specified by the user are also in these files. The features
provided by the functions are the 3-phase PWM generation and 3-phase current measurement, as well as the
DC-bus voltage and auxiliary quantity measurement. The principles of both the 3-phase current measurement
and the PWM generation using the Space Vector Modulation (SVM) technique are described in Sensorless
PMSM Field-Oriented Control (document DRM148).
The mc_periph_init.h header file provides the following macros defined by the user:
•M1_MCDRV_ADC_PERIPH_INIT: this macro calls ADC peripheral initialization.
•M1_MCDRV_PWM_PERIPH_INIT: this macro calls PWM peripheral initialization.
•M1_MCDRV_QD_ENC: this macro calls QD peripheral initialization.
•M1_PWM_FREQ: the value of this definition sets the PWM frequency.
•M1_FOC_FREQ_VS_PWM_FREQ: enables you to call the fast-loop interrupt at every first, second, third, or
nth PWM reload. This is convenient when the PWM frequency must be higher than the maximal fast-loop
interrupt.
•M1_SPEED_LOOP_FREQ: the value of this definition sets the speed loop frequency (TMR1 interrupt).
•M1_PWM_DEADTIME: the value of the PWM dead time in nanoseconds.
•M1_PWM_PAIR_PH[A..C]: these macros enable a simple assignment of the physical motor phases to the
PWM periphery channels (or submodules). You can change the order of the motor phases this way.
•M1_ADC[1,2]_PH_[A..C]: these macros assign the ADC channels for the phase current measurement.
The general rule is that at least one-phase current must be measurable on both ADC converters, and the two
remaining phase currents must be measurable on different ADC converters. The reason for this is that the
selection of the phase current pair to measure depends on the current SVM sector. If this rule is broken, a
preprocessor error is issued. For more information about the 3-phase current measurement, see Sensorless
PMSM Field-Oriented Control (document DRM148).
•M1_ADC[1,2]_UDCB: this define is used to select the ADC channel for the measurement of the DC-bus
voltage.
In the motor-control software, the following API-serving ADC and PWM peripherals are available:
•The available APIs for the ADC are:
–mcdrv_adc_t: MCDRV ADC structure data type.
–void M1_MCDRV_ADC_PERIPH_INIT(): this function is by default called during the ADC peripheral
initialization procedure invoked by the MCDRV_Init_M1() function and should not be called again after the
peripheral initialization is done.
–void M1_MCDRV_CURR_3PH_CHAN_ASSIGN(mcdrv_adc_t*): calling this function assigns proper ADC
channels for the next 3-phase current measurement based on the SVM sector.
–void M1_MCDRV_CURR_3PH_CALIB_INIT(mcdrv_adc_t*): this function initializes the phase-current
channel-offset measurement.
–void M1_MCDRV_CURR_3PH_CALIB(mcdrv_adc_t*): this function reads the current information from
the unpowered phases of a stand-still motor and filters them using moving average filters. The goal is to
obtain the value of the measurement offset. The length of the window for moving the average filters is set to
eight samples by default.
–void M1_MCDRV_CURR_3PH_CALIB_SET(mcdrv_adc_t*): this function asserts the phase-current
measurement offset values to the internal registers. Call this function after a sufficient number of
M1_MCDRV_CURR_3PH_CALIB() calls.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
13 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
–void M1_MCDRV_ADC_GET(mcdrv_adc_t*): this function reads and calculates the actual values of the
3-phase currents, DC-bus voltage, and auxiliary quantity.
•The available APIs for the PWM are:
–mcdrv_pwma_pwm3ph_t: MCDRV PWM structure data type.
–void M1_MCDRV_PWM_PERIPH_INIT: this function is by default called during the PWM periphery
initialization procedure invoked by the MCDRV_Init_M1() function.
–void M1_MCDRV_PWM3PH_SET(mcdrv_pwma_pwm3ph_t*): this function updates the PWM phase duty
cycles.
–void M1_MCDRV_PWM3PH_EN(mcdrv_pwma_pwm3ph_t*): this function enables all PWM channels.
–void M1_MCDRV_PWM3PH_DIS(mcdrv_pwma_pwm3ph_t*): this function disables all PWM channels.
–bool_t M1_MCDRV_PWM3PH_FLT_GET(mcdrv_pwma_pwm3ph_t*): this function returns the state of
the overcurrent fault flags and automatically clears the flags (if set). This function returns true when an
overcurrent event occurs. Otherwise, it returns false.
•The available APIs for the quadrature encoder are:
–mcdrv_qd_enc_t: MCDRV QD structure data type.
–void M1_MCDRV_QD_PERIPH_INIT(): this function is by default called during the QD periphery
initialization procedure invoked by the MCDRV_Init_M1() function.
–void M1_MCDRV_QD_GET(mcdrv_qd_enc_t*): this function returns the actual position and speed.
–void M1_MCDRV_QD_SET_DIRECTION(mcdrv_qd_enc_t*): this function sets the direction of the
quadrature encoder.
–void M1_MCDRV_QD_SET_PULSES(mcdrv_qd_enc_t*): this function sets the number of pulses of the
quadrature encoder.
–void M1_MCDRV_QD_CLEAR(mcdrv_qd_enc_t*): this function clears the internal variables and decoder
counter.
Note: Not all macros are available for every motor control example type.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
14 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
6 User interface
The application contains the demo mode to demonstrate motor rotation. You can operate it either using the
user button, or using FreeMASTER. The NXP development boards include a user button associated with a
port interrupt (generated whenever one of the buttons is pressed). At the beginning of the ISR, a simple logic
executes and the interrupt flag clears. When you press the button, the demo mode starts. When you press the
same button again, the application stops and transitions back to the STOP state.
The other way to interact with the demo mode is to use the FreeMASTER tool. The FreeMASTER application
consists of two parts: the PC application used for variable visualization and the set of software drivers running
in the embedded application. The serial interface transfers data between the PC and the embedded application.
This interface is provided by the debugger included in the boards.
The application can be controlled using the following two interfaces:
•The user button on the development board (controlling the demo mode):
–FRDM-MCXN947 - SW3
•Remote control using FreeMASTER (Following chapter):
–Setting a variable in the FreeMASTER Variable Watch. See chapter Section 7.4
Identify all motor parameters if you are using your own motor (different from the default motors). The automated
parameter identification is described in the following sections.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
15 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
7 Remote control using FreeMASTER
This section provides information about the tools and recommended procedures to control the sensor/
sensorless PMSM Field-Oriented Control (FOC) application using FreeMASTER. The application contains
the embedded-side driver of the FreeMASTER real-time debug monitor and data visualization tool for
communication with the PC. It supports non-intrusive monitoring, as well as the modification of target variables
in real time, which is very useful for the algorithm tuning. Besides the target-side driver, the FreeMASTER tool
requires the installation of the PC application as well. You can download the latest version of FreeMASTER
at www.nxp.com/freemaster. To run the FreeMASTER application including the MCAT tool, double-click
the pmsm_float_enc.pmpx file located in the middleware\motor_control\freemaster folder. The
FreeMASTER application starts and the environment is created automatically, as defined in the *.pmpx file.
Note: In MCUXpresso, the FreeMASTER application can run directly from IDE in motor_control/
freemaster folder.
7.1 Establishing FreeMASTER communication
The remote operation is provided by FreeMASTER via the USB interface. To control a PMSM motor using
FreeMASTER, perform the steps below:
1. Download the project from your chosen IDE to the MCU and run it.
2. Open the FreeMASTER project pmsm_float_enc.pmpx . The PMSM project uses the TSA by default, so
it is not necessary to select a symbol file for FreeMASTER.
3. To establish the communication, click the communication button (the green "GO" button in the top left-hand
corner).
Figure 10. Green “GO” button placed in top left-hand corner
4. If the communication is established successfully, the FreeMASTER communication status in the
bottom right-hand corner changes from "Not connected" to "RS-232 UART Communication; COMxx;
speed=115200". Otherwise, the FreeMASTER warning pop-up window appears.
Figure 11. FreeMASTER—communication is established successfully
5. To reload the MCAT HTML page and check the App ID, press F5.
6. Control the PMSM motor by writing to a control variable in a variable watch.
7. If you rebuild and download the new code to the target, turn the FreeMASTER application off and on.
If the communication is not established successfully, perform the following steps:
1. Go to the Project > Options > Comm tab and make sure that the correct COM port is selected and the
communication speed is set to 115200 bps.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
16 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
Figure 12. FreeMASTER communication setup window
2. Ensure, that your computer is communicating with the plugged board. Unplug and then plug in the USB
cable and reopen the FreeMASTER project.
7.2 TSA replacement with ELF file
The FreeMASTER project for motor control example uses Target-Side Addressing (TSA) information about
variable objects and types to be retrieved from the target application by default. With the TSA feature, you
can describe the data types and variables directly in the application source code and make this information
available to the FreeMASTER tool. The tool can then use this information instead of reading symbol data from
the application’s ELF/Dwarf executable file.
FreeMASTER reads the TSA tables and uses the information automatically when an MCU board is connected.
A great benefit of using the TSA is no issues with the correct path to ELF/Dwarf file. The variables described
by TSA tables may be read-only, so even if FreeMASTER attempts to write the variable, the target MCU side
denies the value. The variables not described by any TSA tables may also become invisible and protected even
for read-only access.
The use of TSA means more memory requirements for the target. If you do not want to use the TSA feature,
you must modify the example code and FreeMASTER project.
To modify the example code, follow the steps below:
1. Open motor control project and rewrite macro FMSTR_USE_TSA from 1 to 0 in freemaster_cfg.h file.
2. Build, download, and run motor control project.
3. Open FreeMASTER project and click to Project > Options (or use shortcut Ctrl+T).
4. Click to MAP Files tab and find Default symbol file (ELF/Dwarf executable file) located in IDE output folder.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
17 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
Figure 13. Default symbol file
5. Click OK and restart the FreeMASTER communication.
For more information, check FreeMASTER User Guide.
7.3 Motor Control Aplication Tuning interface (MCAT)
The PMSM sensor/sensorless FOC application can be easily controlled and tuned using the Motor Control
Application Tuning (MCAT) plug-in for PMSM. The MCAT for PMSM is a user-friendly page, which runs
within the FreeMASTER. The tool consists of the tab menu and workspace as shown in Figure 14. Each tab
from the tab menu (4) represents one submodule which enables tuning or controlling different application
aspects. Besides the MCAT page for PMSM, several scopes, recorders, and variables in the project tree (5) are
predefined in the FreeMASTER project file to further the motor parameter tuning and debugging simplify.
When the FreeMASTER is not connected to the target, the "Board found" line (2) shows "Board ID not found".
When the communication with the target MCU is established, the "Board found" line is read from Board ID
variable watch and displayed. If the connection is established and the board ID is not shown, press F5 to reload
the MCAT HTML page.
There are three action buttons in MCAT (3):
• Load data - MCAT input fields (for example, motor parameters) are loaded from mX_pmsm_appconfig.h
file (JSON formatted comments). Only existing mX_pmsm_appconfig.h files can be selected for loading.
Loaded mX_pmsm_appcofig.h file is displayed in grey field (7).
• Save data - MCAT input fields (JSON formatted comments) and output macros are saved to
mX_pmsm_appconfig.h file. Up to 9 files (m1-9_pmsm_appconfig.h) can be selected. A pop-up window
with the user motor ID and description appears when a different mX_pmsm_appcofig.h file is selected. The
motor ID and description are also saved in mX_pmsm_appcofig.h as a JSON comment. The embedded
code includes m1_pmsm_appcofig.h only at single motor control application. Therefore, saving to higher
indexed mX_pmsm_appconfig.h files has no effect at the compilation stage.
• Update target - writes the MCAT calculated tuning parameters to FreeMASTER Variables, which effectively
updates the values on target MCU. These tuning parameters are updated in MCU's RAM. To write these
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
18 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
tuning parameters to MCU's flash memory, m1_pmsm_appcofig.h must be saved, code recompiled, and
downloaded to MCU.
Note: Path to mX_pmsm_appcofig.h file also composed from Board ID value. Therefore, FreeMASTER must
be connected to the target, and Board ID value read prior using Save/Load buttons.
Note: Only Update target button updates values on the target in real time. Load/Save buttons operate with
mX_pmsm_appcofig.h file only.
Note: MCAT may require Internet connection. If no Internet connection is available, CSS and icons may not be
properly loaded.
Figure 14. FreeMASTER + MCAT layout
1. Tab content
2. Connected board
3. User buttons
4. Tab menu
5. Project tree
6. Variable watch
7. Loaded configuration
In the default configuration, the following tabs (4) are available:
•Application concept: welcome page with the PMSM sensor/sensorless FOC diagram and a short application
description.
•Parameters: this page enables you to modify the motor parameters, hardware and application scales
specification, alignment, and fault limits.
•Current loop: current loop PI controller gains and output limits.
•Speed loop: this tab contains fields for the specification of the speed controller proportional and integral gains,
as well as the output limits and parameters of the speed ramp. The position proportional controller constant is
also set here.
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
19 / 61

NXP Semiconductors PMSMFRDMMCXN947
MCUXpresso SDK Field-Oriented Control (FOC) of 3-Phase PMSM and BLDC Motors
•Sensors: this page contains the encoder parameters and position observer parameters.
•Sensorless: this page enables you to tune the parameters of the BEMF observer, tracking observer, and
open-loop startup.
•Output file: this tab shows all the calculated constants that are required by the PMSM sensor/sensorless FOC
application. It is also possible to generate the m1_pmsm_appconfig.h file, which is then used to preset all
application parameters permanently at the project rebuild.
•Online update : this tab shows actual values of variables on target and new calculated values, which can be
used to update the target variables.
Every sublock in FreeMASTER project tree (5) has defined several variables in variable watch (6).
The following sections provide simple instructions on how to identify the parameters of a connected PMSM
motor and how to tune the application appropriately.
7.3.1 MCAT tabs description
This chapter describes MCAT input parameters and equations used to calculate MCAT output (generated)
parameters. In the default configuration, the below described tabs are available. Some tabs may be missing
if not supported in the embedded code. There are general constants used at MCAT calculations listed in the
following table:
Constant Value Unit
UmaxCoeff 1.73205 -
DiscMethodFactor 1 -
k_factor 100 -
pi 3.1416 -
Table 7. Constants used in equations
7.3.1.1 Application concept
This tab is a welcome page with the PMSM sensor/sensorless FOC diagram and a short description of the
application.
7.3.1.2 Parameters
This tab enables modification of motor parameters, specification of hardware and application scales, alignment,
and fault limits. All inputs are described in the following table. MCAT group and MCAT name help to locate the
parameter in MCAT layout. Equation name represents the input parameter in equations below.
MCAT group MCAT name Equation name Description Unit
PP Pp Motor number of pole-pairs.
Obtain from motor manufacturer
or use the pole-pair assistant to
determine and then fill manually.
-
Rs Rs Stator phase resistance. Obtain
from motor manufacturer or
use the electrical parameters
identification and then fill
manually.
[Ω]
Motor
parameters
Ld Ld Stator direct inductance. Obtain
from motor manufacturer or
[H]
Table 8. Parameters tab inputs
PMSMFRDMMCXN947 All information provided in this document is subject to legal disclaimers. © 2023 NXP B.V. All rights reserved.
User guide Rev. 0 — 5 December 2023
20 / 61