MQTT智能插座GSPM1B2 · 开发者实战指南

GemeOpen GSPM1B2 智能插座 · 开发者实战指南

面向软件开发者、集成商项目经理、传统电子设备厂的深度应用手册

从「为什么值得用」到「怎么落地赚钱」------涵盖协议、写代码、调试、安装施工、与传统设备对接、20+ 应用场景、成本收益与运维体系。

第 1 章开篇：一台小插座，为什么值得开发者认真看
第 2 章认识设备：GSPM1B2 的硬件与能力边界
第 3 章协议全景：MQTT / TCP / 内网 HTTP 与指令哲学
第 4 章快速上手：15 分钟跑通第一条指令（三语言）
第 5 章数据采集：把电变成数据
第 6 章调试手册：从"设备没反应"到"一眼定位"
第 7 章二次开发进阶：把它变成你自己的产品
第 8 章云平台对接：公有云与私有化部署
第 9 章集成实战：让插座融入现有系统
第 10 章定时与自动化：让插座自己干活
第 11 章安装与施工：电气是底线
第 12 章与传统电子用电设备对接
第 13 章应用场景 20+ 例（上）：编号 1~11
第 14 章应用场景 20+ 例（下）：编号 12~24
第 15 章省钱账：一台插座帮你省了什么
第 16 章增效：自动化管理带来的收益
第 17 章增收：把插座变成商业模式
第 18 章项目管理：集成商视角的落地方法论
第 19 章运维体系：让系统长期稳定
第 20 章附录
附录 A · 设备规格与指令基准

第一部分基础认知与快速上手

本篇是《GSPM1B2 智能插座开发者指南》的第 1 部分，覆盖第 1~4 章。

这一部分回答三个最朴素的问题：它是什么？它凭什么值得你认真看？我有多快能跑通第一条指令？

文中所有设备参数、指令名、字段名、取值，均严格以《00-基准事实》为准；凡涉及"怎么用、在哪用、值多少"的判断，属于本篇的经验补充，供参考。

第 1 章开篇：一台小插座，为什么值得开发者认真看

点题： 插座是最不起眼的电器配件，但 GSPM1B2 把"通断电"和"用电数据"变成了一段可以编程的接口------这才是它和楼下五金店里的插排的根本区别。

1.1 从三个真实痛点说起

在讲任何一项技术参数之前，先看三个"如果当时有一台 GSPM1B2 就好了"的场景。这三个场景全部来自工程与运维现场，也恰好对应了这类设备最核心的价值。

痛点一：实验室设备忘关电，没人敢负责

某高校电子实验室有一台价值不菲的功率老化台，学生做完实验常常忘记关机，设备整夜空转，既浪费电又有火灾隐患。值班老师不可能天天巡楼。解决方案很朴素：把老化台插到 GSPM1B2 上，写一段脚本，每天晚上 22:00 自动断电，第二天早上 8:00 自动通电；同时用一条 info-statistic 查询，把当天的 power（功率）和 energy（累计电量）记进表格。省下了什么？ 省下了"人盯人"的巡检人力，也把事故风险和电费都压下去了。

痛点二：机房设备需要远程重启，但人不在现场

托管机房里一台 VPN 网关偶尔会假死，需要断电重启才能恢复。但机房在天南海北，运维工程师打车过去一趟至少半天。把网关的电源适配器插到 GSPM1B2 上之后，工程师在办公室点一下网页按钮，服务端发一条 controller-event（key:0 断电），等 5 秒再发 key:1 通电，设备就"硬重启"了。这相当于给任何一台非智能设备加装了一个远程重启按钮，而成本只是几十块钱的插座加半小时的开发。

痛点三：无人值守站点要定时断电，连网都成问题

野外的气象监测站、基站、广告灯箱，往往无人值守，只需要"白天通电、夜里断电"。这类站点通常只有一个 2.4GHz WiFi 热点可用，没有公网 IP，也进不了机房。GSPM1B2 支持定时任务 和倒计时任务 ，可以直接在设备内部保存多组定时任务------即使服务端一时联系不上，设备也能按本地任务表准点执行。关键点是"自主可控"：任务逻辑跑在设备上，不依赖云端平台的脸色。

这三个场景指向同一个结论：当"插座"能接收指令、能上报数据、能把逻辑写进设备里，它就从"电器"变成了"开发板"。

1.2 「能二次开发的智能插座」和「消费级智能插座」差在哪

市面上几十块钱的智能插座很多，为什么要单独为 GSPM1B2 写一份开发文档？因为它和消费级产品的设计目标根本不同。

对比维度	消费级智能插座	GSPM1B2（可二次开发）
服务端	绑定厂家云（App 只能连官方云）	默认连厂家 MQTT 测试服务器，可改自建服务器
通信协议	厂家私有协议，封闭	MQTT / TCP Client / 内网 HTTP，协议透明
数据归属	数据在厂家云，导出受限	数据直发你的服务器，归属你自己
二次开发	一般无开放接口	有完整指令表，可编程、可集成
部署方式	只能公有云	支持私有化部署，内网可用
平台兼容	只能用官方 App	可接入阿里云、华为云、百度云、腾讯云等物联网平台

一句话总结差异：消费级插座卖的是"一个能远程开关的插座"，GSPM1B2 卖的是"一段你能自己掌控的电源控制接口"。

这里最容易被忽视、但对集成商而言最值钱的三个字是------私有化 。很多工厂、医院、政府单位的数据不允许出厂区，消费级插座的数据必须经过厂家云，这就直接把方案否决了。而 GSPM1B2 可以通过 setting-mqtt 或 setting-tcp 把服务器地址改成内网地址，数据全程不出内网，天然满足合规要求。

需要提前说清的一点：改完服务器配置后，设备需要断电重启，或发一条 controller-restart 才会生效------这是很多人第一次配置时"改了没反应"的根源，后面第 4 章会再强调。

1.3 这份文档写给谁，怎么读

这份文档假设了三类读者，他们对同一个设备的关注点完全不同：

软件开发者 ：你要的是协议、字段、代码。请重点关注第 3 章（协议与指令）、第 4 章（三语言最小示例）以及第 2 部分的数据处理章节。你的工作可以概括为：订阅上行主题、解析 JSON、在正确的主题上发指令。
集成商项目经理：你要的是成本、周期、验收标准、风险。请重点关注第 2 章（能力边界，决定你能不能接这个活）、第 1.2 节（私有化能力，决定能不能过合规），以及第 2 部分的落库与系统集成章节。
传统电子设备厂：你要的是硬件与电气。请重点关注第 2 章（ESP32 主控、过零检测、16A 宏发继电器、10A/2500W 负载边界），这些决定了一台设备能带什么负载、不能带什么负载。

怎么读这份文档：

想快速上手 → 直接跳到第 4 章，照着 4.1→4.4 走一遍，15 分钟就能收到第一条数据。
想评估能不能用 → 先读第 2 章，把"能做什么、不能做什么"划清楚，再决定选型。
想搞懂协议细节 → 精读第 3 章，尤其是 3.2 节那个"反直觉"的坑。

本章要点：

智能插座的价值不在"插座"，而在"可编程的通断电 + 可采集的用电数据"。
GSPM1B2 与消费级插座的核心差异是协议开放、数据自主、支持私有化部署。
三类读者关注点不同，可按 1.3 的路径选择阅读顺序。

第 2 章认识设备：GSPM1B2 的硬件与能力边界

点题： 写代码之前先认清硬件------它决定了你能带多大的负载、数据有多准、哪些场景它压根不该上场。

2.1 规格参数逐条解读

先看一张"体检表"，然后逐条翻译成人话。

项	值	一句话解读
主控芯片	乐鑫 ESP32（内置过零检测）	自带 WiFi，且能做精准计量与继电器过零投切
输入电压	AC 85~265V（50/60Hz）	宽电压，全球市电基本通吃
最大负载电流	10A	硬边界，超过就危险
额定功率	MAX 2500W	10A × 250V 的近似上限
继电器	16A 宏发继电器 HF32FV-16（磁保持类机械触点）	触点余量足、能耗低，是"真能带负载"的开关
待机功率	< 3W	自身几乎不耗电
通讯	2.4GHz WiFi	注意：只支持 2.4G，不支持 5G
尺寸	49mm × 59mm × 28mm	小巧，直接插在墙面插座上
工作温度	-5℃ ~ +40℃	常规室内环境
插孔	转换器（输出三孔/两孔）	插座插在原有墙插上，再引出用电口

逐条深入：

① ESP32 意味着什么。 ESP32 是乐鑫的经典物联网芯片，自带 WiFi 与强大的运算能力。对开发者最大的意义是：它让"设备端可编程"成为可能------定时任务、数据采集、协议封装全部在这颗芯片上跑，你面对的不是一块黑盒，而是一个有开放指令集的终端。

② 过零检测意味着什么。 市电是 50Hz 正弦波，每 20ms 一个周期，每秒钟两次经过 0V。ESP32 内置过零检测，等于设备有一把"以市电节拍为准的尺子"。它带来两个好处：一是计量更准 （采样有稳定的时间基准）；二是继电器过零投切 ------在电压接近 0 的瞬间吸合或断开，把合闸浪涌电流压到最低，保护负载也保护继电器。这就是为什么 16A 的宏发继电器 HF32FV-16 能长期可靠工作。开发者须知：别高频连发通断电指令，设备的过零策略需要时间配合。

③ 16A 继电器 + 10A 额定负载。 继电器触点规格 16A，而整机额定负载电流 10A------触点留了余量 ，这是工程上的稳健设计。但请记住：10A / 2500W 是整机的硬上限，不是"继电器扛得住就行"。整机的线径、端子、散热都按 10A 设计，长期超载会发热。

④ 2.4GHz WiFi 这个坑。 很多开发者第一次配网失败，就是因为路由器把 2.4G 和 5G 合并成了一个 SSID，而设备只认 2.4G。配网时请确认路由器 2.4GHz 频段可用。

⑤ 信号强度怎么读。 设备上报的 signal 字段是信号强度，单位 dBm，数值越接近 0 越好：0 ~ -50 最好，-50 ~ -70 较好，-70 ~ -80 一般，-80 ~ -100 较差 。如果设备装在金属配电箱里或离路由器太远，signal 会明显变差，表现为指令偶尔收不到、上报断续。工程上建议把 signal 低于 -80 视为"需要整改网络"的告警线。

⑥ 待机功率与尺寸。 待机功率小于 3W，自身几乎不耗电，长期挂机不用担心自己变成"耗电大户"；49mm × 59mm × 28mm 的小体积，插在墙面插座上基本不占相邻插位，适合密集部署。

2.2 它能做什么、不能做什么

能做的（能力清单）：

通断电控制 ：继电器开合，用 controller-event 指令，key:1 通电 / key:0 断电。
用电采集 ：上报 voltage（电压 V）、current（电流 A）、power（功率 W）、energy（累计电量 kW·h）。
过零精准计量与过零投切：见上文。
定时任务（多组）+ 倒计时任务：设备本地存任务，脱网也能执行。
上电默认状态 ：setting-on-state，可选记忆 / 关闭 / 开启。
按键锁与配网锁 ：setting-key-lock、setting-wifi-lock，防止误操作。
多协议通信：MQTT / TCP Client / 内网 HTTP。
接入主流云平台与私有化部署。

不能做的（边界，必须牢记）：

① 负载边界：不超过 10A / 2500W。 这是铁律。空调柜机、大功率电暖器、电焊机这类设备动辄 16A 以上，直接超载。

② 阻性负载 vs 感性负载。 这是最容易被忽视的技术点。

阻性负载 （白炽灯、电热锅、电水壶、电暖器）：电流与电压同步，启动无冲击，power 数值接近真实有功功率，最适合本设备。
感性负载 （空调、冰箱、洗衣机、水泵、电机）：启动瞬间会有数倍于额定的浪涌电流 ，且运行时功率因数低。虽然设备有过零投切来减浪涌，但长期带大功率电机仍有风险 ，且 power 是视在功率、估电费会偏高。

③ 不适合的场景：

需要精确电费结算 的场合------power 是视在功率（U×I 估算），不是计量级电表，不能用于收费。
需要三相电 或超过 2500W 的工业设备。
需要高频开关（如秒级反复通断）的场景------过零投切与继电器寿命都受不了。
室外 / 潮湿 / 高温环境------工作温度仅 -5℃ ~ +40℃，且未标称防水。

2.3 选型对照：什么时候用智能插座、什么时候用通断器、什么时候用智能断路器

这三样东西经常被混为一谈，其实定位完全不同。用一句话区分：智能插座是"带数据、可移动"的终端；通断器是"装在配电箱里的开关模块"；智能断路器是"保护 + 控制"的安全器件。

维度	智能插座（GSPM1B2）	智能通断器	智能断路器
安装位置	墙面插座（即插即用）	配电箱导轨/暗盒	配电箱导轨
是否带用电计量	带（V/A/W/kWh）	通常不带或简单	通常带更专业计量
负载能力	10A / 2500W	视型号，多数 16~63A	视型号，可达 63A+
过载/短路保护	无（靠上游空开）	一般无	有（核心技术）
适合场景	单台设备、可移动、要数据	一盏灯/一路回路的开关	大功率回路、要保护
部署难度	最低，插上即用	中，需接线	高，需专业电工

选型决策（编号步骤）：

只想控制一台具体设备 ，还要看它的用电数据 → 用 GSPM1B2 智能插座。
要控制一整条照明回路 / 多个插座 ，装在暗盒里 → 用智能通断器。
控制的是大功率负载（>2500W） ，或需要过载短路保护 → 用智能断路器，且必须由专业电工施工。
要精确收费计量 → 任何一款"插座"都不合适，应选专业电能表。
三者可以组合：上游智能断路器做保护，下游智能插座做单机控制与数据采集。

本章要点：

硬边界：10A / 2500W，宽电压 AC 85~265V，仅 2.4GHz WiFi。
ESP32 内置过零检测 ，既保计量精度又保继电器过零投切；勿高频连发指令。
擅长阻性负载 ，慎用感性负载 ，不可用于收费级计量。
插座 / 通断器 / 断路器定位不同，按 2.3 的编号步骤选型。

第 3 章协议全景：MQTT / TCP / 内网 HTTP 与指令哲学

点题： 设备对外只有一种"语言"------JSON 指令，但它有三条"通道"（MQTT / TCP / 内网 HTTP），选对通道比写对代码更重要。

3.1 三种通信方式怎么选

GSPM1B2 支持三种通信方式，它们不是"新旧替代"关系，而是"各管一段路"。

通信方式	本质	优点	缺点	适用场景
MQTT	发布/订阅消息总线	省流量、天然支持海量设备、支持断线重连	需自建/接入 Broker；主题概念易错	云平台接入、多设备集中管理、私有化部署
TCP Client	设备主动连你的服务器	简单直接、可长连接推流	服务端要自己维护连接池与协议解析	内网专线、自建轻量服务、点对点控制
内网 HTTP	设备作为服务端被访问	调试最直观、用浏览器就能测	一般仅限内网、不适合大规模	局域网调试、现场排障、简单集成

怎么选（编号步骤）：

要做云平台接入 或多设备统一管理 → 选 MQTT。这是本设备的主力方式，文档与示例都围绕它。
服务端就在同一个内网 、想省掉 Broker → 选 TCP Client 。用 setting-tcp 配置 server、port、protocol:"tcp"。
只想快速验证设备通不通 、在现场用手机/电脑试一下 → 用内网 HTTP 或 MQTT 测试服务器。
无论选哪种，改完配置都要断电重启或发 controller-restart 才生效。

关键事实：设备出厂默认连的是 GemeOpen 厂家 MQTT 测试服务器 mqtt.smart-bird.cn:1883。 这意味着你拿到设备、配好网，不改任何配置，它就会往这个测试服务器上报------非常适合"先跑通再自建"的渐进式接入。

3.2 主题与 publish/subcribe 的反直觉（重点，避免踩坑）

这是全文档最容易让开发者翻车的一节。 原因有两个：一是 MQTT 的"发布/订阅"本来就是从设备视角 描述的动作；二是基准事实里设备返回的字段名 publish / subcribe（注意是设备端的拼写）描述的是设备自己要做什么 ，而不是你该做什么。

先建立正确的心理模型：MQTT 里没有"请求方"和"响应方"，只有"发布者"和"订阅者"。谁订阅了什么主题，就能收到发到该主题的消息。

设备通过 info-protocol 指令（响应字段含 server, port, publish, subcribe, clientId, username, protocol）告诉你它的主题配置。务必按下面的方式理解：

设备返回的字段	含义	你要做什么	方向
`publish`	设备发布数据的主题	服务端要订阅它	收上行（设备 → 你）
`subcribe`	设备订阅的主题	服务端要向它发布	发下行（你 → 设备）
`server` / `port`	Broker 地址与端口	用它们连接 Broker	---
`username` / `clientId`	连接凭据	连接时填入（如有）	---

一句话记忆口诀：

设备发的，你去订；设备订的，你去发。

设备 publish 的主题 = 你订阅的主题（接收设备上报的 info-statistic、device-timer-task 等）。
设备 subcribe 的主题 = 你发布的主题（发送 controller-event、info-statistic 查询等指令）。

两个高频踩坑点：

把两个主题搞反。 一旦搞反，你发的指令设备收不到，设备的上报你也收不到，表现为"发了没反应、什么都没收到"。排查时第一件事就是核对方向。
拼写细节。 设备返回的字段确实是 subcribe（不是 subscribe），解析 JSON 时按原样取字段名，不要自作主张改成标准拼写，否则取不到值。

把整个交互画成一张时序图，方向一目了然：

复制代码

       你的服务端                                 GSPM1B2 设备
   （订阅 publish 主题 / 发布 subcribe 主题）      （发布 publish / 订阅 subcribe）

        ① 订阅 PUB_TOPIC  ◀─────────────── ② 设备向 PUB_TOPIC 发布数据
                                                 （如 info-statistic、device-timer-task）

        ③ 向 SUB_TOPIC 发布指令 ──────────▶ ④ 设备订阅 SUB_TOPIC，收到指令
             （如 controller-event）             并执行

        ⑤ 设备把执行结果/数据发回 PUB_TOPIC ─▶ 你的服务端在此前已订阅，收到响应

看这张图就能明白：你做的两件事永远是"订阅设备发布的那条、向设备订阅的那条发布" 。很多新手以为"我发指令应该发到设备 publish 的主题"，恰恰反了。记住 publish / subcribe 描述的是设备的动作，不是你的动作，方向就不会错。

3.3 指令全表速览与 messageId「请求---响应」模型

GSPM1B2 的指令哲学很统一：下行指令以指令名（commandName）+ 业务字段 + type 组织成 JSON；设备处理完后，在上行主题回一条携带 messageId 的响应。

指令全表速览（按功能分组）：

功能	指令名	请求关键字段	响应关键字段
通断电	`controller-event`	`key`(0断电/1通电), `type:"event"`	`commandName, key, mac, ip, onState, signal, ssid, version, wifiLock, keyLock, bssid`
设置上报频率	`device-timer-interval`	`timerEnable`(0/1), `timerInterval`(5~86400), `type:"setting"`	`commandName, timerEnable, timerInterval` 等
定时上报（设备主动）	`device-timer-task`	---	`commandName, voltage, current, power, energy, key, mac, source:"auto"`
设备基础信息	`info-all`	`type:"info"`	`code, ip, mac, signal, ssid, version, wifiLock` 等
实时用电信息	`info-statistic`	`type:"statistic"`	`commandName:"info-statistic", voltage, current, power, energy, key, mac`
查询定时任务	`info-timer-task-query`	---	定时任务列表
设置定时任务	`setting-timer-task`	时间/星期/动作	`success`
删除定时任务	`setting-timer-delete`	---	`success`
设置倒计时任务	`setting-timer-countdown`	倒计时秒数/动作	`success`
倒计时上报	`setting-timer-countdown-active`	---	倒计时状态
清除倒计时	`setting-timer-countdown-clear`	---	`success`
累计电量清零	`energy-clear`	---	`success`
重置设备	`controller-reset`	`system:"reset", type:"setting"`	`success, message`
重启设备	`controller-restart`	`system:"restart", type:"setting"`	`success, message`
查询通信协议	`info-protocol`	---	`server, port, publish, subcribe, clientId, username, protocol`
自定义 MQTT	`setting-mqtt`	`server, port, publish, subcribe, clientId, username, password, type:"custom"`	`success`
自定义 TCP	`setting-tcp`	`server, port, protocol:"tcp"`	`success`
设置 WiFi	`setting-wifi-config`	`ssid, password`	`success`
设置 WiFi 配网锁	`setting-wifi-lock`	`wifiLock`(0/1)	`success`
设置按键锁	`setting-key-lock`	`keyLock`(0/1)	`success`
设置上电默认状态	`setting-on-state`	`onState`(0记忆/1关闭/2开启)	`success`

