OS X and Linux installation

With newer versions of OSF there can be problems compiling with Linux. Fixed by user apolselli. Unable to compile last release (v20.1C.3 8a0872e) on OSX

and improved by user IArchiil. Compile and flash automatically from Linux and Mac OS

Attention release v20.1C.3 8a0872e has been rolled back, use v20.1C.2-update-2.

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 (the photo below could help you). 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. If you don't want to use git, just download, unzip the latest zip file from Github repository and jump to section 2.
   If you don't want to use the command line and revert to an earlier version from the GitHub, you have to click on the Commits button, find the hash, for example latest Stancecoke's commit of version mb.20beta1.A is 17a3649, and click on <> button and from this web page you can download and unzip the tree at this date.
   If you know git or want to learn some git commands open a terminal, move to some chosen directory and read the followings.
   Install git if not already installed (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 command 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.
   The advantage of using git lies in the easy access to the archives:
   $ git config --global alias.hist "log --pretty=format:'%h %ad | %s%d [%an]' --graph --date=short"
$ git hist
* 5d84f76 2020-05-03 | added UI8_ADC_THROTTLE to viewable data [emmebrusa]
* fed1383 2020-05-02 | mb.20beta1.B [emmebrusa]
* 762181c 2020-05-02 | Update README.md [stancecoke]
* 6adbeed 2020-03-27 | Delete config.h [stancecoke]
* 14cb3ce 2020-03-27 | Delete TSDZ2_Configurator.java [stancecoke]
* 2d117d7 2020-03-27 | Delete TSDZ2_Configurator.form [stancecoke]
* 17a3649 2020-03-27 | netbeans project files added [stancecoke]
* 06b74d7 2020-03-25 | fixed typo [stancecoke]
* 9cc7dcd 2020-03-18 | bugfix for temperature sensor [stancecoke]
* 3f816db 2020-03-16 | Fix for assistance without pedaling [stancecoke]
* 2ada949 2020-03-12 | #include "advanced.h" added [stancecoke]
* 2e77e3d 2020-03-12 | Bugfix for overrun [stancecoke]
   And you can see that version mb.20beta1.B started on the 2nd of May 2020. And thus, if you want to revert to the latest version mb.20beta1.A that Stancecoke maintained on GitHub before Mbrusa started using GitHub, you have to checkout version 17a3649:
   $ git checkout 17a3649
   and you can verify that changes after the 27 March disappeared. This Stancecoke's version is very useful for a standard installation because it has very few settings: 36V or 48V motor, VLCD6, VLCD5 or XH18 LCD display, max speed of 25km/h for an European pedelec instead of the default 45, battery capacity which for a 10S4P battery should be 374Wh instead of 630. For standard cells of 3.6V and capacity of 2.6Ah, a so-called 10S4P battery has 10 cells in serial (36V) and the 4 sets in parallel offer a capacity of 10.4Ah (2.6Ah x 4) and a total energy of 10.4Ah X 36V = 374Wh. 630Wh corresponds to a 10S5P with cells of 3.5Ah capacity.
   Then you will find on this (main) directory the file JavaConfigurator.jar which could be launched with the command: $ java -jar JavaConfigurator.jar but if you want to test the latest version, you have to checkout the most recent version with the command:
   $ git checkout master
   and you will be back to the current version mb.20beta1.B. If you can't go back, it means that you modified some files that are not committed yet. Thus, you can make a tag and a branch to save your work:
   $ git tag mb.20beta1.A
   and commit your modified files before being allowed to revert.
   Let us suppose that you configured (see section 2.) from a setting named 20200523-183120CEST.ini a new config.h file and built (and flashed and tested successfully) a new firmware main.ihx that you want to keep in the releases subdirectory. You can do something similar to:
   $ mv src/controller/main.ihx releases/20.1/20200523-183120CEST.ihx
$ mv experimental\ settings/20200523-183120CEST.ini proven\ settings/my_Default_Settings.ini
   and you can move back to the original config.h file settings. Then a git status will warn you that only two files have been created or modified and that you have to add them and commit. It also a good idea to create a branch:
   $ git add proven\ settings/my_Default_Settings.ini
$ git add releases/20.1/20200523-183120CEST.ihx
$ git commit -m "mb.20beta1.A with personal settings"
$ git branch my-mb.20beta1.A
   Checkout to latest version with:
   $ git checkout master
   Again, you can verify with git hist. You can revert to your created branch with $ git checkout my-mb.20beta1.A. As long as the mbrusa GitHub is maintained, you don't need to git clone again, but just update with git pull origin master or revert, even back to Casainho's releases!

2. Let us suppose that you are on a subdirectory which is the top directory of whatever version, unzipped from GitHub or checked out with git. Then try to launch the configurator 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 -f Makefile_windows flash command (after uncommenting the flash step in Makefile_windows).

3. 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.

4. 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.

5. 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 is supposed to process three successive steps Configure, Build and Flash but only the first step Configuration will work on Unixes (Linux and OS/X) because the configurator launches batch files using Windows specific "cmd" orders which end in errors on Unixes: java.io.IOException: Cannot run program "cmd": error=2, No such file or directory
   at java.lang.ProcessBuilder.start(ProcessBuilder.java:1048)
   at java.lang.Runtime.exec(Runtime.java:620)
   at java.lang.Runtime.exec(Runtime.java:450)
   at java.lang.Runtime.exec(Runtime.java:347)
   The first Configure step creates a setting file timestamp.ini in the ./experimental settings/ subdirectoryy, and most importantly, it creates a new configuration file config.h in the src/controller/ subdirectory (the advanced.h subdirectory of version 20beta1.A has been merged back to config.h in version 20beta1.B).
   The Build step is a command launched by the configurator to build the firmware using the file config.h file just created, it is analog (but not identical to make in the src/controller directory);
   The Flash step is also a command launched by the configurator, similar to make flash, to flash the new firmware to the controller of the motor.
   Both Build and Flash steps can be easily done on Linux and OS/X using command lines within the src/controller/ subdirectory instead of by the Java configurator.

6. In order to Build the firmware, 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. The "main.ihx" 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). Once SDCC is installed you can use the makefile named Makefile_windows. Please remark that the Makefile_Linux from Casainho uses other tools (stm8-objcopy and stm8-size) which are hard to find. It also produces an .elf firmware file (--out-fmt-elf) instead of .ihx (--out-fmt-ihx) which is mainly used for debugging purposes. Type the following commands. You should see how each .c file of a library is built, how each .c file of the controller (mainly main.c, ebike_app.c motor.c are compiled, and how at the last end, all .rel files are linked to produce the firmware main.ihx: $ cd src/controller
$ make -f Makefile_windows
sdcc -c -I../common/STM8S_StdPeriph_Lib/inc -I../common -I. -I../ -mstm8 -Ddouble=float --std-c99 --nolospre --out-fmt-ihx --debug -o../common/STM8S_StdPeriph_Lib/src/stm8s_iwdg.c ../common/STM8S_StdPeriph_Lib/src/stm8s_iwdg.c
...
sdcc -c -I../common/STM8S_StdPeriph_Lib/inc -I../common -I. -I../ -mstm8 -Ddouble=float --std-c99 --nolospre --out-fmt-ihx --debug -olights.c lights.c
sdcc -I../common/STM8S_StdPeriph_Lib/inc -I../common -I. -I../ -mstm8 -Ddouble=float --std-c99 --nolospre --out-fmt-ihx --debug main.c ../common/STM8S_StdPeriph_Lib/src/stm8s_iwdg.rel ../common/STM8S_StdPeriph_Lib/src/stm8s_itc.rel ../common/STM8S_StdPeriph_Lib/src/stm8s_clk.rel ../common/STM8S_StdPeriph_Lib/src/stm8s_gpio.rel ../common/STM8S_StdPeriph_Lib/src/stm8s_uart2.rel ../common/STM8S_StdPeriph_Lib/src/stm8s_tim1.rel ../common/STM8S_StdPeriph_Lib/src/stm8s_tim2.rel ../common/STM8S_StdPeriph_Lib/src/stm8s_tim3.rel ../common/STM8S_StdPeriph_Lib/src/stm8s_exti.rel ../common/STM8S_StdPeriph_Lib/src/stm8s_adc1.rel ../common/STM8S_StdPeriph_Lib/src/stm8s_flash.rel ../common/common.rel watchdog.rel torque_sensor.rel uart.rel pwm.rel motor.rel wheel_speed_sensor.rel brake.rel pas.rel adc.rel timers.rel ebike_app.rel eeprom.rel lights.rel

If everything works as expected you get the Intel Hexadecimal file main.ihx which has to be flashed.

7. 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).

8. Before sending your new firmware to the TSDZ2 controller, you might be interested in testing the STMLINK-V2 connection with your TSDZ2 motor. You only need 3 wires connected as on the photo. Added note: Better to use 4 wires, also connecting RST. For example, you can transfer the original firmware and save it on your hard disk. In order to do this backup, 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.

9. Once you know that the transfer between your computer and the motor controller is working, you can now pass the flashing step. Just uncomment the flash step in the file Makefile_windows and type either:
   $ make flash
   or $ make -f Makefile_windows flash if you haven't rename it, or even the more explicit command:
   $ stm8flash -c stlinkv2 -p "stm8s105?6" -w main.ihx
   they all will flash the new main.ihx with a screen output similar to:
   > 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.

10. 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 we 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