Home Automation

Almost bricking BK7231N modules

So, I was given bad/outdated advice and I was spreading it to future me and anyone else that stumbles across these blog posts. I’m use to dealing with Amtel and ESP microcontrollers, and familiar with the tools needed for them. When I started working with the BK7231N, I had read that the hid_download_py tool was the only reliable way to flash the BK7231N in MacOS from the terminal. I was able to successfully make use of this tool to flash the OpenBeken firmware, however when I tried to flash ESPHome or esphome-kickstart, not only was I unable to get it to burn without failing CRC check, the module would no longer boot unless I flashed the OpenBeken firmware again.

I had gone on the hunt for better tooling, and found a few new options:

I tried to use ltchiptool to flash the modules I suspeced of being bricked and got no love. The firmware would write, but it would ALWAYS fail CRC check and wouldn’t boot. I tried the BK7231GUIFlashTool, which worked and passed CRC check, and suddenly things were booting again, yet as soon as I used hid_download_py, it was broken again. Initially, this was confusing, but it turns out that hid_download_py instructions tell users to include the -s 0x0 flag when flashing a BK7231N module, which is ONLY true if the firmware you are flashing INCLUDES the bootloader, which OpenBeken does. If you are flashing a firmware that does NOT include the bootloader, you need to use -s 0x11000 instead, which I’m sure to forget next time. The ltchiptool automatically detects if the bootloader is included and will flash to the correct address, so it’s a non-issue there. Since hid_download_py will happily flash to the wrong address, I’ll be sticking with ltchiptool from now on.

Quoting kuba2k2 on this Github thread:

About hid_download_py, there are two problems:

  • as said in the docs, the file meant for uploading is bk7231t_app_0x011000.rbl, not firmware.bin
  • the offset should be 0x11000, not 0x0, in which case you’re overwriting the bootloader. After you correct these errors, you should be able to upload the firmware.

I always say it and I’ll say it again (so that more people see it):

  • do not use hid_download_py, ever - unless you really have to. bk7231tools has a good firmware reading/writing capabilities (ltchiptool and esphome uploaders are based on this).
  • also, always check if the target addresses are meant for what you’re trying to flash. 0x0 is the bootloader, 0x11000 is the app
  • unless you break the bootloader, flashing to 0x0 is never required. Using the so-called QIO binaries is pointless, and only increases flash wear-out in the bootloader region. “UA” binaries are meant to be flashed to 0x11000, and only that is necessary to update the firmware.

In your case, hid download or BkWriter are the only options (for the time being), because apparently bktools has a bug. Try to run bktools manually in writing mode, and report here what it outputs.

I’m going to be updating my previous posts to reflect this new information.