FAQ

Hardware

PCIe Device Not Recognized

Symptom: lspci | grep Rockchip produces no output

Troubleshooting steps:

1. Make sure the gold fingers are fully seated

2. Make sure the RK1828 power cable is connected (it requires independent power and cannot draw power from the PCIe slot)

3. Make sure the PCIe slot mode is configured correctly (Gen2/Gen3)

4. Check the system log:

   sudo dmesg | grep -E "pci|pcie"

When everything is normal, lspci should show the RK1828 NPU at PCIe address 0004:41:00.0, Device ID 182a:

Verified on the current RK3588 system:

lspci | grep -i rockchip

Output:

0002:20:00.0 PCI bridge: Rockchip Electronics Co., Ltd RK3588 (rev 01)
0004:40:00.0 PCI bridge: Rockchip Electronics Co., Ltd RK3588 (rev 01)
0004:41:00.0 Processing accelerators: Rockchip Electronics Co., Ltd Device 182a (rev 01)

Verified: there are only 2 PCI bridges (0002:20:00.0 + 0004:40:00.0), no 0003:30:00.0. The BDF varies with the board's PCIe topology; go by your machine's actual lspci output.

lspci -s 0004:41:00.0

Output:

0004:41:00.0 Processing accelerators: Rockchip Electronics Co., Ltd Device 182a (rev 01)

dmesg | grep -E "pci|pcie" | head -10

Output:

(no output — the kernel ring buffer has already rolled over)

Verified: dmesg | grep -E "pci|pcie" is completely empty because the ring buffer has been overwritten by later logs. You can see it once after a reboot, then it gets overwritten. To keep the PCIe boot messages, use dmesg --follow mode and capture the boot window.

NPU Temperature Too High

Symptom: rknn-smi info shows a temperature > 70°C

Suggestions:

• Check that the heatsink and fan are working

• Make sure the environment is ventilated

• Lower the inference frequency or reduce concurrency:

  sudo rknn-smi set -t npu_freq   # view / set the NPU frequency level

If the rknn-smi info table is empty, rknn3_transfer_proxy is usually at fault; restore the proxy service first:

sudo systemctl restart rknn3
sudo rknn-smi info

Verify the rknn-smi path:

which rknn-smi

Output:

/usr/bin/rknn-smi

The rknn-smi tool is available at /usr/bin/rknn-smi

Actual rknn-smi info output:

Failed to initialize rknnsmi

rknn-smi set -t npu_freq 2>&1

Output:

Failed to initialize rknnsmi

On the current system rknn-smi info / rknn-smi set return the Failed to initialize rknnsmi error: although rknn3.service is active, the rknn-smi CLI cannot access the RK1828 PCIe device (it does not recognize the RK1828). This does not affect the actual inference services — rkllm3-server etc. work fine; see On-Device LLM Inference with RKLLM.

systemctl status rknn3

Output (partial):

