BBS-FW: Open Source Firmware for BBSHD/BBS02 Controller

[danielnilsson9]

This open source project is finally ready for release!

This firmware is intended to replace the original Bafang firmware on BBSHD/BBS02 motor controllers and can be flashed using the standard programming cable. Almost all functionality of original firmware has been reimplemented and additional features
have been added.

This firmware is compatible with all displays that works with the original firmware. A custom configuration tool is provided since BafangConfigTool is not compatible due to a different set of supported parameters.

Supported Hardware (v1.1.0)
BBSHD:
Controller revision 1.4 and 1.5:

• STC15W4K56S4 (1.4)
• IAP15W4K61S4 (1.5)

BBS02:
Controllers with any of below MCU:s

• STC15F2K60S2
• IAP15F2K61S2

Do not flash on any other revision/microcontroller without access to the original firmware (for that revision) to restore or you may brick your controller. If you have a bricked controller of an older revision, please proceed and let me know of the outcome.

It is a good idea to have access to the bafang original firmware files in case you want to roll back for any reason.

Download & Install
https://github.com/danielnilsson9/bbs-fw

v.1.0.0

• A bit more power without hardware modifications! (max 32A).
• No upper voltage limit in software, can by default run up to 63V (maximum rating of components).
• Support lower voltage cutoff for use with e.g. 36V battery.
• Smooth Throttle/PAS override.
• Optional separate set of street legal & offroad assist levels which can be toggled by a key combination.
• Support setting road speed limit per assist level.
• Support setting cadence limit per assist level.
• Support cruise assist levels (i.e. motor power without pedal or throttle input).
• Display motor/controller temperature (shown in range field on display).
• Use of speed sensor is optional.

v1.1.0

• Support for BBS02 controller.
• Single firmware binary for all supported BBSHD controller revisions.
• Fix bug where an error was reported when trying to use firmware without throttle connected.
• Support additional motor core temperature sensor available on BBSHD.
• Add option to show current temperature in speed field on display while walk mode is active.
• Support selecting which temperature sensors to use (for controllers with broken sensors).
• Decrease motor power gradually when approaching max temperature (75C).
• Decrease motor power gradually when approaching low voltage cutoff limit.
• Improved shift sensor power interrupt.
• Smoother power decrease when releasing throttle to avoid jerk from motor stopping abruptly.
• Added forwarding for current sense resistor error code.
• Implemented basic voltage based battery percentage calculation (not accurate).

v1.1.1

• Fix wrong status code reported for normal operation to display causing issues with some display models.
• Fix low voltage ramp down not working correctly if LVC was set above 25V.
• Add log print for battery voltage reading.

Limitations (v1.1.1)

• "Keep Current" option available in original firmware not yet implemented.

Since this is an open source firmware alternative the possibilities for future improvements are endless, if you have any suggestions, just let me know.

Configuration Tool
To give you a hint of available options.

 

[john61ct]

Wow!

What a great contribution to the community, Thank You!!

Sorry if an obvious question, is this using true FOC?

thread discussing definition

https://endless-sphere.com/forums/viewtopic.php?t=105139

 

[danielnilsson9]

See here https://github.com/danielnilsson9/bbshd-fw/wiki/NEC-Motor-Control-Protocol

Basically the BBSHD controller has two different microcontrollers where one is only focused on doing BLDC control and the other does everything else. The communicate with each other through a serial line.

This firmware only replace the firmware on the "everything else" controller. The other one cannot be flashed without taking the controller pcb out of the housing and removing some of the potting on the bottom.

It is something that is on my list to investigate if it would be possible to provide an optional firmware for this MCU too, but I have not put much work into it yet. It is sort of a rare MCU and there does not exist a cheap flashing device for uploading software.

This is what I got:

User Manual:
https://github.com/danielnilsson9/bbshd-fw/blob/master/doc/D79F9211-NEC.pdf

Flash Programming Protocol:
https://github.com/danielnilsson9/bbshd-fw/blob/master/doc/78Kx3-pgm.pdf

Development environment that could be used in "evaluation mode" which I believe is enough:
https://www.renesas.com/us/en/document/uid/cs-cacx-v40700?r=488821

Here is a project which seems to be able to dump the flash to extract original firmware:
https://github.com/AndrewGBelcher/78K0R_flash_leaker

It also seems to implement more of the programming protocol and could potentially be used for programming the chip.

Also, I have access to source code for an implementation on FOC on this exakt microcontroller (no idea about the quality) which I found a while ago.

I might give this a shot someday, if I can get a shell project running which works and can be flashed I'm sure there are a lot of folks here on the forum that could help with the BLDC control firmware.

Edit:
Upon further investigation I believe UFD79F9211 has been rebranded to UFD78F1000 by Renesas. The have the exact same architecture, memory map and pin layout. Hopefully the tooling provided by Renesas will produce binaries targeting UFD78F1000 that also works on UFD79F9211.

Edit2:
I have looked at the controller PCB and there are no current sense resistors for any phase phase so we cannot due "true FOC".
The MCU that runs the BLDC control can measure battery current and battery voltage.
This will put us in the same situation as TSDZ2 firmware which implements a simplified form of FOC i believe, based on a motor model and the measured battery voltage and current? Which I guess we could to for the BBSHD/(BBS02 eventually) since is just has to work with two different motors.

