Back to Details

arcs-dev-tools

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ARCS SDK 工具链

ARCS SDK Toolchain

为 Claude Code 提供与 ARCS 硬件交互的工具链能力：拉取仓库、安装开发环境、编译、烧录、运行、日志读取。
本 skill 只负责工具链操作，不负责代码编写和理解。 代码开发、需求理解、bug 分析由 Claude Code 本身完成。
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

本 skill 仍处于开发阶段。欢迎在使用过程中反馈：
  • 复现稳定的 bug（最好附上命令输出/日志片段）
  • 环境兼容性问题（发行版、Python 版本、串口设备类型等）
  • 更好的"触发语句/使用示例"（请提交到仓库的 
    docs/
    文档中，避免放进 skill 包内）
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)

  • 运行某个 sample：模型自行定位示例 → 编译 → 烧录 → 读取日志 → 判定成功/失败
  • UI 显示并迭代：模型先写一个在 UI 上显示一行字的示例 → 烧录运行 → 再修改文字内容 → 重新烧录并确认生效
  • 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

示例与触发语句见 
<skill_dir>/references/usage.md
（按需加载，避免主文件过长）。
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

参数默认值说明
BOARD
arcs_evb
目标开发板
串口设备动态扫描每次操作前扫描 
/dev/ttyACM*
/dev/ttyUSB*
烧录波特率
3000000
cskburn 波特率
串口波特率
921600
日志读取波特率
烧录起始地址
0x0
Flash 烧录偏移
仓库地址
https://gitlab.example.com/listenai/arcs-sdk.git
git clone 地址（需用户提供实际地址）
ParameterDefault ValueDescription
BOARD
arcs_evb
Target development board
Serial DeviceDynamic scanningScan 
/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

遇到异常现象时，必须重复验证 2-3 次确认是否稳定复现，再决定是否处理。
  • 每次都复现 → 真实问题，返回给 Claude Code 处理
  • 仅偶发 → 标记为环境因素，不作为代码问题
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

操作 1：拉取仓库

Operation 1: Pull Repository

当用户的环境中还没有 arcs-sdk 仓库时执行。
bash
undefined
Execute when the arcs-sdk repository does not exist in the user's environment.
bash
undefined

克隆仓库（用户需提供实际的仓库地址）

Clone the repository (user needs to provide the actual repository URL)

git clone <仓库地址> arcs-sdk cd arcs-sdk git submodule update --init --recursive

- 如果用户未提供仓库地址，询问用户
- 如果仓库已存在，跳过此步骤，直接使用现有仓库
- 支持切换分支：`git checkout <branch>`
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>`

操作 2：安装开发环境

Operation 2: Install Development Environment

首次使用或工具链缺失时执行。需要运行两个安装脚本：
bash
undefined
Execute for first-time use or when the toolchain is missing. Need to run two installation scripts:
bash
undefined

1. 安装构建工具（cmake、ninja 等）

1. Install build tools (cmake, ninja, etc.)

bash prepare_listenai_tools.sh
bash prepare_listenai_tools.sh

2. 安装 GCC 交叉编译工具链（riscv64-unknown-elf-gcc）

2. Install GCC cross-compilation toolchain (riscv64-unknown-elf-gcc)

bash prepare_toolchain.sh
bash prepare_toolchain.sh

3. 确保 cskburn 有执行权限

3. Ensure cskburn has execution permission

chmod +x ./tools/burn/cskburn

**检查项**：
- `listenai-dev-tools/` 目录是否存在
- `listenai-dev-tools/gcc/bin/riscv64-unknown-elf-gcc` 是否可执行
- `listenai-dev-tools/listenai-tools/cmake/bin/cmake` 是否可执行
- `./tools/burn/cskburn` 是否可执行

如果检查通过，跳过安装。
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.

操作 3：编译

Operation 3: Compile

输入：项目路径（示例目录或用户自建项目目录） 输出：
build/arcs.bin
固件文件，或编译错误信息
bash
cd <项目目录>
bash ./build.sh -C -DBOARD=arcs_evb && bash ./build.sh -r -w -DBOARD=arcs_evb
build.sh 查找策略：
  • 项目目录下有 
    build.sh
    → 直接用
  • 没有 → 用仓库根目录的 
    build.sh -S <项目相对路径>
编译失败时：
  • 将完整错误输出返回给 Claude Code，由 Claude Code 分析并修改代码
  • 查阅 
    <skill_dir>/references/knowledge.md
    对应 topic 看是否有已知解决方案
  • Claude Code 修改代码后，再次调用本操作重新编译
确认编译产物：
  • 在 
    build/
    下查找 
    .bin
    文件
  • 返回固件文件的完整路径和大小
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

操作 4：烧录

Operation 4: Flash

输入：固件文件路径 输出：烧录成功/失败
烧录前：
bash
undefined
Input: Firmware file path Output: Flash success/failure
Before Flashing:
bash
undefined

动态扫描串口设备

Dynamically scan serial devices

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

确认无进程占用

Confirm no process is occupying

fuser <串口设备> 2>/dev/null

**执行**：
```bash
fuser <serial device> 2>/dev/null

**Execution**:
```bash

必须使用仓库自带的 cskburn，必须带 -C arcs 参数

Must use the cskburn provided by the repository, must include the -C arcs parameter

./tools/burn/cskburn -C arcs -s <串口设备> -b 3000000 0x0 <固件文件路径>

> **重要**：必须使用 `./tools/burn/cskburn`（仓库根目录下），**不要**使用 `listenai-dev-tools/listenai-tools/cskburn/cskburn`。
> 后者是通用版本，不支持 `-C arcs` 参数，缺少烧录前自动擦除步骤，会导致写入失败。

**正常烧录输出示例**：
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

**失败处理**：
- `Failed opening device` → 板子未进入烧录模式，提示用户按 BOOT+RESET 进入烧录模式
- `EBUSY` → `fuser` 找到占用进程，提示用户释放
- `ETIMEDOUT` → 等 3 秒，重新扫描设备号，重试
- 设备消失 → 等待后重新扫描 `/dev/ttyACM*`
- `Failed burning partition: 01` → 检查是否误用了 `listenai-dev-tools` 中的 cskburn，换用 `./tools/burn/cskburn`
./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`