messageId「请求---响应」模型：

MQTT 是异步的：你发出指令后，响应不会在函数返回值里给你，而是稍后从上行主题"飘"回来。那么问题来了------我发了三条指令，怎么知道哪条响应对应哪条请求？

答案就是 messageId ：它是一个业务流水号 ，你在请求里自己填一个值，设备会在响应里原样回显。于是你可以用它做请求与响应的关联。

复制代码

服务端                            设备
  │  publish(subcribe主题)          │
  │  {commandName:"info-statistic", │
  │   messageId:"20250101002"}  ───▶│  处理...
  │                                │
  │  ◀─── {commandName:"info-statistic",
  │         messageId:"20250101002",   ← 原样回显，用于关联
  │         voltage, current, power, energy, key, mac}

使用建议：

每条下行指令都带上唯一的 messageId（例如时间戳 + 序号）。
服务端维护一张"待响应表"，收到响应时用 messageId 匹配，或用它做超时重试。
设备端还会在响应里带上 source 字段区分来源：command（指令响应）/ auto（自动上报）/ button（按键触发）。看到 source:"auto" 就知道这是定时上报，不是你请求的响应。

本章要点：

三种通道：MQTT （主力，云/多设备）、TCP Client （内网/自建）、内网 HTTP（调试）。
出厂默认连 mqtt.smart-bird.cn:1883；改配置后需断电重启或 controller-restart。
黄金口诀：设备发的（publish）你去订，设备订的（subcribe）你去发------切勿搞反。
用 messageId 做请求---响应关联，用 source 区分响应与自动上报。

第 4 章快速上手：15 分钟跑通第一条指令（三语言）

点题： 少废话，多动手------本章目标是让你在 15 分钟内，用真实代码收到第一条电压/电流数据，并成功断电再通电。

4.1 准备：设备上电、配网、获取主题与凭据

前置条件清单：

一部手机（用于配网）、一台能上网的电脑（跑代码）。
一个 2.4GHz 的 WiFi（切记：设备不支持 5GHz）。
安装了 Python 3 的运行环境（本章示例主用 Python）。

操作步骤（编号）：

上电：把 GSPM1B2 插到墙面插座上，观察指示灯。
配网：用设备配套的配网方式（或发 setting-wifi-config，字段 ssid、password）把设备接入你的 2.4GHz WiFi。若担心他人乱配网，可后续用 setting-wifi-lock（wifiLock:1）锁住配网。
确认连接 ：设备出厂默认连 mqtt.smart-bird.cn:1883。若你要用自建服务器，请用 setting-mqtt 配置 server/port/publish/subcribe/clientId/username/password（type:"custom"），然后断电重启或发 controller-restart 生效。
获取主题与凭据 ：发一条 info-protocol 查询，从响应里读出关键字段：
- publish → 你要订阅的主题（收上行）。
- subcribe → 你要发布的主题（发指令）。
- server / port / username / clientId → 连接 Broker 用。
把上面 4 个值填进代码，即可开始。

提醒：info-protocol 本身也是一条需要下发的查询指令，你可以先用厂家测试服务器 + 一个通用 MQTT 客户端工具先连上看一看。

首次接入常见故障速查：

现象	最可能原因	排查动作
发指令设备无任何反应	主题方向搞反 / 发错主题	核对是否向 `subcribe` 主题发布
完全收不到上行	没订阅 `publish` 主题	确认已 `subscribe(PUB_TOPIC)`
连接 Broker 失败	server/port/凭据不对	用 `info-protocol` 重新核对
改了服务器没生效	未重启	断电重启或发 `controller-restart`
配网失败	路由器只有 5GHz 或 2.4/5G 合并	确保 2.4GHz 可用
指令偶尔丢 / 上报断续	信号差	查 `signal`，低于 -80 需改善网络

4.2 Python 最小可运行示例（paho-mqtt）

下面这段代码完成了完整闭环：连接 → 订阅 → 发指令 → 收响应 → 断电/通电。

python 复制代码

import json, time
import paho.mqtt.client as mqtt

# ===== 4.1 步骤 4 拿到的值填在这里 =====
BROKER    = "mqtt.smart-bird.cn"   # info-protocol 的 server
PORT      = 1883                    # info-protocol 的 port
PUB_TOPIC = "设备的publish主题"      # 服务端【订阅】它，收设备上行
SUB_TOPIC = "设备的subcribe主题"     # 服务端【发布】它，给设备下指令
USERNAME  = None                    # 如服务器要求鉴权则填
PASSWORD  = None

def on_connect(client, userdata, flags, rc):
    print("已连接 Broker, rc =", rc)
    client.subscribe(PUB_TOPIC)     # 订阅"设备发布"的主题，收上行
    # 连接后立刻查一次通信协议，核对主题方向
    client.publish(SUB_TOPIC, json.dumps({
        "commandName": "info-protocol",
        "messageId": "req-proto-001",
    }))

def on_message(client, userdata, msg):
    data = json.loads(msg.payload.decode())
    name = data.get("commandName")
    mid  = data.get("messageId")
    src  = data.get("source")
    print(f"[上行] {name}  messageId={mid}  source={src}")

    if name == "info-protocol":
        print("  publish(你订阅):", data.get("publish"),
              " subcribe(你发布):", data.get("subcribe"))

    elif name == "info-statistic":                 # 实时用电响应
        print(f"  电压 {data['voltage']}V 电流 {data['current']}A "
              f"功率 {data['power']}W 电量 {data['energy']}kWh "
              f"状态 key={data['key']}")

    elif name == "controller-event":               # 通断电响应
        print(f"  控制结果 key={data['key']} onState={data.get('onState')} "
              f"signal={data.get('signal')}dBm")

client = mqtt.Client(client_id="srv-demo-01")
if USERNAME:
    client.username_pw_set(USERNAME, PASSWORD)
client.on_connect = on_connect
client.on_message = on_message
client.connect(BROKER, PORT, 60)
client.loop_start()
time.sleep(2)   # 等连接就绪

# ① 查询实时用电（type=statistic）
client.publish(SUB_TOPIC, json.dumps({
    "commandName": "info-statistic",
    "type": "statistic",
    "messageId": "req-stat-001",
}))
time.sleep(2)

# ② 断电（key=0）
client.publish(SUB_TOPIC, json.dumps({
    "commandName": "controller-event",
    "key": 0,                     # 0 断电
    "type": "event",
    "messageId": "req-off-001",
}))
time.sleep(5)

# ③ 通电（key=1）
client.publish(SUB_TOPIC, json.dumps({
    "commandName": "controller-event",
    "key": 1,                     # 1 通电
    "type": "event",
    "messageId": "req-on-001",
}))
time.sleep(3)

client.loop_stop()
client.disconnect()

代码要点说明：

订阅 PUB_TOPIC（设备 publish 的主题）、向 SUB_TOPIC（设备 subcribe 的主题）发布------这就是 3.2 节口诀的落地。
controller-event 必须带 key（0/1）与 type:"event"；响应里回显 key、onState、signal 等。
查询实时用电用 info-statistic + type:"statistic"，响应带 voltage/current/power/energy/key/mac。
每条指令带唯一 messageId，响应原样回显，便于关联。
time.sleep 只是演示用的粗暴等待；生产环境应按 messageId 做事件驱动与超时重试。

4.3 Node.js 与 Java 最小示例

Node.js（mqtt 库）：

javascript 复制代码

const mqtt = require('mqtt');
const PUB_TOPIC = '设备的publish主题';   // 服务端订阅
const SUB_TOPIC = '设备的subcribe主题';  // 服务端发布
const client = mqtt.connect('mqtt://mqtt.smart-bird.cn:1883',
                            { clientId: 'srv-node-01' });

client.on('connect', () => {
  client.subscribe(PUB_TOPIC);                     // 收设备上行
  client.publish(SUB_TOPIC, JSON.stringify({       // 查询实时用电
    commandName: 'info-statistic', type: 'statistic', messageId: 'n-001'
  }));
  client.publish(SUB_TOPIC, JSON.stringify({       // 断电
    commandName: 'controller-event', key: 0, type: 'event', messageId: 'n-002'
  }));
});

client.on('message', (topic, buf) => {
  const d = JSON.parse(buf.toString());
  if (d.commandName === 'info-statistic')
    console.log(`电压${d.voltage}V 电流${d.current}A 功率${d.power}W 电量${d.energy}kWh`);
  else
    console.log('上行:', d.commandName, 'messageId=', d.messageId, 'source=', d.source);
});

Java（Eclipse Paho）：

java 复制代码

import org.eclipse.paho.client.mqttv3.*;
import org.eclipse.paho.client.mqttv3.persist.MemoryPersistence;

public class Demo {
  static final String PUB_TOPIC = "设备的publish主题";  // 服务端订阅
  static final String SUB_TOPIC = "设备的subcribe主题"; // 服务端发布
  public static void main(String[] a) throws Exception {
    MqttClient c = new MqttClient("tcp://mqtt.smart-bird.cn:1883",
                                  "srv-java-01", new MemoryPersistence());
    c.setCallback(new MqttCallback() {
      public void connectionLost(Throwable t) {}
      public void messageArrived(String topic, MqttMessage m) throws Exception {
        String d = new String(m.getPayload());  // 用 JSON 库解析
        System.out.println("上行: " + d);        // 关键字段 voltage/current/power/energy
      }
      public void deliveryComplete(IMqttDeliveryToken t) {}
    });
    c.connect();
    c.subscribe(PUB_TOPIC);                                  // 收设备上行
    c.publish(SUB_TOPIC, ("{\"commandName\":\"info-statistic\","
      + "\"type\":\"statistic\",\"messageId\":\"j-001\"}").getBytes(), 0, false);
    c.publish(SUB_TOPIC, ("{\"commandName\":\"controller-event\","
      + "\"key\":0,\"type\":\"event\",\"messageId\":\"j-002\"}").getBytes(), 0, false);
    Thread.sleep(5000);
    c.disconnect(); c.close();
  }
}

三种语言的骨架完全一致：连 Broker → 订阅 publish 主题 → 向 subcribe 主题发 JSON 指令 → 监听上行解析。换语言只是换皮。

4.4 一个完整脚本：查询实时用电并打印电压/电流/功率/累计电量

下面是一个"更实用"的完整脚本：连接后循环查询 info-statistic，把四个电量值格式化打印，并顺便显示信号强度趋势。

python 复制代码

import json, time, uuid
import paho.mqtt.client as mqtt

BROKER, PORT = "mqtt.smart-bird.cn", 1883
PUB_TOPIC = "设备的publish主题"      # 订阅：收上行
SUB_TOPIC = "设备的subcribe主题"     # 发布：下指令
INTERVAL  = 5                         # 每 5 秒查一次

def on_connect(client, u, f, rc):
    client.subscribe(PUB_TOPIC)

def on_message(client, u, msg):
    d = json.loads(msg.payload.decode())
    if d.get("commandName") != "info-statistic":
        return
    v, a, w, e = d["voltage"], d["current"], d["power"], d["energy"]
    on_off = "通电" if d["key"] == 1 else "断电"
    # 估算：视在功率 power = voltage × current（本设备不做相位差测量）
    print(f"[{time.strftime('%H:%M:%S')}] 状态:{on_off} "
          f"电压:{v:>6}V  电流:{a:>6}A  功率:{w:>8}W  累计电量:{e:>9}kWh")

c = mqtt.Client(client_id="srv-demo-" + uuid.uuid4().hex[:6])
c.on_connect, c.on_message = on_connect, on_message
c.connect(BROKER, PORT, 60)
c.loop_start()
try:
    while True:
        c.publish(SUB_TOPIC, json.dumps({
            "commandName": "info-statistic",
            "type": "statistic",
            "messageId": "stat-" + uuid.uuid4().hex[:8],
        }))
        time.sleep(INTERVAL)
finally:
    c.loop_stop(); c.disconnect()

输出示例：

复制代码

[21:03:05] 状态:通电 电压: 220.4V  电流: 0.136A  功率:    30.0W  累计电量: 0.0123kWh
[21:03:10] 状态:通电 电压: 219.8V  电流: 0.141A  功率:    31.0W  累计电量: 0.0125kWh

说明与善意提醒：

power 上报的是视在功率（U×I 估算），不等于有功功率；用它估电费需按负载类型乘功率因数修正，细节见第 2 部分。
energy 是累计电量，断电不归零 ；需要归零时用 energy-clear。
若想连续看曲线，别用这个循环查询，改用 device-timer-interval（timerEnable:1、timerInterval:60）开启设备主动上报 device-timer-task。
info-statistic 与 device-timer-task 的字段基本一致，区别在于后者带 source:"auto"。

4.5 本章落地清单（checkbox）

本章要点：

15 分钟闭环 = 配网 → info-protocol 取主题 → 订阅 publish、发布 subcribe → 发 info-statistic / controller-event。
三语言骨架相同，字段一致；示例可直接运行参考。
生产环境用 messageId 做事件驱动，用 device-timer-interval 开启主动上报，避免高频轮询。

第一部分到此结束。你已经认识了设备、搞懂了协议、跑通了第一条指令。

接下来第 2 部分将深入：数据采集的物理含义、视在功率的处理、上报与查询的选型、数据落库与可视化、以及与云平台/私有化的系统集成。

第二部分数据、调优与系统集成

本篇是《GSPM1B2 智能插座开发者指南》的第 2 部分，覆盖第 5~9 章。

第一部分讲的是"设备是什么、怎么连、指令怎么发"；这一部分讲的是"数据怎么来、问题怎么查、产品怎么做、平台怎么接"。所有字段、指令名、参数范围均以《00-基准事实》为准。

第 5 章数据采集：把电变成数据

点题： 智能插座的核心价值，是把"看不见的电流"翻译成"看得懂的数字"，本章讲清每个数字从哪来、代表什么、怎么取、怎么存。

5.1 电压/电流/功率/电量的物理含义与采集原理

先把四个量放进一个生活化的类比里------把电想成自来水：

电气量	单位	水管类比	一句话理解
电压 voltage	V（伏）	水压	"推"电的压力，插座输入为 AC 85~265V
电流 current	A（安）	水流量	每秒流过多少电荷，本设备上限 10A
功率 power	W（瓦）	每秒做的功	电压 × 电流，MAX 2500W
电量 energy	kW·h（度）	累计用水量	一段时间内用电的"总量"，断电不归零

采集原理（简版） ：GSPM1B2 的主控是乐鑫 ESP32，内置过零检测。市电是 50Hz 正弦波，每 20ms 完成一个周期，每秒两次穿过 0V。芯片借过零点作为"时间基准尺"，在波形上密集采样，再用均方根（RMS）算法算出电压有效值、电流有效值，两者相乘得到功率，功率对时间积分得到累计电量。

过零检测不只是为了计量准------它还被用于继电器的过零投切 ：在电压接近 0 的瞬间吸合/断开继电器，把合闸浪涌压到最低。这正是 16A 宏发继电器 HF32FV-16（磁保持类机械触点）能长期可靠工作的关键。对开发者来说，这意味着：通断电指令不要高频连发，设备内部的过零策略需要一点时间去配合。

一个必须提前明确的定位：这是一只"可开发智能插座"，不是计量级电能表。 它的数据用于趋势、控制与粗算，不能替代电费结算用的专业表计。

5.2 视在功率与有功功率的区别（诚实说明）

点题： power 字段上报的是视在功率，不是有功功率------这不是缺点，而是硬件取舍，工程上必须知道怎么处理。

用"啤酒杯"理解：

杯子里整杯（泡沫 + 酒）= 视在功率 S（单位 VA）
能真正喝到的酒 = 有功功率 P（单位 W）
泡沫 = 无功功率 Q（单位 var）

公式：

视在功率 S = U × I（电压有效值 × 电流有效值）
有功功率 P = U × I × cosφ（乘上功率因数）
功率因数 PF = cosφ = P / S（0~1 之间）

为什么插座只报视在功率？ 因为测量功率因数需要同时精确测量电压与电流的相位差 ，需要更复杂的计量芯片。GSPM1B2 用 ESP32 的采样能力做的是 S = U×I 的估算，不做相位差测量 ，因此 power 是视在功率。这是诚实的设计取舍，必须写清楚，避免集成商拿它去做精准电费核算时"翻车"。

工程上的处理办法（按场景选）：

场景	是否够用	处理方式
只看通断 / 是否在用电	✅ 够用	直接看 `power > 0`
看用电趋势、做峰值预警	✅ 基本够用	用视在功率做相对比较
估算电费	⚠️ 需修正	视在 × 经验功率因数
精细化能耗管理	❌ 不够	外挂专业电能表，插座只做开关

经验功率因数参考（用于把视在功率逼近有功功率）：

负载类型	典型 PF	举例
纯阻性	≈ 1.0	白炽灯、电热锅、电水壶、电暖器
带电子整流	0.6~0.9	LED 灯、充电器、电脑
感性（电机类）	0.5~0.9	空调、冰箱、洗衣机、水泵

所以，如果插座后面挂的是电热设备，power ≈ 有功功率，几乎不用修正；如果挂的是空调/电机，直接用 power 估电费会偏高，需要乘 0.5~0.9 的系数。稳妥做法：在系统里为每类负载维护一个 PF 系数，展示时做修正，并标注"估算值"。

5.3 定时上报（device-timer-interval / device-timer-task）vs 主动查询（info-statistic）如何选择与配置

点题： 取数有两种姿势------让设备主动推 ，还是让你去问；先搞清两者代价，再按场景选。

姿势一：设备主动上报（推模式）

服务端发一条 device-timer-interval 设置上报频率：timerEnable（0关/1开）、timerInterval（5~86400 秒 ）、type:"setting"。
设备此后按周期自动上行 device-timer-task，字段包含 voltage、current、power、energy、key、mac，且 source:"auto" 表明这是自动上报。
优点：服务端无需轮询、数据连续、便于画曲线；缺点：设备全程在线推数据，耗网络、耗电。

姿势二：主动查询（拉模式）

服务端发 info-statistic 查询请求（type:"statistic"）。
设备回复 commandName:"info-statistic" 且带 voltage、current、power、energy、key、mac。
优点：按需取数、最省流量；缺点：实时性取决于你问的频率，且每次都要一次往返。

对比与选型：

维度	定时上报（推）	主动查询（拉）
数据连续性	高，天然等间隔	取决于轮询频率
网络/功耗	持续消耗	按需消耗
服务端复杂度	低（只订阅）	中（要调度 + 匹配响应）
实时性	由 `timerInterval` 决定	由轮询频率决定
适用场景	能耗看板、长期趋势	点开即看、事件触发、省电设备

选型决策（编号步骤）：

需要连续曲线 / 多设备集中看板 → 选推模式 ，timerInterval 设 30~300 秒。
只在用户打开页面时看数 → 选拉模式 ，点开时发 info-statistic。
混合：平时拉模式省资源，进入"监控态"时临时开 timerEnable=1。
关键约束：timerInterval 最小 5 秒，切勿设成 1~2 秒，否则设备与 WiFi 都会被大量上报拖累。

