HLWF — HuskyLens Web Flasher

HLWF is a self-contained, dependency-free static Web Serial uploader for HuskyLens/Kendryte K210 devices. It selects a local .bin, validates its size, computes SHA-256 in the browser, asks for explicit confirmation, and writes the image through a user-selected serial port.

Live site: aztechell.github.io/HLWF

Safety: flashing replaces the current device firmware. Use a known-good image, keep power connected, and do not close the tab during the write stage. The project never starts a flash without the explicit confirmation checkbox. Automated tests do not access serial hardware.

Privacy and security

• Firmware is read with the browser File API and is never uploaded.
• There is no analytics, CDN, remote API, service worker, or external runtime dependency.
• The only runtime fetch() loads the bundled open ISP stub from the same static origin.
• A Content Security Policy restricts scripts, styles, and connections to the same origin.
• Web Serial requires a secure context: HTTPS (including GitHub Pages) or http://localhost.

Browser support

Use a current desktop version of Chrome or Microsoft Edge. Firefox and Safari do not currently expose the Web Serial API used by HLWF.

1. Connect HuskyLens by USB.
2. Click Select port and select its serial adapter.
3. Select or drop a .bin file.
4. Check the filename, byte size, and SHA-256.
5. Accept the replacement warning and click Flash firmware.
6. Keep the device connected until the port is reported closed.

Firmware size rule

HLWF targets the 16 MiB flash used by HuskyLens. A standard K210 boot image adds 37 bytes: one SPI/AES flag byte, a four-byte little-endian firmware length, and a 32-byte SHA-256 suffix. Therefore the maximum accepted raw .bin size is 16 MiB - 37 bytes (16,777,179 bytes). Empty files are rejected.

Why .kfpkg is not supported

HLWF intentionally accepts raw .bin firmware only. HuskyLens .kfpkg packages are compressed multi-image archives containing firmware, models, and a flash address map. A typical original package expands to roughly 11.4 MiB of data that must be written to several flash regions.

The current browser-compatible HuskyLens path is limited to 115200 baud. Web Serial cannot change the baud rate of an already open port, while closing and reopening the tested CP210x adapter during the ISP handoff resets HuskyLens and loses communication. At 115200 baud, a full .kfpkg would take at least about 17 minutes in ideal conditions and typically 20–25 minutes with protocol overhead and retries. For that reason, .kfpkg support is excluded until a reliable faster Web Serial handoff is available.

Original HuskyLens firmware packages and the official desktop uploader are available from HuskyLens/HUSKYLENSUploader.

K210/HuskyLens protocol

The implementation follows the open sipeed/kflash.py flow and the HuskyLens-compatible reset behavior:

1. Open UART at 115200, 8-N-1.
2. Try the dan and kd233 DTR/RTS sequences to enter K210 BootROM.
3. Exchange SLIP-framed BootROM commands (0xC2, 0xC3, 0xC5).
4. Upload the MIT-licensed kflash.py ISP stub to SRAM at 0x80000000 and boot it.
5. Initialize on-board flash (0xD7, type 1).
6. Create the DIO boot image (0x02 + uint32(length) + firmware + SHA-256) and write it at flash address 0x000000 with CRC-32 protected 0xD4 packets.
7. Request reboot (0xD5) and close the serial port in every success, failure, or cancellation path.

HLWF deliberately stays at 115200 baud. This is a practical Web Serial port lifecycle limitation on the tested HuskyLens adapter, not a K210 hardware baud rate limit. The conservative rate keeps the flashing path predictable.

The bundled stub was extracted from sipeed/kflash.py revision 550828c768b16ef329695d3f5eace3f6bcf14af2. Its attribution and exact MIT license are in third_party/kflash.py. No user firmware is bundled.

Local development

No installation or build step is required. Serve the directory over localhost:

npm run serve

Then open http://localhost:8000 in Chrome or Edge. Do not open index.html directly with a file:// URL because Web Serial needs a secure context.

Run the Node.js test suite:

npm test

The tests cover CRC-32, SLIP encoding, packet construction, K210 image layout, size limits, static privacy constraints, ISP stub presence, and serial-port closure after both success and failure. They use no real serial device.

Reproducing the ISP stub

Given a checkout of the pinned kflash.py revision:

node tools/extract-kflash-stub.mjs path\to\kflash.py third_party\kflash.py\isp_prog.bin

Compare the printed SHA-256 with third_party/kflash.py/NOTICE.md and the value pinned in src/app.js.

GitHub Pages

The public version is available at https://aztechell.github.io/HLWF/.

The workflow at .github/workflows/pages.yml runs tests and deploys this directory as a static GitHub Pages artifact on pushes to main. In the GitHub repository settings, set Pages → Source to GitHub Actions.

License

HLWF is released under the MIT License. The bundled kflash.py ISP stub is also MIT-licensed by its original author; its license is reproduced separately.