UNIHIKER K10 MicroPython Firmware Bug Report

UNIHIKER K10 MicroPython Firmware Bug Report

Firmware Version: V0.9.8 (micropython_unihiker_k10&Box_EN_20260506_V0.9.8.bin)
MicroPython Version: 69da69b41-dirty on 2026-05-06
Hardware: Generic ESP32S3 module with ESP32S3 (revision v0.2), 8MB PSRAM
IDF Version: 8768a76078
Date Reported: 2026-06-18
OS Used: Ubuntu Linux

-----

Bug 1: machine.reset() Hangs Indefinitely

Severity: High
Component: MicroPython core / machine module

Description:
Calling machine.reset() from the REPL causes the device to hang indefinitely. The board does not reboot and the REPL becomes unresponsive. A physical USB unplug/replug is required to recover.

Steps to Reproduce:
import machine
machine.reset()

Expected: Device performs a soft reset and reboots into MicroPython.
Actual: Device hangs. REPL becomes unresponsive. No output.
Workaround: Physically unplug and replug USB.

-----

Bug 2: ai.face_recognize_start() Returns No Detections, Even on Fresh Flash

Severity: High
Component: ai module / face recognition

Description:

face_recognize_start() never returns valid face detection data. All values in face_detect (frame_width, nose, eyes, mouth coordinates) return zero regardless of what is in front of the camera. This was first observed after extended REPL use, but was also confirmed on a completely fresh flash (full chip erase followed by clean reflash), ruling out session state corruption as the cause. The camera feed itself displays correctly on screen the whole time. By contrast, ai.move_detect() works correctly and reliably reports motion, confirming the AI engine and camera pipeline are functional in general — the face model specifically appears broken.

Steps to Reproduce:
1. Fully erase and reflash firmware (esptool erase_flash, then write-flash V0.9.8)
2. Boot device, fix any first-boot filesystem corruption if present (see Bug 6)
3. Run the following as the very first code on the device:

import ai
import time

from unihiker_k10 import screen

ai.init_ai()
ai.camera_start()
ai.face_recognize_start()
screen.init()

try:
   while True:
       image_data = ai.camera_capture()
       screen.show_camera_img(image_data)
       if ai.is_ai_data_updated():
           print(ai.get_ai_data()['face_detect']['frame_width'])
       time.sleep_ms(1)
except KeyboardInterrupt:
   ai.deinit_ai()

4. Point a clearly lit face at the camera

Expected: frame_width and face landmark coordinates return non-zero values when a face is in frame.
Actual: frame_width always returns 0, even on a fresh flash with no prior AI usage.

Comparison: ai.move_detect() reliably returns move_flag = True when motion is present, using the same camera pipeline.
Workaround: None found. Issue persists across full reflash.

-----

Bug 3: screen.clear() Does Not Clear the Drawing Layer

Severity: Medium

Component: screen module / drawing layer

Description:
screen.clear() does not clear graphics drawn with screen.draw_rect(), screen.draw_circle(), etc. when overlaid on a camera feed. The drawing layer persists across frames even after calling screen.clear(). This makes it impossible to remove overlaid graphics (e.g. AR-style overlays) using the documented API.

Steps to Reproduce:
from unihiker_k10 import screen
import ai, time

ai.init_ai()
ai.camera_start()
screen.init()

screen.draw_rect(x=50, y=50, w=100, h=50, bcolor=0xFF0000, fcolor=0xFF0000)
screen.show_draw()
time.sleep(2)

screen.clear()
screen.show_draw()
# red rect is still visible

Expected: screen.clear() removes all drawn graphics.

Actual: Graphics remain visible on screen after screen.clear().

Workaround: Draw graphics directly into the raw camera image buffer (bytearray pixel manipulation) rather than using the drawing layer, so each frame is naturally redrawn fresh.

-----

Bug 4: screen.show_camera_feed() Crashes the Device

Severity: High

Component: screen module

Description:
Calling screen.show_camera_feed() causes a hard crash with a Guru Meditation Error. The device reboots automatically but the REPL becomes unstable.

Steps to Reproduce:
from unihiker_k10 import screen
screen.init()
screen.show_camera_feed()

Expected: Displays live camera feed.

Actual: Hard crash:
Guru Meditation Error: Core 1 panic'ed (StoreProhibited)

Workaround: Use screen.show_camera_img(image_data) with a captured frame instead.

-----

Bug 5: SD Card (TF_card) Init Crashes Firmware on First Call

Severity: Medium
Component: k10_base.TF_card

Description:
On first call after flashing, TF_card() causes a Guru Meditation Error crash even with a correctly formatted FAT32 card inserted before boot. The device reboots automatically. On the second attempt after the automatic reboot, the SD card mounts correctly.

Steps to Reproduce:
1. Format SD card as FAT32
2. Insert card before powering on
3. Flash firmware, boot device
4. Immediately run:

from k10_base import TF_card
tf = TF_card()

Expected: SD card mounts successfully.
Actual: Guru Meditation Error on first attempt. Works on second attempt after automatic reboot.
Workaround: Allow device to crash and reboot once; SD card mounts correctly on subsequent attempts.

-----

Bug 6: Filesystem Corruption on First Boot After Flash

Severity: Medium

Component: MicroPython filesystem / _boot.py

Description:
After flashing firmware, the first boot frequently results in filesystem corruption errors. The _boot.py script fails to format the filesystem cleanly, entering a state that reports corruption on every subsequent boot.

Error message:
The filesystem appears to be corrupted. If you had important data there,
you may want to make a flash snapshot to try to recover it. Otherwise, perform
factory reprogramming of MicroPython firmware (completely erase flash, followed
by firmware programming).

Suspected Root Cause:
Connecting Thonny or any serial terminal during first boot sends a Ctrl+C interrupt signal, which interrupts _boot.py mid-filesystem-format, leaving the filesystem in an incomplete state.

Steps to Reproduce:
1. Flash firmware
2. Connect Thonny immediately after reboot
3. Filesystem corruption error appears on every subsequent boot

Workaround:
Manually format the filesystem from the REPL:

import os, flashbdev
os.VfsLfs2.mkfs(flashbdev.bdev)

-----

Additional Notes

- The ai module source is compiled into firmware (frozen) and not inspectable or patchable by users.
- The screen module drawing layer uses an LVGL canvas but no public API exists to clear it reliably.
- Simultaneous AI and WiFi use is documented as unsupported in V0.9.8.
- The machine.reset() hang makes automated recovery scripts impossible.

-----

Suggested Fixes

1. Fix machine.reset() to reliably reboot the device.
2. Investigate and fix the face recognition model in the ai module; it returns no detections even on a fresh flash, while move_detect works correctly using the same camera pipeline.
3. Add a screen.clear_draw() or screen.reset_layer() method that reliably clears the drawing layer.
4. Remove or fix screen.show_camera_feed(); it currently crashes the device.
5. Fix the SD card driver so it does not crash on first init.
6. Add a delay or flag in _boot.py to prevent filesystem format interruption on first boot.

-----

Firmware download: https://www.unihiker.com/wiki/K10/GettingStarted/gettingstarted_mpy/