Part2 - How to Use the Simulator
The first screen to explain is the main data entry and control window:
This is split into 4 areas and I'll explain each of these in turn.
The first is the '
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 that supplies the inverter. It is used to converts 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 PM 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 PM 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.
Next is the
OpenInverter Parameters section. 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.
These are all standard OI parameters so I'm not going to go 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 get included in the future.
Next
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.
And finally
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%)
The windows are:
Operating Point
- opPoint.png (17.48 KiB) Viewed 4183 times
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 plot is calculated from the shaft power of the motor, the electrical power going into the motor is not calculated but will be slightly higher (resistive winding losses). Magnetic and mechanical losses are not allowed for.
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. If anyone else want to have a look at it though feel free
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!
Edit - Jan23 Updated to reflect code changes