Skip to main content

WebSocket /api/ws

P1 Meter
Supported
Energy Socket
In development
Energy Display
In development
kWh Meter
In development
Watermeter
In development
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 HomeWizard Energy WebSocket API allows you to receive real-time updates from the device. The WebSocket lets you subscribe to specific topics and receive updates when data changes.

Structure​

All data packages, in both directions, are formatted in JSON and contain a type field and an optional data field. The data type can be any valid JSON format.

Example: Authorization request from device
{ "type": "authentication_requested", "data": { "api_version": "2.0.0" } }
Example: Subscribe to device information
{ "type": "subscribe", "data": "device" }

When no data needs to be sent, the data field can be omitted.

Example: Ask device to blink
{ "type": "identify" }

Commands​

Connect and Authorize​

To connect to the WebSocket, you must obtain an authorization token. Refer to this page for instructions.

The WebSocket is accessible at wss://<IP ADDRESS>/api/ws. The connection is secured with the same certificate as the HTTPS connection. Once connected, you must send the authorization token within 40 seconds, or the connection will close.

Example
// Connect to the server
→ {"type": "authorization_requested", "data": {"api_version": "2.0.0"}}

// Send a token within 40 seconds
{"type": "authorization", "data": "<TOKEN>"}
→ {"type": "authorized"}

Subscribe​

After authentication, you can subscribe to topics. Topics correspond to available endpoints, with the data matching that returned by the endpoint. Once subscribed, the device sends the latest values and updates when data changes. The type field consist of the topic name, and the data field contains the data from the endpoint.

  • * - Subscribe to all topics
  • device - Subscribe to device information updates
  • user - Subscribe to user list updates
  • measurement - Subscribe to measurement updates
  • system - Subscribe to system updates. Only cloud_enabled and status_led_brightness_pct are updated in real time.
Example
{"type": "subscribe", "data": "system"}
→ {"type":"system", "data": {"wifi_ssid": "My WiFi", "wifi_rssi_db": -70, "cloud_enabled": true, "uptime_s": 42, "status_led_brightness_pct": 100}}
→ {"type":"system", "data": {"wifi_ssid": "My WiFi", "wifi_rssi_db": -70, "cloud_enabled": true, "uptime_s": 42, "status_led_brightness_pct": 70}}

Unsubscribe​

To unsubscribe from a topic, send an unsubscribe message. The data field should contain the topic name, as described in the subscribe section.

Example
{ "type": "unsubscribe", "data": "system" }

Polling Data​

If you only need data once (for example, just a single system update), you can send a request to the WebSocket for the latest data. The device will respond with the latest values.

Example
{"type": "system"}
→ {"type":"system", "data": {"wifi_ssid": "My WiFi", "wifi_rssi_db": -70, "cloud_enabled": true, "uptime_s": 42, "status_led_brightness_pct": 70}}

Setting Data​

Writable parameters, such as system/cloud_enabled, are also controllable via the WebSocket. The device will respond with the new value.

Example
{ "type": "system", "data": { "cloud_enabled": false } }
→ {"type":"system", "data": {"wifi_ssid": "My WiFi", "wifi_rssi_db": -70, "cloud_enabled": false, "uptime_s": 42, "status_led_brightness_pct": 70}}

Identify​

To blink the device LED, send an identify command. The LED will blink for a few seconds.

Example
{ "type": "identify" }

Error Handling​

When an error occurs, the device sends an error message. The message contains an error field with a description of the error, matching the error structure of the v2 API errors.

Example
{"type": "system", "data": {"status_led_brightness_pct": 200}}
→ {"type":"error","data":{"message":"json:parameter-invalid-type:status_led_brightness_pct"}}