Protocol specs for Bafang/TSDZx firmwares

[badsheepy]

Hi Guys, I've been developing an android based display app for bafang and tsdz* motors (and more if possible). I've found it fairly difficult to get detailed data on both the factory and OSF versions of each firmware (obviously the OSF is easier to reverse engineer).

I've added my current findings to the attached ZIP file (I lost my phone during traveling so I can't 2fa login to github for the next week or so), I will update when I can upload the repo properly.

Anyhow, If anyone has any more concrete specs, I'd be grateful for a link/info/anything whatsoever. Especially for bafang factory protocol (I assume we have this mostly correct, bafang support seems to work 100%), TSDZ8 factory protocol, (also seems to work 100% but I'm sure I have some fields mislabeled) and TSDZ* OSF protocols (the latter just because it's quite a terrifying protocol to implement with so many variables) I'd like to make my TSD OSF support require as little config as possible, while still allowing for overrides for advanced users.

I have a pretty simple Serial -> BT LE interface using an NRF52840 board (with several target boards, but it should be trivial to add others) here:
GitHub - speedysheep/nrfProxy: Proxy serial UART to bluetooth LE for BafflingVision display.

Note: There's another app that does this exact thing. My app is unrelated to it, shares no code with it, and I'm pretty sure that project was abandoned. But it's a great idea. Although if anyone has a better idea of how to get 3.3v from a potentially 100v supply, I'd be eternally grateful, as I haven't come across a single solution that doesn't require me to make a PCB at this point. I'm currently just going to avoid this and power it via a rechargable li-on battery until I resolve that.

My display app is currently not open sourced as it's both in active development and I'm not sure where I'm heading with it.

But I've added a screenshotso you guys can get an idea of what is happening. (both the dashboard and the widgets are user definable, you pick what you need. You can have multiple dashboard screens, for e.g. if you wanted real-time data as well as graphs of how you performed over a ride. Google maps support works both full screen (as a live background image) or as a widget (as shown here). Widget list is too large to list, but also trivial to add to.

Heart beat monitor support over bluetooth is working. I'm unsure if there's value in other bike sensors, but feedback would be welcome.

Anyhow, any protocol docs would be helpful. And any unsupported motors with a serial UART connection with a documented protocol would be interesting to hear about also.

The app is currently working 100% (as far as I can tell) across TSDZ8 and Bafang motors, with just a few tidying up issues to resolve. OSF is taking significantly longer as I'm attempting to make it less difficult to set up for a newbie, which requires a surprising amount of logic.

I'll be releasing the app to testers as soon as I have clarified the protocol issues. Which is why I'm delayed by the OSF firmware, as OSF guys are much more likely to be tolerant of bugs and other issues

Anyhow, to sum up, if anyone has any more detailed protocol info for Bafang, Tongsheng (OSF or other) or any other serial UART motor I'd be grateful to hear from you. I'm hoping to eventually support CAN-BUS although I haven't yet seen how practical that might be.

Thanks,
badshepy.

 

[badsheepy]

Also note that with both widgets and background maps, widgets can be placed over them, so you can tell your speed, wattage, etc while looking at the map, and a simple scroll to the left or right can bring up an additional (optional) screen with more details. Each dashboard has 1 or more displays it can scroll between. Also note this is in heavy development, so if you have any requests, please let me know and I can judge the practicality of implementation

 

[stancecoke]

I have a pretty simple Serial -> BT LE interface using an NRF52840 board

So you will need additional hardware?! Lishui used to offer professional BT-Modules for Bafang and Lishui/Kunteng UART systems that can be plugged between the controller and the display simply. It has a standard HM-10 BLE module internally and can switch on/off the system by BT.



you can find some more common UART protocols on the EBiCS repository:

EBiCS_Firmware/Src at master · EBiCS/EBiCS_Firmware

Free FOC firmware for Lishui E-Bike-Controllers. Contribute to EBiCS/EBiCS_Firmware development by creating an account on GitHub.

github.com

Kunteng: Old, but still popular in the DIY communitiy (They offer their own BT Module also)
5s: Many display manufacturers use it, Kingmeter, KeyDisplay, several cheap no name offers also, used by Lishui and JYT controllers
No2: more and more the "standard" protocol for very cheap China hardware like Brainpower with S886 S866, .... displays
J-LCD: Old Kingmeter protocol, rarely used in these days.

I guess, without a detailed tutorial, how to set up the BT-Module and a precomiled apk file, you wont find a user of your interesting project...

 

[badsheepy]

So you will need additional hardware?! Lishui used to offer professional BT-Modules for Bafang and Lishui/Kunteng UART systems that can be plugged between the controller and the display simply. It has a standard HM-10 BLE module internally and can switch on/off the system by BT.
View attachment 391180

you can find some more common UART protocols on the EBiCS repository:
Kunteng: Old, but still popular in the DIY communitiy (They offer their own BT Module also)
5s: Many display manufacturers use it, Kingmeter, KeyDisplay, several cheap no name offers also, used by Lishui and JYT controllers
No2: more and more the "standard" protocol for very cheap China hardware like Brainpower with S886 S866, .... displays
J-LCD: Old KIngmeter protocol, rarely used in these days.

I guess, without a detailed tutorial, how to set up the BT-Module and a precomiled apk file, you want find a user of your interesting project...

Awesome, That's a neat little gadget there!

The only actual additional hardware I need is a 5v or 3/3v supply, I'm just not very good at electronics so I was leaving that to the end. But that little device seems to do most of the uart -> bt bridging I would like to do and must be able to step down the voltage significantly to do so, So I'll take a look at that, and at least try and work out how they did it in a small package.

BT lock/unlock is an excellent bit of functionality but one of my major reasons for implementing this as-is is to remove the requirement for having a display connected at all, as a phone USB serial port is not very reliable when bouncing up and down

I'm not sure how USEFUL only having BT-LE for the display would turn out to be given brakes etc would also need to be wired in as they are currently, but I originally only intended for this to work over USB serial, the BT bridge just seemed to be a very neat solution to some other issues I had, and when it's present it makes using it for security almost a freebie add on.

I'd particularly like to be able to configure the TSD OSF with a nicer interface (because obviously I can make a phone interface a lot more detailed than the OSF display just purely due to display size/fidelity.

Once I have the protocol confirmed a bit more I'll release an alpha version of the display app (it's currently entirely functional on factory TSDZ8 and Bafang motors).

