二次开发

2026-03-31

更新历史

日期	版本	作者	更新内容
2025-4-10	v1.0	BuGu	Update docs
2024-9-26	v0.1	BuGu	Release docs

NanoKVM除实现KVM功能外还开放了一些数据,用于用户的二次开发,此文档用于描述这些数据的作用,以及开发的注意事项

更换 Logo

注：此功能仅在 NanoKVM v2.3.6 及以上版本的应用程序中支持。

NanoKVM 支持自定义 Logo 显示，可在 OLED 屏幕和 Web 管理界面中同时展示。其中，OLED 屏幕显示低分辨率的黑白二值图像，Web 界面显示高分辨率的彩色图像。

步骤一：生成 Logo 文件

下载 Logo 生成 Python 脚本
安装依赖库：
```
pip install Pillow numpy textual
```
准备一张接近正方形的 Logo 图片，并获取其文件路径

执行脚本生成 Logo 文件：

python logo_generator.py /path/to/your_logo.png

选择显示语言（当前仅支持中文和英文）
终端界面将显示 OLED 模拟效果，可通过调整对比度使显示效果符合预期
进行微调：点击"反转"可生成白底 Logo，点击"像素"可单独控制每个像素点的亮灭状态
点击"导出"按钮，将在当前目录下生成 logo.bin 和 logo.ico 两个文件；完成后点击"退出"

步骤二：上传 Logo 文件

将 logo.bin 和 logo.ico 文件上传至 NanoKVM 的 /boot 目录：
- 通过 SCP 命令上传：
```
scp logo.bin logo.ico root@xxx.xxx.xxx.xxx:/boot
```
  默认登录密码为 root。如已修改 Web 管理界面密码，请使用修改后的密码进行认证。
- 或通过 TF 卡方式：将文件复制到 TF 卡的 boot 分区，NanoKVM 开机时将自动读取
重启 NanoKVM 设备，使配置生效

修改 USB VID/PID

NanoKVM 支持自定义 USB 设备的 Vendor ID (VID) 和 Product ID (PID)。您可以通过创建特定的配置文件来修改这些参数。

操作步骤

创建配置文件：
- 修改 VID：在 /boot 目录下创建 usb.vid 文件，写入四位十六进制的VID
- 修改 PID：在 /boot 目录下创建 usb.pid 文件，写入四位十六进制的PID
创建文件的方法有以下两种：

方法一：通过网页终端或 SSH 登录后创建

直接在 NanoKVM 的网页终端或通过 SSH 登录后，执行以下命令：
```
echo "0x3346" > /boot/usb.vid
echo "0x1009" > /boot/usb.pid
```
方法二：通过 TF 卡创建

如果方便取下 TF 卡，可以将 TF 卡插入电脑，在 boot 分区中直接创建 usb.vid 和 usb.pid 文件，并写入对应的值。
重启 NanoKVM 设备，修改将立即生效
恢复默认 VID/PID：删除 /boot/usb.vid 和 /boot/usb.pid 两个文件，然后重启设备即可恢复默认的 VID/PID。

验证效果

修改完成后，可以通过 lsusb 命令验证 VID/PID 是否生效：

$ lsusb
Bus 003 Device 089: ID 3346:1009 sipeed NanoKVM

注意：VID/PID 修改后，主机可能需要重新安装驱动程序。请确保使用合法的 VID/PID 组合，避免与现有设备冲突。

获取推流相关数据

推流和图像参数位于/kvmapp/kvm文件夹下

HDMI 获取的图像原始分辨率
- 图像宽度: /kvmapp/kvm/width
- 图像高度: /kvmapp/kvm/height
示例: 终端查看当前分辨率echo "$(cat /kvmapp/kvm/width) * $(cat /kvmapp/kvm/height)"
- 注: width/height 仅读取,不可写入,kvm_stream 根据该数据实时修改vi参数,自行修改将导致vi子系统无法解析正确图像
- 当两参数中有一个或两个全为0时,表明HDMI线缆拔出或 HDMI 分辨率正在切换
- width/height 两参数仅在HDMI插入,拔出,或改变分辨率时才能捕获,当 NanoKVM 在开机前插入HDMI线缆,并且HDMI输出非默认1080P分辨率时,vi子系统将无法获取正确的尺寸参数,导致无视频流输出,因此建议用户在第一次开机上电后再插入HDMI,后续每次开机会读取上次关机前保留的HDMI分辨率,故不会受到影响.
Stream 传输分辨率
- Stream 传输分辨率不同与 HDMI 获取的分辨率,有时为了减小传输数据量,可以设置一个较小的传输分辨率,NanoKVM会相应的对图像缩放后再传输
- 传输分辨率: /kvmapp/kvm/res
  - 0 : 自动,将跟随 HDMI 原始分辨率
  - 480 : 以640*480传输
  - 600 : 以800*600传输
  - 720 : 以1280*720传输
  - 1080: 以1920*1080传输
- 注: 该参数可读可写
示例: 终端设置 kvm_stream 以 1280*720 分辨率传输: echo 720 > /kvmapp/kvm/res
Stream 最大传输帧率
- 最大传输帧率: /kvmapp/kvm/fps
- 范围: 0-60
- 注: 参数可读可写
示例: 终端限制 kvm_stream 最大以 45 fps 传输: echo 45 > /kvmapp/kvm/fps
Stream 当前传输帧率
- 当前传输帧率: /kvmapp/kvm/now_fps
- 范围: 0-60
- 注: 参数只读
示例: 查看当前stream分辨率: cat /kvmapp/kvm/now_fps
查看硬件版本
- NanoKVM有不同的版本,版本之间硬件有所差异,详情请自行翻阅原理图,开机脚本将检测硬件差异,并保存在/etc/kvm/hw里
  - alpha : 早期内测版 NanoKVM Full
  - beta : 正式版 NanoKVM Full 和 Lite
  - pcie : NanoKVM PCIe
