新手必看：Ulanzi Studio + TC002 MQTT使用教程

Ulanzi

MQTT 使用教程
适用设备：Ulanzi TC002（像素时钟二代）
软件版本：Ulanzi Studio V3.1.0 及以上


一、简介
通过MQTT功能，TC002可以接入更灵活的自动化与数据控制场景。
配合 Ulanzi Studio 使用后，你可以将文字、状态信息或自动化指令同步到设备，让TC002不只是像素时钟，也能作为桌面信息屏或智能联动显示终端。
你可以用它实现例如以下功能：  
1、通过 MQTT 向 TC002 发送文本或控制指令；
2、与 Home Assistant 联动，自动更新设备显示内容；
3、对接 Node-RED、ESPHome 等工具，扩展个性化显示玩法；
本教程将带你完成从 MQTT 服务部署到TC002接入配置的完整流程，适合第一次接触该功能的用户。

二、前置条件
在开始配置之前，请确保您已具备以下条件：

• TC002 设备已通过 WiFi 配网并成功连接到您的局域网（2.4G 网络）
• 一台运行 Windows 10 及以上 / macOS 12.0 及以上的电脑
• 如需使用 Home Assistant 集成，请先在 Docker 中安装并启动 Home Assistant
• 电脑与 TC002 设备处于同一局域网中

三、部署 EMQX 服务器
EMQX 是一款开源的高性能 MQTT 消息服务器。我们需要在本地电脑上部署 EMQX，作为 TC002 与各类 MQTT 客户端之间的消息中转枢纽。

3.1 下载 EMQX
请根据您的操作系统，前往 EMQX 官网下载对应的安装包：

下载地址：https://www.emqx.com/zh/downloads/broker

⚠ 注意：EMQX 官网自 v5.3.2 之后的版本已不再提供 Windows 版本的直接下载链接。如果您是 Windows 用户，请访问 https://www.emqx.com/zh/downloads/broker/v5.3.2 下载 v5.3.2 版本的 Windows 安装包。

参考文档：https://blog.csdn.net/weixin45783574/article/details/122462337



本教程以 Windows 10 系统为例，下载 emqx-5.3.2-windows-amd64.zip。如果您未找到对应系统的安装包，也可以通过 Docker 部署 EMQX 服务器。



3.2 安装与启动 EMQX
下载完成后，请按照以下步骤操作：

Step1：将下载的压缩包解压到您指定的文件夹

Step2：进入文件夹的 emqx/bin目录

在 bin 目录下，以管理员身份打开命令提示符（CMD），依次执行以下命令：

.\\emqx install

.\\emqx console

.\\emqx start



�� 提示：执行 .\\emqx console 命令后，终端会显示 EMQX 的运行日志。当看到 “EMQX is running” 的提示，说明服务器已成功启动。



3.3 访问 EMQX 管理面板
EMQX 启动后，打开浏览器访问以下地址：

http://127.0.0.1:18083



首次登录时，使用以下默认账号密码：

• 用户名：admin

• 密码：public



登录后，系统会提示您设置新的管理员密码。请设置您自己的密码并牢记。

Image

图 1：EMQX 管理面板首页

至此，EMQX 服务器已成功部署并运行在您的本地电脑上。

四、配置 TC002 MQTT 连接
接下来需要让 TC002 连接到您的 MQTT 服务器。

4.1 获取本机 IPv4 地址
在配置之前，请先获取您电脑的局域网 IPv4 地址（通常格式为 192.168.x.x）。

• Windows：打开命令提示符，输入 ipconfig，查看「IPv4 地址」

• macOS：打开终端，输入 ifconfig，查看 en0 或 en1 接口的 inet 地址



4.2 TC002 MQTT 页面配置
在 Ulanzi Studio 软件中，进入 TC002 的应用设置页面，找到 MQTT 配置项：

• MQTT 服务器地址：输入您的本机 IPv4 地址（如 192.168.1.100）

