K230 Debian/Ubuntu 系统使用指南#

提示：Debian 和 Ubuntu 功能相近，K230 平台推荐优先使用 Debian 系统。

快速入门#

镜像获取#

用户可在 K230 Linux SDK 镜像中心下载 CI 编译好的镜像，或参考以下命令自行编译镜像。

镜像文件名示例：

CanMV-K230_01studio_debian_v0.6.4_nncase_v2.9.0.img.gz
CanMV-K230_01studio_ubuntu_v0.6.4_nncase_v2.9.0.img.gz

# 克隆源码
git clone git@github.com:kendryte/k230_linux_sdk.git
# git clone git@gitee.com:kendryte/k230_linux_sdk.git

cd k230_linux_sdk

# 编译配置
make CONF=k230_canmv_01studio_defconfig  # 01studio 开发板
# make CONF=k230_canmv_defconfig          # K230 CANMV 开发板

# 生成镜像
sudo make debian   # 生成 Debian 镜像
sudo make ubuntu   # 生成 Ubuntu 镜像

生成的镜像路径：

Debian: output/k230_canmv_01studio_defconfig/images/CanMV-K230_01studio_debian_v0.6.4_nncase_v2.9.0.img.gz
Ubuntu: output/k230_canmv_01studio_defconfig/images/CanMV-K230_01studio_ubuntu_v0.6.4_nncase_v2.9.0.img.gz

镜像烧录#

请参考镜像烧录指南将固件烧录到开发板。

连接串口#

串口默认参数：115200 8 1 无流控

参考：开发板串口登录指南

自带 USB 转串口芯片的开发板#

部分开发板（如 K230 CANMV）内置了 USB 转串口芯片（CH34x），直接使用 USB 线连接开发板到电脑，安装 CH34x 驱动后，在 PuTTY 中设置正确的串口参数并按下 Reset 按键，即可查看 CPU 输出。

需外接 USB 转串口的开发板#

部分开发板（如 01studio、嘉立创等）需要外接 USB 转串口小板，安装对应驱动后才能查看串口输出。

串口登录系统#

串口看到登录提示后，使用以下凭据登录：

用户名: root
密码: root

配置使用#

说明：系统默认用户和密码均为 root，可通过 apt install 安装软件。

有线网络配置#

DHCP 自动获取 IP#

# 使用 systemd-networkd 配置网络（DHCP）
cat > /etc/systemd/network/10-eth0.network <<'EOF'
[Match]
Name=en*

[Network]
DHCP=yes
EOF

systemctl disable networking
systemctl enable --now systemd-networkd
systemctl restart systemd-networkd

# 查看默认网关
# ip route show default
# ip route

静态 IP 配置#

# 使用 systemd-networkd 配置网络（静态 IP）
cat > /etc/systemd/network/10-eth0.network <<'EOF'
[Match]
Name=en*

[Network]
Address=192.168.1.2/24
Gateway=192.168.1.1
DNS=192.168.1.1
EOF

systemctl disable networking
systemctl stop systemd-networkd
systemctl restart systemd-networkd

软件安装#

注意：apt 命令依赖系统时间，如果时间不正确可能导致 SSL/TLS 连接失败。请先确认时间正确后再安装软件。

# 查看当前时间，如不正确请手动设置
# date -s "2025-04-14 11:15:20"

apt-get update
apt install wpasupplicant

无线网络配置#

# 安装无线网络支持
apt install wpasupplicant

# 执行 sta.sh 脚本连接 WiFi
# 格式: sta.sh <网卡接口> <SSID> <密码>
sta.sh wlan0 canaan_wifi 123456789

NTP 自动校时与时区配置#

# 安装 NTP 客户端
apt install systemd-timesyncd

# 设置时区为亚洲/上海
rm -rf /etc/localtime
ln -s /usr/share/zoneinfo/Asia/Shanghai /etc/localtime

# 启用自动校时
systemctl enable systemd-timesyncd

SSH 远程登录#

# 安装 SSH 服务
apt install -y openssh-server

# 允许 root 用户登录
echo "PermitRootLogin yes" >> /etc/ssh/sshd_config

# 重启 SSH 服务
systemctl restart ssh

开机自动运行脚本#

# 创建启动脚本
cat > /opt/mount_boot.sh <<'EOF'
#!/bin/bash
bootddev=$(cat /proc/cmdline | sed -n "s#root=\(\/dev\/mmcblk[0-9]\).*#\1#p")
sd_size=$(parted ${bootddev} print | grep ${bootddev} | cut -d: -f2)
parted ${bootddev} resizepart 2 ${sd_size}; resize2fs ${bootddev}p2
mount ${bootddev}p1 /boot
EOF

