Skip to content
aztechellPublic

About

Open-source Kendryte K210 firmware for HUSKYLENS SEN0305 and Sipeed Maix Cube, with on-device computer vision, MicroPython, and a Web Serial IDE.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

HackyLens

HackyLens

Open-source modular firmware for HUSKYLENS and the Kendryte K210.

Firmware version 0.9.0 MIT license Tested on SEN0305 Tested on Maix Cube Kendryte K210

HackyLens provides a compact on-device environment for camera experiments, QR scanning, face recognition, object detection, file browsing, diagnostics, and small interactive apps.

Important

HackyLens is a layered K210 reference firmware and MicroPython technology preview. The primary project goal is a lightweight, portable application architecture for robotics hardware: board-independent feature apps, explicit platform capabilities, and a direct path from MicroPython prototypes to native apps. See the architecture and current status and roadmap.

Warning

Flashing custom firmware replaces the firmware currently installed on the device. Make sure you are comfortable entering the K210 bootloader and restoring your preferred firmware before proceeding.

Hardware

HackyLens v0.9.0 ships firmware for HUSKYLENS SEN0305 and Sipeed Maix Cube.

Board Camera Display
DFRobot HUSKYLENS SEN0305 OV2640 320 × 240
Sipeed Maix Cube 2757 OV7740 240 × 240

Use the firmware package for your board. For other revisions, verify the board, flash layout and pin mapping before flashing. See the v0.9.0 release notes for the hardware checks.

Features

  • Live camera preview with configurable capture and display settings
  • USB camera preview and snapshots in HackyLens Code
  • QR scanning powered by quirc
  • KPU-based face detection and on-device enrollment and recognition of up to ten IDs
  • KPU Tiny-YOLOv2 object detection with 20 Pascal VOC classes
  • Shared K210 AI-model runtime with validated SD manifests and conversion tools
  • FAT32 SD-card support, photo capture, screenshots, and an image viewer
  • On-device terminal with bounded history and scrolling
  • Built-in file browser, button tester, Pong, settings, and sleep mode
  • Embedded upstream MicroPython on K210 core 1 with bounded heap, execution deadline, native-iterator-aware STOP/BACK, WDT1 recovery, stdout events, and deterministic cooperative cleanup
  • Atomic littlefs script storage in validated 16 MiB internal flash, with CRC, startup selection, a framed serial protocol, Python CLI, and Web Serial IDE
  • Compile-time app registry: omit individual apps from custom builds
  • UART tooling for flashing, logs, commands, LCD screenshots, and raw camera frames
  • Layered C codebase with an automated architecture-boundary check

Screenshots

HUSKYLENS SEN0305 menu Sipeed Maix Cube menu
HackyLens main menu on SEN0305 HackyLens main menu on Maix Cube
SEN0305 live camera SEN0305 settings
HackyLens camera preview with FPS overlay SEN0305 SETTINGS showing Screen, Lights, Connection, Startup, Device, and Menu Order

The firmware's UART screenshot protocol captured these images directly from the 320 × 240 SEN0305 and the 240 × 240 Maix Cube.

Included apps

TERMINAL, CAMERA, QR-CAMERA, FACE DETECT, APRILTAG, OBJECT DETECT, MICROPYTHON, FILES, BUTTONS, PONG, SETTINGS, POWER, and FACE RECOG.

Hold OK in CAMERA, QR-CAMERA, OBJECT DETECT, or APRILTAG to open its settings. OK opens a row marked >, and BACK returns one level. The Lights section groups the light source and RGB controls.

  • CAMERA groups resolution, photo format, and review in Capture. Use USB photo download to copy saved photos from microSD to a PC.
  • QR-CAMERA keeps Decode Rate on the first screen.
  • APRILTAG measures distance to selected tags. See the calibration guide.
  • OBJECT DETECT can limit detections to selected classes. See the class filter controls.

POWER offers sleep and restart on both boards. Maix Cube also supports power off.

In the launcher, BACK moves down one row and wraps from the last row to the first. When the next row is shorter, it selects that row's last icon and returns to the original column on the following move. LEFT and RIGHT set a new column.

Open SETTINGS → Menu Order to rearrange the launcher icons, including pinned MicroPython scripts. Select an icon with LEFT or RIGHT, press OK to pick it up, move it, then press OK again to save its position. Hold LEFT or RIGHT to keep moving one position at a time at a steady pace. BACK cancels a move. The order is saved across restarts.

Maix Cube adds RECORDER for recording to a FAT32 microSD card and playing recordings. Its FILES app also plays compatible WAV files from the card. See the Cube audio controls. Its ACCELEROMETER app shows tilt, plots live X/Y/Z readings and reports events from the built-in MSA301.

SD models

The tracked sdcard/ directory mirrors the card root. Copy its contents onto a FAT32 card so hackylens.kmodels is at the root. It includes the FACE detector, the two CanMV models for FACE RECOG, and the verified VOC20 OBJECT package. See AI models for the model contracts and FACE RECOG setup for the CanMV model hashes and license.

Build

The bootstrap script provisions the pinned Windows host and Kendryte toolchains. Run the following commands from the repository root in PowerShell.

