Shelly智能插座本地API开发指南：从基础控制到自动化场景实践

这次我们来看一个实用的智能家居设备——Shelly 国标智能插座。这个设备最大的特点是支持本地部署和远程控制，可以直接通过网页界面或API接口进行管理，不需要依赖云服务就能实现智能化控制。

Shelly智能插座采用标准国标插口设计，支持Wi-Fi连接，内置电量计量功能，可以实时监测用电量。设备支持定时开关、远程控制、场景联动等常见智能家居功能，最重要的是它提供了完整的本地API接口，适合喜欢自建智能家居系统的技术爱好者。

1. 核心能力速览

2. 适用场景与使用边界

Shelly智能插座适合需要远程控制电器设备的场景，比如：

• 家庭中的空调、热水器、灯具的定时开关
• 办公室设备的集中管理
• 临时设备的远程控制
• 用电量监测和节能管理

使用边界方面需要注意：

• 最大负载功率不能超过设备标称值（通常2500W）
• 不适合控制大功率电机类设备
• 潮湿环境需要做好防水措施
• 涉及重要设备控制时建议设置冗余保护

3. 环境准备与前置条件

在使用Shelly智能插座前，需要准备以下环境：

硬件要求：

• Shelly智能插座设备
• 2.4GHz Wi-Fi网络（不支持5GHz）
• 智能手机或电脑用于初始配置
• 需要控制的电器设备

网络环境：

• 路由器需要支持DHCP功能
• 建议为设备分配固定IP地址
• 如果需要远程访问，需要配置端口转发或VPN

软件工具：

• 手机App（Shelly App）或网页浏览器
• 如果需要API开发，需要准备HTTP客户端工具

4. 设备配置与网络连接

4.1 首次配置步骤

1. 物理连接：将Shelly插座插入电源，等待指示灯闪烁
2. Wi-Fi配置：手机连接Shelly开头的热点信号
3. 网络设置：在配置页面输入Wi-Fi密码和设备名称
4. 设备发现：在路由器中查看设备分配的IP地址

4.2 网页界面访问

设备连接成功后，可以通过浏览器访问设备IP地址：

# 访问设备管理界面 http://192.168.1.100 # 替换为实际设备IP

登录后可以看到设备状态界面，包括：

• 当前开关状态
• 实时功率读数
• 累计用电量
• 网络连接状态

4.3 手机App配置

下载官方Shelly App，按照提示添加设备：

1. 打开App，点击添加设备
2. 扫描局域网内的Shelly设备
3. 输入设备访问密码（首次使用需要设置）
4. 完成设备绑定

5. 基础功能测试

5.1 开关控制测试

测试目的：验证远程开关功能是否正常

操作步骤：

1. 在网页界面点击开关按钮
2. 观察插座指示灯状态变化
3. 确认连接的设备电源状态

预期结果：

• 网页界面状态实时更新
• 插座继电器有清晰的切换声音
• 连接的设备按预期开启或关闭

判断标准：

• 开关响应延迟小于1秒
• 状态同步准确
• 无异常断开情况

5.2 电量监测功能测试

测试目的：验证电量计量准确性

测试方法：

1. 连接已知功率的设备（如100W灯泡）
2. 在界面观察实时功率读数
3. 运行一段时间后查看累计用电量

数据验证：

