IPM Motor Simulator

What is it

At its core the simulator is a mathematical model of an Interior Permanent Magnet (IPM) motor. This is wrapped with a Graphical User Interface (GUI) that allows the voltage stimulus applied to the motor model, and the resulting motor currents and rotor position from the model, to be graphed. The program also includes hooks to allow the core control code from the OpenInverter (OI) firmware to be used to control the motor. The GUI allows the relevant parameters within the OI firmware, and the motor model parameters, to be adjusted to see what effect changes may have.

Now the model isn't perfect, and it isn't supposed to be, but it is pretty close and good enough for its intended purpose which is to allow an understanding of the effect of parameter changes to be developed and to provide a safer way to evaluate OI code changes before testing in the real world.

Please note that it is just a model, don't assume that just because code runs OK in the simulator that it will work in the real world. It's a different compiler and is running without any of the execution speed limitations found in the real world and does not simulate the full hardware system. Use just as much caution in real testing as you would have done without the simulator.

Now because it includes the OI code, and because it is intended that you can try different versions of the OI code, it is available as full source code rather than and executable, i.e. you have to install the development environment/compiler, the source code and OI firmware and then build the code before you can use it. The process is pretty straightforward and allows the code to be run on multiple platforms (Linux, Windows and Mac to date), it also allows full source code debugging if you want to use it to develop the code or look for problems. The first thing to do is therefore to install the Qt development environment.

For full details of the development of the simulator see https://openinverter.org/forum/viewtopic.php?t=2611

Installing Qt

To quote Wikipedia "Qt is cross-platform software for creating graphical user interfaces as well as cross-platform applications that run on various software and hardware platforms such as Linux, Windows, macOS, Android or embedded systems with little or no change in the underlying codebase while still being a native application with native capabilities and speed.". It comes in both open source and commercial versions and for home use the open source version is fine.

To install download the online installer from https://www.qt.io/download-qt-installer. You will also need to register for a Qt account.

An example of a minimalist installation may look like this: First install only the "Qt x.x for desktop development" module. Then, once the installation is complete, open the Maintenance Tool (MaintenanceTool.exe found in the top level folder where you installed Qt) and select "Add or remove components". In the search bar at the bottom, type 'charts' and select "Qt Charts" under the version of Qt you installed. Click 'Next' and follow the prompts to complete the update.

Installing the Simulator and OpenInverter Software

