佐维云 - 物联网控制台

佐维云物联网控制台

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 Key)** 机制。该私钥可在控制台顶部查看。

MQTT 设备： 在连接 Broker 时，必须将 Username 字段设置为专属私钥，Password留空。
TCP 设备： 建立连接后，设备第一包必须发送校验字符：secret=您的私钥&topic=您的主题名

二、核心命名规则

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

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

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

四、实际主题命名示例

💡 推荐格式：位置/功能 + 设备类型码。

001插座： chazuo001、kitchen001、bedroom001
002灯泡： led002、table_light002、ceiling002

五、命名注意事项

⚠️ 字符限制：主题名称只能包含英文字母、数字和下划线（不支持中文、空格）。
⚠️ 隔离机制：同名的 MQTT 主题和 TCP 主题互不干扰，相互独立。

六、小爱同学（米家）接入与语音控制

💡 平台集成说明：
佐维云平台已全面集成小爱同学（米家）智能控制功能规范。设备创建后，可轻松实现语音控制智能设备。
在米家App -> 我的 -> 其他平台设备 -> 点击添加 -> 找到"巴法"，输入账号即可自动同步支持类型的设备。

🔌 1. 插座设备 (001)

打开时下发消息：on
关闭时下发消息：off

💡 2. 灯泡设备 (002)

消息格式：on#亮度值#rgb值或色温 (亮度范围1-100，rgb值为10进制数)

亮度调节：on#80 (设置为80%)
颜色设置：on#100#16711680 (设置为红色)

💨 3. 风扇设备 (003)

一档 / 二档：on#1 / on#2
一档并打开摇头：on#1#1

🌡️ 4. 传感器设备 (004)

数据格式为：#温度#湿度#开关#

仅上报温度：#21
上报温湿度：#21#45

❄️ 5. 空调设备 (005)

消息格式：开关#模式#温度#风速#左右扫风#上下扫风

模式代码：1(自动) 2(制冷) 3(制热) 4(送风) 5(除湿) 6(睡眠) 7(节能)
示例：on#3#20 (打开，辅热模式，20度)

🔘 6. 开关设备 (006)

打开 / 关闭：on / off

🪟 7. 窗帘设备 (009)

打开百分之80：on#80
暂停：pause

七、 MQTT 设备 C 语言接入示例 (基于 STM32 + Keil)

适用于 STM32 系列微控制器（配合 ESP8266/4G 模块的 AT 指令或轻量级 MQTT 库）。核心在于组装 MQTT 连接报文时传入对应的私钥进行鉴权。

#include "stm32f10x.h"
#include "mqtt_client.h"  // 替换为您工程中的 MQTT 库头文件
#include "usart.h"
#include <stdio.h>
#include <string.h>

/* --- 替换为您的平台专属配置 --- */
#define MQTT_SERVER  "156.238.235.229"
#define MQTT_PORT    1883
#define SECRET_KEY   "你的24位专属私钥"  // MQTT 鉴权的 Username
#define TOPIC_NAME   "led002"           // 控制台中创建的主题名称

// MQTT 初始化与鉴权连接函数
void STM32_MQTT_Init(void) {
    MQTT_Client_TypeDef mqtt_client;
    
    // 1. 基础配置：设定服务器 IP 和端口
    mqtt_client.ServerIP = MQTT_SERVER;
    mqtt_client.ServerPort = MQTT_PORT;
    
    // 2. 【核心鉴权】ClientID = 设备名, Username = 私钥, Password = 空
    mqtt_client.ClientID = TOPIC_NAME;
    mqtt_client.Username = SECRET_KEY;
    mqtt_client.Password = "";
    
    // 3. 发起连接并订阅主题
    printf("正在连接佐维云 MQTT 服务器...\r\n");
    if (MQTT_Connect(&mqtt_client) == SUCCESS) {
        printf("MQTT 鉴权成功，连接建立!\r\n");
        MQTT_Subscribe(TOPIC_NAME, 0); // 订阅本设备的控制主题
    } else {
        printf("MQTT 连接失败，请检查网络和全局私钥...\r\n");
    }
}

// MQTT 消息接收中断/回调处理
void MQTT_Receive_Callback(char* topic, uint8_t* payload, uint16_t length) {
    printf("收到云端控制台指令, 主题: %s\r\n", topic);
    
    // 解析指令并控制单片机外设 (例如：点亮 PC13 LED)
    if (strncmp((char*)payload, "on", 2) == 0) {
        GPIO_SetBits(GPIOC, GPIO_Pin_13);
        printf("执行动作：开灯\r\n");
    } else if (strncmp((char*)payload, "off", 3) == 0) {
        GPIO_ResetBits(GPIOC, GPIO_Pin_13);
        printf("执行动作：关灯\r\n");
    }
}

int main(void) {
    SystemInit();
    USART_Config();
    Network_Module_Init(); // 硬件级初始化: 如复位 W5500 或配置 ESP8266 进透传
    
    STM32_MQTT_Init();
    
    while(1) {
        MQTT_Poll(); // 维持心跳并循环接收解析来自云端的数据
    }
}

八、 TCP 设备 C 语言接入示例 (基于 STM32 + Keil)

TCP 接入更为底层和轻量，适用于裸机 TCP Socket 连接。必须在连接成功后的第一包数据中拼接 secret 以完成身份鉴权。

#include "stm32f10x.h"
#include "tcp_client.h"  // 替换为您工程中的 TCP 网络通信头文件
#include "usart.h"
#include <string.h>
#include <stdio.h>

/* --- 替换为您的平台专属配置 --- */
#define TCP_SERVER   "156.238.235.229"
#define TCP_PORT     8080
#define SECRET_KEY   "你的24位专属私钥"
#define TOPIC_NAME   "led002"

void STM32_TCP_Init(void) {
    char auth_buffer[128];
    
    printf("正在连接佐维云 TCP 服务器...\r\n");
    
    // 1. 建立 TCP Socket 长连接 (依赖具体的网络底层硬件如 W5500)
    if (TCP_Connect(TCP_SERVER, TCP_PORT) == SUCCESS) {
        
        // 2. 【核心鉴权】拼接私钥与主题名称的心跳包字符串格式
        sprintf(auth_buffer, "secret=%s&topic=%s&msg=device_online\n", SECRET_KEY, TOPIC_NAME);
        
        // 3. 连接成功后立即发送第一包鉴权数据给云平台
        TCP_Send((uint8_t*)auth_buffer, strlen(auth_buffer));
        
        printf("TCP 连接成功且已发送鉴权包!\r\n");
    } else {
        printf("TCP 连接失败...\r\n");
    }
}

// TCP 数据轮询与处理任务
void TCP_Receive_Task(void) {
    uint8_t recv_buf[256];
    uint16_t len;
    
    // 轮询读取云端下发的 Socket 数据
    if (TCP_Read(recv_buf, &len) == SUCCESS) {
        recv_buf[len] = '\0'; // 封尾打印
        printf("收到来自云端的数据: %s\r\n", recv_buf);
        
        // 可在此处添加设备控制逻辑并向上级回复应答 (ACK)
        // char ack_buffer[128];
        // sprintf(ack_buffer, "secret=%s&topic=%s&msg=Action_Done\n", SECRET_KEY, TOPIC_NAME);
        // TCP_Send((uint8_t*)ack_buffer, strlen(ack_buffer));
    }
}

int main(void) {
    SystemInit();
    USART_Config();
    Network_Module_Init();
    
    STM32_TCP_Init();
    
    while(1) {
        TCP_Receive_Task(); // 死循环处理云平台下发的 TCP 报文
    }
}