Shelly 插座(Gen 4):开关与功率计量
Shelly Plugs (Gen 4): Switching and Power Metering
**最近验证:** 2026-09-21,在 Shelly Plug US Gen 4(型号 S4PL-00116US,固件 2.0.0)上验证
当新的发现(discovery)识别出一只 Shelly 智能插座,且用户要求开关它或读取其功耗时,使用本指南。
**Last verified:** 2026-09-21 on a Shelly Plug US Gen 4 (model S4PL-00116US,
firmware 2.0.0)
Use this guide when fresh discovery identifies a Shelly smart plug and the user
asks to switch it or to read what it is drawing.
- **mDNS** 是最强的信号。Shelly 插座通过 `_http._tcp` 广播,主机名由型号和设备 MAC 组成,例如 `ShellyPlugUSG4-<MAC>.local`,其中 `<MAC>` 是十二位无分隔符的十六进制数。设备上报自己的 MAC 时也采用同样格式,不带冒号。
- **MAC 厂商前缀**只是辅助证据,不是证明。Shelly 硬件出货用过不止一个前缀,所以命中是正信号,未命中什么也证明不了。按 `~/docs/devices/home_link.md` 的要求解析当前前缀:查阅厂商公开的厂商前缀,然后在本地与发现结果比对。在线查询时只发送厂商前缀,绝不发送完整 MAC 地址。
- **先确认再动作。** 请求 `Shelly.GetDeviceInfo` 并检查 `model`、`app` 和 `gen`。是这个回答——而不是主机名——确立了设备就是你以为的那个。
地址默认是 DHCP 分配的。每次都用 MAC 或主机名识别插座,并从当前的发现结果中取其地址。绝不复用记住的地址。
- **mDNS** is the strongest signal. Shelly plugs advertise over `_http._tcp`
with a hostname built from the model and the device MAC, such as
`ShellyPlugUSG4-<MAC>.local`, where `<MAC>` is the twelve hex digits with no
separators. The device reports its own MAC the same way, without colons.
- **The MAC vendor prefix** is supporting evidence, not proof. Shelly hardware
has shipped under more than one prefix, so a match is a positive signal and a
miss proves nothing. Resolve the current prefixes the way
`~/docs/devices/home_link.md` requires: look up the manufacturer's public
vendor prefixes, then compare them against the discovery result locally.
Send only a vendor prefix to an online lookup, never a full MAC address.
- **Confirm before acting.** Request `Shelly.GetDeviceInfo` and check `model`,
`app`, and `gen`. That answer, not the hostname, is what establishes the
device is what you think it is.
Addresses are DHCP by default. Identify the plug by MAC or hostname and take
its address from the current discovery result every time. Never reuse a
remembered address.
API 取决于代际(generation),两者不兼容。
- `gen` 为 2 或更高(包含 Gen 4)使用下面描述的 RPC API。
- `gen` 1 完全早于 RPC,使用 `/relay/0?turn=on`。如果发现 Gen 1 设备,本指南的其余部分不适用。
The API depends on the generation, and the two are not compatible.
- `gen` 2 or higher, which covers Gen 4, uses the RPC API described below.
- `gen` 1 predates RPC entirely and uses `/relay/0?turn=on`. If you find a
Gen 1 device, the rest of this guide does not apply.
1. 重新发现插座,从当前结果中取其地址和端口。
2. 经 Home Link CONNECT 代理访问它。它提供有文档的 HTTP API,因此 `~/docs/devices/home_link.md` 的 HTTP 章节适用,包括其中的批准和重定向规则。
3. 调用 `Shelly.GetDeviceInfo` 确认型号和代际,并读取 `auth_en`。
4. 动作前先读 `Switch.GetStatus?id=0`,以便知道要改变的是什么状态,并能区分空操作(no-op)和真正的变化。一只插座只有一个开关,位于 `id=0`。
5. 用 `Switch.Set?id=0&on=true` 或 `on=false` 开关。回复是 `{"was_on": <bool>}`,表示调用*之前*的状态,而非结果。把它当作新状态会把含义搞反。
6. 回读状态。`Switch.GetStatus?id=0` 返回 `output`(继电器状态)和 `apower`(实际消耗的瓦特数)。`output` 只能说明继电器动了;`apower` 才说明所接负载有响应。两者都确认后再告诉用户成功了。
对于不应保持开启的操作,`Switch.Set` 还接受 `toggle_after=<seconds>`,它会自动恢复插座状态,无需第二次调用也能生效。
1. Re-discover the plug and take its address and port from the current result.
2. Reach it through the Home Link CONNECT proxy. It serves a documented HTTP
API, so the HTTP section of `~/docs/devices/home_link.md` applies,
including its approval and redirect rules.
3. Call `Shelly.GetDeviceInfo` to confirm the model and generation, and to read
`auth_en`.
4. Read `Switch.GetStatus?id=0` before acting, so you know the state you are
changing and can tell a no-op from a real change. A plug has one switch, at
`id=0`.
5. Switch with `Switch.Set?id=0&on=true` or `on=false`. The reply is
`{"was_on": <bool>}`, which is the state *before* the call, not the result.
Treating it as the new state inverts the meaning.
6. Read the state back. `Switch.GetStatus?id=0` gives `output` for the relay
and `apower` for watts actually drawn. `output` alone says the relay moved;
`apower` is what shows the attached load responded. Confirm both before
telling the user it worked.
For an action that should not be left latched on, `Switch.Set` also accepts
`toggle_after=<seconds>`, which reverts the plug without needing a second call
to survive.
| 动作 | 路径 |
|---|---|
| 设备型号、代际、固件、`auth_en` | `/rpc/Shelly.GetDeviceInfo` |
| 完整设备状态 | `/rpc/Shelly.GetStatus` |
| 单个开关状态 | `/rpc/Switch.GetStatus?id=0` |
| 开或关 | `/rpc/Switch.Set?id=0&on=true` |
| 开或关,之后自动恢复 | `/rpc/Switch.Set?id=0&on=true&toggle_after=60` |
| 切换 | `/rpc/Switch.Toggle?id=0` |
| 开关配置,包括自动关闭 | `/rpc/Switch.SetConfig` |
| 定时计划 | `/rpc/Schedule.List`、`Schedule.Create`、`Schedule.Delete` |
| Action | Path |
|---|---|
| Device model, generation, firmware, `auth_en` | `/rpc/Shelly.GetDeviceInfo` |
| Full device status | `/rpc/Shelly.GetStatus` |
| One switch's status | `/rpc/Switch.GetStatus?id=0` |
| Turn on or off | `/rpc/Switch.Set?id=0&on=true` |
| Turn on or off, reverting later | `/rpc/Switch.Set?id=0&on=true&toggle_after=60` |
| Toggle | `/rpc/Switch.Toggle?id=0` |
| Switch configuration, including auto-off | `/rpc/Switch.SetConfig` |
| Schedules | `/rpc/Schedule.List`, `Schedule.Create`, `Schedule.Delete` |
从 `Shelly.GetDeviceInfo` 读取 `auth_en`,而不是凭假设。家用网络上的插座常常不设认证,普通 HTTP 就能用。这是单个设备的属性,不是型号的属性。
当 `auth_en` 为 true 时,设备要求 HTTP 摘要认证,用户名恒为 `admin`。不要把密码放进命令里。如果插座没有已存储的凭据,按 `~/docs/devices/home_link.md` 中的凭据规则处理,并说明需要先做设置。
Read `auth_en` from `Shelly.GetDeviceInfo` rather than assuming. A plug on a
home network is often left unauthenticated, and plain HTTP works. That is a
property of the individual device, not of the model.
When `auth_en` is true the device wants HTTP digest auth, and the user name is
always `admin`. Do not put the password in the command. If no stored credential
exists for the plug, follow the credential rules in
`~/docs/devices/home_link.md` and explain that setup is required.
值得了解,虽然多数请求用不到:
- 超出 `apower` 的功率计量:电压、电流、频率,以及 `aenergy` 下的累计电量(瓦时),附带最近的每分钟历史记录。
- 内置光线传感器,上报为 `illuminance:0`。
- 开关配置中的过功率和过电流保护阈值。
- BLE 和 BTHome、MQTT、厂商云和 Matter。这些是替代的控制平面(control plane)。优先使用 Link 已能到达的网络上的本地 RPC API。
Worth knowing about, though most requests will not need them:
- Power metering beyond `apower`: voltage, current, frequency, and cumulative
energy in watt-hours under `aenergy`, with recent per-minute history.
- A built-in light sensor, reported under `illuminance:0`.
- Overpower and overcurrent protection thresholds, in the switch config.
- BLE and BTHome, MQTT, the vendor cloud, and Matter. These are alternative
control planes. Prefer the local RPC API over the network the Link already
reaches.