• 端口：保持默认 1883

• 其他参数可根据需要选择填写

配置完成后，点击「保存」按钮。



�� 提示：TC002 成功连接 MQTT 服务器后，您可以在 EMQX 管理面板的「集群概览」页面中查看到已连接的客户端。

五、使用 MQTTX 客户端发送指令
如果您希望通过编写代码的方式自定义像素时钟的显示内容，可以使用 MQTTX 客户端工具进行指令测试。

5.1 安装 MQTTX
MQTTX 是一款开源的跨平台 MQTT 客户端工具，支持 Windows、macOS 和 Linux。

下载地址：https://mqttx.app/

5.2 配置 MQTTX 连接
安装完成后，打开 MQTTX 客户端进行连接配置：

• 名称：可自行填写，用于标识该连接

• 服务器地址：输入您本地电脑的 IPv4 地址（请勿使用 broker.emqx.io）

• 端口：1883

• 其他参数可自行选择填写

配置完成后，点击「连接」按钮。

Image

图 2：MQTTX 连接配置



5.3 添加订阅话题（可选）
您可以在 MQTTX 中添加订阅话题，用于监控 TC002 上报的消息。此步骤为可选操作。

Image

图 3：MQTTX 订阅话题配置



5.4 发送显示指令
在 MQTTX 中，填写发送主题（Topic）和消息内容（Payload），即可向 TC002 发送自定义显示内容。

Image

图 4：MQTTX 发送指令界面



以下是一个示例 JSON 指令，用于在像素时钟屏幕上显示 “Hello World”：

{

"text": [

{

"content": "Hello World",

"fontHeight": 10,

"x": 0,

"y": 0,

"color": "#FFFFFF",

"align": "left",

"valign": "top",

"rect": [0, 0, 52, 16],

"charSpacing": 1

}

]

}

点击右下角的发送按钮后，TC002 的 DIY 界面即会显示 “Hello World” 文字。

Image

图 5：TC002 显示 Hello World 效果

六、Home Assistant 集成配置
如果您希望通过 Home Assistant（简称 HA）智能家居平台控制 TC002，请继续以下配置。

6.1 安装 Home Assistant
请确保您已在 Docker 中安装并成功启动 Home Assistant。如尚未安装，请参考以下文档：

• Ulanzi 官方论坛教程：https://bbs.ulanzistudio.com/thread-2-1-1.html

• 腾讯云开发者社区：https://cloud.tencent.com/developer/article/2539619

Image

图 6：Home Assistant 添加集成入口



6.2 添加 MQTT 集成
在 Home Assistant 中，您需要先添加 MQTT 集成：

Step1：进入 Home Assistant 的「设置」→「设备与服务」页面

Step2：点击右下角「添加集成」按钮

Step3：在搜索框中输入 “MQTT”，选择 MQTT

Image

图 7：搜索并添加 MQTT 集成



系统会提示 MQTT 集成添加成功。返回「设备与服务」页面，可以看到已添加的 MQTT 集成，点击进入配置。

6.3 配置 MQTT 代理
在 MQTT 集成配置页面中：

• MQTT 代理（Broker）：输入您本机电脑的 IPv4 地址

• 端口：保持默认 1883

• 用户名和密码：可根据需要自行设置

• 自动发现（Discovery）：建议开启

配置完成后，点击「保存」按钮。





6.4 验证连接状态
打开 EMQX 管理面板（http://127.0.0.1:18083），进入「集群概览」页面，您可以看到有两台设备处于已连接状态：

Image

图 8：EMQX 集群概览 - 两台设备在线



您可以点击「客户端」页面，检查已连接的设备名称是否为您的 Home Assistant 和 TC002 设备。

接着进入「WebSocket 客户端」页面，点击「连接」按钮。

Image

图 9：EMQX WebSocket 客户端连接



