# linux_oled_oneline

**Repository Path**: one_dev/linux_oled_oneline

## Basic Information

- **Project Name**: linux_oled_oneline
- **Description**: 玩客云oled,只有一行显示ip地址
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-03-02
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# linux_oled_oneline

一个运行在 Linux 上的单行 OLED 显示项目，使用 GPIO 模拟 I2C 时序驱动 `128x32` OLED 小屏，当前主要用途是在设备启动后把本机 IP 地址显示到屏幕上，并可同步发送邮件通知。

项目最初在玩客云环境中使用，代码里默认也是按 Linux `sysfs GPIO` 接口来操作引脚。

![项目效果图 1](/Users/devv/Documents/project_my/python/linux_oled_oneline/image2.png)

![项目效果图 2](/Users/devv/Documents/project_my/python/linux_oled_oneline/image.png)

## 项目功能

- 通过 `gpio` 模块直接读写 `/sys/class/gpio`
- 使用软件方式模拟 I2C 起始、停止、写字节和应答流程
- 初始化 `128x32` OLED 屏幕
- 将 ASCII 字符绘制到显存缓冲区并刷新到屏幕
- 启动后通过多种方式获取本机 IP，获取成功后显示在 OLED 上
- 在配置好 SMTP 参数后，自动发送当前设备 IP 邮件通知

## 项目结构

- `main.py`：程序入口，负责获取 IP 并调用 OLED 显示
- `ip_email.py`：同步自 `ip_get` 的网络信息与邮件发送逻辑
- `oled.py`：OLED 驱动核心，包含 GPIO/I2C 时序、显存、清屏和字符串显示
- `font.py`：ASCII 点阵字库
- `gpio/__init__.py`：基于 Linux `sysfs GPIO` 的简单 GPIO 封装
- `tests/`：`gpio` 模块的单元测试
- `start.sh` / `stop.sh` / `restart.sh`：启动、停止、重启脚本

## 运行原理

程序启动后会按下面的顺序执行：

1. 在 OLED 上显示 `get ip...`
2. 通过 UDP socket、`getaddrinfo()`、系统命令 (`ip addr` / `ifconfig`) 多路获取 IPv4
3. 如果没有拿到有效 IP，就按固定间隔重试，最多 5 次
4. 获取成功后将第一个有效 IPv4 显示到 OLED
5. 读取邮件配置
6. 如果邮件配置完整，则发送一封包含 IP、MAC、主机名和接口详情的 HTML 邮件

OLED 驱动没有依赖硬件 I2C 控制器，而是直接通过两个 GPIO 引脚手动输出时序。

## 默认引脚

在 [oled.py](/Users/devv/Documents/project_my/python/linux_oled_oneline/oled.py) 中当前默认配置为：

- `OLED_SDA = 431`
- `OLED_SCK = 432`

如果你的开发板引脚映射不同，需要先修改这两个值再运行。

## 环境要求

- Linux
- Python 3
- 具备 `/sys/class/gpio` 访问权限

从当前代码看，主程序本身没有显式依赖 `numpy`。  
测试依赖里使用了 `pytest` 和 `mock`。

邮件功能同样只依赖 Python 标准库。

## 快速运行

直接运行：

```bash
python3 main.py
```

如果配置了邮件参数，程序会在 OLED 显示 IP 后继续发送通知邮件。

## 邮件配置

邮件发送通过环境变量控制，未配置时会自动跳过，不会影响 OLED 显示。

可用环境变量如下：

- `OLED_SMTP_SERVER`：SMTP 服务器地址
- `OLED_SMTP_PORT`：SMTP 端口，默认 `465`
- `OLED_SMTP_USE_SSL`：是否使用 SSL，默认 `true`
- `OLED_SMTP_USE_TLS`：是否使用 STARTTLS，默认 `false`
- `OLED_EMAIL_USER`：发件人邮箱
- `OLED_EMAIL_PASSWORD`：发件人密码或授权码
- `OLED_EMAIL_RECIPIENTS`：收件人邮箱，多个用英文逗号分隔
- `OLED_EMAIL_SUBJECT`：邮件主题，默认 `设备 IP 通知`

示例：

```bash
export OLED_SMTP_SERVER="smtp.qiye.aliyun.com"
export OLED_SMTP_PORT="465"
export OLED_SMTP_USE_SSL="true"
export OLED_SMTP_USE_TLS="false"
export OLED_EMAIL_USER="your_name@example.com"
export OLED_EMAIL_PASSWORD="your_password_or_token"
export OLED_EMAIL_RECIPIENTS="admin1@example.com,admin2@example.com"
export OLED_EMAIL_SUBJECT="玩客云 IP 通知"
python3 main.py
```

如果是首次接线调试，建议先确认：

- OLED 分辨率与当前代码一致，为 `128x32`
- 屏幕控制器兼容当前初始化指令
- `SDA`、`SCK` 已正确连接到代码中设置的 GPIO
- 当前用户有权限访问 `/sys/class/gpio`

## 脚本说明

### `start.sh`

脚本会：

- 修改 `/sys/class/gpio/export` 权限
- 进入 `/root/linux_oled_oneline`
- 后台启动 `python3 ./main.py`
- 将进程号写入 `pid.txt`

### `stop.sh`

脚本当前通过：

```bash
ps -ef | grep oled_python | awk '{print $2}' | xargs kill -9
```

来结束进程。

这意味着它依赖进程名中包含 `oled_python`。如果实际运行的是 `python3 ./main.py`，这个停止逻辑可能匹配不到目标进程。

### `restart.sh`

按顺序执行：

```bash
./stop.sh
./start.sh
```

## 安装测试依赖

如果要运行测试，先安装依赖：

```bash
python3 -m pip install pytest mock
```

然后执行：

```bash
python3 -m pytest -q
```

## 测试说明

当前测试主要覆盖的是 [gpio/__init__.py](/Users/devv/Documents/project_my/python/linux_oled_oneline/gpio/__init__.py)：

- GPIO 导出与反导出
- 引脚方向设置
- 高低电平写入
- `active_low` 行为
- 清理逻辑

这些测试通过 mock 文件操作来验证 `sysfs GPIO` 访问，不依赖真实硬件。

`ip_email.py` 当前还没有单元测试。

## 已知限制

- 当前显示逻辑主要面向 ASCII 字符，不适合直接显示中文
- OLED 分辨率和初始化参数写死在代码里，暂未做配置化
- GPIO 访问方式基于较老的 `sysfs` 接口，新内核环境可能需要额外适配
- `start.sh`、`stop.sh`、`restart.sh` 中的路径写死为 `/root/linux_oled_oneline`
- 主程序结束时没有显式执行 GPIO 清理
- 邮件功能依赖外部 SMTP 服务和环境变量配置

## 当前仓库状态说明

从仓库内容看，这个项目包含两部分能力：

- 一个可直接运行的 OLED IP 显示示例
- 一个可独立复用的 Linux `sysfs GPIO` Python 封装

如果后续继续维护，比较值得优先整理的方向是：

- 把硬件参数做成配置项
- 修正进程管理脚本
- 增加 OLED 驱动层的测试
- 补充接线说明和屏幕型号信息