OS X and Linux installation

You have to buy a STLink-V2 or clone, to flash the firmware to the motor. See the main wiki page on how to wire the STLink to the motor connector. Keep the wires from the STLink V2 to the 6-pin male connector (speed sensor) as short as possible. If you need a longer distance from your computer to the bike, use an USB extension cable (it can be very very long).

A few steps are required to set up the software on a Unix computer with some differences between OS/X and Linux. But they should also be feasible for inexperienced computer users :-).

1. Download and unzip the zip file download or, better, clone the Github repository by opening a terminal, moving to some chosen directory and use the git command. Please install git if not already install (with a standard or equivalent Linux command yum install git or OS/X command brew install git) then clone the mbrusa directory of GitHub: $ git clone https://github.com/emmebrusa/TSDZ2-Smart-EBike-1
   this will create a sub-directory TSDZ2-Smart-EBike-1 (add TSDZ2-mbrusa if instead of the default you want to give it the name TSDZ2-mbrusa). You can then do the classical commands $ cd TSDZ2-Smart-EBike-1
$ git remote -v
$ git pull origin master
   to verify that the git sources haven't changed or be informed of the changes since you cloned the mbrusa GitHub.
   Then you will find on this (main) directory the file JavaConfigurator.jar which can be launched with the command:
   $ java -jar JavaConfigurator.jar&
   If the configurator is launched correctly skip the next step which deals with an obsolete version of Java. The ampersand is used to launch the configurator in the background so that you can change to the directory where the sources are stored and compile and flash using the make flash command.

2. The Java Runtime Environment is usually installed on Linux and OS/X but your already installed version might be too old (before Java8) to run the JavaConfigurator.jar and then you must install a more recent JRE version of java. But a better idea is to install the JDK Java Development Kit which includes JRE but will allow you not only to run the configurator but also to rebuild it or customize (translate for example) or downgrade to an ancient version of the configurator. You can choose a recent LTS (for Long Term Service) version of JDK like Java SE 11 (LTS) which will last long.

3. The configurator should look like the scanned screens below. See the parameter configuration guide in the manuals folder. The red texts refer to the use of the GUI configurator.

4. Adjust your personal settings in the GUI and click the Compile & Flash button. You can simply click on the list items on the right to restore former settings. In fact a click on the Compile & Flash button induces three successive steps A, B and C but only the first step A will (fortunately) work on Unixes (Linux and OS/X) because the configurator launches windows batch files and ends in errors. The click will:
   -A- create the config.h file;
   -B- compile the Open Sources version of the TSDZ2 motor (using the config.h file created);
   -C- flash the new firmware to the controller of the motor.

5. In order to pass step B, you need to install the GPL licensed SDCC compiler either using homebrew on OS/X (brew install sdcc) or from the sources on Linux. SDCC (for Small Device C Compiler) is required to compile all ".c" files from the "src/controller" directory and to link the output ".rel" files into a "main.ihx" file. This is the unique file which will be flashed to the motor controller. No need to flash the LCD monitor firmwares (VLCD5, VLCD6, XH18) which are kept untouched (main difference with the Casainho version). You can pass step B manually using the windows makefile named Makefile_windows (the Makefile_Linux from Casainho uses other tools which are hard to find) by typing the commands: $ cd src/controller
$ make -f Makefile_windows If everything works as expected you get the Intel Hexadecimal file main.ihx which has to be flashed in step C.

6. Instead of ST Visual Development which is available only on Windows, install stm8flash. It is currently not available on Homebrew but you can easily install it with the standard procedure (./configure && make && sudo make install).

7. Before sending your new firmware to the TSDZ2 controller, you might be interested in testing your STMLINK-V2 connection and wiring cable with your TSDZ2 motor. The idea is to transfer the original firmware and save it on your hard disk. The battery should be disconnected. On a Terminal window, go to the src/controller directory and type the command:
   $ stm8flash -c stlinkv2 -p stm8s105?6 -r TSDZ2_orig.bin It takes a few seconds to be downloaded from the controller to your hard disk. If it works fine, you can restore the original firmware with the command
   $ stm8flash -c stlinkv2 -p stm8s105?6 -w TSDZ2_orig.bin (a simple -w instead of -r). If you get an error like too many tries, try again.

8. Once you know that the transfer between your computer and the motor controller is working, you can now pass the final step C. Just uncomment the flash step in the file Makefile_windows and type either:
   $ make flash
   or
   $ stm8flash -c stlinkv2 -p stm8s105?6 -w main.ihx and it will flash the new main.ihx
> Determine FLASH area > Due to its file extension (or lack thereof), "main.ihx" is considered as INTEL HEX format!
> 29380 bytes at 0x8000... OK
> Bytes written: 29380

The advantage of the configurator is that you can simply click on the list items on the right to restore former settings and get the corresponding config.h file which is included by the main.c file and compiled and linked into the firmware file main.ihx.

9. Optional for brave people who want to add more features themselves, the development is done under a special version of Eclipse, see Casainho development site. You also need to install OpenOCD software to debug.

For detailed information read the operation manuals in the manuals folder.

Remark: In an earlier version, the so called Stancecoke wiki, we proposed to mimick the windows version so that the Compile & Flash button will work on Linux and OS/X. It required two additional shell files similar to the windows batch files and a patch to be applied to the java configurator. The advantage was very small in comparison to launching the configurator in the background, setting parameters, one click on Compile & Flash button to create the config.h file and two commands: $ java -jar JavaConfigurator.jar& $ cd src/controller && make -f Makefile_windows flash
This the reason why I suppressed these files.

A big improvement could be to rename Makefile the Makefile_windows and to uncomment the flash step. Also, on order to clean the directory, we must do make -f Makefiles_linux clean.

Forum discussions:
French: Programmation du contrôleur Moteur Tongsheng TSDZ2
German: Software für TSDZ2, SFM--DU-250/350 Mittelmotor-Umbausatz
English: Tsdz2 firmware open source adapted to vlcd5, vlcd6 and xh18
Italian: Forum Indipendente Biciclette Elettriche, Pieghevoli e Utility
Spanish: NUEVO FIRMWARE PARA EL TSDZ2 Y PANTALLAS ORIGINALES, v0.20