This assumes that git is already installed, if not you will need to install that first (https://github.com/git-guides/install-git)

Go to the directory where you would like to install and do:

git clone https://github.com/Pete9008/IPMMotorSim

cd IPMMotorSim/

cd IPMMotorSim/

git clone --recurse-submodules https://github.com/jsphuebner/stm32-sine

This will copy the simulator code onto your machine and copy the OpenInverter code into a subdirectory within it. Johannes also has a fork of the repository which already includes the OI code it can be installed by doing a single:

git clone --recurse-submodules https://github.com/jsphuebner/IPMMotorSim.git

Currently the only difference between the two is the way a line of OI code is handled, Johannes automatically comments out a line of code that causes an oscillation in the simulator output but keeps it for real firmware builds. I'm not too keen on this as I believe the line also causes problems in real life and I'd prefer to understand and fix it rather than mask it in the simulator and so I haven't pulled this change. See here for details https://openinverter.org/forum/viewtopic.php?p=49172#p49172

Building the Software

Open QtCreator, go to 'Open Project' (either in the File menu or on the Home screen), browse to the directory where you installed the simulator and then go down into the 'IPMMotorSim' subfolder twice. In there there should be an 'IPMMotorSim.pro' file. Open this and you will get a 'Configure Project' dialog, just accept the default for this. You should see something like this:

To build the software go to 'Build' at the top and select 'Build Project: IPMMotorSim'.  This should do a full build of the simulator software and the OI firmware.  On my Qt install (which is a little out of date) this results in 53 warnings.  They are non-critical (mostly to do with old style type conversions in the OI fixed point math). With that done you can run the software either by clicking the 'Run' button (green triangle at the bottom left), the 'Start Debugging' button (other green triangle with a bug icon) or by selecting the same from the top menu. With that done you should see something like this:

Now on the first run the window positions are not set so the first thing to do is to set the windows up how you like them, this is how I set it up:

On subsequent runs these positions are remembered.  It's worth noting that the more windows you have active the slower the results are to draw so there is no point having windows up that you don't use.

The last thing to do is run the simulator to see if everything works, first change the values for Lq to 4 and Lq to 2 (so that it matches the Lq-Ld setting of 2 that has been pulled from the param file) and hit 'Run (1s)', you should see something like this:

How to Use the Simulator

The first screen to explain is the main data entry and control window:

This is split into 4 areas, taking each in turn.

Vehicle Parameters 

These are the settings that only affect the motor model, they basically configure the model to match the parameters of your motor and vehicle, they can either be measured (see earlier posts in thread for details) or found online.  The closer they match your vehicle/motor the closer the simulator results will be to the real world.  The values are:

• Vehicle Weight - The weight in kg of the vehicle. This is used to calculate how quickly the motor can accelerate for a given torque.
• Wheel Radius - The rolling radius of the vehicle wheels. Again used to calculate how quickly the motor can accelerate for a given torque.
• Gear Ratio - The total gear ratio (gearbox + diff if separate). Again used to calculate how quickly the motor can accelerate for a given torque.
• Vdc - This is the HV bus voltage supplied to the inverter. It is used to convert from the OI PWM values to the effective voltage applied to the motor.
• Lq - This is the quadrature inductance of the motor (inductance with the rotor at 90degress to the field). It determines how the motor current changes in response to applied voltage.
• Ld - This is the direct inductance of the motor (inductance with the rotor aligned to the field). It determines how the motor current changes in response to applied voltage.
• Rs - This is the series resistance of the motor windings. It determines how the motor voltage changes in response to current.
• λ - This is the Flux Linkage of the motor. It determines how effectively the magnetic flux links to the rotor and affects the torque and back EMF of the motor. NOTE - this value is the exception in that it is pulled from the param_prj.h file and used in both the motor model and OI firmware (see comments below for details on the param_prj file).
• SyncDel - This is compensation for the difference in time between the motor position and motor current measurement within the OI firmware. It should be left at 16.
• Loop Frequency - This is the frequency of the main motor control loop. It is always 8800 for OI.
• Sampling Point - This compensates for the OI current sampling point relative to the control loop interrupt/run point. Leave at 50% for current OI versions.
• Extra Cycle Delay - This enables the addition of a clock cycle delay to accurately represent the PWM Timer reload in OI firmware and should be left ticked. (Note - unticking will appear to increase the stability of control loops in the simulator but this is not representative of the real world).
• Add Noise - This adds artificial noise to the motor current measurements and can be used to asses the effect of real world noise on control loop stability.
• Road Gradient - This adds a road gradient, positive is uphill, negative is downhill, Used to introduce acceleration/deceleration into the coasting/zero torque test case (a downhill coast is quite a severe test for the FW and throttle limit control loops).
• Use Throt Ramps - This adds throttle ramps to limit how quickly throttle changes are applied to the control loop. Ticking reflects the ramps present within typical OI configurations. Unticked gives the worst case transient for when testing control loops stability.

OpenInverter Parameters

These are all fields from within the param_prj.h file which are made available here to allow them to be adjusted easily. Any changes to their values are NOT persisted across program runs but are instead re-initialised from the param_prj.h file on each program start up. It is suggested that the param_prj.h file is modified to reflect any changes that you would like to make permanent. Please note that some parameters in the files that you may expect to have an effect are ignored (syncofs, pinswap and respolepairs). All parameters that affect the higher level vehicle control functions of OI are also not used.

NOTE - the param_prj.h file used in simulator builds is the one on the simulator directory, NOT the one in the OI build tree that is used for firmware builds. It is up to the user to keep these files synced if required.

NOTE - the simulator must be rebuilt following any changes to the param_prj.h before the simulator will use the new values.

NOTE - the simulator accurately models the behaviour of the ADCs on the OI boards, including overflow/clipping behaviour. If the values for il1gain and il2gain are not appropriate for the current levels modelled in the simulator then overflow will occur. Keep the currents in the simulator less than 2048/ilxgain to prevent this (e.g. if il1gain=il2gain=5 then keep currents below 2048/5 = 410A)

These are all standard OI parameters so it's not worth going into each. A few fields here are worth mentioning though:

• Motor Poles - This needs to match the real motor otherwise torque calculations will be wrong.
• Lq - Ld - This is completely separate to the Lq and Ld settings in the Vehicle Parameters pane. It is done this way to allow the effect of mismatches to be assessed but for normal operation they should match!
• SyncAdv - This is different to the syncadv pre OI 5.24 and should normally be left as set. Very high or very low inductance motors may benefit from a slight change in the value.
• FMax doesn't do anything, this is implemented the higher vehicle control levels of OI and these are not included in the simulator. It has been left in as an additional speed limiter in the low level OI code has been talked about and may be added in the future.

Run Controls

These are fairly self explanatory and just control the running of the simulation and run for a set time or restart the simulation. Slightly less obvious ones are:

• Numeric field - The time the simulation will run for when using the 'Run For (s)', 'Transient' or 'Accel/Coast' buttons.
• Step - This is primarily used when debugging code using the Qt debugger. It allows the OI control loop to be run a single time only.
• Transient - This runs for a period at zero torque, a period at 'Torque Demand' torque, a period at zero torque and finally a period at 'Torque Demand' torque. The period is set from the numeric field. This can be useful when testing control loop transient response and overshoot.
• Accel/Coast - This runs for a period at 'Torque Demand' torque and then a period at zero torque. It can be useful when testing field weakening.

Window Visibility

This doesn't affect the simulation results in any way but reducing the numbers of displayed windows, or the number of displayed traces, does significantly increase the display update speed. Window visibility settings are persisted across program runs, as are window sizes and screen positions. The radio buttons for the Power/Torque window allow selection of the horizontal axis, plotting against speed is useful for generating traditional power/torque plots, time is useful when trying to correlate against the other plots. Similarly the radio buttons for the Operating Point window allow the display of either Amp or Volts. The checkboxes allow the three phase values to be shown or not on each of the corresponding plots (disabling speeds up redrawing by about 30%)

Graph Window Details

Operating Point

This is probably only useful if you are looking at developing MTPA or MTPV control algorithms. The Id and Iq currents, or Vd and Vq voltages, are shown on the two axis, the green circle shows the maximum current or voltage circle and the blue trace shows the operating point of the motor. Please note that the voltage circle includes the space vector allowance so can be higher than may be expected based on Vdc. In the plot above you can see the operating has moved along the MTPA line as the motor accelerates until it hits the current limit and then dropped down as FW comes in. The plot would look different for low inductance motors.

Simulation

Basic simulation data, motor electrical speed, motor rotor angle, and controller (motor electrical) position. To speed up rendering the position traces can be disabled.

Controller Voltages

This plot provides the motor voltages imposed on the motor by the controller PWM output value. This is not the true motor voltage, as the output is a PWM value, but is the equivalent non-PWM voltage that would produce the same motor currents. NOTE - these voltages are referred to an imaginary ground and so the space vector modulation is visible. The voltages actually seen by the motor would not have the space vector ripple on them (it cancels out across the three phases). If you don't like seeing the space vector ripple then comment out the three lines at line 413 of mainwindow.cpp and uncomment the three lines at line 445. The equivalent direct and quadrature voltages are also shown and are usually more useful than the phase voltages. To speed up rendering the phase voltage traces can be disabled.

Controller Currents

This plot provides the motor currents as seen by the controller. NOTE - the controller view is only correct if the current sampling point, rotor position sampling point, and sampling time offsets are all correct. If they are then this plot will match the Motor Currents plot, if not the values of Id and Iq will drift apart with frequency. Once setup correctly (and the settings above will do that) and the two plots agree there is little point in having both current windows up. Also shown is field weakening current and throttle reduction (Ud/Uq limiting).

Motor Voltages

This plot shows the components of the motor voltages as calculated from the motor equations. Each term of the equations are plotted on a separate trace. This plot is only really of value if you want to understand the interaction of the equation terms and would normally not be enabled.

Motor Currents

This plot shows the motor currents. Note that these are the actual and correct motor currents, if the controller currents and motor currents disagree then these are the correct ones and the sampling parameters (probably SyncAdv unless you have changed SyncDel or Sampling Point from their defaults) needs adjusting. It is worth noting that these should always be sinusoidal as the motor does not 'see' the space vector modulation at all, just a 15% bigger sine wave than would otherwise be possible. If over-modulation is used then some waveform distortion is to be expected. To speed up rendering the phase voltage traces can be disabled.

Power/Torque

This plot is fairly self explanatory. Use a time x-axis if trying to correlate against other plots and a speed axis if you would like a traditional power/torque plot. The normal plot is calculated from the shaft power of the motor. If the Efficiency checkbox is ticked the electrical power going into the motor is also calculated and plotted. The motor efficiency is also calculated and plotted (shaft power/electrical power). Magnetic and mechanical losses are not allowed for in any calculations.

Zooming/Scrolling windows

Zooming and scrolling on the plots is possible but not very sophisticated and currently there is no way to automatically synchronise the x-axis of the plots. To zoom use the + or - keys or draw a rectangle to zoom in on. To pan use the arrow keys. The easiest way to reset the zoom is to Step the simulation. The plotting is one area of the simulator that could probably do with a bit of work (it was quickly cobbled together from Qt examples) but realistically I can't see it happening any time soon.

Other Comments

Few other tricks are worth mentioning. Simulations can get a bit slow if trying to be true to life. If you want to simulate things quickly try dropping the weight of the car to allow it to change speed faster (I typically use 100-500kg for initial runs and only revert to actual weight when almost there).

It's worth simulating both with pack full and pack empty voltages as it can make a significant different to where FW comes in.

Finally if you are interested in the OI code the Qt debugger is fully integrated into the environment and works well with the simulator. For example:

This is with a breakpoint set in the middle of the main control loop (the red dot by the line numbers), the values of frqFiltered, ud and uq are shown on the right, you can single step through the code (while watching how the values change), push down into subroutines, set more breakpoints etc. Hovering over variables also shows their values. For debugging, or just understanding how code works, I find it invaluable. With the simulator it also has the advantage that it's safe, hitting a breakpoint in firmware controlling a real running motor can be problematic to say the least! With the simulator when you hit a breakpoint everything stops, including the motor model, allowing you to continue as if the breakpoint hadn't happened. Without the debugger I very much doubt that any of the fixed point overflow bugs would have been found and I definitely wouldn't have developed the understanding of the way the code works. If you are used programming without a debugger then it is worth having a play with it just to see what you are missing!