ARCS SDK Toolchain

Provides toolchain capabilities for Claude Code to interact with ARCS hardware: repository pulling, development environment setup, compilation, flashing, running, and log reading.

This skill only handles toolchain operations, not code writing or understanding. Code development, requirement understanding, and bug analysis are handled by Claude Code itself.

Current Status

This skill is still in the development phase. Feedback is welcome during use:

Reproducible stable bugs (preferably with command output/log snippets)
Environment compatibility issues (distributions, Python versions, serial device types, etc.)
Better "trigger phrases/usage examples" (please submit to the
```
docs/
```
directory of the repository, avoid including in the skill package)

Verified Capabilities (Successfully Tested)

Run a sample: The model locates the sample on its own → Compile → Flash → Read logs → Determine success/failure
UI display and iteration: The model first writes a sample that displays a line of text on the UI → Flash and run → Modify the text content → Re-flash and confirm effectiveness

Usage Examples

Examples and trigger phrases can be found in

<skill_dir>/references/usage.md

(loaded on demand to avoid overly long main files).

Batch Mode

Execute compile→flash→verify serially one by one (only one operation can use the serial device at the same time)
Each sample outputs verification results independently, with a summary at the end
A failure of one sample does not affect subsequent ones

Default Configuration

Parameter	Default Value	Description
BOARD	`arcs_evb`	Target development board
Serial Device	Dynamic scanning	Scan `/dev/ttyACM` `/dev/ttyUSB` before each operation
Flashing Baud Rate	`3000000`	cskburn baud rate
Serial Port Baud Rate	`921600`	Log reading baud rate
Flashing Start Address	`0x0`	Flash flashing offset
Repository URL	`https://gitlab.example.com/listenai/arcs-sdk.git`	git clone address (users need to provide the actual address)

Core Principle: Confirm It's Not Occasional Before Handling

When encountering abnormal phenomena, must repeat verification 2-3 times to confirm if it stably reproduces before deciding whether to handle it.

Reproduces every time → Real issue, return to Claude Code for handling
Only occasional → Mark as environmental factor, not treated as code issue

Toolchain Operations

Operation 1: Pull Repository

Execute when the arcs-sdk repository does not exist in the user's environment.

bash

# Clone the repository (user needs to provide the actual repository URL)
git clone <repository URL> arcs-sdk
cd arcs-sdk
git submodule update --init --recursive

If the user does not provide the repository URL, ask the user
If the repository already exists, skip this step and use the existing repository directly
Supports branch switching:
```
git checkout <branch>
```

Operation 2: Install Development Environment

Execute for first-time use or when the toolchain is missing. Need to run two installation scripts:

bash

# 1. Install build tools (cmake, ninja, etc.)
bash prepare_listenai_tools.sh

# 2. Install GCC cross-compilation toolchain (riscv64-unknown-elf-gcc)
bash prepare_toolchain.sh

# 3. Ensure cskburn has execution permission
chmod +x ./tools/burn/cskburn

Check Items:

Whether the
```
listenai-dev-tools/
```
directory exists

Whether

listenai-dev-tools/gcc/bin/riscv64-unknown-elf-gcc

is executable

Whether

listenai-dev-tools/listenai-tools/cmake/bin/cmake

is executable

Whether
```
./tools/burn/cskburn
```
is executable

If all checks pass, skip installation.

Operation 3: Compile

Input: Project path (sample directory or user-created project directory) Output:

build/arcs.bin

firmware file, or compilation error messages

bash

cd <project directory>
bash ./build.sh -C -DBOARD=arcs_evb && bash ./build.sh -r -w -DBOARD=arcs_evb

build.sh Search Strategy:

If there is a
```
build.sh
```
in the project directory → Use it directly
If not → Use the repository root directory's
```
build.sh -S <relative project path>
```

When Compilation Fails:

Return the complete error output to Claude Code, who will analyze and modify the code
Check the corresponding topic in
```
<skill_dir>/references/knowledge.md
```
for known solutions
After Claude Code modifies the code, call this operation again to recompile

Confirm Compilation Product:

Look for
```
.bin
```
files under
```
build/
```
Return the full path and size of the firmware file

Operation 4: Flash

Input: Firmware file path Output: Flash success/failure

Before Flashing:

bash

# Dynamically scan serial devices
ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null
# Confirm no process is occupying
fuser <serial device> 2>/dev/null

Execution:

bash

# Must use the cskburn provided by the repository, must include the -C arcs parameter
./tools/burn/cskburn -C arcs -s <serial device> -b 3000000 0x0 <firmware file path>

Important: Must use
./tools/burn/cskburn
(under the repository root directory), do not use
listenai-dev-tools/listenai-tools/cskburn/cskburn
. The latter is a universal version that does not support the
-C arcs
parameter and lacks the automatic erasure step before flashing, which will cause writing failure.

Example of Normal Flash Output:

