RK3506 嵌入式 Qt 控制面板开发教程

从零开始，在幸狐 RK3506 Lyra Pi W 上用 Qt 5.12.9 开发一个带触屏界面的嵌入式控制面板。
硬件: 幸狐 RK3506 Lyra Pi W / 1024×600 触摸屏
软件: Qt 5.12.9 / C++11 / Buildroot Linux

一、环境搭建

1.1 两个 qmake

开发嵌入式 Qt 需要两套 qmake：

用途	路径	说明
x86 本地调试	`Qt5.12.9/5.12.9/gcc_64/bin/qmake`	编译 x86 版本，电脑上直接运行测试
ARM 交叉编译	`Lyra-sdk/buildroot/output/.../host/bin/qmake`	编译 ARM 版本，部署到开发板

为什么需要两个？ 嵌入式设备不方便频繁部署调试，先在电脑上跑通 UI 逻辑，再交叉编译到板子上。

1.2 x86 本地测试

mkdir build_x86 && cd build_x86
/home/robbieht/Qt5.12.9/5.12.9/gcc_64/bin/qmake ../YourProject.pro
make -j$(nproc)
./YourProject

1.3 ARM 交叉编译

mkdir build && cd build
/home/robbieht/Lyra-sdk/buildroot/output/rockchip_rk3506_luckfox/host/bin/qmake \
    ../YourProject.pro "CONFIG+=release" "CONFIG-=debug"
make -j$(nproc)

注意: Release 模式用 CONFIG+=release CONFIG-=debug，嵌入式设备资源有限，不要带调试符号。

1.4 部署到设备

