unihiker-k10-arduino-x-2

原始内容

---
name: unihiker-k10-arduino
description: Use when programming Unihiker K10 board with Arduino/C++, uploading code, flashing firmware, or accessing K10 Arduino APIs (screen, sensors, RGB, audio, AI, TTS, ASR)
---

# Unihiker K10 - Arduino

## Overview

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

**Firmware Version**: 0.9.2
**FQBN**: `UNIHIKER:esp32:k10`

**TTS firmware requirement:** `ASR::setAsrSpeed()` and `ASR::speak()` are available only in the Chinese K10 firmware. Before generating, compiling, or troubleshooting speech-synthesis code, confirm that the board/toolchain is using the Chinese firmware. Selecting or restoring CN model data is not, by itself, proof that the installed firmware exposes TTS.

If a sketch uses K10 AI, voice recognition, TTS, face recognition, or OTA partitions, preserve the factory model-data offsets. Read the repository reference `references/k10-ai-model-flash.md` when available.

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 Arduino/C++ code to K10
- Flashing Arduino firmware
- Looking up K10 Arduino APIs (screen, canvas, sensors, RGB, audio)
- Setting up development environment for the first time
- Port detection or connectivity issues

## Environment Setup (MANDATORY - First Time Only)

Before uploading code, ensure your Arduino environment is configured correctly.

### Windows Self-Contained Offline Installer

For Windows machines with no Arduino tooling installed, use the self-contained offline installer first. The installer bundles `arduino-cli.exe`, the UNIHIKER K10 BSP, required ESP32-S3 tools, and local libraries.

Known install locations to check, in order:

```text
C:\K10A
%USERPROFILE%\K10A
%LOCALAPPDATA%\K10A
%LOCALAPPDATA%\K10Arduino
```

When one of these directories exists and contains `arduino-cli.exe` plus `arduino-cli.local.yaml`, use that local environment instead of assuming `arduino-cli` is on `PATH`:

```powershell
cd C:\K10A
.\setup-config.bat
.\arduino-cli.exe --config-file .\arduino-cli.local.yaml core list
.\arduino-cli.exe --config-file .\arduino-cli.local.yaml compile --fqbn UNIHIKER:esp32:k10 .\examples\Blink
```

For user sketches, prefer:

```powershell
C:\K10A\compile-sketch.bat "C:\path\to\SketchFolder"
C:\K10A\upload-sketch.bat "C:\path\to\SketchFolder" COM3
```

If the short-path installer is present, do not ask the user to download BSP/toolchains again unless required files are missing.

### Windows 快速安装 (推荐)

在Windows上，skill目录已包含预下载的 `arduino-cli.exe`，可直接使用：

```powershell
# 进入skill脚本目录
cd ~/.agents/skills/unihiker-k10-arduino/scripts

# 验证arduino-cli可用
.\arduino-cli.exe version

# 添加到PATH (PowerShell)
$env:PATH = "$env:PATH;$env:USERPROFILE\.agents\skills\unihiker-k10-arduino\scripts"

# 永久添加到PATH (可选)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")
```

### Step 1: Check arduino-cli Installation

```bash
# Check if arduino-cli is installed
which arduino-cli

# Check installed version
arduino-cli version
```

**Expected output:**
```bash
arduino-cli 0.35.0
# Or any version number
```

**If `which arduino-cli` returns empty or "arduino-cli: not found":** Proceed to Step 2.

### Step 2: Install arduino-cli (If Not Installed)

**macOS:**
```bash
# Download the latest release from GitHub
# Visit: https://github.com/arduino/arduino-cli/releases
# Or use Homebrew
brew install arduino-cli
```

**Linux (Ubuntu/Debian):**
```bash
# Download the latest release from GitHub
# Visit: https://github.com/arduino/arduino-cli/releases
# Or use apt (may be outdated)
sudo apt install arduino-cli

# Or download the binary and add to PATH
wget https://github.com/arduino/arduino-cli/releases/download/0.35.0/arduino-cli_0.35.0_Linux_64bit.tar.gz
tar -xzf arduino-cli_0.35.0_Linux_64bit.tar.gz
sudo mv arduino-cli /usr/local/bin/
```

**Windows:**
```powershell
# 方法1: 使用skill自带的arduino-cli (推荐)
# 文件位置: ~/.agents/skills/unihiker-k10-arduino/scripts/arduino-cli.exe

# 方法2: 手动下载
# Visit: https://github.com/arduino/arduino-cli/releases
# Download: arduino-cli_1.2.0_Windows_64bit.zip
# Extract to a folder and add to PATH
```

### Step 3: Install K10 BSP (Board Support Package)

The K10 BSP is required for arduino-cli to recognize the Unihiker K10 board.

#### Board Manager URLs

K10 BSP 依赖 ESP32 Arduino Core。UNIHIKER K10 使用 ESP32 Core 稳定版即可。按网络环境二选一配置：

**中国大陆用户（推荐国内镜像）**

```bash
# K10 BSP — DFRobot 国内 CDN
arduino-cli config add board_manager.additional_urls https://downloadcd.dfrobot.com.cn/UNIHIKER/package_unihiker_index.json

# ESP32 Arduino Core — 稳定版国内镜像
arduino-cli config add board_manager.additional_urls https://jihulab.com/esp-mirror/espressif/arduino-esp32/-/raw/gh-pages/package_esp32_index_cn.json
```

**国外用户（官方源）**

```bash
# K10 BSP — DFRobot
arduino-cli config add board_manager.additional_urls https://downloadcd.dfrobot.com.cn/UNIHIKER/package_unihiker_index.json

# ESP32 Arduino Core — Espressif official stable index
arduino-cli config add board_manager.additional_urls https://dl.espressif.com/dl/package_esp32_index.json
```

配置完成后验证：
```bash
arduino-cli config dump | grep additional_urls
# 应输出 K10 BSP 与 ESP32 Core URL
```

#### 安装 BSP

```bash
# Refresh core index
arduino-cli core update-index

# Install K10 core（约 500MB，首次约 5-10 分钟）
arduino-cli core install UNIHIKER:esp32

# Verify installation
arduino-cli board listall | grep unihiker
```

**Expected output:**
```
UNIHIKER:esp32:k10
```

