System /api/system

P1 Meter

Supported

Energy Socket

Supported in v1

Energy Display

In development

kWh Meter

Supported in v1

Watermeter

Supported in v1

Plug-In Battery

In development

_{See Supported Devices for more information.}

---

warning

The HomeWizard Energy API v2 and its documentation are in beta and subject to change.

The /api/system endpoint can be used to get and set some system information, like the state of the cloud communication and the uptime of the device.

Parameters

Data	Type	Access	Description
wifi_ssid	String	Read-only	The SSID of the Wi-Fi network.
wifi_rssi_db	Number	Read-only	The signal strength of the Wi-Fi network.
uptime_s	Number	Read-only	The uptime of the device in seconds.
cloud_enabled	Boolean	Read/Write	The state of the cloud communication.
status_led_brightness_pct	Number	Read/Write	The brightness of the status LED in percent.
api_v1_enabled	Optional Boolean	Read/Write	The state of the v1 API, will be removed when API v1 is removed, so this parameter is optional.

Actions

Action	Description
Reboot	Reboot the device
Identify	Let the device identify itself by blinking the status LED

Cloud Communication

HomeWizard Energy devices are designed to work with the HomeWizard Energy app and rely on communication with the HomeWizard cloud for full functionality.

Users can choose to disable cloud communication, making the device operate entirely locally. However, this will prevent the app from interacting with the device, and the device will no longer receive firmware updates.

Cloud communication can be re-enabled by setting cloud_enabled to true. It is also automatically restored after a factory reset or when the device is put into pairing mode.

tip

If you're implementing this feature, ensure that users clearly understand its implications. Users might disable cloud communication without fully realizing its effect or forget they did so, leading them to believe the app or device is malfunctioning. This can result in unnecessary support requests, which we want to avoid.

To prevent confusion, consider providing clear documentation or displaying a confirmation message before enabling or disabling this setting.

Examples

Disable Cloud Communication

Request

curl https://<IP ADDRESS>/api/system --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \
  -d '{"cloud_enabled": false}'

Response

https/1.1 200 OK
Content-Type: application/json

{
    "wifi_ssid": "My Wi-Fi",
    "wifi_rssi_db": -77,
    "cloud_enabled": false,
    "uptime_s": 356,
    "status_led_brightness_pct": 100,
    "api_v1_enabled": true
}

After disabling the cloud communication, the device will only work locally.

Enable Cloud Communication

Request

curl https://<IP ADDRESS>/api/system --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \
  -d '{"cloud_enabled": true}'

Response

https/1.1 200 OK
Content-Type: application/json

{
    "wifi_ssid": "My Wi-Fi",
    "wifi_rssi_db": -77,
    "cloud_enabled": true,
    "uptime_s": 356,
    "status_led_brightness_pct": 100,
    "api_v1_enabled": true
}

Device will now reconnect to the cloud.

Status LED Brightness

Most devices have a status LED, and its brightness can be adjusted between 0% and 100%. This adjustment only affects the LED during normal operation. Error indications are always displayed at the default brightness, regardless of the setting.

Examples

Set Status LED Brightness

Request

curl https://<IP ADDRESS>/api/system --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \
  -d '{"status_led_brightness_pct": 50}'

Response

https/1.1 200 OK
Content-Type: application/json

{
    "wifi_ssid": "My Wi-Fi",
    "wifi_rssi_db": -77,
    "cloud_enabled": true,
    "uptime_s": 356,
    "status_led_brightness_pct": 50,
    "api_v1_enabled": true
}

Enable or Disable the v1 API

To protect the device from unauthorized access, the v1 API can be disabled. When the v1 API is disabled, the device will only allow authorized request via the v2 API.

Example

Disable the v1 API

Request

curl https://<IP ADDRESS>/api/system --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \
  -d '{"v1_api_enabled": false}'

Response

https/1.1 200 OK
Content-Type: application/json

{
    "wifi_ssid": "My Wi-Fi",
    "wifi_rssi_db": -77,
    "cloud_enabled": true,
    "uptime_s": 356,
    "status_led_brightness_pct": 100,
    "api_v1_enabled": false
}

The v1 API is now disabled, as if it was disabled via the HomeWizard Energy app. The v1 API will respond with an API disabled error when trying to use it.

Identify

The /api/system/identify endpoint can be used to let the user identify the device. The status light will blink for a few seconds after calling this endpoint.

Example

Request

curl https://<IP ADDRESS>/api/system/identify --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \

Response

https/1.1 204 No Content
Content-Length: 0

Reboot

If needed, you can reboot the device by calling the /api/system/reboot endpoint. After rebooting, the device will reconnect to Wi-Fi and be ready for use again.

tip

A reboot is usually not necessary but can help in certain situations. Make sure to inform the user that ff the issue persists and frequent reboots are required, they need to contact our support team to help identify and resolve the root cause.

Example

Request

curl https://<IP ADDRESS>/api/system/reboot --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2"

Response

https/1.1 204 No Content
Content-Length: 0