Code by Scott שאול בן ישוע
README.md 10.5 KB
Newer Older
Vince Loschiavo's avatar
Vince Loschiavo committed
1
Tesla Powerwall 2 - Local Gateway API documentation
Vince Loschiavo's avatar
Vince Loschiavo committed
2
3
4
======
_(Based on firmware version 1.15.0)_

Vince Loschiavo's avatar
Vince Loschiavo committed
5
This is a list of api URLs and some random thoughts I've been able to pull together from the interwebz and other functions we've been able to reverse engineer from the local gateway.  (This is not the [ Tesla Owner API](https://timdorr.docs.apiary.io/#)).
Vince Loschiavo's avatar
Vince Loschiavo committed
6

Vince Loschiavo's avatar
Vince Loschiavo committed
7
Powerwall 2 Web UI
Vince Loschiavo's avatar
Vince Loschiavo committed
8
---
Vince Loschiavo's avatar
Vince Loschiavo committed
9
The web UI provides ~~an instantaneous~~ 250-500ms average(?) power flow diagram an access to the wizard.
Vince Loschiavo's avatar
Vince Loschiavo committed
10
11
12
13
14
15
16
Hit your local gateway IP with a browser, i.e. _http://192.168.xxx.xxx/

You should see something like this:

![GatewayUI](https://github.com/vloschiavo/powerwall2/raw/master/img/TeslaPowerwallGatewayUI.png "Gateway Web UI")

---
Vince Loschiavo's avatar
Vince Loschiavo committed
17
**Wizard**
Vince Loschiavo's avatar
Vince Loschiavo committed
18
You can hit the _"Run Wizard"_ button here and go through the setup (be careful what you change in the wizard).
Vince Loschiavo's avatar
Vince Loschiavo committed
19
20

`username: <leave this blank as it's ignored (and/or logged)>`
Vince Loschiavo's avatar
Vince Loschiavo committed
21

Vince Loschiavo's avatar
Vince Loschiavo committed
22
23
`password: S + <gateway serial number>`

Vince Loschiavo's avatar
Vince Loschiavo committed
24
25
26
27
You can find the serial number of the gateway ( the linux server that switches power) on the inside of the metal access door to the gateway. Don't unscrew anything as the box is switching high voltage & current behind the screwed pannels. See image:

![Gateway Location](https://github.com/vloschiavo/powerwall2/raw/master/img/equipment.jpg "Gateway location")

Vince Loschiavo's avatar
Vince Loschiavo committed
28
[ Original image taken from www.tesla.com here](https://www.tesla.com/support/energy/install/powerwall/powerwall-installations)
Vince Loschiavo's avatar
Vince Loschiavo committed
29

Vince Loschiavo's avatar
Vince Loschiavo committed
30
31
32
33
34
35
___
### Information

**Meters / Power output stats**
Calling the below URLs does not require authentication.  Each will return JSON output with key-value pairs.

Vince Loschiavo's avatar
Vince Loschiavo committed
36
_GET /api/meters/aggregates_
Vince Loschiavo's avatar
Vince Loschiavo committed
37

Vince Loschiavo's avatar
Vince Loschiavo committed
38
request: `curl http://192.168.xxx.xxx/api/meters/aggregates`
Vince Loschiavo's avatar
Vince Loschiavo committed
39

Vince Loschiavo's avatar
Vince Loschiavo committed
40
41
42
43
response: [see sample response here](https://raw.githubusercontent.com/vloschiavo/powerwall2/master/samples/api_meters_aggregates.json
)

This returns the current readings from the meters that measure solar, grid, battery, and home production and usage.  Watts, Hz, etc.  Watt values can be positive or negative.  
Vince Loschiavo's avatar
Vince Loschiavo committed
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
1. "site" corresponds to "Grid" in the Tesla mobile app
	-Positive numbers indicate power draw from the grid to the system
	-Negative numbers indicate sending power from the system to the grid
2. "battery" corresponds to "Powerwall" in the Tesla mobile app - this is an aggregate number if you have more than one Powerwall
	-Positive numbers indicate power draw from the batteries to the system
	-Negative numbers indicate sending power from the system to the batteries
3. "load" corresponds to "Home" in the Tesla mobile app
	-Positive numbers indicate power draw from the system to the home
	-Negative numbers should never happen
4. "solar" corresponds to "Solar" in the Tesla mobile app
	-Positive numbers indicate power production from solar to the system
	-Negative numbers indicate sending power from the system to solar - this should never be higher than 100 Watts.  On occasion I see +/- -10 at night.
5. "busway" - Unknown - my numbers show 0 for this.
6. "frequency" - Unknown - my numbers show 0 for this.
7. "generator" - Unknown I don't have a generator - my numbers show 0 for this.

---
**State of Charge / State of Energy**
Vince Loschiavo's avatar
Vince Loschiavo committed
62
_GET /api/system_status/soe_
Vince Loschiavo's avatar
Vince Loschiavo committed
63
64

This returns the aggregate charge state in percent of the powerwall(s).
Vince Loschiavo's avatar
Vince Loschiavo committed
65

Vince Loschiavo's avatar
Vince Loschiavo committed
66
request: `curl http://192.168.xxx.xxx/api/system_status/soe`
Vince Loschiavo's avatar
Vince Loschiavo committed
67

Vince Loschiavo's avatar
Vince Loschiavo committed
68
69
70
71
response:	`{"percentage":69.1675560298826}`

---

Vince Loschiavo's avatar
Vince Loschiavo committed
72
73
74
75
76
_GET /api/sitemaster_
Use this URL to determine: 
1. Powerwall state {running|stopped}
2. How long the powerwall has been set to the running state {in seconds}
3. Is the powerwall gateway connected to Tesla's servers {true|false}}
Vince Loschiavo's avatar
Vince Loschiavo committed
77

Vince Loschiavo's avatar
Vince Loschiavo committed
78
request: `curl http://192.168.xxx.xxx/api/sitemaster`
Vince Loschiavo's avatar
Vince Loschiavo committed
79

Vince Loschiavo's avatar
Vince Loschiavo committed
80
response:	`{"running":true,"uptime":"166594s,","connected_to_tesla":true}`
Vince Loschiavo's avatar
Vince Loschiavo committed
81
82
83

---

Vince Loschiavo's avatar
Vince Loschiavo committed
84
85
_GET /api/powerwalls_
Use this URL to determine how many power walls you have, their serial numbers, and if they are in sync (assuming more than one powerwall).
Vince Loschiavo's avatar
Vince Loschiavo committed
86

Vince Loschiavo's avatar
Vince Loschiavo committed
87
request: `curl http://192.168.xxx.xxx/api/powerwalls`
Vince Loschiavo's avatar
Vince Loschiavo committed
88

Vince Loschiavo's avatar
Vince Loschiavo committed
89
response:	`{"powerwalls":[{"PackagePartNumber":"1234567-01-E","PackageSerialNumber":"T1234567890"},{"PackagePartNumber":"1012345-03-E","PackageSerialNumber":"T1234567891"}],"has_sync":true}`
Vince Loschiavo's avatar
Vince Loschiavo committed
90
91
92

---

Vince Loschiavo's avatar
Vince Loschiavo committed
93
94
_GET /api/customer/registration_
Use this URL to determine registration status.  The below shows the results from a system that is fully configured and running.
Vince Loschiavo's avatar
Vince Loschiavo committed
95

Vince Loschiavo's avatar
Vince Loschiavo committed
96
request: `curl http://192.168.xxx.xxx/api/customer/registration`
Vince Loschiavo's avatar
Vince Loschiavo committed
97

Vince Loschiavo's avatar
Vince Loschiavo committed
98
response: `{"privacy_notice":true,"limited_warranty":true,"grid_services":null,"marketing":null,"registered":true,"emailed_registration":true,"skipped_registration":false,"timed_out_registration":false}`
Vince Loschiavo's avatar
Vince Loschiavo committed
99
100
101

---

Vince Loschiavo's avatar
Vince Loschiavo committed
102
103
104
105
_GET /api/system_status/grid_status_
Determine if the Grid is up or down.

request: `curl http://192.168.xxx.xxx/api/customer/registration`
Vince Loschiavo's avatar
Vince Loschiavo committed
106

Vince Loschiavo's avatar
Vince Loschiavo committed
107
response: `{"grid_status":"SystemGridConnected"}`
Vince Loschiavo's avatar
Vince Loschiavo committed
108

Vince Loschiavo's avatar
Vince Loschiavo committed
109
110
{SystemGridConnected} = Grid is up.
{?} = Grid is down.  (I haven't seen a grid down situation yet - have any of you seen the value for a grid down?)  
Vince Loschiavo's avatar
Vince Loschiavo committed
111
112

---
Vince Loschiavo's avatar
Vince Loschiavo committed
113
_GET /api/system/update/status_
Vince Loschiavo's avatar
Vince Loschiavo committed
114

Vince Loschiavo's avatar
Vince Loschiavo committed
115
request: `curl http://192.168.xxx.xxx/api/system/update/status`
Vince Loschiavo's avatar
Vince Loschiavo committed
116

Vince Loschiavo's avatar
Vince Loschiavo committed
117
118
response: `{"state":"/update_failed","info":{"status":["nonactionable"]},"current_time":1422697552910}`

Vince Loschiavo's avatar
Vince Loschiavo committed
119
120
121
1. update_failed / status nonactionable = I tried to do an upgrade but I have the latest firmware version already installed.
2. current_time in EPOC.
	-1422697552910 = **GMT**: Monday, April 2, 2018 8:09:17.447 PM
Vince Loschiavo's avatar
Vince Loschiavo committed
122
	
Vince Loschiavo's avatar
Vince Loschiavo committed
123
---	
Vince Loschiavo's avatar
Vince Loschiavo committed
124
_GET /api/site_info_
Vince Loschiavo's avatar
Vince Loschiavo committed
125

Vince Loschiavo's avatar
Vince Loschiavo committed
126
request: `curl http://192.168.xxx.xxx/api/site_info`
Vince Loschiavo's avatar
Vince Loschiavo committed
127

Vince Loschiavo's avatar
Vince Loschiavo committed
128
response: `Response: {"site_name":"Home Energy Gateway","timezone":"America/Los_Angeles","min_site_meter_power_kW":-1000000000,"max_site_meter_power_kW":1000000000,"nominal_system_energy_kWh":13.5,"grid_code":"60Hz_240V_s_UL1741SA:2016_California","grid_voltage_setting":240,"grid_freq_setting":60,"grid_phase_setting":"Split","country":"United States","state":"California","region":"UL1741SA"}`
Vince Loschiavo's avatar
Vince Loschiavo committed
129
130
131

---

Vince Loschiavo's avatar
Vince Loschiavo committed
132
_GET /api/site_info/site_name_
Vince Loschiavo's avatar
Vince Loschiavo committed
133

Vince Loschiavo's avatar
Vince Loschiavo committed
134
request: `curl http://192.168.xxx.xxx/api/site_info/site_name`
Vince Loschiavo's avatar
Vince Loschiavo committed
135

Vince Loschiavo's avatar
Vince Loschiavo committed
136
response: `{"site_name":"Home Energy Gateway","timezone":"America/Los_Angeles"}`
Vince Loschiavo's avatar
Vince Loschiavo committed
137
138

---
Vince Loschiavo's avatar
Vince Loschiavo committed
139
_GET /api/status_
Vince Loschiavo's avatar
Vince Loschiavo committed
140

Vince Loschiavo's avatar
Vince Loschiavo committed
141
request: `curl http://192.168.xxx.xxx/api/status`
Vince Loschiavo's avatar
Vince Loschiavo committed
142

Vince Loschiavo's avatar
Vince Loschiavo committed
143
144
145
response: `{"start_time":"2018-03-16 19:08:46 +0800","up_time_seconds":"402h8m19.937911668s","is_new":false,"version":"1.15.0\n","git_hash":"dc337851c6cad15a7e9c7223d60fff719eb8da4d\n"}`

Useful here: Gateway Version:  "version":"1.15.0\n"
Vince Loschiavo's avatar
Vince Loschiavo committed
146
147
148

---

Vince Loschiavo's avatar
Vince Loschiavo committed
149
150
151
152
_GET /api/logout_

The Gateway Web UI uses this url to logout of the wizard.  I assume you can also use this to expire an auth token...(some testing is required).

Vince Loschiavo's avatar
Vince Loschiavo committed
153
Request: `curl -i 192.168.xxx.xxx/api/logout`
Vince Loschiavo's avatar
Vince Loschiavo committed
154

Vince Loschiavo's avatar
Vince Loschiavo committed
155
156
157
158
159
160
161
162
Response: `HTTP/1.1 204 No Content
Access-Control-Allow-Credentials: false
Access-Control-Allow-Headers: X-Requested-With, X-HTTP-Method-Override, Content-Type, Accept, Accept-Encoding, Authorization
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
Access-Control-Allow-Origin: *
Access-Control-Max-Age: 86400`

---
Vince Loschiavo's avatar
Vince Loschiavo committed
163
164
165
166
_GET /api/system_status/grid_faults_

Not sure what this does...does it list the recent grid failure dates/times?

Vince Loschiavo's avatar
Vince Loschiavo committed
167
Request: `curl 192.168.xxx.xxx/api/system_status/grid_faults`
Vince Loschiavo's avatar
Vince Loschiavo committed
168

Vince Loschiavo's avatar
Vince Loschiavo committed
169
170
171
Response: `[]`

---
Vince Loschiavo's avatar
Vince Loschiavo committed
172
_GET /api/sitemaster/stop_
Vince Loschiavo's avatar
Vince Loschiavo committed
173

Vince Loschiavo's avatar
Vince Loschiavo committed
174
This stops the powerwalls & gateway.  In the stopped state, the powerwall will not charge, discharge, or monitor solar, grid, battery, home statistics.
Vince Loschiavo's avatar
Vince Loschiavo committed
175

Vince Loschiavo's avatar
Vince Loschiavo committed
176
Request: `curl http://192.168.xxx.xxx/api/sitemaster/stop`
Vince Loschiavo's avatar
Vince Loschiavo committed
177

Vince Loschiavo's avatar
Vince Loschiavo committed
178
Response:  
Vince Loschiavo's avatar
Vince Loschiavo committed
179
180

---
Vince Loschiavo's avatar
Vince Loschiavo committed
181
182
183
_GET /api/sitemaster/run_

This starts the powerwalls & gateway.  Use this after getting an authentication token to restart the powerwalls.
Vince Loschiavo's avatar
Vince Loschiavo committed
184

Vince Loschiavo's avatar
Vince Loschiavo committed
185
Request: `http://192.168.xxx.xxx/api/sitemaster/run`
Vince Loschiavo's avatar
Vince Loschiavo committed
186

Vince Loschiavo's avatar
Vince Loschiavo committed
187
188
189
190
191
192
193
194
Response:  

---
_GET /api/config/completed_

This applies configuration changes.

This is a GET request and doesn't require an authentication token.
Vince Loschiavo's avatar
Vince Loschiavo committed
195

Vince Loschiavo's avatar
Vince Loschiavo committed
196
Request: `curl /api/config/completed`
Vince Loschiavo's avatar
Vince Loschiavo committed
197

Vince Loschiavo's avatar
Vince Loschiavo committed
198
Response:
Vince Loschiavo's avatar
Vince Loschiavo committed
199
200

___
Vince Loschiavo's avatar
Vince Loschiavo committed
201
Note: __*** The below API calls require authentication ***__
Vince Loschiavo's avatar
Vince Loschiavo committed
202
203
204


**Login**
Vince Loschiavo's avatar
Vince Loschiavo committed
205
_POST /api/login/Basic_
Vince Loschiavo's avatar
Vince Loschiavo committed
206
207

**Authentication example:**
Vince Loschiavo's avatar
Vince Loschiavo committed
208
209
210
211
Note: Getting an authentication token will stop the powerwall.  It won't charge, discharge, or collect stats on v1.15.0.  Therefore you should re-enable the powerwall after getting a token.  
See: the _/api/sitemaster/run_ section above.

Here is an example login using a blank username (none needed) and a serial number of T123456789.  The password is S+Serial number: ST123456789.
Vince Loschiavo's avatar
Vince Loschiavo committed
212
213

Request: `curl -s -i -X POST -H "Content-Type: application/json" -d '{"username":"","password":"ST123456789","force_sm_off":false}' "http://192.168.xxx.xxx/api/login/Basic"`
Vince Loschiavo's avatar
Vince Loschiavo committed
214

Vince Loschiavo's avatar
Vince Loschiavo committed
215
216
Response: `{"email":null,"firstname":"Tesla","lastname":"Energy","roles":["Provider_Engineer"],"token":"OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==","provider":"Basic"}`

Vince Loschiavo's avatar
Vince Loschiavo committed
217
Save the token for use with the below calls.
Vince Loschiavo's avatar
Vince Loschiavo committed
218
219

---
Vince Loschiavo's avatar
Vince Loschiavo committed
220
221
_POST /api/operation_
Change the Powerwall mode and Reserve Percentage
Vince Loschiavo's avatar
Vince Loschiavo committed
222
223
224
225
226
227
228
229
230
231

_Note 1: Making changes to the Powerwalls via the Mobile application can take some time to go into effect.  There's a rumor that states that the changes happen around 30 minutes past the hour. (Probably based on a cron job in Tesla's servers)._

_Note 2: Setting a value is not sufficient to make the change.  You must "save" or "commit" the configuration to have it go into effect.  See  the _Config Completed_ section below._

_Note 3: Once a value is changed and committed it is immediately in effect._

The below request would set the battery mode to "Self-powered" and a "Reserve for Power Outages" to 20% (app value) using the token retrieved from the authentication example. 

request: `curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" -X POST -d '{"mode":"self_consumption","backup_reserve_percent":20}' 'http://192.168.xxx.xxx/api/operation'`
Vince Loschiavo's avatar
Vince Loschiavo committed
232

Vince Loschiavo's avatar
Vince Loschiavo committed
233
response: `{"mode":"self_consumption","backup_reserve_percent":24}`
Vince Loschiavo's avatar
Vince Loschiavo committed
234
235
236
237
238

Valid Modes:
1. `self_consumption`
2. `backup`

Vince Loschiavo's avatar
Vince Loschiavo committed
239
There also is an option to set the max PV Export power in kW.  I'm not 100% sure what that does but I could guess. Mine is currently set to null.  You can omit this key/value pair from the POST.
Vince Loschiavo's avatar
Vince Loschiavo committed
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272

`{max_pv_export_power_kW: null, mode: "self_consumption", backup_reserve_percent: 24}`

Note the difference in the app value (20%) versus the value we set via the local API (24%).  The difference is likely proportional until you reach 100%:

Tested values:
20% = 24%
30% = 33%
100% = 100%.

---

Others to be documented:
/api/powerwalls/status
/api/site_info/grid_codes
/api/solars
/api/solars/brands
/api/generators
/api/generators/disconnect_types
/api/solars/brands/SolarEdge%20Technologies
/api/meters
/api/meters/readings
/api/installer - `{company: "Tesla Timbuktu", customer_id: "01234567", phone: "8885551212"}`
/api/customer
/api/config - `{vin: "0123456-00-E--T1234567890"}`


___
Other
---

/api/siteinfo/timezone - `404 - not working at the moment. Requires auth?`