Unihiker K10 Platformio

Use when programming a UNIHIKER K10 board with PlatformIO CLI, creating or converting Arduino/C++ K10 projects to PlatformIO, building, uploading, monitoring serial output, diagnosing K10 PlatformIO setup, or preparing/installing offline PlatformIO support bundles for workshops where many students should not download toolchains at the same time.

Overview

Use PlatformIO Core CLI for UNIHIKER K10 Arduino/C++ development. Prefer this skill when the user wants a PlatformIO-based workflow instead of arduino-cli, especially for workshops that need predownloaded support files.

Core PlatformIO environment:

[env:unihiker]
platform = https://github.com/DFRobot/platform-unihiker.git
board = unihiker_k10
framework = arduino
build_flags =
    -DARDUINO_USB_CDC_ON_BOOT=1
    -DARDUINO_USB_MODE=1
    -DModel=None

K10 uses DFRobot's PlatformIO platform and Arduino framework package. First build downloads a large framework and toolchains; avoid doing this from every student machine during a workshop.

If a project 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, or follow the model rules below.

Screen refresh policy: generated K10 display code must prefer partial redraws. Full-screen clearing or full-background redraw causes visible flicker and is uncomfortable; use it only for initialization, page switches, exit cleanup, or when measured full-screen refresh is above 30 fps.

Quick Workflow

Before writing K10 application code, read the relevant local references:

• references/k10-arduino-api.md for K10 C++ API signatures.
• references/k10-arduino-examples.md for working examples, including display, RGB, sensors, audio, AI, TTS, and ASR.

1. Check PlatformIO:

pio --version

If missing, install PlatformIO Core using the official installer script or package manager. Do not use sudo/admin unless the user explicitly needs a system-wide install.

2. Create or normalize a K10 project:

bash path/to/unihiker-k10-platformio/scripts/init-k10-platformio-project.sh my-k10-project

3. Put code in src/main.cpp. For .ino sketches, preserve the same Arduino code but make sure function prototypes/includes are valid C++.

4. Build:

pio run -d my-k10-project

5. Upload:

pio run -d my-k10-project -t upload --upload-port /dev/cu.usbmodemXXXX

If no port is provided, PlatformIO may auto-detect. Use pio device list when upload fails or multiple boards are connected.

6. Monitor serial:

pio device monitor -d my-k10-project --port /dev/cu.usbmodemXXXX

Bundled Scripts

• scripts/init-k10-platformio-project.sh: create a minimal K10 PlatformIO project with sample screen code.
• scripts/k10-pio.sh: convenience wrapper for doctor, ports, build, upload, and monitor.
• scripts/prepare-offline-bundle.sh: build once, collect K10 PlatformIO support files, and create a distributable .tgz.
• scripts/install-offline-bundle.sh: install a prepared bundle into a user's PlatformIO core directory.
• scripts/doctor-offline.sh: verify that the required K10 PlatformIO packages are present before class.
• scripts/k10-pio.ps1 and scripts/install-offline-bundle.ps1: Windows PowerShell helpers for common operations and bundle installation.

Prefer scripts for repeated workshop setup. Read references/platformio-workshop.md before changing offline bundle behavior.

Workshop Offline Bundle

Use an offline bundle when many learners will build K10 projects in the same room.

Expected support-file sizes after first successful build vary by OS/CPU, but the important K10 pieces are roughly:

Directory	Purpose	Typical uncompressed size
platforms/unihiker	DFRobot PlatformIO platform	<1 MB
packages/framework-arduinounihiker	K10 Arduino framework, SDK, libraries	~500 MB
packages/toolchain-xtensa-esp32s3	ESP32-S3 compiler toolchain	~250-300 MB
packages/toolchain-riscv32-esp	RISC-V helper toolchain used by the K10 build	varies, often large
packages/toolchain-xtensa-esp32	Base ESP32 toolchain declared by platform; include when present for conservative bundles	~350-400 MB
packages/tool-esptoolpy	Upload tool	a few MB
packages/tool-scons	Build tool	a few MB
packages/tool-mkfatfs, tool-mklittlefs, tool-mkspiffs	Filesystem image tools used by some upload targets	a few MB

