System /api/system

P1 Meter

Requires Firmware 6.00, Currently in Beta

Energy Socket

Supported in v1

Energy Display

In development

kWh Meter

Supported in v1

Watermeter

Supported in v1

Plug-In Battery

Supported

_{See Supported Devices for more information.}

---

warning

The HomeWizard Energy API v2 and its documentation are in beta and subject to change. Complete this form to join the beta test group.

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	Availability
wifi_ssid	String	Read-only	The SSID of the Wi-Fi network.	Wi-Fi P1 Meter Plug-In Battery
wifi_rssi_db	Number	Read-only	The signal strength of the Wi-Fi network.	Wi-Fi P1 Meter Plug-In Battery
uptime_s	Number	Read-only	The uptime of the device in seconds.	Wi-Fi P1 Meter Plug-In Battery
cloud_enabled	Boolean	Read/Write	The state of the cloud communication.	Wi-Fi P1 Meter Plug-In Battery read-only
status_led_brightness_pct	Number	Read/Write	The brightness of the status LED in percent.	Wi-Fi P1 Meter Plug-In Battery
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.	Wi-Fi P1 Meter Plug-In Battery

Actions

Action	Description	Availability
Reboot	Reboot the device	Wi-Fi P1 Meter Plug-In Battery
Identify	Let the device identify itself by blinking the status LED	Wi-Fi P1 Meter Plug-In Battery

Plug-In Battery exceptions

The Plug-In Battery has some exceptions compared to the P1 Meter:

• The api_v1_enabled parameter is not available for the Plug-In Battery. The battery only supports the v2 API.
• For safety reasons, the reboot action is not available for the Plug-In Battery.
• The cloud_enabled parameter is read-only and always set to true. The Plug-In Battery requires a cloud connection for initial setup, error reporting, and firmware updates. HomeWizard is working on options to enable fully local use of the Plug-In Battery.

Good to know

The battery is fully controlled locally by the P1 Meter, ensuring fast operation and continued functionality even if the internet connection is lost.

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 '{"api_v1_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 if 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