Prerequisites

  • Git
  • Python 3
  • CMake
  • Ninja
  • 7-Zip (used to unpack the SHA-256-pinned host GCC on Windows)
  • Git for Windows (its Bash/coreutils are used by the upstream MicroPython generator)

Install the Python serial dependency:

python -m pip install pyserial

Download the pinned host GCC, Kendryte SDK/toolchain, MicroPython, littlefs, and flashing support files, then load the generated environment:

python tools\bootstrap_deps.py
. .\env.ps1
python tools\check_env.py

Run the architecture check and build the full firmware:

python tools\check_arch.py
python tools\build_firmware.py full --board huskylens-sen0305

The qualified firmware image, same-stem schema-1 flasher sidecar, and private canonical build attestation are written to dist\hackylens-full-huskylens-sen0305.bin, dist\hackylens-full-huskylens-sen0305.json, and dist\hackylens-full-huskylens-sen0305.attestation.json. The attestation binds the exact image hash to the selected board/profile and complete app composition; feature-disabled builds are not release-qualified.

Tagged releases are automated by .github/workflows/release.yml. A pushed vX.Y.Z tag must match VERSION; CI builds full firmware for SEN0305 and Maix Cube. Download the .bin and its same-stem .json for your board and keep them together when flashing.

Board Firmware Flasher metadata
SEN0305 hackylens-huskylens-sen0305-v<version>.bin hackylens-huskylens-sen0305-v<version>.json
Maix Cube hackylens-sipeed-maix-cube-v<version>.bin hackylens-sipeed-maix-cube-v<version>.json

Copy the contents of sdcard/ from the shared hackylens-sdcard-v<version>.zip to the root of a FAT32 card for either board. THIRD_PARTY_NOTICES.txt contains the firmware licenses. SHA256SUMS.txt verifies the firmware pairs, SD archive and notices.

After building both full images, create this payload locally with:

python tools\package_release_bundles.py --boards huskylens-sen0305 sipeed-maix-cube --tag v0.9.0

Board staging directories under build\release-stage\<board> hold the attestations and manifests. dist\release holds the public files listed above. Packaging refuses unexpected artifacts. The existing package_release.py --board <board> --out-dir <directory> interface remains available for flat packages. Release notes come from docs/releases/<tag>.md when present.

Apps can be excluded by repeating --disable-app:

python tools\build_firmware.py full --board huskylens-sen0305 --disable-app pong --disable-app terminal

HackyLens Code web IDE

The IDE lives in hackylens-code (normally checked out at ..\hackylens-code). It contains the complete buildable source tree derived from MIT-licensed Pybricks Code at pinned commit ea9af98d1fd0a842ed76d3a7f83767f363bc1b17, plus the HackyLens Web Serial transport, UI and tests:

Set-Location ..\hackylens-code
node .yarn\releases\yarn-3.3.0.cjs install --immutable
node .yarn\releases\yarn-3.3.0.cjs typecheck
node .yarn\releases\yarn-3.3.0.cjs test
node .yarn\releases\yarn-3.3.0.cjs build
node .yarn\releases\yarn-3.3.0.cjs start

Open http://127.0.0.1:4173/ in desktop Chrome or Edge. Web Serial requires a secure context; localhost is accepted, while deployed builds require HTTPS. The production site is written to that repository's build directory and is released independently from the firmware/SD-card package.

MicroPython workflow

The internal userfs partition is enabled only when JEDEC discovery confirms exactly 16 MiB of flash. Unsupported 8 MiB revisions keep normal firmware features but expose no script filesystem. Formatting is never automatic.

The on-device MICRO-PYTHON app lists stored .py files and provides RUN, read-only source preview, scrollable logs, startup selection, and confirmed deletion. Use PIN TO MENU to run a saved script from the main menu. The startup selection supplies the default file for an empty-name HMPY RUN and the initial selection in MICRO-PYTHON. Upload scripts from a PC with the IDE or USB CLI. The examples cover display, camera, vision, and audio.

The IDE covers edit, atomic upload, list/read/delete, startup selection, run/stop/status, live stdout/stderr, and USB camera preview and snapshots. The script workflow is also available from the reference CLI:

python tools\hkpy.py ports
python tools\hkpy.py --port COM10 hello
python tools\hkpy.py --port COM10 upload .\main.py --startup --run
python tools\hkpy.py --port COM10 monitor
python tools\hkpy.py --port COM10 stop

The repeatable hardware runner is read-only by default. It records HELLO/STATUS and one maximum 1024-byte PING before the separate filesystem gate, so a corrupt partition does not hide healthy transport evidence. Reversible storage, runtime, native-iterator STOP, and lease-reconnect checks are separate opt-ins; FORMAT still requires its exact destructive token:

python tools\hmpy_acceptance.py --port COM10
python tools\hmpy_acceptance.py --port COM10 --workflow --lease-reconnect
python tools\hmpy_acceptance.py --port COM10 --format-userfs --confirm-format "ERASE USERFS"

