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.
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.
- 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
| HUSKYLENS SEN0305 menu | Sipeed Maix Cube menu |
|---|---|
![]() |
![]() |
| SEN0305 live camera | SEN0305 settings |
|---|---|
![]() |
![]() |
The firmware's UART screenshot protocol captured these images directly from the 320 × 240 SEN0305 and the 240 × 240 Maix Cube.
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.
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.
The bootstrap script provisions the pinned Windows host and Kendryte toolchains. Run the following commands from the repository root in PowerShell.
- 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 pyserialDownload 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.pyRun the architecture check and build the full firmware:
python tools\check_arch.py
python tools\build_firmware.py full --board huskylens-sen0305The 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.0Board 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 terminalThe 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 startOpen 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.
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 stopThe 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.
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.pyselects the bundled display-aware K210 ISP stub from the board descriptor:isp_stub/isp_prog_huskylens.binfor SEN0305 orisp_stub/isp_prog_cube.binfor 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 listFlash the image and monitor the boot log:
python tools\hkflash.py flash-monitor dist\hackylens-full-huskylens-sen0305.bin --board huskylens-sen0305 --port COM10Capture the current LCD contents without a camera or screen-grabber:
python tools\hkflash.py screenshot --board huskylens-sen0305 --port COM10 --output screen.bmpThis debug command opens SETTINGS on the connected SEN0305.
python tools\hkflash.py cmd HKSETTINGS --board huskylens-sen0305 --port COM10Run 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 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 photosInstall 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.
| 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.
HackyLens is released under the MIT License.




