# ukui-monitor-overlay

**Repository Path**: openkylin/ukui-monitor-overlay

## Basic Information

- **Project Name**: ukui-monitor-overlay
- **Description**: UKUI Monitor Overlay 是一款专为 UKUI 桌面环境设计的轻量级系统监控悬浮窗工具
- **Primary Language**: C++
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/openkylin/ukui-monitor-overlay
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 4
- **Created**: 2025-05-29
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: UKUI, openKylin, Qt

## README

# UKUI Monitor Overlay


<div align="center">
<img src="./Screenshot.png" width="400" alt="ukui-perf-controller"/>
</div>


## 介绍

UKUI Monitor Overlay 是一款专为 openKylin 以及 UKUI 桌面环境设计的轻量级系统监控悬浮窗工具，具有以下特色：

- 实时显示硬件状态信息
- 悬浮窗始终显示在桌面最上层
- 支持多种硬件监控和功能扩展
- 支持自定义显示项、主题等
- 支持自定义监视器插件扩展，强大的可扩展性

## 快速开始

### 从源码编译安装

```bash
# 克隆仓库
git clone https://gitee.com/openkylin/ukui-monitor-overlay.git
cd ukui-monitor-overlay

# 编译
mkdir build && cd build
cmake ..
make

# 安装
sudo make install
```

### 开机自启动

默认会将`ukui-monitor-overlay.desktop`添加到`/etc/xdg/autostart/`，如果需要取消自启动请手动删除。

```bash
sudo rm -rf /etc/xdg/autostart/ukui-monitor-overlay.desktop
```

### 使用 Qt Creator 开发

1. 打开 Qt Creator
2. 导入项目
3. 配置构建套件
4. 构建并运行

### 卸载

可以通过apt卸载

```bash
sudo apt purge ukui-monitor-overlay
```

## 打包发布

```bash
cd ukui-monitor-overlay
debmake
debuild -us -uc -ui
```

## 配置设置

应用设置文件位于：
```
~/.config/ukui-monitor-overlay/settings.conf
```

建议在应用内通过设置面板进行调整。

## 系统兼容性

| 操作系统 | 版本 |
|---------|------|
| openKylin | 2.0 (nile) |
| openKylin | 3.0 (huanghe) |

## 功能路线图

### 已实现功能
- **CPU 监控** - 占用率、频率
- **内存监控** - 占用率
- **GPU 监控** - 占用率、显存、温度、频率
  - NVIDIA GPU - 完全支持
  - AMD GPU - 完全支持
  - Intel GPU - 部分支持（核心占用）
- **界面定制** - 字体大小/颜色、背景颜色、显示项选择
- **窗口功能** - 置顶显示、可拖动、系统托盘
- **系统集成** - 桌面图标、开机启动

### 开发中功能
- **网络监控** - 上行/下行状态
- **GPU 支持扩展**
  - PowerVR GPU - 实现中
  - Mali GPU - 实现中
- **界面优化** - 背景透明度调整
- **国际化** - 多语言支持


## 开发指南

### 环境依赖

```bash
# 基础编译工具
sudo apt install build-essential cmake

# openKylin SDK（如果在openKylin平台编译）
sudo apt install libkysdk-hardware libkysdk-hardware-dev
sudo apt install libkysdk-qtwidgets libkysdk-qtwidgets-dev
sudo apt install libkysdk-waylandhelper libkysdk-waylandhelper-dev
sudo apt install libkf5windowsystem-dev
```

### openKylin OpenSDK 问题排查

如果遇到 GPU 信息获取错误：
```bash
The name com.kylin.kysdk.service was not provided by any .service files
```

请安装并启用所需服务：
```bash
sudo apt install libkysdk-system-dbus
systemctl status kysdk-dbus.service
systemctl enable kysdk-dbus.service
```

正常输出应显示服务正在运行：
```
● kysdk-dbus.service - KYLIN SDK SYSTIME DBUS
     Loaded: loaded (/usr/lib/systemd/system/kysdk-dbus.service; enabled)
     Active: active (running)
```

### 进程监控

查看进程运行的 CPU 核心：
```bash
ps -o pid,psr,comm -p <进程ID>
```

### GPU 驱动要求

#### NVIDIA GPU
确保正确安装驱动并能运行 `nvidia-smi` 命令。

如果遇到以下问题，通常指向系统未能正确加载或与NVIDIA内核驱动程序通信：
```bash
NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver. Make sure that the latest NVIDIA driver is installed and running.
```

可以尝试手动加载驱动模块并排查问题：

```bash
sudo modprobe nvidia
sudo modprobe nvidia_uvm
```



#### AMD GPU
验证以下系统文件存在：
```bash
cat /sys/class/drm/card0/device/vendor           # 应显示 0x1002
cat /sys/class/drm/card0/device/gpu_busy_percent # GPU 使用率
cat /sys/class/drm/card0/device/mem_info_vram_*  # 显存信息
```