chmod +x /opt/mount_boot.sh

# 创建 systemd 服务
cat > /etc/systemd/system/mount_boot.service <<'EOF'
[Unit]
Description=Mount Boot Part
After=rc-local.service

[Service]
Type=oneshot
ExecStart=/opt/mount_boot.sh
RemainAfterExit=no

[Install]
WantedBy=basic.target
EOF

# 启用服务
systemctl enable mount_boot.service

Sensor 及显示测试#

# 安装依赖
apt-get install libdrm2

# 安装 K230 ISP 驱动
# dpkg -i /root/deb/k230-vvcam.deb

# 测试 GPU 和显示（vglite_drm 示例）
vglite_drm

# 测试 GPU 和显示（vglite_cube 示例）
vglite_cube

# 列出视频设备
# v4l2-ctl --list-devices

# 显示摄像头画面（根据实际 video 设备调整 -d 参数）
v4l2-drm -d 1 -n 5 -w 640 -h 480

源码参考：

v4l2-drm

vglite_cube 和 vglite_drm

设备树配置#

如果没有显示输出，请检查设备树是否正确：

使用LCD 的设备树：应使用 xxxxxx-lcd.dtb
使用HDMI 的设备树：应使用 xxxxxx.dtb

查看当前设备树：

ls -lh /boot

切换到 LCD 显示：

#以01studio为例
cd /boot
rm -rf k.dtb
ln -s k230-canmv-01studio-lcd.dtb k.dtb
sync
reboot

切换到 HDMI 显示：

#以01studio为例
cd /boot
rm -rf k.dtb
ln -s k230-canmv-01studio.dtb k.dtb
sync
reboot

摄像头设备确认#

如果能看到显示但无法显示视频，可通过以下命令确认摄像头设备号：

v4l2-ctl --list-devices

示例输出：

Linlon Video device (platform:mvx):
 /dev/video0

Canaan nonai 2D (platform:nonai-2d):
 /dev/video7

vvcam-isp-subdev.0 (platform:vvcam-isp-subdev.0):
 /dev/v4l-subdev0

vvcam-video.0.0 (platform:vvcam-video.0.0):
 /dev/video3   # 摄像头设备，v4l2-drm -d 3

vvcam-video.0.1 (platform:vvcam-video.0.1):
 /dev/video4

vvcam-video.0.2 (platform:vvcam-video.0.2):
 /dev/video5

vvcam-video.0.3 (platform:vvcam-video.0.3):
 /dev/video6

GENERAL WEBCAM: GENERAL WEBCAM (usb-91540000.usb-1.1):
 /dev/video1
 /dev/video2
 /dev/media0

人脸识别 Demo 安装及测试#

# 安装人脸识别相关依赖包
# apt-get install -y libdrm2 libgomp1 libwebp7 libpng-dev libopus-dev

# 安装 K230 相关 deb 包
# dpkg -i /root/deb/k230-vvcam.deb /root/deb/k230-opencv4.deb /root/deb/k230-ffmpeg.deb /root/deb/k230-face-detect.deb

# 运行人脸识别 Demo
cd /root/app/face_detect
./face_detect_video.sh

源码参考：buildroot-overlay/package/face_detect

多媒体测试#

# 安装多媒体播放器
# dpkg -i deb/k230-mvx-player.deb

# 查看设备：video0 为编解码器，video1 为摄像头
v4l2-ctl --list-devices

# 捕获摄像头画面保存为 NV12 格式（1080p，25 帧）
# 请确保数据写入速度足够快，否则请降低分辨率
v4l2-ctl \
    --device=/dev/video1 \
    --set-fmt-video=width=1920,height=1080,pixelformat=NV12 \
    --stream-mmap \
    --stream-count=25 \
    --stream-to=output.yuv

# H.264 视频解码
mvx_decoder --dev /dev/video0 -i h264 -o yuv420_nv12 test.264 output1.yuv

# 使用 FFmpeg 采集摄像头并 VPU 编码为 MP4
ffmpeg -f v4l2 -input_format nv12 -r 30 -s 1920x1080 \
    -i /dev/video1 -c:v h264_v4l2m2m -b:v 4M -vsync passthrough -y test.mp4

源码参考：mvx_decoder

UVC 摄像头测试#

# 安装工具
apt install v4l-utils ffmpeg usbutils

# 列出所有 V4L2 设备
v4l2-ctl --list-devices

# 查看设备详细信息
v4l2-ctl -d /dev/video0 --all