Python 示例（paho-mqtt）：

python 复制代码

import json, time
import paho.mqtt.client as mqtt

BROKER = "mqtt.smart-bird.cn"   # 或你的自建 Broker
PORT   = 1883
PUB_TOPIC = "设备publish主题"     # 由 info-protocol 的 publish 字段得到（服务端订阅它，收上行）
SUB_TOPIC = "设备subcribe主题"    # 由 info-protocol 的 subcribe 字段得到（服务端发布它，发指令）

client = mqtt.Client(client_id="srv-collector-01")
client.connect(BROKER, PORT, 60)

# ① 打开定时上报：每 60 秒自动上行 device-timer-task
set_interval = {
    "commandName": "device-timer-interval",
    "timerEnable": 1,
    "timerInterval": 60,
    "type": "setting",
    "messageId": "20250101001",      # 业务流水号，设备原样回显
}
client.publish(SUB_TOPIC, json.dumps(set_interval))

# ② 需要即时值：主动查询一条 info-statistic
query = {
    "commandName": "info-statistic",
    "type": "statistic",
    "messageId": "20250101002",
}
client.publish(SUB_TOPIC, json.dumps(query))

def on_message(c, u, msg):
    data = json.loads(msg.payload)
    if data.get("commandName") == "device-timer-task":
        print("自动上报:", data["voltage"], data["current"], data["power"], data["energy"])
    elif data.get("commandName") == "info-statistic":
        print("查询响应:", data["power"], "W")
    # 注意：响应里的 messageId 会原样回显，可用于关联请求

client.on_message = on_message
client.subscribe(PUB_TOPIC)
client.loop_forever()

5.4 数据落库与可视化

点题： 采集来的数据必须"存得住、查得快、看得见"，选型与容量估算要提前算清。

时序数据库选型建议：

数据库	特点	适合
InfluxDB	生态成熟、写入快、Grafana 原生支持	中小规模、快速上手
TDengine	国产、专为 IoT、压缩率高、超级表好用	大规模设备、成本敏感
TimescaleDB	基于 PostgreSQL，SQL 友好	需要复杂 SQL/联表分析
Prometheus	拉模式、指标监控强	监控告警，不适合长期明细

容量估算（关键公式）： 年度存储 ≈ 设备数 × (86400 / 采样间隔) × 单条字节 × 365

单条时序记录（含时间戳、mac、四个电量字段、标签）按 约 100 字节估算：

采样间隔	单设备/天条数	100 台/天	100 台/年（约）
5 秒	17,280	172.8 万	~63 GB
30 秒	2,880	28.8 万	~10.5 GB
60 秒	1,440	14.4 万	~5.3 GB
300 秒	288	2.88 万	~1.05 GB

结论：监控看板用 30~60 秒足够；只有做"负载指纹"之类的分析才需要 5 秒级。能用 60 秒就不要用 5 秒，存储与写入压力差十几倍。

可视化建议：

快速出图：Grafana 直连 InfluxDB/TDengine，10 分钟搭好曲线与大屏。
定制大屏：前端 ECharts + 后端 WebSocket 推 power/energy 实时值。
数据降采样（continuous query / 物化视图）：原始 60 秒数据保留 30 天，再聚合成 5 分钟均值长期保留，兼顾精度与成本。

数据质量校验（落库前必做）：

范围校验 ：voltage 应在 85~265V，current 不超过 10A，power 不超过 2500W；越界数据先标记可疑，别直接入正式库。
跳变校验 ：energy 是单调递增的累计量（除非发过 energy-clear）。若两次读数出现"大幅回退"，说明可能发生了清零或设备重启，要打时间戳备注，否则出账会算错。
空值/抖动处理：信号差时上行可能延迟或丢失，落库前对相邻点做去重与插值，避免曲线出现断崖。
时区与时钟 ：设备侧时间不一定可信，统一以服务端接收时间作为入库时间戳，保证多设备数据可比。

本章要点 / 落地清单：

voltage/current/power/energy 分别是电压、电流、视在功率、累计电量；断电不归零。
power 是视在功率，估电费需乘经验功率因数（阻性≈1、电机 0.5~0.9）。
连续看板用推（device-timer-interval 设 5~86400 秒），按需看数用拉（info-statistic）。
timerInterval 别小于 5 秒；监控场景 30~60 秒最佳。
时序库按规模选，单条 ~100 字节，100 台 60 秒/年约 5.3 GB。

第 6 章调试手册：从"设备没反应"到"一眼定位"

点题： 99% 的"设备没反应"，都逃不出三层------Broker 通不通、主题对不对、设备在不在线；按顺序排，三步定位。

6.1 三层排查法（Broker → 主题 → 设备）

第一层：Broker（服务器/网络）------"路通了没？"

服务器能不能连：ping mqtt.smart-bird.cn。
端口开没开：nc -vz mqtt.smart-bird.cn 1883。
Broker 服务在不在跑：systemctl status mosquitto / systemctl status emqx。
设备与 Broker 是不是同一网络可达（尤其自建内网 Broker，设备必须能访问到）。

第二层：主题（最易错）------"门牌号写对没？"

牢记 info-protocol 的语义：
- publish = 设备发布的主题 → 服务端要订阅它（收上行）。
- subcribe = 设备订阅的主题 → 服务端要发布到它（下指令）。
90% 的"指令发了没反应"是这一层搞反了：把指令发到了 publish 主题，或订阅了 subcribe 主题。
注意 subcribe 是官方字段的原始拼写（少一个 s），代码里照抄，别"顺手改对"。

第三层：设备（在线/信号/格式）------"人到了没？"

设备是否在线：发 info-all（type:"info"）看有没有回 mac/ip/ssid/signal。
信号强度：看 signal（dBm），越接近 0 越好。

signal 区间	质量
0 ~ -50 dBm	最好
-50 ~ -70 dBm	较好
-70 ~ -80 dBm	一般
-80 ~ -100 dBm	较差

指令 payload 是否合法：JSON 是否可解析、commandName 是否拼对、是否带 messageId。
是否刚改过通信配置：用 setting-mqtt/setting-tcp 改过服务器后，必须断电重启或发 controller-restart 才生效------这是超高频"坑"。

6.2 用 mosquitto_sub / mosquitto_pub 抓包定位

抓包（先看设备在发什么）：

bash 复制代码

# 订阅所有主题，实时看设备上行（-v 显示主题名）
mosquitto_sub -h mqtt.smart-bird.cn -p 1883 -t '#' -v

# 只看某台设备的 publish 主题
mosquitto_sub -h mqtt.smart-bird.cn -p 1883 -t '设备publish主题' -v

# 带账号密码 / 调试输出
mosquitto_sub -h 192.168.1.10 -p 1883 -u user -P pass -t '设备publish主题' -v -d

发指令（模拟服务端）：

bash 复制代码

# 查询实时用电信息
mosquitto_pub -h mqtt.smart-bird.cn -p 1883 \
  -t '设备subcribe主题' \
  -m '{"commandName":"info-statistic","type":"statistic","messageId":"1001"}'

# 通电（key=1）
mosquitto_pub -h mqtt.smart-bird.cn -p 1883 \
  -t '设备subcribe主题' \
  -m '{"commandName":"controller-event","key":1,"type":"event","messageId":"1002"}'

抓包定位步骤：

先用 # 通配看全量，确认设备到底在不在发数据。
若能看到 device-timer-task，说明设备在线、主题对、上行正常 → 问题在"你发指令"这一侧。
若发 controller-event 后能在 # 里看到带相同 messageId 的响应 → 链路完全通。
若发了没响应 → 回到第二层，核对 publish/subcribe 有没有搞反。

6.3 常见故障速查表（症状 → 原因 → 解决）

#	症状	可能原因	解决
1	设备一直离线	Broker 地址/端口错	用 `info-protocol` 核对 server/port
2	设备一直离线	设备没连上 WiFi	检查 `ssid`/信号，重配 WiFi
3	下指令完全无响应	publish/subcribe 搞反	指令发到 `subcribe` 主题
4	下指令无响应	主题拼写大小写错	与 `info-protocol` 逐字对齐
5	设备反复掉线重连	clientId 与他人冲突	用 `setting-mqtt` 保证 clientId 唯一
6	改了服务器不生效	未重启	断电重启或发 `controller-restart`
7	收不到任何上行	服务端没订阅 publish 主题	订阅设备的 `publish` 主题
8	只收到自己发的消息	订阅了 subcribe 主题	改为订阅 `publish` 主题
9	无 `device-timer-task` 上报	定时上报没开	发 `device-timer-interval`，`timerEnable=1`
10	上报间隔不对	`timerInterval` 被设超范围	确保在 5~86400 秒内
11	上报过于频繁	间隔设太小	调大 `timerInterval`（建议 30~60）
12	`power` 与实测不符	视在≠有功	按负载类型乘功率因数
13	`energy` 清零了	有人发了 `energy-clear`	属正常，记录清零时间
14	通断电指令后状态没变	按键锁导致？	查 `keyLock`；必要时先解锁
15	按键按不动	按键锁开启	`setting-key-lock` 设 `keyLock=0`
16	无法重新配网	配网锁开启	`setting-wifi-lock` 设 `wifiLock=0`
17	重启后插座状态变了	上电默认状态设置	查 `onState`（0记忆/1关/2开）
18	信号差、时断时续	WiFi 覆盖不足	换位置/加 AP，`signal` 拉到 -70 以上
19	多台设备互相干扰	主题无区分	按 mac 规划独立主题前缀
20	指令偶发丢失	QoS/网络抖动	提高 QoS，加超时重试
21	JSON 解析失败	payload 非法或编码问题	确保 UTF-8、合法 JSON
22	定时任务不执行	任务未设置成功	用 `info-timer-task-query` 核对
23	响应 messageId 对不上	自行篡改回显	设备原样回显，勿改请求 ID
24	设备频繁重启	负载超限保护	检查是否超 10A/2500W

6.4 日志与可观测性（埋点、请求-响应链路追踪）

点题： 出问题时，日志要能"一眼看到发生了什么"，靠的是统一埋点 和用 messageId 串起链路。

核心思路：messageId 就是你的链路追踪 ID。 请求里带上它，设备响应会原样回显，于是"请求 → 响应 → 耗时"就能自动配对。

埋点建议（每条日志至少记录）：

messageId：业务流水号，全链路唯一。
mac：设备身份。
commandName：指令名。
direction：上行 / 下行。
ts_send / ts_recv：发送与接收时间戳（可算响应延迟）。
result：成功 / 超时 / 失败。

结构化日志示例：

python 复制代码

import json, time, logging

def log_event(direction, mac, command_name, message_id, ok, extra=None):
    logging.info(json.dumps({
        "ts": time.time(),
        "direction": direction,       # "down" 下行 / "up" 上行
        "mac": mac,
        "commandName": command_name,
        "messageId": message_id,
        "ok": ok,
        "extra": extra or {},
    }, ensure_ascii=False))

链路追踪 / 关键指标：

设备在线率 ：周期性 info-all 探活，成功率即在线率。
指令成功率 ：成功响应数 / 下发数。
响应延迟 ：ts_recv - ts_send，超阈值告警。
上报心跳 ：太久没收到 device-timer-task → 设备可能离线。

本章要点 / 落地清单：

排查顺序固定：Broker → 主题 → 设备，别跳步。
publish 要服务端订阅，subcribe 要服务端发布，这是头号坑。
改通信配置后必须重启 （断电或 controller-restart）才生效。
用 mosquitto_sub -t '#' -v 先看设备在发什么，再怀疑别的。
用 messageId 做请求-响应关联，指标盯在线率、成功率、延迟。

第 7 章二次开发进阶：把它变成你自己的产品

点题： 让插座"能用"很简单，难的是让它"好用、稳、还能管一千台"------本章给你可复用的工程骨架。

7.1 SDK 封装：连接、断线重连、请求-响应关联、设备影子

四大件，缺一不可：

连接管理 ：封装 Broker 连接，统一处理 username/password、clientId。
断线重连 ：on_disconnect 里触发重连，采用指数退避（1s、2s、4s...上限 30s），避免雪崩式重连。
请求-响应关联 ：请求生成唯一 messageId，响应按 messageId 找到对应的等待者（Future / 回调）。
设备影子 ：在内存里维护每台设备的最新状态（key/voltage/current/power/energy/signal），即使设备暂时离线，也能读到"最后一次已知状态"。

python 复制代码

import json, uuid, time, threading
import paho.mqtt.client as mqtt

class DeviceClient:
    def __init__(self, host, port, pub_topic, sub_topic, mac,
                 username=None, password=None):
        self.pub_topic = pub_topic      # 设备发布 → 我订阅
        self.sub_topic = sub_topic      # 设备订阅 → 我发布
        self.mac = mac
        self.pending = {}               # messageId -> {"event": Event, "resp": None}
        self.shadow = {}                # 设备影子：最新状态
        self.lock = threading.Lock()
        self.client = mqtt.Client(client_id=f"sdk-{mac}")
        if username:
            self.client.username_pw_set(username, password)
        self.client.on_connect = self._on_connect
        self.client.on_message = self._on_message
        self.client.on_disconnect = self._on_disconnect
        self.host, self.port = host, port
        self._backoff = 1

    def _on_connect(self, c, u, flags, rc):
        self._backoff = 1
        c.subscribe(self.pub_topic)     # 订阅设备发布主题，收上行

    def _on_disconnect(self, c, u, rc):
        # 指数退避重连，避免风暴
        threading.Timer(self._backoff, self._reconnect).start()
        self._backoff = min(self._backoff * 2, 30)

    def _reconnect(self):
        try:
            self.client.reconnect()
        except Exception:
            threading.Timer(self._backoff, self._reconnect).start()
            self._backoff = min(self._backoff * 2, 30)

    def _on_message(self, c, u, msg):
        data = json.loads(msg.payload)
        mid = data.get("messageId")
        # 更新设备影子
        with self.lock:
            for k in ("key", "voltage", "current", "power", "energy", "signal"):
                if k in data:
                    self.shadow[k] = data[k]
        # 关联请求-响应
        if mid in self.pending:
            self.pending[mid]["resp"] = data
            self.pending[mid]["event"].set()

    def request(self, payload, timeout=5):
        """发指令并等待响应，用 messageId 关联"""
        mid = payload.setdefault("messageId", uuid.uuid4().hex[:12])
        ev = threading.Event()
        with self.lock:
            self.pending[mid] = {"event": ev, "resp": None}
        self.client.publish(self.sub_topic, json.dumps(payload))  # 发到设备订阅主题
        got = ev.wait(timeout)
        with self.lock:
            entry = self.pending.pop(mid, None)
        if not got:
            return None                 # 超时，交给上层重试
        return entry["resp"]

    def power_on(self):
        return self.request({"commandName": "controller-event",
                             "key": 1, "type": "event"})

    def read_stat(self):
        return self.request({"commandName": "info-statistic",
                             "type": "statistic"})

    def run(self):
        self.client.connect(self.host, self.port, 60)
        self.client.loop_forever()

7.2 批量设备管理：命名规范与 topic 规划

点题： 一台设备靠"记"，一千台设备靠"规范"。命名乱，运维就是灾难。

命名规范建议：

用 mac 作为唯一身份（设备天然带 mac 字段，不会重复）。
在 mac 之上加业务前缀 ：{场景}-{位置}-{用途}-{mac后6位}，例：factory-A线-注塑机-3F2A1B。
数据库主键用 mac，业务名做显示别名。

topic 规划（两种模式）：

模式 A------每设备独立主题（隔离性好）：

复制代码

gz/{mac}/up        # 设备发布（服务端订阅）
gz/{mac}/down      # 设备订阅（服务端发布）

模式 B------共享主题 + 负载内区分（设备默认形态，靠 mac 区分）：

复制代码

上行：所有设备发到同一 publish 主题，消息里带 mac
下行：所有设备订阅同一 subcribe 主题，消息里带目标 mac

注意：GSPM1B2 出厂以设备各自的 publish/subcribe 主题 工作（见 info-protocol）。要改成按 mac 规划的多级主题，需用 setting-mqtt 自定义 publish/subcribe，并重启生效 。若设备本身不支持通配符订阅，则优先用模式 B，在后端按 mac 分发。

多设备路由示例（后端按 mac 分发）：

python 复制代码

# 模式 B：同一上行主题收到全部设备消息，按 mac 分发给对应处理逻辑
SHADOWS = {}   # {mac: {最新状态}}

def on_upstream(payload):
    data = json.loads(payload)
    mac = data.get("mac")
    if not mac:
        return
    SHADOWS.setdefault(mac, {}).update(
        {k: data[k] for k in ("key", "voltage", "current", "power", "energy") if k in data}
    )
    # 按 mac 路由到该设备的业务规则
    route_by_device(mac, data)

批量设备管理清单：

事项	做法
身份主键	mac
业务命名	场景-位置-用途-短码
主题隔离	每设备前缀或后端按 mac 分发
影子状态	后端集中维护
分组	按场景/区域打标签

7.3 配置化最佳实践：上电默认状态 / 按键锁 / 配网锁

点题： 三条 setting-* 配置，决定了设备"断电来电后什么样、按键能不能按、能不能被重新配网"，是商用落地的安全阀。

1）上电默认状态 setting-on-state（onState：0记忆/1关闭/2开启）

0 记忆：来电后恢复断电前的状态。适合家庭、普通场景。
1 关闭 ：来电后默认断电。适合安全优先（如电热设备、防止无人时自动通电）。
2 开启 ：来电后默认通电。适合需要常在线的设备（如路由器、网关供电）。

2）按键锁 setting-key-lock（keyLock：0开锁/1上锁）

上锁后物理按键失效 ，只能通过平台控制。适合公共场所防误触（酒店、商场、共享设备）。

3）配网锁 setting-wifi-lock（wifiLock：0开锁/1上锁）

上锁后无法重新配网 ，防止顾客/陌生人把设备改连到别的 WiFi。适合商用投放。

场景配置推荐：

场景	onState	keyLock	wifiLock
家庭普通插座	0 记忆	0	0
酒店客房	0 记忆	1 上锁	1 上锁
工厂电热设备	1 关闭	0	1 上锁
共享充电/租赁	1 关闭	1 上锁	1 上锁
机房设备供电	2 开启	1 上锁	1 上锁

配置示例：

python 复制代码

# 酒店客房：上电记忆 + 按键锁 + 配网锁
client.publish(SUB_TOPIC, json.dumps(
    {"commandName": "setting-on-state", "onState": 0, "messageId": "c1"}))
client.publish(SUB_TOPIC, json.dumps(
    {"commandName": "setting-key-lock", "keyLock": 1, "messageId": "c2"}))
client.publish(SUB_TOPIC, json.dumps(
    {"commandName": "setting-wifi-lock", "wifiLock": 1, "messageId": "c3"}))

注意：controller-event 的响应里也带 onState、keyLock、wifiLock，可在一次控制后顺便核对当前配置。

7.4 可靠性工程：断网缓存、指令重试、幂等、超时处理

点题： 网络一定会抖动，做产品就必须假设"消息会丢、会重、会晚到"。

断网缓存（设备侧 / 网关侧）
- 设备端在断网期间，用电数据无法上云，重连后可依赖累计电量 energy 不回零 来"补算"用电总额（用两次 energy 之差还原区间用电）。
- 服务端侧缓存待发指令，重连成功后重放。

指令重试 + 指数退避

python 复制代码

def request_with_retry(client, payload, retries=3, base=1.0):
    for i in range(retries):
        resp = client.request(dict(payload), timeout=5)
        if resp is not None:
            return resp
        time.sleep(base * (2 ** i))   # 1s, 2s, 4s
    return None

