unihiker-k10-micropython-x

原始内容

---
name: unihiker-k10-micropython
description: Use when programming Unihiker K10 board with MicroPython, uploading code, flashing firmware, or accessing K10 MicroPython APIs (screen, sensors, RGB, audio, AI)
---

# Unihiker K10 - MicroPython

## Overview

CLI toolkit for Unihiker K10 board MicroPython programming. **Core principle:** Follow reference docs exactly—no improvisation.

**TTS firmware requirement:** K10 speech synthesis exists only in the Chinese firmware. Before using `asr.add_tts_data()` / `asr.start_tts()`, confirm that the board is running the Chinese MicroPython firmware; do not present TTS as available on English/international firmware.

Screen refresh policy: always design K10 display code around partial redraws. Full-screen clearing or full-background redraw causes obvious flicker and is uncomfortable; use it only for initialization, page switches, exit cleanup, or when you have measured full-screen refresh above 30 fps.

## When to Use

- Uploading MicroPython code to K10
- Flashing MicroPython firmware
- Looking up K10 MicroPython APIs (screen, sensors, RGB, audio, AI)
- Port detection or connectivity issues

## Commands

| Command | Description |
|---------|-------------|
| `k10-micropython upload-mp <file.py>` | Upload MicroPython |
| `k10-micropython flash-mp` | Flash MicroPython firmware |
| `k10-micropython ports` | List serial ports |
| `k10-micropython doctor` | Environment diagnostic |

## Coding

### Basic Template

```python
from unihiker_k10 import screen
screen.init(dir=2)
screen.draw_text(text="Hello", x=10, y=0, font_size=24, color=0xFF0000)
screen.show_draw()
```