Waiting for device...
Entering update mode...
Detected flash size: 16 MB
Erasing region 0x00000000-0x00021000...
Burning partition 1/1... (0x00000000, 130.88 KB)
130.88 KB / 130.88 KB (100.00%)
Resetting...
Finished

Failure Handling:

```
Failed opening device
```
→ The board is not in flashing mode, prompt the user to press BOOT+RESET to enter flashing mode
```
EBUSY
```
→
```
fuser
```
found an occupying process, prompt the user to release it
```
ETIMEDOUT
```
→ Wait 3 seconds, rescan the device number, retry
Device disappears → Wait then rescan
```
/dev/ttyACM*
```

Failed burning partition: 01

→ Check if the cskburn in

listenai-dev-tools

was misused, switch to

./tools/burn/cskburn

Operation 5: Run (Log Reading)

Input: None (automatically executed after flashing) or called independently Output: Serial port log text

Use
serial_read.py
(skill-built script, pure Python stdlib, zero external dependencies):

bash

python3 <skill_dir>/serial_read.py <serial device> -b 921600 -t <reading seconds>

<skill_dir>
refers to the installation directory of this skill, at the same level as SKILL.md.

Parameter Description:

Parameter	Default Value	Description
`-b, --baudrate`	`921600`	Baud rate
`-t, --timeout`	`5`	Read timeout (seconds)
`--dtr`	Not passed (pull low)	If passed, pull high DTR
`--rts`	Not passed (pull low)	If passed, pull high RTS

Features:

Non-TTY environment compatible (
```
O_NOCTTY
```
+
```
select()
```
non-blocking reading)
Pull low DTR and RTS by default (via
```
ioctl TIOCMBIC
```
)
Automatically flush buffer after opening to avoid reading residual data
Real-time output to stdout

Serial Port Issue Handling:

Garbled text → Ensure the baud rate is set correctly (921600), or wait for the board to fully boot before reading
Device disconnection → Close the connection → Wait 2-3 seconds → Rescan devices → Reconnect
No output → Remind the user to press the Reset button, or re-flash
Permission issue → Ensure the user is in the uucp/dialout group
Device occupied → Check for other occupying processes before reading (fuser <serial device>)

Return the logs to Claude Code, who will judge whether the program is running normally.

Operation 6: Check Hardware Connection

Independent operation, can be called at any time.

bash

ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null

Find a unique device → Return the device path
Find multiple devices → Identify with
```
udevadm info
```
then ask the user
Cannot find → Execute
```
lsusb
```
+
```
dmesg | tail -20
```
then inform the user

Common Pipelines

Pipeline A: Run Existing Sample

Claude Code calling sequence:

Check hardware connection
Locate sample directory, read README and source code (done by Claude Code itself)
Compile (Operation 3)
Flash (Operation 4)
Log Reading (Operation 5)
Claude Code compares logs with expected output to judge the result

Pipeline B: Write New Code and Verify

Claude Code calling sequence:

Check hardware connection
Claude Code refers to samples and APIs in the repository to write code
Compile (Operation 3) → If failed, Claude Code modifies code → Recompile (loop)
Flash (Operation 4)
Log Reading (Operation 5)
Claude Code judges whether it meets expectations → If not, modify code → Return to step 3 (loop)

Experience Knowledge Base

File:

<skill_dir>/references/knowledge.md

Organized into 5 topics: Repository Management / Environment Installation / Compilation / Flashing / Serial Port. Read the corresponding topic when encountering issues.

This file is maintained manually by the maintainer, do not modify it with the model.

Self-Optimize SKILL.md

When discovering general issues that should be沉淀到 the skill, do not modify SKILL.md directly, inform the user, and update only after the user agrees.

Notes

This skill only handles toolchain operations: Code writing, requirement understanding, and bug analysis are handled by Claude Code itself
Serial port exclusivity: Flashing and log reading cannot use the same serial port at the same time
Dynamic device number scanning: Scan before each operation, do not hardcode
Confirm exceptions before handling: Repeat verification 2-3 times, handle only after confirming it's not occasional
Safety first: Do not execute dangerous operations like
```
rm -rf
```
Methods to avoid:
- picocom/minicom: Cannot work properly in non-interactive environments (requires TTY)
- pyserial: Requires additional Python package installation, may not be available in restricted environments
- stty + cat: Will echo baud rate in non-TTY environments, and cannot control DTR/RTS signal lines

arcs-dev-tools

NPX Install

Tags

SKILL.md Content (Chinese)

ARCS SDK Toolchain

Current Status

Verified Capabilities (Successfully Tested)

Usage Examples

Batch Mode

Default Configuration

Core Principle: Confirm It's Not Occasional Before Handling

Toolchain Operations

Operation 1: Pull Repository

Operation 2: Install Development Environment

Operation 3: Compile

Operation 4: Flash

Operation 5: Run (Log Reading)

Operation 6: Check Hardware Connection

Common Pipelines

Pipeline A: Run Existing Sample

Pipeline B: Write New Code and Verify

Experience Knowledge Base

Self-Optimize SKILL.md

Notes