REST API¶
The WattWächter REST API is available at http://wattwaechter-XXXXXXXXXXXX.local/api/v1/ and provides full access to device data, settings, and control functions.
Using Python? Use the library
For your own Python scripts there is the official aio-wattwaechter library. It handles requests, tokens and parsing the responses — see Python.
Authentication¶
Disabled by default
API authentication is disabled by default. All endpoints are accessible without a token. The one exception: writing from other web pages. Authentication can be enabled via the settings (api_auth_required: true).
When enabled, the API uses Bearer tokens in the Authorization header:
Authorization: Bearer YOUR_TOKEN
Alternatively, use the header X-Api-Token: YOUR_TOKEN.
There are two token levels:
- READ Token — Read data (history, status, view settings)
- WRITE Token — Change settings, start OTA, trigger reboot
Token Renewal
Tokens can be renewed via a two-phase process:
POST /api/v1/auth/tokens/generate— Generates new tokens (not yet active)POST /api/v1/auth/tokens/confirm— Activates the new tokens (within 60 seconds)
This two-phase approach prevents lockout if the response is lost.
Writing from other web pages (from firmware 1.3)¶
Even with authentication off, not every web page may write to the device. When a browser sends a request from a page that the device did not serve, the request needs the WRITE token. This keeps a foreign web page that somebody in the same network opens from changing settings or switching devices.
- Affected: all calls that change something (
POST,DELETE). Reading (GET) still works without a token. - Not affected: the device's web interface, the app, Home Assistant and your own scripts.
Without the token the device answers:
HTTP/1.1 403 Forbidden
Content-Type: application/json
{"error":"Write access from another web page needs the WRITE token"}
A web page of your own that is meant to write to the device sends the WRITE token:
fetch('http://wattwaechter-XXXXXXXXXXXX.local/api/v1/settings', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_WRITE_TOKEN'
},
body: JSON.stringify({ ledEnable: false })
});
The WRITE token is shown during initial setup. If you did not note it down, create new tokens in the web interface under Settings → API security.
Behind a reverse proxy
The device recognises a foreign page by an Origin header that names another host than the Host header. A reverse proxy therefore has to pass the Host header on (nginx: proxy_set_header Host $host;). Otherwise the device also refuses changes from its own web interface.
Rate Limits & Error Codes¶
Because the WattWächter runs on an ESP32 with limited memory, incoming API requests are throttled. Clients should honor the Retry-After header and back off accordingly.
Rate Limit¶
A maximum of 25 requests per 10 seconds is allowed (device-wide, not per IP — multiple clients share the budget). When the limit is exceeded, the device responds with:
HTTP/1.1 429 Too Many Requests
Retry-After: 10
Content-Type: application/json
{"error":"Too many requests"}
Heap Protection¶
If the free heap drops below a critical threshold (25 KB), new API requests are temporarily rejected to keep the device stable:
HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json
{"error":"Service temporary unavailable"}
This typically happens during very large responses (e.g. long history ranges) under concurrent load. Retrying after a few seconds usually succeeds.
Python Client
The Python library handles both 429 and 503 automatically and respects the Retry-After header.
Endpoint Overview¶
System¶
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/system/alive |
— | Health check |
| GET | /api/v1/system/info |
READ | System information |
| GET | /api/v1/system/led |
READ | LED status |
| GET | /api/v1/system/wifi_scan |
— | WiFi scan |
| GET | /api/v1/system/timezones |
READ | Timezone list |
| POST | /api/v1/system/reboot |
WRITE | Reboot |
History¶
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/history/latest |
READ | Latest reading |
| GET | /api/v1/history/highRes?date=YYYY-MM-DD |
READ | 15-min data for a day |
| GET | /api/v1/history/lowRes?start=YYYY-MM-DD&days=7 |
READ | Daily values |
Settings¶
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/settings |
READ | Read settings |
| POST | /api/v1/settings |
WRITE | Update settings (partial) — see Changing settings |
| POST | /api/v1/auth/tokens/generate |
WRITE | Generate new tokens |
| POST | /api/v1/auth/tokens/confirm |
WRITE | Activate tokens |
| GET | /api/v1/mqtt/ca |
READ | CA certificate status |
| POST | /api/v1/mqtt/ca |
WRITE | Upload CA certificate |
| DELETE | /api/v1/mqtt/ca |
WRITE | Delete CA certificate |
| POST | /api/v1/cloud/pair |
WRITE | Send cloud pairing token |
| GET | /api/v1/cloud/pair |
READ | Status of pairing and cloud connection |
| DELETE | /api/v1/cloud/pair |
WRITE | Remove cloud pairing; ?data=delete also deletes the cloud history |
OTA¶
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/ota/check |
READ | Check for update |
| POST | /api/v1/ota/start |
WRITE | Start update |
Logs¶
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/logs/rawdump |
READ | SmartMeter ring buffer (binary) |
| GET | /api/v1/logs/persistent |
READ | Persistent CSV log file |
| GET | /api/v1/logs/ram |
READ | RAM log snapshot (CSV) |
Modbus TCP¶
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/modbus/status |
READ | Modbus server status and current register map |
→ Details & activation: Modbus TCP
Emulation and switching (from firmware 1.3)¶
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| GET | /api/v1/emulation/status |
READ | Emulation (Shelly and EcoTracker): served values and devices asking |
| GET | /v1/json |
— | EcoTracker interface: current power and meter readings, only with the EcoTracker mode on |
| GET | /api/v1/switch/status |
READ | State of the switching rules |
| POST | /api/v1/switch/test |
WRITE | Switch a rule's device by hand or check the connection |
Turning features on and off and the rules themselves go through POST /api/v1/settings.
Changing settings (POST /api/v1/settings)¶
Everything you save in the web interface under Settings goes through this one endpoint. You can call it just the same from scripts, Home Assistant (rest_command), Node-RED or ioBroker.
How it works¶
- Only what you send changes. You don't need a
GETfirst and never send the whole configuration.{"ledEnable": false}only turns off the LED; everything else stays as it is. - Format: JSON with
Content-Type: application/json, at most 2 KB per request (from firmware 1.3: 8 KB). - One change per second. If the next request comes sooner, the device answers
429withRetry-After: 1. To change several areas, best do it in one request. - Response:
{"success": true, "applied": {…}}.appliedechoes your request — not the stored state. Passwords are left out from firmware 1.3; older firmware returns them in clear text. Whether a value arrived is shown by a subsequentGET /api/v1/settings. - Passwords (Wi-Fi, access point, MQTT, NES meter) are never returned by
GET, only whether one is set (password_set,passwordSet). Leave the field out = password stays; empty text""= password is deleted. - Unknown top-level fields are rejected with
400(Unknown field: …), so a typo shows up. Unknown nested fields (e.g.mqtt.hots), however, are silently ignored; check withGETafter saving. - Most changes take effect immediately, without a restart: MQTT reconnects, Modbus starts or stops, the access point restarts, the time zone applies at once. Wi-Fi changes trigger a reconnect — see Changing Wi-Fi.
- With API protection you need the WRITE token, either as
Authorization: Bearer YOUR_WRITE_TOKENor asX-Api-Token: YOUR_WRITE_TOKEN.
In the examples, WW stands for your device's address, e.g.:
WW=http://wattwaechter-XXXXXXXXXXXX.local # or the IP address, e.g. http://192.168.178.50
If API protection is on, add -H "Authorization: Bearer YOUR_WRITE_TOKEN" to every call.
Reading the current settings¶
curl -s $WW/api/v1/settings
The response has the same structure you use for writing. It also contains display-only values such as rebootsTotal or password_set, which cannot be written.
Device name¶
Shown in the web interface, in Home Assistant and in the app. At most 31 characters.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"device_name": "Basement main meter"}'
Turning the status LED off or on¶
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"ledEnable": false}'
Time zone, time server and language¶
GET /api/v1/system/timezones lists the allowed time zones; an unknown name is rejected with 400 Invalid timezone. The web interface language is de or en.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"timezone": "Europe/Berlin",
"ntp_server": "fritz.box",
"language": { "active": "en" }
}'
Changing Wi-Fi¶
Careful: you can lock yourself out
After a Wi-Fi change the device reconnects. If SSID or password are wrong, it is no longer reachable on the old network. It then falls back to the fallback Wi-Fi or the access point. The response arrives before the switch — it only confirms that the values were stored, not that the connection works.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"wifi": {
"primary": { "ssid": "MyWiFi", "password": "secret-password" }
}
}'
The SSID may have at most 32 characters (otherwise 400). If nothing changes in the Wi-Fi fields, the device doesn't reconnect either.
Fixed IP address¶
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"wifi": {
"primary": {
"static_ip": true,
"ip": "192.168.178.50",
"subnet": "255.255.255.0",
"gateway": "192.168.178.1",
"dns": "192.168.178.1"
}
}
}'
Back to DHCP: {"wifi": {"primary": {"static_ip": false}}}. Simpler and safer is usually to give the WattWächter a fixed address in your router.
Fallback Wi-Fi¶
A second network the WattWächter uses when the first one is unreachable (e.g. a repeater in the basement).
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"wifi": {
"secondary": { "enable": true, "ssid": "MyWiFi-Basement", "password": "other-password" }
}
}'
Access point¶
The access point is the WattWächter's own Wi-Fi for setup. Turn it off:
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"accessPoint": {"enable": false}}'
With your own name and password:
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"accessPoint": {
"enable": true,
"ssid": "WattWaechter-Basement",
"password_enable": true,
"password": "atleast8chars"
}
}'
Password with at least 8 characters
WPA2 requires 8 to 63 characters. From firmware 1.3 the API rejects a shorter or longer password with 400. Older firmware accepts it, but the access point then starts without a password. An empty password clears the password, an empty ssid restores the automatic name.
MQTT¶
Set up a connection to your own broker (here Mosquitto in Home Assistant without TLS):
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"mqtt": {
"enable": true,
"host": "homeassistant.local",
"port": 1883,
"use_tls": false,
"user": "wattwaechter",
"password": "mqtt-password",
"sendInterval": 10
}
}'
sendInterval: seconds between two reading messages, at least 1.client_id: the name the device uses to log in to the broker. Empty text""restores the default (the host namewattwaechter-…).topic_prefix: start of all topics, e.g."WattWaechter/basement".- Upload your own CA certificate for TLS separately via
POST /api/v1/mqtt/ca.
Change only the interval — the other MQTT values stay:
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"mqtt": {"sendInterval": 60}}'
GET /api/v1/mqtt/status shows whether the connection is up. More under MQTT.
Modbus TCP¶
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"modbus": {"enable": true, "port": 502}}'
The server starts immediately. GET /api/v1/modbus/status shows which registers it serves — see Modbus TCP.
Automatic updates and cloud¶
# Stop installing updates automatically at night
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"autoOta": false}'
# Pause the connection to the WattWächter cloud (the pairing stays)
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"awsIotEnabled": false}'
The cloud pairing itself is controlled via POST/DELETE /api/v1/cloud/pair.
Turning on API protection¶
From then on almost every call needs a token (except e.g. /system/alive). So that you don't lock yourself out, the device only accepts the change if you already send the WRITE token with it — otherwise it answers 403. The tokens are in the web interface under Settings → API security.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_WRITE_TOKEN" \
-d '{"api_auth_required": true}'
Turning it off: {"api_auth_required": false} (also with the WRITE token, since protection is still on at that point).
Electricity meter only (WattWächter Plus)¶
Current transformer ratio¶
For meters behind current transformers (semi-direct metering): the ratio multiplies currents, power and meter readings, e.g. 50 for a 250/5 A transformer. Allowed are 1 to 10000; invalid values set the ratio to 1 (direct metering). Applies from the next telegram; earlier values stay unchanged.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"ctRatio": 50}'
Smoothing (median filter)¶
Only for meters with OBIS/D0 protocol: number of readings the median is taken from (1 to 9, default 5; 1 = no smoothing). SML meters ignore the value.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"medianFilterSize": 3}'
NES meters (C12.18)¶
Credentials from the metering point operator and the polling behaviour — details under NES meters.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"c1218": {
"password": "PASSWORD-FROM-OPERATOR",
"userId": 2,
"idleStart": "02:10",
"idleSeconds": 480,
"pollSeconds": 2,
"logoffMinutes": 8
}
}'
| Field | Range | Meaning |
|---|---|---|
password |
at most 20 characters | "" deletes the password |
userId |
0–65535 | User ID for the logon (default 2) |
idleStart |
"HH:MM" |
Start of the daily quiet window |
idleSeconds |
0–3600 | Length of the quiet window, 0 = none |
pollSeconds |
1–300 | Polling interval |
logoffMinutes |
0–1440 | Rebuild the session after this many minutes, 0 = keep open |
Emulation: Shelly and EcoTracker (from firmware 1.3)¶
Some devices cannot read the WattWächter Plus directly, but they can read an EcoTracker or a Shelly Pro 3EM — many batteries and inverters, for example. For them the WattWächter Plus speaks that protocol. Your device then reads the values directly from your electricity meter, no extra measuring device in the distribution board is needed. In the web interface: Settings → Emulation.
There are two protocols under emulation. Both are off by default, both may be on at the same time. If your device supports both, use EcoTracker.
| Setting | Protocol | For | How the battery finds the WattWächter |
|---|---|---|---|
emulation.ecotracker |
EcoTracker | Batteries that offer the EcoTracker as a meter, e.g. EcoFlow STREAM, Growatt NOAH, Hoymiles, Marstek | via mDNS as ecotracker-… (_everhome._tcp), otherwise enter the IP address |
emulation.shelly |
Shelly Pro 3EM | Only batteries that accept no other meter | Marstek via UDP broadcast, others via mDNS as shellypro3em-… (_shelly._tcp, _http._tcp), otherwise enter the IP address |
It does not work with manufacturers that couple the meter via the cloud: the EcoTracker via the everHome account (e.g. Zendure), the Shelly via the Shelly cloud (e.g. Zendure, Anker, EcoFlow).
The host name stays wattwaechter-….local, and the WattWächter can still be found as _wattwaechter._tcp.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"emulation": {"shelly": {"enable": true}, "ecotracker": {"enable": true}}}'
GET /api/v1/emulation/status shows what is currently served and which devices are asking, for both modes. If it says value.direction_unknown: true, the meter reports the power without a direction (import or feed-in) — the WattWächter does not pass it on then, and value.valid is false. This also applies when it reads the direction from the meter readings: close to 0 W, where a battery regulates, it would come too late.
With the EcoTracker mode on, the WattWächter answers GET /v1/json on port 80 — without a token and outside /api/v1. Via mDNS it announces itself as _everhome._tcp.
curl -s $WW/v1/json
{
"power": -3127,
"powerAvg": -3114,
"agePower": 496,
"powerPhase1": -1025,
"powerPhase2": -1176,
"powerPhase3": -926,
"energyCounterOut": 5552927.8,
"energyCounterIn": 1541618.4
}
| Field | Unit | Meaning |
|---|---|---|
power |
W | Current power: positive = import, negative = feed-in |
powerAvg |
W | Average of the last minute |
agePower |
ms | Age of the reading |
powerPhase1 to powerPhase3 |
W | Power per phase, only if the meter delivers valid per-phase values |
energyCounterIn, energyCounterOut |
Wh | Meter reading import (1.8.0) and feed-in (2.8.0) — in Wh, not kWh. Missing if the meter does not provide it |
energyCounterInT1, energyCounterInT2 |
Wh | Import tariff 1 and 2, only if the meter delivers 1.8.1 and 1.8.2 |
Without a current reading, /v1/json delivers no values (empty JSON), like a real EcoTracker. If the mode is off, the answer is 404. Nothing can be changed through these interfaces.
Jackery
Jackery batteries probably do not work with the EcoTracker mode. They keep the HTTP connection to the EcoTracker open, but the WattWächter's web server closes every connection after the answer.
"Shelly" is a trademark of Shelly Group, "EcoTracker" a trademark of everHome GmbH. The WattWächter is not a product of these companies. The emulation uses the communication protocols of the EcoTracker and the Shelly Pro 3EM so that batteries and inverters that only support these meters can read the values.
Switching devices (from firmware 1.3)¶
Switching rules turn a Shelly or another device with an HTTP interface on or off — by readings, time of day and run time. Up to 4 rules. In the web interface you find them under Settings → Switching.
The list is always replaced completely
Unlike the other settings, switch.rules is not a partial update: you send all rules that should apply afterwards. A rule missing from the list is deleted. So read the current list first with GET /api/v1/settings (field switch.rules), change it and send it back in full. If one rule is invalid, nothing is saved.
Structure of a rule¶
Every rule has a target (target) and two sides: on says when to switch on, off when to switch off. Each side has up to 4 conditions (conditions). match sets how they are combined:
"all": all conditions must hold (AND). This also applies ifmatchis missing."any": one condition is enough (OR).
A side may stay empty ("conditions": []). Then the rule never switches in that direction — for example a valve that it only closes, but never opens. At least one side needs a condition.
{
"name": "Example",
"enable": true,
"target": { "type": "shelly", "host": "192.168.178.60", "channel": 0 },
"on": { "match": "all", "conditions": [ … ] },
"off": { "match": "any", "conditions": [ … ] }
}
| Field | Values | Meaning |
|---|---|---|
name |
at most 31 characters | Display name |
enable |
true / false |
Rule active. If the field is missing, it is active |
target.type |
shelly, tasmota or url |
Shelly (Gen1 and Gen2+, detected automatically), Tasmota device or your own address for any other device |
target.host |
IP or name, optionally with :port |
For shelly and tasmota, without http:// |
target.channel |
0–3 (shelly), 0–7 (tasmota) |
Output, counted from 0: the id on a Shelly; on Tasmota 0 stands for Power1, 1 for Power2 and so on |
target.on_url, target.off_url |
http://…, at most 159 characters |
Only for url: called with GET. https is not supported. A side with conditions needs its address, the other one may be empty ("") |
on, off |
match: all or any · conditions: up to 4 |
Switch-on or switch-off side |
Conditions¶
type |
Fields | Met when … | Device |
|---|---|---|---|
value |
source, op (above or below), value, delay (0–86400 s, default 0) |
the reading is above or below value — without a break for at least delay seconds |
all, readings see below |
time |
at ("HH:MM"), days |
it is exactly this time. Holds for the whole minute | all |
window |
from, to ("HH:MM"), days |
the time is from from and before to. Also works across midnight |
all |
state |
for (1–604800 s) |
the device has been in the opposite state for at least for seconds: on the off side on for, on the on side off for |
all |
volume |
value (m³, greater than 0) |
at least this much has flowed since the last change — on the off side that means since switching on | Gas and Water only |
days is a list of weekdays: 1 = Monday to 7 = Sunday. If the field is missing, every day applies. A window across midnight belongs to the day on which it starts: {"type": "window", "from": "22:00", "to": "06:00", "days": [5]} holds from Friday 22:00 to Saturday 06:00.
With state you build run times and pauses. On the off side with "any" it is a maximum run time (off after … at the latest), with "all" a minimum run time (off after … at the earliest). On the on side the same applies to the pause.
Which readings? (source)¶
A value condition watches one of four readings. Which ones a device knows depends on what it measures:
source |
Unit | Device | What is measured |
|---|---|---|---|
export |
W | WattWächter Plus | Surplus = feed-in to the grid. Positive while you feed in, negative while importing |
import |
W | WattWächter Plus | Grid import. Positive while you draw power, negative while feeding in |
flow |
m³/h | WattWächter Gas, WattWächter Water | Flow rate at the meter, calculated from the pulses, never negative |
draw |
m³ | WattWächter Gas, WattWächter Water | Volume without a break: what has flowed since the current flow began. When the flow drops to 0 it starts over |
export and import are the same reading (the current power at the meter, OBIS 16.7.0) with opposite signs: "export" with above 1500 means "more than 1500 W feed-in", "import" with above 1500 means "more than 1500 W import". Use whichever makes your threshold read naturally; export below 0 is the same as import above 0.
On this device export and import are possible. flow, draw and the volume condition only exist on the WattWächter Gas and Water; here the device rejects them with 400 switch.rules[0]: source not available on this device or volume is only available on gas and water devices. Which readings a device knows is listed in GET /api/v1/switch/status under sources.
Examples¶
An immersion heater is switched on via a Shelly as soon as more than 1500 W are fed in for 60 seconds — but only between 9:00 and 17:00. It goes off when the surplus stays below 100 W for 60 seconds or it has run for 2 hours. After the 2 hours it only comes back on once the on side has not held for a moment and is then met anew.
Plus load shedding for the sauna via a Tasmota plug: if the house draws more than 6000 W from the grid for 5 seconds, it goes off. Once the import stays below 3000 W for 5 minutes, it comes back.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"switch": {
"rules": [
{
"name": "Heater",
"enable": true,
"target": { "type": "shelly", "host": "192.168.178.60", "channel": 0 },
"on": {
"match": "all",
"conditions": [
{ "type": "value", "source": "export", "op": "above", "value": 1500, "delay": 60 },
{ "type": "window", "from": "09:00", "to": "17:00" }
]
},
"off": {
"match": "any",
"conditions": [
{ "type": "value", "source": "export", "op": "below", "value": 100, "delay": 60 },
{ "type": "state", "for": 7200 }
]
}
},
{
"name": "Sauna load shedding",
"enable": true,
"target": { "type": "tasmota", "host": "192.168.178.61", "channel": 0 },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "import", "op": "below", "value": 3000, "delay": 300 }
] },
"off": { "match": "all", "conditions": [
{ "type": "value", "source": "import", "op": "above", "value": 6000, "delay": 5 }
] }
}
]
}
}'
More examples¶
Put the following rules into the rules list on their own or together (at most 4 rules per device).
Heat pump on surplus — minimum run time, name instead of IP, second output. Enables the heat pump via output 2 of a Shelly Plus 2PM when more than 3000 W are left over for 5 minutes. The off side is combined with "all": it only goes off once the surplus stays below 500 W for 10 minutes and it has run for at least 30 minutes. This protects the compressor.
{
"name": "Heat pump SG-Ready",
"enable": true,
"target": { "type": "shelly", "host": "shelly-heatpump.local", "channel": 1 },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "export", "op": "above", "value": 3000, "delay": 300 }
] },
"off": { "match": "all", "conditions": [
{ "type": "value", "source": "export", "op": "below", "value": 500, "delay": 600 },
{ "type": "state", "for": 1800 }
] }
}
Switch on only — own URL without an off address. Starts the dishwasher via a Wi-Fi plug that is neither a Shelly nor Tasmota and is switched by an HTTP address, as soon as more than 1000 W are left over for 2 minutes. The off side stays empty: the machine finishes its programme by itself, so the rule needs no off_url.
{
"name": "Start dishwasher",
"enable": true,
"target": { "type": "url", "on_url": "http://192.168.178.62/relay?state=on", "off_url": "" },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "export", "op": "above", "value": 1000, "delay": 120 }
] },
"off": { "match": "all", "conditions": [] }
}
Water heater on the night tariff — time of day and weekdays, port, prepared. Monday to Friday on at 22:00, off every morning at 06:00. At the weekend it stays off. The Shelly is given with a port, the rule is prepared but still switched off ("enable": false).
{
"name": "Night tariff boiler",
"enable": false,
"target": { "type": "shelly", "host": "192.168.178.63:8080", "channel": 0 },
"on": { "match": "all", "conditions": [
{ "type": "time", "at": "22:00", "days": [1, 2, 3, 4, 5] }
] },
"off": { "match": "all", "conditions": [
{ "type": "time", "at": "06:00" }
] }
}
Pure timer without a reading. A pump runs for 5 minutes, pauses for 25 minutes, and so on. Both sides only ask how long the device has been in the opposite state. Counting starts the moment the WattWächter knows the Shelly's state. A restart of the WattWächter does not interrupt it.
{
"name": "Cycle 5/25",
"enable": true,
"target": { "type": "shelly", "host": "192.168.178.64", "channel": 0 },
"on": { "match": "all", "conditions": [ { "type": "state", "for": 1500 } ] },
"off": { "match": "all", "conditions": [ { "type": "state", "for": 300 } ] }
}
What the examples show together
| Variant | Where |
|---|---|
Shelly with IP, name (….local) or IP:port |
host |
| Second output of a multi-channel Shelly | "channel": 1 |
Tasmota device, first output (Power1) |
"type": "tasmota", "channel": 0 |
| Own URL, also with an on address only | "type": "url", "off_url": "" |
| Switch on only or off only | Leave the other side empty: "conditions": [] |
| Several conditions | "match": "all" (AND) or "match": "any" (OR) |
| Minimum / maximum run time | state on the off side, with all or any |
| Time of day, window, weekdays | time, window, days |
| Switch at once | "delay": 0 |
| Prepare a rule without activating it yet | "enable": false |
Delete all rules:
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"switch": {"rules": []}}'
Behaviour¶
- A side switches when it is newly met — once while it keeps holding. A
timecondition holds for one minute and so switches once a day. - Switched by hand stays switched. If you switch the device (on the Shelly, in its app or via
/switch/test), the rule does not overrule you while its side keeps holding. Only once the side has cleared and is met again does it switch again. - If both sides become met at the same moment, switching off wins. The on side only switches again once it has not held for a moment.
- Time of day and weekday follow the device's time zone. Until the clock is set by the time server (NTP),
timeandwindowdo not hold. The time the device currently assumes is in/switch/statusundertime. A missed switch time (time) is caught up for up to 15 minutes: every 30 seconds while the target cannot be reached, once after a gap in Wi-Fi, not after a power failure. stateneed the device's state. The WattWächter polls a Shelly and a Tasmota device every 30 seconds, so changes by hand count too. With your own URL it only knows the state after it has switched itself — before that these conditions do not hold. So start a timer with your own URL once via/switch/test.- State and duration survive a restart. For each rule the WattWächter remembers the state and the time of the last change. After a restart “on for” and “off for” continue from there — for Shelly and Tasmota provided the device is still in the same state. A changed rule starts over.
- Without a fresh reading a
valuecondition does not hold (reading older than 10 seconds). Its delay starts over afterwards. This also applies to the switch-off side: without a reading a device that is on stays on. To guard against that, give the switch-off side with"any"a maximum running time as well (state). The web interface shows a hint at the rule while the reading is missing. The same applies while the meter reports the power without a direction (only the magnitude) and the WattWächter could not read it from the meter readings yet either:exportandimportdo not hold then, andGET /api/v1/switch/statusreportsdirection_unknown: true. If the meter delivers a reading less often, for example every 35 seconds in request mode, the limit follows its rhythm: two intervals plus 5 seconds. - If a command fails (device unreachable), the WattWächter tries again after 30 seconds.
- A missed switching time (
time) is caught up for up to 15 minutes. If the device cannot be reached during the switching minute, the WattWächter keeps trying. If it could not evaluate during that minute itself (no WiFi, clock not yet set, start takes longer), it switches at the next opportunity — unless the device has already changed since the switching time. After a power failure nothing is caught up. - Password-protected Shellys and Tasmota devices are not supported yet. A Tasmota device with a password can be switched via
url:http://<ip>/cm?user=admin&password=<password>&cmnd=Power%20On.
Querying the state and testing by hand¶
curl -s $WW/api/v1/switch/status
# Switch rule 0's device on by hand (does not count as a switching action of the rule)
curl -s -X POST $WW/api/v1/switch/test \
-H "Content-Type: application/json" \
-d '{"rule": 0, "action": "on"}'
# Only check the connection to the Shelly
curl -s -X POST $WW/api/v1/switch/test \
-H "Content-Type: application/json" \
-d '{"rule": 0, "action": "check"}'
/switch/test answers 202 at once; the result appears one to three seconds later in /switch/status under manual.
Fields in GET /api/v1/switch/status:
| Field | Meaning |
|---|---|
sources |
Readings this device knows (export, import) |
volume |
true if volume conditions are possible (Gas and Water) |
max_rules, max_conds |
Maximum number of rules (4) and conditions per side (4) |
time, weekday |
Device time ("HH:MM") and weekday (1 = Monday); null while the clock is not set |
rules[].commanded |
Last own command of the rule: on, off or unknown |
rules[].actual, actual_s |
Device state (on, off, unknown) and how many seconds ago it was last read or set |
rules[].gen, model |
Detected Shelly: generation and model (0 and empty for tasmota and url) |
rules[].state_s |
Seconds in the current state |
rules[].volume_since |
m³ since the last change (Gas and Water only, null here) |
rules[].on, rules[].off |
met: side currently met. Per condition in conds: met, wait_s (seconds until it holds; -1 = not foreseeable) and value (current reading for value conditions, otherwise null) |
rules[].last_action |
Last switching action: cmd, auto (true = by the rule) and s (seconds ago) |
rules[].error |
Last error: code (unreachable, auth, not_shelly, not_tasmota, bad_reply) and s |
rules[].manual |
Result of /switch/test: ok and s, or pending |
Switching rule error messages¶
The device rejects an invalid rule with 400, e.g. {"success":false,"error":"switch.rules[1]: at most 4 conditions per side"}. The number in square brackets is the rule's number, counted from 0.
| Message | Cause |
|---|---|
switch.rules: at most 4 rules |
More than 4 rules |
rule needs at least one condition |
Both sides empty |
match must be all or any |
match is neither all nor any |
at most 4 conditions per side |
More than 4 conditions on one side |
condition type must be value, time, window, state or volume |
Unknown type |
source must be export, import, flow or draw |
Unknown source |
source not available on this device |
flow or draw on the WattWächter Plus |
volume is only available on gas and water devices |
volume condition on the WattWächter Plus |
condition op must be above or below |
op missing or wrong |
threshold must be a number |
value missing or not a number |
delay out of range (0-86400 s) |
delay negative or longer than 24 hours |
time must be HH:MM |
at, from or to not in the format "HH:MM" |
window start and end must differ |
from and to are equal |
days must be a list of weekdays 1-7 |
days is not a list or contains something other than 1–7 |
at least one weekday |
days is empty |
duration out of range (1-604800 s) |
for missing, 0 or longer than 7 days |
switching on needs target.on_url |
On side with conditions but empty on_url (likewise switching off needs target.off_url) |
target needs on_url or off_url |
Own URL without addresses |
target.host must be an IP address or host name |
host empty, too long or with http://, a path or spaces |
target.channel out of range (0-3) or (0-7) |
Output outside 0–3 (Shelly) or 0–7 (Tasmota) |
name too long (max 31) |
Name too long |
Several areas at once¶
Everything in one request saves waiting (one change per second) and is atomic: if a value is invalid, nothing is saved.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"device_name": "Basement",
"ledEnable": false,
"timezone": "Europe/Berlin",
"mqtt": { "enable": true, "host": "192.168.178.10", "port": 1883, "use_tls": false },
"modbus": { "enable": true }
}'
Atomic applies to the checks
The request is rejected before saving for: an unknown top-level field, an SSID that is too long, invalid values under c1218, switch and an invalid time zone. Other values (e.g. a port number out of range) are not reported as errors but ignored or clamped.
From Python¶
import requests
WW = "http://wattwaechter-XXXXXXXXXXXX.local"
HEADERS = {} # with API protection: {"Authorization": "Bearer YOUR_WRITE_TOKEN"}
r = requests.post(f"{WW}/api/v1/settings",
json={"mqtt": {"sendInterval": 30}},
headers=HEADERS, timeout=10)
if r.status_code == 429:
# too fast in a row: wait briefly and send again
...
r.raise_for_status()
print(requests.get(f"{WW}/api/v1/settings", headers=HEADERS, timeout=10).json()["mqtt"])
For your own programs the aio-wattwaechter library is more convenient — see Python.
Error messages¶
| Status | Response (example) | Cause |
|---|---|---|
400 |
{"error":"Missing JSON body"} |
No body, or Content-Type is not application/json |
400 |
{"error":"Invalid JSON"} |
Not valid JSON (e.g. a trailing comma) |
400 |
{"success":false,"error":"Unknown field: ledEnabled"} |
Typo in a top-level field name |
400 |
{"success":false,"error":"Modifying reboot counters is forbidden"} |
rebootCounter, rebootsTotal, rebootsAll are read-only |
400 |
{"success":false,"error":"SSID too long (max 32 chars): wifi.primary.ssid"} |
SSID longer than 32 characters |
400 |
{"error":"Invalid timezone"} |
Time zone not in /api/v1/system/timezones |
400 |
{"success":false,"error":"c1218.password too long (max 20 chars)"} |
Value out of the allowed range |
400 |
{"success":false,"error":"gw settings not supported on this device (not_gw)"} |
gw only exists on gas/water devices |
400 |
{"success":false,"error":"switch.rules[0]: at most 4 conditions per side"} |
Invalid switching rule (number in square brackets), see Switching rule error messages |
401 |
API protection on, token missing or wrong | |
403 |
{"success":false,"error":"To enable API authentication, you must provide the WRITE token. …"} |
Turning on API protection without the WRITE token |
403 |
{"error":"Write access from another web page needs the WRITE token"} |
Browser request from another web page without the WRITE token, see Writing from other web pages |
413 |
{"error":"Request body too large. Max 2KB allowed."} |
Request too large (from firmware 1.3: 8 KB) |
429 |
{"error":"Too many settings updates. Wait 1 second."} |
Less than 1 second since the last change (Retry-After: 1) |
429 |
{"error":"Settings update in progress. Try again."} |
Another change is in progress |
Interactive API Documentation¶
The full API specification in OpenAPI format:
Note
The API documentation is automatically generated from the firmware's OpenAPI specification.