# 把编译产物和插件一起打包
mkdir -p release/plugins
cp build/YourProject release/
cp build/plugins/*.so release/plugins/

# 推送到设备
scp -r release/* root@<设备IP>:/opt/
ssh root@<设备IP>
chmod +x /opt/YourProject
/opt/YourProject

二、插件系统架构

当控制面板需要多个功能模块（终端、文件管理器、蓝牙等）时，插件化是最干净的方案。

2.1 定义接口

// appinterface.h
#include <QWidget>
#include <QString>

class AppInterface {
public:
    virtual ~AppInterface() = default;
    virtual QString appName() const = 0;      // 模块名称
    virtual QString iconPath() const = 0;      // 侧边栏图标
    virtual QWidget* contentWidget() = 0;      // 内容页面
    virtual void initialize() = 0;             // 初始化
};

#define AppInterface_iid "com.lyra.shell.AppInterface"
Q_DECLARE_INTERFACE(AppInterface, AppInterface_iid)

2.2 实现插件

// shellplugin.h
#include <QObject>
#include "appinterface.h"

class ShellPlugin : public QObject, public AppInterface {
    Q_OBJECT
    Q_INTERFACES(AppInterface)
    Q_PLUGIN_METADATA(IID "com.lyra.shell.AppInterface")

public:
    QString appName() const override { return "终端"; }
    QString iconPath() const override { return ":/icons/terminal.png"; }
    QWidget* contentWidget() override;
    void initialize() override;

private:
    QWidget* m_widget = nullptr;  // 懒加载，缓存
};

2.3 独立 .pro 文件

每个插件一个 .pro，编译为独立 .so：

QT       += core gui widgets
TARGET = shell
TEMPLATE = lib
CONFIG += plugin
DESTDIR = ../plugins
SOURCES += shellplugin.cpp
HEADERS += shellplugin.h

2.4 主程序加载插件

QString pluginsPath = QCoreApplication::applicationDirPath() + "/plugins";
QDir dir(pluginsPath);
for (const QString& fileName : dir.entryList({"*.so"}, QDir::Files)) {
    QPluginLoader loader(dir.absoluteFilePath(fileName));
    QObject* obj = loader.instance();
    if (AppInterface* app = qobject_cast<AppInterface*>(obj)) {
        app->initialize();
        // 注册到侧边栏...
    }
}

踩坑提醒: 插件类中不要定义名为 connect() 的方法，否则会遮蔽 QObject::connect()，导致所有信号槽连接静默失效。取别的名字，比如 connectDevice()。

三、PTY 伪终端

在 Qt 应用里嵌入一个真正的 bash 终端，需要 Linux 的 PTY（伪终端）。

3.1 核心原理

┌─────────────┐    PTY     ┌──────────┐
│  Qt 界面    │ ◄────────► │  bash    │
│ (父进程)    │   fd 通信   │ (子进程) │
└─────────────┘            └──────────┘

forkpty() 一步完成：创建伪终端对 + fork 子进程。

3.2 实现代码

#include <pty.h>
#include <unistd.h>
#include <QSocketNotifier>

struct winsize ws = {rows, cols, 0, 0};
int ptyFd;
pid_t childPid = forkpty(&ptyFd, nullptr, nullptr, &ws);

if (childPid == 0) {
    // 子进程：启动 bash
    execlp("/bin/bash", "bash", "--login", nullptr);
    _exit(127);
}

// 父进程：用 QSocketNotifier 把 PTY 数据接入 Qt 事件循环
auto* notifier = new QSocketNotifier(ptyFd, QSocketNotifier::Read, this);
connect(notifier, &QSocketNotifier::activated, this, [this, ptyFd]() {
    char buf[4096];
    ssize_t n = read(ptyFd, buf, sizeof(buf));
    if (n > 0) {
        // 将终端输出追加到 QTextEdit 或 QPlainTextEdit
        appendOutput(QByteArray(buf, n));
    }
});

3.3 发送按键到终端

void sendToTerminal(const QString& text) {
    QByteArray data = text.toLocal8Bit();
    write(ptyFd, data.constData(), data.size());
}

3.4 方向键处理

方向键不是普通字符，需要发送 ANSI 转义序列：

按键	序列	十六进制
↑	`\033[A`	`1B 5B 41`
↓	`\033[B`	`1B 5B 42`
→	`\033[C`	`1B 5B 43`
←	`\033[D`	`1B 5B 44`

四、软键盘

嵌入式触屏没有物理键盘，需要自己做一个浮动软键盘。

4.1 布局

┌─────────────────────────────────┐
│  1  2  3  4  5  6  7  8  9  0  │  ← 数字行
│  Q  W  E  R  T  Y  U  I  O  P  │
│  A  S  D  F  G  H  J  K  L     │
│  Z  X  C  V  B  N  M           │
│  [Ctrl] [Space] [←] [→] [Enter]│  ← 特殊键
└─────────────────────────────────┘

4.2 实现

// 创建一行按键
QHBoxLayout* row = new QHBoxLayout;
for (const QString& key : {"Q","W","E","R","T","Y","U","I","O","P"}) {
    auto* btn = new QPushButton(key);
    btn->setFixedSize(60, 50);  // 触屏友好：按钮要大
    connect(btn, &QPushButton::clicked, [this, key]() {
        emit keyPressed(key.toLower());
    });
    row->addWidget(btn);
}

4.3 特殊键映射

// Enter
connect(btnEnter, &QPushButton::clicked, [this]() {
    sendToTerminal("\r");
});

// Backspace
connect(btnBack, &QPushButton::clicked, [this]() {
    sendToTerminal("\x7f");
});

// 方向键
connect(btnUp, &QPushButton::clicked, [this]() {
    sendToTerminal("\033[A");
});

踩坑提醒: 写键盘布局注释时，行尾不要有 \，它是 C++ 的续行符，会把下一行代码吃掉。看起来完全正常，但行为截然不同。

五、QSS 主题系统

5.1 基本架构

themes/
├── dark.qss      # 深色主题
└── light.qss     # 浅色主题

通过 resources.qrc 编译进二进制，运行时通过 ThemeManager 切换。

5.2 QSS 写法

/* dark.qss */
QWidget#sidebar {
    background-color: #1e1e2e;
}

QPushButton#sidebar-item {
    color: #cdd6f4;
    border: none;
    padding: 12px;
    border-radius: 8px;
}

QPushButton#sidebar-item:hover {
    background-color: #313244;
}

5.3 主题切换

// ThemeManager 单例
class ThemeManager : public QObject {
    Q_OBJECT
public:
    static ThemeManager* instance();

    void setTheme(const QString& name);  // "dark" 或 "light"
    QString currentTheme() const;

private:
    QString m_theme;
    // 配置持久化到 ~/.lyrashell/theme.conf
};

5.4 自定义绘制组件

QSS 能覆盖标准控件，但自己用 QPainter 画的组件需要手动判断主题：

void SidebarItem::drawIcon(QPainter& painter) {
    if (ThemeManager::instance()->currentTheme().startsWith("light")) {
        painter.setPen(QColor("#333333"));  // 浅色主题用深色图标
    } else {
        painter.setPen(QColor("#ffffff"));  // 深色主题用浅色图标
    }
    // QPainterPath 绘制图标...
}

六、触屏交互

6.1 长按菜单

触屏没有右键，用长按模拟：

// 安装事件过滤器
widget->installEventFilter(this);
widget->setContextMenuPolicy(Qt::CustomContextMenu);

bool MyWidget::eventFilter(QObject* obj, QEvent* event) {
    if (event->type() == QEvent::MouseButtonPress ||
        event->type() == QEvent::TouchBegin) {
        // 启动 600ms 定时器
        m_longPressTimer->start(600);
    }
    else if (event->type() == QEvent::MouseButtonRelease ||
             event->type() == QEvent::TouchEnd) {
        m_longPressTimer->stop();  // 提前释放，取消
    }
    return QObject::eventFilter(obj, event);
}

// 定时器触发 → 发射右键信号
connect(m_longPressTimer, &QTimer::timeout, [this, pos]() {
    emit customContextMenuRequested(pos);
});

6.2 中文字体

嵌入式系统默认没有中文字体。添加文泉驿正黑：

// 编译时把字体加入 resources.qrc
// 运行时加载
int fontId = QFontDatabase::addApplicationFont(":/fonts/wqy-zenhei.ttc");
QString family = QFontDatabase::applicationFontFamilies(fontId).at(0);
QApplication::setFont(QFont(family));

七、读取系统信息

7.1 CPU 使用率

读 /proc/stat，两次采样算差值：

QFile file("/proc/stat");
file.open(QIODevice::ReadOnly | QIODevice::Text);
QString line = file.readLine();  // "cpu  user nice system idle iowait irq softirq"
QStringList parts = line.split(QRegExp("\\s+"));

qint64 idle = parts[4].toLongLong();
qint64 total = 0;
for (int i = 1; i <= 7; i++) total += parts[i].toLongLong();

// 两次采样的差值
int cpuPercent = (totalDiff - idleDiff) * 100 / totalDiff;

7.2 内存信息

读 /proc/meminfo，用 QFile::readLine() 而不是 QTextStream：

QFile file("/proc/meminfo");
file.open(QIODevice::ReadOnly | QIODevice::Text);

while (!file.atEnd()) {
    QString line = QString::fromLocal8Bit(file.readLine()).trimmed();

    if (line.startsWith("MemTotal:")) {
        // 提取冒号后的数字
        QString val = line.section(':', 1).trimmed();
        QString numStr;
        for (const QChar& c : val) {
            if (c.isDigit()) numStr += c;
            else if (!numStr.isEmpty()) break;
        }
        memTotal = numStr.toLongLong();  // 单位 kB
    }
    // MemFree, MemAvailable, Buffers, Cached 同理...
}

重要: 读 /proc 和 /sys 虚拟文件时，不要用 QTextStream。它内部的缓冲区和 seek 操作与虚拟文件系统不兼容，在嵌入式设备上可能读到空内容。用 QFile::readLine() 或 QFile::readAll() 直接读取。

八、双栏文件管理器

8.1 架构

┌──────────────────────────────────────┐
│  工具栏: [复制] [剪切] [粘贴] [删除]  │
├────────────────┬─────────────────────┤
│   左栏         │    右栏             │
│  /home/user    │   /media/usb        │
│  ├─ Documents  │   ├─ file1.txt      │
│  ├─ Pictures   │   └─ file2.txt      │
│  └─ Music      │                     │
├────────────────┴─────────────────────┤
│  状态栏                              │
└──────────────────────────────────────┘

