Ai-Thinker TB-Series Flash Tool

TBXX Flash Tool is a Python utility for Ai-Thinker TB-series Bluetooth modules. It provides a PyQt5 desktop interface and a command-line interface for serial flashing, Flash erase/read/write, device triad programming, serial debugging, firmware combination, and access to legacy firmware/document catalogs.

Flash and erase operations are destructive. Confirm the module, serial port, address range, firmware image, wiring, and backup requirements before continuing. Never use production credentials for an unverified test.

Technical navigation

• Entry points and operation flow
• Architecture, protocol and Flash boundaries
• Automated validation evidence

Supported release

The latest release published in this repository is V2.1.0_2215. The former README “download” URL exposed a DingTalk robot access token and was not a software-download endpoint; it has been removed. Rotate or revoke that token if it remains active.

The master branch contains the V2 tool, which does not use the earlier external bootloader workflow. The historical V1 line remains on the 1.x.x branch.

Install on Windows

Python 3.10 or later is recommended.

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Required packages are declared in requirements.txt: PyQt5, pyserial, requests, lxml, and markdown2.

Run the graphical tool

python .\Ai-Thinker_TB_Tools.py

The main window contains five tabs: firmware flashing, serial debugging, firmware market, development documents, and firmware combination. Firmware/document catalog pages scrape legacy Gitee HTML and may stop working if that external page structure changes.

Run the command-line tool

python .\Telink_Tools.py --help
python .\Telink_Tools.py --port COM3 burn firmware.bin
python .\Telink_Tools.py --port COM3 burn_triad 1345 78da07fa44a7 221746e805ac0e6269bd4d3e55f1145c
python .\Telink_Tools.py --port COM3 read_flash 0x4000 16
python .\Telink_Tools.py --port COM3 erase_flash 0x4000 1

The command-line firmware image must contain 1 to 196,608 bytes (192 KiB). Invalid images are rejected before any erase command is sent. Flash reads now have a bounded timeout, and triad secrets are redacted from command-line and GUI logs.

Wiring

USB-TTL                         TB module

                         470 Ω
TX ---------------------+--/\/\/-- SWS
                        |
                        +--/\/\/-- RX
                           470 Ω
RX -------------------------------- TX
RTS ------------------------------- RST

Use the voltage and wiring specified for the exact module/adapter revision. Do not assume every USB-TTL adapter exposes compatible logic levels or RTS behavior.

Validation

python -W error -m compileall -q .
python -m unittest discover -s tests -v
$env:QT_QPA_PLATFORM = "offscreen"
python .\tools\gui_smoke_test.py

The validation suite checks syntax, Flash boundaries, read timeout, pre-erase firmware validation, chunked writes, credential redaction, documentation links, and offscreen creation of the five-tab main window. See VALIDATION.md for tested environments and limitations.

Update security

Automatic executable replacement is deliberately not connected to the application entry point. SimpleUpdata.py and updata.json are retained only as legacy code/data; do not reactivate them unless the update channel gains HTTPS metadata, a verified SHA-256 or signed manifest, safe path handling, and dedicated tests. Prefer signed assets from the repository release page.

License boundary

This repository has no root-level license file. Public source availability alone does not grant reuse, modification, or redistribution rights. Obtain explicit licensing clarification before distributing modified source or packaged executables.