UPDATED MAY 2021
Please note I have tried to update this article to reflect all the options available in May 2021 and so some of my previous comments back in 2020 are out of date. I have tried to explain this in the update notes
If you have seen any of my other blog articles on the TSDZ2 Mid drive motor you will know that I have been testing this motor with multiple different firmware’s over the last year or so. I have linked through to the open source GitHub pages for this, but as time has moved on its maybe not quiet as clear as it once was as to the options available for this motor. So In this post I wanted to summarise the different paths you can now take when changing the firmware on your own TSDZ2 motor.
So Lets start at the beginning and talk about what tools you will need to make any firmware changes to your Motor..
In order to upgrade the firmware on your TSDZ2 motor you will first need to either purchase or build your own programming cable.
Unfortunately I have not yet found a UK or indeed european seller of the cables but you can find some worldwide sellers such as eco-bike.com and electrifybike.com however these are based in the US and as such once you add delivery you are looking at around $50 for the cable.
Its clear from the sellers above that these are exactly the same cable you can make yourself if you are confident with a soldering iron and testing the pinout of cables.
Here is my cable and pinout diagram..
( I purchased a tsdz2 speed sensor extension cable to cut off the 6 pin plug)
TIP:- make the cable as short as posible as you can have issues with volt drop anything longer! and then to connect to your PC/ laptop use a standard USB extension cable.
As you can see you will need a ST-Link v2 USB programmer these are easy to come by on ebay or AliExpress for about £4, but word of warning the pinouts are not all the same so check the image carefully! I have a second unit that even when wired correctly to its labelled pinout will not work, so maybe stick to those that show the same pinout as the above example?
All in you should be able to make your own cable for under £15 if you have some heat shrink to hand.
With the exception of the Original screen open source firmware ( we will come onto that later) all of the programming of the TSDZ2 is done using one tool from ST labs called st visual programmer STVP-STM32 (email registration is needed and link sent to email address – no cost)
After downloading and installing the software and drivers the first thing you will be prompted to do is choose the ST chip you wish to communicate with. so select the following options when prompted.
Once done you should be presented with the main screen
If all has gone well you should now be able to click on the Read -> All tabs menu to read the current configuration of your tsdz2 motor.
There are 3 tabs of data memory, ‘Program Memory ‘, ‘Data Memory’ and ‘Option Bytes’. if the read has been successful you should now see these areas full of data. I would recommend at this stage you save each tab to a file using the File -> Save option so you have a copy of your motors stock firmware should you ever what to revert it to how it was.
So for example you select the program tab, and save that at ‘my-stock-firmware-program-tab.hex ( choose the intel hex format) then choose the data tab and save that tab as my-stock-firmware-data-tab.hex, and the same for the option tab.
You can now start playing with the different firmware options….
Stock Firmware upgrades
So this blog post is all about upgrading the firmware to the new opensource variants isn’t it?
Well yes that’s to come but before the opensource firmwares were developed one of the fist things that was discovered with the TSDZ2 was that many of the different variants of the motor that were sold as 250w,350w,500w and even 750w were the exact same hardware but used slightly different firmware. In fact in many case the difference is one or two bytes changed that record the voltage and current the motor uses.
So in many cases customers who purchased a ‘250w’ motor could simply install the firmware for a 500w motor and unlock the intended power of the motor.
So if you are looking to simply unlock your motor and keep the original screen and use a stock firmware this is the simplest option for you.
A full list of fantastic instructions and a link to the original stock firmware files look here on eco-ebike.com
please note they also cover the stlink cable and software, they use the original stlink v2 device which works in the same way but looks somewhat different to the clones you will find online like the one above)
Bring on the Open Source Firmware!
Ok you have got this far, and maybe you like me have experimented with upgrading your firmware to the unrestricted stock firmware but now you want to see what the opensource community has to offer. what do you need to know?
well first think to ask yourself is are you happy to change the screen and potentially cut up and re-solder some cables to mate a new screen with the motor?
If you are against this level of hacking then a safe option is to try out the custom firmware threat developed by the user emmebrusa that is specifically designed to work with the original TongSheng screens like the VLCD5,VLCD6 and xh18. This will only require you to reprogram the motor using the stvp-tool above, but no other physical changes to the cable.
Stock screen firmware fork by emmebrusa
So a little out of order as this version of the opensource firmware is indeed a fork of the original work done by Casainho, but I wanted to mention it first as its most likely to appeal to people who are looking to try out custom firmware on there own TSDZ2 for the first time.
For all the information on how to use this firmware take a look at the wiki here.
This firmware uses a specially developed Java tool that allows you to choose all the settings you require to compile a special pre-configured firmware for your motor and screen. This is needed as the original screen is not reprogrammed and so only basic settings can be made using it.
I have been testing this fork for a while now and I have to say for a simple upgrade its very good. You don’t get all the extra information the larger screens provide, but using the windows java tool is really easy and quick to make changes save profiles and upload to the motor. So if you are looking at switching over from the stock firmware and are not quite ready to make new cables and buy new screens this is an excellent first step!
The 4 modes available currently are…
POWER ASSIST assistance proportional to the power (Torque x Cadence) on the pedals.
TORQUE ASSIST assistance proportional to the torque on the pedals.
CADENCE ASSIST assistance subordinated to the movement of the pedals.
EMTB ASSIST assistance with progressive percentage of the torque on the pedals.
It can take a little while to get the software setup but if you follow the guide its all explained and there is plenty of help on the forum.
You can find the Endless Sphere forum that covers all of this firmware development here
And if you want to take a look at the code repository it is available here
I have to admit I have not used emmebrusa build for some time and it has developed hugely since I did last test it, so I think it offers some great features for those people who don’t want to change any cables and screens etc and want a quick way to revert back to stock firmware if needed. A great option for all tsdz2 owners on stock firmware!
Update May 2021 (My personal favorite option)
emmebrusa has taken this development fork further and merged his code with the ‘Casainho’ source code (see below)
This now brings all of his features to the new displays 850C/860C and SW102 and even the old KT-LCD3 screen. This is fantastic as it now means there is one development fork that is an option for stock and replacement screens. I have been testing this build and it is currently my favorite yet as it has all of the mode options and flexibility as well as options for stock or modified hardware.
For more information on all of emmebrusa firmware options have a look here
If you are running a 850C or 860C of SW102 screen I would recommend this path. However for consistency I want to still include the Casainho firmware below as it is also an excellent option and as the original developer I want to support his hard work….
OpenSource-Ebike-firmware / Colour_LCD by Casainho
This is the original and still current opensource Firmware developed by Casainho but integrating many features and ideas from other contributors, it has developed significantly since it was first created.
Originally the development focused on the use of the KT LCD3 screen which worked very well but had a fundamental issue in that it only had a small amount of memory which meant that some features could simply not be added to it without removing other features. There were some very clever hacks developed to make best use of the memory to get around this limitation as much as possible but ultimately the decision was made to start developing the firmware around screens that offered much more programming space and the new features would work on. So in the current form only the following screens are supported.
Bafang 850C, 860C and the sw102.
So if you wish to use the very latest and greatest version of the Opensource software, you will need to purchase and wire up one of these screens to use it.
Its also worth understanding that in order to use the screen it also needs to have customer firmware installed and this has its own software and installation paths.
Note the sw102 screen is initially tricky to write firmware too as it needs to be physically opened to gain access to the programming pins.
The initial hard wired programming steps are here
Once programmed you can seal it up again and from then on upgrade over Bluetooth! which is great.
I have opened 4 units to date and have a technique that works for me but its not as easy to open as the KT-LCD3 and the Bafang 850/860C screens can now be programmed with the correct hardware without opening at all.
The Main Wiki that covers all instructions on installation and features is here
Latest built firmware for upload is available here
The Endless Sphere Forum for all discusions on this current firmware is here
You will find mentions of the older firmware’s that did support the KT-LCD3 screen within the forum and in some of the setup guides, this is no longer valid for the current builds but still very useful for those that are interesting in using this screen and are happy not to be using the very latest version.
So why would you want to still use the KT-LCD3 screen or indeed any of the older Firmware versions?
Update may 2021 Please note the following information is now out of date and much of this work has been merged into the emmebrusa fork mentioned above, I have left this here as I think it is still useful for anyone who has a KT-LCD3 screen
Ok, the simple answer is if you are new to the opensource firmware then either of the options above would be ideal.
As by now i’m sure you are aware that in the charity we use the tsdz2 for a few adapted bikes and each of these has its own special requirements. Back end of 2019, we were working with the then beta version 19 of the firmware that was primarily being built by a user called Buba, and at the time he did some fantastic experimental work on different power modes for the TSDZ2. so you could choose to power the motor in either in toque only mode, cadence only mode or the traditional power mode ( mixture of cadence and torque). For one of our specific riders who rides with a prosthetic leg, the cadence only mode was an ideal solution that fixed the hunting the motor would experience in any torque based modes having these options was a great feature for us.
Luckily this fork was still kept and there is now a dedicated page for instructions here
The last release that supported the KT-LCD3 was v0.20.0-beta. 1
I ran this release for several months on my own bike without issue and its what’s running on ‘Bob’ the adapted trike, so this was the firmware I personally recommend for the most flexible options for power delivery
Buba also added a cool light feature that would link into the e-brakes to change from flashing to solid when braking! (now included in the emmebrusa ubild as well)
Its also supports the awesome eMTB Assist mode, which is a blast for tricky climbing and general mountain bike tracks (very responsive)
Hopefully that helps new comers navigate the current (May 2021) options for adding opensource firmware to your TSDZ2. I’m sure there will be future developments, and I will try to add those as they happen, but feel free to add comments if you think I have missed any areas. I did not want to replicate the information that is already out there too much but rather give a overall navigation to the relevant webpages.