Skip to main content

Batteries /api/batteries.

P1 Meter
Supported
Energy Socket
Not supported
Energy Display
Not supported
kWh Meter
Supported
Watermeter
Not supported
Plug-In Battery
Not supported
See Supported Devices for more information.

The /api/batteries endpoint can be used to retrieve information about the control system of the Plug-In Battery/batteries and allows you to change the control mode.

info

Despite its name, the /api/batteries endpoint is available on the P1 Meter and kWh Meter. These devices manage and control connected batteries. The endpoint is not available directly on the Plug-In Battery.

Parameters​

DataTypeAccessDescriptionAvailability
modeStringRead/WriteControl mode of the Plug-In Battery. Can be zero, to_full, standby, or predictive.
Mode predictive is available for API version 2.3.0 (in beta)
Available
API 2.1.0
Beta
API 2.3.0
permissionsArray[String]Read/Write*Permissions to allow charging, discharging, both, or neither. Note: Read-only in to_full mode.
Available
API 2.2.0
charge_to_fullBooleanRead/WriteWhether the Plug-In Battery should be charged to full. This will replace the to_full mode. When to_full mode is enabled, this field will be set to true and all the batteries will charge to 100%, when all batteries are fully charged, this field will be set to false and the mode will switch to the previous mode. You can turn off charge_to_full at any time.
Beta
API 2.3.0
battery_countNumberRead-onlyNumber of connected Plug-In Batteries.
Available
API 2.2.0
power_wNumberRead-onlyCurrent combined power consumption/production of the controlled Plug-In Batteries.
Available
API 2.1.0
target_power_wNumberRead-onlyTarget power consumption/production of the controlled Plug-In Batteries.
Available
API 2.1.0
max_consumption_wNumberRead-onlyMaximum allowed consumption power of the controlled Plug-In Batteries.
Available
API 2.1.0
max_production_wNumberRead-onlyMaximum allowed production power of the controlled Plug-In Batteries.
Available
API 2.1.0
API 2.3.0 is in closed beta

API 2.3.0 requires a firmware updates for certain devices, this firmware is currently being tested by a closed group of beta testers.

  • P1 Meter: 6.04xx or higher
  • kWh Meter: 5.02xx or higher

Mode​

The group of connected batteries can be controlled in five different modes:

  • zero - The Plug-In Battery will try to keep the power consumption/production of your home at zero. This means that the Plug-In Battery will charge or discharge to maintain a net-zero power balance. This is the default mode.
  • predictive - The Plug-In Battery will automatically select between charge_allowed, discharge_allowed, both or neither based on the current and predicted power consumption/production of your home and the current energy prices. This mode is only functional when the P1 Meter is connected to the HomeWizard cloud.
  • standby (legacy) - Batteries will enter standby mode. This means that the Plug-In Battery will neither charge nor discharge.
  • to_full (legacy) - All connected Plug-In Batteries will be charged to 100%, regardless of the power consumption/production of your home. When all batteries are fully charged, the Plug-In Battery will switch to the zero mode.
Note on legacy modes

The modes standby and to_full are provided for backwards compatibility reasons.

  • For standby, we recommend using the permissions field to disallow both charging and discharging instead of using this mode, as it provides more flexibility and will be the only option in the future when standby mode is removed.
  • For to_full, we recommend using the charge_to_full field instead of this mode. During the deprecation period, mode will be set to to_full when this field is set to true and will be set to the previous mode when this field is set to false to reflect the old behavior.

Permissions​

The permissions field can be used to set specific permissions for charging and discharging the connected Plug-In Batteries. The possible values are:

  • charge_allowed - Allow the Plug-In Battery to charge.
  • discharge_allowed - Allow the Plug-In Battery to discharge.

Provide these via an array when updating the permissions field. For example, to allow both charging and discharging, set permissions to ["charge_allowed", "discharge_allowed"]. To disallow both, set it to an empty array [].

Backwards compatibility with standby mode​

Mode standby is exactly the same as mode zero with both charging and discharging disallowed, therefore the following rules apply for backwards compatibility:

  • When switching to standby mode, the permissions field will be set to an empty array [].
  • When adding a permission to the permissions field while in standby mode, the mode will automatically switch to zero.
  • zero mode with both permissions allowed is the same as the default zero mode.
  • zero mode with both permissions disallowed is the same as standby mode, therefore mode will automatically switch to standby.

Examples​

Get Battery Group Information​

Request
curl https://<IP ADDRESS>/api/batteries \
  --insecure \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2"
Response
https/1.1 200 OK
Content-Type: application/json

{
    "mode": "zero",
    "permissions" : ["charge_allowed", "discharge_allowed"],
    "charge_to_full": false,
    "battery_count": 2,
    "power_w": -404,
    "target_power_w": -400,
    "max_consumption_w": 1600,
    "max_production_w": 800
}

Change Control Mode​

Request
curl https://<IP ADDRESS>/api/batteries \
  --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \
  -d '{"mode": "to_full"}'
Response
https/1.1 200 OK
Content-Type: application/json

{
    "mode": "to_full",
    "permissions" : [],
    "charge_to_full": true,
    "battery_count": 2,
    "power_w": 1599,
    "target_power_w": 1600,
    "max_consumption_w": 1600,
    "max_production_w": 800
}

Change permissions​

Request
curl https://<IP ADDRESS>/api/batteries \
  --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \
  -d '{"permissions": ["charge_allowed"]}'
Response
https/1.1 200 OK
Content-Type: application/json

{
    "mode": "zero",
    "permissions" : ["charge_allowed"],
    "charge_to_full": false,
    "battery_count": 2,
    "power_w": 404,
    "target_power_w": 400,
    "max_consumption_w": 1600,
    "max_production_w": 800
}

Set battery to charge to full​

Request
curl https://<IP ADDRESS>/api/batteries \
  --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \
  -d '{"mode": "to_full"}'

# or

curl https://<IP ADDRESS>/api/batteries \
  --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \
  -d '{"charge_to_full": true}'
Response
https/1.1 200 OK
Content-Type: application/json

{
    "mode": "to_full",
    "permissions" : ["charge_allowed", "discharge_allowed"],
    "charge_to_full": true,
    "battery_count": 2,
    "power_w": 1600,
    "target_power_w": 1600,
    "max_consumption_w": 1600,
    "max_production_w": 800
}

Change permissions and mode​

You can set mode and permissions in one request. You cannot set mode to to_full and change permissions at the same time, as permissions is read-only in to_full mode.

Mode will change to standby or zero depending on the provided permissions.

Request
curl https://<IP ADDRESS>/api/batteries \
  --insecure \
  -X PUT \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-Api-Version: 2" \
  -d '{"permissions": ["discharge_allowed"], "mode": "zero"}'
Response
https/1.1 200 OK
Content-Type: application/json

{
    "mode": "zero",
    "permissions": ["discharge_allowed"],
    "charge_to_full": false,
    "battery_count": 2,
    "power_w": -404,
    "target_power_w": -400,
    "max_consumption_w": 1600,
    "max_production_w": 800
}