# 玩客云ONEKVM GPIO 软件 I2C 驱动 SSD1315 OLED 显示系统信息

**Repository Path**: edik/onekvm-0.96oledssd1315

## Basic Information

- **Project Name**: 玩客云ONEKVM GPIO 软件 I2C 驱动 SSD1315 OLED 显示系统信息
- **Description**: Python 脚本，在玩客云上通过软件模拟 I2C 协议驱动一块 0.96 英寸的 SSD1315 OLED 四针i2c显示屏.
自定义名称: 从 name.txt 文件中读取并显示一个用户自定义的名称。
CPU 使用率: 实时显示 CPU 的使用率。
网络信息: 显示 IP 地址和 MAC 地址。
时间: 显示系统当前时间。
所有信息会以文本形式循环刷新显示在 OLED 屏幕上。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-29
- **Last Updated**: 2025-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 玩客云 GPIO 软件 I2C 驱动 SSD1315 OLED 显示系统信息
![输入图片说明](https://foruda.gitee.com/images/1756548248010752710/31964b2f_8205241.jpeg "271bea8b211e74da3a1bb849459a8883.jpg")
## 项目简介

本项目提供了一套完整的 Python 脚本，用于在玩客云 onekvm 系统上，通过软件模拟 I2C 协议驱动一块 0.96 英寸的 SSD1315 OLED 显示屏（I2C 接口）。

根据当前 `sysinfo.py` 代码的实际功能，它会读取并显示以下实时系统信息：

- **自定义名称**：从 `name.txt` 文件中读取用户自定义名称（若文件不存在或读取失败，则显示默认名称 `"NoName"`）。
- **CPU 使用率**：实时显示 CPU 使用率。
- **网络信息**：显示 IP 地址和 MAC 地址。
- **当前系统时间**：显示系统当前日期和时间。
- **屏幕刷新**：信息约每 2 秒刷新一次。

> ⚠️ 注意：当前代码未实现内存使用率和磁盘使用率的显示功能。

---

## 模块说明

### `sysinfo.py`

- **功能**：程序主入口。负责初始化 OLED 驱动、读取系统信息、调用 OLED 驱动库进行显示，以及主循环控制。
- **主要逻辑**：
  1. 初始化 GPIO 和 OLED。
  2. 读取 `name.txt` 获取设备名称（含容错处理）。
  3. 进入无限循环，周期性（约 2 秒）获取 CPU 使用率、网络信息、当前时间。
  4. 清屏并依次显示上述信息。
  5. 延迟 2 秒后重复循环。

### `oled_driver_i2c.py`

- **功能**：SSD1315 OLED 屏幕的底层驱动库，封装了所有与屏幕通信和绘图相关的操作。
- **关键特性**：
  - **软件 I2C**：使用 `libgpiod` 库通过 GPIO 引脚模拟 I2C 通信。
    - SDA: `gpiochip0/line2`
    - SCK: `gpiochip0/line3`
  - **显存 (GRAM) 操作**：使用 `numpy` 管理显存，提供点绘制、清屏、填充等基础绘图函数。
  - **文本显示**：支持显示单个字符 (`show_char`) 和字符串 (`show_string`)，使用内置 8x16 ASCII 字体。
  - **刷新机制**：实现高效的全屏刷新逻辑 (`refresh_gram`)，适用于 SSD1315 的 Horizontal Addressing Mode。
  - **初始化**：包含完整的 SSD1315 初始化序列。

### `font_data.py`

- **功能**：提供 `oled_driver_i2c.py` 所需的 8x16 ASCII 字体点阵数据 (`asc2_1608`)。

### `name.txt`

- **功能**：存储用户自定义设备显示名称。程序启动时读取此文件内容；若文件不存在或为空，则使用默认名称 `"NoName"`。

---

## 硬件连接（玩客云）

| OLED 引脚 | 玩客云引脚                 | Linux GPIO         |
|-----------|----------------------------|--------------------|
| SDA       | GPIO-431 (J2 Pin 32)       | `gpiochip0/line2`  |
| SCK       | GPIO-432 (J2 Pin 31)       | `gpiochip0/line3`  |
| VCC       | 3.3V 电源                  |                    |
| GND       | GND                        |                    |

---

## 软件依赖与使用要求

### 操作系统
- [one-kvm（基于 armbian（Debian/Ubuntu））](https://one-kvm.mofeng.run/)

### Python 版本
- Python 3（推荐 Python 3.7+）

### Python 库依赖

| 库名        | 安装命令 |
|------------|---------|
| libgpiod   | `sudo apt update && sudo apt install python3-libgpiod` |
| numpy      | `pip3 install numpy` 或 `sudo apt install python3-numpy` |
| psutil     | `pip3 install psutil` 或 `sudo apt install python3-psutil` |

### 权限设置

运行脚本的用户需具备访问 `/dev/gpiochip*` 的权限。建议将用户加入 `gpio` 组：
```bash
sudo usermod -a -G gpio $USER
```
注销并重新登录使组权限生效。

# 如何使用

## 文件准备
- 将以下文件放在**同一目录**下：
  - `sysinfo.py`（主程序）
  - `oled_driver_i2c.py`（OLED 驱动库）
  - `font_data.py`（字体数据）
- 创建 `name.txt` 文件，并写入您希望显示的设备名称（例如：`Wankeyun`）。
  - 若文件不存在或为空，程序将使用默认名称 `"NoName"`。

## 网络接口配置
脚本默认获取 `eth0` 接口的 IP 和 MAC 地址。  
如果您的玩客云使用其他网络接口（如 `wlan0`），请编辑 `sysinfo.py` 文件，修改其中的 `INTERFACE` 变量为对应接口名。

## 运行程序
1. 打开终端，进入脚本所在目录：
   ```bash
   cd /path/to/your/script/
   ```
2. 执行主程序：
   ```bash
   python3 sysinfo.py
   ```
系统信息将每约 2 秒刷新一次，显示在 OLED 屏幕上。
按下 Ctrl+C 可安全终止程序。

## 注意事项
- GPIO 冲突：确保 SDA（GPIO 2）和 SCK（GPIO 3）未被其他程序或硬件占用。
- I2C 速度问题：若屏幕刷新出现闪烁或延迟，可尝试在 oled_driver_i2c.py 的 _i2c_delay() 函数中增加微小延时（如 time.sleep(0.0001)）。
- OLED I2C 地址：默认地址为 0x3C。若您的屏幕地址为 0x3D，请修改 oled_driver_i2c.py 中的 OLED_I2C_ADDR 常量。
- 未显示信息：当前版本未启用内存和磁盘使用率的显示功能，尽管相关获取函数已定义。
-------------
- 在玩客云中，可能会出现：pip 确认没有通过它安装 libgpiod。但是 Python 仍然从 /usr/local/lib/... 导入它。这表明文件确实存在于那里，只是 pip 的数据库里没有记录。最直接的解决方案就是手动修改 /usr/local/lib/python3.11/dist-packages 下的 gpiod 文件夹（gpiod、gpiod-x.x.x.dist-info）名称，例如在后面加上.bak。
-网页500 Internal Server Error nginx/1.22.1说明
由于对python底下的gpio文件名进行了修改，使sysinfo代码运行时会读取系统文件夹下的gpiod文件数据，系统的 gpiod 模块版本过新，API 已经变化，但 kvmd 代码还在使用旧的 API。
旧版 gpiod：有 EdgeEvent、新版 gpiod：改成了 LineEvent
而 kvmd 的代码 /usr/local/lib/python3.11/dist-packages/kvmd/aiogp.py 仍在尝试访问 gpiod.EdgeEvent，导致启动失败。
- 解决方法：
```bash
# 编辑 aiogp.py，在顶部添加补丁
sudo sed -i '1i try:\n    import gpiod\n    if not hasattr(gpiod, \x27EdgeEvent\x27):\n        gpiod.EdgeEvent = gpiod.LineEvent\nexcept ImportError:\n    pass\n' /usr/local/lib/python3.11/dist-packages/kvmd/aiogp.py
# 自动修改 aiogp.py 文件，在文件最开头加上几行代码，让新版 gpiod 兼容旧程序（kvmd）。
```
---------------
# 设置开机自启动（Systemd）
# 步骤 1：赋予脚本可执行权限
```bash
sudo chmod +x /path/to/sysinfo.py
```
将 /path/to/ 替换为实际路径，例如：
```bash
sudo chmod +x /root/0.96oled/sysinfo.py
```
- 检查 Python 环境：
确保已安装 Python 3。
确认 sysinfo.py 文件首行 Shebang 正确：
```Python
#!/usr/bin/env python3
```
## 步骤 2：创建 Systemd 服务文件
```bash
sudo nano /etc/systemd/system/sysinfo.service
```
粘贴以下内容（请根据实际情况修改路径和用户名）：

```Ini
[Unit]
Description=Sysinfo Python Script
After=network.target

[Service]
ExecStart=/usr/bin/python3 /path/to/sysinfo.py
WorkingDirectory=/path/to/
Restart=always
User=root
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=multi-user.target
```
- 注意：将 /path/to/ 替换为脚本实际路径。

## 步骤 3：启用并启动服务
```bash
# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 设置开机自启
sudo systemctl enable sysinfo.service

# 立即启动服务
sudo systemctl start sysinfo.service
```
##　步骤 4：验证服务状态
```bash
sudo systemctl status sysinfo.service
```
若显示 active (running)，表示服务已成功运行。
若失败，请根据输出的错误信息排查问题（如路径错误、权限不足、依赖缺失等）。