幂等
- 重要：controller-event 这类"设置型"指令是天然的幂等操作------把插座设成"通电"重复一百次，结果还是"通电"，重复执行无害。
- 相反：energy-clear（清零）不幂等，重发会让电量再次清零，务必只发一次并做好标志位防重。
- 幂等键建议用 messageId，服务端记录已处理的 ID，避免重复触发业务动作。
超时处理
- 每个请求都要有超时上限（如 5 秒），超时即判失败并进入重试/告警。
- 对探活类 请求（info-all），连续 N 次超时判定设备离线。

可靠性对照表：

指令	是否幂等	重试策略
`controller-event`	✅ 幂等	可安全重试
`setting-on-state`	✅ 幂等	可安全重试
`setting-key-lock`	✅ 幂等	可安全重试
`setting-timer-task`	⚠️ 可能重复建任务	先查再建
`energy-clear`	❌ 不幂等	勿重试，防重复清零
`controller-restart`	⚠️ 会短暂离线	慎用、低频

本章落地清单：

SDK 必备四件套：连接、重连、请求-响应关联、设备影子。
用 mac 做身份，命名规范 场景-位置-用途-短码。
三种锁配好：onState、keyLock、wifiLock------商用安全阀。
设置型指令幂等可重试；energy-clear 不幂等，严禁重试。
所有请求带超时，用指数退避重连/重试。

第 8 章云平台对接：公有云与私有化部署

点题： GSPM1B2 是一台支持 MQTT 的设备，它既能接公有云物联网平台，也能私有化部署------本章讲清两条路的思路、要点与安全底线。

8.1 接入阿里云/腾讯云/华为云/百度云物联网平台

核心思路： 主流公有云 IoT 平台本质都是 "MQTT Broker + 物模型 + 规则引擎" 。设备已经支持 MQTT，且能用 setting-mqtt 自定义 server/port/publish/subcribe/clientId/username/password，因此理论上一台 GSPM1B2 可以指到任意标准 MQTT 平台。

关键差异（务必注意）： 公有云平台的主题是平台规定的 （通常形如 /${productKey}/${deviceName}/user/...），而设备默认有一套自己的 publish/subcribe 主题结构。两者不一样。对接时有两条路：

路 A：主题对齐 ------用 setting-mqtt 把设备的 publish/subcribe 改成平台规定的主题，clientId/username/password 填三元组。改完重启生效。
路 B：网关/规则引擎中转 ------设备保持原主题，后端做一个"协议适配层"，收到设备消息后转成平台物模型格式转发。改动小，容错好，推荐用于存量改造。

四家平台对接要点速览：

平台	认证方式	典型主题结构	对接要点
阿里云 IoT	三元组（ProductKey/DeviceName/DeviceSecret）	`/${pk}/${dn}/user/...`	用 `setting-mqtt` 填三元组派生信息
腾讯云 IoT	产品 ID + 设备名 + 密钥	平台自定义	需做 topic 映射
华为云 IoTDA	设备 ID + 密钥，支持物模型	`$oc/devices/{id}/...`	物模型要定义 voltage/power 等属性
百度云 IoT	设备物接入，thing 模型	平台自定义	规则引擎做数据转发

操作步骤（以路 B 为例）：

在云平台创建产品与设备，拿到设备身份/密钥。
定义物模型属性 ：voltage(V)、current(A)、power(W)、energy(kWh)、key(0/1)------与设备字段一一对应。
后端订阅设备的 publish 主题，收到 device-timer-task/info-statistic 后，转换成平台要求的 JSON，再发布到平台。
平台下行指令时，后端把云指令转成设备认得的 commandName 格式，发到设备 subcribe 主题。
用平台规则引擎做存储、告警、联动大屏。

8.2 私有化部署完整方案（自建 Mosquitto/EMQX + 后端服务）

点题： 要数据自主可控、要成本低、要内网跑，就私有化------自建 Broker + 自研后端。

推荐架构（文字版）：

复制代码

[GSPM1B2 设备群]
      │  WiFi / MQTT
      ▼
[Broker：Mosquitto 或 EMQX]   ← 认证、ACL、TLS
      │
      ├─▶ [接入服务] 订阅 publish 主题，解析上行
      ├─▶ [设备服务] 维护设备影子、下发指令
      ├─▶ [规则/告警] 阈值判断、联动
      ▼
[存储层：InfluxDB/TDengine + MySQL/PostgreSQL]
      ▼
[API 网关] → [Web 前端 / 大屏 / ERP 对接]

组件选型：

组件	轻量方案	大规模方案
Broker	Mosquitto	EMQX（集群）
时序库	InfluxDB	TDengine
关系库	MySQL	PostgreSQL
缓存	Redis	Redis Cluster
前端可视化	Grafana	自研大屏

部署步骤（编号）：

安装 Broker：小规模用 Mosquitto，海量设备用 EMQX 集群。
配置认证：开启 username/password，为每台设备建独立账号。
配置 ACL：限制每台设备只能读写自己的主题。
开启 TLS（8883 端口），配好证书。
部署后端接入服务，订阅设备 publish 主题。
设备端用 setting-mqtt 指向自建 Broker（server/port/publish/subcribe/clientId/username/password），重启生效。
数据落库 + Grafana 出图，联调验收。

8.3 安全：账号体系、TLS、权限隔离、设备身份

点题： 设备联网就是"暴露在公网"，安全必须当成一等公民。

维度	风险	措施
传输加密	明文被抓包	用 TLS（8883）替代明文 1883
账号体系	匿名接入被滥用	关闭匿名，每设备独立 `username/password`
权限隔离	越权控制他人设备	ACL：设备只能读写自己主题
设备身份	设备被伪造	用 `mac` + clientId 绑定，唯一性校验
指令鉴权	伪造下行指令	后端校验指令来源与权限

要点：

生产环境务必上 TLS 。setting-mqtt 支持自定义 server/port，把端口改成 8883 即可走向加密通道。
clientId 唯一 ：设备用 setting-mqtt 设 clientId，避免多设备撞 ID 导致互相踢下线（这正是 6.3 表里第 5 条故障的根因）。
权限最小化 ：一台设备只允许访问自己的 publish/subcribe 主题，别给通配符写权限。
身份绑定：把 mac 写进 topic 或 payload，后端做白名单校验。

本章落地清单：

公有云对接两条路：主题对齐 或 网关中转（存量改造优先中转）。
物模型属性与 voltage/current/power/energy/key 一一对应。
私有化：自建 Mosquitto/EMQX + 接入/设备/规则服务 + 时序库 + Grafana。
安全四件套：TLS、账号、ACL、clientId 唯一。
改完 setting-mqtt 记得重启。

第 9 章集成实战：让插座融入现有系统

点题： 插座不是孤岛------它最终要汇进你已有的 HA、ERP、Scada 或数据中台，本章给出可直接抄的集成范式。

9.1 接入 Home Assistant（YAML 示例）

思路： HA 内置 MQTT 集成。用设备的 publish 主题做传感器（读电量），用 subcribe 主题做开关（控通断）。

yaml 复制代码

# configuration.yaml
mqtt:
  # 电量传感器：订阅设备 publish 主题，从 device-timer-task / info-statistic 提取字段
  sensor:
    - name: "GSPM1B2 电压"
      state_topic: "设备publish主题"
      unit_of_measurement: "V"
      value_template: "{{ value_json.voltage }}"
    - name: "GSPM1B2 电流"
      state_topic: "设备publish主题"
      unit_of_measurement: "A"
      value_template: "{{ value_json.current }}"
    - name: "GSPM1B2 功率"
      state_topic: "设备publish主题"
      unit_of_measurement: "W"
      value_template: "{{ value_json.power }}"
    - name: "GSPM1B2 累计电量"
      state_topic: "设备publish主题"
      unit_of_measurement: "kWh"
      value_template: "{{ value_json.energy }}"
  # 开关：发 controller-event 控制通断电
  switch:
    - name: "GSPM1B2 开关"
      state_topic: "设备publish主题"
      state_template: "{{ 'ON' if value_json.key == 1 else 'OFF' }}"
      command_topic: "设备subcribe主题"
      payload_on: '{"commandName":"controller-event","key":1,"type":"event","messageId":"ha1"}'
      payload_off: '{"commandName":"controller-event","key":0,"type":"event","messageId":"ha2"}'

说明：把 设备publish主题 / 设备subcribe主题 换成 info-protocol 返回的真实 publish 与 subcribe 值即可。HA 的 value_json.xxx 直接对应设备的 voltage/current/power/energy/key 字段。

9.2 对接自建平台 / ERP / 工单系统的思路

核心链路： 设备 → Broker → 接入服务 → 业务库 → 对外 API → ERP/工单。

落地思路：

接入服务 订阅 publish 主题，把上行数据写业务库。
业务库通过对外 REST API 暴露"设备状态 / 用电量 / 控制"接口给 ERP。
ERP/工单系统调用 API 做资产绑定 （某工位某台插座）、能耗工单（超阈值自动开工单）。
反向控制：ERP 下发"断电"，API 转 controller-event 发到 subcribe 主题。

典型场景（具体）：

某工厂每台注塑机挂一只 GSPM1B2，实时读 power；当 power 连续 N 分钟为 0 却仍在工单"生产中"→ 自动生成"设备停机核查"工单。
某产业园按 energy 差值给租户出账（注意：因 power 是视在功率，账单标注"估算"，或乘功率因数修正）。

9.3 与 SCADA / 组态软件 / 可视化大屏对接

点题： SCADA/组态要的是"工业协议 + 实时点位"，而插座出的是 MQTT------中间需要一个协议网关。

对接方式：

方式	说明	适用
自研网关 → Modbus TCP	后端把 MQTT 数据映射成寄存器，供 SCADA 轮询	传统组态/PLC 系统
OPC UA 网关	把电量点位暴露为 OPC UA 节点	新式工业平台
WebSocket 直推	大屏订阅 WebSocket，实时刷新	Web 大屏
MQTT → Kafka → 大屏	经消息队列缓冲后推前端	高并发大屏

思路（Modbus 网关为例）：

后端为每台设备分配一组 Modbus 寄存器地址（电压/电流/功率/电量/状态）。
收到 MQTT 上行后，更新对应寄存器的值。
SCADA 按 Modbus TCP 轮询这些寄存器，像读 PLC 一样读插座。
反向写寄存器 → 后端转成 controller-event 下发。

9.4 通过 Webhook / 消息队列（Kafka/RabbitMQ）做中台化

点题： 当设备规模上去、下游系统变多，就别让各系统直连设备------用消息队列做"中台"解耦。

架构：

复制代码

[设备] → [Broker] → [接入服务] → [Kafka/RabbitMQ] → [多个消费者]
                                                     ├─ 存储服务
                                                     ├─ 告警服务
                                                     ├─ 大屏服务
                                                     └─ 第三方 Webhook

要点：

解耦：接入服务只管"把设备数据丢进 MQTT/Kafka 主题（Topic）"，下游各取所需。
削峰：设备集中上报时，Kafka 缓冲，避免后端被打垮。
Topic 规划 ：按业务分主题，如 device.telemetry（电量上行）、device.event（开关事件）、device.command（下行指令）。
Webhook ：对不支持消息队列的第三方系统，提供 Webhook 回调------当 power 超阈值时 POST 一个 JSON 到对方 URL。

Webhook 触发示例（伪代码）：

python 复制代码

def on_telemetry(data):
    if data.get("commandName") in ("device-timer-task", "info-statistic"):
        # 阈值告警 → 触发 Webhook
        if data["power"] > 2000:
            requests.post("https://erp.example.com/hook/power-alarm", json={
                "mac": data["mac"],
                "power": data["power"],
                "voltage": data["voltage"],
                "ts": data.get("ts"),
            })

本章落地清单：

HA 用 MQTT 集成，传感器读 voltage/current/power/energy，开关发 controller-event。
ERP/工单：Broker → 接入服务 → 业务库 → API，实现资产绑定与能耗工单。
SCADA/大屏：经协议网关映射为 Modbus/OPC UA，或 WebSocket 直推。
规模化用 Kafka/RabbitMQ 中台化解耦，按 telemetry/event/command 分主题。
对第三方用 Webhook 回调，阈值告警自动推送。

第二部分完。 本部分从"把电变成数据"讲到"把设备变成产品、把产品接进你的系统"，全程字段与指令均对齐《00-基准事实》。第三部分可继续展开性能压测、量产烧录与运维体系。

第 3 部分 · 安装施工、传统对接与 20+ 应用场景

适用产品：GemeOpen（武汉智鸟科技）GSPM1B2 智能转换器插座 10A-S1 Plus-WiFi

主控 ESP32（内置过零检测）｜输入 AC 85~265V｜最大负载电流 10A ｜额定功率 **MAX 2500W（阻性负载）**｜继电器 16A 宏发 HF32FV-16｜2.4GHz WiFi

本篇为开发/集成/施工三方共用的落地手册：先讲"设备怎么自己干活"（定时与自动化），再讲"怎么装才安全"（安装施工），然后讲"怎么接老设备"（传统对接），最后给出 24 个可复制的真实场景 。

全文指令与字段均以 GemeOpen 官方开发者文档为准，示例代码基于 paho-mqtt 2.x 真实字段，不臆造参数。

第 10 章定时与自动化：让插座自己干活

一句话点题： 定时任务是插座的"肌肉记忆"------指令一下发，即使断网、断云，它也会到点自己动手，这才是电气安全最后的兜底。

10.1 设备端定时任务与倒计时任务

GSPM1B2 把"定时"能力做进了设备固件，与平台无关。设备端任务分两类：循环定时任务（timer） 和 倒计时任务（countdown）。

10.1.1 定时通断任务：`setting-timer-task`

用于"每天/每周/某一次到点执行开或关"。设备以任务编号 number 管理多条任务，repeat 决定重复方式：

字段	类型	说明	示例
`command`	Object	到点要执行的开关指令	`{"key":0,"type":"event"}`
`command.key`	int	0 断电 / 1 通电	`0`
`hour`	int	小时 0~23	`12`
`minute`	int	分钟 0~60	`30`
`number`	int	任务编号（同一编号视为编辑该任务）	`1`
`repeat`	String	`week` 按周 / `day` 按天 / `oneof` 一次性	`day`
`task`	String	固定值 `"timer"`	`timer`
`type`	String	固定值 `"setting"`	`setting`

下发示例（每天 12:30 断电）：

json 复制代码

{
  "command": { "key": 0, "type": "event" },
  "hour": 12,
  "minute": 30,
  "number": 1,
  "repeat": "day",
  "task": "timer",
  "type": "setting"
}

设备回执会原样回显 commandName:"setting-timer-task"、hour、minute、number、repeat、mac、source:"command"，据此判断是否成功。

10.1.2 查询定时任务：`info-timer-task-query`

请求体用 action:"timerTaskQuery"：

json 复制代码

{ "action": "timerTaskQuery", "type": "event" }

设备返回 commandName:"info-timer-task-query"，核心是 list 数组。list 中每一条含 hour、minute、number、repeat；带 year/month/day 表示"按年月日时分执行一次"，不带则是"每天按时分循环" 。对多路设备还有 key1/key2/key3 表示各路动作（单路 GSPM1B2 用 key）。注意：info-timer-task-query 的 list 用来"读回设备里到底存了什么"，与平台数据库做对账非常关键。

10.1.3 删除定时任务：`setting-timer-delete`

json 复制代码

{ "action": "delete", "number": 1, "type": "setting" }

number 指定要删的任务编号，删除不可逆 ，返回 success:true。

10.1.4 倒计时任务：`setting-timer-countdown`

"从现在起 N 秒后执行某动作"，比定时任务更适合"临时、相对时间"的场景（如"1 小时后关掉充电"）。

字段	说明
`countdownSecond`	倒计时总时间（秒）
`finishCommand`	到点执行的动作 `{key,type}`
`task`	固定值 `"countdown"`
`timerInterval`	倒计时状态上报间隔（秒），取值 1~86400
`type`	固定值 `"setting"`

json 复制代码

{
  "countdownSecond": 3600,
  "finishCommand": { "key": 0, "type": "event" },
  "task": "countdown",
  "timerInterval": 5,
  "type": "setting"
}

设备会按 timerInterval 周期自动上报 setting-timer-countdown-active，字段含 countdownSecond、remainingSecond、state：

`state`	含义
0	待启动
1	正在进行
2	结束

于是平台能画出"剩余时间进度条"，用户随时知道还有多久断电。清除倒计时用 setting-timer-countdown-clear：

json 复制代码

{ "task": "countdown-clear", "type": "setting" }

10.1.5 一份可复用的 Python 封装

python 复制代码

import json, time, uuid
import paho.mqtt.client as mqtt
from paho.mqtt.enums import CallbackAPIVersion

BROKER, PORT = "192.168.1.10", 1883
MAC = "28372fcbbbb8"                                  # 设备 MAC（小写）
TOPIC_CMD = f"gemeopen/gspm1b/{MAC}/command"          # 设备订阅 → 我们发布
TOPIC_RPT = f"gemeopen/gspm1b/{MAC}/report"           # 设备发布 → 我们订阅

client = mqtt.Client(CallbackAPIVersion.VERSION2, client_id="gspm1b-console")

def new_message_id() -> str:
    return time.strftime("%Y%m%d%H%M%S") + uuid.uuid4().hex[:4]

def send(cmd: dict) -> None:
    cmd = {"messageId": new_message_id(), **cmd}
    client.publish(TOPIC_CMD, json.dumps(cmd), qos=1)

# ① 每天 08:00 通电
send({"command": {"key": 1, "type": "event"},
      "hour": 8, "minute": 0, "number": 1,
      "repeat": "day", "task": "timer", "type": "setting"})

# ② 每天 22:30 断电
send({"command": {"key": 0, "type": "event"},
      "hour": 22, "minute": 30, "number": 2,
      "repeat": "day", "task": "timer", "type": "setting"})

# ③ 查询设备里已存的任务
send({"action": "timerTaskQuery", "type": "event"})

# ④ 1 小时后自动断电
send({"countdownSecond": 3600,
      "finishCommand": {"key": 0, "type": "event"},
      "task": "countdown", "timerInterval": 5, "type": "setting"})

# ⑤ 撤销倒计时
send({"task": "countdown-clear", "type": "setting"})

10.2 设备端定时 vs 平台端策略引擎：如何分工

很多人第一次集成都会问："定时到底做在设备里，还是做在服务器上？" 正确做法是两条腿走路，按"可靠性 vs 灵活性"分工。

维度	设备端定时（`setting-timer-task`/`countdown`）	平台端策略引擎（服务端下发 `controller-event`）
依赖网络	不依赖，断网/断云照常执行	依赖 Broker 与后端可用
精度	到分钟	可达秒级
条件复杂度	简单（时/分/星期/一次/倒计时）	复杂（多条件、联动、节假日、峰谷电价、传感器触发）
多设备联动	不支持	支持（一个事件触发 N 台设备）
可审计	弱	强（每个下发都有日志）
修改成本	需逐台下发	改一条数据库记录即可
典型用途	安全兜底：实验室/车间到点强制断电	柔性编排：工作日历、节能策略、场景联动

分工口诀：底线安全放设备端，柔性编排放平台端，二者叠加就是"双保险"。

平台端怎么做？以本系列配套的"实验室智慧用电管理系统"为例，后端用一张 schedule 表描述策略（time_hhmm、action 取 on/off、关联 device_id），到点由调度器把 action 翻译成 MQTT 指令下发：

python 复制代码

# 平台侧：到点把策略翻译为设备指令
def fire_schedule(device_mac: str, action: str):
    payload = {"key": 1 if action == "on" else 0, "type": "event"}
    payload["messageId"] = new_message_id()
    client.publish(f"gemeopen/gspm1b/{device_mac}/command",
                   json.dumps(payload), qos=1)

注意平台侧"乐观更新设备影子"：下发成功后即把本地状态标记为 on/off，等设备的上行 controller-event（含 key、source:"command"）回来再校正，避免界面卡顿又能最终一致。同时为关键回路在设备端再设一条保底定时（如每天 22:30 断电），即使后端宕机、Broker 挂掉，插座也会自己断电。

