佐维云 - 物联网控制台

ID: {{ item.id }}

订阅端：{{ item.status.sub ? '在线' : '离线' }} 发布端：{{ item.status.pub ? '在线' : '离线' }}

最新上报/下发消息{{ item.last_time }}

OTA

ID: {{ item.id }}

TCP 长连接：{{ item.status.sub ? '设备在线' : '设备离线' }}

最新上报/下发消息{{ item.last_time }}

OTA

设备接入规范与指南

一、私钥鉴权机制 (Secret Authentication)

为了保障设备的绝对安全，佐维云全面启用了设备专属私钥 (Secret Key) 机制。该私钥可在控制台顶部查看。

MQTT 设备接入： 在连接 Broker 时，必须将 Username 字段设置为您的全局专属私钥。
TCP 设备接入： 建立连接后，设备必须发送身份校验字符串，格式为：secret=您的私钥&topic=您的主题名&msg=消息内容

二、核心命名规则

在佐维云平台中，为了实现高度的自动化管理与终端适配，设备类型主要由主题名称的后三位数字决定。这种设计让平台能够自动识别硬件设备类型。

主题名称格式：[自定义名称前缀][设备类型码]

自定义名称前缀：可用于标识房间、用途、位置等。
设备类型码：必须为严格的三位数字，代表具体的硬件类型。

三、支持的设备类型及标识码

四、实际主题命名示例

🔌 插座设备（001）

chazuo001、socket001、power001、outlet001
kitchen001、bedroom001、living001

💡 灯泡设备（002）

led002、light002、bulb002、lamp002
deng002、table_light002、ceiling002

五、命名最佳实践与注意事项

✅ 位置 + 类型码：kitchen001 (厨房插座)、bedroom002 (卧室灯)
✅ 功能 + 类型码：main_light002 (主灯)、temp_sensor004 (温度传感器)
⚠️ 字符限制：主题名称只能包含英文字母、数字和下划线（不支持中文、空格及特殊符号）。
⚠️ 隔离机制：同名的 MQTT 主题和 TCP 主题互不干扰，相互独立。

六、设备接入代码示例

以下提供 Python 版本的极简接入代码示例（模拟单片机逻辑），便于开发者快速验证与联调。对于 ESP8266/ESP32 等硬件，逻辑完全一致。

1. MQTT 接入示例 (依赖 paho-mqtt)

核心要点：将 Username 严格设置为您的全局专属私钥，Password 留空。

import paho.mqtt.client as mqtt

# ================= 佐维云配置参数 =================
HOST = "156.238.235.229"
PORT = 1883
CLIENT_ID = "device_led002"
SECRET_KEY = "替换为控制台顶部的专属私钥"
TOPIC = "led002"

def on_connect(client, userdata, flags, rc):
    if rc == 0:
        print("✅ 成功连接到佐维云 MQTT Broker")
        client.subscribe(TOPIC)  # 订阅指令下发主题
    else:
        print(f"❌ 连接失败，状态码: {rc} (请检查私钥是否正确)")

def on_message(client, userdata, msg):
    print(f"📥 收到云端指令: {msg.payload.decode('utf-8')}")

# 1. 初始化客户端
client = mqtt.Client(CLIENT_ID)
# 2. 【核心鉴权配置】用户名必须填私钥，密码为空
client.username_pw_set(SECRET_KEY, "") 

client.on_connect = on_connect
client.on_message = on_message

# 3. 发起连接并上报上线消息
client.connect(HOST, PORT, 60)
client.publish(TOPIC, "hello, device is online!")
client.loop_forever() # 保持心跳长连接

2. TCP 接入示例 (原生 Socket 通信)

核心要点：建立连接后，第一条数据包必须携带 secret(私钥) 和 topic(主题名) 参数。

import socket
import threading

# ================= 佐维云配置参数 =================
HOST = "156.238.235.229"
PORT = 8080
SECRET_KEY = "替换为控制台顶部的专属私钥"
TOPIC = "led002"

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect((HOST, PORT))
print("✅ TCP Socket 连接已建立")

# 1. 【核心鉴权】发送握手校验数据包
# 格式要求：secret=私钥&topic=主题名&msg=上报消息内容
auth_msg = f"secret={SECRET_KEY}&topic={TOPIC}&msg=hello"
s.sendall(auth_msg.encode('utf-8'))

# 2. 独立线程循环接收云端下发的指令
def receive_cmd():
    while True:
        try:
            data = s.recv(1024)
            if data:
                print(f"📥 收到云端指令: {data.decode('utf-8').strip()}")
        except:
            print("⚠️ 连接已断开")
            break

threading.Thread(target=receive_cmd, daemon=True).start()

# 阻塞主线程以保持程序运行
while True:
    pass

设备接入规范与指南

一、 私钥鉴权机制 (Secret Authentication)

二、 核心命名规则

三、 支持的设备类型及标识码

四、 实际主题命名示例