Hướng dẫn cài đặt PiKVM trên Vontar DQ08 RK3528 TV Box với Armbian

Mục tiêu: Biến TV box Vontar DQ08 (RK3528) thành thiết bị PiKVM để điều khiển máy tính từ xa qua mạng.

Hardware cần thiết:

Vontar DQ08 RK3528 TV Box
SD card tối thiểu 8GB (khuyến nghị 32GB hoặc USB SSD)
HDMI to USB capture dongle
USB-A to USB-A cable (cần cắt dây nguồn VCC/+5V)
Máy tính có Ubuntu (VM hoặc bare metal) để build Armbian

PHẦN 1: BUILD ARMBIAN IMAGE

1.1. Chuẩn bị môi trường build (Ubuntu)

bash

# Update hệ thống
sudo apt update && sudo apt upgrade -y

# Cài dependencies
sudo apt install -y git vim make python3-dev gcc xz-utils wget sudo
# Tạo thư mục làm việc
mkdir -p ~/rk3528-tvbox
cd ~/rk3528-tvbox

# Clone Armbian build system
git clone https://github.com/armbian/build.git armbian-build

# Clone devicetree cho RK3528
git clone https://github.com/ilyakurdyukov/rk3528-tvbox.git devicetree

1.2. Enable USB HID Gadget support trong kernel

bash

cd ~/rk3528-tvbox/armbian-build

# Edit kernel config để enable USB HID
sed -i 's/# CONFIG_USB_CONFIGFS_F_HID is not set/CONFIG_USB_CONFIGFS_F_HID=y/' config/kernel/linux-rk3528-tvbox-legacy.config

# Verify thay đổi
grep "CONFIG_USB_CONFIGFS_F_HID" config/kernel/linux-rk3528-tvbox-legacy.config
# Phải thấy: CONFIG_USB_CONFIGFS_F_HID=y

1.3. Build Armbian image

bash

# Xóa cache kernel cũ
sudo rm -rf cache/sources/linux-kernel-worktree
sudo rm -rf .tmp

# Build image (mất 1-2 giờ)
./compile.sh build \
  BOARD=rk3528-tvbox \
  BRANCH=legacy \
  BUILD_DESKTOP=yes \
  BUILD_MINIMAL=no \
  DESKTOP_APPGROUPS_SELECTED= \
  DESKTOP_ENVIRONMENT=mate \
  DESKTOP_ENVIRONMENT_CONFIG_NAME=config_base \
  EXPERT=yes \
  KERNEL_CONFIGURE=no \
  KERNEL_GIT=shallow \
  RELEASE=bookworm \
  PREFER_DOCKER=no

Output: File .img trong output/images/

1.4. Fix DTB và enable OTG

Tạo script tự động fix DTB:

bash

cd ~/rk3528-tvbox

cat > fix-dtb.sh << 'EOF'
#!/bin/bash
set -e

IMAGE="$HOME/rk3528-tvbox/armbian-build/output/images/Armbian-unofficial_26.02.0-trunk_Rk3528-tvbox_bookworm_legacy_5.10.160_mate_desktop.img"

if [ ! -f "$IMAGE" ]; then
    echo "ERROR: Image file not found: $IMAGE"
    exit 1
fi

echo "Cleaning up..."
sudo losetup -d /dev/loop10 2>/dev/null || true
sudo umount /mnt 2>/dev/null || true

echo "Setting up loop device..."
sudo losetup --partscan /dev/loop10 "$IMAGE"
sleep 2

echo "Mounting boot partition..."
sudo mount /dev/loop10p1 /mnt

# Build DTB with OTG enabled
cd $HOME/rk3528-tvbox/devicetree

echo "Building DTB with OTG enabled..."
rm -f *.dtsi *.dtb *.dtb.txt 2>/dev/null || true
rm -rf obj/ 2>/dev/null || true