# 列出支持的格式
v4l2-ctl -d /dev/video1 --list-formats-ext

# 抓取单帧图片
ffmpeg -f v4l2 -i /dev/video1 -frames:v 1 -s 640x480 camera_capture.jpg

# 录制视频（CPU 编码，速度较慢）
ffmpeg -f v4l2 -i /dev/video1 -c:v libx264 -s 640x480 -r 15 -t 3 record_10s.mp4

# 查看 FFmpeg 支持的编码器
ffmpeg -encoders | grep v4l2

PyQt 安装及测试#

安装 PyQt5#

apt update
apt install -y qtbase5-dev qtbase5-examples python3-pyqt5

显示配置#

HDMI 显示：

cat > /etc/profile.d/qt_env.sh <<'EOF'
export QT_QPA_PLATFORM=linuxfb
export QT_QPA_FB_DRM=1
export QT_QPA_EGLFS_KMS_CONFIG="/root/kms_config.json"
EOF

cat > /root/kms_config.json <<'EOF'
{
    "device": "/dev/dri/card0",
    "outputs": [
        { "name": "HDMI1", "format": "argb8888" }
    ]
}
EOF

LCD 显示：

cat > /etc/profile.d/qt_env.sh <<'EOF'
export QT_QPA_PLATFORM=linuxfb
export QT_QPA_FB_DRM=1
export QT_QPA_EGLFS_KMS_CONFIG="/root/kms_config.json"
EOF

cat > /root/kms_config.json <<'EOF'
{
    "device": "/dev/dri/card0",
    "outputs": [
        { "name": "DSI1", "format": "argb8888" }
    ]
}
EOF

运行测试#

cat > helloworld_pyqt.py <<'EOF'
import sys
from PyQt5.QtWidgets import QApplication, QWidget, QLabel
from PyQt5.QtGui import QFont

def main():
    app = QApplication(sys.argv)
    window = QWidget()
    window.setWindowTitle('Hello World')

    # 标签 1
    label = QLabel('Hello World', window)
    label.move(50, 50)

    # 标签 2
    label = QLabel('wjx, test', window)
    label.move(300, 400)
    label.setFont(QFont('Arial', 30, QFont.Bold))
    label.setStyleSheet("QLabel { color: red; }")

    # 标签 3
    label = QLabel('k230 pyqt5 test', window)
    label.move(500, 500)
    label.setFont(QFont('Arial', 50, QFont.Bold))
    label.setStyleSheet("QLabel { color: red; }")

    window.show()
    sys.exit(app.exec_())

if __name__ == '__main__':
    main()
EOF

python3 helloworld_pyqt.py

C/C++ 开发参考#

Helloworld
向量测试
人脸识别

Python 开发参考#

环境搭建#

apt update
apt install -y python3 python3-pip

python3 --version
pip3 --version

注意：如需使用 KPU 功能，需安装 nncase runtime：
pip install --break-system-packages /root/nncaseruntime_k230-2.11.0-py3-none-linux_riscv64.whl
依赖 Python 3.13 环境（Debian 默认提供）

目前仅适用于 Debian 系统

下载地址：nncaseruntime_k230-2.11.0-py3-none-linux_riscv64.whl

KPU Python Demo#

API 文档：nncaseruntime_k230_API

参考命令如下：

apt-get install unzip
wget https://github.com/kendryte/nncase_docs/archive/refs/heads/master.zip
unzip master.zip
cd nncase_docs-master/Linux_only_dir/demo
python3 demo.py

运行结果：output.jpg

源码参考：demo.py

Python OpenCV 示例 - 视频显示#

apt install -y python3-opencv

cat > t.py <<'EOF'
import cv2
import time
import sys
import select

# 指定摄像头索引
camera_index = 1

# 打开摄像头
cap = cv2.VideoCapture(camera_index)

# 检查摄像头是否成功打开
if not cap.isOpened():
    print(f"Cannot open camera {camera_index}")
    exit()

# 设置分辨率（宽度，高度）
cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1920)
cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 1080)
print(f"Resolution set to 1920x1080")

frame_count = 0
start_time = time.time()

while True:
    # 读取帧
    ret, frame = cap.read()
    if not ret:
        print("Cannot read frame")
        break

    frame_count += 1

    # 每秒计算一次 FPS
    current_time = time.time()
    if current_time - start_time >= 1.0:
        fps = int(frame_count / (current_time - start_time))
        print(f"FPS: {fps}")
        frame_count = 0
        start_time = current_time

    # 颜色空间转换（摄像头返回 RGB，OpenCV 需要 BGR）
    frame = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)

    # 显示画面
    cv2.imshow('Camera Feed', frame)

    # 键盘退出
    if cv2.waitKey(1) & 0xFF == ord('q'):
        print("\nExiting program.")
        break
    if sys.stdin in select.select([sys.stdin], [], [], 0)[0]:
        print("\nExiting due to input from stdin!")
        break
    time.sleep(0.01)