Thank you very much for the reply stancecoke! Several of your other replies on this forum have been incredibly useful

 

[stancecoke]

So I'll take a look at that, and at least try and work out how they did it in a small package.

It's quite easy to do with standard components, see here:

https://www.pedelecforum.de/forum/index.php?threads/nachbau-lishui-bluetooth-modul.45072/

 

[badsheepy]

It's quite easy to do with standard components, see here:

https://www.pedelecforum.de/forum/index.php?threads/nachbau-lishui-bluetooth-modul.45072/

That is incredibly useful thank you, I could get lists of parts I needed but I've been worried about the huge step down from ~100v (which is unnecessarily high of course) down to the board voltage of 5/3.3v. This is more helpful thank you could imagine!

Thanks again Stancecoke! Hopefully you'll be interested in my app so I can pay some of this forward

 

[stancecoke]

There is the Kunteng module also, but as far as I remember, it has no possibility to switch on/off the system

KT-BLE module bluetooth for KT controllers

A device that allows you to connect the display of a KT electric bike with a smartphone.

nexun.pl

 

[badsheepy]

There is the Kunteng module also, but as far as I remember, it has no possibility to switch on/off the system

KT-BLE module bluetooth for KT controllers

A device that allows you to connect the display of a KT electric bike with a smartphone.

nexun.pl

Turning it on/off isn't a big issue for me, I have full programmatic control of the GPIO pins on the nrf52840, so that bit just needs a relay added to it. My main issue was just that I had no idea how to get from a fully charged battery voltage down to the 3.3/5v (board accepts both) from a vastly higher voltage ebike battery. But I think your first few links have resolved that for me. And if not, this board can run for weeks on a button cell battery until I figure something out

However that is much more like my current solution, essentially I'm using the nrf52840 as a serial -> BT LE bridge.
The triggering on/off will be done by sending a specific command to the board from the phone app.

The actual purpose f the board isn't to enable/disable things though, that's just a nice side effect. All it currently does at the moment is: on first connection, (or when reset by restarting while holding a reset button) it permanently pairs the phone and the board. As the connection is encrypted and authenticated, we can use it to trigger the relay to enable/disable the controller.

When a connection is established, all serial UART gets rerouted via BT-LE to the phone app, and vice versa. It's protocol agnostic (and will hopefully remain so if all the on/off functionality works roughly the same.

The reason I chose the nrf52840 board is I found them for $1.11 on aliExpress (unfortunately before tariffs and import fees went crazy) and they're well documented.