再次返回「集群概览」，您将看到连接数变为 3。恭喜，MQTT 通信链路已全部打通！接下来我们将在 Home Assistant 中进行进一步配置，实现通过 HA 控制 TC002 设备。



七、Home Assistant 蓝图配置
蓝图（Blueprint）是 Home Assistant 提供的自动化模板功能，可以快速创建可复用的自动化场景。

7.1 获取蓝图 YAML 文件
您可以通过以下两种方式获取蓝图 YAML 文件：

方式一：从蓝图仓库选择

访问以下 GitHub 仓库，浏览不同效果的蓝图模板：

https://github.com/jeeftor/homeassistant?tab=readme-ov-file

选择您喜欢的效果，点击页面上的 “Import” 按钮进行导入。

Image

图 10：GitHub 蓝图仓库 - 选择并导入蓝图



方式二：自行编写 YAML 文件

如果您熟悉 YAML 语法，可以自行编写蓝图文件。编写完成后，将 YAML 文件上传到公网并获取 HTTP 链接，然后在 HA 蓝图导入页面填入您的链接即可。

Image

图 11：导入蓝图 - 填写链接

以下是本教程附带的一个示例 YAML 文件

[light.yaml]

（light.yaml），您可以直接使用它体验 Lights 灯光效果：

7.2 放置蓝图文件
将下载或编写好的 YAML 文件放入 Home Assistant 的配置目录中。有两种方式：

• 方式一：通过命令行工具将文件挂载到容器中的 config 目录

• 方式二：手动进入 Home Assistant 的 config 文件夹，按以下路径放置文件：

Image

图 12：找到 Home Assistant 的 config 文件夹



依次进入以下目录：

haconfig → blueprints → automation



将您的 YAML 文件放入 automation 文件夹中。

Image

图 13：将 YAML 文件放入 blueprints/automation 目录



八、通过蓝图创建自动化实体
蓝图文件放置完成后，即可在 Home Assistant 中通过蓝图创建自动化实体。

Step1：进入「设置」→「自动化与场景」页面

Step2：点击「创建自动化」按钮

Image

图 14：Home Assistant 自动化配置页面

Image

图 15：Home Assistant 参数配置

Step3：选择您导入的蓝图模板，根据向导完成参数配置

Step4：点击「保存」按钮



保存成功后，进入「设置」→「设备与服务」→「实体」页面，确认您的实体已创建成功。

最后，进入 HA 的「概览」页面，即可找到您配置的实体卡片。

Image

Image

Image

九、查看效果
现在，您可以将 TC002 设备切换到 DIY 模块，即可在像素屏幕上看到您通过 Home Assistant 设置的效果。

恭喜！您已完成 MQTT 全流程配置。您现在可以：

• 通过 MQTTX 客户端发送自定义文本和动画指令到 TC002

• 通过 Home Assistant 的自动化场景灵活控制 TC002 的显示内容

• 进一步对接 Node-RED、ESPHome 等平台，打造更丰富的 IoT 应用场景

十、参考链接
EMQX 官网：https://www.emqx.com/zh/downloads/broker

EMQX v5.3.2 Windows 版：https://www.emqx.com/zh/downloads/broker/v5.3.2

MQTTX 客户端：https://mqttx.app/

Home Assistant 蓝图仓库：https://github.com/jeeftor/homeassistant?tab=readme-ov-file

Ulanzi 官方论坛 HA 教程：https://bbs.ulanzistudio.com/thread-2-1-1.html

腾讯云 HA Docker 部署指南：https://cloud.tencent.com/developer/article/2539619

EMQX 部署参考：https://blog.csdn.net/weixin_45783574/article/details/122462337

AWTRIX 协议参考：https://blueforcer.github.io/awtrix3/

Ulanzi FAQ：https://docs.ulanzistudio.com/zh/faq/



⚠ 注意：请确保 TC002 设备固件已升级至最新版本，以获得最佳 MQTT 兼容性。如有任何问题，请访问 Ulanzi 官方 FAQ 页面或联系技术支持。