bk7231tools - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #llm #golang #go #android #machine-learning #rust #deep-learning #nodejs #awesome #cli #awesome-list #ios

bk7231tools

(★ 70)

This is a collection of tools to interact with and analyze artifacts for BK7231 MCUs

File Explorer

Download Latest Version (.zip)

- - release.yml
- - __init__.py
  - crc16.py
  - flash.py
  - kvstorage.py
  - rbl.py
  - storage.py
  - utils.py
- - __init__.py
  - code.py
  - util.py
- - __init__.py
  - cmd_hl_flash.py
  - cmd_ll_chip.py
  - cmd_ll_flash.py
  - legacy.py
  - linking.py
  - main.py
  - protocol.py
- __init__.py
- __main__.py
.gitignore
LICENSE
package.json
poetry.lock
pyproject.toml
README.md

# Installation Guide

1. Get the code

git clone https://github.com/tuya-cloudcutter/bk7231tools

Downloads the entire project code from GitHub to your computer.

cd bk7231tools

Moves into the project folder you just downloaded.

2. Official Install Script

Easy Recommended

Prerequisites

Python 3 Python is required to use pip.

pip install bk7231tools[cli]

Installs the package published on PyPI directly — no need to clone the source.

✅ After installing, open a new terminal and run the program's version command (e.g. --version) to confirm it worked.

Pulled directly from this repo's README.

3. Node.js

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install

Downloads and installs the libraries listed in package.json.

npm start

Starts the development/run server.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

4. Python

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Python 3 On Windows, be sure to check 'Add Python to PATH' during installation.

pip install bk7231tools[cli]

Installs the package published on PyPI directly — no need to clone the source.

✅ If it runs without errors and prints output in the terminal, it worked.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# bk7231tools
This is a collection of tools to interact with and analyze artifacts for BK7231 MCUs.

## Contributors
- [Kuba Szczodrzyński - @kuba2k2](https://github.com/kuba2k2)

## Installation
Install the package from PyPI:
```
pip install bk7231tools[cli]
```

The `[cli]` extras will include PyCryptodome, required for Tuya Storage extraction.

## ⚠️ WARNING⚠️
Please be aware that this software is provided without any guarantees from the authors. If you will still use it, then please be aware that:

1. You understand what the software is doing
2. You choose to use it at your own risk
3. The authors cannot be held accountable for any damages that arise.

## Usage
There are a couple of usage modes for this toolset:
- dissecting already extracted flash artifacts; does not require interaction with the device
- chip identification
- reading flash
- writing flash

### Flash reading

**Note:** since version 1.0.0 of this tool, the `--no-verify-checksum` argument is not needed (even for BK7231N). It is recommended to remove that argument, to ensure that the captured dump is valid.

Ensure that the MCU is hooked up to a UART bridge such that:
- `UART_TXD1` on the MCU is hooked up to the `RXD` pin on the UART bridge
- `UART_RXD1` on the MCU is hooked up to the `TXD` pin on the UART bridge

Afterwards, hook up the `GND` and `3v3` line to the MCU off the bridge or some other power source. In case another power source is used, ensure the power source's `GND` line is tied to the UART bridge's `GND` line.

Once the devices are connected, invoke `bk7231tools`. For example, to read all internal flash contents (2 MB in size, that's `0x200000` in hex) off a BK7231T device hooked up to `/dev/ttyUSB0` and into the file `dump.bin`, use:

```sh
# the -s and -l arguments are optional and default to the values provided here
bk7231tools read_flash -d /dev/ttyUSB0 -s 0 -l 0x200000 dump.bin
```

The toolset will then attempt to connect to the MCU and perform the requested operation. During the connection attempt process, it may be the case that the device is not reset (in case RTS signal is not hooked up as well). If that's the case, the connection will fail. In order to remedy this issue, manually reset the device by disconnecting its power (but not the UART bridge!) a few times after issuing the command.

### Dissecting flash dumps
Once a flash dump has been acquired, it can be dissected into its constituents by invoking the `dissect_dump` subcommand. For example, to dissect and extract artifacts from the flash dump file produced by the command in [flash reading](#flash-reading):

```sh
$ bk7231tools dissect_dump -e -O dump_extract_dir dump.bin

RBL containers:
        0x10f9a: bootloader - [encoding_algorithm=NONE, size=0xdd40]
                extracted to dump_extract_dir
        0x129f0a: app - [encoding_algorithm=NONE, size=0xfd340]
                extracted to dump_extract_dir
```
The above command flags are `-e` to extract - otherwise only a listing is shown and `-O` to write the extracted files to the specified directory (`dump_extract_dir`).
Combined with `--rbl`, you can also extract fully reconstructed RBL files for later usage.

Extracted artifacts are dependent on the flash layout supplied, but usually there are two partitions `app` and `bootloader`. If an extracted partition is also a known encrypted code partition (e.g. `app`), its decrypted version is also extracted with the suffix `_decrypted.bin`.

### Writing flash
Writing can be used to restore stock firmware or flash custom firmware. The tool allows to flash a binary file to an arbitrary location in flash (which needs to be 4K-aligned).

The writing process is optimized to not write empty (all 0xFF) blocks, to speed up the UART communication.

The tool can also skip certain amount of bytes from the input file (i.e. to skip uploading the bootloader).

```sh
# write app firmware (from app-only binary file)
# start=0x11000, skip=0, length=(entire file)
bk7231tools write_flash -d /dev/ttyUSB0 -s 0x11000 -S 0 dump_app.bin

# write stock app (from full dump)
# start=0x11000, skip=0x11000, length=0x121000
bk7231tools write_flash -d /dev/ttyUSB0 -s 0x11000 -S 0x11000 -l 0x121000 dump_stock_full_2mb.bin

# write/restore bootloader only (BK7231N only!!)
# start=0, skip=0, length=0x11000
bk7231tools write_flash -d /dev/ttyUSB0 -s 0 -S 0 -l 0x11000 --bootloader dump_stock_full_2mb.bin

# write entire flash dump (BK7231N only!!)
# start=0, skip=0, length=0x200000
bk7231tools write_flash -d /dev/ttyUSB0 -s 0 -S 0 -l 0x200000 --bootloader dump_stock_full_2mb.bin
```