Skip to content

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:

  1. POST /api/v1/auth/tokens/generate — Generates new tokens (not yet active)
  2. 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 GET first 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 429 with Retry-After: 1. To change several areas, best do it in one request.
  • Response: {"success": true, "applied": {…}}. applied echoes 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 subsequent GET /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 with GET after 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_TOKEN or as X-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 name wattwaechter-…).
  • 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 if match is 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 time condition 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), time and window do not hold. The time the device currently assumes is in /switch/status under time. 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.
  • state need 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 value condition 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: export and import do not hold then, and GET /api/v1/switch/status reports direction_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.