network相关配置
- /etc/kvm/server.yaml
- 详情参考WiKi->KVM->NanoKVM Cube->网络
USB状态获取
- cat /sys/class/udc/4340000.usb/state
  - configured 已连接
  - not attached 未连接
HDMI状态获取
- cat /kvmapp/kvm/state
  - 1：HDMI正常
  - 0：HDMI异常
ETH状态获取
- cat /sys/class/net/eth0/carrier
  - 1：网线接入
  - 0：网线断开（不准确）
WiFi存在
- /etc/kvm/wifi_exist 文件存在即为wifi模块存在
WiFi状态获取
- cat /kvmapp/kvm/wifi_state
  - 0：wifi存在但未连接
  - 1：wifi已连接
打开watchdog（实时）
- touch /etc/kvm/watchdog 打开
- rm /etc/kvm/watchdog 关闭
关闭ping功能
- touch /etc/kvm/stop_ping 关闭
- rm /etc/kvm/stop_ping 打开

USB HID模拟设备

初始化: NanoKVM借助USB Gedget 模拟 USB HID 设备, 在设备开机脚本 /etc/init.d/S03usbdev 中完成了键盘,鼠标,触屏的初始化
模拟键盘
- 设备: /dev/hidg0
- 报文：8byte：
  - 格式: |0x00|0x00|0xXX|0x00|0x00|0x00|0x00|0x00|
  - 第四位代表普通按键键值,如 F11: 0x44
  - 发送键值后需要及时释放
  - 示例: 按下F11按键
```
echo -ne \\x00\\x00\\x44\\x00\\x00\\x00\\x00\\x00 > /dev/hidg0   # 按下F11键
echo -ne \\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00 > /dev/hidg0   # 释放
```
模拟鼠标
- 设备: /dev/hidg1
- 报文：4byte：
  - 格式: |b8 按键|s8 x轴相对位移|s8 y轴相对位移|s8 滚轮|
  - 按键
    - 左键按下：0x01
    - 右键按下：0x12 # 兼容多系统
    - 释放：0x00
    - 示例: 点按左键
```
echo -ne \\x01\\x00\\x00\\x00 > /dev/hidg1  # 按下左键
echo -ne \\x00\\x00\\x00\\x00 > /dev/hidg1  # 释放
```
  - 位移 (相对位移)
    - x/y轴相对位移为带符号数，x正值向右移动，y正值向下移动
    - 示例: 右移5格，上移1格
```
echo -ne \\x00\\x05\\xff\\x00 > /dev/hidg1
```
  - 滚轮
    - 滚轮为带符号数，正值向下移动
    - 示例: 下移1格
```
echo -ne \\x00\\x00\\x00\\x01 > /dev/hidg1
```
模拟触屏
- 设备: /dev/hidg2
- 报文：6byte：
  - 格式: |按键|x轴绝对位置低8位|x轴绝对位置高8位|y轴绝对位置低8位|y轴绝对位置高8位|滚轮|
  - 按键
    - 左键按下：0x01
    - 右键按下：0x10
    - 释放：0x00
    - 示例: 点按左键
```
echo -ne \\x01\\x00\\x00\\x00\\x00\\x00 > /dev/hidg2  # 按下左键
echo -ne \\x00\\x00\\x00\\x00\\x00\\x00 > /dev/hidg2  # 释放
```
  - 位移 (绝对位置)
    - x/y均为无符号数，(0x0001,0x0001) 代表左上角, (0x7fff,0x7fff) 代表右下角
    - 示例: 鼠标移动至屏幕正中间
```
echo -ne \\x00\\xff\\x3f\\xff\\x3f\\x00 > /dev/hidg2
```
  - 滚轮
    - 滚轮为带符号数，正值向下移动
    - 示例: 下移1格
```
echo -ne \\x00\\x00\\x00\\x00\\x00\\x01 > /dev/hidg2
```

IO

ATX电源控制功能借助IO和外置的KVM-B实现，IO和功能对应关系如下
Alpha 版定义（包含早期NanoKVM-Cube）

功能	Linux GPIO编号
PWR LED 输入	504
PWR KEY 输出	503
RST KEY 输出	507

Beta 版定义（包含后期NanoKVM-Cube和全部的NanoKVM-PCIe）

功能	Linux GPIO编号
PWR LED 输入	504
PWR KEY 输出	503
RST KEY 输出	505

+ 读取LED状态 (以Beta为例)
    ```shell
    cat /sys/class/gpio/gpio504/value
    # 0 -> LED亮
    # 1 -> LED咩
    ```
+ 操作电源按钮 (以Beta为例)
    ```shell
    # 按下
    echo 1 > /sys/class/gpio/gpio503/value

    # 等待1s
    sleep 1

    # 抬起
    echo 0 > /sys/class/gpio/gpio503/value
    ```
+ 操作重启按钮 (以Beta为例)
    ```shell
    # 按下
    echo 1 > /sys/class/gpio/gpio505/value

    # 等待1s
    sleep 1

    # 抬起
    echo 0 > /sys/class/gpio/gpio505/value
    ```

其他IO：请参考 LicheeRV Nano GPIO 开发

注意事项

用户自己构建的程序请不要放在/kvmapp下,每次更新将会重置文件夹内所有内容
模拟键鼠操作可能与前端页面操作冲突

用户指南

Tailscale

wiki