#### Intel GPU
验证以下系统文件存在：
```bash
cat /sys/class/drm/card0/gt_act_freq_mhz    # GPU 当前频率
cat /sys/class/drm/card0/gt_max_freq_mhz    # GPU 最大频率
```

## GPU 监视器接口开发

我们欢迎为更多 GPU 型号提供支持！参考以下接口实现：

### 基础接口定义

```cpp
#ifndef GPUMONITORINTERFACE_H
#define GPUMONITORINTERFACE_H

/**
 * @brief GPU 监视器接口基类
 */
class GpuMonitorInterface {
public:
    virtual ~GpuMonitorInterface() = default;
    
    /**
     * @brief 获取 GPU 核心占用率
     * @return 占用率百分比，失败返回 -1
     */
    virtual double getGpuCoreUsage() = 0;
    
    /**
     * @brief 获取 GPU 显存占用率  
     * @return 占用率百分比，失败返回 -1
     */
    virtual double getGpuMemUsage() = 0;
};

#endif // GPUMONITORINTERFACE_H
```

### NVIDIA GPU 实现示例

```cpp
// nvgpumonitor.h
#ifndef NVGPUMONITOR_H
#define NVGPUMONITOR_H

#include "gpu_monitor_interface.h"

class NVGpuMonitor : public GpuMonitorInterface {
public:
    NVGpuMonitor();
    ~NVGpuMonitor() override;
    
    double getGpuCoreUsage() override;
    double getGpuMemUsage() override;
};

#endif // NVGPUMONITOR_H
```

```cpp
// nvgpumonitor.cpp
#include "nvgpumonitor.h"
#include <QProcess>

double NVGpuMonitor::getGpuCoreUsage() {
    QProcess process;
    process.start("nvidia-smi", {
        "--query-gpu=utilization.gpu",
        "--format=csv,noheader,nounits"
    });
    process.waitForFinished();
    
    QString output = process.readAllStandardOutput();
    return output.trimmed().toDouble();
}

double NVGpuMonitor::getGpuMemUsage() {
    QProcess process;
    process.start("nvidia-smi", {
        "--query-gpu=memory.used,memory.total", 
        "--format=csv,noheader,nounits"
    });
    process.waitForFinished();
    
    QStringList parts = QString(process.readAllStandardOutput())
                       .trimmed().split(',');
    if (parts.size() >= 2) {
        double used = parts[0].toDouble();
        double total = parts[1].toDouble();
        return (used / total) * 100;
    }
    return -1;
}
```


**欢迎提交 PR 来丰富我们的 GPU 支持！**

## 插件开发指南

### 插件系统概述