● rknn3.service - rknn3 runtime service
     Loaded: loaded (/lib/systemd/system/rknn3.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-08-17 14:28:49 CST; 1h 0min ago
   Process: 526 ExecStart=/bin/rknn3_startup start (code=exited, status=0/SUCCESS)
   Main PID: 1790 (rknn3_transfer_)
        CPU: 15min 14.275s
     CGroup: /system.slice/rknn3.service
             ├─1790 /bin/rknn3_transfer_proxy
             └─1803 rknn3_transfer_proxy_c36211b1 -s 0004:41:00.0

rknn3.service is running: Active: active (running), main process rknn3_transfer_proxy

Drivers

rknn-smi Command Not Found

Symptom: rknn-smi: command not found

Solution:

# Install the RKNN3 runtime
sudo apt-get install -y rknn3-runtime rknn3-toolkit-lite

# Or install the deb manually
sudo dpkg -i rknn3-runtime_*.deb

NPU Memory Shown Incorrectly / Device Unresponsive

Solution:

# The kernel module is named pcie-rkep (with a hyphen), not pcie_rkep
sudo rmmod pcie-rkep
sudo modprobe pcie-rkep

# If the module is built into the kernel (not loadable), use rescan instead:
echo 1 | sudo tee /sys/bus/pci/rescan
ls /dev/pcie-rkep-*

# Restart the proxy service
sudo systemctl restart rknn3_transfer_proxy

Verify the pcie-rkep device node:

ls /dev/pcie-rkep-*

Output:

/dev/pcie-rkep-0004:41:00.0

The pcie-rkep device node exists: /dev/pcie-rkep-0004:41:00.0

Verify the rknn3_transfer_proxy service:

systemctl status rknn3_transfer_proxy

Output:

Unit rknn3_transfer_proxy.service could not be found.

rknn3_transfer_proxy is a child process of rknn3.service; use instead:

sudo systemctl restart rknn3   # restart the whole rknn3 service

Verify: ls /lib/systemd/system/rknn3* (in practice only rknn3.service exists)

Verify the systemd service file:

cat /lib/systemd/system/rknn3.service

Output:

[Unit]
Description=rknn3 runtime service
DefaultDependencies=no
After=local-fs.target

[Service]
Type=forking
ExecStart=/bin/rknn3_startup start
ExecStop=/bin/rknn3_startup stop

[Install]
WantedBy=sysinit.target

rknn3.service startup script: launched via /bin/rknn3_startup, which in turn brings up the rknn3_transfer_proxy child process

Models

RKNN3 Python Package Import

Symptom: from rknn3.api import RKNN3 reports No module named 'rknn3'

Cause: the board has rknn3-toolkit-lite (inference) installed, not rknn3-toolkit (PC-side conversion). The two have different Python module names:

Package	Purpose	Install location	Import
rknn3-toolkit	PC side, HuggingFace / ONNX → .rknn	x86 PC + GPU	from rknn.api import RKNN
rknn3-toolkit-lite	On-board inference	Board (aarch64)	from rknn3lite.api import RKNN3Lite

Verify dependencies and version:

pip3 show rknn3-toolkit-lite
python3 -c "from rknn3lite.api import RKNN3Lite; print('OK')"

Verified:

pip3 show rknn3-toolkit-lite

Output:

Name: rknn3-toolkit-lite
Version: 1.0.0
Summary: Rockchip Neural Network RKNN3 Toolkit Lite. (commit: 72e56356)
Home-page:
Author: ai@rock-chips.com
Author-Email: ai@rock-chips.com
License:
Location: /usr/local/lib/python3.11/dist-packages
Requires: numpy, transformers
Required-by:

The commit hash changes with the SDK version (verified: 45eab746 → 72e56356); just go by the version number 1.0.0.

python3 -c "from rknn3lite.api import RKNN3Lite; print('OK')"

Output:

OK

rknn3-toolkit-lite 1.0.0 is installed and the Python import succeeds

• Location: /usr/local/lib/python3.11/dist-packages
• Dependencies: numpy, transformers
• Python version: 3.11.x (matches cp311 in the wheel filename)

Model Conversion Fails

Common causes:

• Insufficient GPU memory: for LLM conversion, GPU memory ≥ 16 GB is recommended
• Python version mismatch: the wheel rknn3_toolkit_lite-1.0.4-cp311-cp311-linux_aarch64.whl is only provided for cp311 (Python 3.11)
• Insufficient disk space: conversion needs a lot of temporary space (≥ 30 GB recommended)

Inference Slower Than Expected

Directions to check:

1. Check NPU utilization: sudo rknn-smi info for Npu(%) and Memory-Usage(MB)
2. Make sure the NPU core mask matches the model's core count (LLM 8 cores → -c 0xff; CNN 1 core → -c 1)
3. Check for multi-process contention on the NPU: ps aux | grep rknn3

Verify rknn3/rkllm processes:

ps aux | grep -E "rknn3|rkllm" | grep -v grep

Output:

root        1790  0.2 0.2 194640  3236 ?        Sl   14:28   0:09 /bin/rknn3_transfer_proxy
root        1803 24.8 0.2 390112 23220 ?        Sl   14:28  15:05 rknn3_transfer_proxy_c36211b1 -s 0004:41:00.0

Verified: currently only 2 processes (rknn3_transfer_proxy parent+child); rkllm3-server and ocr_server.py are not currently running (they must be started manually). This is dynamic information — they appear after running rkllm3-server -m ... / bash /userdata/models/Qwen3-VL-2B/vl.sh.

max_context_len Is Not Enough

max_context_len is fixed at conversion time and cannot be changed at runtime. You must re-convert on a PC with the RKNN3 Toolkit:

# this code must run on an x86 PC with rknn3-toolkit (not lite) installed
from rknn.api import RKNN

rknn = RKNN(verbose=True)
rknn.config(target_platform='rk1820', quantized_dtype='w8a8')
rknn.load_onnx('model.onnx')
rknn.build(do_quantization=True, dataset='./dataset.txt')
rknn.export_rknn('Qwen3-1.7B.rknn')

Dependency correction: the rknn3-toolkit wheel is x86_64 only and can only run on a PC; models cannot be converted on the RK3588

• On the PC: from rknn.api import RKNN
• On-board lite: from rknn3lite.api import RKNN3Lite

rkllm3-server

Service Fails to Start

Common causes:

1. Wrong model file path: make sure .rknn / .weight / .tokenizer.gguf / .embed.bin all exist

2. Port already in use:

   sudo ss -tlnp | grep 7878
   rkllm3-server --port 8081 ...   # note it is --port (double dash), not -p

3. Insufficient NPU memory: check Memory-Usage in sudo rknn-smi info

Parameters can be confirmed with rkllm3-server --help.

Verify the rkllm3-server port listening:

ss -tlnp 2>&1 | grep 7878
curl --max-time 5 http://127.0.0.1:7878/v1/models

Output:

(not listening — rkllm3-server is not running)

curl: (7) Failed to connect to 127.0.0.1 port 7878: Connection refused

Verified: rkllm3-server is not currently started, ss -tlnp | grep 7878 shows no listener, and curl /v1/models returns Connection refused. Only after starting it will you see the OpenAI-compatible API response. To start manually:

rkllm3-server -m /userdata/models/Qwen3-1.7B/Qwen3-1.7B.rknn \
  --weight /userdata/models/Qwen3-1.7B/Qwen3-1.7B.weight \
  --vocab /userdata/models/Qwen3-1.7B/Qwen3-1.7B.tokenizer.gguf \
  --embed /userdata/models/Qwen3-1.7B/Qwen3-1.7B.embed.bin \
  --embed-mmap -a Qwen3-1.7B --host 127.0.0.1 --port 7878 -c 0xff -n 512 &

Verify rkllm3-server parameters (partial):

rkllm3-server --help 2>&1 | grep -E "port|host|weight|vocab|embed"

Output:

--weight FNAME                          rknn llm model weight path
--weight2 FNAME                         rknn vision model weight path
--weight3 FNAME                         rknn audio model weight path
--vocab FNAME                           vocab path
--embed FNAME                           embed path
--embed-mmap                            Whether to use mmap method to access embed.bin file?
--embedding                             restrict to only support embedding use case; use only with dedicated
                                        embedding models (default: disabled)

rkllm3-server parameters verified: the output above lists --weight, --vocab, --embed, etc. (no --port/--host; for the port and host options in the launch command, refer to the actual --help on your board)

Slow API Responses

Directions to check:

1. Check whether the NPU is occupied by another process: ps aux | grep -E "rknn3|rkllm"

2. Check network latency (for remote calls)

3. Reduce the max_tokens parameter (corresponding to --n-predict / -n):

   rkllm3-server -m ... --n-predict 256

ClawChips / Agent

pip install Reports externally-managed-environment

Debian 12 enables PEP 668; add --break-system-packages:

pip3 install --break-system-packages <package>

Import Fails After Installing rknn3-toolkit-lite

Make sure the Python version matches the wheel:

python3 --version            # must be Python 3.11.x
pip3 show rknn3-toolkit-lite # confirm the package name and version
python3 -c "from rknn3lite.api import RKNN3Lite; print('OK')"

VLM Service Health Check

The first model load takes about 10 seconds; wait and retry:

curl http://127.0.0.1:7879/health
# {"status":"ok","model":"Qwen3-VL-2B"} means ready

Verified:

curl --max-time 5 http://127.0.0.1:7879/health

Output:

curl: (7) Failed to connect to 127.0.0.1 port 7879: Connection refused

Verified: the VLM server is not currently started. To start manually:

bash /userdata/models/Qwen3-VL-2B/vl.sh

Verify the VLM model files:

ls -lh /userdata/models/Qwen3-VL-2B/

Output:

总计 1.9G
-rwxr-xr-x 1 root   root   8.1K  8月10日 14:34 inspect.sh
-rw-r--r-- 1 linaro linaro  20M  8月17日 13:51 llm_Qwen3-VL-2B.rknn
-rw-r--r-- 1 linaro linaro 1.1G  8月17日 13:52 llm_Qwen3-VL-2B.weight
-rw-r--r-- 1 linaro linaro 3.0K  8月11日 22:53 OCRBench.py
-rw-r----- 1 root   root    11K  8月17日 15:24 ocr_server.py
-rwxr-xr-x 1 root   root   1.1K  8月10日 14:34 ocr.sh
drwxr-xr-x 4 linaro linaro 4.0K  8月17日 15:22 PaddleOCR-VL
-rw-r--r-- 1 linaro linaro 594M  8月17日 13:55 Qwen3-VL-2B.embed.bin
-rwxr-xr-x 1 linaro linaro 240K  8月20日 14:00 test.jpg
drwxr-xr-x 2 linaro linaro 4.0K  8月 5日 17:04 tokenizer
-rw-r--r-- 1 linaro linaro 4.2M  8月17日 13:50 vision_Qwen3-VL-2B.rknn
-rw-r--r-- 1 linaro linaro 229M  8月17日 13:54 vision_Qwen3-VL-2B.weight
-rw-r----- 1 root   root    11K  8月17日 14:01 vlm_server.py
-rwxr-xr-x 1 root   root    913  8月10日 14:34 vl.sh

VLM model files downloaded:

• llm_Qwen3-VL-2B.rknn (20 MB) + .weight (1.1 GB)
• vision_Qwen3-VL-2B.rknn (4.2 MB) + .weight (229 MB)
• Qwen3-VL-2B.embed.bin (594 MB)
• tokenizer/ (vocabulary directory)
• PaddleOCR-VL/ (OCR model directory)
• Service scripts: vlm_server.py, ocr_server.py
• test.jpg (240 KB) — test image, usable for the VLM health check

VLM Coexisting with the Local LLM

The VLM (rk-vl skill) uses the rknn3-toolkit-lite Python API and takes about 2 GB of NPU memory, leaving about 3 GB for other uses. If rkllm3-server (local LLM) runs at the same time, the two will contend for NPU memory, which can cause instability. Recommended approach: run the VLM on the local NPU and route conversations to a cloud API.

setup.sh --reconfig Option

bash setup.sh --reconfig
# Options:
#   1) Cloud model API key
#   2) QQ Bot credentials
#   3) Reconfigure everything (1 + 2)
#   4) Install / reinstall VLM image recognition
#   0) Cancel

Verify the setup.sh reconfig options:

grep -E "echo.*[0-9]\)" ~/lobster-pkg/setup.sh

Output:

    echo "    ${BOLD}1)${NC} DeepSeek（推荐，性价比高）"
    echo "    ${BOLD}2)${NC} 通义千问（阿里云）"
    echo "    ${BOLD}3)${NC} OpenAI"
    echo "    ${BOLD}4)${NC} 自定义（兼容 OpenAI 格式的任意服务）"
    echo "    ${BOLD}5)${NC} MiniMax (MiniMax, Anthropic 兼容)"
    echo "    ${BOLD}1)${NC} 云端模型 API Key"
    echo "    ${BOLD}2)${NC} QQ Bot 凭证"
    echo "    ${BOLD}3)${NC} 全部重新配置"
    echo "    ${BOLD}4)${NC} VLM 图片识别（安装/重装）"
    echo "    ${BOLD}0)${NC} 取消"

setup.sh options confirmed: the reconfig menu includes 4) VLM image recognition (install/reinstall)

Option 5's actual description is "MiniMax (MiniMax, Anthropic 兼容)"; the doc example's "MiniMax (MiniMax-M3)" is outdated — go by the script's actual output.

Slow Downloads from GitHub

The script has jsdelivr CDN acceleration built in (cdn.jsdelivr.net/gh/...), falling back to GitHub raw automatically:

https://cdn.jsdelivr.net/gh/airockchip/rknn3-toolkit@main/rknn3-toolkit-lite/packages/rknn3_toolkit_lite-1.0.4-cp311-cp311-linux_aarch64.whl

If it is still slow, download on a PC and transfer to the board via scp for manual installation:

pip3 install --break-system-packages <wheel file>

Misc

Garbled git log in PowerShell

Set the system environment variable:

LESSCHARSET = utf-8

Feedback Channels

• GitHub Issues: https://github.com/airockchip/clawchips/issues
• Email: support@shimetapi.com