10.3 典型案例

案例 A：实验室定时断电（安全兜底）

高校化学实验室夜间无人值守，曾发生电热套忘记关引发险情。方案：每台高功率实验仪器插座设 setting-timer-task 每日 22:30 强制断电（command.key=0，repeat:"day"），白天 08:00 通电。关键点：这条定时写在设备里，即便校园网维护、服务器重启，插座照断不误。平台侧再加一条"夜间电流不为 0 即告警"，双保险。

案例 B：门店定时开关灯

连锁奶茶店 22:00 打烊。门店招牌/灯箱/背景音乐走一个 GSPM1B2。配置：repeat:"week"，周一至周日 10:00 通电、22:00 断电。相比人工每天开关，一年省下"忘关灯"造成的电费与人工巡检成本；遇节假日用平台端临时覆盖（下发一次性 controller-event），设备端保底逻辑不动。

案例 C：设备轮换运行（延长寿命）

某检测站有 A、B 两台同型号恒温设备，长期只跑 A 导致 A 提前老化。方案：两台各配 1 台 GSPM1B2，平台端按周轮换------单周 A 通电 B 断电，双周反之，各用一次 repeat:"week" 定时实现。设备端负责"到点切换"，平台端负责"按周分配角色"，把设备寿命拉平，减少单点故障。

本章要点 / 落地清单

安全类"必须断电"的动作，一律写进设备端 setting-timer-task，不依赖网络。
复杂条件（工作日历、峰谷、传感器触发、联动）放平台端。
上线前用 info-timer-task-query 读回设备任务列表，与平台配置做对账。
临时性动作优先用 setting-timer-countdown（相对时间），别硬排绝对时间点。
倒计时任务用 setting-timer-countdown-active 的 remainingSecond 做可视化。

第 11 章安装与施工：电气是底线

一句话点题： 软件写错能回滚，电接错会起火------施工是整条链路里唯一"不可马虎"的环节。

11.1 安装形态与适用场合

GSPM1B2 的产品形态是智能转换器插座 ：它自己插在原有的墙壁插座上，再对外提供三孔/两孔输出（尺寸仅 49mm × 59mm × 28mm，非常小巧）。这一形态决定了它的核心优势------免布线、免电工、即插即用。

安装形态	代表形态	安装难度	适用场合	限制
转换器插座（本产品）	插墙上插座再用	极低（0 布线）	存量改造、租赁物业、临时用电、实验台	占用一个墙插；受原墙插回路容量约束
86 盒嵌墙	标准 86 型墙壁插座（如 GSPW 系列）	中（需电工）	新建/装修、固定工位	需开槽接线
导轨/通断器	配电箱导轨安装（如 GSCW 系列通断器）	中高	车间主管路、分支回路	需专业电工与配电箱空间

选型建议 ：酒店客房、长租公寓、联合办公、门店这类"不能砸墙、又要快速上线 "的场景，优先选 GSPM1B2；新建产线、需要藏在配电箱里的，才上导轨通断器。施工前务必先确认原墙插所在回路的断路器容量，插座自身 10A，但整条回路可能还挂别的负载。

11.2 接线、负载匹配、阻性/感性负载

GSPM1B2 是转换器形态，用户无需二次接线 ，但"负载侧怎么用"才是安全的关键。

11.2.1 正确理解 10A / 2500W 边界

官方参数是 最大负载电流 10A 、额定功率 MAX 2500W（阻性负载）。这两个数字不是"随便哪个都能到"：

10A 是硬约束：它是流过插座继电器触点的电流上限，任何负载都不能长期超过。
2500W 是功率上限，但随电压浮动 ：2500W ≈ 250V × 10A。我国民用市电标称 220V，此时 10A 对应约 2200W ；电压越高，能带的功率越大。所以先看电流，再按实际电压折算功率，永远以 10A 为准绳。
"2500W"的隐藏前提是"阻性负载"：即功率因数≈1 的纯电阻负载，才可能逼近这个上限。

估算公式：

复制代码

估算电流 I = P / (U × cosφ)

其中 P 为设备功率(W)，U 为实际电压(V)，cosφ 为功率因数。只要算出来的 I > 10A，就绝对不能用。

11.2.2 阻性 / 感性 / 容性负载的差异

负载类型	举例	功率因数	启动浪涌	建议
阻性	电热丝、电水壶、白炽灯、电暖器	≈1.0	≈1 倍	可接近额定值，但建议留 20% 余量（≤8A）
感性	电机、水泵、风机、压缩机、变压器	0.6~0.85	3~8 倍	大幅降额；大功率感性负载经接触器间接控制
容性	大电容、部分 LED 驱动电源	0.5~0.9	涌流大	关注启动涌流，避免多台同时上电

为什么感性负载要格外小心？ 电机启动瞬间电流可达额定的 3~8 倍。若一台标称 800W 的水泵在 220V 下工作电流已接近 3.6A，启动瞬间可能冲到 15~25A，远超 10A，长期如此会烧蚀继电器触点。

GSPM1B2 的硬件底气 ：主控 ESP32 内置过零检测 ，配合 16A 宏发 HF32FV-16 继电器，可实现过零投切 ------在交流电压/电流过零点附近闭合/断开，把浪涌和电弧降到最低，这正是它敢用 16A 继电器去承担 10A 额定负载的原因（留足安全余量）。但过零投切只能减少突变，不能消除感性负载持续大电流，所以大功率电机仍要走接触器。

11.3 批量配网与施工流程（含可打印工序卡）

单台好装，批量才是工程。酒店 200 间客房、写字楼 30 个公区，靠人工一台台点太慢，必须流程化。

11.3.1 配网与指向自建服务器

设备通过 setting-wifi-config 入网：

json 复制代码

{ "ssid": "Office-WiFi", "password": "xxxxxx" }

要让设备连到你自己的 Broker ，用 setting-mqtt 下发自定义参数：

json 复制代码

{
  "server": "192.168.1.10", "port": 1883,
  "publish": "gemeopen/gspm1b/28372fcbbbb8/report",
  "subcribe": "gemeopen/gspm1b/28372fcbbbb8/command",
  "clientId": "gspm1b-28372fcbbbb8",
  "username": "device", "password": "device-pass",
  "type": "custom"
}

⚠️ 易错点 ：publish 是设备"发布"的主题（你要订阅 ），subcribe 是设备"订阅"的主题（你要发布 ）。原文拼写就是这样。setting-mqtt 改完必须断电重启或发 controller-restart 才生效。

配网完成后建议锁配网 （setting-wifi-lock，wifiLock:1）与锁按键 （setting-key-lock，keyLock:1)，防止终端用户误改。

11.3.2 可打印施工工序卡

序	工序	操作	工具/指令	校验	签字
1	点位核对	按图纸确认墙插点位、回路、断路器容量	图纸、验电笔	回路容量 ≥ 设计负载	☐
2	预置 Broker	提前在电脑写好批量配网脚本与 broker 参数	脚本、`setting-mqtt` 参数表	参数与主题命名一致	☐
3	上电入网	插入插座，发 `setting-wifi-config`	手机/脚本	上报出现	☐
4	切服	下发 `setting-mqtt` → `controller-restart`	脚本	自建 Broker 收到 `info-all`	☐
5	身份登记	读取 `info-all`，记录 `mac`、`ip`、`version`	脚本	MAC 与标签一致	☐
6	贴标	插座背面 + 配电表贴同一编号	标签机	编号唯一	☐
7	通断测试	发 `controller-event` key=1/0	脚本	`key` 状态回显正确	☐
8	上报校验	设 `device-timer-interval` 定时上报	脚本	周期收到 `device-timer-task`	☐
9	信号记录	记录 `signal`（dBm）	`info-all`	≥ -70dBm 为佳	☐
10	策略下发	下发 `setting-timer-task` 保底定时	脚本	`info-timer-task-query` 读回一致	☐

11.3.3 批量配网脚本示意

python 复制代码

import json, time, paho.mqtt.client as mqtt
from paho.mqtt.enums import CallbackAPIVersion

def provision_one(mac: str, ssid: str, pw: str, broker: dict):
    topic_cmd = f"gemeopen/gspm1b/{mac}/command"
    cli = mqtt.Client(CallbackAPIVersion.VERSION2, client_id=f"provision-{mac}")
    cli.connect(broker["server"], broker["port"], 60)
    cli.loop_start()
    # 1) 配网
    cli.publish(topic_cmd, json.dumps(
        {"messageId": str(int(time.time())), "ssid": ssid, "password": pw}))
    # 2) 切到自建 Broker
    cli.publish(topic_cmd, json.dumps({
        "messageId": str(int(time.time())),
        "server": broker["server"], "port": broker["port"],
        "publish": f"gemeopen/gspm1b/{mac}/report",
        "subcribe": f"gemeopen/gspm1b/{mac}/command",
        "clientId": f"gspm1b-{mac}",
        "username": broker["username"], "password": broker["password"],
        "type": "custom"}))
    # 3) 重启生效
    cli.publish(topic_cmd, json.dumps(
        {"messageId": str(int(time.time())), "system": "restart", "type": "setting"}))
    time.sleep(3); cli.loop_stop(); cli.disconnect()

11.4 安全规范与验收要点

施工规范

插座不可串联排插再接大功率设备，避免"插座摞插座"。
保持散热空间（工作温度 -5℃ ~ +40℃），远离水源、蒸汽、易燃物。
回路断路器与漏电保护器容量要与负载匹配；GSPM1B2 不是漏保，不能替代漏电保护。
金属外壳类设备务必可靠接地。
避免同一插座频繁大功率通断，减少继电器机械磨损。

验收清单

项	方法	合格标准
通断	`controller-event` key=1/0	`key` 回显正确、继电器有声
计量	`info-statistic`	`voltage/current/power/energy` 合理
上报	`device-timer-interval`	按 `timerInterval` 周期收到 `device-timer-task`
信号	`info-all` 的 `signal`	0~-50 最好，-50~-70 较好，-70~-80 一般，-80~-100 较差
上电行为	`setting-on-state`（0记忆/1关闭/2开启）	与业务要求一致（安全类建议 1）
锁定	`setting-wifi-lock` / `setting-key-lock`	现场不可随意改
断电保持	断电重启后 `info-timer-task-query`	定时任务仍在
电量归零	`energy-clear`	`energy` 归零且断电不丢

本章要点 / 落地清单

牢记 10A 是硬约束，2500W 是"阻性负载 + 250V"上限，感性负载必须降额或走接触器。
优先选转换器形态解决"免布线、快速上线"；回路容量先算再装。
批量施工走工序卡：预置 Broker → 逐台上电 → 切服 → 校验 → 贴标。
上线即锁配网/按键，设好上电默认状态（安全类设"关闭"）。
缺一不可的验收项：通断、计量、上报、信号、断电保持。

第 12 章与传统电子用电设备对接

一句话点题： 插座不只是插台灯的，它是"弱电指挥强电"的开关量接口------用对了，能让一堆老设备开口说话。

12.1 用插座驱动接触器 / 中间继电器 → 间接控制大功率设备

GSPM1B2 的输出能力是 220V / 10A 。当被控设备是大功率（三相电机、中央空调外机、大功率烘干机）时，不能让插座直接带 ，而是让插座去驱动接触器/中间继电器的线圈，用线圈去控制主触点。

原理链 ：GSPM1B2 输出 220V → 接触器线圈吸合 → 接触器主触点闭合 → 大功率负载得电

复制代码

  市电L ──┐
          ├── GSPM1B2 输出 ── 接触器线圈(A1/A2) ── 市电N
  市电N ──┘                        │
                                   ▼（线圈吸合）
  三相电源 L1/L2/L3 ── 接触器主触点(T1/T2/T3) ── 大功率负载

选型要点

接触器线圈选 AC 220V 型（如 CJX2 系列），线圈功耗通常只有几 VA，远小于 10A，插座完全带得动。
中间继电器（如 JQX-13F）用于信号中转：插座输出 220V 给线圈，它的无源触点再去闭合别的回路。
GSPM1B2 的继电器是磁保持类机械触点 ，通断电状态能长期保持，非常适合驱动需要"长时间吸合"的接触器（不像脉冲继电器会自行复位）。

控制代码（就是最普通的通断电指令）：

python 复制代码

def set_relay(on: bool) -> None:
    """on=True 通电（线圈吸合→大设备开机），False 断电。"""
    send({"key": 1 if on else 0, "type": "event"})   # controller-event

注意：磁保持继电器适合"少次、长时"的开关。若需高频通断（如按分钟启停），应把动作交给接触器/变频器，插座只做"使能"信号，交给它自己完成频率控制。

12.2 控制电机、水泵、风机等感性负载的注意点

负载	典型启动倍数	建议控制方式
小风扇、微型水泵（<150W）	3~5 倍	可经插座直接控制，但按 5A 以内降额
工业水泵、风机（>500W）	5~8 倍	必须经接触器/软启动/变频器，插座只驱动线圈
压缩机（冷柜、空调）	6~8 倍	经接触器；考虑启动延时、防频繁启停
三相设备	---	插座仅做控制信号，主回路走三相接触器

核心注意事项

降额：感性负载建议按额定功率的 40%~50% 使用，或把工作电流控制在 5A 以内。
过零投切：GSPM1B2 内置过零检测 + 过零投切，能显著降低闭合瞬间的浪涌与触点电弧，这是它比普通机械插座更适合带感性负载的关键。
防频繁启停 ：电机频繁启停会发热、缩短寿命，也应避免继电器频繁动作；用 setting-timer-countdown 或平台端做最小间隔保护。
堵转保护 ：水泵堵转电流大，建议监测 current，超过阈值即由平台下发 controller-event 断电。
消弧：大感性负载接触器建议加 RC 吸收或压敏电阻，保护触点。

python 复制代码

# 电流超阈值（堵转）自动断电
def on_report(msg):
    if msg.get("commandName") == "info-statistic" and msg.get("current", 0) > 8.0:
        set_relay(False)          # 立即断电保护

12.3 老旧设备与非智能电器的"智能化改造"方法论

给"没有联网能力"的老设备加智能，本质是寻找一个可被通断电控制的供电点或信号点。推荐四步法：

第一步 · 识别供电点：老设备能否"插座化"？能插插座的（饮水机、电暖器、老式展示柜）直接用 GSPM1B2；已硬接线的走导轨通断器。

第二步 · 判断控制逻辑：

只关心"通/断"（大多数设备）→ 直接控制。
断电后重来电会"自启动"的设备要小心：上电默认状态 用 setting-on-state 设为 2（开启）或 1（关闭）来匹配业务。比如"断电即安全停机"的设备，设 1；"需要断电恢复后自动运行"的，设 2。
需要保留设备自身开关的，用"串联"方式把插座串在供电线上，设备开关仍可用。

第三步 · 选择接入层：小功率直控 → 大功率经接触器 → 只取信号经干接点。

第四步 · 叠加计量与策略 ：用 GSPM1B2 的 voltage/current/power/energy 采集老设备的工作时长、能耗、异常，再用定时/平台策略让它"定时开关、异常断电"。老设备至此完成"智能化改造"。

风险红线 ：凡是"断电会引发安全事故"的设备（UPS 输出、生命支持类、消防设备），绝不串联智能插座。

12.4 信号对接：干接点、RS-232/485、PLC 协同

先讲清一个事实：GSPM1B2 的对外接口是 220V 通断（继电器）+ 2.4GHz WiFi（MQTT / TCP Client / 内网 HTTP） ，它本身没有 RS-232/485 串口 ，也没有标准"干接点输出"。所以"信号对接"要借助外部器件或上位机完成，不能臆想设备自带串口。

12.4.1 干接点（Dry Contact）

需要"无源触点"给第三方系统 （门禁、消防、PLC 的 DI）：用一个中间继电器 把插座的 220V 输出转成无源触点。插座通电→中间继电器线圈得电→其常开触点闭合，作为干接点送给外部系统。插座本身输出的是有源 220V，不能直接当干接点用。
反向：第三方系统的干接点要去触发一个动作，可以用它驱动一个小中间继电器，再由上位机读该继电器状态（或直接由上位机通过 MQTT 桥接），不建议用干接点直接"骗"插座。

12.4.2 RS-232 / 485

GSPM1B2 无串口，但可用 协议网关/上位机 桥接：上位机（工控机、树莓派）一头跑 Modbus RTU（RS-485）对接 PLC/仪表，另一头跑 MQTT 与插座通信，做双向翻译 ：
- PLC 侧写线圈 → 上位机读 Modbus → 上位机发 controller-event 给插座；
- 插座上报 info-statistic/controller-event → 上位机写回 Modbus 寄存器 → PLC 读状态。
这样 GSPM1B2 就成了 Modbus/PLC 系统里的一个"WiFi 远程 IO 点"。

12.4.3 PLC 协同的实用模式

模式	数据流	适用
插座作"执行末端"	PLC → 网关/上位机 → MQTT → 插座通断	PLC 逻辑控制远端设备
插座作"状态回读"	插座上报 `key`/`current` → 上位机 → PLC 寄存器	PLC 需要知道远端设备是否真在运行
插座作"联锁节点"	插座状态参与 PLC 互锁逻辑	安全联锁（如"排风未开则禁止加热"）

联锁与故障安全 ：涉及安全联锁时，默认失败方向必须是"安全侧" （Fail-Safe），例如"通信中断一律断电"。可结合上电默认状态 setting-on-state 与平台端心跳检测实现：超过 N 个上报周期没收到 device-timer-task，即判定离线并下发断电。

python 复制代码

import time
last_seen = {}

def on_any_report(mac: str, msg: dict):
    last_seen[mac] = time.time()

def watchdog(stale_seconds: int = 180):
    """离线看门狗：安全场景下，通信中断即断电。"""
    now = time.time()
    for mac, ts in list(last_seen.items()):
        if now - ts > stale_seconds:
            client.publish(f"gemeopen/gspm1b/{mac}/command",
                           '{"key":0,"type":"event","messageId":"wd"}')

本章要点 / 落地清单

大功率/感性/三相设备，一律经接触器/中间继电器间接控制，插座只驱动线圈。
感性负载按额定 40%~50% 降额，善用过零投切与最小启停间隔。
老设备改造四步法：找供电点 → 定控制逻辑 → 选接入层 → 加计量与策略。
牢记 GSPM1B2 无 485 口、无干接点，信号对接靠中间继电器/网关/上位机桥接。
安全联锁默认"通信中断=断电"（Fail-Safe），用离线看门狗落地。

第 13 章应用场景 20+ 例（上）：编号 1~11

一句话点题： 前面三章是"弹药"，这一章开始"打靶"------每个场景都给出谁在用、怎么装、怎么配、值多少。
统一结构：场景与痛点 → 方案设计 → 设备选型与数量 → 关键代码/配置要点 → 价值与收益

场景 1 · 高校实验室

场景与痛点：化学、材料、电子类实验室仪器多、用电大；夜里无人值守，电热类设备忘关险情高发；导师要掌握各实验台能耗与开机时长。
方案设计：每个实验台/每台高功率仪器配 1 台 GSPM1B2，采集电压电流功率电量；设备端设"每日 22:30 强制断电"保底定时；平台端叠加"夜间电流不为 0 告警"与"仪器停机时长统计"。
设备选型与数量：按实验台 1:1 配置；一个 30 台仪器的实验室约 30 台。
关键代码/配置要点 ：setting-timer-task（22:30，key=0，repeat=day）；device-timer-interval 设 60s 上报；info-statistic 抄读 energy。
价值与收益：夜间断电兜底显著降低电气火灾风险；分台能耗核算让经费分摊有据可依；开机时长数据支撑仪器利用率评估。

场景 2 · 科研院所

