Vitis Motor Control Library Tutorial - 2023.2 English

Vitis Libraries

Release Date
2023-12-20
Version
2023.2 English

Tutorial Overview

Motor Control Library provides 4 algorithm-level synthesizable APIs including FOC, SVPWM_DUTY, PWM_GEN and QEI. And a simple virtual motor model is provided for verification.

Based on the Motor Control library with a virtual motor model, users can complete all core module verifications such as FOC, QEI, SVPWM, solely in the Vitis environment. This can be helpful to improve the efficiency of design modification and iterations. This tutorial is designed to guide users on how to conduct design verification and learn how to validate design functionality at different stages of the design process.

Lab-1: Downloading the Library and Understanding the structure

Download the Vitis Motor Control Library

#!/bin/bash
git clone https://github.com/Xilinx/Vitis_Libraries.git
cd Vitis_Libraries/motor_control
git checkout next

Get knowledge about directory structure of Vitis Motor Control Library

├── docs------------------------document
│   └── src
│       ├── benchmark
│       ├── guide_L1
│       │   └── IPs
│       └── images
└── L1
   ├── include
   │   └── hw------------------L1 APIs
   ├── meta
   └── tests-------------------L1 Test
      ├── IP_FOC
      │   └── src
      ├── IP_PWM_GEN
      ├── IP_QEI
      │   └── src
      ├── IP_SVPWM
      │   └── src
      └── Model---------------model files include virtual motor model

Get knowledge about the virtual motor model

A simplified physical motor model can be represented as follows:

motor1motor2

The corresponding matrix representation is shown below:

equation

The datasheet below shows parameters used in motor model.

Parameter Unit Value
Torque Constant (Kt) oz-in/A 2.27
Rotor Inertia (Ir) oz-in-sec2 3.3x10^-5
Rated Voltage V 24
Rated Torque oz-in 2.0
Rated Speed RPM 10,000
Rated Power W 15
Rated Current A 0.88
Poles pairs (N) # 2
Permanent magnet flux linkage A/Nm 0.008015
Peak Torque oz-in 6.0
No Load Speed RPM 12,800
Line-to-Line Resistance Ω 4.63
Line-to-Line Inductance mH 1.69
Ld = 0.5 * line-to-line inductance mH 0.845

These parameters could be set in the header file common.hpp in ./motor_control/L1/include/hw/ folder, the virtual motor model could be found in ./motor_control/L1/tests/Model/model_motor.hpp.

Lab-2: Simulation and verification of FOC_sensor

CSIM verification flow

source <Vitis_install_path>/Vitis/2023.2/settings64.sh
git clone https://github.com/Xilinx/Vitis_Libraries.git
cd ./motor_control/
git checkout next
git pull
cd L1/tests/IP_FOC/
make run CSIM=1

Stdout explanation

vim ./motor_control/L1/tests/IP_FOC/ip_foc_periodic_ap_fixed_sim.prj/sol1/csim/report/hls_foc_periodic_ap_fixed_csim.log

