Battery

Read a home battery’s charge level and mode, and tell it to charge, discharge, or run itself. Each recipe below covers one task end to end.

What a battery reports

GET /battery/{id} returns the battery’s state alongside the commands and settings it supports.

{
  "success": true,
  "data": {
    "state": {
      "status": "idle",
      "level": 67,
      "capacity": 10.4,
      "chargeRate": 0,
      "dischargeLimit": 10,
      "currentMode": "auto.balance"
    }
  }
}

Field
`status`	`charging`, `discharging`, `idle`, or `standby`.
`level`	State of charge, in percent.
`capacity`	Total capacity, in kWh.
`chargeRate`	Current rate in kW. Negative while discharging.
`dischargeLimit`	Discharge limit, in percent.
`currentMode`	The command the battery is running. Absent when the mode has no canonical name.

See Pull for freshness, caching, and the rest of the device read.

Commands

Command	What it does	Parameters	Execution
`charge`	Charge from grid or solar. Stops at `target`.	`target`, `power`, `reserve`	immediate, scheduled, windowed
`discharge`	Discharge to the home or grid. Stops at `target`.	`target`, `power`, `reserve`	immediate, scheduled, windowed
`idle`	Pause charging and discharging.	none	immediate, scheduled
`auto.balance`	Self-consumption: store surplus solar, cover the home’s load.	none	immediate, scheduled
`auto.reserve`	Hold charge in reserve for a grid outage.	none	immediate, scheduled
`auto.export`	Favour exporting to the grid.	none	immediate, scheduled

target and reserve are in percent, power is in kw. The table shows the most a battery can accept. Each device lists its own subset, bounds, and execution shapes in commands, and anything outside that list returns 422 DEVICE_NOT_CAPABLE. See Capabilities.

Recipes

Charge in a cheap-rate window

Charge between a start and end.

Start a charge later

Defer a charge to a future time.

Discharge during a peak

Discharge or export in a peak-rate window.

Return to self-consumption

Hand control back with auto.balance.

Change a setting

Update the discharge floor, charge ceiling, and more.

Get started

API Reference

Guides

Cookbooks

What a battery reports

Commands

Recipes

Charge in a cheap-rate window

Start a charge later

Discharge during a peak

Return to self-consumption

Change a setting

​What a battery reports

​Commands

​Recipes

Charge in a cheap-rate window

Start a charge later

Discharge during a peak

Return to self-consumption

Change a setting

What a battery reports

Commands

Recipes