场景与痛点：大型仪器（真空泵、恒温箱、离心机）需 7×24 或定时运行，断电即造成样品损毁；要求断电后能记录"谁在什么时候断了电"。
方案设计 ：贵重仪器回路用 GSPM1B2 计量 + 平台端全量操作审计；设定"仅授权角色可断电"；对不允许断电的设备设 setting-on-state=2（来电自启）并加离线看门狗防误断。
设备选型与数量：重点仪器每台 1 台，全所通常 20~100 台。
关键代码/配置要点 ：setting-key-lock 锁按键；setting-timer-countdown 做"预约停机"；审计日志记录每次 controller-event。
价值与收益：样品安全与可追溯并重；避免误操作导致的高价值实验报废。

场景 3 · 企业研发中心

场景与痛点：可靠性实验室、EMC 房、老化测试台长期无人；测试设备需"跑够时长后自动停"；研发用电要按项目分摊。
方案设计 ：老化台每工位 1 台 GSPM1B2；用 setting-timer-countdown 实现"跑满 N 小时后自动断电"；平台按项目/工位统计 energy。
设备选型与数量：按工位数 1:1，中型研发中心 30~80 台。
关键代码/配置要点 ：{"countdownSecond": N*3600, "finishCommand":{"key":0,"type":"event"}, "task":"countdown"}；用 setting-timer-countdown-active 的 remainingSecond 显示倒计时。
价值与收益：测试不再"跑过夜没人管"；项目能耗分摊清晰；无人值守时段安全可控。

场景 4 · 联合办公

场景与痛点：共享工位、会议室的饮水机、投影、咖啡机常整夜待机；租户进出不固定，公区用电难管。
方案设计：公区电器按区域配 GSPM1B2；设备端设"工作日 09:00 通电 / 21:00 断电"，周末全断；会议室用平台端"扫码通电、离开自动倒计时断电"。
设备选型与数量：每个公区/会议室 1~3 台，中型空间 20~40 台。
关键代码/配置要点 ：repeat:"week" 工作日定时；会议场景下发 controller-event key=1 + setting-timer-countdown 2 小时。
价值与收益：消除"整夜待机"电费；公区管理从"人工巡检"变"自动运行"。

场景 5 · 写字楼（公区）

场景与痛点：大堂灯、走廊灯、卫生间排气、广告屏等公区设备多、分布广，物业能耗高、巡检累。
方案设计：按楼层/区域分组配 GSPM1B2；照明按"工作日/节假日"两套定时；排气扇定时运行；广告屏按营业时段开关。
设备选型与数量：每层 2~5 台，整栋楼可达上百台。
关键代码/配置要点 ：多台批量下发同一套 setting-timer-task；用主题 gemeopen/gspm1b/+/report 通配订阅统一纳管。
价值与收益：公区电费明显下降；物业少雇巡检人力；照明/排气按需运行更舒适。

场景 6 · 中小学校园

场景与痛点：教室多媒体、饮水机、风扇用电时段集中；安全教育要求"人走断电"；总务处想掌握各年级用电。
方案设计：教室按班级配 GSPM1B2；设备端设"上学日 07:30 通电 / 18:00 断电"；饮水机加定时；家长/学校端可视化用电。
设备选型与数量：按班级数配，一所学校 30~60 台。
关键代码/配置要点 ：setting-timer-task repeat:"week"；寒假/暑假由平台端批量覆盖为"寒假模式"。
价值与收益：落实"人走断电"安全要求；用电可视化助力节能宣传；假期灵活覆盖不误事。

场景 7 · 职业院校

场景与痛点：实训室（电工、焊工、数控、汽修）设备多且用电大；实训按课时开停；学生操作误用电源风险高。
方案设计：每个实训工位 1 台 GSPM1B2，随课表定时通电/断电；权限交给实训教师；对高功率焊接类设备经接触器间接控制。
设备选型与数量：按工位配，单个实训楼 50~200 台。
关键代码/配置要点 ：课表映射为多条 setting-timer-task；setting-key-lock=1 防学生误操作；大功率走接触器。
价值与收益：实训用电"随课启停"；安全事故与误操作双降；与教学管理系统打通可自动排程。

场景 8 · 酒店客房

场景与痛点：客房数量多、改造不能砸墙；住客离房后电器常空转；需要"无人自动断电、有人自动恢复"。
方案设计：客房内电器（热水壶、电视、台灯）走 GSPM1B2，插原墙插即用；结合门磁/取电卡状态平台联动；退房后按倒计时断电。
设备选型与数量：每间客房 1~2 台，200 间酒店约 300~400 台。
关键代码/配置要点 ：批量配网脚本；setting-timer-countdown 做"退房延时断电"；setting-on-state=1 保证来电默认关闭。
价值与收益：免布线改造、上线快；客房空置电耗下降；提升住客体验与酒店节能形象。

场景 9 · 长租公寓

场景与痛点：公寓分散、租户流动、收费难；"欠费不断电"与"恶意拖欠"两难；房东远程管理需求强。
方案设计 ：入户总插座位置配 GSPM1B2，做预付费/欠费断电 ：平台监测 energy 与账单，欠费自动下发 key=0，缴费后 key=1；退租一键断电。
设备选型与数量：每户 1 台，100 户公寓 100 台。
关键代码/配置要点 ：energy-clear 用于每个租期清零；结合 controller-event 实现远程通断；setting-wifi-lock=1 防租户改网。
价值与收益：电费回收率提升；远程管理省去人工上门；租期能耗账单透明。

场景 10 · 商超门店

场景与痛点：招牌、冷藏柜、收银、灯带、空调按营业时段开关；总部要管连锁门店能耗；节假日营业时间不同。
方案设计：招牌/灯带走 GSPM1B2 定时；冷柜长时间不断电仅做监测告警；收银区按营业时间供电；总部平台统一管理多门店。
设备选型与数量：单店 5~15 台，连锁 100 店约 500~1500 台。
关键代码/配置要点 ：按 store_id 统一主题前缀；setting-timer-task 按营业时间；平台端对冷柜只监测不随意断电。
价值与收益：招牌灯按点开、不白亮；连锁能耗可比、可排名；减少"忘关灯/忘关空调"损失。

场景 11 · 餐饮后厨

场景与痛点：后厨大功率电磁炉、蒸柜、消毒柜、排风多；油烟潮湿、安全要求高；打烊必须断电。
方案设计：小功率电器直连 GSPM1B2；大功率蒸柜/烤箱经接触器；排风与主灶联锁（主灶通电则排风必开）；打烊定时断电。
设备选型与数量：单店 8~20 台。
关键代码/配置要点 ：setting-timer-task 打烊断电；平台端做联锁逻辑；current 超阈值告警。
价值与收益：打烊断电消除火灾隐患；大功率安全间接控制；排风联锁改善后厨环境。

本章要点 / 落地清单

上篇 11 个场景覆盖"科研/教育/办公/住宿/商业"五大类，选型逻辑一致：小功率直控、大功率经接触器。
安全类场景（实验室、后厨、实训室）务必叠加设备端保底定时。
分散多门店/多楼层用统一主题 + 批量脚本纳管，避免逐台人工。
欠费/预付费场景靠 energy + controller-event 组合实现。

第 14 章应用场景 20+ 例（下）：编号 12~24

一句话点题： 从工厂到田间、从基站到水族箱------只要"电需要被按需开关"，GSPM1B2 就有用武之地。
统一结构：场景与痛点 → 方案设计 → 设备选型与数量 → 关键代码/配置要点 → 价值与收益

场景 12 · 小型工厂车间

场景与痛点：车间用电大、设备多；夜班/白班时段不同；空压机、冷却泵常空转；缺乏分设备能耗数据。
方案设计：小型单相设备直连 GSPM1B2，大功率经接触器；按班次定时；对空压机做"压力/时间"双条件控制；分设备计量。
设备选型与数量：按设备/工段配，中小厂 20~80 台。
关键代码/配置要点 ：setting-timer-task 按班次；info-statistic 采集；超 current 告警。
价值与收益：空转电费下降；分设备能耗可见；夜班安全断电。

场景 13 · 自动化产线辅助

场景与痛点 ：产线辅助设备（气泵、除尘、照明、风扇）需与主产线同步启停；主设备停而辅助设备仍在跑造成浪费。
方案设计 ：辅助设备走 GSPM1B2；上位机/PLC 通过 MQTT 联动，主产线启停时同步下发 controller-event；辅助设备状态回读参与联锁。
设备选型与数量：每条产线 3~10 台。
关键代码/配置要点：PLC→网关→MQTT 桥接；联锁"主停则辅全停"；离线看门狗 Fail-Safe。
价值与收益：辅助设备不再空转；启停同步减少人为遗漏；能耗与产线节拍对齐。

场景 14 · 农业大棚 / 温室

场景与痛点：补光灯、水帘、风机、灌溉泵需按光照/温度/湿度开启；地处偏远、人工巡棚成本高。
方案设计：补光灯、水泵、风机走 GSPM1B2；结合温湿度传感器平台联动（湿度低开灌溉、温度高开风机）；按日出日落设补光定时。水泵属感性负载，按降额或经接触器。
设备选型与数量：单棚 2~6 台，园区几十到上百台。
关键代码/配置要点 ：setting-timer-task 做补光时段；平台规则"传感器阈值→controller-event"；水泵用 setting-timer-countdown 限时灌溉。
价值与收益：减少人工巡棚；按需补光/灌溉节水节电；恶劣天气远程处置。

场景 15 · 畜禽养殖

场景与痛点：猪舍/鸡舍通风、保温灯、喂料、清粪设备需 24 小时可靠运行；断电或风机停转会造成畜禽应激甚至死亡。
方案设计 ：风机、保温灯走 GSPM1B2 并只做监测与告警为主，避免误断；喂料机按时间定时运行；关键风机加"离线即告警"。
设备选型与数量：每栋舍 3~10 台。
关键代码/配置要点 ：setting-on-state=2（来电自启，保通风）；上报中断即告警；喂料机用 setting-timer-task。
价值与收益：关键通风设备运行有据可查；减少因断电导致的损失；喂料定时降低人工。

场景 16 · 通信基站

场景与痛点：基站/机房空调、照明、排风用电大；偏远站点无人；需远程重启空调/排风应对高温。
方案设计：基站单相空调、排风、照明走 GSPM1B2；远程通断；结合温度告警"高温自动开空调/排风"；避免主设备供电被误断。
设备选型与数量：每站 2~5 台，运营商规模可达数千台。
关键代码/配置要点 ：controller-event 远程通断；温度阈值联动；仅控制辅助设备，不碰主供电。
价值与收益：减少上站次数；空调按需运行省电；高温风险远程化解。

场景 17 · 数据中心 / 机房

场景与痛点 ：机房对供电稳定性极敏感；但照明、测试位、临时设备可被按需管控；机柜内小设备（风扇、跳线灯）需精细化。
方案设计 ：仅对非关键负载 （运维照明、临时工位、测试设备）用 GSPM1B2；关键 IT 设备绝不经插座；配合 PDU/列头柜使用。
设备选型与数量：每机房 5~20 台（非关键负载）。
关键代码/配置要点 ：明确"管控白名单"；测试位用 setting-timer-countdown 限时；能耗计量用于 PUE 辅助分析。
价值与收益：非关键负载按需供电；临时工位不再忘记关；精细化能耗辅助节能。

场景 18 · 仓储物流

场景与痛点：仓库照明、充电区、传送带、叉车充电桩用电集中；夜间照明与安防需在岗；充电区过充风险。
方案设计 ：仓库照明按作业时段定时；叉车/设备充电用 setting-timer-countdown 防过充；传送带随作业启停。
设备选型与数量：单个仓 10~40 台。
关键代码/配置要点 ：setting-timer-task 照明；充电桩用倒计时 + current 监测；超阈值断电。
价值与收益：照明按需、充电防过充；作业区用电与班次同步。

场景 19 · 路灯 / 景观照明

场景与痛点：路灯、景观灯按日落开、日出关，冬夏时间不同；人工统一开关误差大、费人力。
方案设计：每条回路/每段景观灯走 GSPM1B2（小功率段）或经接触器（大功率段）；按季节设不同定时；节假日单独策略。
设备选型与数量：按回路配，一个园区 10~50 台。
关键代码/配置要点 ：setting-timer-task 按季节；平台端批量改"夏令/冬令"；日落偏移用平台端计算后覆盖。
价值与收益：不再"天亮还亮灯"；省人工、省电费；节假日灯光策略灵活。

场景 20 · 充电桩配套

场景与痛点：两轮/三轮电动车充电、"飞线充电"火灾频发；需要限时充电、防过充、防私拉。
方案设计：在充电插口位置配 GSPM1B2，做"扫码启动 + 限时倒计时断电 + 电流异常断电"；充满或到点自动断。
设备选型与数量：每个充电位 1 台，车棚几十台。
关键代码/配置要点 ：setting-timer-countdown 限时；current 低于阈值判断"充满"；超阈值判断异常。
价值与收益：从源头遏制"飞线充电"火灾；充电限时提高车位周转；用电可计量收费。

场景 21 · 共享设备

场景与痛点：共享充电宝柜、共享按摩椅、共享洗衣机需要"按时长计费、到点断电"；设备分散、无人值守。
方案设计：共享设备供电走 GSPM1B2；平台按订单下发"通电启动 + 倒计时断电"；计量用于计费与耗材分析。
设备选型与数量：每台共享设备 1 台。
关键代码/配置要点 ：下单 → controller-event key=1 + setting-timer-countdown；结束时 setting-timer-countdown-clear；energy 计费。
价值与收益：计费与供电一致；无需现场值守；设备故障可远程断电复位。

场景 22 · 家庭 / 公寓

场景与痛点：忘记关电热毯/电暖器；想让鱼缸灯、路由器、热水器按需运行；独居老人用电安全关切。
方案设计：家庭各类电器配 GSPM1B2；电热类设保底断电定时；热水器按用水高峰预热；离家一键断电场景。
设备选型与数量：每户 5~15 台。
关键代码/配置要点 ：setting-timer-task 保底；setting-timer-countdown 做"临时延时断电"；离家模式批量 key=0。
价值与收益：消除忘关电器隐患；按需用电省电费；远程照护更安心。

场景 23 · 宠物 / 水族

场景与痛点：鱼缸灯需规律开关（过久爆藻、过短鱼不适）；加热棒/水泵需稳定供电；主人出差需远程把控。
方案设计 ：鱼缸灯走 GSPM1B2 定时（如每天 8 小时）；加热棒/水泵仅监测告警不随意断；出差期间远程查看 power 是否在运行。
设备选型与数量：每缸 1~3 台。
关键代码/配置要点 ：setting-timer-task 灯光时段；info-statistic 判断加热棒是否工作；断电即告警。
价值与收益：光照规律、养鱼更稳；设备停摆即时知晓；出差远程照看。

场景 24 · 广告灯箱 / 数字标牌

场景与痛点：灯箱常整夜亮、维护成本高；数字标牌需按营业时段开关；多点多店统一管理难。
方案设计：每块灯箱/每台标牌配 GSPM1B2；按营业时间定时；总部平台统一管理多门店多灯箱；能耗对比发现异常屏。
设备选型与数量：每屏/每灯箱 1 台，连锁 100 点约 100~300 台。
关键代码/配置要点 ：repeat:"week" 按营业时间；主题按 point_id 规划；energy 突变告警（可能灯管故障）。
价值与收益：灯箱按时熄、省电费；故障屏提前发现减少空耗；总部统一编排。

本章要点 / 落地清单

下篇 13 个场景覆盖"工业/农业/通信/照明/共享/民生"六大类，共性仍是先判负载性质，再定控制层级。
关键负载只监测、不随意断（养殖通风、机房 IT、水族加热），避免"智能化"变成"风险源"。
计费类场景（充电桩、共享设备、长租公寓）统一用 energy + controller-event + 倒计时三件套。
分散多点的照明/灯箱，用按点位规划主题 + 总部批量策略管理。
所有场景收尾都要回到第 11 章验收清单：信号、上报、断电保持、上电默认状态逐项确认。

附：全篇指令速查（与本部分强相关）

目的	指令名	关键字段（请求）
通断电	`controller-event`	`key`(0/1), `type:"event"`
设定时任务	`setting-timer-task`	`command{key,type}`, `hour`, `minute`, `number`, `repeat`(week/day/oneof), `task:"timer"`, `type:"setting"`
查定时任务	`info-timer-task-query`	`action:"timerTaskQuery"`, `type:"event"`
删定时任务	`setting-timer-delete`	`action:"delete"`, `number`, `type:"setting"`
设倒计时	`setting-timer-countdown`	`countdownSecond`, `finishCommand{key,type}`, `task:"countdown"`, `timerInterval`(1-86400), `type:"setting"`
倒计时上报	`setting-timer-countdown-active`	上报含 `countdownSecond`,`remainingSecond`,`state`(0/1/2)
清倒计时	`setting-timer-countdown-clear`	`task:"countdown-clear"`, `type:"setting"`
设上报频率	`device-timer-interval`	`timerEnable`(0/1), `timerInterval`(5-86400), `type:"setting"`
实时用电	`info-statistic`	`type:"statistic"`
设备信息	`info-all`	`type:"info"`
自定义 MQTT	`setting-mqtt`	`server,port,publish,subcribe,clientId,username,password,type:"custom"`（需重启）
重启	`controller-restart`	`system:"restart"`, `type:"setting"`
上电默认状态	`setting-on-state`	`onState`(0记忆/1关闭/2开启)
配网锁/按键锁	`setting-wifi-lock` / `setting-key-lock`	`wifiLock`(0/1) / `keyLock`(0/1)

主题约定（多设备纳管）：gemeopen/gspm1b/<mac>/report（设备发布，平台订阅）、gemeopen/gspm1b/<mac>/command（设备订阅，平台发布）。字段语义与拼写（含 subcribe）以 GemeOpen 官方开发文档为准。

第 4 部分 · 商用价值与运维实战（第 15~20 章）

面向对象：集成商 / 服务商 / 设备厂 / 项目负责人

本部分所有金额均为「示例测算」 ，仅为演示算式用；请把假设替换成你自己的真实数字后再下结论。凡出现数字的表，都可整表替换。

技术事实以《00-基准事实.md》为准：型号 GSPM1B2 （智能转换器插座 10A-S1 Plus-WiFi），主控 ESP32（内置过零检测），输入 AC 85~265V，最大负载 10A / 2500W，16A 宏发继电器 HF32FV-16，待机 <3W，2.4GHz WiFi。

第 15 章省钱账：一台插座帮你省了什么

本章点题： 用一套可替换的假设与算式，把「自研硬件」和「采购可二次开发成品」两条路的钱摊开算清楚。

这一章不讲情怀，只算账。算账的目的不是告诉你"一定便宜"，而是给你一套能套用自己数字的模型。看懂模型，你自己就能判断在不同产量、不同场景下，哪条路更划算。

15.1 硬件成本对比：自研硬件 vs 采购可二次开发成品

做一款"能联网、能计量、能控制"的智能插座，通常有两条路线：

路线 A：完全自研硬件 ------ 自己选芯片、画 PCB、开外壳模具、做认证、试产。
路线 B：采购可二次开发成品 ------ 直接采购 GemeOpen GSPM1B2，协议现成、可私有化部署，把精力放在软件与业务上。

先看路线 A 的一次性投入（示例测算，单位：人民币）：

成本项	示例金额	计算/说明（可替换）
硬件研发人力	18 万	硬件工程师 2 人 × 3 个月 × 3 万/人月
外壳开模	5 万	一套注塑模 3~8 万，取中值
认证（3C/CE/FCC 等）	6 万	单项 5~10 万区间，取 6 万
PCBA 打样与试产	1.5 万	打样 + 小批试产
固件开发（从零）	4.5 万	嵌入式工程师 1.5 人月 × 3 万
云平台与协议对接	2 万	协议设计 + 平台联调
一次性投入合计	约 37 万	上式相加

再看路线 B：假设成品单价 99 元/台（示例，请替换为你的实际报价区间 60~120 元）。

采购量	采购成本（示例）	自研一次性投入（示例）
100 台	9,900 元	约 37 万
1,000 台	99,000 元	约 37 万
5,000 台	495,000 元	约 37 万 + 边际成本

