简介：这是一份面向物联网开发者的ESP8266/32接入涂鸦Tuyalink平台的Arduino项目源码包，适合需要实现智能设备联网、远程控制与OTA在线升级的嵌入式工程师。压缩包共3个文件，包含inscode工程配置文件、index.html设备控制页面和.gitignore版本管理规则，整体仅6KB，结构轻量且便于二次开发。已有125人学习使用。项目源码完整演示了接入授权码获取、MQTT连接参数配置、TLS加密传输等关键步骤，并给出了设备初始化、网络连接与云平台通信的参考实现；同时附带简洁的Web控制页面，可帮助读者厘清从设备端到Tuyalink再到App的完整链路，快速将类似能力移植到智能插座、传感器等实际项目中。 做硬件接入这些年，最烦的事莫过于“芯片选好了，云平台还在纠结”。 ESP8266和ESP32这类Wi-Fi模块不缺算力、不缺社区资源，缺的是一个接入成本足够低的云平台。自己搭MQTT服务器吧，公网、证书、域名样样都要折腾；用大厂IoT平台吧，SDK一坨坨的，不少还得换指定模组。直到我把ESP32接到了Tuyalink（涂鸦Link）上，才发现IoT上云这事儿原来可以这么干净——用MQTT over TLS直连涂鸦云，不需要专用的Wi-Fi模组，不需要捆绑SDK，只需要一组三元组信息，代码量比你想象的小得多。
这篇文章把我从零到一跑通的ESP8266/32连接Tuyalink项目拆开讲透。从平台配置、签名原理、源码实现到实际调试中踩过的坑，全部摊开说，适合手里正好有ESP8266/ESP32开发板、想快速让设备联网并接入成熟IoT平台的开发者参考。
1. 涂鸦Link接入思路与整体设计
1.1 涂鸦Link不是原来那套涂鸦SDK
很多早年玩过涂鸦方案的朋友，印象还停留在“必须买涂鸦的Wi-Fi模组，再用MCU串口跟模组通信”的老路上。那套方案确实成熟，但设备端被限制得比较死，主控必须理解涂鸦的串口协议，而且模组价格、供货、开发方式都不是自己能完全掌控的。
涂鸦Link（Tuyalink）的思路完全不同：它把涂鸦云的能力以MQTT协议的方式直接开放给任意具备联网能力的设备。换句话说，只要你的MCU能跑TCP/IP协议栈，能发标准MQTT报文，就能接入涂鸦云，哪怕你的板子是ESP8266、ESP32、树莓派，甚至是PC上的程序都没问题。
核心工作流程拆开就三件事：设备端通过TLS加密通道连接涂鸦的MQTT Broker；认证时使用一组“一机一密”的密钥三元组；之后用JSON格式按涂鸦定义的数据模型上报属性、接收指令。整个链路不依赖任何厂商专用固件，这给了开发者很大的自由空间。
1.2 为什么选Tuyalink而不是其他接入方案
市面上ESP8266/ESP32上云的路子我基本都试过，各有各的痛点：
- 自建MQTT服务器（EMQX/Mosquitto）：适合极客，但公网服务器要钱、要维护，还要处理证书、域名、端口映射。做产品demo还行，做量产方案维护成本偏高。
- 阿里云/腾讯云IoT平台：服务能力很强，但设备端接入往往要引入官方SDK，有些还需要特定固件规范，代码侵入性比较大。对个人开发者来说，光理解设备证书、Topic权限这些概念就要花不少时间。
- 涂鸦Link：最大的优势是“MQTT标准协议直连+成熟App生态”。你不需要引入杂七杂八的SDK，一个
PubSubClient库就能搞定。同时涂鸦本身的App、小程序、语音音箱生态是现成的，设备接入云端后，直接用涂鸦生态的App就能控制，省去了自己从头开发App的功夫。
对我这种习惯“代码越少越好”的开发者来说，这基本是最优解。
1.3 整体数据链路设计
我用一张图来描述这个项目的完整链路（文字版，大家脑补一下）：
ESP8266/ESP32 (WiFiClientSecure + PubSubClient) │ │ MQTT over TLS (Port 8883) ▼ 涂鸦云 MQTT Broker (mqtts.tuyacn.com) │ ├── 上行：属性上报/事件上报（JSON） ├── 下行：属性设置/指令调用（JSON） ▼ 涂鸦App / 小程序 / 语音音箱设备端要做的逻辑非常清晰：连Wi-Fi → 同步时间（这是签名计算的关键） → 建立TLS连接 → MQTT认证 → 订阅下行Topic → 循环发布属性数据。平台端只需要在产品定义里建好DP点（数据点），然后把三元组填到代码里，整个物理世界和云端之间的通道就算打通了。
2. 硬件选型与开发环境搭建
2.1 ESP8266还是ESP32，我的建议
很多朋友在这两个芯片之间纠结。说实话，如果你只是接一个温湿度传感器，每分钟上报一次数据，ESP8266（如NodeMCU、Wemos D1 mini）完全够用，价格还便宜。但如果你计划以后扩展屏幕、摄像头、本地语音、或者跑Micro-ROS，那直接上ESP32更省事。
更关键的一点是TLS握手对内存的压力。ESP8266只有80MHz单核，内存还分内部DRAM和flash缓存，跑TLS握手时如果缓冲区配置不当，很容易出现SSL connect error直接崩。ESP32双核240MHz，320KB RAM，TLS表现稳得多。我的建议是：做涂鸦Link方向的开发，优先ESP32，省下来的调试时间远不止芯片那几块钱差价。
注意，ESP8266如果选1MB flash的板子，编译会遇到镜像超出分区大小的问题，建议买4MB flash版本。ESP32则尽量选带USB-UART桥接芯片的主流板子（CP2102或CH340都行），驱动好找，烧录不容易翻车。
2.2 Arduino IDE环境搭建
Arduino IDE 2.x是我目前的主力版本，界面清爽，串口监视器、库管理都内置了。添加开发板来源的方法很简单。
在“文件 → 首选项 → 附加开发板管理器网址”里填入：
http://arduino.esp8266.com/stable/package_esp8266com_index.json https://espressif.github.io/arduino-esp32/package_esp32_index.json然后在“开发板管理器”中搜索“esp8266”或“esp32”安装对应平台包。网上很多人报错failed to install platform: 'esp32:3.3.11'，这类问题绝大多数是网络下载开发板工具链超时导致的。解决办法是手动下载工具链压缩包，解压到%LOCALAPPDATA%/Arduino15/packages/esp32/tools目录，或者干脆换个网络环境再试。国内用户把Arduino IDE的代理调好，成功率会高很多。
2.3 需要安装的第三方库
本项目用到的库就三个，全部在Arduino库管理器里搜索安装：
- PubSubClient（MQTT客户端，knolleary出品）
- ArduinoJson（JSON构造和解析，选v6或v7版本皆可，API差异不大）
- WiFiManager（可选，用于配网体验优化，在库管理器直接安装同名库）
我在macOS和Windows上各验证过一次，依赖完全一致。如果你用的是PlatformIO + VSCode，那更简单，platformio.ini里声明三行依赖就行，编译环境会自动下载。
3. 涂鸦控制台配置与连接参数
3.1 创建产品并定义DP点
在涂鸦IoT平台注册账号并登录后，进入“产品开发”，选择“自定义产品”——这个选项很适合自己造设备，而不是从官方品类库里挑模板。创建产品时，需要选择产品品类（比如“传感器”“电工”），分类影响App端的显示模板，但不影响MQTT接入逻辑。
建好产品后最重要的一步是“定义功能”，也就是DP点。举个例子，做一个温湿度传感器，我建的DP点类似这样：
| DP ID | 功能名称 | 数据类型 | 读写类型 |
|---|---|---|---|
| 1 | 温度 | Int（整数） | 只读 |
| 2 | 湿度 | Int（整数） | 只读 |
| 3 | 开关 | Bool（布尔） | 可写 |
请注意，DP点的“可写”属性决定了这个指令是“只能上报”还是“也能从云端下发控制”。比如开关，必须设置成可写，才能通过App远程开关。DP点数据类型要和设备端上报的数据严格一致，否则数据会被云端拒绝。
3.2 开启涂鸦Link云云对接
产品创建完成后，进入“云端开发”模块，选择开发方式为“涂鸦Link”（有的页面叫“涂鸦Link云云对接”）。这个过程会为产品生成一组与MQTT Broker通信的密钥信息。
关键信息在“运行状态”或者“设备调试”页面里找：
- Device ID：每台设备的唯一ID，形如
6ce2c1xxxxxxx，设备端上报时作为Topic的一部分，非常重要 - Client ID：涂鸦分配的MQTT客户端ID，也是一串十六进制字符串
- Access Secret：设备级密钥，用于计算MQTT连接的动态密码
- MQTT接入地址：中国区是
mqtts.tuyacn.com，端口8883（TLS加密）
给产品添加测试设备后，控制台会显示这些三元组信息。注意不同地区（中国/海外）的MQTT地址不一样，海外要用mqtts.tuyaus.com这类域名，根据自己控制台所在区域填。
3.3 MQTT参数与Topic结构说明
涂鸦Link的MQTT连接参数，简单说就是“标准MQTT三项”：
- ClientID：填控制台分配的
Client ID - Username：填控制台分配的
Client ID - Password：动态计算，不能用明文Access Secret
Password的计算规则是：用Access Secret作为HMAC密钥，对字符串device_id + client_id + 时间戳(毫秒)做HMAC-SHA256签名，输出十六进制小写字符串。时间戳必须是当前的Unix毫秒时间戳，涂鸦要求12小时内有效，所以设备端必须联网同步时间。
Topic结构如下（{device_id}替换为实际设备ID）：
| 方向 | Topic | 说明 |
|---|---|---|
| 设备发布 | /tylink/{device_id}/property/post | 上报属性数据 |
| 设备发布 | /tylink/{device_id}/thing/call_reply | 指令执行结果回复 |
| 设备订阅 | /tylink/{device_id}/property/set | 云端下发属性设置 |
| 设备订阅 | /tylink/{device_id}/thing/call | 云端下发指令调用 |
理清Topic后，整个接入方案的轮廓就全出来了。
4. 设备端源码实现与核心原理
4.1 密码签名与时间同步
签名是涂鸦Link接入最容易出错的一环。先说原理：HMAC-SHA256是一种带密钥的哈希算法，可以把它理解成“用钥匙锁文件”，同一份明文，换一把钥匙（密钥），出来的密文完全不同。涂鸦这里把Access Secret当钥匙，把device_id + client_id + 时间戳当明文，算出的结果就是MQTT的Password。
在Arduino环境里，ESP32和ESP8266都内置了mbedTLS，可以直接调用。我封装了一个签名函数：
#include <WiFi.h> #include "mbedtls/md.h" String hmacSha256(String key, String payload) { byte hmacResult[32]; mbedtls_md_context_t ctx; mbedtls_md_init(&ctx); mbedtls_md_setup(&ctx, mbedtls_md_info_from_type(MBEDTLS_MD_SHA256), 1); mbedtls_md_hmac_starts(&ctx, (const unsigned char*)key.c_str(), key.length()); mbedtls_md_hmac_update(&ctx, (const unsigned char*)payload.c_str(), payload.length()); mbedtls_md_hmac_finish(&ctx, hmacResult); mbedtls_md_free(&ctx); String hexStr = ""; for (int i = 0; i < 32; i++) { char buf[3]; sprintf(buf, "%02x", hmacResult[i]); hexStr += buf; } return hexStr; }时间戳的获取要特别注意：Arduino的millis()是从开机开始计数的，并不是Unix时间戳。正确的做法是联网后先同步NTP：
#include <time.h> configTime(8 * 3600, 0, "ntp.aliyun.com", "pool.ntp.org"); time_t now = time(nullptr); long long timestamp = (long long)now * 1000LL;configTime的第一个参数是时区偏移，中国是UTC+8，写8 * 3600。如果设备没有正确同步时间，签名里带的时间戳就会超出涂鸦的12小时有效性窗口，连接直接被拒绝。
签名生成函数：
String generatePassword(String deviceId, String clientId, String accessSecret) { time_t now = time(nullptr); long long timestamp = (long long)now * 1000LL; String message = deviceId + clientId + String(timestamp); return hmacSha256(accessSecret, message); }4.2 MQTT连接与订阅
Wi-Fi连接之后，创建WiFiClientSecure和PubSubClient实例。开发阶段为省事，可以调用setInsecure()跳过证书校验，但正式部署时建议把涂鸦的CA证书写入固件做双向校验，别图省事留隐患。
连接涂鸦云的代码框架：
WiFiClientSecure espClient; PubSubClient mqttClient(espClient); const char* mqttHost = "mqtts.tuyacn.com"; const int mqttPort = 8883; String clientId = "你的ClientID"; String deviceId = "你的DeviceID"; String accessSecret = "你的AccessSecret"; String password = generatePassword(deviceId, clientId, accessSecret); espClient.setInsecure(); mqttClient.setServer(mqttHost, mqttPort); mqttClient.setCallback(callback); if (mqttClient.connect(clientId.c_str(), clientId.c_str(), password.c_str())) { mqttClient.subscribe(("/tylink/" + deviceId + "/property/set").c_str()); mqttClient.subscribe(("/tylink/" + deviceId + "/thing/call").c_str()); }连接成功后立刻订阅下行Topic。注意订阅时机一定要在连接成功之后，否则会错过云端下发的指令。
4.3 属性上报
属性上报就是往/tylink/{device_id}/property/post这个Topic发布一条JSON消息。涂鸦要求的数据格式中，msg_id是消息唯一标识，可以自己生成，建议用自增计数或者随机数；pty里放DP点ID和值的映射。
void reportProperty() { StaticJsonDocument<256> doc; doc["msg_id"] = String(random(100000, 999999)); doc["device_id"] = deviceId; JsonObject pty = doc.createNestedObject("pty"); pty["1"] = temperature; // DP点1 pty["2"] = humidity; // DP点2 char buffer[256]; serializeJson(doc, buffer); String topic = "/tylink/" + deviceId + "/property/post"; mqttClient.publish(topic.c_str(), buffer); }ArduinoJson的缓冲区大小要按数据量估算，我给传感器数据开256字节足够。如果后续要上报字符串类型（比如固件版本），记得把buffer和doc空间都调大。上报之后，云端会通过/tylink/{device_id}/property/post_reply返回一个ack，可以在回调里解析code字段判断是否成功。
4.4 指令下发处理
当你在涂鸦App里点击开关，云端会向设备的/tylink/{device_id}/property/setTopic推送一条消息。设备端在回调函数里解析，典型消息长这样：
{"msg_id":"123456","device_id":"xxxx","pty":{"3":true}}回调函数内部做一个JSON反序列化，把pty对象里的DP点ID取出来，执行对应的硬件操作。
void callback(char* topic, byte* payload, unsigned int length) { StaticJsonDocument<256> doc; deserializeJson(doc, payload); String msgId = doc["msg_id"].as<String>(); JsonObject pty = doc["pty"].as<JsonObject>(); if (pty.containsKey("3")) { bool switchState = pty["3"]; digitalWrite(RELAY_PIN, switchState ? HIGH : LOW); } // 回执消息 StaticJsonDocument<128> replyDoc; replyDoc["msg_id"] = msgId; replyDoc["device_id"] = deviceId; replyDoc["code"] = 0; char replyBuf[128]; serializeJson(replyDoc, replyBuf); String replyTopic = "/tylink/" + deviceId + "/thing/call_reply"; mqttClient.publish(replyTopic.c_str(), replyBuf); }这里有个细节：如果不回执，App端偶尔会显示“指令超时”。所以收到指令后不管执行成功与否，都建议向thing/call_reply回一条带code的报文。code=0表示成功，非0表示失败。
4.5 断线重连与保活优化
IoT项目掉线是常态，Wi-Fi不稳定、云端保活超时都会踢掉连接。我在主循环里有一个简单的状态机：
void loop() { if (!mqttClient.connected()) { reconnect(); } mqttClient.loop(); static unsigned long lastReport = 0; if (millis() - lastReport > 10000) { lastReport = millis(); reportProperty(); } } void reconnect() { while (!mqttClient.connected()) { String password = generatePassword(deviceId, clientId, accessSecret); if (mqttClient.connect(clientId.c_str(), clientId.c_str(), password.c_str())) { mqttClient.subscribe(("/tylink/" + deviceId + "/property/set").c_str()); mqttClient.subscribe(("/tylink/" + deviceId + "/thing/call").c_str()); } else { delay(5000); } } }注意重连时密码要重新计算，因为时间戳变了，旧密码可能已经失效。我在这一点上吃过亏，后来一查发现签名里带着时间，明白了必须每次连接都现算。这个重连函数已经跑了一个多月，稳定性非常好。
5. 常见问题与排查技巧实录
5.1 TLS连接失败、SSL握手闪退
如果你用的是ESP8266，连接时经常WiFiClientSecure报SSL connect error，十有八九是内存不足。TLS握手要分配一大块堆内存作为发送/接收缓冲，而ESP8266在某些库版本下堆碎片化严重。解决办法：换用ESP32开发板测试；如果坚持用ESP8266，可以尝试把PubSubClient的发送缓冲调小，或者在编译选项里打开ESP8266_1M的优化分区。必要的时候把上报频率降下来，不要每秒钟触发TLS连接。
5.2 认证失败，返回connect error code 5
MQTT_CONNECT_FAILED里藏着好多种原因。最常见的是签名时间戳过期，检查一下设备是否成功走到time(nullptr)分支。调试方法很直接：在串口打印时间和生成的Password，然后放到涂鸦控制台的“调试工具”里手动验证签名规则。另外确认你填写的AccessSecret是“设备级密钥”，而不是产品级的。有些朋友把产品密钥和设备密钥弄混，找了半天才发现查错了地方。
5.3 数据上报成功但App不刷新
设备上报了，App里数据不动，这个bug我排查了很久。后来发现是DP点ID对不上。控制台建的DP点ID是从0开始还是从1开始？涂鸦的自定义DP点默认从1开始，但有些模板建出来可能是101这种。设备端pty对象里的key必须是控制台实际显示的DP ID。在代码里打一条JSON日志，对照控制台产品定义逐一核对，基本能找到答案。
5.4 设备在线但指令下发没反应
指令收不到，十有八九是Subscription没有成功。用mqttClient.subscribe前，可以先调用mqttClient.connected()确认连接状态。然后检查Topic拼写：很多朋友把property/set拼成了property/set/，多一个斜杠订阅就失效了。还有一个隐蔽问题：ESP8266/32的PubSubClient对Topic长度有限制，如果设备ID很长导致完整Topic超过128字节，需要手动修改库的MQTT_MAX_TOPIC_LENGTH宏。
6. 项目扩展方向
项目跑通后，可以做的扩展还挺多的。
我目前在这个基础上接入了光敏电阻、继电器模块和本地按键，实现了“物理按键+App双控”的方案。按键触发本地GPIO中断，MCU同时上报一条DP点给云端，这样App端状态永远和真实物理状态同步。再往后可以接一个彩屏，把设备状态直接显示在屏幕上。
另外一个非常实用的扩展是OTA升级。ESP32支持通过Arduino库做HTTP OTA，或者用涂鸦自己的OTA通道（如果不想维护自己的升级服务器）。联网设备没有OTA能力等于半残，部署到现场后再想改代码就只能拆设备了，这个一定要提前考虑。
如果你正好有Micro-ROS相关需求，ESP32完全可以在跑着涂鸦Link的同时再开一个UART口接ROS2节点，相当于把涂鸦云当作ROS2设备的远程监控通道。这块水比较深，建议先把基础的MQTT通道跑通再玩。
最后分享一个小技巧
涂鸦Link平台的在线调试功能特别好用。在控制台的“设备调试”页面里，既能模拟设备上报数据，也能给设备下发指令，数据流转的过程都会记录下来。我每次改完代码，都会先去控制台手动下发一次指令，确认设备端串口日志里有响应，再关掉本地调试去连App。这个习惯帮我省下了大量和平台侧扯皮的时间。
接入IoT平台这件事，本不该变成劝退新手的天堑。Tuyalink把这层门槛压到了“看得懂MQTT就能玩”的程度，配上ESP32的性价比，确实是做联网硬件原型验证的一把好手。照着这篇文章把第一盏灯点亮，后面屏幕、传感器、语音控制，扩展起来都只是水到渠成的事。
本文还有配套的精品资源，点击获取