A minimal compressed bundle is typically hundreds of MB. Prepare one bundle per OS/architecture: macOS arm64, macOS Intel, Windows, and Linux are not interchangeable.

Bundle preparation flow:

# On a prepared teacher machine
bash scripts/init-k10-platformio-project.sh /tmp/k10-pio-probe
pio run -d /tmp/k10-pio-probe
bash scripts/prepare-offline-bundle.sh /tmp/k10-platformio-bundle.tgz

Student installation flow:

bash scripts/install-offline-bundle.sh /path/to/k10-platformio-bundle.tgz
bash scripts/doctor-offline.sh
pio run -d my-k10-project

If the student machine still tries to download packages, check that the bundle was built on the same OS/CPU architecture and that it was extracted into the same PlatformIO core directory used by pio.

If build fails with ModuleNotFoundError: No module named 'intelhex' from tool-esptoolpy, repair the local PlatformIO Python environment or reinstall PlatformIO Core. This indicates an incomplete PlatformIO tool dependency, not a K10 source-code error.

Project Conventions

• Use platformio.ini at the project root.
• Use src/main.cpp for code.
• Keep assets/data files in data/ only when using filesystem upload features.
• Use lib/ for private libraries that belong to the project.
• Do not mix arduino-cli FQBN settings with PlatformIO project configuration.
• Keep K10 USB serial flags in build_flags; they are required for expected USB CDC behavior.
• Treat the PlatformIO skill as self-contained. Do not rely on sibling skills or repository-relative paths for API details after installation from ClawHub.

K10 API Notes

• Include K10 board APIs with #include "unihiker_k10.h".
• Include speech recognition with #include "asr.h".
• For animations, dashboards, sensor readouts, voice status, OTA status, and other repeated updates, erase and redraw only the changed region. Do not use canvasClear() or redraw the full background in a loop unless the measured full-screen refresh rate is above 30 fps.
• For ASR command registration, prefer mutable char[] command buffers:

char cmdLightOn[] = "kai deng";
asr.addASRCommand(1, cmdLightOn);

Avoid asr.addASRCommand(id, String("...")) unless the upstream library has been verified fixed. Some K10 ASR library versions recurse in the String overload and can trigger a loopTask stack canary reset.

OTA Notes

PlatformIO's DFRobot platform supports normal USB upload with pio run -t upload. For OTA-style HTTP uploads used by existing K10 Arduino examples, continue using the existing OTA helper pattern only when the firmware exposes the expected /ota endpoint.

For native PlatformIO OTA via ESP OTA, set upload_protocol = espota and upload_port = <ip> only after confirming the firmware and platform support that route.

When combining OTA with K10 built-in AI features, use a partition table that keeps these regions at the factory offsets:

• model at 0x510000, size 4563K
• voice_data at 0x985000, size 2542K
• fr at 0xC01000, size 100K

Use 2.5 MB OTA app slots ending exactly before 0x510000. Do not use generic 6 MB OTA slots for AI projects, because they overlap the model region.

For model recovery or first initialization, add separate USB-only environments:

[env:unihiker]
build_flags =
    -DARDUINO_USB_CDC_ON_BOOT=1
    -DARDUINO_USB_MODE=1
    -DModel=None

[env:unihiker-init-cn]
build_flags =
    -DARDUINO_USB_CDC_ON_BOOT=1
    -DARDUINO_USB_MODE=1
    -DModel=CN

[env:unihiker-init-en]
build_flags =
    -DARDUINO_USB_CDC_ON_BOOT=1
    -DARDUINO_USB_MODE=1
    -DModel=EN

Use unihiker-init-cn for the Chinese model and unihiker-init-en for the English model only when model data may be missing or damaged. Use unihiker for normal app uploads and OTA builds.

References

• Read references/platformio-workshop.md for offline bundle preparation, installation, and troubleshooting.
• Read references/k10-ai-model-flash.md for AI model partitions, OTA compatibility, and recovery workflow.
• Read references/k10-arduino-api.md for K10 API signatures.
• Read references/k10-arduino-examples.md for complete K10 Arduino examples. The C++ APIs are the same as Arduino mode; only the build/upload toolchain changes.