04 The Java Tool
Initial configuration of the controller is done via config.h parameters.
For easy handling there is a graphical tool based on Java which also helps to avoid setting unreasonable or potentially dangerous parameter combinations.
All "grey" parameters can be changed via the BluOSEC Android App at runtime. To use that functionality You need a bluetooth module (for instance HC-05) connected to the display connector of the controller though.
After having configured the firmware, you can then flash the fully configured firmware via the same Java tool.
Prior to flashing, you first have to "unlock" your controller which is done by removing the write protection from the controller and setting needed optionbytes.
Press the "Write Option Bytes" button once for that purpose. Attention! If this function is selected, the original Kunteng firmware will be irretrievably deleted! Please make sure to find out the correct phase and Hall sensor assignment on the complete system with the original firmware before deleting.
This makes sure, that the controller and the motor work together in principle. Still it can be necessary to swap the wires after flashing the firmware to a different combination. If the motor doesn't start properly with the custom firmware (turns not or only very slowly with noise and high current) try to find the right combination by trial and error. Also test the other peripheral devices such as throttle, PAS and brake lever for correct function on the entire system beforehand!
The tool is started by double-clicking on "OSEC Parameter Configurator.jar" in the project directory.
-
Number of PAS magnets: Number of magnets in the PAS disk. Required for correct calculation of the cadence
-
Wheel circumference: Wheel circumference in millimetres, is required to calculate the speed. The setting in the display is ignored.
-
PAS Timeout: Time to stop motor after stopping pedalling. Value in 64µs for Motor Speed = Normal, 48µs for Motor Speed = High. Calculation example: 3125*0,000064s = 0,2s
-
Throttle min: Voltage at closed throttle or torque signal. Required for adapting the throttle signal to full 8bit resolution of the PWM value. Conversion: 0V corresponds to 0, 5V corresponds to 255 (8bit resolution of the AD converter)
-
Throttle max: Voltage at full throttle or full deflection of the torque signal, explanation analogous to Throttle min
-
Battery Current max: maximum battery current. Calculation: Value = desired current in ampere multiplied by the value from field Battery Current cal a devided by 10. Example with the default values for limiting to 15A: 15A *100/10 = 150
-
Phase Current max: maximum phase current. Calculation like Battery Current max. The phase current is derived from the formula phase current = battery current / duty cycle internally. Phase Current max must be much higher than Battery current max, e.g. 1.5 or 2.0 times higher.
-
Regen Current max: maximum recuperation current. Calculation analogous to Battery Current calculate max. desired current as negative value.
-
Battery Current cal a: Factor a in the calibration function. ADC value = calA * Battery current + calB. calB is measured automatically at starup. Required for internal calculation of the current from the 10bit ADC value. For a 6FET and 12FET controller the value has to be something around 100, for the 18FET about 50.
-
Gear ratio: Ratio of electrical revolutions to wheel revolutions. The value is half the value of P1 for Kunteng displays, since P1 uses the number of magnets and for Gear Ratio, we need the number of pole pairs. Only needed if option Speed sensor = Internal.
-
Undervoltage: Undervoltage cutoff value. Calculation: Value in volts times (256/Battery Voltage Calibration). example: 34.3V * (256/70) = 125
-
Overvoltage: Overvoltage cutoff value during Regeneration. Calculation: Value in volts times (256/Battery Voltage Calibration). example: 54.0V * (256/70) = 203
-
Volt Calib: Used for internal calculation of the voltage from the 8bit ADC value. Must only be changed if the calibration with the preset values obviously does not fit.
-
GAIN P: Proportional factor of the PI controller. The higher the value is selected, the higher the risk, that the control starts oscillating.
-
GAIN I: Integral factor of the PI controller. The smaller the value, the smoother the control runs into the setpoint. Both gain values must be written with a dot as a decimal separator.
-
PAS threshold: Threshold for direction detection from the PAS signal. The value should be the arithmetic mean of the reciprocal of the duty cycle of the PAS-signal during forward and reverse rotation. The appropriate value can be determined by trial and error or by looking at the displayed values at turning the pedals forwards and backwards in "Diagnostics" mode, or look at the value of PAS fraction in the BluOSEC app. Set PAS threshold to a value somewhere in the middle between the value at pedalling forwards and the value at pedalling in reverse. The preset 1.7 was determined for a simple PAS with 8 magnets.
-
Assist Level 1: Support factor level 1 in torque sensor and torque simulation mode. Calculated as a percentage with the assist factor / maximum battery current
-
Assist Level 2 to Assist Level 5: see Assist Level 1
-
Morse-time 1: Is the first time of the morse code in 1/50s. The value 50 means one second. The cheat works like this: Hold the brake lever for cheat time 1, then release it for the duration of cheat time 2, then pull it again for cheat time 3, then release it again. For step 1 with a value of 50, the release of the brake lever is recognized as valid for a period of 1 to 1.5 seconds after pulling and continues with step 2. If the lever is released too early or too late, the whole procedure is reset and you have to start all over again. Currently the user does not get any feedback on whether the cheat has been activated.
-
Morse-time 2 and Morse-time 3: see Morse-time 1
-
TQ Calib: Factor for calculating the torque sensor support. Calibration factors of the measurement chain are summarized here. Greater value: More support with equal human performance. The value is internally offset with the percentage defined in the Assist level.
-
Ramp end: Duration of time between two PAS pulses in 64µs (48µs for Motor speed = High), which belongs to the desired limit cadence in torque simulation mode. Value = 60/ ((Wish cadence in 1/min)Number of PAS magnets64µs). Example calculation for a limit cadence of 60/min: 60/ (60160,000064)=977
-
Ramp start: maximum time that is still fed into the calculation (this influences how fast the startup response is after a standstill)
-
Limit (km/h): Overall speed limit
-
Without PAS (km/h): How fast you can go on motor power without pedalling
-
Offroad (km/h): The new speed limit when you are in offroad mode and the normal speed limit is overridden (only works if offroading is enabled, see below)
-
Display Type -> None: No display support.
-
Display Type -> BluOsec: Bluetooth module needed & Android App. see "Supported Displays" below.
-
Display Type -> Kingmeter J-LCD: Support of the Kingmeter J-LCD and the Lishui Forerider-App. At present, only the normal operating mode works, the programming mode of the display and the app are not supported.
-
Display Type -> KT-LCD3: Support of Kunteng LCD3, only the speed and wheel size are used. All other settings are currently without function.
-
Display Type -> Diagnostics: If this option is activated, the display protocol is not sent via UART, but some selected internal variables. Connect Rx of the display connector to GND (yellow to black) if you don't want to sent any data to the controller, even if you use Tx for diagnostics. These five values are sent as default:
- duty cycle of the PWM (0... 255)
- ERPS
- battery current (10bit AD converter value)
- battery voltage (10bit AD converter value)
- advance angle
-
Dynamic Assist Level: Using the throttle for a longer period of time will automatically increase the assist factor a bit. After the throttle is released, the assist factor will slowly ramp down again.
-
Enable rotor angle correction: The automatic adjustment of the advance angle is activated. If a ZVS type is used, the option must remain deactivated. The controller will then not run at optimum efficiency and generate unnecessary heat.
-
Bypass PI control regen @low speed: This improves the regeneration rate at low speeds, more or less the opposite to "Speed influences Regen Rate"
-
Torquesensor: This is a mode switch. In TQ sensor mode PAS activity and throttle are handled differently as you do both at the same time with your feet.
-
Assist Lvl affects throttle: self explanatory
-
Offroad enabled: If enabled, speed restrictions can be suspended. Check which regulations apply in your country b4 enabling.
-
Brake disables Offroad: Offroad mode is disabled after braking for 5 seconds
-
Regen Digital: regen is activated by the brake lever switch, otherwise linear regen via an analog voltage on pad X4, you can use an additional thumb throttle for example
-
Speed influences Regen Rate: more regen the faster you are going
-
Speed influences TQ sensor: more power the faster you are (only in TQ sensor mode)
-
PAS inverted: Switch the direction, if motor runs only while pedalling in reverse
-
Power Based Control: Switches from current regulation control to power regulation (the lower voltage the more current you get for the same assist %)
-
Idle Disables Offroad: If offroad has been enabled, this disables it after one minute of inactivity /standstill.
-
External Speed Sensor: If enabled, speed is calculated from external sensor signal. The speed is always correctly displayed here, even when the motor is at a standstill and in the case of middrive motors. If disabled (left unchecked), speed is calculated from the motor commutation. No speed will display for motors with freewheel function if motor is not moving.
-
Switch to 360 degree interpol: Normally the controller interpolates PWM between hall sensor signals, that is 60° interpolation
This option switches to 360° at 60 ERPS (iirc). The faster the motor is spinning the more likely 60° interpolation is going to interpolate "rough" / incorrect especially if you have high gear ratio / high speed motor. Then there are only 7 or 8 steps left within 60° and you might get noticeable rounding errors.
- High Speed Motor: If activated, PWM frequency 20.833 kHz, for very fast rotating motors. If disabled (unchecked), PWM frequency 15.625 kHZ, sufficient for direct drive and most hub and mid-engines.
- Hall Angle 4: Defines the rotor angle assigned to Hall pattern 4. (Hall patterns shown here) Usually does not need to be changed. This can be used to compensate for manufacturing inaccuracies in the Hall sensor positioning, which can manifest themselves, for example, in noisy running or vibrations. In the BluOsec App, the phase current display indicates in which direction the angle must be changed in order to achieve a smoother run. In the hall order diagram there are also suggestions on how to change the angles (left column) based on actual pwm cycles in each phase (right column)
Note that these values are between 0 and 255. Therefore, the default values of 1, 43, 86, 128, etc, actually correspond to the degree angles 0, 60, 120, 180, etc.
-
Hall Angle 1 ... 6: Analogous to Hall Angle 4
-
Correction Angle: This is the angle at which the Advance Angle is automatically adjusted. In case of doubt set to 127! This value is also between 0-255, so the default value of 127 means 180 degrees.
-
Motor specific angle: Using this value, the timing of the motor control can be changed. As a result, manufacturing inaccuracies of the Hall sensor positions in the motor can be compensated. Only change if the motor starts badly. If unsure start with 0 (this has changed recently from 213, default angle is no longer -60° but 0°)
This value is between 0-255, representing 0-360 degrees.
-
Motor anti-jitter (@60 degree interpol): Relates to 360 degree interpol. if there are big rounding errors the interpolation might calculate the motor is at for instance 125° and then comes the next hall signal change that says 120° normally the controller would now go back on his wavetable which you can feel as "stutter" or whatever the right word is :) With this option it just stays where it is until interpolation catches up again.
-
Disable Interpolation: This disables interpolation, which should be done for any ZWS type controllers (like the KT48ZWSRD). Enabling this option on the ZWS type controllers will result in lots of vibration and noise from the motor.
-
Disable 60 degree Interpolation: Similar to Switch to 360 but interpolation goes to 360° right after startup.
-
PWM off @coast: not implemented yet!
-
DC Static Zero: Fixes the duty cycle statically so you create a lot of current through the controllers sensor when turning the wheel by hand. You can then read you motor angle from the diagram. If you accidentally ride with this option enabled you'll probably fry some components.
Write eeprom magic byte checkbox: Will reset saved values in the controller (all changed "grey" options are reverted back to flashed defaults)
Write Configuration button: The set parameters are written to the file "config. h" and the compilation of the code and then the flash process is started. The controller must be connected to the STLink-V2. Flashing can be observed by the blinking LED in the STLink-V2.
Write Option Bytes button: Remove the write protection of a new controller. Attention, this function deletes the original firmware of Kunteng and cannot be undone! This function only has to be executed when the controller is locked or when option bytes are set to microcontroller default.
To find the right value for Motor Specific Angle:
-
Set all speed limits to 100, set Gear Ratio to 100. This makes sure, that no speedlimit cuts the power at high rpms. (Note: If you set these values via BluOSEC App, go with max. Values of '80'; '100' seems to cause overflow and you are back at '20' in the App)
-
Than change the motor specific angle in steps of 5 in both directions starting from zero (0, 5, 10 .... 255, 250, 245) until 20 and 235. Look at the current draw with wheel in the air at full throttle. The setting with the lowest current is the best. If you found the optimum, you can finetune with steps of 1.
Note: The gear ratio has no effect on the commutation, it only defines the threshold where the motor cuts the power due to the speedlimit. So just check the speed where the motor cuts the power with a normal speedometer, when you set the speedlimits to e.g.25 kmph. Then adjust the gear ration and the wheel circumference.