DOCSEARCHbyAlgolia
Submit Docs

HomeWizard API

website·Indexed 35 days ago

https://api-documentation.homewizard.com

Local network API for HomeWizard energy devices, including the P1 Meter (HWE-P1), Energy Sockets (HWE-SKT), 1-Phase and 3-Phase kWh Meters (HWE-KWH1, HWE-KWH3, SDM230-wifi, SDM630-wifi), and Plug-In Batteries (HWE-BAT). Documentation covers v1 and v2 versions, featuring measurement data, system actions, WebSocket communication, device discovery via mDNS, and authorization.

Tokens
13.6K
Snippets
62
Records
94
Agent score
61%

What's inside HomeWizard

  1. Overview of HomeWizard Local API

    HomeWizard devices (P1 Meter, Energy Socket, kWh Meter, Watermeter, and Plug-In Battery) provide a local API to retrieve real-time measurements or control the device. To use the local API, the client must be connected to the same Wi-Fi network as the device. Note that historical data cannot be retrieved via the local API as it is not stored on the device.

  2. Authorize API requests with a Bearer token

    v2
    The HomeWizard API requires a Bearer token for authorization. This token must be included in the Authorization header of every request. If the token is missing or invalid, the API returns a 401 Unauthorized response with the error user:unauthorized.
    curl https://<IP ADDRESS>/api --insecure \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2"

  3. Understand HomeWizard API versioning and backward compatibility

    The HomeWizard API follows semantic versioning (MAJOR.MINOR.PATCH).

    • MAJOR updates indicate incompatible API changes.
    • MINOR updates add backward-compatible features.
    • PATCH updates provide backward-compatible bug fixes.

    To maintain backward compatibility, when a breaking change occurs, the MAJOR version increases, but the previous version remains accessible for a period of time.

  4. Access the HomeWizard API locally

    The HomeWizard API is available on your local network, allowing it to be used without an active internet connection. Users have the option to disable the cloud connection entirely via the system settings.

  6. Toggle HomeWizard cloud communication

    v1

    Use the /api/v1/system endpoint to enable or disable all communication between the HomeWizard device and the HomeWizard cloud.

    Important Considerations:

    • When cloud_enabled is set to false, the device becomes fully local. It will no longer communicate with the HomeWizard app and will not receive firmware updates.
    • Cloud communication is restored by setting cloud_enabled to true, performing a factory reset, or putting the device into pairing mode.
    • Because this action disables app functionality and updates, it is recommended to provide clear documentation or a confirmation popup to the end-user before triggering this change.

    Supported Devices:

    • P1 Meter
    • Energy Socket
    • kWh Meter
    • Watermeter
    • Plug-In Battery (v2)
    • Note: Energy Display is not supported.

  8. Handle HomeWizard API errors

    v1
    When making requests to the HomeWizard API, always verify that the HTTP status code is 200 OK before parsing the response. If a request is invalid or an error occurs, the API returns a non-200 status code and a JSON object containing an error object with a numeric id and a string description.

  9. Create a local user and obtain an authorization token

    v2

    To obtain an authorization token, you must create a user on the device via a POST /api/user request. This process requires physical interaction with the device to prove possession.

    Pairing Flow:

    1. Send a POST /api/user request with the desired user name.
    2. The device will initially respond with 403 Forbidden (user:creation-not-enabled).
    3. The user must physically press the button on the device.
      • Note for kWh Meter: The wifi-pair button must be pressed for 1 to 3 seconds.
    4. While waiting for the button press, the app can continue sending the POST request to reset the timer.
    5. Once the button is pressed, the next request within a 30-second window will return a 200 OK response containing the token.

    Request Parameters:

    • name (String): Must be prefixed with local/. Length: 1-40 characters. Allowed characters: a-z, A-Z, 0-9, -, _, \, /, #, and spaces. (Regex: ^local\[a-zA-Z0-9\-\_/\\# \]{1,40}$).

    Response Fields:

    • name (String): The user name prefixed with local/.
    • token (String): A 32-character alphanumeric token (A-F, 0-9).
    # Step 1 & 2: Request token (repeat until button is pressed)
curl https://<IP ADDRESS>/api/user --insecure \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Version: 2" \
  -d '{"name": "local/new_user"}'

  10. Generate an authorization token for HomeWizard API v2

    The v2 API requires a secret token for access. To generate one:

    1. Identify the device's IP address.
    2. Send a POST request to the /api/user endpoint. The first attempt will return {"error":"user:creation-not-enabled"}.
    3. Physically press the button on the HomeWizard device once to authorize the request.
    4. Send the same POST request again to receive the token.
    curl https://<IP ADDRESS>/api/user --insecure -X POST -d '{"name": "local/cool-new-app"}'

  11. Adjust status LED brightness

    v2
    The status LED brightness can be adjusted between 0% and 100% using the status_led_brightness_pct parameter. This setting only affects the LED during normal operation; error indications always use default brightness.
    curl https://<IP ADDRESS>/api/system --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \
  -d '{"status_led_brightness_pct": 50}'

  12. Discover HomeWizard devices using mDNS

    HomeWizard energy devices can be automatically discovered on a local network using Multicast DNS (mDNS), also known as Zeroconf or Bonjour. This allows applications to find devices without knowing their IP addresses. Depending on the API version supported by the device, it will broadcast one or both of the following services:

    • _hwenergy._tcp: Used for devices supporting API v1 (HTTP, port 80).
    • _homewizard._tcp: Used for devices supporting API v2 and later (HTTPS, port 443).