I know very little about BLDC/FOC etc at the moment, if I messed something up here, please correct me.

 

[Cybernetica]

This is absolutely fantastic news!

As a BBS02 owner I sent 10$ donation to help you get BBS02 controller.

I encourage everyone who owns BBSXX to do the same whether it's to support BBSHD developent or to speed up the release of BBS02 version.

Thank you!

 

[TenMile]

Can anyone expand on how the "No Display" would work? How would you select PAS levels etc?

 

[Daxxie]

Great work.

Flashed my BBSHD (V1.4 STC15W4K56S4)
Worked!

 

[fechter]

Great work! I'll have to check it out. I sort of hate messing with my BBSHD since it's running nicely now, but it has a couple of the known annoying issues.

 

[SuperSl0w]

This is supurb. Already donated $10 for this guys hard work. This is what the bbshd needs, custom fw!

 

[danielnilsson9]

Can anyone expand on how the "No Display" would work? How would you select PAS levels etc?

You won't. You only have on level, you startup assist level selected when configuring the firmware. You can do the same with the original firmware really. It is mostly useful when running a throttle only setup, but it would also work with the "variable PAS" mode where you set assist level power using the throttle but still have to pedal to receive the power.

On another note, has anyone tried running this firmware with a gear sensor? I the power gap wide enough for smooth shifting or does it need to be tuned for a nicer experience? I don't have a gear sensor and haven't tested that function.

 

[caleb7]

63V support opens door to 15s li-ion batteries without modifications? That should make some happy. With maximum of 32A current enabled, that would be equal to 1700-2000W range. I have no idea about how efficiency would get affected by this though.

By the way I don't see anything about gear sensor in "Limitations", I guess it works.

 

[Bengy22]

