ESP32 设备接入指南与配网助手

通用固件

认证与 Wi‑Fi 一次写入

核验账户、识别设备并完成安全初始化，最后由设备一次性保存认证信息和 Wi‑Fi。

01账户资格
02连接设备
03设备初始化
04Wi‑Fi 信息
05写入并联网

先确认账户认证资格

只有试用、月度、年度或永久会员可以发起设备认证和安全初始化。

当前账户未登录账户等级免费会员

前往用户登录

开始之前

四步完成一次接入

01 - 04

创建项目和设备
在 WorldIoT App 中创建目标项目和设备，认证 Token 只放在设备安全配置中。
固定产品身份
使用稳定的 TMPL_... 产品模板 ID，并定义显示名称和固件版本。
约定虚拟引脚
先配置一个只读遥测 Pin，确认实时值和历史数据正常，再增加控制回调。
验证设备状态
连接后在设备详情查看模板 ID、名称、固件版本和最后数据时间。

可运行起点

最小 Arduino / ESP32 示例

#define BLYNK_TEMPLATE_ID "TMPL_WORLDIOT_MPPT_ESP32"
#define BLYNK_TEMPLATE_NAME "WorldIoT MPPT ESP32"
#define BLYNK_FIRMWARE_VERSION "1.0.0"

#include <WiFi.h>
#include <BlynkSimpleEsp32.h>

char auth[] = "DEVICE_TOKEN_FROM_SECURE_PROVISIONING";
char ssid[] = "WIFI_SSID";
char pass[] = "WIFI_PASSWORD";
BlynkTimer timer;

void publishReading() {
  Blynk.virtualWrite(V0, readSensor());
}

BLYNK_WRITE(V10) {
  setOutputEnabled(param.asInt() != 0);
}

void setup() {
  Serial.begin(115200);
  Blynk.begin(auth, ssid, pass, "worldiot.top", 8080);
  timer.setInterval(2000L, publishReading);
}

void loop() {
  Blynk.run();
  timer.run();
}

产品模板芯片目标产品文档

#pragma once

#define BLYNK_TEMPLATE_ID "TMPL_WORLDIOT_MPPT_ESP32"
#define BLYNK_TEMPLATE_NAME "WorldIoT MPPT ESP32"
#define BLYNK_FIRMWARE_VERSION "1.0.0" // Change for every firmware release.
// Target: esp32
// WORLDIOT_AUTH_TOKEN_FROM_PROVISIONING
// Provisioning supplies the credential at runtime. Do not hard-code it here.

// V1: 输入功率 (device-to-cloud, W)
// V2: 电池电量 (device-to-cloud, %)
// V3: 输入电压 (device-to-cloud, V)
// V4: 输入电流 (device-to-cloud, A)
// V5: 输出电压 (device-to-cloud, V)
// V6: 输出电流 (device-to-cloud, A)
// V7: 设备温度 (device-to-cloud, C)
// V15: 充电目标电压 (bidirectional, V)
// V16: 充电电流限制 (bidirectional, A)
// V22: 输出功率 (device-to-cloud, W)
// V23: 累计电能 (device-to-cloud, kWh)
// V24: 当日电能 (device-to-cloud, Wh)
// V27: Wi-Fi 信号强度 (device-to-cloud, dBm)
// V29: 屏幕亮度 (bidirectional, %)
// V30: 屏幕唤醒状态 (bidirectional, 布尔值)
// V50: Buck 使能 (bidirectional, 布尔值)
// V52: MPP 算法 (bidirectional, 模式)
// V53: 风扇覆盖 (bidirectional, 布尔值)
// V54: 负载 1 (bidirectional, 布尔值)
// V58: 输出模式 (bidirectional, 模式)
// V59: 负载 2 (bidirectional, 布尔值)
// V60: 负载 3 (bidirectional, 布尔值)

虚拟引脚	名称	方向	单位
V1	输入功率	设备上报	W
V2	电池电量	设备上报	%
V3	输入电压	设备上报	V
V4	输入电流	设备上报	A
V5	输出电压	设备上报	V
V6	输出电流	设备上报	A
V7	设备温度	设备上报	C
V15	充电目标电压	双向同步	V
V16	充电电流限制	双向同步	A
V22	输出功率	设备上报	W
V23	累计电能	设备上报	kWh
V24	当日电能	设备上报	Wh
V27	Wi-Fi 信号强度	设备上报	dBm
V29	屏幕亮度	双向同步	%
V30	屏幕唤醒状态	双向同步	布尔值
V50	Buck 使能	双向同步	布尔值
V52	MPP 算法	双向同步	模式
V53	风扇覆盖	双向同步	布尔值
V54	负载 1	双向同步	布尔值
V58	输出模式	双向同步	模式
V59	负载 2	双向同步	布尔值
V60	负载 3	双向同步	布尔值

服务端约定

设备上报什么，服务器保存什么

产品身份

tmpl 是稳定产品模板 ID，tnm 是显示名称，fw 是固件版本。名称不是 Token，也不能用于设备鉴权。

兼容策略

旧固件只发送 tmpl 仍然可以连接；没有新的 tnm 时，服务器不会覆盖已有产品名称。

项目数据

虚拟引脚、图表、仪表盘和 OTA 通道属于项目配置。模板 ID 不会自动覆盖用户已有项目。

数据节奏

使用定时器发送普通遥测，状态变化再即时发送；始终在主循环运行 Blynk.run()，不要阻塞网络处理。

快速定位

常见问题

能连接但名称为空

确认编译时定义了 BLYNK_TEMPLATE_NAME，并使用包含 tnm 支持的库版本。旧固件只上报 tmpl 时仍兼容，但服务器不会猜测名称。

Invalid auth token

Token 必须属于当前项目中的当前设备。模板 ID、模板名称和产品名称都不能替代 Token。

实时值有了，图表为空

确认项目已将该 Pin 配置为历史数据，并且设备持续上报有效值。一次 virtualWrite 不等于已经形成历史曲线。

控制回调没有反应

确认存在对应的 BLYNK_WRITE(Vx)，回调不做耗时阻塞，并对范围和保护状态进行校验。功率级控制默认应安全关闭。

完整字段、示例和安全要求见 Warm-rain-Blynk/docs/WORLDIOT_CUSTOM_DEVICE.md。