盈亏平衡点公式：

复制代码

单品自研成本 = 一次性投入 / 产量 + 单台边际成本
盈亏平衡产量 N* = 一次性投入 / (成品单价 − 自研单台边际成本)

代入示例：一次性投入 37 万，成品单价 99 元，自研单台边际成本取 45 元（物料+制造+返修）：

复制代码

N* = 370,000 / (99 − 45) ≈ 6,852 台

结论（示例）： 年产量需要超过约 6,850 台 ，自研才比采购划算；低于这个量，采购可二次开发成品更省，而且省的不只是钱------还有上市时间。

还需要给自研补上几笔隐性成本，它们很难在立项时估准，却会在量产后持续吞噬利润：

库存与最小起订量：物料、PCBA、外壳往往有起订门槛，卖不掉就压资金。
不良与返修：早期产品良率不稳，返修、换货、物流都是钱。
售后与备件：客户现场出问题，你得备件、得派人，周期长、体验差。
合规与责任：电气安全、认证过期、产品责任，一旦出事代价极高。

采购可二次开发成品，本质上是把这些不确定性转移给上游厂家：你按台付费、按需采购，卖多少买多少，没有库存死角，也不背产品责任。对小批量、快交付的项目，这种"轻资产"往往比账面单价更重要。

15.2 开发与调试成本：协议现成、免写固件、免驱动

路线 A 最容易被低估的不是硬件，而是软件与协议的隐性工作量。GSPM1B2 把这些都变成了"现成能力"。

现成能力清单：

协议现成 ：MQTT 主题、指令 JSON 已定义好。你只需"订阅上行、发布下行"，用 paho-mqtt 几十行就能跑通。
免写固件：不用维护 ESP32 固件，不必操心看门狗、分区表、OTA 体系。
免驱动：标准 2.4GHz WiFi + MQTT，不涉及串口驱动、专有 SDK、私有上位机。

工作量对比（示例测算，单位：人月）：

事项	自研路线	用 GSPM1B2
固件开发	3~6 人月	0
OTA 升级体系	1~2 人月	0（厂家负责）
协议设计与文档	0.5 人月	0（现成）
设备管理后台	2~3 人月	可复用现成 demo 快速改造
合计（示例）	6.5~11.5 人月	接近 0（只做对接）

示例算式：若自研额外投入约 7.5 人月，按 3 万/人月计 ≈ 22.5 万元 。这笔钱足够买 2,270 台 99 元的成品。

15.3 施工与运维成本：集中配置、远程处理

设备装到现场之后的成本，往往比设备本身更贵。GSPM1B2 的两个能力直接砍掉这部分开支：

集中配置 ：用 setting-mqtt、setting-wifi-config 等指令批量把设备指向你的 Broker / WiFi，不必逐台现场操作。
远程处理 ：controller-event（通断电）、controller-restart（重启）、controller-reset（重置）都可远程下发，减少跑现场。

施工效率对比（示例测算）：

环节	自研方案	GSPM1B2 方案
单台现场处理时间	30 分钟（刷固件+调试）	3 分钟（扫码+配网）
100 台施工总工时	50 小时	5 小时
节省工时	---	45 小时
按 150 元/小时折算	---	6,750 元

运维节省（示例测算）： 一次远程处理替代一次现场，单次现场成本（交通+工时）示例取 200 元。若每月因此减少 10 次现场：

复制代码

月度节省 = 10 × 200 = 2,000 元
年度节省 = 2,000 × 12 = 24,000 元

除了看得见的人力，还有两笔"看不见"的收益：

响应速度：过去故障要等工程师排期、跑现场，动辄一两天；现在一条指令几秒钟解决，客户感知完全不同。
运维窗口：远程操作可以在深夜、周末静默进行，不影响客户正常使用，也避免现场等待和沟通成本。

要强调的是，"集中配置"的真正威力在于规模效应：3 台设备靠人也就干了，300 台、3,000 台时，逐台现场操作几乎不可行。GSPM1B2 用指令把配置批量化，让"设备数增长"不再等于"人力线性增长"，这正是规模化项目能盈利的前提。

15.4 一张 ROI 测算表（假设随意替换）

下面这张表是"母表"。把假设列换成你的数字，结论列会自动跟着变。

项目	假设（示例，可替换）	算式	示例结果
覆盖设备数 N	100 台	---	100
成品单价 P	99 元/台	---	99
一次性采购成本	---	N × P	9,900 元
施工节省	45 小时 × 150 元/小时	直接乘	6,750 元
运维节省（年）	10 次/月 × 200 元 × 12	直接乘	24,000 元
节能收益（年）	每台省 20W 待机 × 8,760h × 0.6 元/kWh ÷ 1000 × N	见公式	≈ 10,512 元
年总收益（示例）	施工+运维+节能	6,750 + 24,000 + 10,512	≈ 41,262 元
首年净收益	年总收益 − 采购成本	41,262 − 9,900	≈ 31,362 元
ROI	净收益 / 采购成本	31,362 / 9,900	≈ 317%

节能算式展开：省电收益 = 单台节省功率(W) × 年小时数 × 电价(元/kWh) ÷ 1000 × 台数

= 20 × 8760 × 0.6 ÷ 1000 × 100 ≈ 10,512 元（示例）

提醒：以上全部为示例测算，仅用于演示算式结构，不代表任何真实报价或官方承诺。

本章要点 / 落地清单

把"一次性投入 / 边际成本 / 成品单价"三个数字换成你的真实值，算出 N*。
盘点软件隐性工作量（固件、OTA、协议、后台），这部分最容易漏算。
用 15.4 母表跑一遍你自己的 ROI，假设列务必标注来源。
明确一句话结论：小批量拼的是"省固定投入"，大批量才拼"边际成本"。

第 16 章增效：自动化管理带来的收益

本章点题： 省钱只是第一步，真正的价值是让"人不用到现场、灯不用一直亮、账不用月底才算"。

16.1 无人值守与远程运维（减少现场次数）

GSPM1B2 把"现场动作"变成"远程指令"。

任务	传统方式	用 GSPM1B2
重启设备	到现场拔插电源	发 `controller-restart`
通断电	手动拔插	发 `controller-event`（key=1/0）
恢复出厂	找按键长按	发 `controller-reset`
查设备状态	到现场看指示灯	发 `info-all` 看 `ip/mac/signal/ssid/version`
查实时用电	现场接钳形表	发 `info-statistic`

一句话：凡是"能远程做的"，就不该派人去现场。

16.2 能耗可视化与节能（找"电老虎"、错峰用电）

设备上报 voltage(V)、current(A)、power(W，视在功率)、energy(kWh，累计用电量)。四个数就能干两件大事：

（1）找"电老虎" ------ 按 power 排序，一眼看出谁在偷电：

设备	实时功率 power(W)	判定
老旧冰柜	320	24h 常开，重点
台式机+显示器	180	工作时间
投影仪	8（待机）	待机耗电，可下班断电

（2）错峰用电 / 待机断电 ------ 用定时任务 （setting-timer-task，可多组）+ 倒计时任务 （setting-timer-countdown）在低谷电价时段运行、在下班后断电。

节能测算（示例）： 某设备待机功率 8W，若每天 16 小时处于待机：

复制代码

日耗电 = 8W × 16h ÷ 1000 = 0.128 kWh
年耗电 ≈ 0.128 × 365 = 46.7 kWh
年电费 = 46.7 × 0.6 元/kWh ≈ 28 元/台

10 台这类设备，一年可省约 280 元 （示例）。数字不大，但自动执行、零人工。

能耗可视化的另一个价值是"让浪费现形 "。在没有计量之前，"这屋到底耗多少电"是个玄学；有了每台设备的 power 与 energy，浪费就变成了一行行可对比的数字。人对自己看不见的东西不会心疼，一旦把"电老虎"打印在月报上、贴在墙上，节能就从口号变成了动作。

错峰用电同样如此：有了数据，你才知道哪些负载"可延时、可避开高峰"。用一组定时任务把非关键负载安排到低谷时段运行，既省钱，也减轻了配电压力------这正是分时电价场景下最直接的收益。

16.3 安全用电（防患于未然，异常及时断电）

安全收益往往比省电更大，因为它规避的是事故损失。

过零投切 ：ESP32 内置过零检测，继电器在电压过零点动作，减少浪涌冲击，延长负载寿命。
异常用电告警 + 自动断电 ：后端持续比较 current / power 与阈值，越限即发 controller-event（key=0）。

阈值参考（示例，按 10A/2500W 上限留裕量）：

指标	建议阈值	动作
电流 current	> 9A	告警
功率 power	> 2200W	告警
电流异常突增	环比 > 50%	告警+断电

后端伪代码：

python 复制代码

LIMIT_A, LIMIT_W = 9.0, 2200.0
def on_report(d):
    if d.get("current", 0) > LIMIT_A or d.get("power", 0) > LIMIT_W:
        publish_command(d["mac"], {"key": 0, "type": "event"})  # 立即断电
        alert(f"{d['mac']} 越限：{d['current']}A / {d['power']}W")

16.4 数据驱动决策（用数据做预算与考核）

累计电量 energy 是"分项计量"的天然数据源：

分项计量 ：按工位/部门/设备给插座编号，energy 增量即该单元用电。
做预算 ：用近 3 个月 energy 均值为下季度预算，替代"拍脑袋"。
做考核：对比各单元单位产出能耗，量化节能成效。
做台账 ：energy-clear 清零后重新计一段周期，形成清晰的"月度账"。

本章要点 / 落地清单

把"能远程做"的操作列一张清单，逐条替换掉现场作业。
用 power 排名找出前 10 台"电老虎"，制定断电/错峰策略。
设定电流/功率告警阈值，并在后端实现"越限自动断电"。
给设备按单元编号，用 energy 建月度台账，为预算与考核提供依据。

第 17 章增收：把插座变成商业模式

本章点题： 前面是"省"，这一章教你"赚"------把插座当入口，卖出项目、订阅和服务。

17.1 系统集成项目（按项目收费：设计+施工+软件）

把 GSPM1B2 当作"交付物料"而不是"零售商品"，按整体解决方案报价。

示例报价结构（单位：元，均为示例）：

分项	计价方式	示例金额
方案设计费	一次性	20,000
硬件（插座）	台数 × 单价	100 × 99 = 9,900
施工与调试	台数 × 工时单价	100 × 3min × 150元/h ≈ 750
软件（平台+看板）	一次性	50,000
首年运维	年费	30,000
合计（示例）	---	≈ 110,650

关键点：硬件只是小头，设计与软件才是利润源。

17.2 SaaS 订阅（按设备数/年收费）

把平台按订阅卖，收入可预测、可复购。

套餐	对象	计价（示例）	内容
基础版	小型	20 元/设备/年	数据看板 + 远程开关
专业版	中型	50 元/设备/年	+ 告警 + 定时 + 报表
旗舰版	大型	100 元/设备/年	+ 定制报表 + SLA

收入测算（示例）： 1,000 台设备全部走专业版：

复制代码

年订阅收入 = 1,000 × 50 = 50,000 元/年

规模越大，边际成本越低，订阅收入越可观。

17.3 代运维与增值服务

在"卖完就不管"和"长期陪跑"之间，代运维是稳定现金流：

代运维：按月/年收取，承诺在线率与响应时限（见第 19 章）。
能耗报告：每月出一份"用电分析与节能建议"，是很好卖的增值项。
安全巡检：季度出具越限/异常记录，用于客户内部合规。
二次开发：为客户定制专属看板、对接 ERP/OA。

17.4 行业定制（实验室/宿舍/园区等垂直方案）

同一款插座，换个场景就是一套新方案：

场景	痛点	GSPM1B2 价值点
高校实验室	违规大功率电器	功率越限自动断电 + 记录
学生宿舍	用电安全、能耗管理	定时断电 + 分项计量
产业园区	分散设备管理难	集中配置 + 远程运维
共享空间	按人/按时计费	`energy` 分项计量做结算
老旧机房	小设备需要远程重启	`controller-restart` 无人值守

本章要点 / 落地清单

按"设计+硬件+施工+软件+运维"五段报价，别把报价做成一锤子买卖。
设计 2~3 档 SaaS 套餐，按设备数/年收费，形成复购。
整理 1~2 项增值服务（能耗报告/安全巡检），作为持续收入。
挑 1 个垂直行业做样板案例，沉淀可复制方案。

第 18 章项目管理：集成商视角的落地方法论

本章点题： 项目做得顺不顺，取决于标准动作；这一章给你一套从调研到验收的模板。

18.1 需求调研与方案设计

调研"五问"：

要控什么？（单纯通断电 / 还要计量 / 还要安全保护）
有多少台？装在哪些点位？
网络怎么走？（局域网 / 公网 / 是否有 VLAN、防火墙）
谁来管？（自有团队 / 委托你代运维）
要不要对接已有系统（ERP/OA/大屏）？

方案设计输出： 网络拓扑图 → 点位清单 → 功能清单 → 数据流图 → 报价单。

调研阶段最容易犯的错，是"客户说啥就做啥 "。客户往往只描述症状（"我这儿老跳闸"），而真正的问题可能在配电、网络或管理流程。有经验的集成商会把症状翻译成需求："跳闸"背后可能是功率越限需要自动断电，"管不过来"背后可能是需要集中配置与远程运维。把需求背后的目的挖出来，方案才不会做偏。

方案设计还要给客户留"可扩展性"：第一期先解决最痛的点，第二期再叠加计量、报表、对接。这样既降低了首期决策门槛，也为后续增收埋下伏笔。切忌一次报一个大而全的方案把客户吓退。

18.2 选型与 BOM 清单（示例表格）

序号	物料	型号/规格	数量	说明
1	智能插座	GemeOpen GSPM1B2	100	主设备
2	MQTT Broker	Mosquitto（自建/容器）	1	建议加认证
3	服务器	2C4G 起	1	跑后端+看板
4	数据库	InfluxDB/TimescaleDB	1	时序数据持久化
5	网络设备	工业级 WiFi AP	按点位	保证 signal ≥ -70dBm
6	施工辅材	线材/标贴/扎带	若干	现场

BOM 清单的作用不只是"买东西"，更是"对齐预期 "。把物料、数量、规格、说明四列写清楚，既是采购依据，也是验收依据，还能避免"以为含在报价里其实没含"的扯皮。建议在 BOM 下再加一行"可选件"，把第二期才会用到的服务器扩容、网络设备、增值软件单独标出来，让客户一眼看清首期与扩展的边界。

选型时还有一条经验：网络设备别省。设备再好，如果现场 WiFi 信号弱、AP 覆盖差，上报丢包、指令超时就会接踵而来。与其后期反复上门调网络，不如在 BOM 阶段就把工业级 AP 和点位规划到位，这是"一次做对"最划算的投入。

18.3 实施计划与里程碑（甘特式阶段表）

阶段	主要工作	周期	里程碑
S1 调研	需求确认、现场勘察	3~5 天	需求确认书
S2 设计	方案/拓扑/报价	3~5 天	方案评审通过
S3 采购	下单、到货	7~15 天	到货验收
S4 部署	Broker+平台上线	3~5 天	平台可用
S5 施工	装设备、配网、联调	2~5 天	全量在线
S6 试运行	观察、调参、培训	7 天	试运行报告
S7 验收	按标准验收、交付	1~2 天	验收签字

18.4 验收标准与交付物清单

验收标准（建议量化）：

指标	目标值
设备在线率	≥ 99%
指令成功率	≥ 99%
数据延迟	≤ 上报间隔 × 2
告警准确率	越限必报

交付物清单：

网络拓扑图 + 点位图
设备台账（MAC/位置/负责人）
平台账号与权限说明
运维手册 + 应急流程
试运行报告 + 验收单

本章要点 / 落地清单

用"五问"做调研，输出五份设计文档。
BOM 表把硬件、Broker、服务器、网络、辅材都列全。
按 S1~S7 排里程碑，每阶段设一个可签字产物。
验收用量化指标，不用"感觉良好"。

第 19 章运维体系：让系统长期稳定

本章点题： 上线只是开始，运维体系决定了这套系统能"活多久、跑多稳"。

19.1 监控与告警（设备在线率、指令成功率、异常用电）

四大核心指标：

指标	采集方式	告警阈值（示例）
设备在线率	距上次上报时长 > 3×间隔	< 99% 告警
指令成功率	下发后有响应 / 下发数	< 99% 告警
异常用电	`current`/`power` 越限	见 16.3
Broker 连接数	`$SYS/broker/clients/connected`	掉线告警

参考命令：

bash 复制代码

mosquitto_sub -h <broker> -t '$SYS/broker/clients/connected' -v   # Broker 连接数
curl http://localhost:8000/api/health                              # 后端健康

监控的重点不是"能看"，而是"看得懂、会告警"。指标再多，如果没人看、没人管，等于没有。因此每上一个指标，都要配套回答三个问题：谁看它？超过什么值报警？报警了谁处理、怎么处理？把"指标---阈值---责任人---动作"四件事绑定，监控才真正转起来。

推荐的告警分级思路是：趋势类指标看板化、突发类指标告警化。像在线率、能耗趋势这种"慢慢变化"的，适合放在看板上每天巡看；像越限、掉线这种"突然发生"的，才适合实时推送到值班手机。两件事分开，既不漏掉重要告警，也不会被无关提醒淹没。

19.2 固件升级与配置变更

配置变更 ：改 MQTT/TCP 用 setting-mqtt / setting-tcp；改 WiFi 用 setting-wifi-config。
⚠️ 改完需断电重启或发 controller-restart 才生效。
变更流程：先测试环境验证 → 灰度 1~2 台 → 观察 24h → 批量。
固件升级：交由厂家维护，具体机制以官方文档为准；现场只做"版本核对 + 变更记录"。

19.3 故障分级与响应（P0/P1/P2 + 响应时限）

等级	定义	示例	响应时限	解决时限
P0	全局中断	Broker/平台宕机	15 分钟	2 小时
P1	批量异常	大批设备离线	30 分钟	8 小时
P2	单点问题	单台失联/数据异常	4 小时	24 小时

处理原则： 先止血（切备用/重启），再定位，最后写复盘。

19.4 大规模部署经验（百台/千台的批量配网、topic 规划、容量估算）

（1）Topic 规划 ------ 按 MAC 分层，便于多设备：

复制代码

gemeopen/gspm1b/<mac>/report     # 设备上报（你订阅）
gemeopen/gspm1b/<mac>/command    # 下发指令（你发布）

后端订阅通配符 gemeopen/gspm1b/+/report 即可一网打尽多台设备。

（2）批量配网 SOP：

现场用统一 SSID/密码的 WiFi；
逐台用 setting-wifi-config 配网；
用 setting-mqtt 批量指向自建 Broker（脚本化，可比人工快 10 倍）；
统一发 controller-restart 生效；
用 info-all 回读 mac/ip/signal/version 做台账。

（3）容量估算（示例）：

复制代码

单设备日均消息数 = 86400 / 上报间隔(秒)
15 秒间隔 → 86400 / 15 ≈ 5,760 条/天/台
1,000 台 → 约 576 万条/天 ≈ 67 条/秒（平均）

结论：1,000 台、15 秒间隔，对单台普通服务器压力很小；高频（如 5 秒）或上万台时，需考虑 Broker 集群与时序库分片。

（4）其他经验：

设备 clientId 不可重复，建议用 MAC 派生；
现场 WiFi 要保证 signal ≥ -70dBm；
批量操作分批进行，避免瞬时风暴。

大规模部署的三条心法：

先小后大：先装 3~5 台跑通全链路，再铺开，避免"一次性铺开、一次性返工"。
先规范后施工：Topic、命名、台账规则要在施工前定死，否则规模越大越乱。
先监控后交钥匙：没有监控就交付，等于把隐患留给未来；先让系统"会说话"，再交给客户。