cp orig/*.dtsi . 2>/dev/null || true
patch -p1 -i rk3528-tvbox.patch 2>/dev/null || true
make NAME=rk3528-vontar-dq08 PRESET=LINUX

# Modify DTB to enable OTG
echo "Enabling OTG (dr_mode = peripheral)..."
dtc -I dtb -O dts rk3528-vontar-dq08.dtb -o rk3528-vontar-dq08.dts
sed -i 's/dr_mode = "host"/dr_mode = "peripheral"/g' rk3528-vontar-dq08.dts
dtc -I dts -O dtb rk3528-vontar-dq08.dts -o rk3528-vontar-dq08.dtb

echo "Copying DTB to image..."
sudo mkdir -p /mnt/dtb/rockchip
sudo cp rk3528-vontar-dq08.dtb /mnt/dtb/rockchip/

# Update armbianEnv.txt
echo "Updating armbianEnv.txt..."
sudo sed -i "s#fdtfile=.*#fdtfile=rockchip/rk3528-vontar-dq08.dtb#" /mnt/armbianEnv.txt

if ! grep -q "overlays=" /mnt/armbianEnv.txt; then
    echo "overlays=usbhost0 usbhost1 usbhost2 usbhost3" | sudo tee -a /mnt/armbianEnv.txt
else
    sudo sed -i "s#overlays=.*#overlays=usbhost0 usbhost1 usbhost2 usbhost3#" /mnt/armbianEnv.txt
fi

echo ""
echo "===== Verification ====="
cat /mnt/armbianEnv.txt
ls -la /mnt/dtb/rockchip/rk3528-vontar-dq08.dtb

sudo umount /mnt
sudo losetup -d /dev/loop10

echo "=========================================="
echo "✅ DTB fixed with OTG enabled!"
echo "✅ Image ready to flash."
echo "=========================================="
EOF
chmod +x fix-dtb.sh
./fix-dtb.sh

1.5. Flash image vào SD card

Trên Windows:

Tải Balena Etcher: https://etcher.balena.io/
Copy file .img từ Ubuntu về Windows
Flash vào SD card
Verify write

PHẦN 2: INITIAL SETUP ARMBIAN

2.1. Boot lần đầu

Cắm SD card vào DQ08
Cắm Ethernet cable
Bật nguồn
Đợi 1-2 phút

Tìm IP:

Dùng Advanced IP Scanner trên Windows
Hoặc check router DHCP table

2.2. SSH và initial setup

bash

ssh root@<IP-DQ08>
# Password mặc định: 1234

Setup wizard sẽ hỏi:

New root password
Create new user (ví dụ: louis)
Select locale: en_US.UTF-8
Select timezone: Asia/Saigon

2.3. Enable USB host overlays

bash

armbian-config

Navigate: System → Hardware

Enable (nhấn Space):

✅ usbhost0
✅ usbhost1
✅ usbhost2
✅ usbhost3

Save → Reboot

bash

reboot

2.4. Configure USB Gadget modules

SSH lại vào sau reboot:

bash

ssh root@<IP-DQ08>
nano /boot/armbianEnv.txt
```
**Thêm dòng `extraargs`:**
```
overlays=usbhost0 usbhost1 usbhost2 usbhost3
extraargs=modules-load=dwc2,g_ether g_ether.host_addr=00:22:82:ff:ff:00 g_ether.dev_addr=00:22:82:ff:ff:01
```

**Hoặc nếu cần USB serial debug:**
```
extraargs=console=ttyGS0,115200 modules-load=dwc2,g_cdc g_cdc.host_addr=00:22:82:ff:ff:00 g_cdc.dev_addr=00:22:82:ff:ff:01

Save: Ctrl+O, Enter, Ctrl+X

bash

reboot

2.5. Verify OTG enabled

bash

ssh root@<IP-DQ08>
# Check UDC
ls -la /sys/class/udc/
# Phải thấy: fe500000.dwc3
# Check dr_mode
cat /sys/firmware/devicetree/base/usbdrd/dwc3@fe500000/dr_mode
# Phải thấy: peripheral
# Check USB gadget modules
lsmod | grep gadget
lsmod | grep dwc2

Nếu UDC rỗng hoặc dr_mode = “host” → Image không đúng, cần rebuild!

PHẦN 3: CÀI ĐẶT PIKVM

3.1. Update và cài dependencies

bash

apt update && apt upgrade -y
apt install -y git vim make python3-dev gcc xz-utils wget sudo
# Verify Python version
python3 --version
# Phải >= 3.10

3.2. Clone kvmd-armbian

bash

cd /root
git clone https://github.com/srepac/kvmd-armbian.git
cd kvmd-armbian

3.3. Install Part 1

bash

./install.sh
```

Script sẽ:
- Cài packages
- Setup USB gadget modules
- Tạo certificates
- Configure services

**Cuối cùng sẽ yêu cầu:**
```
Press ENTER to reboot

→ Nhấn ENTER

3.4. Install Part 2

Sau khi reboot, SSH lại vào:

bash

ssh root@<IP-DQ08>
cd /root/kvmd-armbian
./install.sh
```

Script sẽ:
- Load USB gadget modules
- Tạo HID devices
- Cài kvmd packages
- Configure web interface

**Sẽ hiển thị config và hỏi:**
```
Did kvmd -m run properly?  [y/n]

→ Nhấn y

3.5. Configure kvmd-otg

bash

nano /etc/kvmd/override.yaml

Thêm config (ngang hàng với kvmd:):

yaml

kvmd:
    hid:
        mouse_alt:
            device: /dev/kvmd-hid-mouse-alt
    msd:
        type: disabled
    atx:
        type: disabled
    streamer:
        forever: true
        cmd_append:
            - "--slowdown"
        resolution:
            default: 1280x720

otg:
    udc: fe500000.dwc3

Save: Ctrl+O, Enter, Ctrl+X

bash

reboot

3.6. Verify services

bash

ssh root@<IP-DQ08>
# Check HID devices
ls -la /dev/kvmd-hid-*
# Phải thấy: keyboard, mouse, mouse-alt
# Check services
systemctl status kvmd
systemctl status kvmd-nginx
systemctl status kvmd-otg

# Tất cả phải: active (running)

PHẦN 4: FIX VIDEO DEVICE

4.1. Check HDMI capture dongle

bash

# Xem USB devices
lsusb

# Xem video devices
ls -la /dev/video*
v4l2-ctl --list-devices

4.2. Fix symlink /dev/kvmd-video

bash

# Xóa symlink cũ (nếu sai)
rm -f /dev/kvmd-video

# Tạo symlink đúng
ln -sf /dev/video0 /dev/kvmd-video

# Verify
ls -la /dev/kvmd-video
# Phải thấy: /dev/kvmd-video -> /dev/video0
# Restart kvmd
systemctl restart kvmd

4.3. Test capture

bash

# Cài ffmpeg
apt install -y ffmpeg

# Stop kvmd tạm thời
systemctl stop kvmd

# Capture frame
ffmpeg -f v4l2 -i /dev/video0 -frames 1 /tmp/test.jpg

# Check file
ls -lh /tmp/test.jpg

# Start kvmd lại
systemctl start kvmd
```
Copy `/tmp/test.jpg` về Windows để xem có hình không.

**Nếu hình ĐEN:** HDMI source không có tín hiệu → Check máy tính đã bật và cáp HDMI chưa.

---

## PHẦN 5: TRUY CẬP PIKVM
### 5.1. Web Interface

Mở browser:
```
URL: https://<IP-DQ08>/

Username: admin
Password: admin
```

**Lưu ý:** 
- Phải dùng **HTTPS**
- Browser sẽ cảnh báo certificate → Click "Advanced" → "Proceed"
### 5.2. Đổi password admin
1. Click **System** (góc trên phải)
2. Click **Users**
3. Chọn user `admin`
4. Click **Change password**
5. Nhập password mới

---

## PHẦN 6: KẾT NỐI PHẦN CỨNG
### 6.1. Sơ đồ kết nối
```
[Máy tính cần điều khiển]
    ↓ HDMI cable
[HDMI to USB Capture Dongle]
    ↓ USB cable
[DQ08 - Cổng USB thường]
[DQ08 - Cổng USB OTG]
    ↓ USB-A to USB-A cable (ĐÃ CẮT DÂY NGUỒN VCC)
[Máy tính cần điều khiển - Cổng USB]

6.2. Chuẩn bị USB OTG cable

Quan trọng: Phải cắt dây nguồn (VCC/+5V) trong USB cable để tránh conflict nguồn!

Cách cắt:

Mổ USB cable ở giữa
Cắt dây ĐỎ (VCC +5V)
Để nguyên 3 dây còn lại: đen (GND), xanh lá (D+), trắng (D-)
Cách điện lại

6.3. Kết nối

HDMI capture dongle:
- Input: HDMI từ máy tính
- Output USB: Cắm vào cổng USB thường của DQ08
USB OTG cable:
- Một đầu: Cổng USB OTG của DQ08
- Đầu kia: Cổng USB của máy tính cần điều khiển
Bật nguồn:
- DQ08 đã bật
- Máy tính cần điều khiển đã bật

PHẦN 7: SỬ DỤNG PIKVM

7.1. Các tính năng

Desktop Viewer:

Xem màn hình máy tính real-time
Stream qua HDMI capture

Virtual Keyboard/Mouse:

Click vào màn hình để di chuyển chuột
Gõ phím trên keyboard ảo
Máy tính nhận input như keyboard/mouse thật

Terminal:

Truy cập shell của DQ08 từ web
Chạy lệnh trực tiếp

System Info:

CPU, RAM, nhiệt độ
Network status

7.2. Tính năng nâng cao

Mass Storage Device (MSD):

Mount ISO/IMG file
Boot máy tính từ file ISO

ATX Power Control:

Power on/off/reset máy tính
Cần thêm hardware relay

Wake-on-LAN:

Wake máy tính từ xa

PHẦN 8: TROUBLESHOOTING

8.1. HID devices không có

bash

# Load modules
modprobe libcomposite
modprobe usb_f_hid

# Nếu lỗi: Module not found
# → Kernel thiếu CONFIG_USB_CONFIGFS_F_HID
# → Cần rebuild image!
# Restart kvmd-otg
systemctl restart kvmd-otg
ls -la /dev/kvmd-hid-*

8.2. Web không truy cập được

bash

# Restart nginx
systemctl restart kvmd-nginx

# Check port
netstat -tulpn | grep 443
# Check firewall
iptables -L

8.3. Video không có hình

Check HDMI source:

Máy tính đã bật?
Cáp HDMI cắm chặt?
Màn hình máy tính có hoạt động?

Check dongle:

bash

lsusb
v4l2-ctl --list-devices
ls -la /dev/video*

Test capture:

bash

systemctl stop kvmd
ffmpeg -f v4l2 -i /dev/video0 -frames 1 /tmp/test.jpg
systemctl start kvmd

8.4. Keyboard/Mouse không hoạt động

bash

# Check HID devices
ls -la /dev/kvmd-hid-*

# Check USB OTG cable đã cắm
lsusb -t

# Restart kvmd-otg
systemctl restart kvmd-otg

8.5. WiFi không hoạt động (Nếu cần)

bash

# Check WiFi adapter
rfkill list

# Enable WiFi
ip link set wlan0 up

# Connect WiFi
nmtui
# → Activate a connection → Chọn WiFi → Nhập password

Lưu ý: WiFi trên DQ08 có thể gặp lỗi power GPIO. Khuyến nghị dùng USB WiFi dongle hoặc Ethernet.

PHẦN 9: TỐI ƯU HÓA

9.1. Chuyển sang USB SSD (Khuyến nghị)

Lợi ích:

Nhanh hơn SD card
Bền hơn (SD card dễ hỏng khi ghi liên tục)

Cách làm:

bash

# 1. Flash CÙNG image vào USB SSD (bằng Balena Etcher)
# 2. Cắm USB SSD vào DQ08
# 3. SSH vào DQ08
# Gán label cho SSD
e2label /dev/sda2 ssd

# Sửa boot config
nano /boot/armbianEnv.txt
# Đổi: rootdev=UUID=...
# Thành: rootdev=LABEL=ssd
# Reboot
reboot
# Kiểm tra
df -h /
# Phải thấy /dev/sda2

9.2. Enable Avahi (mDNS)

bash

# Cài avahi
apt install -y avahi-daemon libnss-mdns libnss-mymachines

# Enable SSH
systemctl enable --now ssh
# Reboot
reboot

Sau đó SSH qua hostname:

bash

# Linux
ssh [email protected]

# Windows
ssh root@rk3528-tvbox

9.3. Auto-start services

Services đã được enable tự động:

bash

# Verify
systemctl list-unit-files | grep kvmd

# Phải thấy:
# kvmd.service              enabled
# kvmd-nginx.service        enabled
# kvmd-otg.service          enabled

Mỗi khi bật DQ08:

Services tự động start
PiKVM sẵn sàng sau 1-2 phút
Không cần chạy lệnh gì

PHẦN 10: LƯU Ý VÀ BEST PRACTICES

10.1. Bảo mật

✅ Đổi password admin ngay sau khi cài
✅ Tạo user riêng, không dùng admin
✅ Enable 2FA nếu expose ra internet
✅ Dùng VPN thay vì port forwarding

10.2. Hiệu năng

✅ Dùng USB SSD thay vì SD card
✅ Dùng Ethernet thay vì WiFi
✅ Resolution 1280×720 cho stream mượt
✅ FPS 30-40 là đủ

10.3. Hardware

✅ HDMI capture dongle tốt: Macrosilicon MS2109, Fushicai
✅ USB OTG cable: Phải cắt dây nguồn
✅ SD card: Class 10, A1/A2
✅ USB SSD: USB 3.0, tốc độ đọc/ghi tốt

10.4. Use cases

PiKVM phù hợp cho:

✅ Quản lý server từ xa
✅ Troubleshoot máy tính không boot được
✅ BIOS/UEFI setup từ xa
✅ Cài đặt OS từ xa (mount ISO)
✅ Homelab management

PiKVM KHÔNG phù hợp cho:

❌ Gaming (latency cao)
❌ Video editing (stream quality hạn chế)
❌ Thay thế Remote Desktop (dùng RDP/VNC tốt hơn)

PHẦN 11: TÀI LIỆU THAM KHẢO

Official PiKVM:

KVMD-Armbian:

https://github.com/srepac/kvmd-armbian

RK3528 TV Box:

https://github.com/ilyakurdyukov/rk3528-tvbox

Armbian:

KẾT LUẬN

Bạn đã thành công biến Vontar DQ08 thành thiết bị PiKVM! Giờ có thể:

✅ Điều khiển máy tính từ xa qua web
✅ Xem màn hình real-time qua HDMI
✅ Gõ phím và di chuột như ngồi trước máy
✅ Truy cập BIOS/UEFI từ xa
✅ Mount ISO để cài OS

Chi phí: