QtUsb：跨平台USB模块开发教程

QtUsb：跨平台USB模块开发教程

【免费下载链接】QtUsb A cross-platform USB Module for Qt. 项目地址: https://gitcode.com/gh_mirrors/qt/QtUsb

QtUsb是一个专为Qt框架设计的跨平台USB模块，基于libusb-1.0和libhidapi库构建。它提供了丰富的API来管理和操作USB设备，支持批量传输、中断传输、热插拔检测和设备枚举过滤等功能。

环境准备与安装

系统依赖安装

在开始使用QtUsb之前，需要安装必要的系统依赖库：

# Ubuntu/Debian系统
sudo apt-get install libusb-1.0-0-dev libhidapi-dev pkg-config

# 如果需要使用系统包，还需要安装
sudo apt-get install qt6-base-private-dev

获取QtUsb源码

从官方仓库克隆项目代码：

git clone https://gitcode.com/gh_mirrors/qt/QtUsb
cd QtUsb

编译安装

使用CMake进行编译安装：

mkdir build
cd build
cmake ..
make
sudo make install

或者构建为静态模块以获得更好的可移植性：

mkdir build
cd build
cmake -DQTUSB_AS_STATIC_MODULE=ON ..
make
sudo make install

在Qt项目中使用QtUsb

配置项目文件

在你的Qt项目CMakeLists.txt中添加QtUsb依赖：

find_package(Qt6 REQUIRED COMPONENTS Core Usb)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE Qt6::Core Qt6::Usb)

基本使用示例

创建一个简单的USB设备列表应用：

#include <QCoreApplication>
#include <QUsb>
#include <QUsbDevice>
#include <QDebug>

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    
    QUsb usb;
    QUsb::IdList devices = usb.devices();
    
    qDebug() << "发现" << devices.size() << "个USB设备:";
    
    for (const QUsb::Id &device : devices) {
        qDebug() << "VID:" << QString::number(device.vid, 16)
                 << "PID:" << QString::number(device.pid, 16)
                 << "总线:" << device.bus
                 << "端口:" << device.port;
    }
    
    return app.exec();
}

核心API详解

QUsb类

QUsb是主要的USB管理类，提供设备枚举和热插拔检测功能：

// 获取所有USB设备
QUsb::IdList devices = QUsb::devices();

// 检查特定设备是否存在
QUsb::Id targetDevice(0x1234, 0x5678); // VID=0x1234, PID=0x5678
bool isPresent = usb.isPresent(targetDevice);

// 设置日志级别
usb.setLogLevel(QUsb::logDebug);

QUsbDevice类

QUsbDevice用于具体的USB设备操作：

QUsbDevice device;
QUsbDevice::Config config;

// 配置设备
config.speed = QUsbDevice::fullSpeed;
config.config = 1;
config.interface = 0;
config.alternate = 0;

// 打开设备
if (device.open(targetDevice, config)) {
    qDebug() << "设备打开成功";
    
    // 进行数据传输操作...
    
    device.close();
} else {
    qDebug() << "设备打开失败:" << device.errorString();
}

实际应用案例

USB设备监控应用

创建一个实时监控USB设备插拔的应用：

#include <QCoreApplication>
#include <QUsb>
#include <QDebug>

class UsbMonitor : public QObject
{
    Q_OBJECT
public:
    explicit UsbMonitor(QObject *parent = nullptr) : QObject(parent)
    {
        connect(&m_usb, &QUsb::deviceInserted, this, &UsbMonitor::onDeviceInserted);
        connect(&m_usb, &QUsb::deviceRemoved, this, &UsbMonitor::onDeviceRemoved);
    }

private slots:
    void onDeviceInserted(QUsb::Id id)
    {
        qDebug() << "设备插入:" << "VID:" << QString::number(id.vid, 16)
                 << "PID:" << QString::number(id.pid, 16);
    }

    void onDeviceRemoved(QUsb::Id id)
    {
        qDebug() << "设备移除:" << "VID:" << QString::number(id.vid, 16)
                 << "PID:" << QString::number(id.pid, 16);
    }

private:
    QUsb m_usb;
};

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);
    UsbMonitor monitor;
    return app.exec();
}

批量数据传输示例

// 创建端点进行批量传输
QUsbEndpoint endpoint(&device);
endpoint.setEndpoint(0x01); // 输出端点
endpoint.setType(QUsbEndpoint::bulk);

QByteArray data("Hello USB!");
qint64 bytesWritten = endpoint.write(data);

if (bytesWritten == -1) {
    qDebug() << "写入失败:" << endpoint.errorString();
} else {
    qDebug() << "成功写入" << bytesWritten << "字节";
}

最佳实践建议

1. 错误处理：始终检查USB操作的返回值，使用errorString()获取详细错误信息
2. 权限管理：在Linux系统中确保应用程序有访问USB设备的权限
3. 资源释放：使用完毕后及时调用close()释放设备资源
4. 异步操作：对于耗时操作使用异步方式避免界面冻结
5. 设备过滤：使用QUsb::Id的过滤功能只监听特定类型的设备

常见问题解决

权限问题

在Linux系统中，可能需要将用户添加到plugdev组：

sudo usermod -a -G plugdev $USER

或者创建udev规则文件 /etc/udev/rules.d/99-myusb.rules：

SUBSYSTEM=="usb", MODE="0666", GROUP="plugdev"

编译问题

如果遇到编译错误，确保：

• 所有依赖库已正确安装
• CMake能找到Qt6和QtUsb模块
• 使用正确的Qt版本（需要Qt6或更高版本）

QtUsb为Qt开发者提供了强大而便捷的USB设备操作能力，通过合理的API设计和跨平台支持，使得开发USB相关应用变得更加简单高效。

【免费下载链接】QtUsb A cross-platform USB Module for Qt. 项目地址: https://gitcode.com/gh_mirrors/qt/QtUsb