本帖最后由 SquareNX 于 2025-8-2 19:18 编辑
首次发帖，如有格式错误等等还请告知。感觉论坛里大佬如云，这篇教程也算是斗胆抛个砖了，有什么错误还请指出（特别一些计算机术语，不太确定叫的对不对），有帮助的话那是最好。
一切起源于一次刷视频刷到的一位智能家居向博主的awtrix像素灯介绍视频，感觉为智能家居加一个风格化的提示屏也挺有意思，于是翻出了之前收藏的另一位博主的像素灯硬件设计方案，“pen-pineapple-apple-pen”了一下，就有了我的这块像素灯。
硬件有了，讲具体如何使用的中文教程似乎有点少，在研究了下官方文档吭哧吭哧用起来后，便有了写这下这篇文章的想法。不过折腾这个玩意确实需要点基础知识，包括焊接、3d打印、docker、homeassistant等等。将这些知识全部纳进本篇文章实在有些繁杂，这里姑且默认大家都会，可以在别的地方补一下相关知识。 全文约 4700 字，感谢你还留有阅读这种长度文章的能力。 实话说，像素灯的风潮最盛应该是2020-2022年左右，现在写其实颇有点“吃*赶不上热乎”的感觉。 由于市售的8*8灯板都有些大，四块连在一起远超出我的3d打印机的打印尺寸，因此使用了b站聪明的二手脑袋设计的灯板，也就顺便用了该设计配套的栅格和外壳，加上一块esp32开发板、三个金属按钮、一个无源蜂鸣器、一块亚克力，一些杜邦线组装出了这台像素灯，成本大概40（闲鱼买的成品灯板）+20（esp32开发板）+5（按钮）+1（蜂鸣器）+12（亚克力）+5（外壳耗材费和打印电费）+4（杜邦线、螺丝等杂七杂八）=87元。
软件毕竟是为了同ha联动，便使用了awtrix固件。比起曾经火过的awtrix2.0，现在的3.0主要是提供了几项可以独立运行的功能，如时间（自动联网校时）、日历、温湿度（需加装组件）、音乐（需加装组件），且仍然可以通过mqtt或者api实现自定义玩法。
组装外壳组装很简单，亚克力+匀光板+栅格+灯板+外壳+后壳一步步安装即可。由于是用的现成固件，接线都已经在文档中给出，按下表接好即可。考虑到灯板灯珠数量多电流大，没有直接用开发板的针脚供电，而是从供电单独引了一路给它。按钮的话，其中一根脚串连到一起接开发板gnd，另一根对应文档接线即可。 | GPIO | 连接硬件 | ADC6 / GPIO34 | 电池电量 (可选) | ADC7 / GPIO35 | 亮度传感器 (GL5516) (可选) | GPIO32 | 灯板 | GPIO26 | 左侧按钮 (可选) | GPIO27 | 中间按钮 (可选) | GPIO14 | 右侧按钮 (可选) | GPIO15 | 蜂鸣器 (可选) | 21 (SDA) /22(SCL) | 温湿度传感器，支持BME280 BMP280 HTU21df SHT31 (可选) | 23(RX)/18(TX) | DFplayer (可选) |
如果需要详细教程，那么可以看BV1FC411s7Yf和BV1qRf6YeEXm这两个视频，其中外壳、灯板看第一个，电路、固件刷写看第二个。但需注意固件只需刷官方的即可，不需要再刷第二个博主自己编译的，所添加的 dev.json 文件也需要把3改成1。
自定义显示费劲组装一个像素灯肯定不单单是为了看时间的，接入HA或者其他数据源后显示自定义数据才是重点。但需要明确的是，除自带的几项功能外，AWTRIX固件没有获取数据的能力，只具备基础的显示功能，各种数据的获取需要其他设备的配合，数据的显示也需要其他设备向AWTRIX发送指令才可实现。 这部分重点关注的是数据的显示，这需要同AWTRIX设备建立通信并发送指令。如果将这一过程比作信件收发，那么我们需要明确信该由谁寄（通信协议）、信该怎么写（控制指令）以及信该寄去哪（交互链接）。
通信协议AWTRIX固件主要支持两种通信协议，分别是MQTT协议与HTTP协议。
MQTTMQTT协议一种适用于性能较弱或网络环境较差的设备之间进行相互通讯的“发布/订阅”式协议，多使用于低性能的物联网设备，AWTRIX接入ha便是用的mqtt协议。 在该协议下，ha与awtrix就像某社交平台的两个用户，awtrix可以建立许多个帖子（开关、亮度等等），之后在这些帖子分门别类的发布自己的当前状态，而ha便可订阅这些个帖子，进而得知awtrix的不同状态；而ha也可以在对应的帖子中发布指令，awtrix便会按照这些指令进行动作。从上自然可以看出，这些操作需要一个“社交平台”，这在mqtt协议中被称为broker（技术名），我一直用的是emqx（产品名）。
HTTPHTTP协议大家应该比较熟悉，日常浏览的网页便是浏览器与服务器之间通过http协议进行通信而来。同MQTT协议不同，HTTP协议是两台设备之间直接连接，客户端发起请求，服务端响应请求。为了让服务端知道自己应如何响应，HTTP协议规定了多种请求方式，如GET（从服务端获取资源）、POST（向服务端发送数据）、DELETE（从服务器删除数据）等等。 web api则是基于HTTP协议，将服务端可提供的功能规定了具体的格式与指令。客户端按照api给定的格式向特定的URL发起请求，服务端便会按照指令进行响应。awtrix在支持mqtt的基础上，同时提供了web api以供调用。
控制指令控制 AWTRIX 使用的是 json 格式的指令，这种格式用大括号｛｝括起，包括一个或多个“键值对”，多个键值对之间需用逗号隔开。键值对用冒号分开，左边为键(key)，右边是值(value)，其中键始终需要加双引号，值则根据不同的数据类型决定是否加引号或方括号。（整形、布尔型无需加符号，字符串型需要加引号，数组、字符串组需要加方括号） 举例如下：
以红色显示“Hello, AWTRIX 3!”10秒钟的时间：
{
"text": "Hello, AWTRIX 3!",
"color":[255,0,0],
"duration": 10
}
或
{"text": "Hello, AWTRIX 3!","color":[255,0,0],"duration": 10}
以下是AWTRIX中我认为比较常用的键，我没有提及的部分可去官方文档差缺补漏。 所有的键均是可选项，实际使用时只需包括需要的键。部分属性在自定义app与通知中可用性不同，表格中已标出。
| 键 | 类型 | 描述 | 默认值 | 自定义app | 通知 | text | 字符串 | 显示的文字。需注意默认字体每个字母占据的空间有所不同，这在文字滚动时可能有所影响。 | N/A | 可用 | 可用 | color | 字符串或整数数组 | 文字、进度条或线条的颜色。 | N/A | 可用 | 可用 | blinkText | 整型 | 使文本按指定的时间间隔闪烁，时间单位为毫秒。同gradient 、 rainbow不兼容。 | N/A | 可用 | 可用 | fadeText | 整型 | 使文本按指定的时间间隔渐隐渐显，时间单位为毫秒。同gradient 、 rainbow不兼容。 | N/A | 可用 | 可用 | background | 字符串或整数数组 | 设置一个背景颜色。 | N/A | 可用 | 可用 | rainbow | 布尔型 | 使文本中每个字母的颜色在整个RGB色轮中渐变。 | false | 可用 | 可用 | icon | 字符串 | 需显示的图标ID或文件名(不含扩展名)。同时也可使用 Base64 字符串发送8x8的jpeg图片。 | N/A | 可用 | 可用 | repeat | 整型 | 设置app或通知结束显示前文字的滚动次数。 | -1 | 可用 | 可用 | duration | 整型 | 设置app或通知的显示时长。 | 5 | 可用 | 可用 | hold | 布尔型 | 设为 true 时，通知会持续显示至按下中间按钮或通过 homeassistant 忽略。 | false | 不可用 | 可用 | rtttl | 字符串 | 直接发送并播放 RTTTL 铃声编码。（需加装蜂鸣器） | N/A | 不可用 | 可用 | loopSound | 布尔型 | 在通知持续期间循环音乐或RTTTL铃声。 | false | 不可用 | 可用 | progress | 整型 | 在屏幕底部显示一个进度条。赋值范围为0-100。 | -1 | 可用 | 可用 | progressC | 字符串或整数数组 | 设置进度条的前景色。 | -1 | 可用 | 可用 | progressBC | 字符串或整数数组 | 设置进度条的背景色。 | -1 | 可用 | 可用 | lifetime | 整型 | 当自定义app在给定的时间内未更新过，则将其删除(可通过lifetimeMode调整)。时间的单位为秒。 | 0 | 可用 | 不可用 | lifetimeMode | 整型 | 自定义app长时间未更新后的处理方式。0 = 删除该app, 1 = 在app外围显示一圈红色矩形标志其已过期。 | 0 | 可用 | 不可用 | stack | 布尔型 | 定义通知是否可堆叠，设为false会直接替换掉当前的通知。 | true | 不可用 | 可用 | wakeup | 布尔型 | 如果收到该通知时屏幕为关闭状态，则将其打开，并在通知结束后将其关闭。 | false | 不可用 | 可用 | noScroll | 布尔型 | 禁用文字滚动。 | false | 可用 | 可用 | scrollSpeed | 整型 | 调整滚动速度。以默认速度为100%，填入百分比数值。 | 100 | 可用 | 可用 | effect | 字符串 | 使用一个效果作为背景。该效果可通过发送该键的空值以移除。 |
| 可用 | 可用 | effectSettings | json map | 调整效果的颜色与速度。 |
| 可用 | 可用 | save | 布尔型 | 将自定义app保存至falsh存储器中，以便在重启后加载。避免保存更新速度较快的自定义app，以防flash存储器读写寿命的快速消耗。 |
| 可用 | 不可用 |
交互链接对于“信该寄去哪”，通过对通信协议的认识，应该可以推断出：MQTT协议下需要发送到特定的“帖子”（学名为主题），而HTTP协议下需要发送至特定的链接。AWTRIX的显示内容可分成两个类型，分别是“通知”和“自定义app”，同一指令发送至不同主题/链接有着不同的处理方式。
通知 该类型下所接收的指令不会被保存，只会显示一次，退出后无法再显示（除非再次发送）。发送的主题为 [前缀]/notify ([前缀]可在AWTRIX后台的MQTT界面找到)，发送的链接为 http://[IP]/api/notify ([IP]需替换为设备的当前ip，请求方式为POST)。
自定义app 该类型下所接受的指令会被临时保存至下次重启(默认设置下)，并可多次显示。为方便管理，自定义app有“名称”这一概念，发送的主题为 [前缀]/custom/[app] ([app]即为该app的名称)，发送的链接为 http://[IP]/api/custom，需在查询参数中添加app的名称(name=[appname])。 由于自定义app会被临时保存，所以它也有“更新”这一概念，向该app对应的主题/链接再次发送指令便可即时更新。删除该自定义app则需向对应的主题/链接发送空载荷/空请求体。 默认情况下，awtrix会在各app之间自动轮换，有通知时则优先显示通知。
实际应用
使用homeassistant/MQTTawtrix接入ha走的是mqtt协议，这需要一个broker。如果使用的HAOS，那么直接使用加载项安装emqx即可，如果不是，则可以单独用docker安装。 安装完成后，需要将broker的ip地址（haos安装的话就是ha的ip）、端口号（默认为1883）、用户名、密码（emqx默认用户名admin，密码public）填入awtrix的网页后台，打开ha自动发现。Prefix即为所有MQTT主题中的[前缀]。 在完成上述操作后，如果设备正常连接上了broker（未正常连接的话屏幕左下角会亮一颗黄灯），在ha的设备和服务-mqtt下便可发现这个设备。 目前固件版本（0.98）默认有11个可控实体（注意像素屏、指示灯实体都是可以再点开的，和其他灯一样有亮度、颜色等详细设置），14个传感器实体。成功接入后便可在仪表控制一些基础的选项，详细的控制则需要使用自动化中的其他动作-MQTT-发布动作。
该动作中，重点需要关注的是“主题”和“有效载荷”：主题是之前的“交互链接”，有效载荷便是json格式的指令(qos无特别需求选0即可)。
由于json命令中可以嵌套ha的模板，便可将HA中的实体属性显示到AWTRIX上，这里提供一个实际的自动化例子，是我用来监控3d打印进度的：
#触发：打印机进度发生变化；
#条件：像素灯开着；
#动作：如果进度为0-99%，则创建一个自定义 app展示当前进度并实时更新；如果进度为100%，则发送带提示音的打印完成持久通知，同时删除该自定义 app。
triggers:
- trigger: state
entity_id:
- sensor.打印进度
conditions:
- condition: state
entity_id: light.像素灯
state: "on"
actions:
- if:
- condition: numeric_state
entity_id: sensor.打印进度
above: 0
below: 100
then:
- action: mqtt.publish
metadata: {}
data:
qos: "0"
topic: [前缀]/custom/print_progress
payload: >-
{"text":"{{states('sensor.打印进度',
with_unit=true)}}","progress":"{{states('sensor.打印进度',
with_unit=false)}}","icon":"printer"}
- if:
- condition: numeric_state
entity_id: sensor.打印进度
above: 99.9
below: 100.1
then:
- action: mqtt.publish
metadata: {}
data:
qos: "1"
topic: [前缀]/notify
payload: >-
{"text":"done","hold":true,"icon":"printer_done","rtttl":"":d=4,o=5,b=100:16e6,16e6""}
- action: mqtt.publish
metadata: {}
data:
qos: "1"
topic: [前缀]/custom/print_progress
使用node-red/web api除了使用ha走mqtt控制awtrix，还可使用node-red直接调用web api。node-red与emqx同理，可以使用HAOS的加载项安装，也可使用docker独立安装。 使用node-red向AWTRIX发送消息最少需要两个节点，一个是fuction节点，用于填写控制指令，一个是http request节点，用于发起请求。
同MQTT类似，重点需要关注的是http request节点中的URL，和请求参数中msg.payload=这一行，URL便是之前的交互链接，payload填入json格式的指令。示例节点文件见附件。 说实话，node-red我还没怎么研究，这部分也就没有在用的自动化流程了，可以在资源网站（见下）中找一找。
扩展内容高级控制 除了本文介绍的自定义显示外，AWTRIX固件还提供了许多其他功能，这些功能的调用和本文介绍的方法是一样的，无非是交互链接或者控制命令上有所区别，这些内容都可以在官方文档中找到。
Art-Net协议 除了通过mqtt/http控制外，awtrix还支持art-net协议，该协议主要应用于舞台灯光、LED显示屏和投影设备的控制，理论上可用的软件还是很多的，但多较为专业，官方文档中推荐了jinx!并给出了模板文件。导入模板并修改ip为设备ip后，便可使用该软件控制AWTRIX。 我用这个软件测试了下中文显示，只能说8x8的点阵对于汉字来说实在太小，这种像素灯还是更适合显示英文。
手机控制app 作者提供了可在手机上控制像素灯的app，在play商店或appstore可以找到，叫AWTRIX 3，售价约30rmb。 app内提供了提供了调整亮度、开关像素屏、开关内置app、调整app顺序、绘制动图图标等功能。在没有安装按钮且未接入MQTT时，该程序可以作为调整像素灯基础设置的工具。如果接入了MQTT/安装了顶部的三颗按键，该程序所提供的功能基本能用其他方法来实现。 总的来说，这个只建议当做支持作者来买，不太建议买来用，也就绘制动图图标有点意思，但不太值这30块。
常用网站 官方文档：https://blueforcer.github.io/awtrix3/#/README 一些现成的flow或HA自动化蓝图：https://flows.blueforcer.de/ 在线RTTTL铃声编辑器：https://corax89.github.io/esp8266Game/soundEditor.html
到这基础的用法差不多就讲完了，那么最后，祝玩灯愉快。 | 
发表于 
