Ethernet Configuration¶

Document Context¶

Purpose: Ethernet network configuration API for managing wired connectivity including DHCP and static IP settings
When to use: Setting up wired network connectivity, configuring static IP addresses, troubleshooting network issues, deployment planning
Prerequisites: Basic networking knowledge (IP addresses, subnet masks, gateways), understanding of DHCP vs static IP concepts
Related to: Wi-Fi setup, Network discovery, device settings configuration
Validates against: IPv4 network configuration standards, DHCP client behavior, static IP validation requirements

Key Facts¶

Endpoint: /api/v1/eth/settings - Ethernet network configuration management
Methods: GET (read), POST (overwrite), PUT (update) - Full configuration control
Network modes: DHCP automatic assignment or static IP with manual configuration
Required fields: IP, netmask, gateway, DNS when using static IP configuration
Default state: Ethernet enabled with DHCP (static_ip: false)

Authentication

When a Web UI password is set, HTTP endpoints require HTTP authentication.

Firmware 1.10.X and later: Uses HTTP Digest authentication - Server challenges with WWW-Authenticate: Digest … (realm is the device hostname) - Algorithm: MD5-sess (device advertises MD5-sess; integrity variant supported) - qop: auth (and optionally auth-int for requests with body integrity) - Nonce and opaque are issued by the device; the client must include cnonce and increment nc - Expired nonce: server may return 401 with WWW-Authenticate: …, stale=true. In that case, retry the same request once using the new server challenge, a new cnonce, and reset nc=00000001.

Firmware before 1.10.X: Uses HTTP Basic authentication - Server challenges with WWW-Authenticate: Basic realm="..." - Credentials are base64-encoded in Authorization: Basic <encoded-credentials>

Recommended approach: Use --anyauth in curl to automatically detect and use the appropriate method:

curl --anyauth -u ":<password>" http://whatwatt-ABCDEF.local/api/v1/system

Alternative Method

Ethernet settings can also be configured from the device's WebUI.

Endpoint Details¶

This endpoint allows you to configure the Ethernet connection settings including static IP configuration and DHCP options.

Parameter	Value
Endpoint	`/api/v1/eth/settings`
Methods	`GET`, `POST`, `PUT`
Response Content Type	`application/json`

Configuration Fields¶

Field	Type	Default	Description
`enable`	boolean	`true`	Enable/disable Ethernet port
`static_ip`	boolean	`false`	Use static IP instead of DHCP client
`ip`	string	`"0.0.0.0"`	Static IP address (IPv4 format)
`netmask`	string	`"0.0.0.0"`	Subnet mask (IPv4 format)
`gateway`	string	`"0.0.0.0"`	Gateway address (IPv4 format)
`dns`	string	`"0.0.0.0"`	DNS server address (IPv4 format)

Network Configuration Types¶

DHCP Configuration (Automatic)¶

Most home and office networks use DHCP for automatic IP assignment:

{
  "enable": true,
  "static_ip": false,
  "ip": "0.0.0.0",
  "netmask": "0.0.0.0",
  "gateway": "0.0.0.0",
  "dns": "0.0.0.0"
}

Static IP Configuration¶

For networks requiring fixed IP addresses:

{
  "enable": true,
  "static_ip": true,
  "ip": "192.168.1.201",
  "netmask": "255.255.255.0",
  "gateway": "192.168.1.1",
  "dns": "8.8.8.8"
}

Examples¶

Get Current Configuration¶

No authWith password

curl -s http://192.168.1.100/api/v1/eth/settings

curl -s --anyauth -u ":PASSWORD" http://192.168.1.100/api/v1/eth/settings

Response:

{
  "enable": true,
  "static_ip": false,
  "ip": "0.0.0.0",
  "netmask": "0.0.0.0",
  "gateway": "0.0.0.0",
  "dns": "0.0.0.0"
}

Enable Ethernet with DHCP¶

curl -X PUT -H "Content-Type: application/json" \
     -d '{
       "enable": true,
       "static_ip": false
     }' \
     http://192.168.1.100/api/v1/eth/settings

Configure Static IP¶

curl -X PUT -H "Content-Type: application/json" \
     -d '{
       "enable": true,
       "static_ip": true,
       "ip": "192.168.1.201",
       "netmask": "255.255.255.0",
       "gateway": "192.168.1.1",
       "dns": "8.8.8.8"
     }' \
     http://192.168.1.100/api/v1/eth/settings

Disable Ethernet¶

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.

curl -X PUT -H "Content-Type: application/json" \
     -d '{"enable": false}' \
     http://192.168.1.100/api/v1/eth/settings

Static IP Guidelines¶

Address Assignment¶

Address Conflicts

When setting static addressing, address collision can occur. Ensure no other device uses the same IP address.

Safe Static IP Ranges:

Below DHCP range: 192.168.1.2 - 192.168.1.99 (if DHCP uses 100-200)
Above DHCP range: 192.168.1.201 - 192.168.1.254 (if DHCP uses 100-200)
Check router settings: Verify DHCP range in router configuration

Common Network Configurations¶

Home Network (192.168.1.x)¶

{
  "enable": true,
  "static_ip": true,
  "ip": "192.168.1.201",
  "netmask": "255.255.255.0",
  "gateway": "192.168.1.1",
  "dns": "8.8.8.8"
}

Office Network (192.168.0.x)¶

{
  "enable": true,
  "static_ip": true,
  "ip": "192.168.0.150",
  "netmask": "255.255.255.0",
  "gateway": "192.168.0.1",
  "dns": "192.168.0.1"
}

Corporate Network (10.0.x.x)¶

{
  "enable": true,
  "static_ip": true,
  "ip": "10.0.1.100",
  "netmask": "255.255.0.0",
  "gateway": "10.0.1.1",
  "dns": "10.0.1.1"
}

Field Requirements¶

Static IP Requirements¶

When static_ip: true, the following fields must be set to non-zero values:

Field	Requirement	Example
`ip`	Device IP address	`"192.168.1.201"`
`netmask`	Subnet mask	`"255.255.255.0"`
`gateway`	Router/gateway IP	`"192.168.1.1"`
`dns`	DNS server IP	`"8.8.8.8"` or `"192.168.1.1"`

DNS Configuration Options¶

DNS Setting	Use Case	Example
`"8.8.8.8"`	Google DNS (external)	Reliable public DNS
`"1.1.1.1"`	Cloudflare DNS (external)	Fast public DNS
`"192.168.1.1"`	Router DNS (local)	Use router for DNS resolution
Custom DNS	Corporate networks	Internal DNS servers

Troubleshooting¶

Connection Issues¶

# Test connectivity after configuration change

ping -c 3 192.168.1.201

# Check if IP is reachable
curl -s http://192.168.1.201/api/v1/system

# Verify no IP conflicts
nmap -sP 192.168.1.201

Configuration Validation¶

# Verify settings were applied
curl -s http://192.168.1.100/api/v1/eth/settings | jq '.'

# Check system network status
curl -s http://192.168.1.100/api/v1/system | jq '.ethernet'

Common Problems¶

Issue	Cause	Solution
Cannot access device	IP conflict	Check for duplicate IPs on network
No internet access	Wrong gateway/DNS	Verify gateway and DNS settings
Configuration rejected	Invalid IP format	Use proper IPv4 format (x.x.x.x)
Settings not persistent	Configuration not saved	Use PUT/POST method, not GET

Best Practices¶

Network Planning

Document IP assignments to avoid conflicts
Use consistent IP ranges for static devices
Test configuration before applying to production

Backup Access

Keep Wi-Fi enabled as backup connection method
Note current IP before making changes
Have physical access available if needed

Performance

Ethernet typically provides more stable connection than Wi-Fi
Consider cable quality and length for reliable connections
Use static IP for servers and automation systems