Skip to content

Commit 086554b

Browse files
jasonacoxjasonacox
committed
Enhance API documentation with quick examples and control endpoint details
1 parent 6123b98 commit 086554b

1 file changed

Lines changed: 116 additions & 43 deletions

File tree

‎proxy/API.md‎

Lines changed: 116 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ This document describes the HTTP API endpoints provided by the PyPowerwall Proxy
44

55
---
66

7+
Jump To: [Quick Examples](#quick-examples) | [Control](#control-endpoints) | [Convenience /pw](#convenience-pw-endpoints) | [Fans](#fans-endpoints) | [Raw API](#powerwall-api-endpoints) | [Optional APIs](#optional-api-endpoints-tedapi-cloud-fleetapi) | [Cache](#cache-and-error-handling) | [Notes](#notes)
8+
79
## Overview
810

911
The proxy server exposes a RESTful API for accessing Powerwall data, including site, battery, solar, vitals, alerts, and more. It can be run locally or in a container, and supports both local gateway and cloud modes.
@@ -53,7 +55,37 @@ The proxy server exposes a RESTful API for accessing Powerwall data, including s
5355

5456
_Add `?headers` to include CSV headers._
5557

56-
### Control Endpoints
58+
**Aggregates Variants**
59+
- `/aggregates` Processed & cached combined metrics.
60+
- `/pw/aggregates` Same as above via convenience namespace.
61+
- `/api/meters/aggregates` Raw gateway API payload (unprocessed fields).
62+
63+
### Quick Examples
64+
65+
```bash
66+
# Get site aggregates
67+
curl http://localhost:8675/aggregates
68+
69+
# Get battery state of energy
70+
curl http://localhost:8675/soe
71+
72+
# Get device vitals
73+
curl http://localhost:8675/vitals
74+
75+
# Check connection health and cache status
76+
curl http://localhost:8675/health
77+
78+
# Get alerts
79+
curl http://localhost:8675/alerts
80+
81+
# Get power summary (shortcut)
82+
curl http://localhost:8675/pw/power
83+
84+
# CSV Examples
85+
curl "http://localhost:8675/csv/v2?headers"
86+
```
87+
88+
## Control Endpoints
5789

5890
| Endpoint | Description |
5991
|-------------------------|--------------------------------------------------|
@@ -62,9 +94,9 @@ _Add `?headers` to include CSV headers._
6294
| `/control/grid_charging`| Get/set grid charging enable (POST/GET) |
6395
| `/control/grid_export` | Get/set grid export policy (POST/GET) |
6496

65-
> **Note:** Control endpoints require `PW_CONTROL_SECRET` to be set.
97+
> **Note:** Control endpoints require `PW_CONTROL_SECRET` to be set. See [Control Examples](#control-examples) below.
6698
67-
#### CONTROL API Usage & Security
99+
### Control API Usage & Security
68100

69101
Control operations are DISABLED by default. To enable, set the environment variable `PW_CONTROL_SECRET` (any non-empty value). All control POST requests must include a `token` parameter matching this secret.
70102

@@ -81,8 +113,9 @@ Supported control values:
81113
- Grid Charging: `true` or `false`
82114
- Grid Export: `battery_ok`, `pv_only`, `never`
83115

84-
Example calls (replace `<secret>`):
85-
```
116+
### Control Examples
117+
118+
```bash
86119
# Get current reserve
87120
curl 'http://localhost:8675/control/reserve?token=<secret>'
88121

@@ -110,9 +143,14 @@ curl -X POST -d 'value=pv_only&token=<secret>' http://localhost:8675/control/gri
110143

111144
POST success responses return a JSON object with the updated field, or an error object on failure. GET requests return the current setting. Missing or invalid `token` returns an authorization error.
112145

146+
Mode clarification:
147+
- `self_consumption` / `autonomous`: Maximize local solar usage (firmware may use either term; treat as equivalent).
148+
- `backup`: Preserve charge for outage protection.
149+
- `time_of_use`: Optimize around configured TOU rates.
150+
113151
---
114152

115-
### Convenience /pw Endpoints
153+
## Convenience /pw Endpoints
116154

117155
The proxy provides shorthand endpoints under `/pw/` that map to common library calls. All return JSON.
118156

@@ -146,7 +184,7 @@ The proxy provides shorthand endpoints under `/pw/` that map to common library c
146184

147185
---
148186

149-
### Fans Endpoints
187+
## Fans Endpoints
150188

151189
Available when TEDAPI provides fan telemetry (e.g., Powerwall 3 systems):
152190

@@ -157,7 +195,9 @@ Available when TEDAPI provides fan telemetry (e.g., Powerwall 3 systems):
157195

158196
If fan data is unavailable, these return an empty JSON object `{}`.
159197

160-
### Powerwall API Endpoints
198+
Update interval: Fan metrics refresh with standard polling (same cadence as vitals/strings) and appear only when TEDAPI + compatible hardware (e.g., PW3) are present.
199+
200+
## Powerwall API Endpoints
161201

162202
| Endpoint | Description |
163203
|-----------------------------------|--------------------------------------------------|
@@ -185,7 +225,7 @@ If fan data is unavailable, these return an empty JSON object `{}`.
185225
| `/api/system/networks` | System network status |
186226
| `/api/meters/readings` | Meter readings data |
187227

188-
### Optional API Endpoints (TEDAPI, Cloud, FleetAPI)
228+
## Optional API Endpoints (TEDAPI, Cloud, FleetAPI)
189229

190230
_These endpoints require specific configuration to be enabled._
191231

@@ -212,42 +252,72 @@ The proxy server implements robust error handling and caching:
212252
- **TTL Behavior**: After cache TTL expires (default 30 seconds), endpoints return `null` instead of stale data
213253
- **Network Resilience**: Graceful handling of network errors with configurable retry and fallback behavior
214254
- **Health Monitoring**: Track connection health and cache status via `/health` endpoint
215-
216-
For configuration options, see [proxy/README.md](https://github.com/jasonacox/pypowerwall/blob/main/proxy/README.md).
217-
218-
---
219-
220-
## Example Usage
221-
222-
**Get site aggregates:**
223-
```sh
224-
curl http://localhost:8675/aggregates
255+
- **SOE Scaling Note**: `/soe` reports true 0–100% whereas `/api/system_status/soe` reports a 0–95% firmware-limited scale.
256+
257+
Environment Variables Influencing Behavior:
258+
- `PW_CACHE_TTL` Cache duration (seconds) for key endpoints (default 30).
259+
- `PW_GRACEFUL_DEGRADATION` If enabled, reduces hard failures under transient errors.
260+
- `PW_FAIL_FAST` Return quickly on errors instead of longer retries.
261+
- `PW_SUPPRESS_NETWORK_ERRORS` Suppress repetitive network error logs.
262+
- `PW_NETWORK_ERROR_RATE_LIMIT` Rate limit interval (seconds) for repeated network error messages.
263+
- `PW_CONTROL_SECRET` Enables control endpoints & required `token` value.
264+
265+
Authentication Overview:
266+
- Read-only endpoints generally need no client token; underlying gateway/cloud auth is handled internally.
267+
- Control endpoints always require `token=<PW_CONTROL_SECRET>`.
268+
269+
Error Responses (examples):
270+
| Scenario | HTTP | JSON |
271+
|----------|------|------|
272+
| Control disabled | 200 | `{ "error": "Control Commands Disabled - Set PW_CONTROL_SECRET to enable" }` |
273+
| Missing/invalid token | 403 | `{ "error": "Unauthorized" }` |
274+
| Invalid value | 400 | `{ "error": "Invalid Value" }` |
275+
| Upstream failure | 500 | `{ "error": "Request Failed" }` |
276+
277+
Sample JSON Snippets:
278+
```json
279+
// /aggregates - abbreviated
280+
{
281+
"site": {
282+
"instant_power": -2626,
283+
},
284+
"battery": {
285+
"instant_power": -2280.0000000000005,
286+
},
287+
"load": {
288+
"instant_power": 946.25,
289+
},
290+
"solar": {
291+
"instant_power": 5860,
292+
}
293+
}
294+
295+
// /health - abbreviated
296+
{
297+
"pypowerwall": "0.14.1 Proxy t81",
298+
"cache_ttl_seconds": 30,
299+
"graceful_degradation": true,
300+
"fail_fast_mode": false,
301+
"health_check_enabled": true,
302+
"startup_time": "2025-09-05T23:21:42",
303+
"current_time": "2025-09-14T11:58:57.239988",
304+
"proxy_stats": {},
305+
"connection_health": {},
306+
"cached_data": {},
307+
"endpoint_statistics": {}
308+
}
309+
310+
// POST /control/reserve success
311+
{"reserve": "Set Successfully"}
312+
313+
// POST /control/reserve invalid token
314+
{"error": "Unauthorized"}
315+
316+
// /fans/pw
317+
{"FAN1_actual": 1180, "FAN1_target": 1200, "FAN2_actual": 1175, "FAN2_target": 1200}
225318
```
226319

227-
**Get battery state of energy:**
228-
```sh
229-
curl http://localhost:8675/soe
230-
```
231-
232-
**Get device vitals:**
233-
```sh
234-
curl http://localhost:8675/vitals
235-
```
236-
237-
**Check connection health and cache status:**
238-
```sh
239-
curl http://localhost:8675/health
240-
```
241-
242-
**Get alerts:**
243-
```sh
244-
curl http://localhost:8675/alerts
245-
```
246-
247-
**Set battery reserve (requires control secret):**
248-
```sh
249-
curl -X POST -d "value=20&token=<secret>" http://localhost:8675/control/reserve
250-
```
320+
For configuration options, see [proxy/README.md](https://github.com/jasonacox/pypowerwall/blob/main/proxy/README.md).
251321

252322
---
253323

@@ -256,3 +326,6 @@ curl -X POST -d "value=20&token=<secret>" http://localhost:8675/control/reserve
256326
- Key metric endpoints (`/aggregates`, `/soe`, `/vitals`, `/strings`) return `null` when no fresh or valid cached data is available (after TTL expiry).
257327
- Some endpoints require local mode or specific configuration (see server documentation).
258328
- For more details, see the main project [README.md](https://github.com/jasonacox/pypowerwall/blob/main/README.md).
329+
330+
### API Changes
331+
Refer to `proxy/RELEASE.md` for history (e.g., t82 added `/control/grid_charging` & `/control/grid_export`).

0 commit comments

Comments
 (0)