8.2 活动面板追踪

int m_activePanel = 0;  // 0=左, 1=右

// 点击左栏
connect(leftView, &QListView::clicked, [this]() {
    m_activePanel = 0;
});

// 点击右栏
connect(rightView, &QListView::clicked, [this]() {
    m_activePanel = 1;
});

// 工具栏操作作用于活动面板
void onCopy() {
    if (m_activePanel == 0) {
        // 从左栏复制到右栏
        m_rightManager->paste(m_leftManager->selectedFiles());
    } else {
        m_leftManager->paste(m_rightManager->selectedFiles());
    }
}

九、蓝牙

9.1 bluetoothctl 常用命令

bluetoothctl
power on
scan on
trust XX:XX:XX:XX:XX:XX
pair XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX

9.2 程序化调用

# 非交互式执行
echo 'power on' | bluetoothctl
echo 'scan on' | bluetoothctl

注意: RK3506 上 Wi-Fi 和蓝牙共用模块，切换蓝牙可能需要修改 /usr/bin/wifibt-util.sh。

十、常见问题速查表

问题	原因	解决
SVG 图标不显示	嵌入式 Qt 无 SVG 模块	用 QPainter 绘制或 PNG 替代
中文显示方块	缺少中文字体	添加文泉驿 `wqy-zenhei.ttc`
图片加载失败	qrc 路径与代码不一致	确保 `":/path"` 与 qrc 中完全一致
信号槽不生效	自定义方法名遮蔽 `QObject::connect`	重命名，避免 `connect()` 等保留名
`QProcess::finished` 编译错误	Qt 5 有两个重载	用 `QOverload<int, QProcess::ExitStatus>::of(...)`
内存信息 N/A	`QTextStream` 不兼容 `/proc`	改用 `QFile::readLine()`
触屏无右键菜单	`customContextMenuRequested` 不响应触摸	eventFilter + 600ms 长按定时器
奇怪的编译/运行错误	注释末尾的 `\` 续行符	删除注释末尾的反斜杠

项目结构参考

YourProject/
├── main.cpp
├── mainwindow.h/cpp      # 主窗口
├── YourProject.pro
├── resources.qrc          # 资源文件
├── fonts/                 # 字体（编译进资源）
├── resources/             # 图片资源
├── themes/                # QSS 主题文件
├── utils/                 # 工具类（ThemeManager 等）
├── sidebar/               # 侧边栏
├── content/               # 内容区域
├── widgets/               # 自定义控件
├── apps/                  # AppInterface + AppManager
├── sysinfo/               # 系统信息模块
├── filemanager/           # 文件管理器
├── shell/                 # Shell 终端插件（独立 .pro）
├── bluetooth/             # 蓝牙模块
├── build/                 # ARM 编译输出（.gitignore）
├── build_x86/             # x86 编译输出（.gitignore）
└── release/               # 部署包（.gitignore）

RK3506 嵌入式 Qt 控制面板开发教程

RK3506 嵌入式 Qt 控制面板开发教程

一、环境搭建

1.1 两个 qmake

1.2 x86 本地测试

1.3 ARM 交叉编译

1.4 部署到设备

二、插件系统架构

2.1 定义接口

2.2 实现插件

2.3 独立 .pro 文件

2.4 主程序加载插件

三、PTY 伪终端

3.1 核心原理

3.2 实现代码

3.3 发送按键到终端

3.4 方向键处理

四、软键盘

4.1 布局

4.2 实现

4.3 特殊键映射

五、QSS 主题系统

5.1 基本架构

5.2 QSS 写法

5.3 主题切换

5.4 自定义绘制组件

六、触屏交互

6.1 长按菜单

6.2 中文字体

七、读取系统信息

7.1 CPU 使用率

7.2 内存信息

八、双栏文件管理器

8.1 架构

8.2 活动面板追踪

九、蓝牙

9.1 bluetoothctl 常用命令

9.2 程序化调用

十、常见问题速查表

项目结构参考

添加新评论

最新文章

最近回复

分类

归档

其它