ZeroPhone/ZPUI 项目安装与更新指南

硬件设备安装（树莓派等单板计算机）

对于希望在真实硬件上运行ZPUI的用户，以下是完整的安装流程和注意事项。

系统要求

• 基于Linux的单板计算机（如树莓派）
• 已安装基础操作系统
• 网络连接（用于下载依赖项）

安装步骤

1. 获取源代码

git clone 项目仓库地址
cd ZPUI/

2. 执行安装脚本

sudo ./setup.sh

此脚本将：

• 安装所有必要的依赖包
• 创建系统级ZPUI副本（默认位于/opt/zpui）
• 配置systemd服务

3. 硬件配置

sudo ./config.py

运行此交互式配置工具设置输入输出设备。

4. 测试运行

sudo python main.py

验证屏幕和按钮是否正常工作。

5. 部署到系统

sudo ./sync.sh

将工作配置同步到系统级副本。

系统架构说明

ZPUI采用双副本设计：

• 本地副本：开发/修改使用的目录
• 系统副本：实际运行的稳定版本（/opt/zpui）

推荐工作流程：

1. 在本地副本进行修改
2. 停止服务：sudo systemctl stop zpui.service
3. 本地测试：sudo python main.py
4. 确认无误后同步：sudo ./sync.sh

这种设计避免了直接修改运行系统可能导致的问题。

更新管理

可通过以下方式更新：

1. 在ZPUI界面中选择"设置"→"更新ZPUI"
2. 命令行执行update.sh（同步+更新）
3. 仅同步使用sync.sh

服务控制命令

sudo systemctl start|stop|status zpui.service

开发测试模式

开发时可直接运行：

sudo python main.py

需先停止系统服务以确保独占访问硬件。

模拟器安装（PC开发环境）

对于希望在PC上开发ZPUI应用的用户，可以使用模拟器环境。

系统要求

• Linux操作系统（Ubuntu/Debian/Arch/OpenSUSE等）
• 图形环境
• Python 3环境

配置说明

模拟器默认使用128x64单色模式，可通过修改config.yaml调整：

device: emulator
resolution: 400x240  # 自定义分辨率
mode: RGB            # 色彩模式

各系统安装指南

Ubuntu/Debian

sudo apt-get update
sudo apt-get install python3-pip git python3-dev build-essential python3-pygame
git clone 项目仓库地址
cd ZPUI
sudo ./config.py  # 选择"emulator"选项
python3 -m pip install -r requirements.txt
python main.py

Arch Linux

sudo pacman -S python-pip git python-pygame
# 后续步骤同上

OpenSUSE

sudo zypper install python-pip git python-devel gcc python-curses python-pygame
# 后续步骤同上

模拟器特点

• 完全模拟硬件环境
• 支持键盘输入
• 实时显示日志输出
• 便于UI开发和调试

注意事项

1. 硬件环境下修改代码时，建议始终保持一个可工作的系统副本
2. 模拟器环境下不需要运行setup.sh/sync.sh等脚本
3. 遇到pip安装问题时，可尝试添加--break-system-packages参数
4. 开发过程中建议定期提交代码变更

通过本指南，用户可以根据自身需求选择在真实硬件或模拟器环境中安装和运行ZPUI系统，为后续的应用开发和系统定制打下基础。