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

Security Scan

The skill appears to be a legitimate Arduino uploader for the Unihiker K10, but it contains a few inconsistencies and uses remote install steps (curl|sh, pip installs, nonstandard BSP URL) and potential privileged operations that warrant caution before running.

Purpose & Capability

Name, description, references, and scripts align with an Arduino development/upload tool for the Unihiker K10. However SKILL.md claims a pre-downloaded Windows arduino-cli.exe in the skill directory while the file manifest does not include that binary — minor inconsistency that should be clarified.

Instruction Scope

Runtime instructions and scripts stay within the expected scope (install arduino-cli, install BSP, detect serial port via /dev and sysfs, compile and upload sketches). They do however instruct actions that affect system state: adding items to PATH, changing PowerShell execution policy, creating ~/.k10, and installing libraries via arduino-cli and pip. Port-detection scripts read sysfs/udev and invoke powershell on Windows (expected for device detection).

Install Mechanism

There is no formal install spec but setup.sh pipes a remote installer (curl https://raw.githubusercontent.com/... | sh) and uses pip to install tools. setup.sh also attempts to move binaries into /usr/local/bin (sudo may be used). SKILL.md and scripts reference a board-manager URL hosted at https://downloadcd.dfrobot.com.cn — a vendor-host but not a canonical GitHub release host. Downloading and executing remote scripts and installing packages automatically increases risk and should be reviewed.

Credentials

The skill requests no environment variables, no API keys, and no config paths beyond creating a local ~/.k10 directory. No credentials appear required. That is proportional to the stated purpose. Note: scripts may modify PATH and suggest changing PowerShell execution policy on Windows.

Persistence & Privilege

always:false and no request to modify other skills or global agent configuration. However setup.sh can install system binaries (move to /usr/local/bin) and pip packages, and SKILL.md suggests adding its scripts to the user PATH — these are normal for developer tooling but elevate the skill's system presence and may require sudo.

What to consider before installing

This skill looks coherent for uploading and managing Arduino sketches on a Unihiker K10, but review before running: 1) Do not blindly run setup.sh that pipes remote scripts to sh—inspect the installer script from https://raw.githubusercontent.com first. 2) Verify the Unihiker BSP URL (https://downloadcd.dfrobot.com.cn/...) and any downloaded binaries for authenticity; prefer official GitHub releases where possible. 3) The script may prompt for sudo and will install/move binaries into /usr/local/bin and pip-install packages—consider running in a disposable/VM environment if you have doubts. 4) Note the SKILL.md claim of a bundled Windows arduino-cli.exe is not matched by the manifest—confirm whether a binary is actually included before trusting it. 5) If you only need reference docs, no installation is necessary; only run the upload/setup steps when you accept the risk of installing system-level tooling.

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