Fixture names are collision-checked and cleanup restores the baseline file list and startup selection. The runner never formats an unformatted userfs unless both FORMAT options are present.

The v0.2.0 CLI/HMPY workflow has passed on a physical SEN0305 after an explicitly authorized USERFS format: atomic file operations, startup execution, cooperative STOP (123 ms), native sum/min STOP (121 ms), executor reuse, lease reconnect, and exact cleanup. Later checks on both boards covered browser Web Serial upload/run/stop and physical BACK cleanup. See the hardware log. The MicroPython runtime passed 1,000 run/stop cycles on each board. A separate instrumented run confirmed stable C heap usage and working launcher navigation. Hardware results

On 2026-11-20, the maintainer excluded physical NOR endurance tests, deliberate power-loss testing during writes, and checks on additional SEN0305 units from the project's hardware acceptance scope. Hardware evidence covers the tested devices and recorded scenarios.

HMPY runs default to 30 seconds and accept up to 300 seconds. Runs started on the device continue until they finish, hit an error, or receive a stop request. See the HMPY protocol and the MicroPython research report.

The MicroPython API exposes buttons, timing, display, LED/RGB, and external UART/I2C on both boards. Scripts can capture frames and track colors, run FACE and OBJECT detection, decode QR codes and AprilTags, and save BMPs and data to microSD. Maix Cube also exposes PCM playback and recording and MSA301 acceleration readings.

STOP is checked in bytecode and native iterator loops. If a native C call still does not return after the STOP/deadline grace period, a one-shot WDT1 reset is used; MicroPython autostart is held for that recovery boot to prevent loops. HELLO exposes a backward-compatible WDT1_RECOVERY boot flag so clients can report and acceptance-test that safe-boot path explicitly. The reproducible, deliberately test-build-only procedure is documented in WDT1 hardware acceptance; production builds do not expose a Python fault-injection API. The physical -wdtfi reset, recovery and autostart-suppression checks passed on both boards on 2026-11-20.

Flash and debug

There are three ways to install firmware:

  • HLWF Desktop — an offline Windows x64 flasher with package validation, progress reporting, and recovery support.
  • HLWF — a dependency-free browser uploader built on Web Serial.
  • tools/hkflash.py — the repository's Python flashing and debug tool, intended for development workflows.
  • hkflash.py selects the bundled display-aware K210 ISP stub from the board descriptor: isp_stub/isp_prog_huskylens.bin for SEN0305 or isp_stub/isp_prog_cube.bin for Maix Cube. The stub runs independently of the installed firmware; no hardware auto-detection or extra protocol command is required. See stub provenance and checksums.

List detected serial adapters:

python tools\hkflash.py list

Flash the image and monitor the boot log:

python tools\hkflash.py flash-monitor dist\hackylens-full-huskylens-sen0305.bin --board huskylens-sen0305 --port COM10

Capture the current LCD contents without a camera or screen-grabber:

python tools\hkflash.py screenshot --board huskylens-sen0305 --port COM10 --output screen.bmp

This debug command opens SETTINGS on the connected SEN0305.

python tools\hkflash.py cmd HKSETTINGS --board huskylens-sen0305 --port COM10

Run python tools\hkflash.py --help or the help for an individual subcommand to see reset, baud-rate, verification, monitor, command, and frame-capture options.

Download CAMERA photos over USB

Download the newest numbered photo from the board's microSD. Use the board ID and COM port for your connected device.

python tools\hkflash.py photos --board sipeed-maix-cube --port COM15 -o photos

Install a firmware build with HKPHOTOS support and close any IDE session using the serial port. The command reads BMP, RAW and PPM photos already saved in hackylens.photo. Use --list to see filenames, --name IMG00001.BMP to select one or --all to copy all photos. Existing destination files are skipped in --all mode. Transfers use the USB console's default 115200 baud.

Project layout

Path Purpose
firmware/src/apps App entry points and self-contained feature modules
firmware/src/controllers User flows and screen coordination
firmware/src/services Camera, QR, settings, debug, and screenshot services
firmware/src/storage Internal flash/littlefs, FAT32, files, images, photos, and persistent data
firmware/src/ui Screen rendering
firmware/src/drivers Board-independent device drivers and services-facing hardware APIs
boards Descriptor-driven board ports, generated headers, layouts, and selected BSPs
platforms/k210/hal, platforms/k210/startup K210 HAL and platform startup composition
firmware/src/runtime Startup and the main loop
tools Dependency bootstrap, build, checks, flashing, and diagnostics
models Locked K210 conversion workflow and model descriptor specs
sdcard Files laid out exactly as they should appear on the FAT32 card

HackyLens Code is intentionally maintained in the separate sibling hackylens-code repository.

See Architecture for the current implementation, hardware acceptance and limitations, and Roadmap for product and research priorities. Detailed references cover AI models, app lifecycle, RAM/flash budget and public interfaces. Historical plans and decisions remain in Git history.

License

HackyLens is released under the MIT License.

About

Open-source Kendryte K210 firmware for HUSKYLENS SEN0305 and Sipeed Maix Cube, with on-device computer vision, MicroPython, and a Web Serial IDE.

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages