|
| 1 | +--- |
| 2 | +title: Batteries |
| 3 | +sidebar_position: 8 |
| 4 | +description: Enable and disable cloud communication. |
| 5 | +--- |
| 6 | + |
| 7 | +import Badge from '@site/src/components/Badge.js' |
| 8 | + |
| 9 | +# Batteries `/api/batteries` |
| 10 | + |
| 11 | +{/* prettier-ignore */} |
| 12 | +<Badge color='hw-purple' icon='mdi:wrench' subtext='Requires firmware 6.0200 or later (in beta)'>P1 Meter</Badge> |
| 13 | +<Badge color='hw-grey' icon='mdi:close' subtext='Not supported'>Energy Socket</Badge> |
| 14 | +<Badge color='hw-grey' icon='mdi:close' subtext='Not supported'>Energy Display</Badge> |
| 15 | +<Badge color='hw-purple' icon='mdi:wrench' subtext='In development'>kWh Meter</Badge> |
| 16 | +<Badge color='hw-grey' icon='mdi:close' subtext='Not supported'>Water Meter</Badge> |
| 17 | +<Badge color='hw-grey' icon='mdi:close' subtext='Not supported'>Plug-In Battery</Badge> |
| 18 | +<br /> |
| 19 | +<sub>_See [Supported Devices](/docs/introduction#devices) for more information._</sub> |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +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. |
| 24 | + |
| 25 | +## Parameters |
| 26 | + |
| 27 | +| Data | Type | Access | Description | |
| 28 | +| ----------------- | ------ | ---------- | ----------------------------------------------------------------------------------- | |
| 29 | +| [mode](#mode) | String | Read/Write | Control mode of the Plug-In Battery. Can be either `zero`, `to_full`, or `standby`. | |
| 30 | +| power_w | Number | Read-only | Current combined power consumption/production of the controlled Plug-In Batteries. | |
| 31 | +| target_power_w | Number | Read-only | Target power consumption/production of the controlled Plug-In Batteries. | |
| 32 | +| max_consumption_w | Number | Read-only | Maximum allowed consumption power of the controlled Plug-In Batteries. | |
| 33 | +| max_production_w | Number | Read-only | Maximum allowed production power of the controlled Plug-In Batteries. | |
| 34 | + |
| 35 | +## Mode |
| 36 | + |
| 37 | +The group of connected batteries can be controlled in three different modes: |
| 38 | + |
| 39 | +- `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. |
| 40 | +- `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. |
| 41 | +- `standby` - Batteries will enter standby mode. This means that the Plug-In Battery will neither charge nor discharge. |
| 42 | + |
| 43 | +### Examples |
| 44 | + |
| 45 | +#### Get Battery Group Information |
| 46 | + |
| 47 | +```shell title="Request" |
| 48 | +curl https://<IP ADDRESS>/api/batteries \ |
| 49 | + --insecure \ |
| 50 | + -H "Authorization: Bearer <TOKEN>" \ |
| 51 | + -H "X-Api-Version: 2" |
| 52 | +``` |
| 53 | + |
| 54 | +```http title="Response" |
| 55 | +https/1.1 200 OK |
| 56 | +Content-Type: application/json |
| 57 | +
|
| 58 | +{ |
| 59 | + "mode": "zero", |
| 60 | + "power_w": -404, |
| 61 | + "target_power_w": -400, |
| 62 | + "max_consumption_w": 1600, |
| 63 | + "max_production_w": 800 |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +#### Change Control Mode |
| 68 | + |
| 69 | +```shell title="Request" |
| 70 | +curl https://<IP ADDRESS>/api/batteries \ |
| 71 | + --insecure \ |
| 72 | + -X PUT \ |
| 73 | + -H "Authorization: Bearer <TOKEN>" \ |
| 74 | + -H "X-Api-Version: 2" \ |
| 75 | + -d '{"mode": "to_full"}' |
| 76 | +``` |
| 77 | + |
| 78 | +```http title="Response" |
| 79 | +https/1.1 200 OK |
| 80 | +Content-Type: application/json |
| 81 | +
|
| 82 | +{ |
| 83 | + "mode": "to_full", |
| 84 | + "power_w": 1599, |
| 85 | + "target_power_w": 1600, |
| 86 | + "max_consumption_w": 1600, |
| 87 | + "max_production_w": 800 |
| 88 | +} |
| 89 | +``` |
0 commit comments