Skip to main content

Batteries /api/batteries.

P1 Meter
Supported
Energy Socket
Not supported
Energy Display
Not supported
kWh Meter
Supported
Water Meter
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.

Parameters​

DataAvailabilityTypeAccessDescription
mode
Available
2.1.0		StringRead/WriteControl mode of the Plug-In Battery. Can be either zero, to_full, or standby.
permissions
In beta
2.2.0		Array[String]Read/Write*Permissions to allow charging, discharging, both, or neither. Note: Read-only in to_full mode.
battery_count
In beta
2.2.0		NumberRead-onlyNumber of connected Plug-In Batteries.
power_w
Available
2.1.0		NumberRead-onlyCurrent combined power consumption/production of the controlled Plug-In Batteries.
target_power_w
Available
2.1.0		NumberRead-onlyTarget power consumption/production of the controlled Plug-In Batteries.
max_consumption_w
Available
2.1.0		NumberRead-onlyMaximum allowed consumption power of the controlled Plug-In Batteries.
max_production_w
Available
2.1.0		NumberRead-onlyMaximum allowed production power of the controlled Plug-In Batteries.

Mode​

The group of connected batteries can be controlled in three 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.
  • to_full - 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.
  • standby - Batteries will enter standby mode. This means that the Plug-In Battery will neither charge nor discharge. For new implementations we recommend to use the permissions field to disallow both charging and discharging instead of using this mode.

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.

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"],
    "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" : [],
    "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 \
  -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"],
    "battery_count": 2,
    "power_w": 404,
    "target_power_w": 400,
    "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 \
  -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"],
    "battery_count": 2,
    "power_w": -404,
    "target_power_w": -400,
    "max_consumption_w": 1600,
    "max_production_w": 800
}