Device Settings¶

Document Context¶

Purpose: Configure device system settings, service enablement, and authentication protection
When to use: For initial device setup, service configuration, security setup, or system administration
Prerequisites: Network access to device; understanding of intended services and security requirements
Related to: Device initialization, service management, Web UI protection, cloud integrations
Validates against: Real device settings from whatwatt Go hardware

Key Facts¶

Endpoint: /api/v1/settings
Methods: GET, POST, PUT
Authentication: Required when device Web UI password is set
Dynamic apply: Changes take effect immediately without reboot
Response format: JSON with nested system and services objects
Sections: system (device identity, protection) and services (cloud/local integrations)
License-dependent services: Some services configured here remain inactive on FREE, including local Solar Manager report access, myStrom cloud, meter proxy, Modbus TCP, and Berry script execution
No reboot needed: Configuration changes apply dynamically
Error codes: 400 (invalid config), 401 (auth required)

Endpoint Details¶

This endpoint manages the device's basic system settings and enables/disables built-in services.

License-dependent services

Some service switches described on this page can be configured on all editions, but the firmware activates them only when the device has an active Plus or higher license. This applies to the local Solar Manager report endpoint, myStrom cloud, meter proxy, Modbus TCP, and Berry script execution.

Endpoint	`api/v1/settings`
Method	GET, POST, PUT
Response content type	application/json

Dynamic apply

Configuration changes are applied without requiring a device reboot. The Web UI and HTTP pages reload dynamically after updates. Avoid reboots during operation; only firmware upgrades trigger an automatic restart.

Object schema¶

Top-level sections
system: device-identifying properties and access protection
services: cloud/local integrations and built-in services

Fields: system¶

JSON path	Type	Default	Range/Rules	Notes
`system.name`	string	""	length 0..31	Friendly device name.
`system.host_name`	string	`whatwatt_XXXXXX`	length 0..31; must be a valid hostname	Used on network and for realm; write rejected if invalid.
`system.protection`	boolean	false		When true and `password` set, HTTP auth is enforced.
`system.password`	string	""	length 0..31	Write-only; hidden in GET responses.
`system.power_save`	boolean	false		Global power save mode; see constraint below.
`system.p1_wifi_boost`	boolean	true		When true and P1 is connected, disables Wi‑Fi power save to boost throughput.
`system.use_dhcp_ntp_server`	boolean	false		Adds NTP server learned from DHCP to the time sync list.
`system.custom_ntp_server`	string	""	length 0..127	must be a valid hostname or IP. Optional custom NTP server used by low-power reporting.
`system.use_custom_ntp_server`	boolean	false		Enables `custom_ntp_server` when the value is non-empty and valid.

Constraints

Enabling system.power_save is rejected while the Ethernet link is UP (request returns 400).
system.host_name must be valid; invalid value causes 400.
system.custom_ntp_server must be a valid hostname or IP; invalid value is discarded and system.use_custom_ntp_server is cleared.

Power Management Decision Trees¶

The device implements intelligent power management based on connection type and configuration settings.

Wi-Fi Power Save Logic¶

flowchart TD
  %% Colors controlled via CSS (see assets/extra.css)

  A[Wi‑Fi Power Management] --> B{power_save enabled?}
  B -->|Yes| C[Wi‑Fi Power Save: ON]
  B -->|No| D{USB connected?}
  D -->|Yes| G[Wi‑Fi Power Save: OFF<br/>Faster performance]
  D -->|No| E{P1 connected AND p1_wifi_boost?}
  E -->|Yes| G[Wi‑Fi Power Save: OFF<br/>Faster performance]
  E -->|No| H[Wi‑Fi Power Save: ON<br/>Lower power]

  class A title;
  class B,E,D decision;
  class C,H bad;
  class G good;

Ethernet Enable Logic¶

flowchart TD
  %% Colors controlled via CSS (see assets/extra.css)

  A[Ethernet Management] --> B{power_save enabled?}
  B -->|Yes| C[Ethernet: DISABLED]
  B -->|No| D{USB connected?}
  D -->|Yes| E{ethernet.enable?}
  D -->|No| F[Ethernet: DISABLED]
  E -->|Yes| G[Ethernet: ENABLED]
  E -->|No| F

  class A title;
  class B,D,E decision;
  class C,F bad;
  class G good;

Key Points:

Global power_save: Overrides all other settings (Wi-Fi power save ON, Ethernet OFF)
p1_wifi_boost: When enabled and P1 is connected, Wi‑Fi power save is disabled (higher throughput)
USB connection: Indicates external power, enabling faster performance
P1 connection: With boost enabled, active P1 link disables Wi‑Fi power save
Ethernet: Enabled when USB power is present AND ethernet.enable is set; disabled when power_save is true

Fields: services¶

