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: INLINECODE0

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 快速安装 (推荐)

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

CODEBLOCK0

Step 1: Check arduino-cli Installation

CODEBLOCK1

Expected output:
CODEBLOCK2

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

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

macOS:
CODEBLOCK3

Linux (Ubuntu/Debian):
CODEBLOCK4

Windows:
CODEBLOCK5

Step 3: Install K10 BSP (Board Support Package)

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

CODEBLOCK6

Expected output:
CODEBLOCK7

注意: BSP包大小约500MB，首次下载需要较长时间。

Verification

After completing Steps 1-3, verify your environment:

CODEBLOCK8

Commands

Command	Description
INLINECODE3	Compile & upload Arduino sketch
INLINECODE4

List serial ports | | k10-arduino doctor | Environment diagnostic |

Coding

Basic Template

CODEBLOCK9

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 INLINECODE9
FQBN: INLINECODE10
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

上传脚本使用说明

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

Windows 用户

CODEBLOCK10

macOS/Linux 用户

CODEBLOCK11

Performance Tips

Screen Rendering Optimization

K10 的屏幕刷新率有限，频繁的全屏清除 (canvasClear()) 会导致闪烁和卡顿。推荐使用局部刷新技术：

核心思想：

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

示例代码：

CODEBLOCK12

优化建议：

- 静态背景（如云朵、地面）只绘制一次
降低帧率到 30-40fps 以平衡流畅度和性能
避免每帧都调用 INLINECODE20
使用 delay(25-33) 控制帧率 (对应 30-40fps)

开发经验教训

2025-03-22 实践总结

成功的经验：

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

遇到的问题及解决：

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

改进建议：

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

Files

CODEBLOCK13

Manual usage without CLI:
CODEBLOCK14

Quick Development Workflow

CODEBLOCK15

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)

API Quick Reference

Display

Import: INLINECODE24

CODEBLOCK16

SD Card (TF Card)

CODEBLOCK17

Onboard Sensors

Buttons A/B:
CODEBLOCK18

Temperature & Humidity (AHT20):
CODEBLOCK19

Light Sensor (ALS):
CODEBLOCK20

Accelerometer:
CODEBLOCK21

Pedometer:
CODEBLOCK22

RGB LED:
CODEBLOCK23

Audio:
CODEBLOCK24

Microphone:
CODEBLOCK25

AI Recognition

Import: INLINECODE25

CODEBLOCK26

ASR (Speech Recognition)

Import: INLINECODE26

CODEBLOCK27

ASR Constants:

- ONCE, INLINECODE28
INLINECODE29, INLINECODE30

GPIO

P0/P1 (on-board):
CODEBLOCK28

Extended GPIO (Edge Connector):
CODEBLOCK29

Common Imports

CODEBLOCK30

Examples Available

See 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

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

Unihiker K10 - Arduino

概述

Unihiker K10 板 Arduino 编程的 CLI 工具包。核心原则： 严格遵循参考文档——不要即兴发挥。

固件版本：0.9.2
FQBN：UNIHIKER:esp32:k10

何时使用

- 向 K10 上传 Arduino/C++ 代码
烧录 Arduino 固件
查阅 K10 Arduino API（屏幕、画布、传感器、RGB、音频）
首次搭建开发环境
端口检测或连接问题

环境搭建（必须执行 - 仅首次）

在上传代码之前，请确保您的 Arduino 环境配置正确。

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)

步骤 1：检查 arduino-cli 安装

bash

检查是否安装了 arduino-cli

which arduino-cli

检查已安装的版本

arduino-cli version

预期输出：
bash
arduino-cli 0.35.0

或任何版本号

如果 which arduino-cli 返回空或 arduino-cli: not found： 继续执行步骤 2。

步骤 2：安装 arduino-cli（如果未安装）

macOS：
bash

从 GitHub 下载最新版本

访问：https://github.com/arduino/arduino-cli/releases

或使用 Homebrew

brew install arduino-cli

Linux (Ubuntu/Debian)：
bash

从 GitHub 下载最新版本

访问：https://github.com/arduino/arduino-cli/releases

或使用 apt（可能版本较旧）

sudo apt install arduino-cli

或下载二进制文件并添加到 PATH

wget https://github.com/arduino/arduino-cli/releases/download/0.35.0/arduino-cli0.35.0Linux_64bit.tar.gz tar -xzf arduino-cli0.35.0Linux_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: 手动下载

访问：https://github.com/arduino/arduino-cli/releases

下载：arduino-cli1.2.0Windows_64bit.zip

解压到文件夹并添加到 PATH

步骤 3：安装 K10 BSP（板级支持包）

K10 BSP 是 arduino-cli 识别 Unihiker K10 板所必需的。

bash

将 K10 BSP URL 添加到 arduino-cli

arduino-cli config add boardmanager.additionalurls https://downloadcd.dfrobot.com.cn/UNIHIKER/packageunihikerindex.json

更新核心索引

arduino-cli core update-index

安装 K10 核心

arduino-cli core install UNIHIKER:esp32

验证安装

arduino-cli board listall | findstr unihiker

预期输出：
bash
UNIHIKER:esp32:k10

注意： BSP包大小约500MB，首次下载需要较长时间。

验证

完成步骤 1-3 后，验证您的环境：

bash

检查 arduino-cli

arduino-cli version

检查 K10 板

arduino-cli board listall | findstr unihiker

检查端口

arduino-cli board list

命令

命令	描述
k10-arduino upload <file.ino>	编译并上传 Arduino 草图
k10-arduino ports

列出串行端口 | | k10-arduino doctor | 环境诊断 |

编码

基本模板

cpp
#include unihiker_k10.h

UNIHIKER_K10 k10;

void setup() {
k10.begin();
k10.initScreen(2); // 屏幕方向：0-3
k10.creatCanvas(); // 创建画布对象
k10.setScreenBackground(0x000000); // 背景颜色（黑色）

// 画布绘制方法（使用 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(); // 更新显示
}

void loop() {
// 您的代码在此处
}

重要提示：

- 文件结构：.ino 文件必须放在同名的目录中（例如 star/star.ino）
画布 API：所有画布方法使用 k10.canvas->，而不是 k10.
FQBN：UNIHIKER:esp32:k10
参考：references/arduino-api.md

常见问题

问题	解决方案
arduino-cli: command not found	Windows用户使用skill目录下的arduino-cli.exe，或安装并添加到PATH
Platform UNIHIKER:esp32:k10 not found

上传脚本使用说明

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

Windows 用户

powershell

方法1: PowerShell脚本

.\scripts\upload-arduino.ps1 .\yoursketch\yoursketch.ino

方法2: Python脚本

python .\scripts\uploadk10.py .\yoursketch\your_sketch.ino

方法3: Batch脚本

.\scripts\upload-k10.bat .\yoursketch\yoursketch.ino

macOS/Linux 用户

bash

Bash脚本

bash scripts/upload-arduino.sh ./yoursketch/yoursketch.ino

性能优化提示

屏幕渲染优化

K10 的屏幕刷新率有限，频繁的全屏清除 (canvasClear()) 会导致闪烁和卡顿。推荐使用局部刷新技术：

核心思想：

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

示例代码：

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,

unihiker-k10-arduinoUnihiker K10 Arduino编程