**注意:** 即使使用镜像，BSP 包约 500MB 首次仍需较长时间。建议配合 [Step 4 的 build_cache](#step-4-configure-build-cache-recommended) 避免反复下载。

### Step 4: Configure Build Cache (Recommended)

Arduino CLI has a built-in compilation cache. For repeated K10 builds, use the official `build_cache.*` configuration keys and keep build artifacts in a stable directory. **This is strongly recommended** — without it, every compile rebuilds the entire BSP (~500 MB) from scratch.

**Windows PowerShell:**
```powershell
arduino-cli config set build_cache.path "$env:LOCALAPPDATA\arduino\build-cache"
arduino-cli config set build_cache.compilations_before_purge 0
```

**Linux/macOS:**
```bash
arduino-cli config set build_cache.path ~/.cache/arduino-build-cache
arduino-cli config set build_cache.compilations_before_purge 0
```

#### Optimized Compile Command

Use these flags for every compile to get incremental + parallel compilation:

| Flag | Effect |
|------|--------|
| `--build-path .arduino-build` | Keep intermediate `.o` files; only recompile changed sources |
| `--output-dir build` | Put final `.bin`/`.elf` in `build/` |
| `--build-property "build.partitions=custom"` | Use project `partitions.csv` for OTA support |
| `--jobs 0` | Use all CPU cores for parallel compilation |

```bash
arduino-cli compile --fqbn UNIHIKER:esp32:k10 . \
  --build-path .arduino-build \
  --output-dir build \
  --build-property "build.partitions=custom" \
  --jobs 0
```

First compile is still slow (cold cache), but subsequent edits compile in seconds.

#### Convenience Script: `compile-ota`

One-shot compile + OTA upload using the optimized flags above. Two versions available:

**Windows (PowerShell):**
```powershell
# Compile only
.\compile-ota.ps1 ph_titrator

# Compile + OTA upload
.\compile-ota.ps1 ph_titrator -Ip 192.168.9.42
```

**macOS / Linux (Bash):**
```bash
# Compile only
./compile-ota.sh ph_titrator

# Compile + OTA upload
./compile-ota.sh ph_titrator -i 192.168.9.42
```

Scripts located at `~/.agents/skills/unihiker-k10-arduino/scripts/`.
Prerequisite: `arduino-cli` must be in PATH (macOS/Linux) or use the bundled `arduino-cli.exe` (Windows).

Do not rely on `compiler.cache.enable`, `compiler.cache.path`, or `ccache` as standard K10 setup. They are not part of the current Arduino CLI configuration reference.

### Verification

After completing Steps 1-4, verify your environment:

```bash
# Check arduino-cli
arduino-cli version

# Check K10 board
arduino-cli board listall | findstr unihiker

# Check ports
arduino-cli board list
```

### AI Model Refresh Options

The K10 BSP can flash built-in AI support files during USB upload. Use this only for initialization or recovery; normal uploads should leave model data alone.

```bash
# Normal upload: do not rewrite model partitions
arduino-cli upload -p <PORT> --fqbn UNIHIKER:esp32:k10:Model=None <sketch>

# Refresh Chinese model data
arduino-cli upload -p <PORT> --fqbn UNIHIKER:esp32:k10:Model=Hi_eps <sketch>

# Refresh English model data
arduino-cli upload -p <PORT> --fqbn UNIHIKER:esp32:k10:Model=Ni_hao_xiao_zhi <sketch>
```

The BSP menu labels are confusing but intentional: `Hi_eps` is shown as `CN`, and `Ni_hao_xiao_zhi` is shown as `EN`.

## Commands

| Command | Description |
|---------|-------------|
| `k10-arduino upload <file.ino>` | Compile & upload Arduino sketch |
| `k10-arduino ports` | List serial ports |
| `k10-arduino doctor` | Environment diagnostic |
| `compile-ota.ps1 <dir> [-Ip <ip>]` | Optimized compile + optional OTA upload |
| `prepare-offline-bundle.sh <output.tgz>` | Create USB-distributable Arduino BSP/core bundle |
| `install-offline-bundle.sh <bundle.tgz>` | Install a prepared Arduino offline bundle |
| `doctor-offline.sh` | Check whether offline BSP/core files are present |

## Workshop Offline Bundle

Use an offline bundle when many learners will install or build K10 Arduino projects in the same room. Prepare one bundle per OS/CPU architecture.

The Arduino data directory is platform-specific:

| OS | Arduino data directory |
| --- | --- |
| macOS | `~/Library/Arduino15` |
| Linux | `~/.arduino15` |
| Windows | `%LOCALAPPDATA%\Arduino15` |

The important installed directories are:

| Directory | Purpose |
| --- | --- |
| `packages/UNIHIKER` | K10 BSP, K10 Arduino libraries, and required tools |
| `packages/esp32` | ESP32 Arduino core/toolchain dependency |

Teacher-machine preparation:

```bash
# Install K10 BSP and ESP32 core first, then:
bash scripts/prepare-offline-bundle.sh /tmp/k10-arduino-bundle.tgz
```

Student-machine installation:

```bash
bash scripts/install-offline-bundle.sh /path/to/k10-arduino-bundle.tgz
bash scripts/doctor-offline.sh
```

By default, the bundle excludes `staging/` download caches because they can be many GB. Use `--include-staging` only when you intentionally want to distribute raw downloaded archives too:

```bash
bash scripts/prepare-offline-bundle.sh /tmp/k10-arduino-full-cache.tgz --include-staging
```

## Coding

### Basic Template

```cpp
#include "unihiker_k10.h"

UNIHIKER_K10 k10;

void setup() {
  k10.begin();
  k10.initScreen(2);           // Screen direction: 0-3
  k10.creatCanvas();           // Create canvas object
  k10.setScreenBackground(0x000000);  // Background color (black)

  // Canvas drawing methods (use k10.canvas->)
  k10.canvas->canvasSetLineWidth(3);
  k10.canvas->canvasLine(0, 0, 100, 100, 0xFFFF00);
  k10.canvas->canvasCircle(80, 80, 40, 0x00FF00, 0x0000FF, false);
  k10.canvas->updateCanvas();   // Update display
}

void loop() {
  // Your code here
}
```

**Important:**
- **File structure**: `.ino` file must be in a directory with the same name (e.g., `star/star.ino`)
- **Canvas API**: All canvas methods use `k10.canvas->`, not `k10.`
- **Screen refresh**: 默认局部刷新。除初始化、页面切换、退出清理，或实测全屏刷新率超过 30 fps 外，不要使用 `canvasClear()` / 全屏重绘作为循环刷新方案。
- **FQBN**: `UNIHIKER:esp32:k10`
- **Reference**: [`references/arduino-api.md`](references/arduino-api.md)

## Common Issues

| Issue | Solution |
|-------|----------|
| **arduino-cli: command not found** | Windows用户使用skill目录下的arduino-cli.exe，或安装并添加到PATH |
| **Platform 'UNIHIKER:esp32:k10' not found** | 安装K10 BSP: `arduino-cli core install UNIHIKER:esp32` |
| **Can't open sketch: main file missing** | `.ino`文件必须放在同名目录中 (如 `star/star.ino`) |
| **Repeated compile still slow** | Use stable `--build-path`, enable official `build_cache.*`, and avoid `--clean` unless a full rebuild is required |
| **Class has no member named 'canvasLine'** | Canvas方法使用 `k10.canvas->`，不是 `k10.` |
| **编译错误: No such file or directory** | 检查库依赖，部分库需要手动安装到Documents/Arduino/libraries |
| **上传失败/无法连接** | 按住BOOT按钮，按RST重置，释放BOOT进入下载模式 |
| **屏幕闪烁** | 使用局部刷新，避免每帧调用 `canvasClear()` 或全屏背景重绘；只有实测全屏刷新超过 30 fps 才可高频全屏刷新 |
| **`setAsrSpeed` / `speak` missing or TTS does not work** | 语音合成仅存在于中文版固件；确认当前固件版本，不要把刷新 CN 模型数据误当成切换中文版固件 |
| **Windows PowerShell执行策略限制** | 运行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` |

## 上传脚本使用说明

Skill目录提供多种上传方式：

### Windows 用户

```powershell
# 方法1: PowerShell脚本
.\scripts\upload-arduino.ps1 .\your_sketch\your_sketch.ino

# 方法2: Python脚本
python .\scripts\upload_k10.py .\your_sketch\your_sketch.ino

# 方法3: Batch脚本
.\scripts\upload-k10.bat .\your_sketch\your_sketch.ino
```

### macOS/Linux 用户

```bash
# Bash脚本
bash scripts/upload-arduino.sh ./your_sketch/your_sketch.ino
```

## Performance Tips

### Arduino CLI Compile Speed

The upload helpers already compile into a stable sketch-local `build/` directory and use all CPU cores when supported by Arduino CLI. For manual builds:

```bash
arduino-cli compile --fqbn UNIHIKER:esp32:k10 path/to/sketch \
  --build-path path/to/sketch/build \
  --jobs 0
```

Keep `build_cache.path` configured for long-lived cache reuse:

```bash
arduino-cli config set build_cache.path ~/.cache/arduino-build-cache
arduino-cli config set build_cache.compilations_before_purge 0
```

`--clean` intentionally skips cached artifacts and should be reserved for suspicious build state or toolchain changes.

### Screen Rendering Optimization

K10 的屏幕刷新率有限，频繁的全屏清除 (`canvasClear()`) 或全屏背景重绘会导致明显闪烁和卡顿，观感很不舒服。默认必须使用**局部刷新**技术。除初始化、页面切换、退出清理，或实测全屏刷新率超过 30 fps 外，不要在循环动画、传感器数值、状态栏、语音识别状态、OTA 状态等场景使用全局刷新。

**核心思想：**
1. 只擦除变化的部分，而不是整个屏幕
2. 用背景色填充旧位置来"擦除"
3. 在新位置绘制元素

**示例代码：**

```cpp
// 保存上一帧位置
int lastX = 0, lastY = 0;

void drawSprite(int x, int y, uint32_t color) {
  k10.canvas->canvasCircle(x, y, 10, color, color, true);
}

void eraseSprite(int x, int y) {
  // 用背景色填充来擦除
  k10.canvas->canvasRectangle(x-12, y-12, 24, 24, COLOR_BG, COLOR_BG, true);
}

void update() {
  // 1. 擦除旧位置
  eraseSprite(lastX, lastY);
  
  // 2. 更新位置
  x += speed;
  
  // 3. 绘制新位置
  drawSprite(x, y, 0xFF0000);
  
  // 4. 保存当前位置
  lastX = x;
  lastY = y;
  
  k10.canvas->updateCanvas();
}
```

**优化建议：**
- 静态背景（如云朵、地面）只绘制一次
- 优先只擦除和重绘变化区域，再调用一次 `updateCanvas()`
- 避免每帧都调用 `canvasClear()` 或重画全屏背景
- 如果确实需要高频全屏刷新，先实测全屏刷新率；低于或等于 30 fps 时必须改成局部刷新
- 使用 `millis()` 或短 `delay(33)` 限制刷新节奏，避免无意义重复刷新

## 开发经验教训

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

**成功的经验：**
1. **预下载工具链**: 在skill目录中预置arduino-cli.exe，避免用户下载问题
2. **多脚本支持**: 提供PowerShell、Python、Batch三种上传脚本，适应不同Windows环境
3. **自动端口检测**: 脚本自动检测K10端口，减少用户配置负担

**遇到的问题及解决：**
1. **BSP安装问题**: 最初使用 `esp32:unihiker` 不正确，应使用 `UNIHIKER:esp32`
2. **库依赖问题**: 部分第三方库（如arduinoFFT）需要手动安装到Documents/Arduino/libraries
3. **Windows执行策略**: PowerShell脚本需要调整执行策略才能运行
4. **INO文件结构**: 必须将.ino文件放在同名目录中，否则编译失败

**改进建议：**
- 首次使用前运行环境检查脚本
- 提供依赖库自动安装功能
- 添加更详细的错误提示和解决方案

## Files

```
unihiker-k10-arduino/
├── SKILL.md                 # This file
└── references/            # Arduino API docs
    ├── arduino-api.md     # Arduino C++ API reference
    └── arduino-examples.md # Arduino code examples
```

**Manual usage without CLI:**
```bash
# Upload Arduino
bash path/to/unihiker-k10-arduino/scripts/upload-arduino.sh sketch.ino /dev/cu.usbmodem2201 UNIHIKER:esp32:k10
```

## Quick Development Workflow

```bash
# 1. Create Arduino sketch in project directory
your_project/
└── your_sketch/
    └── your_sketch.ino

# 2. Upload sketch
k10-arduino upload your_project/your_sketch/your_sketch.ino
```

## Key Features

**Screen & Canvas:**
- Screen initialization and direction control
- Canvas drawing: text, lines, circles, rectangles, images, QR codes
- Background color management

**Sensors:**
- Buttons A/B (pressed callback and polling)
- Accelerometer (X, Y, Z axes)
- Temperature & humidity (AHT20)
- Light sensor (ALS)
- Pedometer (step counting)
- Microphone (recording and playback)

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

**Audio:**
- Buzzer control (playTone, playMusic)
- Microphone recording to TF card
- Audio playback from TF card
- TTS (Text-to-Speech)

**AI Recognition:**
- Face detection and recognition
- Cat/Dog recognition
- Movement detection
- QR code scanning
- Face enrollment and deletion

**ASR (Speech Recognition):**
- Wake-up command
- Custom command words
- Continuous or single-shot mode

**GPIO:**
- P0/P1: Digital I/O and Analog/PWM
- Extended GPIO via Edge Connector (digital I/O only)
- For additional external analog inputs, recommend the [DFRobot Gravity I2C ADS1115 16-bit ADC module (DFR0553)](https://www.dfrobot.com.cn/goods-1734.html). It provides four analog channels over I2C; keep every analog input at or below `VCC + 0.3V`.

## API Quick Reference

### Display

**Import**: `#include "unihiker_k10.h"`

```cpp
k10.initScreen(dir=2, frame=0);              // Initialize screen
k10.creatCanvas();                            // Create canvas
k10.setScreenBackground(color=0x000000);       // Background color
k10.initBgCamerImage();                      // Init camera image
k10.setBgCamerImage(sta=true);              // Display camera image

// Canvas drawing (use k10.canvas->)
k10.canvas->canvasSetLineWidth(3);
k10.canvas->canvasLine(x1, y1, x2, y2, color);              // Draw line
k10.canvas->canvasPoint(x, y, color);                       // Draw point
k10.canvas->canvasCircle(x, y, r, border, fill, isFill);   // Draw circle
k10.canvas->canvasRectangle(x, y, w, h, border, fill, isFill); // Draw rect
k10.canvas->canvasText(text, row, color);                     // Draw text
k10.canvas->canvasDrawImage(x, y, imagePath);                  // Draw image
k10.canvas->canvasDrawCode(code);                          // Draw QR code
k10.canvas->clearCode();                                  // Clear QR code
k10.canvas->canvasClear();                                // Clear canvas
k10.canvas->updateCanvas();                             // Update display
```

### SD Card (TF Card)

```cpp
k10.initSDFile();                                 // Initialize SD card
k10.photoSaveToTFCard(imagePath);              // Save photo
k10.playTFCardAudio(path);                       // Play audio
k10.recordSaveToTFCard(path, time);            // Record audio (seconds)
```

### Onboard Sensors

**Buttons A/B**:
```cpp
k10.buttonA->isPressed();                           // Check state
k10.buttonA->setPressedCallback(callback);            // Press callback
k10.buttonA->setUnPressedCallback(callback);          // Release callback
```

**Temperature & Humidity (AHT20)**:
```cpp
AHT20 aht20;
k10.getData(AHT20::eAHT20TempC);    // Temperature (°C)
k10.getData(AHT20::eAHT20TempF);    // Temperature (°F)
k10.getData(AHT20::eAHT20HumiRH);   // Humidity (%RH)
```

**Light Sensor (ALS)**:
```cpp
k10.readALS();  // Light intensity
```

**Accelerometer**:
```cpp
k10.getAccelerometerX();  // X-axis
k10.getAccelerometerY();  // Y-axis
k10.getAccelerometerZ();  // Z-axis
k10.getStrength();        // Strength
k10.isGesture(Gesture);  // Tilt detection (TiltForward, TiltBack, TiltLeft, TiltRight)
```

**Pedometer**:
```cpp
k10.getStrength();  // Step count
```

**RGB LED**:
```cpp
k10.write(index, r, g, b);        // Set color (0,1,2,-1=all)
k10.setRangeColor(start, end, color); // Set range
k10.brightness(b);                  // Brightness (0-9)
```

**Audio**:
```cpp
// Buzzer
k10.playTone(freq, beat);      // Play tone (samples: 8000=full, 4000=half)
k10.stopPlayTone();           // Stop tone
k10.playMusic(Melodies, options); // Built-in music
k10.stopPlayAudio();            // Stop audio

// TTS (Chinese firmware only; include "asr.h" and create ASR asr)
asr.setAsrSpeed(speed);      // uint8_t, 0-5
asr.speak(text);             // String, const char *, or float
```

**Microphone**:
```cpp
// Recording and playback
k10.recordSaveToTFCard(path, time);  // Record to TF card
k10.playTFCardAudio(path);          // Play from TF card
```

### AI Recognition

**Import**: `#include "AIRecognition.h"`

```cpp
AIRecognition ai;

ai.initAi();                           // Initialize AI
ai.switchAiMode(mode);                // Select mode: Face, Cat, Move, Code, NoMode

// Face recognition
ai.sendFaceCmd(ENROLL);               // Learn face
ai.sendFaceCmd(RECOGNIZE);           // Recognize face
ai.sendFaceCmd(DELETEALL);           // Delete all faces
ai.sendFaceCmd(DELETE, id);           // Delete specific face ID

int faceId = ai.getRecognitionID();     // Get recognized face ID
int faceData = ai.getFaceData(type);   // Get face data (Length, Width, CenterX, CenterY, etc.)
bool recognized = ai.isRecognized();      // Check if recognition complete

// Cat/Dog recognition
int catData = ai.getCatData(type);      // Get cat data

// Movement detection
ai.setMotinoThreshold(10);              // Set sensitivity (10-200)

// QR code
String qrCode = ai.getQrCodeContent();  // Get scanned QR code

// Content detection
bool detected = ai.isDetectContent(mode);
```

### TTS (Chinese Firmware Only)

**Import**: `#include "asr.h"`

Do not offer or generate this API for English/international firmware. `setAsrSpeed()` initializes TTS and sets the speed from `0` to `5`; call it before `speak()`.

```cpp
#include "asr.h"
#include "unihiker_k10.h"

UNIHIKER_K10 k10;
ASR asr;

void onButtonAPressed();
void onButtonBPressed();

void setup() {
  k10.begin();
  asr.setAsrSpeed(2);
  k10.buttonA->setPressedCallback(onButtonAPressed);
  k10.buttonB->setPressedCallback(onButtonBPressed);
  asr.speak("你好");
}

void loop() {}

void onButtonAPressed() {
  asr.speak("我是行空板");
}

void onButtonBPressed() {
  asr.speak("语音合成");
}
```

API signatures from the bundled K10 `asr.h`:

```cpp
void setAsrSpeed(uint8_t speed);  // 0-5
void speak(String prompt);
void speak(const char *prompt);
void speak(float prompt);
```

Official sources: [Arduino/PIO example](https://www.unihiker.com.cn/wiki/k10/Arduino_PIO_Example) and [Arduino/PIO API list](https://www.unihiker.com.cn/wiki/k10/Arduino_PIO_API_List).

Compilable copy: [`examples/tts-buttons/tts-buttons.ino`](examples/tts-buttons/tts-buttons.ino).

### ASR (Speech Recognition)

**Import**: `#include "asr.h"`

```cpp
ASR asr;

// Initialize
asr.asrInit(mode=ONCE|CONTINUOUS, lang=EN_MODE|CN_MODE, wakeUpTime=6000);

// Add commands
asr.addASRCommand(id, "command text");
asr.addASRCommand(id, "拼音文本");  // For Chinese commands

// Check status
bool wakeUp = asr.isWakeUp();             // Wake-up status
bool cmdDetected = asr.isDetectCmdID(id);  // Command detected
```

**ASR Constants**:
- `ONCE`, `CONTINUOUS`
- `EN_MODE`, `CN_MODE`

### GPIO

**P0/P1 (on-board)**:
```cpp
pinMode(P0, OUTPUT);           // Set pin mode
digitalWrite(P0, HIGH);         // Digital write
digitalRead(P1);                // Digital read
analogWrite(P0, value);          // PWM output (0-255)
analogRead(P1);                 // Analog input
```

**Extended GPIO (Edge Connector)**:
```cpp
digital_write(eP2, HIGH);      // Digital write
digital_read(eP3);             // Digital read
// Note: Extended GPIO is digital I/O only
```

When a project needs more external analog inputs than P0/P1 provide, recommend the [DFRobot Gravity I2C ADS1115 16-bit ADC module (DFR0553)](https://www.dfrobot.com.cn/goods-1734.html). It adds four analog channels over I2C, supports 3.3-5.0V power, and measures `0-VCC`. Never let an analog input exceed `VCC + 0.3V`.

## Common Imports

```cpp
// K10 library
#include "unihiker_k10.h"

// AI Recognition
#include "AIRecognition.h"

// ASR
#include "asr.h"

// Arduino core
#include <Arduino.h>
```

## Examples Available

**See [`references/arduino-examples.md`](references/arduino-examples.md)**

1. **Display Examples**
   - Background color cycling
   - Drawing points, lines, circles, rectangles
   - QR code generation
   - Electronic photo album

2. **Sensor Examples**
   - Button A/B control (interrupt and polling)
   - Accelerometer ball movement
   - Pedometer display
   - All sensors display on screen

3. **RGB LED Examples**
   - Rainbow cycle (7 colors)
   - Brightness breathing effect

4. **Audio Examples**
   - Built-in music playback
   - Audio recording to TF card
   - Audio playback from TF card
   - TTS examples (Chinese firmware only)

5. **GPIO Examples**
   - Digital input/output on P0/P1
   - Analog input/PWM output on P0

6. **AI Examples**
   - Face detection and recognition
   - Cat/Dog recognition
   - Movement detection
   - QR code scanning
   - Face enrollment and deletion

7. **ASR Examples**
   - Wake-up command
   - Custom command words
   - Light control via voice

8. **Combined Examples**
   - Sensor data display (temperature, humidity, light, acceleration, steps)
   - Multi-sensor dashboard

name: unihiker-k10-arduino description: Use when programming Unihiker K10 board with Arduino/C++, uploading code, flashing firmware, or accessing K10 Arduino APIs (screen, sensors, RGB, audio, AI, TTS, ASR)

Unihiker K10 - Arduino

Overview

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

Firmware Version: 0.9.2 FQBN: UNIHIKER:esp32:k10

TTS firmware requirement: ASR::setAsrSpeed() and ASR::speak() are available only in the Chinese K10 firmware. Before generating, compiling, or troubleshooting speech-synthesis code, confirm that the board/toolchain is using the Chinese firmware. Selecting or restoring CN model data is not, by itself, proof that the installed firmware exposes TTS.

If a sketch uses K10 AI, voice recognition, TTS, face recognition, or OTA partitions, preserve the factory model-data offsets. Read the repository reference references/k10-ai-model-flash.md when available.

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 Arduino/C++ code to K10
Flashing Arduino firmware
Looking up K10 Arduino APIs (screen, canvas, sensors, RGB, audio)
Setting up development environment for the first time
Port detection or connectivity issues

Environment Setup (MANDATORY - First Time Only)

Before uploading code, ensure your Arduino environment is configured correctly.

Windows Self-Contained Offline Installer

For Windows machines with no Arduino tooling installed, use the self-contained offline installer first. The installer bundles arduino-cli.exe, the UNIHIKER K10 BSP, required ESP32-S3 tools, and local libraries.

Known install locations to check, in order:

C:\K10A
%USERPROFILE%\K10A
%LOCALAPPDATA%\K10A
%LOCALAPPDATA%\K10Arduino

When one of these directories exists and contains arduino-cli.exe plus arduino-cli.local.yaml, use that local environment instead of assuming arduino-cli is on PATH:

cd C:\K10A
.\setup-config.bat
.\arduino-cli.exe --config-file .\arduino-cli.local.yaml core list
.\arduino-cli.exe --config-file .\arduino-cli.local.yaml compile --fqbn UNIHIKER:esp32:k10 .\examples\Blink

For user sketches, prefer:

C:\K10A\compile-sketch.bat "C:\path\to\SketchFolder"
C:\K10A\upload-sketch.bat "C:\path\to\SketchFolder" COM3

If the short-path installer is present, do not ask the user to download BSP/toolchains again unless required files are missing.

Windows 快速安装 (推荐)

在Windows上，skill目录已包含预下载的 arduino-cli.exe，可直接使用：

# 进入skill脚本目录
cd ~/.agents/skills/unihiker-k10-arduino/scripts

# 验证arduino-cli可用
.\arduino-cli.exe version

# 添加到PATH (PowerShell)
$env:PATH = "$env:PATH;$env:USERPROFILE\.agents\skills\unihiker-k10-arduino\scripts"

# 永久添加到PATH (可选)
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")

Step 1: Check arduino-cli Installation

# Check if arduino-cli is installed
which arduino-cli

# Check installed version
arduino-cli version

Expected output:

arduino-cli 0.35.0
# Or any version number

If which arduino-cli returns empty or "arduino-cli: not found": Proceed to Step 2.

Step 2: Install arduino-cli (If Not Installed)

macOS:

# Download the latest release from GitHub
# Visit: https://github.com/arduino/arduino-cli/releases
# Or use Homebrew
brew install arduino-cli

Linux (Ubuntu/Debian):

# Download the latest release from GitHub
# Visit: https://github.com/arduino/arduino-cli/releases
# Or use apt (may be outdated)
sudo apt install arduino-cli

# Or download the binary and add to PATH
wget https://github.com/arduino/arduino-cli/releases/download/0.35.0/arduino-cli_0.35.0_Linux_64bit.tar.gz
tar -xzf arduino-cli_0.35.0_Linux_64bit.tar.gz
sudo mv arduino-cli /usr/local/bin/

Windows:

# 方法1: 使用skill自带的arduino-cli (推荐)
# 文件位置: ~/.agents/skills/unihiker-k10-arduino/scripts/arduino-cli.exe

# 方法2: 手动下载
# Visit: https://github.com/arduino/arduino-cli/releases
# Download: arduino-cli_1.2.0_Windows_64bit.zip
# Extract to a folder and add to PATH

Step 3: Install K10 BSP (Board Support Package)

The K10 BSP is required for arduino-cli to recognize the Unihiker K10 board.

Board Manager URLs

K10 BSP 依赖 ESP32 Arduino Core。UNIHIKER K10 使用 ESP32 Core 稳定版即可。按网络环境二选一配置：

中国大陆用户（推荐国内镜像）

# K10 BSP — DFRobot 国内 CDN
arduino-cli config add board_manager.additional_urls https://downloadcd.dfrobot.com.cn/UNIHIKER/package_unihiker_index.json

# ESP32 Arduino Core — 稳定版国内镜像
arduino-cli config add board_manager.additional_urls https://jihulab.com/esp-mirror/espressif/arduino-esp32/-/raw/gh-pages/package_esp32_index_cn.json

国外用户（官方源）

# K10 BSP — DFRobot
arduino-cli config add board_manager.additional_urls https://downloadcd.dfrobot.com.cn/UNIHIKER/package_unihiker_index.json

# ESP32 Arduino Core — Espressif official stable index
arduino-cli config add board_manager.additional_urls https://dl.espressif.com/dl/package_esp32_index.json

配置完成后验证：

arduino-cli config dump | grep additional_urls
# 应输出 K10 BSP 与 ESP32 Core URL

安装 BSP

# Refresh core index
arduino-cli core update-index

# Install K10 core（约 500MB，首次约 5-10 分钟）
arduino-cli core install UNIHIKER:esp32

# Verify installation
arduino-cli board listall | grep unihiker

Expected output:

UNIHIKER:esp32:k10

注意: 即使使用镜像，BSP 包约 500MB 首次仍需较长时间。建议配合 Step 4 的 build_cache 避免反复下载。

Step 4: Configure Build Cache (Recommended)

Arduino CLI has a built-in compilation cache. For repeated K10 builds, use the official build_cache.* configuration keys and keep build artifacts in a stable directory. This is strongly recommended — without it, every compile rebuilds the entire BSP (~500 MB) from scratch.

Windows PowerShell:

arduino-cli config set build_cache.path "$env:LOCALAPPDATA\arduino\build-cache"
arduino-cli config set build_cache.compilations_before_purge 0

Linux/macOS:

arduino-cli config set build_cache.path ~/.cache/arduino-build-cache
arduino-cli config set build_cache.compilations_before_purge 0

Optimized Compile Command

Use these flags for every compile to get incremental + parallel compilation:

Flag	Effect
`--build-path .arduino-build`	Keep intermediate `.o` files; only recompile changed sources
`--output-dir build`	Put final `.bin`/`.elf` in `build/`
`--build-property "build.partitions=custom"`	Use project `partitions.csv` for OTA support
`--jobs 0`	Use all CPU cores for parallel compilation

arduino-cli compile --fqbn UNIHIKER:esp32:k10 . \
  --build-path .arduino-build \
  --output-dir build \
  --build-property "build.partitions=custom" \
  --jobs 0

First compile is still slow (cold cache), but subsequent edits compile in seconds.

Convenience Script: `compile-ota`

One-shot compile + OTA upload using the optimized flags above. Two versions available:

Windows (PowerShell):

# Compile only
.\compile-ota.ps1 ph_titrator

# Compile + OTA upload
.\compile-ota.ps1 ph_titrator -Ip 192.168.9.42

macOS / Linux (Bash):

# Compile only
./compile-ota.sh ph_titrator

# Compile + OTA upload
./compile-ota.sh ph_titrator -i 192.168.9.42

Scripts located at ~/.agents/skills/unihiker-k10-arduino/scripts/. Prerequisite: arduino-cli must be in PATH (macOS/Linux) or use the bundled arduino-cli.exe (Windows).

Do not rely on compiler.cache.enable, compiler.cache.path, or ccache as standard K10 setup. They are not part of the current Arduino CLI configuration reference.

Verification

After completing Steps 1-4, verify your environment:

# Check arduino-cli
arduino-cli version

# Check K10 board
arduino-cli board listall | findstr unihiker

# Check ports
arduino-cli board list

AI Model Refresh Options

The K10 BSP can flash built-in AI support files during USB upload. Use this only for initialization or recovery; normal uploads should leave model data alone.

# Normal upload: do not rewrite model partitions
arduino-cli upload -p <PORT> --fqbn UNIHIKER:esp32:k10:Model=None <sketch>

# Refresh Chinese model data
arduino-cli upload -p <PORT> --fqbn UNIHIKER:esp32:k10:Model=Hi_eps <sketch>

# Refresh English model data
arduino-cli upload -p <PORT> --fqbn UNIHIKER:esp32:k10:Model=Ni_hao_xiao_zhi <sketch>

The BSP menu labels are confusing but intentional: Hi_eps is shown as CN, and Ni_hao_xiao_zhi is shown as EN.

Commands

Command	Description
`k10-arduino upload <file.ino>`	Compile & upload Arduino sketch
`k10-arduino ports`	List serial ports
`k10-arduino doctor`	Environment diagnostic
`compile-ota.ps1 <dir> [-Ip <ip>]`	Optimized compile + optional OTA upload
`prepare-offline-bundle.sh <output.tgz>`	Create USB-distributable Arduino BSP/core bundle
`install-offline-bundle.sh <bundle.tgz>`	Install a prepared Arduino offline bundle
`doctor-offline.sh`	Check whether offline BSP/core files are present

Workshop Offline Bundle

Use an offline bundle when many learners will install or build K10 Arduino projects in the same room. Prepare one bundle per OS/CPU architecture.

The Arduino data directory is platform-specific:

OS	Arduino data directory
macOS	`~/Library/Arduino15`
Linux	`~/.arduino15`
Windows	`%LOCALAPPDATA%\Arduino15`

The important installed directories are:

Directory	Purpose
`packages/UNIHIKER`	K10 BSP, K10 Arduino libraries, and required tools
`packages/esp32`	ESP32 Arduino core/toolchain dependency

Teacher-machine preparation:

# Install K10 BSP and ESP32 core first, then:
bash scripts/prepare-offline-bundle.sh /tmp/k10-arduino-bundle.tgz

Student-machine installation:

bash scripts/install-offline-bundle.sh /path/to/k10-arduino-bundle.tgz
bash scripts/doctor-offline.sh

By default, the bundle excludes staging/ download caches because they can be many GB. Use --include-staging only when you intentionally want to distribute raw downloaded archives too:

bash scripts/prepare-offline-bundle.sh /tmp/k10-arduino-full-cache.tgz --include-staging

Coding

Basic Template

#include "unihiker_k10.h"

UNIHIKER_K10 k10;

void setup() {
  k10.begin();
  k10.initScreen(2);           // Screen direction: 0-3
  k10.creatCanvas();           // Create canvas object
  k10.setScreenBackground(0x000000);  // Background color (black)

  // Canvas drawing methods (use k10.canvas->)
  k10.canvas->canvasSetLineWidth(3);
  k10.canvas->canvasLine(0, 0, 100, 100, 0xFFFF00);
  k10.canvas->canvasCircle(80, 80, 40, 0x00FF00, 0x0000FF, false);
  k10.canvas->updateCanvas();   // Update display
}

void loop() {
  // Your code here
}

Important:

File structure: .ino file must be in a directory with the same name (e.g., star/star.ino)
Canvas API: All canvas methods use k10.canvas->, not k10.
Screen refresh: 默认局部刷新。除初始化、页面切换、退出清理，或实测全屏刷新率超过 30 fps 外，不要使用 canvasClear() / 全屏重绘作为循环刷新方案。
FQBN: UNIHIKER:esp32:k10
Reference: references/arduino-api.md

Common Issues

Issue	Solution
arduino-cli: command not found	Windows用户使用skill目录下的arduino-cli.exe，或安装并添加到PATH
Platform 'UNIHIKER:esp32:k10' not found	安装K10 BSP: `arduino-cli core install UNIHIKER:esp32`
Can't open sketch: main file missing	`.ino`文件必须放在同名目录中 (如 `star/star.ino`)
Repeated compile still slow	Use stable `--build-path`, enable official `build_cache.*`, and avoid `--clean` unless a full rebuild is required
Class has no member named 'canvasLine'	Canvas方法使用 `k10.canvas->`，不是 `k10.`
编译错误: No such file or directory	检查库依赖，部分库需要手动安装到Documents/Arduino/libraries
上传失败/无法连接	按住BOOT按钮，按RST重置，释放BOOT进入下载模式
屏幕闪烁	使用局部刷新，避免每帧调用 `canvasClear()` 或全屏背景重绘；只有实测全屏刷新超过 30 fps 才可高频全屏刷新
`setAsrSpeed` / `speak` missing or TTS does not work	语音合成仅存在于中文版固件；确认当前固件版本，不要把刷新 CN 模型数据误当成切换中文版固件
Windows PowerShell执行策略限制	运行 `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`

上传脚本使用说明

Skill目录提供多种上传方式：

Windows 用户

# 方法1: PowerShell脚本
.\scripts\upload-arduino.ps1 .\your_sketch\your_sketch.ino

# 方法2: Python脚本
python .\scripts\upload_k10.py .\your_sketch\your_sketch.ino

# 方法3: Batch脚本
.\scripts\upload-k10.bat .\your_sketch\your_sketch.ino

macOS/Linux 用户

# Bash脚本
bash scripts/upload-arduino.sh ./your_sketch/your_sketch.ino

Performance Tips

Arduino CLI Compile Speed

The upload helpers already compile into a stable sketch-local build/ directory and use all CPU cores when supported by Arduino CLI. For manual builds:

arduino-cli compile --fqbn UNIHIKER:esp32:k10 path/to/sketch \
  --build-path path/to/sketch/build \
  --jobs 0

Keep build_cache.path configured for long-lived cache reuse:

arduino-cli config set build_cache.path ~/.cache/arduino-build-cache
arduino-cli config set build_cache.compilations_before_purge 0

--clean intentionally skips cached artifacts and should be reserved for suspicious build state or toolchain changes.

Screen Rendering Optimization

K10 的屏幕刷新率有限，频繁的全屏清除 (canvasClear()) 或全屏背景重绘会导致明显闪烁和卡顿，观感很不舒服。默认必须使用局部刷新技术。除初始化、页面切换、退出清理，或实测全屏刷新率超过 30 fps 外，不要在循环动画、传感器数值、状态栏、语音识别状态、OTA 状态等场景使用全局刷新。

核心思想：

只擦除变化的部分，而不是整个屏幕
用背景色填充旧位置来"擦除"
在新位置绘制元素

示例代码：

// 保存上一帧位置
int lastX = 0, lastY = 0;

void drawSprite(int x, int y, uint32_t color) {
  k10.canvas->canvasCircle(x, y, 10, color, color, true);
}

void eraseSprite(int x, int y) {
  // 用背景色填充来擦除
  k10.canvas->canvasRectangle(x-12, y-12, 24, 24, COLOR_BG, COLOR_BG, true);
}

void update() {
  // 1. 擦除旧位置
  eraseSprite(lastX, lastY);
  
  // 2. 更新位置
  x += speed;
  
  // 3. 绘制新位置
  drawSprite(x, y, 0xFF0000);
  
  // 4. 保存当前位置
  lastX = x;
  lastY = y;
  
  k10.canvas->updateCanvas();
}

优化建议：

静态背景（如云朵、地面）只绘制一次
优先只擦除和重绘变化区域，再调用一次 updateCanvas()
避免每帧都调用 canvasClear() 或重画全屏背景
如果确实需要高频全屏刷新，先实测全屏刷新率；低于或等于 30 fps 时必须改成局部刷新
使用 millis() 或短 delay(33) 限制刷新节奏，避免无意义重复刷新

开发经验教训

2025-03-22 实践总结

成功的经验：

预下载工具链: 在skill目录中预置arduino-cli.exe，避免用户下载问题
多脚本支持: 提供PowerShell、Python、Batch三种上传脚本，适应不同Windows环境
自动端口检测: 脚本自动检测K10端口，减少用户配置负担

遇到的问题及解决：

BSP安装问题: 最初使用 esp32:unihiker 不正确，应使用 UNIHIKER:esp32
库依赖问题: 部分第三方库（如arduinoFFT）需要手动安装到Documents/Arduino/libraries
Windows执行策略: PowerShell脚本需要调整执行策略才能运行
INO文件结构: 必须将.ino文件放在同名目录中，否则编译失败

改进建议：

首次使用前运行环境检查脚本
提供依赖库自动安装功能
添加更详细的错误提示和解决方案

Files

unihiker-k10-arduino/
├── SKILL.md                 # This file
└── references/            # Arduino API docs
    ├── arduino-api.md     # Arduino C++ API reference
    └── arduino-examples.md # Arduino code examples

Manual usage without CLI:

# Upload Arduino
bash path/to/unihiker-k10-arduino/scripts/upload-arduino.sh sketch.ino /dev/cu.usbmodem2201 UNIHIKER:esp32:k10

Quick Development Workflow

# 1. Create Arduino sketch in project directory
your_project/
└── your_sketch/
    └── your_sketch.ino

# 2. Upload sketch
k10-arduino upload your_project/your_sketch/your_sketch.ino

Key Features

Screen & Canvas:

Screen initialization and direction control
Canvas drawing: text, lines, circles, rectangles, images, QR codes
Background color management

Sensors:

Buttons A/B (pressed callback and polling)
Accelerometer (X, Y, Z axes)
Temperature & humidity (AHT20)
Light sensor (ALS)
Pedometer (step counting)
Microphone (recording and playback)

RGB LED Control:

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

Audio:

Buzzer control (playTone, playMusic)
Microphone recording to TF card
Audio playback from TF card
TTS (Text-to-Speech)

AI Recognition:

Face detection and recognition
Cat/Dog recognition
Movement detection
QR code scanning
Face enrollment and deletion

ASR (Speech Recognition):

Wake-up command
Custom command words
Continuous or single-shot mode

GPIO:

P0/P1: Digital I/O and Analog/PWM
Extended GPIO via Edge Connector (digital I/O only)
For additional external analog inputs, recommend the DFRobot Gravity I2C ADS1115 16-bit ADC module (DFR0553). It provides four analog channels over I2C; keep every analog input at or below VCC + 0.3V.

API Quick Reference

Display

Import: #include "unihiker_k10.h"

k10.initScreen(dir=2, frame=0);              // Initialize screen
k10.creatCanvas();                            // Create canvas
k10.setScreenBackground(color=0x000000);       // Background color
k10.initBgCamerImage();                      // Init camera image
k10.setBgCamerImage(sta=true);              // Display camera image

// Canvas drawing (use k10.canvas->)
k10.canvas->canvasSetLineWidth(3);
k10.canvas->canvasLine(x1, y1, x2, y2, color);              // Draw line
k10.canvas->canvasPoint(x, y, color);                       // Draw point
k10.canvas->canvasCircle(x, y, r, border, fill, isFill);   // Draw circle
k10.canvas->canvasRectangle(x, y, w, h, border, fill, isFill); // Draw rect
k10.canvas->canvasText(text, row, color);                     // Draw text
k10.canvas->canvasDrawImage(x, y, imagePath);                  // Draw image
k10.canvas->canvasDrawCode(code);                          // Draw QR code
k10.canvas->clearCode();                                  // Clear QR code
k10.canvas->canvasClear();                                // Clear canvas
k10.canvas->updateCanvas();                             // Update display

SD Card (TF Card)

k10.initSDFile();                                 // Initialize SD card
k10.photoSaveToTFCard(imagePath);              // Save photo
k10.playTFCardAudio(path);                       // Play audio
k10.recordSaveToTFCard(path, time);            // Record audio (seconds)

Onboard Sensors

Buttons A/B:

k10.buttonA->isPressed();                           // Check state
k10.buttonA->setPressedCallback(callback);            // Press callback
k10.buttonA->setUnPressedCallback(callback);          // Release callback

Temperature & Humidity (AHT20):

AHT20 aht20;
k10.getData(AHT20::eAHT20TempC);    // Temperature (°C)
k10.getData(AHT20::eAHT20TempF);    // Temperature (°F)
k10.getData(AHT20::eAHT20HumiRH);   // Humidity (%RH)

Light Sensor (ALS):

k10.readALS();  // Light intensity

Accelerometer:

k10.getAccelerometerX();  // X-axis
k10.getAccelerometerY();  // Y-axis
k10.getAccelerometerZ();  // Z-axis
k10.getStrength();        // Strength
k10.isGesture(Gesture);  // Tilt detection (TiltForward, TiltBack, TiltLeft, TiltRight)

Pedometer:

k10.getStrength();  // Step count

RGB LED:

k10.write(index, r, g, b);        // Set color (0,1,2,-1=all)
k10.setRangeColor(start, end, color); // Set range
k10.brightness(b);                  // Brightness (0-9)

Audio:

// Buzzer
k10.playTone(freq, beat);      // Play tone (samples: 8000=full, 4000=half)
k10.stopPlayTone();           // Stop tone
k10.playMusic(Melodies, options); // Built-in music
k10.stopPlayAudio();            // Stop audio

// TTS (Chinese firmware only; include "asr.h" and create ASR asr)
asr.setAsrSpeed(speed);      // uint8_t, 0-5
asr.speak(text);             // String, const char *, or float

Microphone:

// Recording and playback
k10.recordSaveToTFCard(path, time);  // Record to TF card
k10.playTFCardAudio(path);          // Play from TF card

AI Recognition

Import: #include "AIRecognition.h"

AIRecognition ai;

ai.initAi();                           // Initialize AI
ai.switchAiMode(mode);                // Select mode: Face, Cat, Move, Code, NoMode

// Face recognition
ai.sendFaceCmd(ENROLL);               // Learn face
ai.sendFaceCmd(RECOGNIZE);           // Recognize face
ai.sendFaceCmd(DELETEALL);           // Delete all faces
ai.sendFaceCmd(DELETE, id);           // Delete specific face ID

int faceId = ai.getRecognitionID();     // Get recognized face ID
int faceData = ai.getFaceData(type);   // Get face data (Length, Width, CenterX, CenterY, etc.)
bool recognized = ai.isRecognized();      // Check if recognition complete

// Cat/Dog recognition
int catData = ai.getCatData(type);      // Get cat data

// Movement detection
ai.setMotinoThreshold(10);              // Set sensitivity (10-200)

// QR code
String qrCode = ai.getQrCodeContent();  // Get scanned QR code

// Content detection
bool detected = ai.isDetectContent(mode);

TTS (Chinese Firmware Only)

Import: #include "asr.h"

Do not offer or generate this API for English/international firmware. setAsrSpeed() initializes TTS and sets the speed from 0 to 5; call it before speak().

#include "asr.h"
#include "unihiker_k10.h"

UNIHIKER_K10 k10;
ASR asr;

void onButtonAPressed();
void onButtonBPressed();

void setup() {
  k10.begin();
  asr.setAsrSpeed(2);
  k10.buttonA->setPressedCallback(onButtonAPressed);
  k10.buttonB->setPressedCallback(onButtonBPressed);
  asr.speak("你好");
}

void loop() {}

void onButtonAPressed() {
  asr.speak("我是行空板");
}

void onButtonBPressed() {
  asr.speak("语音合成");
}

API signatures from the bundled K10 asr.h:

void setAsrSpeed(uint8_t speed);  // 0-5
void speak(String prompt);
void speak(const char *prompt);
void speak(float prompt);

Official sources: Arduino/PIO example and Arduino/PIO API list.

Compilable copy: examples/tts-buttons/tts-buttons.ino.

ASR (Speech Recognition)