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 kflash wire protocol 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 Apache-2.0 HuskyLens display 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 comes from aztechell/huskylens-isp-stub v1.0. Its Apache-2.0 license and provenance are in isp_stub. 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.

Bundled ISP stub

HLWF bundles the display-aware huskylens-isp-stub v1.0. The 17,600-byte SRAM helper shows flashing progress on the HuskyLens ST7789 screen and preserves the kflash wire protocol. Its SHA-256 is db3ba7debd7a9a0246b65853d774fc6a568507e148772e2cdffa0d3c55ca5623. See isp_stub/NOTICE.md for provenance and reproducible build details.

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 HuskyLens ISP stub is Apache-2.0 licensed; its license and notices are reproduced separately.