Features and configurations on display - OpenSourceEBike/TSDZ2_wiki GitHub Wiki
If your are looking for previous version information: Features and configurations on display 860C_850C_SW102_v0.8.0.
The following only applies to TSDZ2 motor controller firmware version 1.0.0 and 860C, 850C and SW102 displays firmware 1.0.0.
CAUTION: due to any possible existing bug on the firmware or user incorrect configuration, the motor controller may burn and/or the motor and bicycle wheel may start to run very fast at max power - please be very careful when installing the firmware and keep the bicycle back wheel on the air, have brake sensors installed and the possibility with easy access to quick cut the battery power like removing the battery connector to the TSDZ2.
CAUTION:
- Always use the mentioned firmware version for both the TSDZ2 motor controller and display!
- Before using the TSDZ2 and display with new firmware, you must correctly configure the options on the display. For instance, you should configure your battery low voltage cut off so as not to over discharge the battery. You should set as many of the other parameters as you can to ensure proper operation.
- When installing new firmware, always check that no unwanted functions have become enabled or disabled during the install process.
NOTE: Both displays have 3 different main screens and each one has its own customized numeric fields and 860C and 850C have also their own customized graph field on each main screen. You can change the information/variable shown on this customized fields.
- Turn on/off: ON/OFF long press
- Change assist level: UP or DOWN click
- Turn on/off the lights: UP long press
- Walk assist: hold DOWN pressed (walk assist is only enabled while DOWN button is pressed)
- Street mode on/off: While pressing DOWN, long press ON/OFF
- Motor max power: while pressing UP, long press ON/OFF
- Virtual throttle: in "Motor max power" mode, while pressing UP, long press ON/OFF
- Alternate main screen: ON/OFF click
- Show fields labels (SW102 only): M click
- Enter configurations screen: simultaneous ON/OFF, UP and DOWN, long press
- Select the variable: simultaneous UP and DOWN, long press
- Leave: ON/OFF long press
- Choose new variable: UP or DOWN click
- Jump to next field: ON/OFF click
- (860C/850C only) UP and DOWN long press to select on the graph the X axis scale from 15m, 1h, 4h or automatic
- (860C/850C only) UP or DOWN click to change X axis scale
- (860C/850C only) ON/OFF long press to leave
- Leave: ON/OFF long press to go back
- Scroll up or down: UP or DOWN click
- Edit item: 850C: ON/OFF click; 860C/SW102: menu click
- Apply: 850C: ON/OFF long press; 860C/SW102: menu click
There are a few variables that can be selected to be shown on the customized numeric fields or graph (850C only). Note that only some of them are available to be show on the graph.
| Variable | Description |
| trip time | Amount of time from startup of the system. |
| trip distance | Amount of kms from counted from startup of the system. |
| odometer | Total amount of kms. This value can be edited on the configurations, for instance in the case you want to set a specific value. |
| cadence | Pedal cadence measured using the PAS sensor inside the TSDZ2 motor. |
| human power |
Pedal human power. This is calculated using the following formulas:
|
| Wh/km | Battery power used by each km. |
| motor power | This value is calculated by multiplying the battery current to the battery voltage. |
| batt voltage | Battery voltage measure by the TSDZ2 motor controller. |
| batt current | Battery current measure by the TSDZ2 motor controller. |
| motor current | Motor current. This value is calculated as: motor current = measured battery current / PWM duty-cycle. Note that PWM duty-cycle value varies between 0 and 1. |
| battery SOC | Battery state of charge, based on counting the amount power pulled from the battery to power the TSDZ2 motor. |
| motor temp | Motor temperature. Note that if the temperature sensor is not installed, this value has no meaning. |
| motor speed | In ERPS (electric rotation per second) units. The motor has 8 pair of magnets inside, meaning each 1 ERPs equal to one RPS (rotation per second). |
| motor pwm | Motor PWM duty-cycle. This value can fluctuate between 0% and 100% max. Where 0 means 0 battery voltage applied to motor coils while 100 means max battery voltage applied. When this value hits the max of 100, means that motor max power possible is being applied. |
| motor foc | Angle calculated by FOC algorithm, between 0 and 30. Higher motor phase current and/or higher motor speed, makes this value increase. |
| Name | Default value | Description |
| Max speed | 50 |
Enter speed limit from where the motor will fade out power from.
|
| Circumference | 2050 |
Enter your wheel circumference so that speed and distance are correctly calculated.
Tip: Search on Google how to measure the wheel circumference. Below are approximate values for a quick setup. Remember to calibrate with GPS for finer adjustments. 20 inch wheel = 1595 mm 26 inch wheel = 2050 mm 27 inch wheel = 2150 mm 27.5 inch wheel = 2215 mm 28 inch wheel = 2250 mm 29 inch wheel = 2300 mm |
| Name | Default value | Description |
| Max current | 16 ampere | Set maximum allowable current to be pulled from the battery - this value is a technical characteristic of your battery, you need to find it on your battery user manual or ask to the manufacturer. Also the TSDZ2 has his own limit of the max current it can pull from the battery that is 18 amps so the TSDZ2 firmware limits to this value (no point for you to setup a higher value than 18). |
| Low cut-off | 42 volts |
The controller will reduce power to stay over this limit! NOTE that is saffer and so highly suggested that your battery pack have BMS to protect against battery deep discharging, short circuit, etc and this way to avoid possible explosions of the battery pack. Calculate the Low cut-off limit by multiplying amount of cells in series with the safe cut-off-voltage per cell, which is usually between 2.8 - 3.0 volts. Example: 42.0 volts for: 14 cells in series * 3.0 volts = 42.0 volts. Note that by setting a to high Low cut-off limit you will make less deep discharging cycles of your battery meaning the battery life will be increased AND you will then have less power available to use and so less range. |
| Resistance | 300 milliohms | The battery SOC (State Of charge) indicator use the battery resistance to consider the power loss inside the battery resistance and also the resistance on the cables. See Resistance est field instructions to know how you can get this value. |
| Voltage est | - | Real time battery voltage value that is filtered using the battery pack resistance. If the battery resistance value is correct, this voltage should almost not change when the motor is not running or when motor is running and pulling high current from the battery. |
| Resistance est | - |
Battery resistance estimated value that is automatically calculated so you can assess his value and then configure the Resistance field. How to start the automatic battery pack resistance estimation:
|
| Power loss est | - | Power loss estimated value that happens inside the battery pack due to battery and cables resistance. |
For correct configuration of SOC: 1. set battery Wh value 2. set battery voltage to reset the SOC counter 3. set the battery internal resistance
The battery needs to be charged to at least the pre-defined battery voltage to reset the counter. You can set the reset voltage to any voltage you like.
| Name | Default value | Description |
| Text | SOC % | "SOC %" to show on the main screen, near the battery symbol, the value of SOC in percentage. "Volts" to show the battery voltage and "disable" to show nothing' |
| Reset at voltage / Reset at | 58.5 |
Threshold voltage to reset the SOC watt-hour meter: when powering on the display this value is compared to the battery voltage. If the battery voltage is higher, then the battery is expected to be fully charged and the SOC watt-hour meter is reset, effectively resetting the SOC to 100%.
Tip: To find a suitable value, fully charge the battery and measure the voltage on the display, use a slightly lower value for the threshold voltage. Example: my 52V battery charges up to 58.8 volts, so I set the threshold to 58.5 volts. |
| Battery total Wh / Battery total | 500 |
Set the total capacity in watt-hours your battery has.
Tip: fully charge the battery and then discharge it completely and use the measured value to input here. NOTE that you also need first to setup the correct value of your battery internal resistance as also the low cut-off voltage. Tip: the capacities stated from suppliers are often too high, expect a value of around 80 % - 90 % of stated value. I use 350 Wh for my 386 Wh battery. Tip: roughly calculate the capacity by multiplying the nominal voltage with the nominal ampere hours. Example: a 52 volt, 7 Ah battery has a nominal watt-hour capacity of 364 Wh. |
| Used Wh | 0 |
This value shows the SOC watt-hour meter value. You can change this value if you need, like in the event that the battery was not fully charged and this value is not accurate anymore.
|
| Name | Default value | Description |
| Motor voltage | 48V |
Depending on type of motor, set appropriate value so that FOC calculations are correctly executed. The voltage of the battery does not matter, this value should always be set depending on type of motor. Set "48V" for 48V brushless motor (TSDZ2 52V version has a 48V brushless motor). Set "36V" for 36V brushless motor. Set "exp 48V" or "exp 36V" for the 48 or 36V brushless motor, high cadence mode (this experimental options may not be good for the motor, use at your own risk). |
| Max current | 16 |
The more current the more torque the motor will do (will also put more stress on internal gears like the blue gear and make the motor heat faster). The TSDZ2 firmware limits this value to max of 30 amps and high values are achieved at motor startup / very low speeds. As an example, a value of 8 amps can be used for a kid ebike, to reduce the amount of torque since he is small and light. For an adult, a value of 18 amps can be used. |
| Current ramp | 5 amps per second | Set value after user preference. Higher value corresponds to faster acceleration but also greater forces on the mid drive. Be mindful not to select too fast acceleration. |
| Motor control / Motor ctrl | torque |
If set to "torque", the motor current (torque) will be equal to: measured pedal torque * assist level factor. If set to "power", the motor current will be equal to: measured pedal power * assist level factor (the measured pedal power is equal to: pedal torque * pedal cadence). |
| Min current ADC step | 1 | Min current value (in ADC steps) while pedaling, even if not pressing the pedals. This is nice to keep motor engaged and ready even if rotating pedals with minimal force that it is not even detected by the torque sensor. |
| Field weakening / Field weak | enable |
Field Weakening feature increases motor cadence (up to 120 RPM when possible) but also has power loss of about 25% when Field Weakening is automatically activated (when PWM value is higher than 100). You can learn more about Field Weakening looking on Internet about FOC and Field Weakening. |
Before you enable the "calibration", you MUST calibrate your torque sensor by following this guide: How to calibrate the torque sensor.
How to use: everytime you startup the system, the crank arms need to be vertical (within about 18º which is 1/20th revolution). You can select whether it is the left or right pedal that points to ground in the 'Start pedal ground' field below, based on your preferences. This is because the torque sensor ADC values are different for the right and left pedals as you should have noticed when doing your initial calibration. For the system to know whether to use the value from the right or left table, the system needs to have a starting point from which it can use the crank sensor pulses to count whether it is the right or left pedal that is being pushed.
| Name | Default value | Description |
| Torque s ADC thresho / Torq s thr | 20 | Threshold value for ADC torque sensor, for startup pedaling. This value can be adjusted if user want to rest his feet on the pedals while the bicycle is stopped. |
| Assist w/o pedal rot | disable | Enable to get motor assistance once you press the pedals even without rotating them. Recommended to keep disabled if you do not have brake sensors installed. |
| Coast brake / Coast brak | disabled | Need to be enabled if you have a TSDZ2 coast brake version. |
| Coast brake ADC / Coa bk ADC | 25 | Sensibility of coast brake, in ADC steps to consider brake when pushing pedals backwards. |
| Calibration | disabled | Enable the torque sensor full calibration (enable only after doing the correct calibration by following this guide, then leave enabled: How to calibrate the torque sensor). |
| Torque sensor filter / Torq s fil | 20 | Amount of filtering of the torque sensor signal. 100 is max filtering but also a more delayed motor response. This filter is only applied if torque sensor calibration is enabled. |
| Start pedal ground / Pedal ground | left | For the calibration to work, you need to power on the system while keeping the pedals in the vertical position and without touching them or moving the bicycle. One of the pedals must be near the ground, you can select here your preferred pedal. |
| Left weight 1 / L weight 1 | 0 | Set the first weight value for the left pedal. |
| Left ADC 1 | 304 | Set the first weight value for the left pedal. |
| Left weight x / L weight 1 | x | Set the x weight value for the left pedal. |
| Left ADC x | x | Set the x weight value for the left pedal. |
The firmware applies a motor current (motor torque) based on the pedal human power done by the rider and multiplied by the assist level factor. As an example, if the current assist level factor is 0.153 and the rider pedal human power is 100W, the motor current will be 100 * 0.153 = 15.3 amps.
The default twenty assist levels start at factor 0.005 and each next assist level increase the factor by +33%, which should good for most users. If you still want to customize, follow the next steps to adapt assist level factors for you:
- Calibrate the torque sensor.
- Ride with assist level 0 (motor will be disabled) for some minutes on a flat road and see on the display what is the average value of your pedal human power - my average value is 125 watts.
- As it is advised to not exceed 18 amps of motor current on TSDZ2, let's say I want to have a motor current of 12 amps for my average human power of 125 watts, so, the assist level factor should be 0.144 (divide motor current by human power: 12 / 150 = 0.144).
- You can choose an assist level factor like 0.05 for assist level 0 and increase next one by multiplying 1.33 (each level have +33% motor current from previous one), resulting in the following values: 0.05, 0.07, 0.09, 0.12, 0.16, etc.
| Name | Default value | Description |
| Number of assist levels / Num levels | 20 | Select the desired number of assist levels from a minimum of 1 to a maximum of 20. If you choose for instance 5, only the first 5 levels will be available. |
| Level 1 | 0.005 | The value with which the human pedal power is multiplied to obtain the motor current value. |
| Level X | x | The desired multiplier for assist level X. |
Here you can enable or disable the walk assist function. And also configure the motor duty-cycle in each and every enabled assist level. The defaults should work for most situations.
The walk assist PWM value sets the motor duty-cycle. It is an open loop controller. A PWM value of 30 will set the target duty-cycle to 30. Maximum settable PWM in the walk assist function is limited to a value of 100.
NOTES:
- There are only as many walk assist levels as there are assist levels.
- Carefully test and set appropriate values.
- The function is only active in speeds below 8 km/h or around 5 mph.
| Name | Default value | Description |
| Enable/disable walk assist function | disabled | Enable or disable the walk assist function. |
| Level 1 | 30 | The fixed PWM value applied to the motor. |
| Level X | x | The fixed PWM value applied to the motor. |
WARNING: do not enable/use BOOST feature because it is currently buggy.
Here you can enable, disable and configure the BOOST feature. This feature helps from standstills where you might need greater assistance. It gives more power during a set time and then fades the power back to normal assistance. Configure the function after your own likening and preference.
| Name | Default value | Description |
| Feature | disabled | Enable or disable the startup BOOST function. |
| Active on | startup | Set to startup to enable startup BOOST feature only when startup and bicycle wheel speed is equal to zero or set to enable to enable BOOST feature every time pedal cadence or torque sensor value are zero. |
| Limit to max-power | no | Yes to enable BOOST power limit to the maximum battery power value and no to disable. |
| Duration | 2.0 | Set time limit of BOOST in seconds. |
| Fade | 3.5 | Set time limit to transition of power from BOOST to regular power. |
| Level 1 | 4 | Set the BOOST multiplier corresponding to assist level 1. Tip: See assist levels for more information about multipliers. |
| Level X | - | Set the BOOST multiplier corresponding to assist level X. |
Here you can enable or disable the throttle or the motor temperature protection that will let you push the motor limits. Note that you must first install the motor temperature sensor.
NOTES:
- The throttle and the motor temperature protection can not be active simultaneously. This is because they use the same hardware ports to operate.
- If the motor temperature sensor is installed it is not possible to use the throttle. Do NOT enable throttle if that is the case.
| Name | Default value | Description |
| Feature | disabled |
"disabled" means that neither motor temperature limit function nor throttle is enabled. Set to "temperature" to enable the automatic motor temperature control limit or set to "throttle" to enable the throttle.
NOTE: Do NOT enable the throttle if you have installed the motor temperature sensor. If you have the sensor installed you need to either have the motor temperature limit function enabled or everything disabled. |
| Min limit | 75 | Set the minimum motor temperature at which the power will start to be limited. |
| Max limit | 85 | Set the maximum motor temperature at which the power will be completely blocked, i.e. no motor assistance. Max recommended value is 85 degrees Celsius. |
This feature enables user to limit speed and power when using the bike on public roads (useful in the case the local laws impose such limitations - YOU MUST CHECK YOUR OWN LOCAL LAWS AND COMPLY WITH THEM). It is also possible to disable the throttle function when in Street Mode.
On 860C/850C display you will see the ASSIST label with orange color when street mode is disabled. On SW102, the white lines around battery symbol, battery SOC and wheel speed will disappear when street mode is disabled.
| Name | Default value | Description |
| Feature | disabled | When this feature is disabled, you can not activate if from the main screen. |
| Enable at startup / Enabl stup | no | Determines whether Street mode should be active on system startup. |
| Speed limit / Speed limt | 25 km/h | Set speed limit for when Street Mode is active. The motor will fade out power from -0.5 km/h to +2,0 km/h to prevent overspeeding. |
| Motor power limit / Power limt | 250 W | The power limit in watts when Street Mode is active. |
| Throttle enable / Throt enab | no | Determines if throttle is enabled in Street Mode. |
This configuration let you configure some options of the possible variables shown on the numeric field and on graph.
| Name | Default value | Description |
| Graph auto max min | x | Should graph use an automatic values for max and min or use the following manual values. |
| Graph max | x | Set the graph max value. Will be set up to when a new value on the graph is lower than this value. |
| Graph min | x | Set the graph min value. Will be set up to when a new value on the graph is higher than this value. |
| Thresholds | x |
Thresholds will make the graph or numeric field values fade to yellow or red color, depending on the variable value. For instance, as soon motor speed start to approach near his max value, the color will fade first to yellow and then to red. You can disable, set to manual or automatic the thresholds. |
| Max threshold | x | Set the value for manual max threshold, for red color. |
| Min threshold | x | Set the value for manual max threshold, for yellow color. |
| Name | Default value | Description |
| Cadence fast stop / Cadenc stp | enable | Enable for regular bicycles and disable for some full suspension bicycles, if you feel the motor stops while you are pedaling. |
| ADC lights offset / ADC lights | 1 | Amount of ADC steps of battery current - this value should help to avoid motor lack of power when lights are enabled and connected. |
| Virtual throttle step / V thr step | 10 | Amount steps for each increase and decrease of Virtual throttle. |
| Odometer | 0 | This field shows current odometer value. You can also edit the value, like set to 0 to reset the odometer. |
| Name | Default value | Description |
| Clock hours (850C only) | 0 | See current hour value or set a different value. |
| Clock minutes (850C only) | 0 | See current minutes value or set a different value. |
| Brightness on (850C only) | 100% | Set display back light brightness when lights are on. |
| Brightness off (850C only) | 30% | Set display back light brightness when lights are off. |
| Auto power off | 15m |
Set the amount of minutes for the display automatic power off. The auto power off timer counter is reset when wheel speed or battery current higher than 0, or, if brakes or buttons are active. |
| Units | SI | Set units to SI or Imperial. |
| LCD type (850C only) | x | This is read only and is the LCD type on the display and is relevant for developers. Actual options are ILI9481, ST7796 and unknown. |
| Reset BLE connections / Reset BLE | no | Set to yes to reset current Bluetooth pairing. Reset the system after reset the BLE connection. |
| Reset to defaults | no | Set yes to reset all the configurations to default values. |
Here you can see the values of some variables of the system. This can help debug issues on TSDZ2 or help you understand how the system works.
| Name | Default value | Description |
| ADC throttle sensor | x | Current value of the input signal from throttle, from 0 to 255. |
| Throttle sensor | x | Current value of the input signal from throttle, without offset, from 0 to 255. |
| ADC torque sensor | x | Current value of the input signal from torque sensor, from 0 to 1023. |
| Pedal side | x | Current side of the pedal the firmware considers. This value depends on correct calibration at startup of the system: the pedals need to be vertical pointing to ground. You can select on Configurations to be left or right pedal to point to ground at startup, based on your preferences. This is needed to the system can know in which pedal are you doing the force with your legs, since the weight is measured differently on each pedal due to the torque sensor. |
| Weight with offset | x | Weight on the pedals and this value can have an offset representing a no zero value at startup when there are zero weight on pedals. |
| Weight without offset | x | Same as previous but with offset removed. |
| Pedal cadence | x | |
| PWM duty-cycle | x | This values can fluctuate between 0 and 100 max. Where 0 means 0 battery voltage applied to motor coils while 100 means max battery voltage applied. When this value hits the max of 100, means that motor max power possible is being applied. |
| Motor speed | x | In ERPS (electric rotation per second) units. The motor has 8 pair of magnets inside, meaning each 1 ERPs equal to one RPS (rotation per second). |
| Motor FOC | x | Angle calculated by FOC algorithm, between 0 and 30. Higher motor phase current and/or higher motor speed, makes this value increase. |
| Hall sensors | x | Current value of the motor hall sensor. You can rotate very slow the bicycle wheel back backwards to see this value changing and it must always follow the next same sequence and values must be only the next ones: 4, 6, 2, 3, 1, 5. |