ARCS SDK Toolchain

Current Status

• 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

<skill_dir>/references/usage.md

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

arcs_evb

/dev/ttyACM*

/dev/ttyUSB*

3000000

921600

0x0

https://gitlab.example.com/listenai/arcs-sdk.git

Core Principle: Confirm It's Not Occasional Before Handling

• 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

# 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

# 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

• 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

Operation 3: Compile

build/arcs.bin

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

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

• 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

• Look for

  .bin

  files under

  build/

• Return the full path and size of the firmware file

Operation 4: Flash

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

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

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

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

serial_read.py

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.

-b, --baudrate

921600

-t, --timeout

5

--dtr

--rts

• 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

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

Operation 6: Check Hardware Connection

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

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

Pipeline B: Write New Code and Verify

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

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

Self-Optimize SKILL.md

Notes

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