Network POST

Set network configuration.

URL : /api/network/
Method : POST
Auth required : YES (v1.1+)

Example Body

{
	"ssid": "my ssid",
	"psk": "my psk",
	"isAP": false,
	"ipConfig": {
		"deviceIP": "192.168.1.195",
		"netmask": "255.255.255.0",
		"gateway": "192.168.1.1",
		"dns": "192.168.1.1"
	}
}

Usage

This endpoint only accepts POST requests using the application/json content header.
Failure to provide this header will result in a 404 response.

Not all parameters must be supplied when POSTing to the endpoint.
Only the parameters specified in your body will be changed.

Notes

• Both SSID and PSK must be supplied if you wish to change either of those.
  • Only supplying one of these parameters will result in an error.
• Changes POSTed to this endpoint will not result in an automatic reboot.
  The ESP32 only sets up its WiFi connection once at boot time.

Parameters

Below is a list of all parameters that can be presented in the request body:

ssid / psk

Saves the SSID and PSK of a network you wish to connect do.
This data will be used at boot time.

Payload

{
	"ssid": <string>,
	"psk": <string>
}

isAP

Specifies if the ESP32 should act as an Access Point or not.
This is only checked at boot.

Payload

{
	"isAP": <bool>
}

• true
  • The ESP32 wll start as an Access Point.
• false
  • The ESP32 will attempt to connect to a network using saved SSID and PSK data.

ipConfig

Changes the IPv4 configuration of the device.
Not all parameters must be specified.

Successful changes are only applied at boot time.

Payload

{
    "ipConfig": {
		"useDHCP": <bool>,
		"deviceIP": <string>,
		"netmask": <string>,
		"gateway": <string>,
		"dns": <string>
	}
}

• useDHCP (bool) [Optional]
  • true
    • Disregard static IP configuration.
  • false
    • Use (existing) static IP configuration.
  • Defaults to true if the ipConfig object is passed in the request.
• deviceIP (string)
  • Local IP of the device.
• netmask (string)
  • Network mask of the device.
    • Do not use a CIDR notation.
• gateway (string)
  • IP-Address of the gateway.
• dns (string)
  • IP-Address of the primary DNS server.

Notes

Changes are persistent and stored in a JSON file on the device.

Instructing the device to use DHCP will not clear existing static IP configuration;
Instead, the ESP will just ignore it.

Authentication

This endpoint requires authentication in order to be used.
To authenticate, supply the following header:
"Authorization": "<code>"

The authentication code can be obtained using /api/auth.

Only applicable to version 1.1+.

Error handling

The whole request body gets validated once received by the system.
If a parameter or value violates the authentication set as dictated by the system, the whole request gets discarded and will instead return a 400 response.

Bad authentication attempts will result in a 403 response.