Parameters
The inverter can be adapted to many kinds of motors, battery packs and driver preferences by changing parameters. A video on parameters is here: https://youtu.be/GQNQbBUsqf0
A Parameter Database with common usage scenarios is here: https://openinverter.org/parameters/
A synchronous motor tuning guide is here: Using FOC Software
Motor Parameters
The parameters to adjust the inverter to the motor are boost, fweak, fslipmin, fslipmax, polepairs, fmin, fmax and numimp.
They can be deduced from the motors nameplate or by trying which feels best. For illustration we will assume a bus voltage of 500V and a 4-pole (p=2) motor with a nominal speed of n=1450rpm@f=50Hz and 230V. With 500V DC an AC voltage of 500/1.41=355V can be generated.
boost is the digital amplitude of the sine wave at motor startup. It is needed to overcome the motors ohmic resistance. Digital amplitude is an internal quantity. 0 means no voltage is generated at all, 37813 means the full possible voltage is generated.
Example: boost=1700
At full throttle an effective voltage of 1700/37813*355=16V is generated. The best way to find a feasible value is to optimize it in the finished car. Start with the default value and increase until you get a good startup.
fweak is the frequency at which the full possible voltage is generated. It is also the point of the highest motor power. Beyond fweak torque will decrease to the square of frequency and thus power will decrease linear with frequency.
A starting point for fweak is the motors nameplate:
With our illustration motor fweak=(355 V/230 V) * 50 Hz = 77 Hz. fweak can be configured lower than that resulting in more torque at the low end.
fslipmin/fslipmax is the slip frequency at which the motor is run at minimum/maximum throttle. fslipmin is set to the motors optimal slip frequency which can be deduced from the nameplate. fslipmin=f-p*n/60. With our illustration motor fslipmin=50-2*1450/60=1.66Hz. fslipmax can be set as high as breakdown torque which is not found on the nameplate. So its best found experimental starting with 2*fslipmin. If set too high the motor will start to rock violently on startup, possibly tripping the over current limit.
polepairs is set to p, 2 in our example.
fmin should be set just below fslipmin.
fmax is used to limit the speed of the motor. The default 200Hz would result in a maximum speed of about 6000rpm.
ampmin Is the minimum relative amplitude fed to the motor. At very low amplitudes the motor does not generate any noticable torque and throttle travel is wasted that does nothing. Find out a good value by experimenting.
Inverter Parameters
pwmfrq Sets the frequency at which the IGBTs are switched on and off. The faster the switching the higher the losses in the inverter and the lower the losses in the motor. The maximum frequency is also limited by the driver boards as explained here.
pwmpol Sets the polarity of the PWM signals, active high or active low. Do not touch this parameter if you don't know what you're doing. When configured inversely it will blow up your power stage immediatly if connected to a potent power source like batteries.
deadtime The time between switching off one IGBT and switching on the other. 28=800ns, 63=1.5µs. More values can be found in the STM32 data sheet. Make sure to test the deadtime at low power levels. Setting the deadtime too low while operating of a potent power source can blow up your power stage!
Parameter Reference
The following parameters currently exist to customize the controller software. Type
set param <value>
to change it. Type
get param
to get the current value.
Parameters are internally stored with 5 binary fraction digits. That means there are 32 possible values after the decimal point. So when you set a value of 0.35 you might end up with 0.33.
Name | Unit | Min | Max | Default | Description |
Motor (FOC) | |||||
iqkp | 0 | 20000 | 64 | Current controller proportional gain. Low inductance/resistance motors need less, high inductance/resistance motors more | |
idkp | 0 | 20000 | 64 | Same as above but often a little higher then iqkp | |
curki | 0 | 100000 | 20000 | Current controller integral gain (id and iq) | |
vlimflt | 0 | 16 | 10 | Amplitude limiting field weakening filter | |
vlimmargin | 0 | 10000 | 2500 | Field weakening is brought in at modmax-vlimmargin. Increase if you get short bursts of unwanted regen at speed | |
fwcurmax | -1000 | 0 | -100 | Maximum field weakening current. Must be set to critical current of motor (TODO: link forum). Set to 0 for disabling field weakening | |
lqminusld | mH | 0 | 1000 | 0 | Difference between d and q axis inductance. The higher, the more d-current is brought in for additional reluctance torque |
fluxlinkage | mWeber | 0 | 1000 | 90 | Magnetic link between rotor and stator, shapes MTPA curve |
syncadv | dig/Hz | 0 | 65535 | 10 | Shifts "syncofs" downwards/upwards with frequency. Must be set so that ud remains at 0 when coasting below field weakening speed. SUPER DANGEROUS! Setting it wrong can cause unwanted acceleration. |
curkifrqgain | dig/Hz | 0 | 1000 | 50 | Current controllers integral gain frequency coefficient (deprecated, removed) |
ffwstart | Hz | 0 | 1000 | 200 | Starting point of field weakening controller. Below that frequency it is disabled, above it its gain is increased proportional to frequency and hits fwkp at fmax. (deprecated, removed in latest release) |
Motor (sine) | |||||
boost | dig | 0 | 37813 | 1700 | 0 Hz Boost in digit. 1000 digit ~ 2.5% |
fweakstrt | Hz | 0 | 1000 | 400 | Fweak value at potnom < 35%. Can improve low speed stability and reduce oscillation when set higher than fweak. Set equal to fweak to disable. |
fweak | Hz | 0 | 400 | 67 | Frequency where V/Hz reaches its peak |
fconst | Hz | 0 | 400 | 400 | Maximum slip is increased from fslipmax to fslipconstmax as frequency approaches this value. Only effective when greater than fweak. |
udcnom | V | 0 | 1000 | 0 | Nominal voltage for fweak and boost. fweak and boost are scaled to the actual dc voltage. 0=don't scale |
fslipmin | Hz | 0 | 100 | 1 | Slip frequency at minimum throttle |
fslipmax | Hz | 0 | 100 | 3 | Slip frequency at maximum throttle |
fslipconstmax | Hz | 0 | 10 | 5 | Slip frequency at maximum throttle and fconst. Set equal to fslipmax to disable. |
fmin | Hz | 0 | 400 | 1 | Below this frequency no voltage is generated |
Motor (common) | |||||
polepairs | 1 | 16 | 2 | Pole pairs of motor (e.g. 4-pole motor: 2 pole pairs) | |
respolepairs | 1 | 16 | 1 | Pole pairs of resolver (normally same as polepairs of motor, but sometimes 1) | |
sincosofs | dig | 0 | 4096 | 2048 | Mid point of sin/cos chip |
encflt | 0 | 16 | 4 | Filter constant between pulse encoder and speed calculation. Makes up for slightly uneven pulse distribution | |
encmode | 0 | 4 | 0 | 0=single channel encoder, 1=quadrature encoder,
2=quadrature /w index pulse, 3=SPI (deprecated), 4=Resolver, 5=sin/cos chip | |
fmax | Hz | 0 | 400 | 200 | At this frequency rev limiting kicks in |
numimp | Imp/rev | 8 | 8192 | 60 | Pulse encoder pulses per turn |
dirchrpm | rpm | 0 | 2000 | 100 | Motor speed at which direction change is allowed |
dirmode | 0 | 1 | 1 | 0=button (momentary pulse selects forward/reverse), 1=switch (forward or reverse signal must be constantly high) | |
syncofs | dig | 0 | 65535 | 0 | Phase shift of sine wave after receiving index pulse |
snsm | 2 | 3 | 2 | Motor temperature sensor. 12=KTY83, 13=KTY84, 14=Leaf, 15=KTY81 | |
Inverter | |||||
pwmfrq | 0 | 3 | 2 | PWM frequency. 0=17.6kHz, 1=8.8kHz, 2=4.4kHz, 3=2.2kHz. Needs PWM restart | |
pwmpol | 0 | 1 | 0 | PWM polarity. 0=active high, 1=active low. DO NOT PLAY WITH THIS!
Needs PWM restart | |
deadtime | dig | 0 | 255 | 28 | Deadtime between highside and lowside pulse. 28=800ns, 56=1.5µs. Not always linear, consult STM32 manual. Needs PWM restart |
ocurlim | A | -65535 | 65535 | 100 | Hardware over current limit. RMS-current times sqrt(2) + some slack. Set negative if il1gain and il2gain are negative. |
minpulse | dig | 0 | 4095 | 1000 | Narrowest or widest pulse, all other mapped to full off or full on, respectively |
il1gain | dig/A | 0 | 4095 | 4.7 | Digits per A of current sensor L1 |
il2gain | dig/A | 0 | 4095 | 4.7 | Digits per A of current sensor L2 |
udcgain | dig/V | 0 | 4095 | 6.15 | Digits per V of DC link |
udcofs | dig | 0 | 4095 | 0 | DC link 0V offset |
udclim | V | 0 | 1000 | 540 | High voltage at which the PWM is shut down |
snshs | 0 | 1 | 0 | Heatsink temperature sensor. 0=JCurve, 1=Semikron, 2=MBB600, 3=KTY81, 4=PT1000, 5=NTCK45+2k2, 6=Leaf | |
pinswap | 0 | 7 | 0 | Swap pins (only "FOC" software). Multiple bits can be set. 1=Swap Current Inputs, 2=Swap Resolver sin/cos, 4=Swap PWM output 1/3
0001 = 1 Swap Currents ony 0010 = 2 Swap Resolver only 0011 = 3 Swap Resolver and Currents 0100 = 4 Swap PWM 1 and 3 only 0101 = 5 Swap PWM 1 and 3 and Currents 0110 = 6 Swap PWM 1 and 3 and Resolver 0111 = 7 Swap PWM 1 and 3 and Resolver and Currents 1xxx likewise with PWM 2 and 3 | |
Derating | |||||
bmslimhigh | % | 0 | 100 | 50 | Positive throttle limit on BMS under voltage |
bmslimlow | % | -100 | 0 | -1 | Regen limit on BMS over voltage |
udcmin | V | 0 | 1000 | 450 | Minimum battery voltage |
udcmax | V | 0 | 1000 | 520 | Maximum battery voltage |
iacmax | A | 0 | 5000 | 5000 | Maximum peak AC current |
idcmax | A | 0 | 5000 | 5000 | Maximum DC input current |
idckp | dig | 0.1 | 20 | 2 | Proportional rate of DC current derating |
idcmin | A | -5000 | 0 | -5000 | Maximum DC output current (regen) |
throtmax | % | 0 | 100 | 100 | Throttle limit |
throtmin | % | -100 | 0 | -100 | Throttle regen limit |
ifltrise | dig | 0 | 32 | 10 | Controls how quickly slip and amplitude recover. The greater the value, the slower |
ifltfall | dig | 0 | 32 | 3 | Controls how quickly slip and amplitude are reduced on over current. The greater the value, the slower |
Charger | |||||
chargemode | 0 | 4 | 0 | 0=Off, 3=Boost, 4=Buck | |
chargecur | 0 | 50 | 0 | Charge current setpoint. Boost mode: charger INPUT current. Buck mode: charger output current | |
chargekp | 0 | 100 | 80 | Charge controller proportional gain. Lower if you have oscillation, raise to get best power factor. | |
chargeki | 0 | 100 | 10 | Charge controller integral gain. | |
chargeflt | 0 | 10 | 8 | Charge current filtering. Raise if you have oscillations | |
chargepwmin | % | 0 | 99 | 0 | Lowest charge mode duty cycle. This is needed for synchronous converters like in the Prius Gen2 where the lower IGBT is also active in buck mode and actually boosts the battery voltage into the bus capacitor when duty cycle is low. |
chargepwmax | % | 0 | 99 | 90 | Charge mode duty cycle limit. Especially in boost mode this makes sure you don't overvolt you IGBTs if there is no battery connected. |
Throttle | |||||
potmin | dig | 0 | 4095 | 0 | Value of "pot" when pot isn't pressed at all |
potmax | dig | 0 | 4095 | 4095 | Value of "pot" when pot is pushed all the way in |
pot2min | dig | 0 | 4095 | 4095 | Value of "pot2" when regen pot is in 0 position |
pot2max | dig | 0 | 4095 | 4095 | Value of "pot2" when regen pot is in full on position |
potmode | 0 | 2 | 0 | 0=Pot 1 is throttle and pot 2 is regen strength preset
1=Pot 2 is proportional to pot 1 (redundancy) 2=Throttle/regen controlled via CAN (like 0) 3=Throttle via CAN with redundancy (like 1) | |
throtramp | %/10ms | 0 | 100 | 100 | Max positive throttle slew rate |
throtramprpm | rpm | 0 | 20000 | 20000 | No throttle ramping above this speed |
ampmin | % | 0 | 100 | 10 | Minimum relative sine amplitude (only "sine" software) |
slipstart | % | 10 | 100 | 50 | % positive throttle travel at which slip is increased (only "sine" software) |
throtcur | A/% | -10 | 10 | 1 | Motor current per % of throttle travel (only "FOC" software) |
Regen | |||||
brknompedal / brakeregen | % | -100 | 0 | -50 | Foot on brake pedal regen torque |
regenramp | %/10ms | 0.1 | 100 | 100 | Ramp speed when entering regen. E.g. when you set brkmax to -30% and regenramp to 1, it will take 300ms to arrive at brake force of -60% |
brknom / regentravel | % | 0 | 100 | 30 | Range of throttle pedal travel allocated to regen |
brkmax / offthrotregen | % | -100 | 0 | -30 | Foot-off throttle regen torque |
brkcruise / cruiseregen | % | -100 | 0 | -30 | Maximum regen of cruise control |
brkrampstr / regenrampstr | Hz | 0 | 400 | 10 | Below this frequency the regen torque is reduced linearly with the frequency |
maxregentravelhz | Hz | 0 | 1000 | 0 | |
brkout / brklightout | % | -100 | -1 | -50 | Activate brake light output at this amount of braking force |
Automation | |||||
idlespeed | rpm | -100 | 1000 | -100 | Motor idle speed. Set to -100 to disable idle function. When idle speed controller is enabled, brake pedal must be pressed on start. |
idlethrotlim | % | 0 | 100 | 50 | Throttle limit of idle speed controller |
idlemode | 0 | 1 | 0 | Motor idle speed mode. 0=always run idle speed controller, 1=only run it when brake pedal is released, 2=like 1 but only when cruise switch is on | |
speedkp | Hz | 0 | 100 | 1 | Speed controller gain (Cruise and idle speed). Decrease if speed oscillates. Increase for faster load regulation |
speedflt | dig | 0 | 16 | 1 | Filter before cruise controller |
cruisemode | 0 | 1 | 0 | 0=button (set when button pressed, reset with brake pedal), 1=switch (set when switched on, reset when switched off or brake pedal) | |
Contactor Control | |||||
udcsw | V | 0 | 1000 | 330 | Voltage at which the DC contactor is allowed to close |
udcswbuck | V | 0 | 1000 | 540 | Voltage at which the DC contactor is allowed to close in buck charge mode |
tripmode | 0 | 2 | 0 | What to do with relays at a shutdown event. 0=All off, 1=Keep DC switch closed, 2=close precharge relay | |
bootprec | 0 | 1 | 0 | Engage precharge relay in boot loader. Introduced for enabling Prius Gen3 DC/DC converter when precharge relay is released. Use together with tripmode=2 | |
Auxillary PWM | |||||
pwmfunc | 0 | 2 | 0 | Quantity that controls the PWM output. 0=tmpm, 1=tmphs, 2=speed | |
pwmgain | dig/C | 0 | 65535 | 100 | Gain of PWM output |
pwmofs | dig | -65535 | 65535 | 0 | Offset of PWM output, 4096=full on |
Communication | |||||
canspeed | 0 | 3 | 0 | Baud rate of CAN interface 0=250k, 1=500k, 2=800k, 3=1M | |
canperiod | 0 | 1 | 0 | 0=send configured CAN messages every 100ms, 1=every 10ms | |
nodeid | 1 | 63 | 1 | Node ID for CAN SDO messages and for selective enabling of UART when sharing one ESP8266 module between multiple processors. | |
Testing | |||||
fslipspnt | Hz | -100 | 100 | 0 | Slip setpoint in mode 2. Written by software in mode 1 |
ampnom | % | 0 | 100 | 0 | Nominal amplitude in mode 2. Written by software in mode 1 |
Spot values
The following values are available for diagnostic purposes. Type
get
to get the current value. To read more then one you can provide a list like
get il1,il2,udc
Name | Unit | Description |
version | Firmware version | |
hwver | Hardware version | |
opmode | Operating mode. 0=Off, 1=Run, 2=Manual_run, 3=Boost, 4=Buck, 5=Sine, 6=2 Phase sine | |
lasterr | Last error message | |
udc | V | DC link voltage |
uac | V | Calculated AC voltage |
idc | A | Calculated DC current |
il1 | A | AC current L1 |
il2 | A | AC current L2 |
il1rms | A | RMS current L1 |
il2rms | A | RMS current L2 |
ilmax | A | Calculated max of il1, il2, il3 |
boostcalc | A | DC link adjusted boost setting |
fweakcalc | A | DC link adjusted fweak setting |
fstat | Hz | Stator frequency |
speed | rpm | Motor speed |
cruisespeed | rpm | Motor RPM set point for cruise control if cruisemode=CAN |
turns | Number of turns the motor completed since power up | |
amp | dig | Sine amplitude, 37813=max |
angle | ° | Motor rotor angle, 0-360°. When using the SINE software, the slip is added to the rotor position.
This is not the physical angle, but a "virtual" angle. E.g. if your motor has four pole pairs (motor and resolver), then per one physical revolution the "angle" will change four times between 0 and 360°. Discussed here: https://openinverter.org/forum/viewtopic.php?p=71253#p71253 |
pot | dig | Pot value, 4095=max |
pot2 | dig | Regen Pot value, 4095=max |
potnom | % | Scaled pot value, 0 accel.
potnom also includes the deratings. So say you have programmed udcmin=300V and you are tuning without HV, so udc=0, potnom will never be positive because it thinks the battery voltage is low. Discussed here: https://openinverter.org/forum/viewtopic.php?p=62930#p62930 range: * negative means regeneration (e.g. -30%, according to Schematics and Instructions - openinverter.org wiki) * zero means "zero torque request" * 100% means full acceleraton. |
dir | Rotation direction. -1=REV, 0=Neutral, 1=FWD | |
tmphs | °C | Heatsink temperature |
tmpm | °C | Motor temperature |
uaux | V | Auxiliary voltage (i.e. 12V system). Measured on pin 11 (mprot) |
pwmio | raw state of PWM outputs at power up | |
canio | Digital IO bits received via CAN | |
din_cruise | Cruise Control. This pin activates the cruise control with the current speed. Pressing again updates the speed set point. | |
din_start | State of digital input "start". This pin starts inverter operation | |
din_brake | State of digital input "brake". This pin sets maximum regen torque (brknompedal). Cruise control is disabled. | |
din_mprot | State of digital input "motor protection switch". Shuts down the inverter when =0 | |
din_forward | Direction forward | |
din_reverse | Direction backward | |
din_emcystop | State of digital input "emergency stop". Shuts down the inverter when =0 | |
din_ocur | Over current detected | |
din_bms | BMS over voltage/under voltage | |
cpuload | % | CPU load for everything except communication |
Tuning Guide
First you want to find a flat surface - a parking lot etc. so you can drive and stop without checking traffic. Change only one parameter at a time and save settings that work!
1. set fslipmin so that you feel car taking off smoothly and try to change it by +/-0,1Hz and check differences in starting. Save when satisfied.
2. lower boost value in 100 point until motor jitters at start. Then return it to last good value.
3. try lowering ampmin in 0,1 increments and observe throttle travel. When throttle is not just smooth but becomes sluggish return some previous increments until throttle reaction is acceptable.
4. change fweak value in +/-10Hz increments from starting point and observe torque in starting. This value is very dependent on battery voltage and is very subjective.
Now you find a hill or ramp and set car on it. You want to hold car in position on slope just using throttle pedal. If there parameters are not good motor will jump or will feel sluggish
1. add boost if motor is oscillating if it is smooth reduce it in 100 point increments until you get oscillation. Then return to last good value
2. reduce/increase ampmin in 0,25 increments untill you get oscilation in motor and return last good value
Now set the car into a hill to set fslipmax. Warning full throttle will be used. Be sure there is no other traffic!
Set fslipmax to chosen value (guess it at 2xfslipmin if you have no other way) and try to take off with full throttle.
If car feels sluggish with full throttle you have to add more slip.
If motor starts to jitter there is too much slip. Try to reduce it in 0.1Hz increments.
When you feel satisfied with settings save them and go on setting regen and braking effect.