规模从百台走向千台，考验的不再是"能不能装"，而是"能不能管"。设备越多，越要依赖自动化（脚本配网、批量校验）和标准化（统一命名、统一流程），把人为差异降到最低。GSPM1B2 的指令化配置刚好为这种规模化提供了抓手：能批量，才谈得上规模化盈利。

本章要点 / 落地清单

上线"在线率/指令成功率/异常用电/Broker连接数"四路监控。
配置变更走"测试→灰度→观察→批量"流程；改 MQTT 记得重启。
明确 P0/P1/P2 定义与响应时限，并落到值班表。
Topic 按 MAC 规划，批量配网脚本化，容量按 86400/间隔估算。

第 20 章附录

本章点题： 把速查、示例、清单和 FAQ 集中在这一章，随手可查。

20.1 指令速查表（完整表格）

messageId 为业务流水号，设备原样回显。字段细节以 GemeOpen 官方开发文档为准。

功能	指令名	请求 payload 关键字段	响应关键字段
通断电	`controller-event`	`key`(0断电/1通电), `type:"event"`	`commandName, key, mac, ip, onState, signal, ssid, version, wifiLock, keyLock, bssid`
设置上报频率	`device-timer-interval`	`timerEnable`(0/1), `timerInterval`(5~86400 秒), `type:"setting"`	`commandName, timerEnable, timerInterval, ...`
定时上报（设备主动）	`device-timer-task`	---	`commandName, voltage, current, power, energy, key, mac, source:"auto"`
设备基础信息	`info-all`	`type:"info"`	`code, ip, mac, signal, ssid, version, wifiLock, ...`
实时用电信息	`info-statistic`	`type:"statistic"`	`commandName:"info-statistic", voltage, current, power, energy, key, mac`
查询定时任务	`info-timer-task-query`	---	定时任务列表
设置定时任务	`setting-timer-task`	时间/星期/动作等	`success`
删除定时任务	`setting-timer-delete`	---	`success`
设置倒计时任务	`setting-timer-countdown`	倒计时秒数/动作	`success`
倒计时上报	`setting-timer-countdown-active`	---	倒计时状态
清除倒计时	`setting-timer-countdown-clear`	---	`success`
累计电量清零	`energy-clear`	---	`success`
重置设备	`controller-reset`	`system:"reset", type:"setting"`	`success, message`
重启设备	`controller-restart`	`system:"restart", type:"setting"`	`success, message`
查询通信协议	`info-protocol`	---	`server, port, publish, subcribe, clientId, username, protocol`
自定义 MQTT	`setting-mqtt`	`server, port, publish, subcribe, clientId, username, password, type:"custom"`	`success`
自定义 TCP	`setting-tcp`	`server, port, protocol:"tcp"`	`success`
设置 WiFi	`setting-wifi-config`	`ssid, password`	`success`
设置 WiFi 配网锁	`setting-wifi-lock`	`wifiLock`(0/1)	`success`
设置按键锁	`setting-key-lock`	`keyLock`(0/1)	`success`
设置上电默认状态	`setting-on-state`	`onState`(0记忆/1关闭/2开启)	`success`

易错点： info-protocol 里 publish = 设备发布（你订阅）；subcribe = 设备订阅（你发布）。拼写虽反，语义别搞错。

20.2 代码示例索引

主题	语言/工具	位置/说明
切换设备到自建 Broker	Python (paho-mqtt)	`scripts/configure_device.py`
切换配置模板	JSON	`scripts/device_switch.example.json`
MQTT 桥接与字段归一化	Python	`backend/app/mqtt_client.py`
Home Assistant 实体定义	YAML	`homeassistant/mqtt-gspm1b.yaml`
后端 API/WebSocket	Python (FastAPI)	`backend/app/main.py`
前端实时看板	React	`frontend/src/`
部署与 Docker	YAML	`docker-compose.yml`

20.3 部署与施工检查清单（checkbox）

网络与环境

Broker 地址设备可达（局域网 IP 或公网域名，非 localhost）
防火墙放行 1883（TLS 用 8883）
WiFi 为 2.4GHz，现场 signal ≥ -70dBm
已启用 Broker 密码认证，关闭匿名访问

设备配置

每台设备 clientId 唯一
Topic 按 MAC 规划并写入台账
已用 setting-mqtt 指向自建 Broker
已断电重启或发 controller-restart 使配置生效
已用 info-protocol 回读校验 server/publish/subcribe

平台与数据

后端 /api/health 正常，mqttConnected:true
时序库已持久化（非内存）
看板能实时显示 voltage/current/power/energy
告警阈值已配置并可触发

安全与交付

前端 HTTPS，CORS_ORIGINS 已收紧
敏感信息走环境变量/密钥管理
台账、拓扑图、运维手册已交付
seed 密码/默认口令已全部修改

20.4 常见问题 FAQ（一问一答）

Q1：GSPM1B2 最大能带多大负载？

A：最大负载电流 10A，额定功率 MAX 2500W；输入 AC 85~265V。

Q2：继电器是什么类型？

A：16A 宏发继电器 HF32FV-16（磁保持类机械触点）。

Q3：支持 5GHz WiFi 吗？

A：不支持，仅 2.4GHz WiFi。

Q4：待机功耗多大？

A：待机功率 < 3W。

Q5：工作温度和尺寸？

A：工作温度 -5℃ ~ +40℃；尺寸 49mm × 59mm × 28mm。

Q6：key 字段是什么含义？

A：key=1 表示通电，key=0 表示断电。

Q7：energy 断电会归零吗？

A：不会。energy 是累计用电量（kWh），断电不归零，只有发 energy-clear 后才归零。

Q8：怎么清零累计电量？

A：发指令 energy-clear。

Q9：publish 和 subcribe 谁订阅谁？

A：publish 是设备发布的主题，服务端要订阅它；subcribe 是设备订阅的主题，服务端要发布指令给它。

Q10：改了 MQTT 配置为什么没生效？

A：setting-mqtt 需断电重启 或发 controller-restart 后才生效。

Q11：上报间隔最小/最大是多少？

A：timerInterval 取值 5~86400 秒。

Q12：怎么开启定时上报？

A：发 {"timerEnable":1,"timerInterval":15,"type":"setting"}（device-timer-interval）。

Q13：设备不上报数据怎么办？

A：先确认是否已切换到自建 Broker、是否开启了定时上报，再用 mosquitto_sub 抓包确认。

Q14：支持 TCP 吗？

A：支持，用 setting-tcp 配置。

Q15：支持内网 HTTP 控制吗？

A：支持内网 HTTP 通信方式（具体接口以官方文档为准）。

Q16：能接阿里云/华为云/百度云/腾讯云吗？

A：可以，设备支持接入这些物联网平台，也支持私有化部署。

Q17：signal 多少算好？

A：0~-50 最好，-50~-70 较好，-70~-80 一般，-80~-100 较差。

Q18：source 字段有哪几种取值？

A：command（指令响应）/auto（自动上报）/button（按键）。

Q19：controller-reset 和 controller-restart 区别？

A：前者是重置设备（请谨慎，可能清空配网），后者是重启设备。

Q20：怎么设置上电默认状态？

A：setting-on-state，onState 取 0记忆/1关闭/2开启。

Q21：按键锁和配网锁怎么用？

A：分别用 setting-key-lock（keyLock 0/1）和 setting-wifi-lock（wifiLock 0/1）。

Q22：怎么设置定时任务？

A：setting-timer-task（支持多组）；查询用 info-timer-task-query，删除用 setting-timer-delete。

Q23：倒计时任务怎么用？

A：setting-timer-countdown 设置，setting-timer-countdown-active 上报状态，setting-timer-countdown-clear 清除。

Q24：怎么查设备基础信息？

A：发 info-all，返回 code/ip/mac/signal/ssid/version 等。

Q25：怎么查实时用电？

A：发 info-statistic，返回 voltage/current/power/energy/key/mac。

Q26：两台设备能把 clientId 设成一样吗？

A：不可以，clientId 必须唯一，建议用 MAC 派生。

Q27：消息丢了怎么办？

A：关注 QoS 设置与网络质量；messageId 用于业务对账。

Q28：power 是视在功率还是有功功率？

A：本设备上报的 power 为视在功率（W）。

Q29：过零检测有什么用？

A：用于更精准的计量与继电器过零投切，减少浪涌。

Q30：如何实现异常自动断电？

A：后端比较 current/power 与阈值，越限即下发 controller-event（key=0）。

Q31：一台服务器能带多少设备？

A：示例中 1,000 台、15 秒间隔约 67 条/秒，普通服务器压力很小；更大规模需 Broker 集群。

Q32：多台设备怎么批量配网？

A：脚本化下发 setting-wifi-config 与 setting-mqtt，再统一 controller-restart 生效。

Q33：固件升级怎么处理？

A：由厂家维护，现场做"版本核对 + 变更记录"，具体机制以官方文档为准。

Q34：为什么设备离线？

A：常见原因有 WiFi 掉线、Broker 不可达、断电；结合 signal 与抓包定位。

Q35：设备的时间会准吗？

A：定时任务由设备执行，网络时间同步机制以官方文档为准。

20.5 结语

给开发者： 你面对的是一条现成、清晰的 MQTT 指令链------别再造轮子，把创造力留给上层应用。
给集成商： 硬件是入场券，真正卖出去的是方案、软件和长期服务。
给设备厂： 把"可二次开发"做到位，让下游省下的每一分工程成本，都会变成你的复购订单。

全文数字均为示例测算，请以你的真实报价与官方文档为准。

（第 4 部分完）

附录 A · 设备规格与指令基准

1. 产品

品牌：GemeOpen（武汉智鸟科技）
型号：GSPM1B2，产品名「智能转换器插座 10A-S1 Plus-WiFi」
定位：面向软件开发者的可二次开发智能插座，支持私有化部署

电气与硬件参数（以此为准）

项	值
主控芯片	乐鑫 ESP32（内置过零检测）
输入电压	AC 85~265V（50/60Hz）
最大负载电流	10A
额定功率	MAX 2500W
继电器	16A 宏发继电器 HF32FV-16（磁保持类机械触点）
待机功率	< 3W
通讯	2.4GHz WiFi
尺寸	49mm × 59mm × 28mm
工作温度	-5℃ ~ +40℃
插孔	转换器（插座插在原有墙壁插座上，输出为三孔/两孔）

能力

通断电控制（继电器）
用电采集：电压(V)、电流(A)、功率(W，视在功率)、累计用电量(kWh)
采集"过零检测"→ 用于更精准的计量与继电器过零投切（减少浪涌）
定时任务（多组）+ 倒计时任务
上电默认状态、按键锁、配网锁
通信：MQTT / TCP Client / 内网 HTTP
可接入阿里云、华为云、百度云、腾讯云等物联网平台；支持私有化部署

2. 通信与主题

设备出厂默认连 GemeOpen 厂家 MQTT 测试服务器 （mqtt.smart-bird.cn:1883）。
用 setting-mqtt / setting-tcp 可改到自建服务器；改后需断电重启或发 controller-restart 生效。
info-protocol 返回的字段语义（易错，必须讲清）：
- publish：设备发布数据的主题 → 服务端要订阅（收上行）
- subcribe：设备订阅的主题 → 服务端要发布（下指令）
- 另含 server、port、username、clientId

3. 指令全集（下行为主，`messageId` 为业务流水号，设备原样回显）

功能	指令名	请求 payload 关键字段	响应关键字段
通断电	`controller-event`	`key`(0断电/1通电), `type:"event"`	`commandName, key, mac, ip, onState, signal, ssid, version, wifiLock, keyLock, bssid`
设置上报频率	`device-timer-interval`	`timerEnable`(0/1), `timerInterval`(5~86400 秒), `type:"setting"`	`commandName, timerEnable, timerInterval, ...`
定时上报（设备主动）	`device-timer-task`	---	`commandName, voltage, current, power, energy, key, mac, source:"auto"`
设备基础信息	`info-all`	`type:"info"`	`code, ip, mac, signal, ssid, version, wifiLock, ...`
实时用电信息	`info-statistic`	`type:"statistic"`	`commandName:"info-statistic", voltage, current, power, energy, key, mac`
查询定时任务	`info-timer-task-query`	---	定时任务列表
设置定时任务	`setting-timer-task`	时间/星期/动作等	`success`
删除定时任务	`setting-timer-delete`	---	`success`
设置倒计时任务	`setting-timer-countdown`	倒计时秒数/动作	`success`
倒计时上报	`setting-timer-countdown-active`	---	倒计时状态
清除倒计时	`setting-timer-countdown-clear`	---	`success`
累计电量清零	`energy-clear`	---	`success`
重置设备	`controller-reset`	`system:"reset", type:"setting"`	`success, message`
重启设备	`controller-restart`	`system:"restart", type:"setting"`	`success, message`
查询通信协议	`info-protocol`	---	`server, port, publish, subcribe, clientId, username, protocol`
自定义 MQTT	`setting-mqtt`	`server, port, publish, subcribe, clientId, username, password, type:"custom"`	`success`
自定义 TCP	`setting-tcp`	`server, port, protocol:"tcp"`	`success`
设置 WiFi	`setting-wifi-config`	`ssid, password`	`success`
设置 WiFi 配网锁	`setting-wifi-lock`	`wifiLock`(0/1)	`success`
设置按键锁	`setting-key-lock`	`keyLock`(0/1)	`success`
设置上电默认状态	`setting-on-state`	`onState`(0记忆/1关闭/2开启)	`success`

说明：字段细节以 GemeOpen 官方开发文档为准；本篇作为应用与实战指南，重在讲清"怎么用、在哪用、值多少"，指令表作为速查。

4. 数据字段语义

voltage 电压 V；current 电流 A；power 视在功率 W；energy 累计用电量 kW·h（断电不归零，energy-clear 后归零）
key 通断状态：1 通电 / 0 断电
signal 信号强度 dBm（0~-50 最好，-50~-70 较好，-70~-80 一般，-80~-100 较差）
source：command（指令响应）/ auto（自动上报）/ button（按键）

MQTT智能插座GSPM1B2 · 开发者实战指南

GemeOpen GSPM1B2 智能插座 · 开发者实战指南

目录

第一部分 基础认知与快速上手

第 1 章 开篇：一台小插座，为什么值得开发者认真看

1.1 从三个真实痛点说起

1.2 「能二次开发的智能插座」和「消费级智能插座」差在哪

1.3 这份文档写给谁，怎么读

第 2 章 认识设备：GSPM1B2 的硬件与能力边界

2.1 规格参数逐条解读

2.2 它能做什么、不能做什么

2.3 选型对照：什么时候用智能插座、什么时候用通断器、什么时候用智能断路器

第 3 章 协议全景：MQTT / TCP / 内网 HTTP 与指令哲学

3.1 三种通信方式怎么选

3.2 主题与 publish/subcribe 的反直觉（重点，避免踩坑）

3.3 指令全表速览与 messageId「请求---响应」模型

第 4 章 快速上手：15 分钟跑通第一条指令（三语言）

4.1 准备：设备上电、配网、获取主题与凭据

4.2 Python 最小可运行示例（paho-mqtt）

4.3 Node.js 与 Java 最小示例

4.4 一个完整脚本：查询实时用电并打印电压/电流/功率/累计电量

4.5 本章落地清单（checkbox）

第二部分 数据、调优与系统集成

第 5 章 数据采集：把电变成数据

5.1 电压/电流/功率/电量的物理含义与采集原理

5.2 视在功率与有功功率的区别（诚实说明）

5.3 定时上报（device-timer-interval / device-timer-task）vs 主动查询（info-statistic）如何选择与配置

5.4 数据落库与可视化

第 6 章 调试手册：从"设备没反应"到"一眼定位"

6.1 三层排查法（Broker → 主题 → 设备）

6.2 用 mosquitto_sub / mosquitto_pub 抓包定位

6.3 常见故障速查表（症状 → 原因 → 解决）

6.4 日志与可观测性（埋点、请求-响应链路追踪）

第 7 章 二次开发进阶：把它变成你自己的产品

7.1 SDK 封装：连接、断线重连、请求-响应关联、设备影子

7.2 批量设备管理：命名规范与 topic 规划

7.3 配置化最佳实践：上电默认状态 / 按键锁 / 配网锁

7.4 可靠性工程：断网缓存、指令重试、幂等、超时处理

第 8 章 云平台对接：公有云与私有化部署

8.1 接入阿里云/腾讯云/华为云/百度云物联网平台

8.2 私有化部署完整方案（自建 Mosquitto/EMQX + 后端服务）

8.3 安全：账号体系、TLS、权限隔离、设备身份

第 9 章 集成实战：让插座融入现有系统

9.1 接入 Home Assistant（YAML 示例）

9.2 对接自建平台 / ERP / 工单系统的思路

9.3 与 SCADA / 组态软件 / 可视化大屏对接

9.4 通过 Webhook / 消息队列（Kafka/RabbitMQ）做中台化

第 3 部分 · 安装施工、传统对接与 20+ 应用场景

第 10 章 定时与自动化：让插座自己干活

10.1 设备端定时任务与倒计时任务

10.1.1 定时通断任务：setting-timer-task

10.1.2 查询定时任务：info-timer-task-query

10.1.3 删除定时任务：setting-timer-delete

10.1.4 倒计时任务：setting-timer-countdown

10.1.5 一份可复用的 Python 封装

10.2 设备端定时 vs 平台端策略引擎：如何分工

10.3 典型案例

案例 A：实验室定时断电（安全兜底）

案例 B：门店定时开关灯

案例 C：设备轮换运行（延长寿命）

第 11 章 安装与施工：电气是底线

11.1 安装形态与适用场合

11.2 接线、负载匹配、阻性/感性负载

11.2.1 正确理解 10A / 2500W 边界

11.2.2 阻性 / 感性 / 容性负载的差异

11.3 批量配网与施工流程（含可打印工序卡）

11.3.1 配网与指向自建服务器

11.3.2 可打印施工工序卡

11.3.3 批量配网脚本示意

11.4 安全规范与验收要点

第 12 章 与传统电子用电设备对接

12.1 用插座驱动接触器 / 中间继电器 → 间接控制大功率设备

12.2 控制电机、水泵、风机等感性负载的注意点

12.3 老旧设备与非智能电器的"智能化改造"方法论

12.4 信号对接：干接点、RS-232/485、PLC 协同

12.4.1 干接点（Dry Contact）

12.4.2 RS-232 / 485

12.4.3 PLC 协同的实用模式

第 13 章 应用场景 20+ 例（上）：编号 1~11

场景 1 · 高校实验室

第一部分基础认知与快速上手

第 1 章开篇：一台小插座，为什么值得开发者认真看

第 2 章认识设备：GSPM1B2 的硬件与能力边界

第 3 章协议全景：MQTT / TCP / 内网 HTTP 与指令哲学

第 4 章快速上手：15 分钟跑通第一条指令（三语言）

第二部分数据、调优与系统集成

第 5 章数据采集：把电变成数据

第 6 章调试手册：从"设备没反应"到"一眼定位"

第 7 章二次开发进阶：把它变成你自己的产品

第 8 章云平台对接：公有云与私有化部署

第 9 章集成实战：让插座融入现有系统

第 10 章定时与自动化：让插座自己干活

10.1.1 定时通断任务：`setting-timer-task`

10.1.2 查询定时任务：`info-timer-task-query`

10.1.3 删除定时任务：`setting-timer-delete`

10.1.4 倒计时任务：`setting-timer-countdown`

第 11 章安装与施工：电气是底线

第 12 章与传统电子用电设备对接

第 13 章应用场景 20+ 例（上）：编号 1~11

第 14 章应用场景 20+ 例（下）：编号 12~24

第 15 章省钱账：一台插座帮你省了什么

第 16 章增效：自动化管理带来的收益

第 17 章增收：把插座变成商业模式

第 18 章项目管理：集成商视角的落地方法论

第 19 章运维体系：让系统长期稳定

第 20 章附录

3. 指令全集（下行为主，`messageId` 为业务流水号，设备原样回显）