1. 项目概述：为你的Divoom Pixoo设备打造一个REST API网关
如果你手头有一台Divoom Pixoo或Pixoo 64这类Wi-Fi像素画框，并且厌倦了在手机App里点点戳戳，或者想把它集成到你的智能家居、自动化工作流里，那你来对地方了。pixoo-rest这个项目，本质上是一个用Python Flask写的Web服务，它在你本地网络里架起了一座桥，把你熟悉的HTTP请求，翻译成Pixoo设备能听懂的语言。这样一来，你就可以用任何能发送HTTP请求的工具——比如curl命令、Python脚本、Node.js程序，甚至是Home Assistant这样的家庭自动化平台——来远程控制你的像素画框，在上面画画、显示图片、播放GIF动画、调节亮度，想怎么玩就怎么玩。
这个项目最初诞生于2022年，核心是给一个优秀的第三方Python库pixoo套上了一层RESTful的外衣。虽然原库的作者在2024年8月也为其增加了REST接口，但pixoo-rest凭借其开箱即用的Swagger UI交互文档、详尽的“直通”端点示例、预构建的Docker镜像以及Helm Chart等特性，依然保持着独特的价值和活跃的维护。它尤其适合那些希望快速上手、清晰调试，或者需要在容器化环境（如Docker, Kubernetes）中部署的开发者或极客。
简单来说，pixoo-rest解决的核心问题是标准化和简化对Pixoo设备的编程式访问。它把设备原生那个有些晦涩、文档不全的HTTP API，封装成了结构清晰、有文档可查、易于测试的REST API。无论你是想写个脚本在每天早晨显示天气和日程，还是在有人按门铃时让Pixoo显示一个动画，这个项目都能让你事半功倍。
2. 核心设计思路与方案选型
为什么需要pixoo-rest？直接调用Pixoo自带的HTTP API不行吗？这里就涉及到工程上的权衡和设计思路了。
2.1 直面原生API的挑战
Pixoo设备本身确实开放了一个HTTP服务端口（通常是80），允许接收JSON格式的指令。但是，这个原生接口存在几个明显的痛点：
- 文档缺失与不准确：官方几乎没有提供完整的、可靠的API文档。社区和开发者们大多依靠逆向工程、抓包分析和试错来摸索指令格式，这过程既耗时又容易出错。
- 数据格式复杂：一些高级功能，比如绘制多像素点、显示动画，需要构造非常复杂的嵌套JSON结构。手动拼接这些JSON极易出错，调试困难。
- 缺乏抽象与便利功能：原生API是“原子级”的，你需要自己处理图片缩放、颜色格式转换（如RGB到设备接受的索引色）、帧率控制等底层细节。
直接面对这些底层细节，开发效率很低，代码也容易变得冗长且脆弱。
2.2pixoo-rest的封装哲学
pixoo-rest的设计哲学是“分层封装”和“体验优先”。它并没有重新发明轮子，而是巧妙地站在了巨人的肩膀上：
- 底层依赖：
SomethingWithComputers/pixoo库：这是整个项目的基石。这个优秀的第三方Python库已经解决了与Pixoo设备通信、图像格式自动转换、绘图命令封装等最棘手的底层问题。pixoo-rest直接调用这个库的方法，确保了功能的可靠性和正确性。 - 中间层：Flask Web框架：
pixoo-rest使用轻量级的Flask框架，将上述Python库的方法“映射”成一个个HTTP端点。例如，库里的draw_text方法，就对应着POST /api/text这个API。这样做的好处是，任何支持HTTP的客户端都能调用，极大地扩展了使用场景。 - 表现层：Swagger UI：这是
pixoo-rest的一大亮点。它自动为所有API生成了交互式文档界面。你不仅能看到每个接口的说明，还能直接在网页上填写参数、点击“Execute”按钮进行测试，并能立刻看到生成的curl命令。这对于API调试、学习和脚本编写来说，体验提升是巨大的。 - “直通”模式的设计考量：尽管封装层很好用，但开发者有时可能需要直接使用某些尚未被库封装的原生设备指令。
pixoo-rest考虑到了这一点，提供了“pass-through”端点。你可以将摸索出来的原始JSON指令直接通过这个端点发送给设备，同时还能享受Swagger UI提供的参数示例和格式化展示。这体现了设计上的灵活性，既提供了便利的抽象，也没有堵死直接操作底层的大门。
这种设计选择的结果是，你获得了一个高生产力、易调试、易集成的控制中心。你不需要关心设备IP如何被发现、图片如何被转换成16x16或64x64的像素数据，你只需要关注业务逻辑：“我要显示什么内容”。
注意：选择
pixoo-rest也意味着你接受了一个间接层。理论上，直接调用原库或原生API可能有极致的性能。但在绝大多数家庭自动化或趣味项目场景下，这毫秒级的差异完全可以忽略不计，而它带来的开发效率提升和可维护性优势则是决定性的。
3. 环境准备与详细配置解析
好了，理论说完，我们开始动手。首先是把服务跑起来。pixoo-rest提供了两种运行方式：直接在Python环境中运行，或者使用更便捷的Docker容器。我会详细讲解两种方式，并深入每个配置项的含义。
3.1 方案一：基于Python虚拟环境直接运行
这种方式适合喜欢深度控制、需要在宿主机上直接调试Python代码的用户。
第一步：获取项目代码打开终端，执行克隆命令。这会将项目及其所有文件下载到本地。
git clone https://github.com/4ch1m/pixoo-rest.git cd pixoo-rest第二步：创建并激活虚拟环境虚拟环境是Python项目的“隔离工作间”，能避免不同项目间的依赖冲突。这是Python开发的最佳实践，强烈建议执行。
# 创建名为 venv 的虚拟环境 python3 -m venv venv # 激活虚拟环境 # 在 Linux/macOS 上： source venv/bin/activate # 在 Windows 上： # venv\Scripts\activate激活后，你的命令行提示符前通常会显示(venv)，表示你已进入该环境。
第三步：安装项目依赖项目根目录下的requirements.txt文件列出了所有必需的Python包。使用pip一键安装。
pip install -r requirements.txt这个过程会安装Flask、Werkzeug、requests以及核心的pixoo库等。
第四步：关键配置 - 理解.env文件在运行应用前，必须告诉它你的Pixoo设备在哪里。这是通过一个名为.env的环境变量文件完成的。在项目根目录（与app.py同级）创建这个文件。
touch .env # Linux/macOS # 或在编辑器中新建用文本编辑器打开.env，填入你的配置。下面我逐条解释每个配置项的作用和如何填写：
# 【必填】你的Pixoo设备在网络中的地址。可以是IP地址（推荐），也可以是主机名（如果你的路由器支持）。 # 如何查找？通常可以在路由器的设备管理界面找到，或者使用Pixoo App查看设备信息。 PIXOO_HOST=192.168.1.100 # 【可选】启用Pixoo底层库的调试模式。如果设为true，会在控制台打印与设备通信的详细日志，用于排查连接或指令问题。 PIXOO_DEBUG=false # 【可选】指定Pixoo设备的屏幕尺寸。必须是64（Pixoo 64）或16（Pixoo 16）。如果省略，默认为64。 PIXOO_SCREEN_SIZE=64 # 【可选】启用Flask框架的调试模式。开发时建议设为true，这样代码修改后会自动重载，并且错误信息更详细。生产环境务必设为false。 PIXOO_REST_DEBUG=true # 【可选】REST服务监听的网络接口。127.0.0.1表示只允许本机访问。0.0.0.0表示允许所有网络接口访问（如同局域网内其他设备访问）。 PIXOO_REST_HOST=0.0.0.0 # 【可选】REST服务使用的端口号。默认5000，如果冲突可以修改。 PIXOO_REST_PORT=5000 # 【可选】应用启动时尝试连接Pixoo设备的次数。如果设备启动较慢或网络不稳定，可以适当增加。默认会无限重试直到成功。 PIXOO_TEST_CONNECTION_RETRIES=10 # 【高级可选】设置URL路径前缀。只有当你在Nginx等反向代理后面运行此服务，并且希望通过一个子路径（如 http://你的服务器/pixoo-rest/）访问时才需要设置。 # 注意：值必须以斜杠开头。 # SCRIPT_NAME=/pixoo-rest第五步：运行服务配置完成后，运行就很简单了。
python app.py如果看到类似* Running on http://0.0.0.0:5000的输出，说明服务启动成功。现在打开浏览器，访问http://你的电脑IP:5000就能看到Swagger UI界面了。
3.2 方案二：使用Docker容器化运行（推荐）
对于大多数用户，尤其是想快速部署、避免环境配置麻烦的，Docker方案是首选。它通过容器技术将应用及其所有依赖打包，确保在任何系统上运行结果一致。
第一步：确保系统已安装Docker和Docker Compose在终端输入docker --version和docker compose version检查是否已安装。如果没有，请参考Docker官方文档进行安装。
第二步：配置.env文件与方案一完全相同，在项目根目录创建并配置.env文件。这是容器读取配置的标准方式。
第三步：使用Docker Compose一键启动Docker Compose通过一个docker-compose.yml文件定义和运行多容器应用。本项目很简单，只有一个服务。
# 在项目根目录执行，-d 参数表示在后台运行 docker compose up -d第一次运行时会自动从Docker Hub拉取基础镜像并构建pixoo-rest的镜像，稍等片刻即可。之后再次启动就是秒级。
第四步：使用预构建镜像（更快捷）项目作者已将构建好的镜像推送到了Docker Hub。如果你想跳过构建步骤，直接使用稳定版本，可以修改项目根目录下的docker-compose.yml文件： 找到services:下的app:部分，将配置从“构建”改为“使用镜像”：
services: app: # 注释掉 build 行，启用 image 行 image: 4ch1m/pixoo-rest:latest # build: . # ... 其他配置保持不变然后再次运行docker compose up -d，它会直接拉取远程镜像运行，速度更快。
第五步：管理容器
- 查看日志：
docker compose logs -f app - 停止服务：
docker compose down - 重启服务：
docker compose restart app
实操心得：我个人强烈推荐Docker方案。它不仅干净利落，避免了污染宿主机环境，而且在未来升级时，只需要拉取新镜像并重启容器即可，管理起来非常方便。特别是当你需要在树莓派、NAS等设备上长期运行这个服务时，Docker的稳定性优势更明显。
4. 核心API功能详解与实战操作
服务跑起来后，浏览器打开Swagger UI (http://localhost:5000)，你会看到一个清晰分类的API列表。我们挑几个最常用、最核心的功能来深入讲解如何调用，并理解其背后的原理。
4.1 设备基础控制
这类API用于管理设备本身的状态。
GET /api/device：获取设备信息。这是一个很好的连通性测试接口。调用它会返回设备的名称、屏幕尺寸、亮度、当前频道等状态。在Swagger UI里点击“Try it out”，然后“Execute”，你会在“Responses”部分看到返回的JSON数据，同时“Curl”部分会生成对应的命令行。你可以直接复制这个curl命令到终端执行，效果一样。POST /api/device/clear：清空屏幕。发送一个空POST请求即可。这在你想绘制新内容前，确保画布干净时很有用。POST /api/device/brightness：设置亮度。你需要提供一个JSON请求体，例如{"brightness": 50}。亮度范围通常是0-100。这个API的调用展示了如何通过Swagger UI发送带参数的请求：在“Parameters”部分的“brightness”模型示例中修改数值，然后执行。
4.2 绘制文本与图形
这是创造自定义显示内容的核心。
POST /api/text：绘制文本。这是最复杂的API之一，参数众多。我们拆解一下：text: 要显示的字符串。position: 一个包含x和y键的字典，表示文本左上角的起始坐标。坐标原点(0,0)在屏幕左上角。color: RGB颜色值，如[255, 0, 0]表示红色。font: 字体大小和样式。库通常内置几种字体，如f8。background_color: 文本背景色，设为[0,0,0]为透明背景。delay: 绘制完成后等待的毫秒数，用于控制动画节奏。
在Swagger UI中，这个接口的“Example Value”已经给出了一个完整的JSON结构。你只需要修改里面的
text、position等字段的值，然后执行，就能立即在Pixoo上看到效果。这比你自己去计算像素位置、构造复杂JSON要简单无数倍。POST /api/rectangle/POST /api/filled_rectangle：绘制矩形框或实心矩形。参数包括起点position、width、height、color等。你可以用它来绘制边框、进度条等元素。
注意事项：Pixoo 64的屏幕分辨率是64x64像素，坐标范围是0-63。在绘制时，务必确保你的文本或图形坐标不会超出这个范围，否则部分内容将不可见。Swagger UI的交互测试能让你快速调整参数找到最佳位置。
4.3 图像与动画显示
让Pixoo“活”起来的关键。
POST /api/image：显示一张静态图片。你需要通过image_url参数提供一个图片的URL地址，或者通过image_file上传本地文件。服务会自动将图片缩放并抖动处理成适合Pixoo屏幕的像素画。这是实现自定义图标、照片显示的核心。POST /api/animation：播放GIF动画。参数与图片类似，通过animation_url或animation_file指定一个GIF。服务会解析GIF的每一帧，并按顺序发送到设备播放。你可以制作简单的动画来显示天气变化、加载指示器等。
这里有一个非常重要的实战技巧：对于本地文件，你通常需要先通过一个HTTP服务将其暴露出来。一个快速的方法是使用Python的简单HTTP服务器。在图片所在的目录下运行：
python3 -m http.server 8000然后你的图片URL就可以是http://你的电脑IP:8000/你的图片.gif。当然，更稳定的做法是将图片放到pixoo-rest服务本身的静态文件目录，或者使用云存储链接。
4.4 “直通”模式高级用法
当你需要调用一些pixoo库尚未封装，但设备原生支持的功能时，“直通”端点就派上用场了。
POST /api/passthrough：这是通往设备原生API的隧道。你需要将完整的、设备期望的原始JSON指令放在请求体中。 例如，设备有一个切换“时钟”、“视觉化”、“自定义”等频道的指令。你可以在Swagger UI的这个端点下，找到作者预置的一些“Example Value”，比如设置频道的示例。你可以基于这些示例进行修改。 如何使用？首先，你需要在网上社区（如GitHub Issues、Reddit）或通过抓包，找到你想要的原生命令格式。然后，将其粘贴到Swagger UI的请求体编辑框中，执行即可。Swagger UI在这里的价值是提供了一个格式化和测试的界面，避免了你在命令行中用curl手动拼接复杂JSON的麻烦。
5. 集成到智能家居与自动化脚本
pixoo-rest的真正威力在于集成。下面我分享几个将它与常见平台集成的思路和代码片段。
5.1 使用cURL在Shell脚本中调用
这是最轻量级的方式。Swagger UI每次执行请求后生成的curl命令可以直接复制使用。
#!/bin/bash # 一个简单的脚本：每小时更新一次Pixoo上的时间显示 # 清屏 curl -X POST http://localhost:5000/api/device/clear # 获取当前时间并格式化 CURRENT_TIME=$(date +"%H:%M") # 绘制时间文本，位置居中（估算），颜色为青色 curl -X POST http://localhost:5000/api/text \ -H "Content-Type: application/json" \ -d '{ "text": "'"$CURRENT_TIME"'", "position": {"x": 15, "y": 25}, "color": [0, 255, 255], "font": "f8", "background_color": [0, 0, 0] }'你可以将这个脚本加入crontab，实现每小时自动更新。
5.2 使用Python脚本进行复杂控制
Python脚本可以完成更复杂的逻辑，比如获取网络API数据并显示。
import requests import json from datetime import datetime PIXOO_REST_URL = "http://localhost:5000/api" def clear_screen(): requests.post(f"{PIXOO_REST_URL}/device/clear") def draw_text(text, x, y, color=(255,255,255)): payload = { "text": text, "position": {"x": x, "y": y}, "color": list(color), "font": "f8", "background_color": [0,0,0] } resp = requests.post(f"{PIXOO_REST_URL}/text", json=payload) return resp.ok def display_weather(): # 1. 清屏 clear_screen() # 2. 模拟获取天气数据（此处需替换为真实API，如OpenWeatherMap） # weather_data = requests.get("你的天气API").json() # temp = weather_data['main']['temp'] # condition = weather_data['weather'][0]['main'] temp = 22 condition = "Sunny" # 3. 在Pixoo上绘制 draw_text(f"{temp}C", 10, 10, (255, 200, 0)) # 温度用橘黄色 draw_text(condition, 10, 30, (100, 200, 255)) # 天气状况用浅蓝色 # 4. 绘制一个简单的太阳图标（使用实心矩形和线条模拟） # 这里可以调用 /api/filled_rectangle 和 /api/line 等API # 为简化，此处省略具体绘图代码，原理同上 if __name__ == "__main__": display_weather()5.3 集成到Home Assistant
Home Assistant (HA) 可以通过其强大的“RESTful Command”或“Shell Command”集成来调用pixoo-rest。
方法一：使用RESTful Command集成在HA的configuration.yaml中添加：
rest_command: pixoo_clear: url: "http://你的pixoo-rest服务IP:5000/api/device/clear" method: post content_type: "application/json" pixoo_show_text: url: "http://你的pixoo-rest服务IP:5000/api/text" method: post content_type: "application/json" payload: '{"text":"{{ text }}", "position":{"x":{{ x }}, "y":{{ y }}}, "color":{{ color }}, "font":"f8"}'然后你就可以在自动化或脚本中这样调用：
automation: - alias: "显示有人在家门口" trigger: ... # 例如门铃传感器触发 action: - service: rest_command.pixoo_clear - service: rest_command.pixoo_show_text data: text: "Visitor!" x: 20 y: 25 color: [255, 0, 0] # 红色方法二：使用Shell Command集成如果HA和pixoo-rest在同一台机器上，也可以用更直接的shell命令。
shell_command: pixoo_clock_channel: 'curl -X POST http://localhost:5000/api/passthrough -H "Content-Type: application/json" -d ''{"Command":"Channel/SetIndex","Index":0}'''这个例子使用了直通模式，直接将设备切换到时钟频道（Index: 0）。
6. 常见问题排查与性能优化心得
在实际部署和使用中，你可能会遇到一些问题。这里我总结了一些常见坑点和解决思路。
6.1 连接与通信问题
| 问题现象 | 可能原因 | 排查步骤 |
|---|---|---|
| 服务启动失败，提示连接不上Pixoo | 1.PIXOO_HOST配置错误（IP或主机名不对）2. Pixoo设备未开机或不在同一网络 3. 防火墙/路由器阻止了端口通信 | 1. 检查.env文件中的PIXOO_HOST，确保是设备的正确局域网IP。2. 尝试用 ping PIXOO_HOST测试网络连通性。3. 确保Pixoo和运行 pixoo-rest的机器在同一个子网内。 |
| Swagger UI可以打开，但调用API无反应或超时 | 1. Pixoo设备繁忙或响应慢 2. 网络存在间歇性丢包 3. Docker容器网络模式问题 | 1. 重启Pixoo设备。 2. 在 .env中设置PIXOO_DEBUG=true，查看服务日志是否有详细错误。3. 如果使用Docker，确保容器网络是 host模式或与宿主机桥接正确。检查docker-compose.yml中的网络配置。 |
| 图片或动画上传后显示异常（颜色不对、卡顿） | 1. 图片尺寸或格式不兼容 2. GIF动画帧率过高或帧数太多 3. 网络传输慢导致帧丢失 | 1. 尽量使用尺寸接近64x64的正方形图片。pixoo库会自动处理，但源图质量影响效果。2. 对于GIF，建议用工具（如EZGIF.com）将其优化为64x64尺寸，减少帧数（10帧以内为佳），降低颜色数。 3. 对于复杂动画，考虑在服务端先将GIF解码成多张静态图片序列，然后使用 /api/image配合延迟循环发送，可控性更强。 |
6.2 性能与稳定性优化
- 减少频繁的清屏操作：
/api/device/clear会清空整个屏幕缓冲区。如果你只是更新部分内容（如一个数字），可以考虑直接在原有画布上覆盖绘制（比如先画一个背景色方块盖住旧数字），而不是每次都清屏重画。这能减少闪烁感和通信次数。 - 批量绘制：虽然
pixoo-rest没有提供原生的“批量命令”接口，但你可以在自己的客户端脚本中缓存多次绘制操作，最后一次性发送多个请求。或者，对于复杂的静态画面，可以预先在电脑上生成一张完整的64x64图片，然后通过/api/image一次性发送，效率最高。 - 使用Docker的健康检查：在
docker-compose.yml中，可以为服务添加健康检查，确保服务崩溃后能自动重启。services: app: # ... 其他配置 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:5000/api/device"] interval: 30s timeout: 10s retries: 3 start_period: 40s - 处理设备休眠：Pixoo设备在一段时间无操作后可能会进入休眠（屏幕变暗）。通过REST API发送任何指令通常可以唤醒它。为了保持常亮，你可以设置一个最简单的定时任务，比如每5分钟发送一个获取设备信息的
GET请求（/api/device），作为“心跳”来阻止休眠。
6.3 关于“直通”模式的警告
直通模式非常强大，但也非常“危险”。因为你发送的是原始指令，一旦格式错误，轻则指令被忽略，重则可能导致设备出现未定义行为（虽然通常不会变砖）。在使用前，务必：
- 充分测试：先在Swagger UI里用小参数测试。
- 查阅社区资料：GitHub上原
pixoo库的Issues、Divoom相关的论坛或Subreddit，是寻找原始指令格式的宝库。 - 备份配置：如果你通过直通模式修改了设备的重要设置，记得记录下修改前的值。
最后，别忘了这是一个社区维护的项目。如果你发现了bug，有了新的功能想法，或者为某些原生指令编写了好用的示例，非常鼓励你去项目的GitHub页面提交Issue或Pull Request。正是这种共享和协作，让pixoo-rest这样的工具变得如此有用。
