Environment Setup in Detail

This chapter explains in detail how to get RKNN 3.x model conversion working.

If you only want a quick overview, see ch02 Environment Setup — the 30-second overview.

1. System Requirements

Component	Minimum	Recommended
OS	Ubuntu 20.04	Ubuntu 22.04 LTS
CPU	4-core x86_64	8 cores or more
Memory	8 GB	16 GB or more
Disk	50 GB	100 GB SSD

Model quantization does not need an NVIDIA GPU; pure CPU works.

2. Host Cross-Compile Toolchain

sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

Verify:

aarch64-linux-gnu-gcc --version

Output:

aarch64-linux-gnu-gcc (Debian 12.2.0-14+deb12u1) 12.2.0
Copyright (C) 2022 Free Software Foundation, Inc.

Key Environment Variables

CROSS_COMPILE: aarch64-linux-gnu-
ARCH: arm64
CC: ${CROSS_COMPILE}gcc

3. NPU Development Environment

Install the RKNN 3.x Toolkit

python3 -m venv ~/rk1828-npu-env
source ~/rk1828-npu-env/bin/activate
cd /userdata/RK1820_RK1828_AI_SDK/rknn/rknn3-toolkit/rknn3-toolkit/packages
pip install rknn3_toolkit-*.whl

The RKNN 3.x Toolkit wheel only supports x86_64 (manylinux_2_17_x86_64) and cannot be installed directly on the RK3588 (aarch64) board. You must:
Install it on Ubuntu
Convert models on Ubuntu
Copy the .rknn files to the RK3588 board
The board can only install rknn3-toolkit-lite (inference only, no conversion); the wheels are under rknn/rknn3-toolkit/rknn3-toolkit-lite/packages/, with four Python versions: cp39 / cp310 / cp311 / cp312.

Verify the packages:

ls /userdata/RK1820_RK1828_AI_SDK/rknn/rknn3-toolkit/rknn3-toolkit/packages/

Output:

md5sum.txt
requirements_cp310-1.0.0.txt
requirements_cp312-1.0.0.txt
rknn3_toolkit-1.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
rknn3_toolkit-1.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Verify the installation (inside the virtualenv):

python3 -c "from rknn.api import RKNN; print('RKNN 3.x OK')"

Output:

RKNN 3.x OK

Running directly in the system Python environment reports ModuleNotFoundError: No module named 'rknn'; the venv must be activated first.

Input Models Supported by RKNN 3.x

Training Framework	Export Format	Support
PyTorch	`.pt` / `.onnx`	Recommended
ONNX	`.onnx`	Most stable
TensorFlow	`.pb` / `.tflite`
PaddlePaddle	`.pdmodel`
Caffe	`.caffemodel`	Some operators limited

Verify the PCIe NPU Driver

Device node:

ls /dev/pcie-rkep-*

Output:

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

Driver loading:

lsmod | grep pcie_rkep

Empty output is normal: the driver is built into the kernel, not a loadable module.

PCIe device:

/usr/bin/pcie_upgrade_tool ld 2>&1 | sed 's/\x1b\[[0-9;]*m//g'

Output:

Program directory: /usr/bin/
List of connected rkep devices
Addr=0004:41:00.0 [1d87:182a]

Service status:

systemctl is-active rknn3.service

Output:

active

4. On-Board NPU Firmware Loading

Firmware location:

ls -lh /lib/firmware/rknn3_rk1820.img

Output:

-rwxr-xr-x 1 root root 2.2M  8月19日 17:59 /lib/firmware/rknn3_rk1820.img

Push over PCIe:

bdf=$(/usr/bin/pcie_upgrade_tool ld 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | grep -o 'Addr=[0-9:a-f]*' | head -1 | cut -d= -f2)
sudo /usr/bin/pcie_upgrade_tool -s "$bdf" uf /lib/firmware/rknn3_rk1820.img

Output:

Program directory: /usr/bin/
Downloading firmware...
Device boot state: 0x00004b52
Device is not in maskrom mode or loader mode

The device is already in normal running state; firmware update requires maskrom/loader mode. Under normal circumstances the firmware is loaded automatically by rknn3.service, so no manual execution is needed.

Restart the service:

sudo systemctl restart rknn3.service

Output:

● rknn3.service - rknn3 runtime service
     Loaded: loaded (/lib/systemd/system/rknn3.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-08-17 17:01:04 UTC; 31s ago
   Process: 5042 ExecStart=/bin/rknn3_startup start (code=exited, status=0/SUCCESS)
  Main PID: 5065 (rknn3_transfer_)
       CPU: 5.840s
   CGroup: /system.slice/rknn3.service
           ├─5065 /bin/rknn3_transfer_proxy
           └─5074 rknn3_transfer_proxy -s 0004:41:00.0

Slow service restart: systemctl stop / restart rknn3.service often gets stuck in the deactivating state for 1+ minute while processes are cleaned up. This is a known issue.

5. Verify the Environment

Inference demos:

which rknn3_cnn_demo      # /usr/bin/rknn3_cnn_demo
which rknn3_llm_demo      # /usr/bin/rknn3_llm_demo
which rknn3_vlm_demo      # /usr/bin/rknn3_vlm_demo

Model throughput test:

which rknn3_model_test    # /usr/bin/rknn3_model_test

If all are found, the environment is ready.

6. Troubleshooting

Symptom	Cause	Fix
`ModuleNotFoundError: No module named 'rknn'`	venv not activated	`source ~/rk1828-npu-env/bin/activate`
Toolkit wheel won't install	Installed on the board (aarch64 unsupported)	Move to a PC (x86_64) to install
`pcie_upgrade_tool` command not found	SDK not installed	Reinstall the `rknn3-runtime` deb
`Addr=` list empty	PCIe not enumerated / card not seated	Reseat + check for the 182a device with `lspci`
`systemctl restart rknn3.service` stuck deactivating 1+ min	Known issue	Wait; do not Ctrl+C
`rknn3_*_demo` not found	SDK package incomplete	Run the SDK install script to complete it

7. Next Steps

Quick Start — complete host-side workflow + first demo build and run
Vendor SDK Data Extraction — RK182X key parameters / host reference values quick reference