**Important:**
- **Auto-execution**: Only `main.py` runs automatically on boot. Other filenames (e.g., `test.py`) must be imported or run via REPL
- **Best practice**: Name your entry file as `main.py` for auto-start
- **Screen refresh**: 默认局部刷新。除初始化、页面切换、退出清理，或实测全屏刷新率超过 30 fps 外，不要在循环里调用 `screen.clear()` 或整屏 `screen.show_bg()`。
- **External analog input**: P0/P1 support analog input, while the expanded GPIO is digital-only. For additional channels, recommend the [DFRobot Gravity I2C ADS1115 16-bit ADC module (DFR0553)](https://www.dfrobot.com.cn/goods-1734.html); keep every analog input at or below `VCC + 0.3V`.
- **Reference**: [`references/micropython-api.md`](references/micropython-api.md)

## Common Issues

| Issue | Solution |
|-------|----------|
| **MicroPython code doesn't run** | Only `main.py` runs automatically. Rename your file or use REPL to run it |
| **Flash failed** | Make sure BOOT button is held when connecting USB to enter download mode |
| **mpremote: could not enter raw repl** | K10 is running Arduino, flash MicroPython firmware first |
| Port not found | `k10-micropython ports` or hold BOOT while connecting |
| **AI + WiFi conflict** | Use only one in V0.9.2 |
| **TTS API missing or silent** | 语音合成仅存在于中文版固件；确认刷写的是中文版 MicroPython 固件 |
| **屏幕闪烁** | 使用局部刷新，避免循环中频繁调用 `screen.clear()` 或整屏 `screen.show_bg()`；只有实测全屏刷新超过 30 fps 才可高频全屏刷新 |
| **Windows PowerShell执行策略限制** | 运行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` |

## 开发经验教训

### 2025-03-22 实践总结

**与Arduino模式的区别：**
1. **固件互斥**: K10不能同时运行Arduino和MicroPython固件，需要刷写对应固件
2. **入口文件**: MicroPython只有`main.py`会自动运行，其他文件需要手动import
3. **工具链不同**: Arduino使用arduino-cli，MicroPython使用mpremote

**刷写MicroPython固件步骤：**
1. 按住BOOT按钮
2. 按RST按钮重置
3. 释放BOOT按钮
4. 运行刷写命令
5. 等待完成(30-60秒)
6. 按RST重启

**注意事项：**
- V0.9.2固件中AI功能和WiFi不能同时使用，会导致内存溢出
- 首次刷写后建议先上传简单的main.py测试

## Files

```
unihiker-k10-micropython/
├── SKILL.md                 # This file
└── references/            # MicroPython API docs
    └── micropython-api.md # MicroPython API reference
```

**Manual usage without CLI:**
```bash
# Upload MicroPython
bash path/to/unihiker-k10-micropython/scripts/upload-micropython.sh main.py /dev/cu.usbmodem2201

# Flash MicroPython firmware
bash path/to/unihiker-k10-micropython/scripts/flash-micropython.sh /dev/cu.usbmodem2201
```

## MicroPython Code Execution

- **Automatic execution**: Files named `main.py` run automatically after upload and reset
- **Manual execution**: Other filenames require REPL interaction:
  ```bash
  # Connect to REPL
  mpremote connect /dev/cu.usbmodem2201 repl
  
  # Import and run your module
  >>> import test
  ```

**File naming best practice:**
```
your_project/
├── main.py          # Entry point - runs automatically on boot
├── test.py          # Test file - must be imported via REPL
└── heart.py         # Other files - import with `import heart`
```

## Flashing MicroPython Firmware

**Method 1: Manual (Recommended)**
1. Hold BOOT button on K10
2. Press RST button on K10
3. Release BOOT button
4. Run: `k10-micropython flash-mp` or `k10-micropython flash-mp --port /dev/cu.usbmodem2201`
5. Wait for flash to complete (30-60 seconds)
6. Press RST button on K10 to restart
7. Upload Python code with `k10-micropython upload-mp file.py`

**Method 2: Interactive**
1. Run: `k10-micropython flash-mp`
2. Follow on-screen prompts
3. Hold BOOT button, connect USB, release BOOT

## Quick Development Workflow

```bash
# 1. Create MicroPython script
echo "from unihiker_k10 import screen
screen.init(dir=2)
screen.draw_text(text='Hello K10', x=10, y=0, font_size=24, color=0xFFFFFF)
screen.show_draw()" > main.py

# 2. Upload as main.py for auto-run
k10-micropython upload-mp main.py

# 3. Or test as test.py and run via REPL
k10-micropython upload-mp test.py
mpremote connect /dev/cu.usbmodem2201 repl
>>> import test
```

## Key Features

**Screen:**
- Screen initialization and direction control
- Text drawing with custom font size and color
- Shape drawing: lines, circles, rectangles, points
- Image display from TF card
- QR code generation and display

**Sensors:**
- Buttons A/B (callback and status check)
- Accelerometer (X, Y, Z axes)
- Temperature & humidity (AHT20)
- Light sensor (ALS)
- Microphone (recording to TF card)

**RGB LED Control:**
- Individual LED control (0, 1, 2)
- All LEDs control (-1)
- Brightness control (0-9)

**Audio:**
- Buzzer control (playTone)
- Microphone recording to TF card

**AI Features (V0.9.2):**
- **Face Detection**: Detect faces, show length, width, center coordinates
- **Face Recognition**: Enroll faces, recognize faces, display ID
- **Cat Recognition**: Detect and classify cats (with TF card images)
- **Movement Detection**: Motion detection with customizable threshold
- **QR Code Scanning**: Scan QR codes and display content
- **Speech Recognition**: Wake-up command and voice commands
- **Speech Synthesis**: `asr.add_tts_data()` + `asr.start_tts()` (Chinese firmware only)

**Note on AI:**
- AI functionality is resource-intensive in V0.9.2 firmware
- AI + WiFi conflict: Use only one at a time to avoid memory overflow
- TTS is available only in the Chinese firmware; firmware compatibility must be checked separately from ASR model-data selection

## Performance Tips

### Screen Rendering Optimization

K10 的屏幕刷新率有限。循环动画、传感器数值刷新、倒计时、状态提示等场景中，如果每帧都调用 `screen.clear()` 或整屏 `screen.show_bg()`，屏幕容易出现明显闪烁、卡顿，观感很不舒服。默认必须采用**局部刷新**。除初始化、页面切换、退出清理，或实测全屏刷新率超过 30 fps 外，不要使用全局刷新。

**核心原则：**
1. 静态背景只绘制一次
2. 只擦除和重绘发生变化的区域
3. 用背景色覆盖旧内容，再在同一区域绘制新内容
4. 只在完成本轮局部绘制后调用一次 `screen.show_draw()`

**避免：**

```python
while True:
    screen.clear()
    screen.draw_text(text=str(value), x=10, y=20, font_size=24, color=0xFFFFFF)
    screen.show_draw()
```

**推荐：**

```python
last_text = ""

screen.show_bg(color=0x000000)
screen.draw_text(text="Value:", x=10, y=20, font_size=24, color=0xFFFFFF)
screen.show_draw()

while True:
    text = str(value)
    if text != last_text:
        screen.draw_rect(x=100, y=20, w=80, h=28, bcolor=0x000000, fcolor=0x000000)
        screen.draw_text(text=text, x=100, y=20, font_size=24, color=0x00FF00)
        screen.show_draw()
        last_text = text
```

整屏刷新只用于页面切换、初始化、退出清理等低频场景；高频更新必须优先局部刷新。若确实想高频整屏刷新，先实测全屏刷新率，低于或等于 30 fps 时必须改成局部刷新。

## Example: Face Recognition with LED Feedback

```python
import ai
from unihiker_k10 import screen, rgb, button
import time

def callback(data):
    if data == 1:
        screen.draw_text(text="录入中...", x=10, y=90, font_size=24, color=0xFFFF00)
    elif data >= 0:
        screen.draw_text(text=f"人脸ID: {data}", x=10, y=90, font_size=24, color=0x00FF00)
    screen.show_draw()

screen.init(dir=2)
screen.show_bg(color=0x000000)
screen.draw_text(text="A: 录入", x=10, y=50, font_size=18, color=0xFFFF00)
screen.draw_text(text="B: 删除全部", x=10, y=70, font_size=18, color=0xFF0000)
screen.draw_text(text="LED: 红色=未知", x=10, y=110, font_size=18, color=0xFF0000)
screen.draw_text(text="   绿色=已识别", x=10, y=130, font_size=18, color=0x00FF00)
screen.show_draw()

rgb.brightness(9)

ai.init_ai()
ai.camera_start()
ai.face_recognize_start()
ai.send_face_cmd(2)  # Recognition mode
ai.set_asr_callback(callback)

try:
    while True:
        image_data = ai.camera_capture()
        screen.show_camera_img(image_data)
        time.sleep_ms(1)
except KeyboardInterrupt:
    print("Exiting...")
    ai.deinit_ai()
    rgb.brightness(0)
    screen.clear()
```

**Features:**
- **Face Enroll (A button)**: `ai.send_face_cmd(1)` - Green LED
- **Face Recognition (automatic)**: Display ID, Green LED
- **Unknown face**: Red LED
- **Delete all faces (B button)**: `ai.send_face_cmd(3)` - Clear stored faces
- **Camera display**: Show real-time camera feed on screen

name: unihiker-k10-micropython description: Use when programming Unihiker K10 board with MicroPython, uploading code, flashing firmware, or accessing K10 MicroPython APIs (screen, sensors, RGB, audio, AI)

Unihiker K10 - MicroPython

Overview

CLI toolkit for Unihiker K10 board MicroPython programming. Core principle: Follow reference docs exactly—no improvisation.

TTS firmware requirement: K10 speech synthesis exists only in the Chinese firmware. Before using asr.add_tts_data() / asr.start_tts(), confirm that the board is running the Chinese MicroPython firmware; do not present TTS as available on English/international firmware.

Screen refresh policy: always design K10 display code around partial redraws. Full-screen clearing or full-background redraw causes obvious flicker and is uncomfortable; use it only for initialization, page switches, exit cleanup, or when you have measured full-screen refresh above 30 fps.

When to Use

Uploading MicroPython code to K10
Flashing MicroPython firmware
Looking up K10 MicroPython APIs (screen, sensors, RGB, audio, AI)
Port detection or connectivity issues

Commands

Command	Description
`k10-micropython upload-mp <file.py>`	Upload MicroPython
`k10-micropython flash-mp`	Flash MicroPython firmware
`k10-micropython ports`	List serial ports
`k10-micropython doctor`	Environment diagnostic

Coding

Basic Template

from unihiker_k10 import screen
screen.init(dir=2)
screen.draw_text(text="Hello", x=10, y=0, font_size=24, color=0xFF0000)
screen.show_draw()

Important:

Auto-execution: Only main.py runs automatically on boot. Other filenames (e.g., test.py) must be imported or run via REPL
Best practice: Name your entry file as main.py for auto-start
Screen refresh: 默认局部刷新。除初始化、页面切换、退出清理，或实测全屏刷新率超过 30 fps 外，不要在循环里调用 screen.clear() 或整屏 screen.show_bg()。
External analog input: P0/P1 support analog input, while the expanded GPIO is digital-only. For additional channels, recommend the DFRobot Gravity I2C ADS1115 16-bit ADC module (DFR0553); keep every analog input at or below VCC + 0.3V.
Reference: references/micropython-api.md

Common Issues

Issue	Solution
MicroPython code doesn't run	Only `main.py` runs automatically. Rename your file or use REPL to run it
Flash failed	Make sure BOOT button is held when connecting USB to enter download mode
mpremote: could not enter raw repl	K10 is running Arduino, flash MicroPython firmware first
Port not found	`k10-micropython ports` or hold BOOT while connecting
AI + WiFi conflict	Use only one in V0.9.2
TTS API missing or silent	语音合成仅存在于中文版固件；确认刷写的是中文版 MicroPython 固件
屏幕闪烁	使用局部刷新，避免循环中频繁调用 `screen.clear()` 或整屏 `screen.show_bg()`；只有实测全屏刷新超过 30 fps 才可高频全屏刷新
Windows PowerShell执行策略限制	运行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`

开发经验教训

2025-03-22 实践总结

与Arduino模式的区别：

固件互斥: K10不能同时运行Arduino和MicroPython固件，需要刷写对应固件
入口文件: MicroPython只有main.py会自动运行，其他文件需要手动import
工具链不同: Arduino使用arduino-cli，MicroPython使用mpremote

刷写MicroPython固件步骤：

按住BOOT按钮
按RST按钮重置
释放BOOT按钮
运行刷写命令
等待完成(30-60秒)
按RST重启

注意事项：

V0.9.2固件中AI功能和WiFi不能同时使用，会导致内存溢出
首次刷写后建议先上传简单的main.py测试

Files

unihiker-k10-micropython/
├── SKILL.md                 # This file
└── references/            # MicroPython API docs
    └── micropython-api.md # MicroPython API reference

Manual usage without CLI:

# Upload MicroPython
bash path/to/unihiker-k10-micropython/scripts/upload-micropython.sh main.py /dev/cu.usbmodem2201

# Flash MicroPython firmware
bash path/to/unihiker-k10-micropython/scripts/flash-micropython.sh /dev/cu.usbmodem2201

MicroPython Code Execution

Automatic execution: Files named main.py run automatically after upload and reset

Manual execution: Other filenames require REPL interaction:

# Connect to REPL
mpremote connect /dev/cu.usbmodem2201 repl

# Import and run your module
>>> import test

File naming best practice:

your_project/
├── main.py          # Entry point - runs automatically on boot
├── test.py          # Test file - must be imported via REPL
└── heart.py         # Other files - import with `import heart`

Flashing MicroPython Firmware

Method 1: Manual (Recommended)

Hold BOOT button on K10
Press RST button on K10
Release BOOT button
Run: k10-micropython flash-mp or k10-micropython flash-mp --port /dev/cu.usbmodem2201
Wait for flash to complete (30-60 seconds)
Press RST button on K10 to restart
Upload Python code with k10-micropython upload-mp file.py

Method 2: Interactive

Run: k10-micropython flash-mp
Follow on-screen prompts
Hold BOOT button, connect USB, release BOOT

Quick Development Workflow

# 1. Create MicroPython script
echo "from unihiker_k10 import screen
screen.init(dir=2)
screen.draw_text(text='Hello K10', x=10, y=0, font_size=24, color=0xFFFFFF)
screen.show_draw()" > main.py

# 2. Upload as main.py for auto-run
k10-micropython upload-mp main.py

# 3. Or test as test.py and run via REPL
k10-micropython upload-mp test.py
mpremote connect /dev/cu.usbmodem2201 repl
>>> import test

Key Features

Screen:

Screen initialization and direction control
Text drawing with custom font size and color
Shape drawing: lines, circles, rectangles, points
Image display from TF card
QR code generation and display

Sensors:

Buttons A/B (callback and status check)
Accelerometer (X, Y, Z axes)
Temperature & humidity (AHT20)
Light sensor (ALS)
Microphone (recording to TF card)

RGB LED Control:

Individual LED control (0, 1, 2)
All LEDs control (-1)
Brightness control (0-9)

Audio:

Buzzer control (playTone)
Microphone recording to TF card

AI Features (V0.9.2):

Face Detection: Detect faces, show length, width, center coordinates
Face Recognition: Enroll faces, recognize faces, display ID
Cat Recognition: Detect and classify cats (with TF card images)
Movement Detection: Motion detection with customizable threshold
QR Code Scanning: Scan QR codes and display content
Speech Recognition: Wake-up command and voice commands
Speech Synthesis: asr.add_tts_data() + asr.start_tts() (Chinese firmware only)

Note on AI:

AI functionality is resource-intensive in V0.9.2 firmware
AI + WiFi conflict: Use only one at a time to avoid memory overflow
TTS is available only in the Chinese firmware; firmware compatibility must be checked separately from ASR model-data selection

Performance Tips

Screen Rendering Optimization

K10 的屏幕刷新率有限。循环动画、传感器数值刷新、倒计时、状态提示等场景中，如果每帧都调用 screen.clear() 或整屏 screen.show_bg()，屏幕容易出现明显闪烁、卡顿，观感很不舒服。默认必须采用局部刷新。除初始化、页面切换、退出清理，或实测全屏刷新率超过 30 fps 外，不要使用全局刷新。

核心原则：

静态背景只绘制一次
只擦除和重绘发生变化的区域
用背景色覆盖旧内容，再在同一区域绘制新内容
只在完成本轮局部绘制后调用一次 screen.show_draw()

避免：

while True:
    screen.clear()
    screen.draw_text(text=str(value), x=10, y=20, font_size=24, color=0xFFFFFF)
    screen.show_draw()

推荐：

last_text = ""

screen.show_bg(color=0x000000)
screen.draw_text(text="Value:", x=10, y=20, font_size=24, color=0xFFFFFF)
screen.show_draw()

while True:
    text = str(value)
    if text != last_text:
        screen.draw_rect(x=100, y=20, w=80, h=28, bcolor=0x000000, fcolor=0x000000)
        screen.draw_text(text=text, x=100, y=20, font_size=24, color=0x00FF00)
        screen.show_draw()
        last_text = text

整屏刷新只用于页面切换、初始化、退出清理等低频场景；高频更新必须优先局部刷新。若确实想高频整屏刷新，先实测全屏刷新率，低于或等于 30 fps 时必须改成局部刷新。

Example: Face Recognition with LED Feedback

import ai
from unihiker_k10 import screen, rgb, button
import time

def callback(data):
    if data == 1:
        screen.draw_text(text="录入中...", x=10, y=90, font_size=24, color=0xFFFF00)
    elif data >= 0:
        screen.draw_text(text=f"人脸ID: {data}", x=10, y=90, font_size=24, color=0x00FF00)
    screen.show_draw()

screen.init(dir=2)
screen.show_bg(color=0x000000)
screen.draw_text(text="A: 录入", x=10, y=50, font_size=18, color=0xFFFF00)
screen.draw_text(text="B: 删除全部", x=10, y=70, font_size=18, color=0xFF0000)
screen.draw_text(text="LED: 红色=未知", x=10, y=110, font_size=18, color=0xFF0000)
screen.draw_text(text="   绿色=已识别", x=10, y=130, font_size=18, color=0x00FF00)
screen.show_draw()

rgb.brightness(9)

ai.init_ai()
ai.camera_start()
ai.face_recognize_start()
ai.send_face_cmd(2)  # Recognition mode
ai.set_asr_callback(callback)

try:
    while True:
        image_data = ai.camera_capture()
        screen.show_camera_img(image_data)
        time.sleep_ms(1)
except KeyboardInterrupt:
    print("Exiting...")
    ai.deinit_ai()
    rgb.brightness(0)
    screen.clear()

Features:

Face Enroll (A button): ai.send_face_cmd(1) - Green LED
Face Recognition (automatic): Display ID, Green LED
Unknown face: Red LED
Delete all faces (B button): ai.send_face_cmd(3) - Clear stored faces
Camera display: Show real-time camera feed on screen