---
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.

## 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
- **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 |

## 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

**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

## 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