# 释放资源
cap.release()
cv2.destroyAllWindows()
EOF

python3 t.py

OpenCV 人脸检测 - 图片#

# 安装 wget（如未安装）
apt-get install -y wget

# 下载人脸检测模型和测试图片
wget https://raw.githubusercontent.com/opencv/opencv/master/data/haarcascades/haarcascade_frontalface_default.xml
wget -c https://www.kendryte.com/api/post/attachment?id=602 -O 1.jpg

cat > t.py <<'EOF'
import cv2
import sys

# 加载人脸检测模型
face_cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml')

# 加载图片
image_path = '1.jpg'
img = cv2.imread(image_path)

# 检查图片是否加载成功
if img is None:
    print(f"Cannot load image: {image_path}")
    sys.exit()

# 转换为灰度图（人脸检测在灰度图上进行）
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

# 检测人脸
faces = face_cascade.detectMultiScale(gray, scaleFactor=1.1, minNeighbors=5, minSize=(30, 30))

print(f"Found {len(faces)} face(s)")

# 绘制检测框（绿色，线宽 2）
for (x, y, w, h) in faces:
    print(f"x={x}, y={y}, w={w}, h={h}")
    cv2.rectangle(img, (x, y), (x + w, y + h), (0, 255, 0), 2)

# 显示结果
cv2.imshow('Face Detection', img)
cv2.waitKey(0)
cv2.destroyAllWindows()
EOF

python3 t.py

OpenCV 人脸检测 - 摄像头#

# 下载人脸检测模型（如未下载）
wget https://raw.githubusercontent.com/opencv/opencv/master/data/haarcascades/haarcascade_frontalface_default.xml

cat > t.py <<'EOF'
import cv2
import time

# 加载人脸检测模型
face_cascade = cv2.CascadeClassifier('haarcascade_frontalface_default.xml')

# 打开摄像头（根据实际设备调整参数）
cap = cv2.VideoCapture(1)

# 检查摄像头是否成功打开
if not cap.isOpened():
    print("Cannot open camera")
    exit()

# 检测间隔（每 N 帧检测一次）
detection_interval = 1
frame_count = 0
faces = []

# 初始化时间变量
start_time = time.time()

while True:
    # 读取帧
    ret, frame = cap.read()
    if not ret:
        print("Cannot read frame")
        break

    frame_count += 1

    # 按间隔进行人脸检测
    if frame_count % detection_interval == 0:
        # 转换为灰度图
        gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
        # 检测人脸
        faces = face_cascade.detectMultiScale(
            gray, scaleFactor=1.1, minNeighbors=5, minSize=(30, 30))

    # 绘制检测框
    for (x, y, w, h) in faces:
        print(f"x={x}, y={y}, w={w}, h={h}")
        cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2)

    # 计算并打印 FPS
    elapsed_time = time.time() - start_time
    if elapsed_time >= 1.0:
        fps = frame_count / elapsed_time
        print(f"FPS: {fps:.2f}")
        frame_count = 0
        start_time = time.time()

    # 显示画面
    cv2.imshow('Live Face Detection', frame)

    # 键盘退出
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

# 释放资源
cap.release()
cv2.destroyAllWindows()
EOF

python3 t.py

K230 Debian/Ubuntu 系统使用指南

目录

K230 Debian/Ubuntu 系统使用指南#

快速入门#

镜像获取#

镜像烧录#

连接串口#

自带 USB 转串口芯片的开发板#

需外接 USB 转串口的开发板#

串口登录系统#

配置使用#

有线网络配置#

DHCP 自动获取 IP#

静态 IP 配置#

软件安装#

无线网络配置#

NTP 自动校时与时区配置#

SSH 远程登录#

开机自动运行脚本#

Sensor 及显示测试#

设备树配置#

摄像头设备确认#

人脸识别 Demo 安装及测试#

多媒体测试#

UVC 摄像头测试#

PyQt 安装及测试#

安装 PyQt5#

显示配置#

运行测试#

C/C++ 开发参考#

Python 开发参考#

环境搭建#

KPU Python Demo#

Python OpenCV 示例 - 视频显示#

OpenCV 人脸检测 - 图片#

OpenCV 人脸检测 - 摄像头#