为了支持更多硬件设备，本项目参考 [UKUI Quick](https://gitee.com/openkylin/ukui-quick) 项目实现了一套插件系统，可以方便地扩展支持特殊硬件设备。

### 创建插件项目

#### CMake 配置

```cmake
cmake_minimum_required(VERSION 3.14)

set(PROJECT_NAME ukui-monitor-testplugin)
project(${PROJECT_NAME} LANGUAGES CXX)

set(CMAKE_INCLUDE_CURRENT_DIR ON)
set(CMAKE_AUTOUIC ON)
set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(QT NAMES Qt6 Qt5 COMPONENTS Core REQUIRED)
find_package(Qt${QT_VERSION_MAJOR} COMPONENTS Core REQUIRED)

add_library(${PROJECT_NAME} SHARED
    DiskTestPlugin_global.h
    ukui_monitor_testplugin.cpp
    ukui_monitor_testplugin.h
    ../../include/systeminfoplugininterface.h
)

target_link_libraries(${PROJECT_NAME} PRIVATE Qt${QT_VERSION_MAJOR}::Core)
target_compile_definitions(${PROJECT_NAME} PRIVATE DISKTESTPLUGIN_LIBRARY)
```

#### 插件接口定义

```cpp
#ifndef SYSTEMINFOPLUGININTERFACE_H
#define SYSTEMINFOPLUGININTERFACE_H

#define PluginInterfaceIID "com.ukui-monitor-overlay.SystemInfoPluginInterface/1.0"

#include <QObject>
#include <QString>
#include <QVariant>

/**
 * @brief 系统信息插件接口
 */
class SystemInfoPluginInterface : public QObject {
    Q_OBJECT
    
public:
    virtual ~SystemInfoPluginInterface() = default;
    
    // 插件基本信息
    virtual QString name() const = 0;           // 插件名称
    virtual QString displayName() const = 0;    // 显示名称
    virtual QString description() const = 0;    // 插件描述
    virtual QString author() const { return QString(); }  // 作者（可选）
    
    // 监控功能
    virtual QVariant getMonitoringValue() const = 0;  // 获取监控值
};

Q_DECLARE_INTERFACE(SystemInfoPluginInterface, PluginInterfaceIID)

#endif // SYSTEMINFOPLUGININTERFACE_H
```

#### 插件实现示例

```cpp
// ukui_monitor_testplugin.h
#ifndef UKUI_MONITOR_TESTPLUGIN_H
#define UKUI_MONITOR_TESTPLUGIN_H

#include "systeminfoplugininterface.h"

class UKUIMonitorTestPlugin : public SystemInfoPluginInterface {
    Q_OBJECT
    Q_PLUGIN_METADATA(IID PluginInterfaceIID)
    Q_INTERFACES(SystemInfoPluginInterface)

public:
    explicit UKUIMonitorTestPlugin();
    ~UKUIMonitorTestPlugin() override;
    
    QString name() const override;
    QString displayName() const override;
    QString description() const override;
    QString author() const override;
    QVariant getMonitoringValue() const override;
};

#endif // UKUI_MONITOR_TESTPLUGIN_H

```

```cpp
// ukui_monitor_testplugin.cpp
#include "ukui_monitor_testplugin.h"
#include <random>
#include <cmath>
#include <QDebug>

UKUIMonitorTestPlugin::UKUIMonitorTestPlugin() {
    qDebug() << "测试插件已加载";
}

QString UKUIMonitorTestPlugin::name() const {
    return "XXX温度插件";
}

QString UKUIMonitorTestPlugin::displayName() const {
    return "XXX温度";
}

QString UKUIMonitorTestPlugin::description() const {
    return "该插件用于获取XXX设备的温度信息";
}

QString UKUIMonitorTestPlugin::author() const {
    return "DSOE1024";
}

QVariant UKUIMonitorTestPlugin::getMonitoringValue() const {
    // 生成模拟温度数据 (10-99°C)
    std::random_device rd;
    std::mt19937 gen(rd());
    std::uniform_int_distribution<> distrib(10, 99);

    return QString::number(distrib(gen));
}


UKUIMonitorTestPlugin::~UKUIMonitorTestPlugin()
{
    // 可以为空
}
```

### 插件分发与安装

1. **编译插件** - 成功编译后生成 `.so` 文件
2. **分发插件** - 可在 openKylin 论坛和源码仓库分发
3. **安装插件** - 复制到用户插件目录：

```bash
cp your-plugin.so ~/.local/share/monitor-overlay/plugins$
```


**注意**: 项目正在快速迭代中，插件系统可能调整，请参考最新文档。

## 项目维护

### 核心维护者

- **[DSOE1024](https://gitee.com/DSOE1024)** - computerlub@163.com

### 特别致谢

感谢以下贡献者的宝贵支持：

- [chipo](https://gitee.com/chipo) - 功能验证与测试
- [gitealinux](https://gitee.com/gitealinux) - 系统兼容性测试

## 许可证

本项目主要代码遵循 **GPLv3** 开源协议，详见 [LICENSE](LICENSE) 文件。

为了让“插件特殊条款”在法律和技术层面更加明确，同时兼顾硬件厂商 SDK 的授权限制，建议使用以下更规范的表述替换原有内容：



### 插件特殊条款

本项目的核心代码（不含插件部分）采用 **GPLv3** 许可证。为了允许开发者自由扩展硬件支持并兼容专有 SDK，特对插件相关代码作出如下例外规定：


- 插件开发者需自行承担使用专有 SDK 可能带来的合法性、可靠性、安全性等风险（如授权费、二次分发限制等）。

- 文件 `systeminfoplugininterface.h` 及其声明的接口类（`SystemInfoPluginInterface`）、宏（`PluginInterfaceIID`）等，**单独以 LGPLv3 许可证发布**。
- 基于该头文件开发的插件（无论闭源或开源）遵循以下条件：
  - 必须**动态链接**到主程序，不得静态链接或以其他方式将 GPLv3 代码合并到插件中。
  - 不得修改该头文件的内容并重新分发。
  - 满足 LGPLv3 对调用接口的基本要求（即用户有能力替换该接口的实现，通常通过动态链接实现）。

- 插件中继承 `SystemInfoPluginInterface` 的具体实现类、辅助功能代码等，**可以选择任意许可证**（包括闭源、商业授权、GPL、MIT、Apache 等）。插件对应的源代码**无需公开**，可以完全私有。


- 插件可以仅以编译后的动态库（如 `.so` 文件）形式单独分发，无需附带源代码。
- 插件分发时须注明：
  - 插件名称、版本、作者、适用平台。
  - 所依赖的外部 SDK 及其授权条款（如果有）。
  - 不包含主程序 GPLv3 代码的衍生部分（如直接复制主程序的非接口代码）。

- 对于必须调用厂商专有 SDK（例如不提供开源授权的 GPU 驱动库、硬件加速库等）才能获取监控数据的插件，**完全允许闭源并仅提供二进制形式**。