SIM_FOC_M:********** Simulation parameters ************* Motor parameter ******************** Log files***************************************
SIM_FOC_M:  Timescale  :     10 (us)    |  motor.w     : 718.0615       (rad/s) |  Log of parameters : sim_torqueWithoutSpeed.para.foc
SIM_FOC_M:  Total step :   3000         |  motor.theta :  5.014019      (rad)   |  Log of FOC inputs : sim_torqueWithoutSpeed.in.foc
SIM_FOC_M:  Total time : 0.030000 (s)   |  motor.Id    : 0.334735       ( A )   |  Log of FOC outputs: sim_torqueWithoutSpeed.out.foc
SIM_FOC_M:  Inteval    :      3         |  motor.Iq    : 1.253668       ( A )
SIM_FOC_M:  FOC MODE   : MOD_TORQUE_WITHOUT_SPEED
SIM_FOC_M:  FOC CPR    :   1000         |  FOC PPR:      2
SIM_FOC_M:************ PID Final Status *********
SIM_FOC_M:  SPEED SP   : 10000.0        |  FLUX SP: 0.0000                      |  TORQUE SP: 4.8000            |  FW SP: --
SIM_FOC_M:  SPEED KP   : 2.7000         |  FLUX KP: 1.0000                      |  TORQUE KP: 5.0000            |  FW KP: --
SIM_FOC_M:  SPEED KI   : 0.0033         |  FLUX KI: 0.0000                      |  TORQUE KI: 0.0033            |  FW KI: --
SIM_FOC_M:  SPEED ERR  : 3144.000       |  FLUX ERR:  -0.332                    |  TORQUE ERR:  3.5469  |  FW ERR: --
SIM_FOC_M:  SPEED ACC  : 23853.000      |  FLUX ACC: -862.297                   |  TORQUE ACC: 9952.8320        |  FW ACC: --
SIM_FOC_M:************************************************************************************************************************************
SIM_FOC_M:********** Simulation parameters ************* Motor parameter ******************** Log files***************************************
SIM_FOC_M:  Timescale  :     10 (us)    |  motor.w     : 1030.6429      (rad/s) |  Log of parameters : sim_rpm10k.para.foc
SIM_FOC_M:  Total step :   3000         |  motor.theta :  4.277364      (rad)   |  Log of FOC inputs : sim_rpm10k.in.foc
SIM_FOC_M:  Total time : 0.030000 (s)   |  motor.Id    : 0.079221       ( A )   |  Log of FOC outputs: sim_rpm10k.out.foc
SIM_FOC_M:  Inteval    :      3         |  motor.Iq    : -0.002429      ( A )
SIM_FOC_M:  FOC MODE   : MOD_SPEED_WITH_TORQUE
SIM_FOC_M:  FOC CPR    :   1000         |  FOC PPR:      2
SIM_FOC_M:************ PID Final Status *********
SIM_FOC_M:  SPEED SP   : 10000.0        |  FLUX SP: 0.0000                      |  TORQUE SP: 4.8000            |  FW SP: --
SIM_FOC_M:  SPEED KP   : 2.7000         |  FLUX KP: 1.0000                      |  TORQUE KP: 0.0400            |  FW KP: --
SIM_FOC_M:  SPEED KI   : 0.0033         |  FLUX KI: 0.0000                      |  TORQUE KI: 0.0033            |  FW KI: --
SIM_FOC_M:  SPEED ERR  : 159.000        |  FLUX ERR:  -0.078                    |  TORQUE ERR: 429.0039         |  FW ERR: --
SIM_FOC_M:  SPEED ACC  : -22210.000     |  FLUX ACC: -318.191                   |  TORQUE ACC: -16205.0859      |  FW ACC: --
SIM_FOC_M:************************************************************************************************************************************
SIM_FOC_M:********** Simulation parameters ************* Motor parameter ******************** Log files***************************************
SIM_FOC_M:  Timescale  :     10 (us)    |  motor.w     : -1472.6259     (rad/s) |  Log of parameters : sim_rpm16k.para.foc
SIM_FOC_M:  Total step :   3000         |  motor.theta :  -1.176267     (rad)   |  Log of FOC inputs : sim_rpm16k.in.foc
SIM_FOC_M:  Total time : 0.030000 (s)   |  motor.Id    : 0.151595       ( A )   |  Log of FOC outputs: sim_rpm16k.out.foc
SIM_FOC_M:  Inteval    :      3         |  motor.Iq    : -0.000646      ( A )
SIM_FOC_M:  FOC MODE   : MOD_SPEED_WITH_TORQUE
SIM_FOC_M:  FOC CPR    :   1000         |  FOC PPR:      2
SIM_FOC_M:************ PID Final Status *********
SIM_FOC_M:  SPEED SP   : -16000.0       |  FLUX SP: 0.0000                      |  TORQUE SP: 4.8000            |  FW SP: --
SIM_FOC_M:  SPEED KP   : 2.7000         |  FLUX KP: 1.0000                      |  TORQUE KP: 0.0400            |  FW KP: --
SIM_FOC_M:  SPEED KI   : 0.0033         |  FLUX KI: 0.0000                      |  TORQUE KI: 0.0033            |  FW KI: --
SIM_FOC_M:  SPEED ERR  : -1938.000      |  FLUX ERR:  -0.148                    |  TORQUE ERR: -5231.9961       |  FW ERR: --
SIM_FOC_M:  SPEED ACC  : -12261.000     |  FLUX ACC: -835.707                   |  TORQUE ACC: 14277.8711       |  FW ACC: --
SIM_FOC_M:************************************************************************************************************************************
  • The current test is a hybrid test of the 8 modes run serially.The first three of the the eight modes’s simulation parameter and Motor parameter is shown up.
  • For example, the title of “simulation parameters” shows the setting for simulation. The first 3000 test steps
    • use MOD_SPEED_WITH_TORQUE, Speed setpoint is 10000, as we could check the “motor parameter” motor.w=1030.6429 (rad/s) is near the setting rpm 10000. (RPM = motor.w * 60 / (2 * pi) )
    • CPR = 1000 and PPR =2
    • title of “log files” shows the log files generate for this 3000 steps. They will be used as input and golden files for the file flow test, which better simulate the actual running.
    • Then still apply MOD_SPEED_WITH_TORQUE for the next 3000 steps, Speed setpoint is 16000