As mentioned the code is in the repo above (but only if you happen to be curious, there's nothing clever going on at all there).

None of the above is actually an issue right now though, my main problem is there's just so many fields in the protocols that it's difficult to be entirely confident what each one does, and I think a lot of the documentation might be out of date (for example, one of the "torque" fields on my factory tsdz8 goes up linearly with throttle use, on a motor with absolutely no crank arms connected, so I'm unsure if this is just minor measurement issues or actually an amps/watts value, which is what it most resembles. But I also discovered an entirely undocumented (to me) packet while analyzing that issue.

I don't mind reverse engineering these values myself, but half the time I've made what I thought was a breakthrough, I've found that when I know what to look for, someone else on this forum found the same thing two years ago!

Again, thanks for your help Stancecoke. At a minimum, I'm definitely going to look into support for those other motor types. My phone app abstracts the motor communication entirely away from the display so adding new motors is fairly trivial when their protocol and capabilities are well known.

 

[stancecoke]

The reason I chose the nrf52840 board is I found them for $1.11 on aliExpress

Hm, the board has to be flashed by the user. My experience: that will put off a lot of potential users. A HM-10 BLE module has just to be plugged in, the app takes care of the rest....
It has digital and analogue IOs also, that can be served by AT commands from the app. So you can switch lights or the whole system or read break or throttle signals.
But of course, this sensor reading capability doesn't help, if the current setpoint is not sent via UART with the chosen protocol.

 

[badsheepy]

Hm, the board has to be flashed by the user. My experience: that will put off a lot of potential users. A HM-10 BLE module has just to be plugged in, the app takes care of the rest....
It has digital and analogue IOs also, that can be served by AT commands from the app. So you can switch lights or the whole system or read break or throttle signals.
But of course, this sensor reading capability doesn't help, if the current setpoint is not sent via UART with the chosen protocol.

Hi Stancecoke, Thanks again for all these incredibly useful replies

The board is actually flashable by just plugging it in via USB and hitting "flash" in the nrf connect app. I would be very happy to ship out pre-programmed board, but I'd like to replace the bootloader on it (which would require pre-flashing anyhow).

How does an HM-10 need to be configured? it is entirely configured by an app?

The nrf-52840 is however trivially easy to flash (the cheap board you just put in bootloader mode, load NRF connect, and then flash the hex) or depending on the board flashing can be done entirely by copying the fimware to the mounted flash partition. There's also a whole selection of these boards at different price points.

I can also replace the bootloader to allow for on-the wire bootloading. This would require pre-flashing (but again I'd be willing to do that mysef, and if you're planning to solder one of these flashing is the least of your problem.

This is just a proof of concept at the moment. But also if I add brakes/lights/etc I could easily control these functions also, they'd just need wiring into the same harness that already has those sockets. And it worries me to have a third party interrupt the brake signals for safety reasons.

My goal here is not to provide a 1:1 replacement for an actual 1T4 (or other) cable, it's to make my app work reliably while adding BT enable/disable functionality. All of that is 90-100% complete.

I've purposely not bothered adding braking, throttle, or other such pins as it'd make the actual BT part require a whole load of already existing ports (I have quite a few GPIO and ADC ports available, I'm purposely not doing this yet)

If it seems like an essential property these are all trivially add-able, but I don't see real value in connecting the brakes up separately just yet (this might change drastically when I come to implement hardware assist level)..

These have all been excellent questions, thanks! If you want access to my private github repo (even if I can't currently give you permissions due to my 2fa disaster, please let me know if you wanto access to the Android source so you can get a better idea of the plan here (but also I won't be offended if not! it's a lot of code for a thing I assume you're not incredibly interested in outside of helping out, which I'm incredibly grateful for).

I'm pretty sure this makes no difference to you, but you were already on my "about" screen due to your numerous various other solutions (also unfinished, I have many more people to thank for this project);

In general, the nrf-52840 is the least important part of this project at present. I wanted a nicer Ebike display, one which didn't charge a subscription for maps. Switching that board in/out is fairly trivial, but it's a good board, supports NFC if required, uses absolutely minimal battery power, and also allows for BT-LE triggered firmware updates (as mentioned, this requires a flash of a bootloader, but I'm not planning on producing these enough to make the 30 seconds per-device flashing be an issue)

So ignoring the nrf board, the APP functioanlity includes: Custom dashboards, with multiple pages (i.e. you can have a real-time speed/cadence/distance page vs a speed/cadence/battery etc over time, via a quick scroll. I've added some screenshots, but none of these will be ideal as the real idea is you customize it for your actuall needs. For example I have my dog as a background on one dashboard, and google maps on another one, with speed, cadence, and torque values superimposed on the map. I can also (perhaps not strictly legally so I haven't implemented this) duplicate ANY other bafang/tsd display as it's just plugging in a few widgets.

I've attached a few screenshots so you can get an idea, and also an APK for wider view. But do please be aware it's under constant development at the moment so e.g. selecting an unsupported motor type works, but will not actually function correctly. (Bafang and TSDZ8/TSDZ2 might well work perfectly already, as well as bafang assist level settings.

Anyhow, thanks yet again for some great feedback, you've given me some things to think about (unrelated to protocols entirely!)

If you (or anyone) is interested (and feel free to be completely non-interested!), attached are some app screenshots as I'm not sure I'd trust a random internet person sending me an APK Note the UX is very customizable (from colours, to backgrounds, so original widgets showing borders or labels etc, so all the examples are likely ugly but should give an idea of the functionality I'm trying to achieve (note that all the values are zero because a motor isn't actualy installed, so there's no data to report).

 

[stancecoke]

and also an APK for wider view.

Hm, I'm getting an error message, trying to install the APK
I'm on Android 13.

 

[maglo18]

Were you planning to add integration with Garmin Ant+? It's missing from most displays. Your NRF probably supports this protocol.

 

[badsheepy]

I took a little more of a look at the HM-10 BLE as it sounds interesting, But I can't see how you could get a

Were you planning to add integration with Garmin Ant+? It's missing from most displays. Your NRF probably supports this protocol.

ANT+ is absolutely supported by nrf-52840 boards. I haven't looked into it that much however as I don't own any. But it should be trivial to add, and trivial to send the data to the phone app. It's one of the reasons I looked into this board specifically.

 

[badsheepy]

Hm, I'm getting an error message, trying to install the APK

I'll take a look at this today, I only have this set up via android studio/adb/my phone in debug mode and I've never released an APK before now. It's probable I likely just need to provide a production build.

As mentioned, I lost my main phone while traveling this week (and heathrow lost and found is incredibly slow), so I'll see what I can do to get this functional on a stock android phone.

 

[badsheepy]

Added a signed, hopefully working on different phones, APK

 

[maglo18]

I took a little more of a look at the HM-10 BLE as it sounds interesting, But I can't see how you could get a

ANT+ is absolutely supported by nrf-52840 boards. I haven't looked into it that much however as I don't own any. But it should be trivial to add, and trivial to send the data to the phone app. It's one of the reasons I looked into this board specifically.

It's about connecting Garmin devices like a watch or computer and sending data directly to the ongoing training.

Getting Started — ANT for nRF Connect SDK documentation

ant-nrfconnect.github.io

 

[stancecoke]

Added a signed, hopefully working on different phones, APK

Still can't install it. Have you set the minSdk value to an older Android version?
For me we need Android 13 at least.

 

[badsheepy]

Still can't install it. Have you set the minSdk value to an older Android version?
For me we need Android 13 at least.

I have:
minSdk = 34
targetSdk = 37
(34 was required for some SDK functionality!)

As mentioned, I have some phone issues at the moment (My usual phone is lost in Heathrow right now)

Can you compile an android app? I can zip up the source files if you're interested, I'm just unable to change any github settings due to 2fa

 

[badsheepy]

It's about connecting Garmin devices like a watch or computer and sending data directly to the ongoing training.

Getting Started — ANT for nRF Connect SDK documentation

ant-nrfconnect.github.io

The nrf-52840 absolutely supports ANT+ so it should work, I just haven't updated the code to send extra packets based on extra data. But I have some functions/methods which intercept the IO so it should be very simple to add. I don't have any Garmin devices (except for a watch that provides for BT heartrate count, which is implemented) so I was planning to add that eventually. It's nice to know this is requested functionality though, I'll put a bit more work into it once I have the protocols locked down.

Thanks
Badsheepy

 

[stancecoke]

minSdk = 34

This means Android 14. So it can't be installed on my Android 13 phone...
For Android 13 you have to set minSdk to 33.

 

[badsheepy]

This means Android 14. So it can't be installed on my Android 13 phone...
For Android 13 you have to set minSdk to 33.

I'll see what I can do to work around this restriction. I wanted to target as low an SDK as possible, but I needed some v34 functionality (for reasons I don't recall). I will update this thread when I have a solution.

I'm kind of surprised you can't install on an older phone TBH, my dev phone is a pixel 5 (but google is good at intrusive updates if nothing else)

Anyhow, thanks for checking, and thanks for pointing me in the correct direction!