{ "power": 98.5, // 实时功率（瓦） "voltage": 220.1, // 电压（伏） "current": 0.45, // 电流（安） "energy": 0.098 // 累计用电量（千瓦时） }

准确性判断：

• 功率读数误差应在±5%以内
• 电压读数应与电网电压基本一致
• 累计用电量应随时间线性增长

5.3 定时功能测试

测试目的：验证定时开关功能的可靠性

配置示例：

{ "enable": true, "time": "08:00", "action": "on", "days": [1,2,3,4,5] // 周一到周五 }

测试要点：

• 定时触发时间准确性
• 重复执行稳定性
• 多个定时任务无冲突

6. API接口调用详解

Shelly设备提供完整的REST API接口，支持本地和远程控制。

6.1 基础API调用

获取设备状态：

curl http://192.168.1.100/status

返回数据示例：

{ "wifi_sta": { "connected": true, "ssid": "HomeWiFi", "ip": "192.168.1.100" }, "cloud": { "enabled": false, "connected": false }, "mqtt": { "connected": false }, "relays": [ { "ison": false, "has_timer": false } ], "meters": [ { "power": 0.0, "is_valid": true } ] }

控制开关状态：

# 开启插座 curl http://192.168.1.100/relay/0?turn=on # 关闭插座 curl http://192.168.1.100/relay/0?turn=off # 切换状态 curl http://192.168.1.100/relay/0?turn=toggle

6.2 高级API功能

设置定时任务：

curl http://192.168.1.100/schedule/create \ -d '{"enable":true, "timespec":"0 8 * * 1-5", "call":0, "action":"on"}'

获取用电统计：

curl http://192.168.1.100/meter/0

6.3 Python控制示例

import requests import json class ShellyPlug: def __init__(self, ip_address): self.base_url = f"http://{ip_address}" def get_status(self): """获取设备状态""" response = requests.get(f"{self.base_url}/status") return response.json() def turn_on(self): """开启插座""" response = requests.get(f"{self.base_url}/relay/0?turn=on") return response.json() def turn_off(self): """关闭插座""" response = requests.get(f"{self.base_url}/relay/0?turn=off") return response.json() def get_power_usage(self): """获取用电数据""" response = requests.get(f"{self.base_url}/meter/0") return response.json() # 使用示例 plug = ShellyPlug("192.168.1.100") status = plug.get_status() print(f"当前状态: {'开启' if status['relays'][0]['ison'] else '关闭'}") print(f"实时功率: {status['meters'][0]['power']}W")

7. 场景联动与自动化

7.1 基于时间的自动化

工作日早晨自动开启设备：

import schedule import time from datetime import datetime def morning_routine(): """工作日早晨7点自动开启设备""" if datetime.now().weekday() < 5: # 周一到周五 plug.turn_on() print("工作日早晨设备已开启") # 设置定时任务 schedule.every().day.at("07:00").do(morning_routine) while True: schedule.run_pending() time.sleep(1)

7.2 基于用电量的智能控制

用电量超限自动告警：

def power_monitor(): """用电量监控""" usage = plug.get_power_usage() current_power = usage['power'] if current_power > 1000: # 超过1000W告警 send_alert(f"用电功率过高: {current_power}W") if current_power < 5: # 功率过低可能设备异常 check_device_status() def send_alert(message): """发送告警通知""" # 实现邮件、短信或推送通知 print(f"告警: {message}")

7.3 与其他设备联动

与温度传感器联动：

def temperature_control(): """根据温度自动控制空调""" temperature = get_temperature() # 获取温度传感器数据 if temperature > 28: plug.turn_on() # 开启空调 elif temperature < 24: plug.turn_off() # 关闭空调

8. 安全配置与访问控制

8.1 设备安全设置

修改默认密码：

1. 登录网页界面 → 设置 → 安全
2. 修改默认访问密码
3. 启用HTTPS访问

网络隔离：

• 将设备放在独立的VLAN中
• 限制设备只能访问必要的网络资源
• 关闭不必要的服务端口

8.2 API访问安全

使用认证的API调用：

# 带认证的API调用 curl -u username:password http://192.168.1.100/status

Python带认证示例：

import requests from requests.auth import HTTPBasicAuth auth = HTTPBasicAuth('admin', 'your_password') response = requests.get('http://192.168.1.100/status', auth=auth)

9. 常见问题与排查方法

9.1 网络连接问题排查

检查设备网络状态：

# ping设备测试连通性 ping 192.168.1.100 # 扫描设备端口 nmap -p 80 192.168.1.100

查看设备日志： 通过网页界面访问系统日志，查看连接错误信息。

9.2 性能问题排查

监控设备资源使用：

• 观察网页界面响应速度
• 检查API调用延迟
• 监控网络流量

优化建议：

• 减少不必要的频繁API调用
• 使用MQTT替代HTTP轮询
• 设置合理的定时任务间隔

10. 高级功能与扩展应用

10.1 MQTT集成

Shelly设备支持MQTT协议，适合物联网平台集成：

MQTT配置示例：

{ "enable": true, "server": "mqtt.broker.com:1883", "user": "username", "pass": "password", "topic": "shelly/plug01" }

MQTT主题示例：

• shelly/plug01/relay/0/command- 控制命令
• shelly/plug01/relay/0/status- 状态反馈
• shelly/plug01/meter/0/power- 功率数据

10.2 云端同步配置

虽然Shelly支持本地部署，但也提供云端同步选项：

云端功能：

• 远程访问（无需公网IP）
• 设备状态历史记录
• 多用户共享管理

隐私考虑：

• 敏感设备建议保持本地模式
• 重要数据定期本地备份
• 评估云端服务的数据安全政策

10.3 批量设备管理

多设备统一控制：

class ShellyManager: def __init__(self): self.devices = [] def add_device(self, ip): self.devices.append(ShellyPlug(ip)) def bulk_control(self, action): """批量控制所有设备""" for device in self.devices: if action == 'on': device.turn_on() elif action == 'off': device.turn_off() def monitor_all(self): """监控所有设备状态""" status_report = {} for i, device in enumerate(self.devices): status = device.get_status() status_report[f"device_{i}"] = status return status_report # 使用示例 manager = ShellyManager() manager.add_device("192.168.1.100") manager.add_device("192.168.1.101") manager.bulk_control('on') # 同时开启所有设备

11. 实际应用案例

11.1 家庭节能管理

用电分析系统：

def analyze_energy_usage(): """分析家庭用电模式""" daily_data = collect_daily_usage() # 识别高耗电时段 peak_hours = identify_peak_usage(daily_data) # 制定节能策略 energy_saving_plan = create_saving_plan(peak_hours) return energy_saving_plan def create_saving_plan(peak_hours): """创建自动化节能方案""" plan = { "suggestions": [ "在电价高峰时段减少大功率设备使用", "设置设备在夜间低谷时段运行", "使用定时功能避免设备待机耗电" ], "automations": [ {"time": "14:00-16:00", "action": "limit_power"}, {"time": "22:00-06:00", "action": "normal_operation"} ] } return plan

11.2 办公室设备管理

下班自动关机系统：

def office_auto_shutdown(): """办公室自动化管理""" work_hours = "09:00-18:00" weekend_auto_off = True # 工作日下班后关闭非必要设备 if is_after_hours() and not is_weekend(): turn_off_non_essential_devices() # 周末全天关闭设备 if is_weekend() and weekend_auto_off: turn_off_all_devices() def is_after_hours(): """判断是否下班时间""" from datetime import datetime current_hour = datetime.now().hour return current_hour >= 18 or current_hour < 9

Shelly国标智能插座作为一个支持本地API的智能设备，为技术爱好者提供了很大的自定义空间。通过合理的配置和自动化脚本，可以实现真正符合个人需求的智能家居解决方案。最重要的是，所有控制逻辑都可以在本地运行，不依赖外部云服务，既保证了响应速度，也增强了隐私安全性。

在实际使用中，建议先从简单的定时开关开始测试，逐步增加复杂的自动化逻辑。对于重要的设备控制，一定要设置手动 override 机制和异常告警，确保系统可靠性。电量监测功能可以帮助优化用电习惯，长期使用还能节省不少电费。