SIM_FOC_F:****Loading parameters and input from files ************************************************************************************
SIM_FOC_F:  parameters file is sim_torqueWithoutSpeed.para.foc, format:
SIM_FOC_F:  FOC inputs file is sim_torqueWithoutSpeed.in.foc, format: <float va> <float vb> <float vb> <theta_m, rpm> <int va> <int vb> <int vc>
SIM_FOC_F:  FOC output file is sim_torqueWithoutSpeed.out.foc, format: <float va> <float vb> <float vb> <theta_m, rpm> <int va> <int vb> <int vc>
SIM_FOC_F:  MODE      : 2
SIM_FOC_F:  FLUX_SP   : 0.000000
SIM_FOC_F:  FLUX_KP   : 1.000000
SIM_FOC_F:  FLUX_KI   : 0.000000
SIM_FOC_F:  TORQUE_SP : 4.799988
SIM_FOC_F:  TORQUE_KP : 5.000000
SIM_FOC_F:  TORQUE_KI : 0.003311
SIM_FOC_F:  SPEED_SP  : 10000.000000
SIM_FOC_F:  SPEED_KP  : 2.699997
SIM_FOC_F:  SPEED_KI  : 0.003311
SIM_FOC_F:  VD        : 0.000000
SIM_FOC_F:  VQ        : 24.000000
SIM_FOC_F:  FW_KP     : 1.000000
SIM_FOC_F:  FW_KI     : 0.003311
SIM_FOC_F:  CNT_TRIP  : 3000
SIM_FOC_F: ***********   Comparison with golden file: ********
SIM_FOC_F:  Total step  :   3000
SIM_FOC_F:  Golden File : sim_torqueWithoutSpeed.out.foc
SIM_FOC_F:  Max Voltage : 24.000        100.00%
SIM_FOC_F:  threshold   : 1.200 5.00%
SIM_FOC_F:  Mean error  : 0.000 0.00%
SIM_FOC_F:  Max error   : 0.000 0.00%
SIM_FOC_F:  Min error   : 0.000 0.00%
SIM_FOC_F:  Total error :      0
SIM_FOC_F:********************************************************************************************************************************
  • The stdout shown above is the file based simulation result of the first of the eight modes.

Waveform explanation and check

  1. vim ./motor_control/L1/tests/IP_FOC/ip_foc_periodic_ap_fixed_sim.prj/sol1/csim/build/sim_foc_ModelFoc.log
  2. Copy the content to excel and draw the speed curve.
sensor_csim

COSIM verification flow

cd ./motor_control/L1/tests/IP_FOC/
make run COSIM=1  XPART=xc7z020-clg400-1

To see the waveform of signal of the foc, please add parameter -wave_debug behind cosim_design in file ./motor_control/L1/tests/IP_FOC/run_hls_sim.tcl.

Waveform explanation

The image below shown the signals output from the AXI interface.