操作 5：运行（日志读取）

Operation 5: Run (Log Reading)

输入：无（烧录完成后自动执行）或独立调用 输出：串口日志文本
使用 
serial_read.py
（技能自带脚本，纯 Python stdlib，零外部依赖）：
bash
python3 <skill_dir>/serial_read.py <串口设备> -b 921600 -t <读取秒数>
<skill_dir>
 即本技能安装目录，与 SKILL.md 同级。
参数说明：
参数默认值说明
-b, --baudrate
921600
波特率
-t, --timeout
5
读取超时（秒）
--dtr
不传（拉低）传入则拉高 DTR
--rts
不传（拉低）传入则拉高 RTS
特性：
  • 非 TTY 环境兼容（
    O_NOCTTY
    + 
    select()
    非阻塞读取）
  • 默认拉低 DTR 和 RTS（通过 
    ioctl TIOCMBIC
    ）
  • 打开后自动 flush 缓冲区，避免读到残留数据
  • 实时输出到 stdout
串口问题处理：
  • 乱码 → 确保波特率设置正确（921600），或等板子完全启动后再读
  • 设备断连 → 关闭连接 → 等 2-3 秒 → 重新扫描设备 → 重连
  • 无输出 → 提醒用户按 Reset 键，或重新烧录
  • 权限问题 → 确保用户在 uucp/dialout 组中
  • 设备占用 → 读取前检查是否有其他进程占用（fuser <串口设备>）
日志返回给 Claude Code，由 Claude Code 判断程序是否正常运行。
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:
ParameterDefault ValueDescription
-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.

操作 6：检查硬件连接

Operation 6: Check Hardware Connection

独立操作，可在任意时刻调用。
bash
ls /dev/ttyACM* /dev/ttyUSB* 2>/dev/null
  • 找到唯一设备 → 返回设备路径
  • 找到多个 → 
    udevadm info
    识别后询问用户
  • 找不到 → 
    lsusb
    + 
    dmesg | tail -20
    后告知用户
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

流水线 A：运行现有示例

Pipeline A: Run Existing Sample

Claude Code 调用顺序：
  1. 检查硬件连接
  2. 定位示例目录，阅读 README 和源码（Claude Code 自己做）
  3. 编译（操作 3）
  4. 烧录（操作 4）
  5. 日志读取（操作 5）
  6. Claude Code 对比日志和预期输出，判断结果
Claude Code calling sequence:
  1. Check hardware connection
  2. Locate sample directory, read README and source code (done by Claude Code itself)
  3. Compile (Operation 3)
  4. Flash (Operation 4)
  5. Log Reading (Operation 5)
  6. Claude Code compares logs with expected output to judge the result

流水线 B：编写新代码并验证

Pipeline B: Write New Code and Verify

Claude Code 调用顺序：
  1. 检查硬件连接
  2. Claude Code 参考仓库中的示例和 API，编写代码
  3. 编译（操作 3）→ 失败则 Claude Code 改代码 → 重新编译（循环）
  4. 烧录（操作 4）
  5. 日志读取（操作 5）
  6. Claude Code 判断是否符合预期 → 不符合则改代码 → 回到步骤 3（循环）
Claude Code calling sequence:
  1. Check hardware connection
  2. Claude Code refers to samples and APIs in the repository to write code
  3. Compile (Operation 3) → If failed, Claude Code modifies code → Recompile (loop)
  4. Flash (Operation 4)
  5. Log Reading (Operation 5)
  6. Claude Code judges whether it meets expectations → If not, modify code → Return to step 3 (loop)

经验知识库

Experience Knowledge Base

文件：
<skill_dir>/references/knowledge.md
按 5 个 topic 组织：仓库管理 / 环境安装 / 编译 / 烧录 / 串口。遇到问题时只读对应 topic。
本文件由维护者手动维护，模型不要修改。
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.

自优化 SKILL.md

Self-Optimize SKILL.md

发现应沉淀到 skill 的通用性问题时，不要直接修改 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

  1. 本 skill 只做工具链操作：代码编写、需求理解、bug 分析由 Claude Code 本身完成
  2. 串口独占：烧录和日志读取不能同时使用同一串口
  3. 设备号动态扫描：每次操作前都扫描，不硬编码
  4. 异常先确认再处理：重复验证 2-3 次，确认非偶发后再处理
  5. 安全优先：不执行 
    rm -rf
    等危险操作
  6. 避免使用的方法：
    • picocom/minicom: 在非交互式环境中无法正常工作（需要 TTY）
    • pyserial: 需要额外安装 Python 包，在受限环境中可能不可用
    • stty + cat: 在非 TTY 环境下会回显波特率，且无法控制 DTR/RTS 信号线
  1. This skill only handles toolchain operations: Code writing, requirement understanding, and bug analysis are handled by Claude Code itself
  2. Serial port exclusivity: Flashing and log reading cannot use the same serial port at the same time
  3. Dynamic device number scanning: Scan before each operation, do not hardcode
  4. Confirm exceptions before handling: Repeat verification 2-3 times, handle only after confirming it's not occasional
  5. Safety first: Do not execute dangerous operations like 
    rm -rf
  6. 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