Unihiker K10 Arduino

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)

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

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，可直接使用：

# 进入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.

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

# Update core index
arduino-cli core update-index

# Install K10 core
arduino-cli core install UNIHIKER:esp32

# Verify installation
arduino-cli board listall | findstr unihiker

Expected output:

UNIHIKER:esp32:k10

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

Verification

After completing Steps 1-3, verify your environment:

# Check arduino-cli
arduino-cli version

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

# Check ports
arduino-cli board list

Commands

Command	Description
k10-arduino upload <file.ino>	Compile & upload Arduino sketch
k10-arduino ports	List serial ports
k10-arduino doctor	Environment diagnostic

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.
• 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)
Class has no member named 'canvasLine'	Canvas方法使用 k10.canvas->，不是 k10.
编译错误: No such file or directory	检查库依赖，部分库需要手动安装到Documents/Arduino/libraries
上传失败/无法连接	按住BOOT按钮，按RST重置，释放BOOT进入下载模式
屏幕闪烁	使用局部刷新，避免每帧调用 canvasClear()，详见性能优化章节
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

Screen Rendering Optimization

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

核心思想：

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

示例代码：

// 保存上一帧位置
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();
}

优化建议：

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

开发经验教训

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:

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

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 (Text-to-Speech)
asr.setAsrSpeed(speed);      // Set speed
asr.speak(text);             // Speak text

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);

ASR (Speech Recognition)

Import: #include "asr.h"

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

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

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

Common Imports

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

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