JSON path	Type	Default	Range/Rules	Notes
`services.cloud.what_watt`	boolean	true		whatwatt Cloud integration
`services.cloud.solar_manager`	boolean	false		Solar Manager cloud
`services.cloud.mystrom`	boolean	true		myStrom cloud; inactive on `FREE`
`services.cloud.stromkonto`	boolean	false		Stromkonto cloud
`services.local.solar_manager`	boolean	false		Local Solar Manager API; report endpoint requires Plus or higher
`services.broadcast`	boolean	true		mDNS broadcast (discovery)
`services.other_energy_provider`	boolean	false		Enable other energy provider features
`services.report_interval`	uint	30	1..3600 (seconds)	Cloud/custom reporting interval
`services.low_power_report`	boolean	false		Uses the low-power reporting flow when a meter interface is configured.
`services.log`	boolean	false		Enable internal log service
`services.meter_proxy`	boolean	false		Enable meter proxy service; inactive on `FREE`
`services.sd.enable`	boolean	false		Store periodic reports to SD card
`services.sd.frequency`	uint	15	1..1440 (seconds)	SD write cadence
`services.sd.recorder_mode`	boolean	false		Standalone SD recorder mode (FW 2.0.1+)
`services.modbus.enable`	boolean	false		Modbus TCP server; inactive on `FREE`
`services.modbus.port`	uint	502	1..65535	Modbus TCP port
`services.berry.auto_run`	boolean	false		Auto-run Berry script on boot; execution requires Plus or higher
`services.berry.run_delay`	uint	300	60..86400 (seconds)	Delay before auto-run

Constraints

services.low_power_report affects startup only when meter.if_type != auto; without a configured meter interface it has no effect.
In low-power mode, NTP uses DHCP and custom server options from the system section.

Examples¶

Read current settings¶

No authWith password

curl http://whatwatt-XXXXXX.local/api/v1/settings

curl --anyauth -u :PASSWORD http://whatwatt-XXXXXX.local/api/v1/settings

Example response (abridged):

{
  "system": {
    "name": "",
    "host_name": "whatwatt_9F8124",
    "protection": false,
    "power_save": false,
    "p1_wifi_boost": true,
    "use_dhcp_ntp_server": true,
    "custom_ntp_server": "time.cloudflare.com",
    "use_custom_ntp_server": false
  },
  "services": {
    "cloud": {
      "what_watt": true,
      "solar_manager": false,
      "mystrom": false,
      "stromkonto": false
    },
    "local": {
      "solar_manager": false
    },
    "broadcast": true,
    "other_energy_provider": false,
    "report_interval": 30,
    "low_power_report": false,
    "log": false,
    "meter_proxy": false,
    "sd": { "enable": false, "frequency": 15, "recorder_mode": false },
    "modbus": { "enable": false, "port": 502 },
    "berry": { "auto_run": false, "run_delay": 300 }
  }
}

Partial vs. Full Update

Partial update: Use PUT with only the fields you want to change. Unspecified fields remain unchanged.
Full replace: Use POST with the complete object when the API defines a "replace" operation; missing fields may reset to defaults.
Validation: Invalid payloads return 400 Bad Request.

Enable Web UI protection¶

{
  "system": {
    "protection": true,
    "password": "your-secure-password"
  }
}

Configure SD card reports logging¶

{
  "services": {
    "sd": { "enable": true, "frequency": 60 }
  }
}

Configure NTP for low-power reporting¶

{
  "system": {
    "use_dhcp_ntp_server": false,
    "custom_ntp_server": "pool.ntp.org",
    "use_custom_ntp_server": true
  },
  "services": {
    "low_power_report": true
  }
}

This combination is useful when the device should wake, synchronize time, send a report, and return to low-power operation using a configured meter interface.

Enable Modbus TCP¶

{
  "services": {
    "modbus": { "enable": true, "port": 502 }
  }
}

Use services.modbus.enable to turn the Modbus TCP server on or off and services.modbus.port to choose the listening port. The complete Modbus TCP service, register mapping, and /api/v1/modbus documentation is covered on the Modbus TCP page.

Configure Berry auto-run¶

{
  "services": {
    "berry": { "auto_run": true, "run_delay": 300 }
  }
}

Use services.berry.auto_run to start the saved Berry script automatically after boot and services.berry.run_delay to delay execution until the device is ready. Berry script execution and auto-run require an active Plus or higher license at runtime. The complete Berry scripting, /api/v1/berry, and Berry editor documentation in the main Web UI is covered on the Berry scripting page.

Method semantics¶

GET: returns current settings (with system.password hidden)
PUT: partial update; only provided fields change
POST: full replace; unspecified fields reset to zero/empty/false

Recommendations

Prefer PUT for targeted changes
For POST, include the complete desired object to avoid resetting fields unintentionally

Error cases¶

400 Bad Request
Invalid system.host_name
Attempt to enable system.power_save while Ethernet link is active
Invalid system.custom_ntp_server
Payload fails validation (types/ranges)

Device Settings¶

Document Context¶

Key Facts¶

Endpoint Details¶

Object schema¶

Fields: system¶

Power Management Decision Trees¶

Wi-Fi Power Save Logic¶

Ethernet Enable Logic¶

Fields: services¶

Examples¶

Read current settings¶

Enable Web UI protection¶

Configure SD card reports logging¶

Configure NTP for low-power reporting¶

Enable Modbus TCP¶

Configure Berry auto-run¶

Method semantics¶

Error cases¶

See also¶