REST API¶
Same API as the WattWächter Plus
The REST API of the WattWächter Gas is the same as on the WattWächter Plus. The readings, however, carry the unit m³ in their names (e.g. import_total_m3, flow_m3h, consumption_m3 instead of import_total_kWh, power_W), feed-in values are missing, and /api/v1/history/latest additionally contains a gw block with sensor data. Which device answers is shown in /api/v1/system/info under esp.model_id (ww_gw_mf or ww_gw_id, ww_plus on the Plus).
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.
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
Switching (from firmware 1.3)¶
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| 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).
WattWächter Gas only: meter settings¶
The device checks all values under gw before saving anything. If one is out of range, the whole request is rejected with 400 and nothing changes.
Entering or correcting the meter reading¶
initialReading is the reading in m³ you currently see on the meter. The device counts on from this value; the correction does not count as consumption.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"gw": {"initialReading": 1234.567}}'
Each entry increments readingSeq (visible in GET /api/v1/settings under gw). The current reading is shown there as reading.
Medium, volume per revolution and sensitivity¶
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"gw": {
"medium": "gas",
"pulseVolume": 0.01,
"hysteresis": 250
}
}'
| Field | Range | Meaning |
|---|---|---|
medium |
"gas" or "water" |
What is counted |
pulseVolume |
0.0001–1 m³ | Volume per revolution of the counter wheel (gas typically 0.01, water 0.001) |
hysteresis |
magnetic (GW-MF): 10–5000 µT, default 250 · inductive (GW-ID): 5–500 counts, default 15 | Sensitivity or minimum swing of the detection |
Changing pulseVolume does not make the reading jump; only future revolutions count with the new value. Your variant is shown in GET /api/v1/system/info under esp.model_id (ww_gw_mf / ww_gw_id).
Conversion to kWh (gas only)¶
Calorific value and Z-number are on your gas bill. The device uses them to convert m³ to kWh (m³ × Z-number × calorific value).
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{"gw": {"calorificValue": 11.2, "zNumber": 0.9542}}'
| Field | Range |
|---|---|
calorificValue |
5–15 kWh/m³ |
zNumber |
0.8–1.2 |
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 or by the volume that has flowed. 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 flow and draw are possible — it measures gas or water, not power. A rule with export or import is rejected with 400 switch.rules[0]: source not available on this device.
draw and the volume condition both count cubic metres, but from a different moment: draw from the start of the flow, no matter what was switched. volume from the last change of the switched device.
In the API, flow and volumes are always in m³/h and m³. Which readings a device knows is listed in GET /api/v1/switch/status under sources.
Examples¶
A Shelly turns on a warning light when more than 2.5 m³/h of gas flow for 10 minutes, and off again when the flow stays below 0.5 m³/h for a minute.
curl -s -X POST $WW/api/v1/settings \
-H "Content-Type: application/json" \
-d '{
"switch": {
"rules": [
{
"name": "Gas warning light",
"enable": true,
"target": { "type": "shelly", "host": "192.168.178.60", "channel": 0 },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "flow", "op": "above", "value": 2.5, "delay": 600 }
] },
"off": { "match": "all", "conditions": [
{ "type": "value", "source": "flow", "op": "below", "value": 0.5, "delay": 60 }
] }
}
]
}
}'
More examples¶
Put the following rules into the rules list on their own or together (at most 4 rules per device).
Extractor hood when cooking with gas — minimum run time, name instead of IP, second output. If gas flows for 10 seconds, the extractor hood starts via output 2 of a Shelly Plus 2PM. It goes off once hardly anything flows for 5 minutes and it has run for at least 10 minutes.
{
"name": "Extractor hood",
"enable": true,
"target": { "type": "shelly", "host": "shelly-kitchen.local", "channel": 1 },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "flow", "op": "above", "value": 0.05, "delay": 10 }
] },
"off": { "match": "all", "conditions": [
{ "type": "value", "source": "flow", "op": "below", "value": 0.01, "delay": 300 },
{ "type": "state", "for": 600 }
] }
}
A lot of gas without a break. If more than 5 m³ are used without a break, a warning light turns on and goes off again after 30 minutes.
{
"name": "Gas 5 m³ without a break",
"enable": true,
"target": { "type": "shelly", "host": "192.168.178.62", "channel": 0 },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "draw", "op": "above", "value": 5, "delay": 0 }
] },
"off": { "match": "all", "conditions": [
{ "type": "state", "for": 1800 }
] }
}
Full load in the middle of the night — window and time of day, Tasmota, prepared. With night setback the heating hardly runs at night. If it draws more than 2 m³/h for 30 minutes between 00:00 and 05:00, a Tasmota plug turns on a warning light. At 07:00 it goes off. The rule is prepared but still switched off ("enable": false).
{
"name": "Gas at night",
"enable": false,
"target": { "type": "tasmota", "host": "192.168.178.62", "channel": 0 },
"on": { "match": "all", "conditions": [
{ "type": "window", "from": "00:00", "to": "05:00" },
{ "type": "value", "source": "flow", "op": "above", "value": 2, "delay": 1800 }
] },
"off": { "match": "all", "conditions": [
{ "type": "time", "at": "07:00" }
] }
}
Report high consumption — own URL, switch on only. If more than 3 m³/h flow for 15 minutes, a Wi-Fi plug that is neither a Shelly nor Tasmota turns on a warning light via its HTTP address. The off side stays empty: you turn the light off yourself after checking.
{
"name": "Gas warning lamp",
"enable": true,
"target": { "type": "url", "on_url": "http://192.168.178.62/relay?state=on", "off_url": "" },
"on": { "match": "all", "conditions": [
{ "type": "value", "source": "flow", "op": "above", "value": 3, "delay": 900 }
] },
"off": { "match": "all", "conditions": [] }
}
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. stateandvolumeneed 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 (sensor reports an error). 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. A meter that stands still is not an error: a flow of 0 is a valid reading. - 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 (flow, draw) |
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 |
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 |
export or import on a gas or water device |
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 |
volume out of range |
volume with 0 or less |
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 gw, 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"])
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":"gw.pulseVolume out of range (0.0001-1 m³)"} |
Value out of the allowed range |
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.