# usb_lcd

**Repository Path**: mail_osc/usb_lcd

## Basic Information

- **Project Name**: usb_lcd
- **Description**: usb的lcd模块显示内网ip
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# USB 小屏状态显示

这套程序会把当前机器的内网 IP、CPU、内存和磁盘使用率显示到 `MSU2_MINI_MG` USB 小屏上。

## 当前效果

- 上方显示内网 IP
- 下方显示：
  - CPU 使用率
  - 内存使用率
  - 磁盘使用率
- 四周保留 1 像素空白
- 默认每 20 秒刷新一次
- USB 小屏后插也能自动识别
- 握手成功后保持串口长连接，断线后自动重新连接
- 两次画面刷新之间使用厂商 ADC 只读命令维持设备会话

## 文件说明

- [display_ip.py](display_ip.py)：主程序
- [build_binary.sh](build_binary.sh)：生成单文件二进制
- [install.sh](install.sh)：安装并立即启动 systemd 服务
- [restart.sh](restart.sh)：停止当前服务并重新启动
- [make_release.sh](make_release.sh)：生成可迁移的 ZIP 安装包
- [dist/usb-lcd-dashboard](dist/usb-lcd-dashboard)：构建后的可执行文件

## 运行方式

### 直接运行源码

```bash
sudo python3 display_ip.py
```

### 持续刷新

```bash
sudo python3 display_ip.py --watch 20
```

### 详细日志

```bash
sudo python3 display_ip.py -v --watch 20
```

### 只测试屏幕

```bash
sudo python3 display_ip.py --test
```

## 自动识别

程序不会依赖固定 USB 口。

它会自动扫描：

- `VID:PID = 1A86:FE0C`
- 备用 `/dev/ttyACM*`

所以 USB 插在不同接口上，设备号变化后也能找到。

## 热插拔行为

在 `--watch` 模式下：

- 没插 USB 小屏时，不报错
- 程序继续等待
- 你后面再插入，小屏会在下一轮自动显示
- 设备拔出或通信中断后关闭旧连接，下一轮重新扫描和握手

这适合开机后过一段时间才插小屏的场景。

## 打包成二进制

### 生成

```bash
./build_binary.sh
```

输出文件：

```bash
dist/usb-lcd-dashboard
```

### 打包说明

这个二进制已经把 Python 代码和 Python 侧依赖打进去了，使用时不需要再安装：

- Pillow
- psutil
- numpy

但它仍然依赖系统基础动态库，所以不是完全静态二进制。

### 兼容性说明

当前这份二进制适合在相近的 Linux 环境上运行。

如果你要覆盖到更老的系统，比如 CentOS 7，建议在目标系统或同级别老环境里重新构建，而不是直接拿当前构建物跨大版本使用。

## 安装自启动

### 直接从源码目录安装

```bash
./install.sh
```

它会：

- 把程序安装到 `/usr/local/bin/usb-lcd-dashboard`
- 安装只匹配 `1A86:FE0C` 的 udev 规则，阻止 ModemManager 把 LCD 当成调制解调器探测
- 创建并启用 `usb-lcd-dashboard.service`
- 每 20 秒刷新一次数据
- 安装完成后立即启动，之后每次开机自动启动

### 服务行为

默认启动命令是：

```bash
/usr/local/bin/usb-lcd-dashboard --watch 20
```

也就是每 20 秒刷新一次。

画面刷新间隔内，程序每秒读取一次设备 ADC 通道 9 作为轻量心跳。这与厂商程序的连接维护方式一致，可避免固件因串口长期无命令而停止响应；心跳无确认时会关闭旧连接并重新握手。

### 生成可迁移 ZIP

发布脚本不会重新编译，而是校验并打包现有的 `dist/usb-lcd-dashboard`。这样可以避免在较新的 Linux 上重建后，意外提高 glibc 要求，导致 Ubuntu 20.04 无法运行。

在当前机器执行：

```bash
./make_release.sh
```

输出文件：

```text
release/usb-lcd-dashboard-linux-x86_64.zip
```

ZIP 内只有三个运行所需文件：

- `usb-lcd-dashboard`
- `install.sh`
- `restart.sh`

打包时会自动检查：

- 二进制是 x86-64 ELF 文件
- 二进制 glibc 要求不高于 Ubuntu 20.04 的 2.31
- ZIP 文件结构完整

如果源码有改动，必须先在 Ubuntu 20.04 或更老的兼容构建环境中重新生成 `dist/usb-lcd-dashboard`，再运行 `make_release.sh`。

### 转移到新的 Ubuntu

可以用 U 盘、局域网共享或 `scp`。例如从构建机器发送到新机器：

```bash
scp release/usb-lcd-dashboard-linux-x86_64.zip user@新机器IP:~/
```

然后在新机器执行：

```bash
sudo apt install -y unzip
unzip usb-lcd-dashboard-linux-x86_64.zip -d usb-lcd-dashboard
cd usb-lcd-dashboard
./install.sh
```

`install.sh` 会自动请求 sudo 权限，无需单独安装 Python 或 Python 包。

### 重新启动

解压目录中执行：

```bash
./restart.sh
```

脚本会让 systemd 停止当前进程并重新启动服务。

### 查看状态

```bash
systemctl status usb-lcd-dashboard
```

### 查看日志

```bash
journalctl -u usb-lcd-dashboard -f
```

## 卸载

```bash
sudo systemctl disable --now usb-lcd-dashboard.service
sudo rm -f /etc/systemd/system/usb-lcd-dashboard.service
sudo rm -f /etc/udev/rules.d/99-usb-lcd-dashboard.rules
sudo udevadm control --reload-rules
sudo systemctl daemon-reload
sudo rm -f /usr/local/bin/usb-lcd-dashboard
```

## 常见问题

### 1. 没有显示

先看服务状态：

```bash
systemctl status usb-lcd-dashboard
```

再看日志：

```bash
journalctl -u usb-lcd-dashboard -n 50 --no-pager
```

日志出现 `LCD 已连接` 说明串口握手和方向命令已经确认；出现 `已发送到` 说明地址命令确认后，完整图像帧已经写入串口。仅有 systemd 的 `active (running)` 不能说明 LCD 通信成功。

### 2. 手动运行报权限错误

说明当前用户没有串口权限，直接用 root 运行即可：

```bash
sudo ./dist/usb-lcd-dashboard
```

或者把用户加入 `dialout` 组后重新登录。

### 3. USB 设备没插时提示报错

现在的实现里，`--watch` 模式不会把“没插设备”当异常。

如果你看到错误，一般是：

- 指定了错误的 `--port`
- 串口被别的程序占用
- 设备异常重枚举

### 4. CentOS 7 不能直接跑

根因是系统动态库版本差异，不是 Python 代码本身。

建议在 CentOS 7 上重新构建，或者走更老环境构建后再分发。

## 构建环境备注

当前仓库里已经有：

- 本地构建产物
- systemd 安装脚本
- PyInstaller 打包脚本
- 可迁移 ZIP 打包脚本

如果源码有改动并且需要重新生成兼容二进制，按下面顺序：

1. 在 Ubuntu 20.04 或 glibc 不高于 2.31 的 x86-64 环境中构建
2. 确认 `python3`、PyInstaller 和项目依赖可用
3. 执行 `./build_binary.sh`
4. 执行 `./make_release.sh`，通过兼容性校验后生成发布 ZIP