Anyone have a photo of what the display would look like with this firmware, maybe even with a bafang 860c? I too have been very happy with my current firmware, even did the shunt mod to 45a (which I assume wouldn't cause any problems with this firmware other than reporting the wrong amps like currently it does) but I do like how this will show the temps. I already put a thermistor on the controller side but having it built into the display would be nice.

 

[IceBandit]

Looks like a great mod. Well done.
I'd love to see a setup that uses a hidden switch to toggle the entire display to show a 250w street legal setup (Australian nanny state law) so that when the cops show up to inspect your setup it deceives them into thinking its all good! ) Slap a 250w sticker on the motor as well. But for normal ops one could revert back to the standard setup.

 

[LewTwo]

Slap a 250w sticker on the motor as well.

My new BBS02B came with four stickers. I could not resist the temptation to put one of them to use ... :lol: :lol: :lol:

 

[IceBandit]

Hehehe... well done. Although I'd have covered up the 750w bit.
Just had an interesting discussion with a bloke here in Perth about the 750w vs. 1000w motors. I am thinking about building a bike with either one or the other, but he reckons the 1kw motor is total overkill for what I wanto do (30km round tripping with heavy bag). Reckons a 500w hub would be better. Not sure myself. Was wondering what the reliability of the 750w BBS02 is like? What is the best battery AH pairing?

 

[LewTwo]

Hehehe... well done. Although I'd have covered up the 750w bit.
Just had an interesting discussion with a bloke here in Perth about the 750w vs. 1000w motors. I am thinking about building a bike with either one or the other, but he reckons the 1kw motor is total overkill for what I wanto do (30km round tripping with heavy bag). Reckons a 500w hub would be better. Not sure myself. Was wondering what the reliability of the 750w BBS02 is like? What is the best battery AH pairing?

A lot of undefined variables involved. Total weight (you, the bike, motor, battery and cargo), speed, terrain, paved roads or dirt track, type/size tires, pedaling or throttle only, etc.

 

[IceBandit]

IceBandit wrote: ↑Aug 08 2022 12:20pm
Hehehe... well done. Although I'd have covered up the 750w bit.
Just had an interesting discussion with a bloke here in Perth about the 750w vs. 1000w motors. I am thinking about building a bike with either one or the other, but he reckons the 1kw motor is total overkill for what I wanto do (30km round tripping with heavy bag). Reckons a 500w hub would be better. Not sure myself. Was wondering what the reliability of the 750w BBS02 is like? What is the best battery AH pairing?
A lot of undefined variables involved. Total weight (you, the bike, motor, battery and cargo), speed, terrain, paved roads or dirt track, type/size tires, pedaling or throttle only, etc.

Yes, indeed. All of the above I'd say. I would like a bike that does the lot - This bloke in the bike store kept downgrading my request saying I don't 'need' that much power. But I like your Mod, I'll be using it.

 

[SuperSl0w]

I saw you changed the version to 1.1.0.. The public release is stil in 1.0. Do we need to compile the new version for ourself, or will there be a downloadable version soon?

Will flash the custom fw again in a few days, forgot to set my Eggrider to "online live data" last time. :lol:

 

[danielnilsson9]

Anyone have a photo of what the display would look like with this firmware, maybe even with a bafang 860c? I too have been very happy with my current firmware, even did the shunt mod to 45a (which I assume wouldn't cause any problems with this firmware other than reporting the wrong amps like currently it does) but I do like how this will show the temps. I already put a thermistor on the controller side but having it built into the display would be nice.

There is no change to how the display looks, this firmware is only for the motor controller not the display. If you display support showing an estimated range, then that field will report the motor temperature instead.

E.g. It may say " RANGE 46km" and that will be the temperature 46C. If you have set imperial units in both the config tool and the display it will says XX miles which will be XX F.

I saw you changed the version to 1.1.0.. The public release is stil in 1.0. Do we need to compile the new version for ourself, or will there be a downloadable version soon?

Will flash the custom fw again in a few days, forgot to set my Eggrider to "online live data" last time. :lol:

1.1.0 is not ready yet and is not recommended to be uses since it has not been tested very much by me yet. 1.0.0 is fine, there are not really any bugs reported. 1.1.0 will only be a minor fix to make some things smoother.

Current changes in 1.1.0
Support current sense error code
Single firmware binary for both controller revisions
Ramp down current when approaching LVC
Ramp down current when approaching temperature limit
Longer and smoother shift sensor interrupt (I hope)

 

[jtekken]

Is this firmware compatible with the Eggrider display? Someone wrote here that it sets live data on Eggrider and then works. The Eggrider application has the same settings as the Bafanf config tool, but not as the settings in your open source firmware software.

 

[Matze_Senpai]

im interested in this bbshd firmware however i have not bought a motor yet so i just got some quick questions ;
if i buy a motor now will the controller be compatible?
also does it matter if i buy 48v version of motor to run with 52v battery?

 

[SkinZ]

Awesome work! I can't wait to give it a go!

 

[danielnilsson9]

Is this firmware compatible with the Eggrider display? Someone wrote here that it sets live data on Eggrider and then works. The Eggrider application has the same settings as the Bafanf config tool, but not as the settings in your open source firmware software.

I'm not sure. It is not compatible with the EggRider mode switching at least which uses the bafang programming protocol to change the parameters. But if you don't use that function of the EggRider I suppose it could work.

im interested in this bbshd firmware however i have not bought a motor yet so i just got some quick questions ;
if i buy a motor now will the controller be compatible?
also does it matter if i buy 48v version of motor to run with 52v battery?

Yes, I have not heard any report of new controller revisions so if you buy a new motor (BBSHD) it will very likely have controller revision 1.5 which is compatible. 48V or 52V will not matter as the only difference lies in the original bafang firmware. With this firmware you can run any voltage up to 63V which is the maximum rating of the components (although maybe not recommended to be right on the limit).

 

[jtekken]

I'm not sure. It is not compatible with the EggRider mode switching at least which uses the bafang programming protocol to change the parameters. But if you don't use that function of the EggRider I suppose it could work.

If you mean switching the road/offroad profile, I use it.
It would be nice if Eggrider would work with your great FW.
I like the FW very much, especially the newly added function of lowering the power before reaching a critical temperature value. I currently have a BBS02 with modified FW to accept 52V batteries. But it is true that temperatures have to be monitored, with your FW it would be easier. Thank you for your hard work!

 

[silenec]

This is great :thumb:

One stock feature I really like is configurable "Keep Current" (%).

What this setting does when set at 60% is ramp the current down to 60% of the PAS level selected based on pedal cadence rpm, so at low pedal cadence you get 100% of the level selected but as your pedal cadence increases the power is reduced down to 60%. As you pedal faster the motor does less work down to whatever this number is set to (60% of max current or 15 amps on 25 Amp system)."

This way you need to change PAS levels less often (hill / lower cadence = more power without pressing any buttons). So convenient that I don't even feel a need for a torque sensor.

Is something like this implemented in BBSHD-FW?

Also do we know how many different controller HW revisions are there for BBSHD and BBS02?

My BBS02 from 2017 says:

Manufacturer: HZXT
Model: SZZ9
Hardware Ver.: V1.1
Firmware Ver.: V2.0.1.1

BBS02 support would be great because the throttle on some revisions does not work together with PAS (and there is no firmware with a fix available like there is for BBSHD) and they overheat easier (is there any way to show motor temperature on C961/C965 displays? maybe it could be sent to the display instead of current speed temporarily with some key combination or while parked / when real speed is 0km/h?) Just an idea.

Lower voltage cutoff would also be perfect for my 12S li-ion battery. Good luck with the development, I am sure many BBSXX owners will be grateful

 

[geofft]

Also do we know how many different controller HW revisions are there for BBSHD and BBS02?

My BBS02 from 2017 says:
Manufacturer: HZXT
Model: SZZ9
Hardware Ver.: V1.1
Firmware Ver.: V2.0.1.1

....just to add to this data, I've got a very early BBS02 (c.2016 at a guess), this has the following hardware/firmware data:-

Hardware Ver: V1.1
Firmware Ver: V1.0.0.1

...so basically just the same hardware with an earlier fw version. This is the firmware version that sometimes gave an irritating 'pulsing/stuttering' feel to the drive at lower motor rpm's.