Code by Scott שאול בן ישוע
README.md 27.2 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
_(This documentation is currently in flux: portions are updated and portions aren't updated.  Use at your own risk)_
Vince Loschiavo's avatar
Vince Loschiavo committed
5

6
7
_(I am in process of updating this documentation to work with firmware version 1.40.2)_

Vince Loschiavo's avatar
Vince Loschiavo committed
8
9
10
11
12
___*** Please be patient as I have an unrelated day job! ***___

**Please help me update this: Pull requests are welcome!**

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

gpeszek's avatar
gpeszek committed
14
15
A note about HTTPS and SSL Certificates
---
16
17
In a recent update to the Powerwall firmware (v1.20+) non-SSL requests (http) are no longer supported and queries will return HTTP/1.1 301 Moved Permanently.  Unfortunately the certificate presented by the Powerwall is not signed by a root certificate authority as they are self-signed.  This results in web browsers and tools like curl not accept it without it either being included as a trusted certificate or a specific action by the user to override the error. 

Vince Loschiavo's avatar
Vince Loschiavo committed
18
You have three ways around a certificate error:
Vince Loschiavo's avatar
Vince Loschiavo committed
19

Vince Loschiavo's avatar
Vince Loschiavo committed
20
1) In web browser this will manifest itself as an error that the certificate is not trusted.  To bypass simply click "details" (IE/Edge) or "Advanced..." (Firefox) and select continue.
Vince Loschiavo's avatar
Vince Loschiavo committed
21

Vince Loschiavo's avatar
Vince Loschiavo committed
22
2) With curl the `--insecure` or `-k` option will ignore the SSL certificate.  This is ok, but it doesn't authenticate the device you are connecting to.
Vince Loschiavo's avatar
Vince Loschiavo committed
23

Vince Loschiavo's avatar
Vince Loschiavo committed
24
3) A better way is to export the Powerwall public certificate and add it to the local machine's trusted certificate list or just use the certificate in your curl request.
25

Vince Loschiavo's avatar
Vince Loschiavo committed
26
__I recommend option 3 above.__
27

Vince Loschiavo's avatar
Vince Loschiavo committed
28
_Here's what worked for me:_
Vince Loschiavo's avatar
Vince Loschiavo committed
29

Vince Loschiavo's avatar
Vince Loschiavo committed
30
Step 1: DNS
Vince Loschiavo's avatar
Vince Loschiavo committed
31

Vince Loschiavo's avatar
Vince Loschiavo committed
32
33
34
35
Enable DNS lookups, on your local network, for one of the following DNS names in the certificate under the "Certificate Subject Alt Name".  On my gateway these names are:
1) teg
2) powerwall
3) powerpack
Vince Loschiavo's avatar
Vince Loschiavo committed
36

Vince Loschiavo's avatar
Vince Loschiavo committed
37
You can add this to your local DNS server as an A Record or /etc/hosts file or other DNS name resolution service.  
38

Vince Loschiavo's avatar
Vince Loschiavo committed
39
For /etc/hosts add an entry that looks like this if your Powerwall gateway's IP was 192.168.99.99:
Vince Loschiavo's avatar
Vince Loschiavo committed
40

Vince Loschiavo's avatar
Vince Loschiavo committed
41
`192.168.99.99	powerwall`
42
43

Step 2: Get the certificate
Vince Loschiavo's avatar
Vince Loschiavo committed
44
`echo quit | openssl s_client -showcerts -servername powerwall -connect powerwall:443 > cacert.pem`
45

Vince Loschiavo's avatar
Vince Loschiavo committed
46
This grabs the certificate from the powerwall using the DNS entry you setup in step 1.
47
48

Step 3: use the certificate in your curl statements
Vince Loschiavo's avatar
Vince Loschiavo committed
49
e.g. `curl --cacert cacert.pem https://powerwall/api/meters/aggregates`
50

Vince Loschiavo's avatar
Vince Loschiavo committed
51
If you get this error: `curl: (51) SSL: no alternative certificate subject name matches target host name` then the name you chose (teg or powerwall or powerpack) doesn't match what's in the certificate file and you'll need to check the certificate and perhaps do some googling to figure out the solution.
52

Vince Loschiavo's avatar
Vince Loschiavo committed
53
For the rest of the documentation, I will assume you copied the certificate and are using method C with the Powerwall's public certificate.  If you didn't, just leave out the certificate `--cacert cacert.pem` portion and add `-k`.
gpeszek's avatar
gpeszek committed
54
55


Vince Loschiavo's avatar
Vince Loschiavo committed
56
Powerwall 2 Web UI
Vince Loschiavo's avatar
Vince Loschiavo committed
57
---
Vince Loschiavo's avatar
Vince Loschiavo committed
58
The web UI provides ~~an instantaneous~~ a 250-500ms average(?) power flow diagram an access to the wizard.
59
Hit your local gateway IP with a browser, i.e. _https://powerwall/
Vince Loschiavo's avatar
Vince Loschiavo committed
60
61
62

You should see something like this:

Vince Loschiavo's avatar
Vince Loschiavo committed
63
![GatewayUI](https://github.com/vloschiavo/powerwall2/raw/master/img/TeslaPowerwallGatewayUI.jpg "Gateway Web UI")
Vince Loschiavo's avatar
Vince Loschiavo committed
64
65

---
Vince Loschiavo's avatar
Vince Loschiavo committed
66
**Wizard**
67
You can hit the _"Login"_ link on this page and go through the setup (be careful what you change in the wizard).
Vince Loschiavo's avatar
Vince Loschiavo committed
68

69
`username: <Enter whatever you like here>`
Vince Loschiavo's avatar
Vince Loschiavo committed
70

71
72
`password: `
Follow the instructions on the web page to set/change/recover the password. Whatever you set here will be used later.
Vince Loschiavo's avatar
Vince Loschiavo committed
73

Vince Loschiavo's avatar
Vince Loschiavo committed
74

Vince Loschiavo's avatar
Vince Loschiavo committed
75
76
77
78
___
### Information

**Meters / Power output stats**
79
Calling the below URLs does not require authentication.  Each will return JSON output with key-value pairs. Specify the cacert.pem you grabbed earlier using the Certificate Subject Alt Name.
Vince Loschiavo's avatar
Vince Loschiavo committed
80

Vince Loschiavo's avatar
Vince Loschiavo committed
81
_GET /api/meters/aggregates_
Vince Loschiavo's avatar
Vince Loschiavo committed
82

83
request: `curl --cacert cacert.pem https://powerwall/api/meters/aggregates`
Vince Loschiavo's avatar
Vince Loschiavo committed
84

Vince Loschiavo's avatar
Vince Loschiavo committed
85
86
87
88
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
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
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.

Vince Loschiavo's avatar
Vince Loschiavo committed
105
106
When site master or the Powerwalls are off, the response is: HTTP Status 502

vls29's avatar
vls29 committed
107
108
109
110
_GET /api/meters/site_

Detailed information about the site specific meter.

111
request: `curl --cacert cacert.pem https://powerwall/api/meters/site`
vls29's avatar
vls29 committed
112

Vince Loschiavo's avatar
Vince Loschiavo committed
113
response: [see sample response here](https://raw.githubusercontent.com/vloschiavo/powerwall2/master/samples/api-meters-site.json)
vls29's avatar
vls29 committed
114
115
116
117
118

_GET /api/meters/solar_

Detailed information about the solar specific meter.

119
request: `curl --cacert cacert.pem https://powerwall/api/meters/solar`
vls29's avatar
vls29 committed
120

Vince Loschiavo's avatar
Vince Loschiavo committed
121
response: [see sample response here](https://raw.githubusercontent.com/vloschiavo/powerwall2/master/samples/api-meters-solar.json)
vls29's avatar
vls29 committed
122
123


Vince Loschiavo's avatar
Vince Loschiavo committed
124
125
---
**State of Charge / State of Energy**
Vince Loschiavo's avatar
Vince Loschiavo committed
126
_GET /api/system_status/soe_
Vince Loschiavo's avatar
Vince Loschiavo committed
127
128

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

130
request: `curl --cacert cacert.pem https://powerwall/api/system_status/soe`
Vince Loschiavo's avatar
Vince Loschiavo committed
131

Vince Loschiavo's avatar
Vince Loschiavo committed
132
133
response:	`{"percentage":69.1675560298826}`

Vince Loschiavo's avatar
Vince Loschiavo committed
134
135
When site master or the Powerwalls are off, the response is: HTTP Status 502

Vince Loschiavo's avatar
Vince Loschiavo committed
136
137
---

Vince Loschiavo's avatar
Vince Loschiavo committed
138
139
140
141
142
_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
143

144
request: `curl --cacert cacert.pem https://powerwall/api/sitemaster`
Vince Loschiavo's avatar
Vince Loschiavo committed
145

146
response:	`{"running":true,"uptime":"802459s,","connected_to_tesla":true}`
Vince Loschiavo's avatar
Vince Loschiavo committed
147

Vince Loschiavo's avatar
Vince Loschiavo committed
148
149
When site master or the Powerwalls are off, the response is:  `{"running":false,"uptime":"log:","connected_to_tesla":false}`

Vince Loschiavo's avatar
Vince Loschiavo committed
150
151
---

Vince Loschiavo's avatar
Vince Loschiavo committed
152
153
_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
154

155
request: `curl --cacert cacert.pem https://powerwall/api/powerwalls`
Vince Loschiavo's avatar
Vince Loschiavo committed
156

Vince Loschiavo's avatar
Vince Loschiavo committed
157
response:	[see sample response here](https://raw.githubusercontent.com/vloschiavo/powerwall2/master/samples/api-powerwalls.json)
Vince Loschiavo's avatar
Vince Loschiavo committed
158
159
160

I have two of the AC Powerwall 2s in the United States.  The PackagePartNumber is: 1092170-03-E.  Let me know if you have a different package part number and what Powerwall model you have.  (i.e. DC, AC, Powerwall v1 or v2)

Vince Loschiavo's avatar
Vince Loschiavo committed
161
162
163

---

Vince Loschiavo's avatar
Vince Loschiavo committed
164
165
_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
166

167
request: `curl --cacert cacert.pem https://powerwall/api/customer/registration`
Vince Loschiavo's avatar
Vince Loschiavo committed
168

169
response: `{"privacy_notice":true,"limited_warranty":true,"grid_services":null,"marketing":null,"registered":true,"timed_out_registration":false}`
Vince Loschiavo's avatar
Vince Loschiavo committed
170
171
172

---

Vince Loschiavo's avatar
Vince Loschiavo committed
173
174
175
_GET /api/system_status/grid_status_
Determine if the Grid is up or down.

176
request: `curl --cacert cacert.pem https://powerwall/api/system_status/grid_status`
Vince Loschiavo's avatar
Vince Loschiavo committed
177

178
response: {"grid_status":"SystemGridConnected","grid_services_active":false}
Vince Loschiavo's avatar
Vince Loschiavo committed
179

Vince Loschiavo's avatar
Vince Loschiavo committed
180
`{"grid_status":"SystemGridConnected"}` = grid is up
Vince Loschiavo's avatar
Vince Loschiavo committed
181

Vince Loschiavo's avatar
Vince Loschiavo committed
182
`{"grid_status":"SystemIslandedActive"}` = grid is down
Vince Loschiavo's avatar
Vince Loschiavo committed
183

Vince Loschiavo's avatar
Vince Loschiavo committed
184
185
`{"grid_status":"SystemTransitionToGrid"}` = grid is restored but not yet in sync.

Vince Loschiavo's avatar
Vince Loschiavo committed
186
---
Vince Loschiavo's avatar
Vince Loschiavo committed
187
_GET /api/system/update/status_
188
189
_UPDATE: You need to be authenticated for this command_
request: `curl --cacert cacert.pem https://powerwall/api/system/update/status`
Vince Loschiavo's avatar
Vince Loschiavo committed
190

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

Vince Loschiavo's avatar
Vince Loschiavo committed
193
194
195
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
196
	
Vince Loschiavo's avatar
Vince Loschiavo committed
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
	  
possible values of "state" property, according to the code:

-   "/clear_update_status", // Checking for firmware update is in progress (need to keep sending request until state is changed)  
    
-   "/update_succeeded", // Success  
    
-   "/update_failed", // Update failed, or not required  
    
-   "/update_staged", // Staging update?  
    
-   "/download",  // Downloading update  
    
-   "/update_downloaded", // Ready to update  
    
-   "/update_unknown"  

possible values of "status" property according to the code:

-   "ignoring", // possibly some uninterruptable action is in progress?  
    
-   "error",  
    
-   "nonactionable" // everything is OK  
    

  

Use case:  One user is making this request to check new firmware available, and run the upgrade, approximately 30 minutes before switching to discharging (self_consumption mode with 5% reserve). Assumption is - we better upgrade firmware while battery is in standby mode, rather then letting gateway upgrade itself later, because it will stop battery possibly during peak hours for an upgrade. He noticed his gateway has self-upgraded during peak hours, resulting around 15 minutes stop of battery, which was an unpleasant surprise and extra cost. So, his idea was to force a new firmware check (and upgrade) when battery is not used:

  
-   7:15am  check for new fimware and run an upgrade if firmware is available  
    
-   7:55am  - start discharging (self_consumption, 5% reserve)  
    
-   10:05pm  - start charging (backup, 100% reserve)  
    

Southern California Edison has TOU plan with the following details:

-   8am-2pm,  8pm-10pm  - offpeak  
    
-   2pm-8pm  - peak  
    
-   10pm-8am  - super offpeak

Vince Loschiavo's avatar
Vince Loschiavo committed
243
---	
Vince Loschiavo's avatar
Vince Loschiavo committed
244
_GET /api/site_info_
Vince Loschiavo's avatar
Vince Loschiavo committed
245

246
request: `curl --cacert cacert.pem https://powerwall/api/site_info`
Vince Loschiavo's avatar
Vince Loschiavo committed
247

248
response: `{"max_site_meter_power_kW":1000000000,"min_site_meter_power_kW":-1000000000,"nominal_system_energy_kWh":13.5,"nominal_system_power_kW":10,"site_name":"Loschiavo","timezone":"America/Los_Angeles","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","distributor":"*","utility":"Pacific Gas and Electric Company","retailer":"*","region":"UL1741SA"}`
Vince Loschiavo's avatar
Vince Loschiavo committed
249
250
251

---

Vince Loschiavo's avatar
Vince Loschiavo committed
252
_GET /api/site_info/site_name_
Vince Loschiavo's avatar
Vince Loschiavo committed
253

254
request: `curl --cacert cacert.pem https://powerwall/api/site_info/site_name`
Vince Loschiavo's avatar
Vince Loschiavo committed
255

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

258
259
The site_name value can be changed from the Tesla Mobile app settings.

Vince Loschiavo's avatar
Vince Loschiavo committed
260
---
Vince Loschiavo's avatar
Vince Loschiavo committed
261
_GET /api/status_
Vince Loschiavo's avatar
Vince Loschiavo committed
262

263
request: `curl --cacert cacert.pem https://powerwall/api/status`
Vince Loschiavo's avatar
Vince Loschiavo committed
264

265
response: `{"start_time":"2019-09-23 23:38:46 +0800","up_time_seconds":"223h5m51.577762169s","is_new":false,"version":"1.40.2","git_hash":"14f7c1769ec307bba2ea62355a09d01c8e58988c+"}`
Vince Loschiavo's avatar
Vince Loschiavo committed
266

267
Useful here: Gateway Version:  "version":"1.40.2\n"
Vince Loschiavo's avatar
Vince Loschiavo committed
268
269
270

---

Vince Loschiavo's avatar
Vince Loschiavo committed
271
272
273
_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).
274
_This is untested. Question for the community: Does this still work? Soliciting for pull requests! :)_
Vince Loschiavo's avatar
Vince Loschiavo committed
275

276
Request: `curl --cacert cacert.pem -i https://powerwall/api/logout`
Vince Loschiavo's avatar
Vince Loschiavo committed
277

278
279
Response: `HTTP/2 204 
date: Thu, 03 Oct 2019 13:48:10 GMT`
Vince Loschiavo's avatar
Vince Loschiavo committed
280

281
returns HTTP/2 Status 204, with a date
Vince Loschiavo's avatar
Vince Loschiavo committed
282

Vince Loschiavo's avatar
Vince Loschiavo committed
283
---
Vince Loschiavo's avatar
Vince Loschiavo committed
284
285
286
287
_GET /api/system_status/grid_faults_

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

288
Request: `curl --cacert cacert.pem https://powerwall/api/system_status/grid_faults`
Vince Loschiavo's avatar
Vince Loschiavo committed
289

Vince Loschiavo's avatar
Vince Loschiavo committed
290
291
292
Response: `[]`

---
Vince Loschiavo's avatar
Vince Loschiavo committed
293
_GET /api/sitemaster/stop_
294
_UPDATE: You need to be authenticated for this command_
Vince Loschiavo's avatar
Vince Loschiavo committed
295
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
296

297
Request: `curl --cacert cacert.pem https://powerwall/api/sitemaster/stop`
Vince Loschiavo's avatar
Vince Loschiavo committed
298

Vince Loschiavo's avatar
Vince Loschiavo committed
299
Response:  
Vince Loschiavo's avatar
Vince Loschiavo committed
300

Vince Loschiavo's avatar
Vince Loschiavo committed
301
302
303
304
returns HTTP Status 500 if powerwall cannot be stopped at this moment with the following JSON: 

`{"code":500,"error":"Cannot Start Wizard","message":"Unable to stop sitemaster"}`

Vince Loschiavo's avatar
Vince Loschiavo committed
305
---
Vince Loschiavo's avatar
Vince Loschiavo committed
306
_GET /api/sitemaster/run_
307
_UPDATE: You need to be authenticated for this command_
Vince Loschiavo's avatar
Vince Loschiavo committed
308
This starts the powerwalls & gateway.  Use this after getting an authentication token to restart the powerwalls.
Vince Loschiavo's avatar
Vince Loschiavo committed
309

310
Request: `curl --cacert cacert.pem https://powerwall/api/sitemaster/run`
Vince Loschiavo's avatar
Vince Loschiavo committed
311

Vince Loschiavo's avatar
Vince Loschiavo committed
312
Response:  
Vince Loschiavo's avatar
Vince Loschiavo committed
313
314
Returns HTTPS Status 202 if request is accepted

Vince Loschiavo's avatar
Vince Loschiavo committed
315
316
317

---
_GET /api/config/completed_
318
_UPDATE: You need to be authenticated for this command_
Vince Loschiavo's avatar
Vince Loschiavo committed
319
320
This applies configuration changes.

321
Request: `curl --cacert cacert.pem https://powerwall/api/config/completed`
Vince Loschiavo's avatar
Vince Loschiavo committed
322

Vince Loschiavo's avatar
Vince Loschiavo committed
323
Response:
Vince Loschiavo's avatar
Vince Loschiavo committed
324
325
Returns HTTP Status 202 if input accepted

Vince Loschiavo's avatar
Vince Loschiavo committed
326
327

___
Vince Loschiavo's avatar
Vince Loschiavo committed
328
Note: __*** The below API calls require authentication ***__
Vince Loschiavo's avatar
Vince Loschiavo committed
329

330
331
332
Note2: __*** This documentation is old (created on version 1.15) and needs updating ***__
__*** I wouldn't be surprised if less than 1% of the below still works in versions 1.40+ ***__

Vince Loschiavo's avatar
Vince Loschiavo committed
333
334

**Login**
Vince Loschiavo's avatar
Vince Loschiavo committed
335
_POST /api/login/Basic_
Vince Loschiavo's avatar
Vince Loschiavo committed
336

337
338
Note: _This section needs updating: Does this work?_

Vince Loschiavo's avatar
Vince Loschiavo committed
339
**Authentication example:**
340
Note: Getting an authentication token will stop the powerwall.  It won't charge, discharge, or collect stats on v1.15+.  Therefore you should re-enable the powerwall after getting a token.  
Vince Loschiavo's avatar
Vince Loschiavo committed
341
342
343
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
344

Vince Loschiavo's avatar
Vince Loschiavo committed
345
Request: 
Vince Loschiavo's avatar
Vince Loschiavo committed
346

347
`curl --cacert cacert.pem -s -i -X POST -H "Content-Type: application/json" -d '{"username":"","password":"ST123456789","force_sm_off":false}' https://powerwall/api/login/Basic`
Vince Loschiavo's avatar
Vince Loschiavo committed
348
349
350
351

Response: 

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

Vince Loschiavo's avatar
Vince Loschiavo committed
353
Save the token for use with the below calls.
Vince Loschiavo's avatar
Vince Loschiavo committed
354

Vince Loschiavo's avatar
Vince Loschiavo committed
355
356
357
358
359
360
**Note for Windows users:**
Windows shell handles quotes differently than linux Bash.
In windows, the above example works by:
1. changing the single quotes to double quotes
2. escape the double quotes inside the -d section

Vince Loschiavo's avatar
Vince Loschiavo committed
361
362
Windows Example Request: 

gpeszek's avatar
gpeszek committed
363
`curl -s -i -X POST -H "Content-Type: application/json" -d "{\"username\":\"\",\"password\":\"ST123456789\",\"force_sm_off\":false}" https://192.168.xxx.xxx/api/login/Basic`
Vince Loschiavo's avatar
Vince Loschiavo committed
364
365


Vince Loschiavo's avatar
Vince Loschiavo committed
366
---
Vince Loschiavo's avatar
Vince Loschiavo committed
367
_GET & POST /api/operation_
Vince Loschiavo's avatar
Vince Loschiavo committed
368
Change the Powerwall mode and Reserve Percentage
Vince Loschiavo's avatar
Vince Loschiavo committed
369
370
371
372
373
374
375

_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._

Vince Loschiavo's avatar
Vince Loschiavo committed
376
377
378

_GET_

gpeszek's avatar
gpeszek committed
379
request: `curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/operation`
Vince Loschiavo's avatar
Vince Loschiavo committed
380
381
382
383
384
385

response: `{"mode":"self_consumption","backup_reserve_percent":15}`


_POST_

Vince Loschiavo's avatar
Vince Loschiavo committed
386
387
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. 

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

Vince Loschiavo's avatar
Vince Loschiavo committed
390
response: `{"mode":"self_consumption","backup_reserve_percent":24.6}`
Vince Loschiavo's avatar
Vince Loschiavo committed
391
392
393
394

Valid Modes:
1. `self_consumption`
2. `backup`
Vince Loschiavo's avatar
Vince Loschiavo committed
395
396
397
398
399
400
401
402
403
404
405
406
3. `autonomous` (aka Time of Use (TOU) as reported by dlieu on the teslamotorsclub.com forums)
4. `scheduler`  aka Aggregation - This seems like it is not supported now. 

The JavaScript constant in the code of mobile client for Android has the following options:

```
OperationModes = 
{SELF_CONSUMPTION: "self_consumption",
TIME_OF_USE: "autonomous",
BACKUP: "backup",
AGGREGATION: "scheduler"}
```
Vince Loschiavo's avatar
Vince Loschiavo committed
407

Vince Loschiavo's avatar
Vince Loschiavo committed
408
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 (Time of use?). Mine is currently set to null (probably because time of use isn't enabled on my system yet (as of April 2018).  You can omit this key/value pair from the POST.
Vince Loschiavo's avatar
Vince Loschiavo committed
409
410
411
412
413

`{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%:

Vince Loschiavo's avatar
Vince Loschiavo committed
414
___**Tested values:**___
Vince Loschiavo's avatar
Vince Loschiavo committed
415

Vince Loschiavo's avatar
Vince Loschiavo committed
416
417
418
419
420
421
422
423
424
| APP Setting | API Setting |
| :-------------: |:-------------:|
| 5%	| 10%		| 
| 16%	| 20%		|
| 16%	| 20.6%		|
| 20%	| 24%		|
| 21%	| 24.6% 	|
| 30%	| 33%		|
| 100%	| 100%		|
Vince Loschiavo's avatar
Vince Loschiavo committed
425

Vince Loschiavo's avatar
Vince Loschiavo committed
426

Vince Loschiavo's avatar
Vince Loschiavo committed
427
428
---

Vince Loschiavo's avatar
Vince Loschiavo committed
429
_GET /api/powerwalls/status_
Vince Loschiavo's avatar
Vince Loschiavo committed
430

Vince Loschiavo's avatar
Vince Loschiavo committed
431
Informational:
Vince Loschiavo's avatar
Vince Loschiavo committed
432

Vince Loschiavo's avatar
Vince Loschiavo committed
433
434
Request:

gpeszek's avatar
gpeszek committed
435
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/powerwalls/status`
Vince Loschiavo's avatar
Vince Loschiavo committed
436
437

Response:
Vince Loschiavo's avatar
Vince Loschiavo committed
438

Vince Loschiavo's avatar
Vince Loschiavo committed
439
440
441
442
443
444
445
446
`{"code":409,"error":"Sitemaster is current running","message":"Sitemaster is current running"}`

---
_GET /api/site_info/grid_codes_
Informational: setting options used in the wizard

Request:

gpeszek's avatar
gpeszek committed
447
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/site_info/grid_codes`
Vince Loschiavo's avatar
Vince Loschiavo committed
448
449
450
451
452
453
454
455

Response: 

[ Grid Codes Long JSON response here](https://raw.githubusercontent.com/vloschiavo/powerwall2/master/samples/api_site_info_grid_codes.json)

---

_GET /api/solars_
Vince Loschiavo's avatar
Vince Loschiavo committed
456

Vince Loschiavo's avatar
Vince Loschiavo committed
457
458
459
460
Informational: responds with the solar inverter brand, model, and max power rating as stored on the gateway.

Request:

gpeszek's avatar
gpeszek committed
461
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/solars`
Vince Loschiavo's avatar
Vince Loschiavo committed
462
463
464
465
466
467
468
469

Reply:

`[{"brand":"SolarEdge Technologies","model":"SE5000 (240V) w/ -ER-US or A-US","power_rating_watts":6000}]`

---

_GET /api/solars/brands_
Vince Loschiavo's avatar
Vince Loschiavo committed
470

Vince Loschiavo's avatar
Vince Loschiavo committed
471
472
473
474
Informational: responds with the Solar inverter Brand options for the wizard.

Request:

gpeszek's avatar
gpeszek committed
475
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/solars/brands > api_solars_brands.json`
Vince Loschiavo's avatar
Vince Loschiavo committed
476
477
478
479
480

[ Solar Brands - Long JSON response here](https://raw.githubusercontent.com/vloschiavo/powerwall2/master/samples/api_solars_brands.json)

---

Vince Loschiavo's avatar
Vince Loschiavo committed
481
482
483
484
485
486
487

_GET /api/solars/brands/SolarEdge%20Technologies_

Informational: Get a list of SolarEdge models - used in the wizard.

Request:

gpeszek's avatar
gpeszek committed
488
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/solars/brands/SolarEdge%20Technologies`
Vince Loschiavo's avatar
Vince Loschiavo committed
489
490
491
492
493
494
495

Response

[ SolarEdge Models - Long JSON response here](https://raw.githubusercontent.com/vloschiavo/powerwall2/master/samples/solar_edge_models.json)

---

Vince Loschiavo's avatar
Vince Loschiavo committed
496
497
498
499
500
501
_GET /api/generators_

Note: I don't have a generator tied to my system.

Request:

gpeszek's avatar
gpeszek committed
502
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" httsp://192.168.xxx.xxx/api/generators`
Vince Loschiavo's avatar
Vince Loschiavo committed
503
504
505
506
507
508
509
510

Response:

`{"disconnect_type":"None","generators":[]}`

---


Vince Loschiavo's avatar
Vince Loschiavo committed
511
512
513
514
515
516
_GET /api/customer_

Informational:

Request: 

gpeszek's avatar
gpeszek committed
517
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/customer`
Vince Loschiavo's avatar
Vince Loschiavo committed
518
519
520
521

Response:

`{"city":"New York","state":"New York ","zip":"10010","country":"US","registered":true,"privacy_notice":true,"limited_warranty":true,"emailed_registration":true}`
Vince Loschiavo's avatar
Vince Loschiavo committed
522
523
524
525

---


Vince Loschiavo's avatar
Vince Loschiavo committed
526
_GET /api/config_
Vince Loschiavo's avatar
Vince Loschiavo committed
527

Vince Loschiavo's avatar
Vince Loschiavo committed
528
Informational - I'm not sure what this is...
Vince Loschiavo's avatar
Vince Loschiavo committed
529

Vince Loschiavo's avatar
Vince Loschiavo committed
530
Request:
Vince Loschiavo's avatar
Vince Loschiavo committed
531

gpeszek's avatar
gpeszek committed
532
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/config`
Vince Loschiavo's avatar
Vince Loschiavo committed
533

Vince Loschiavo's avatar
Vince Loschiavo committed
534
Response:
Vince Loschiavo's avatar
Vince Loschiavo committed
535

Vince Loschiavo's avatar
Vince Loschiavo committed
536
537
538
539
540
541
542
543
544
545
`{vin: "0123456-00-E--T1234567890"}`


---
__Others to be documented:__

_GET /api/generators/disconnect_types_

Request:

gpeszek's avatar
gpeszek committed
546
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/generators/disconnect_types`
Vince Loschiavo's avatar
Vince Loschiavo committed
547
548
549
550
551
552
553
554
555
556
557
558


Response:

`["DownstreamATS"]`

---

_GET /api/meters_

Request: 

gpeszek's avatar
gpeszek committed
559
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/meters`
Vince Loschiavo's avatar
Vince Loschiavo committed
560
561
562
563
564
565
566
567
568
569
570
571
572
573

Response:

`[{"serial":"OBB3172012345","short_id":"49123","connected":true,"cts":[{"type":"solar","valid":[false,false,true,true],"inverted":[false,false,false,false]},{"type":"site","valid":[true,true,false,false],"inverted":[false,false,false,false]}]}]`

---


_GET /api/installer_

Details of the company that did the installation of the powerwall as well as your customer ID in their system.  This can be configured in the Wizard.

Request:

gpeszek's avatar
gpeszek committed
574
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/installer`
Vince Loschiavo's avatar
Vince Loschiavo committed
575
576
577
578

Response:

 `{company: "Tesla Timbuktu", customer_id: "01234567", phone: "8885551212"}`
Vince Loschiavo's avatar
Vince Loschiavo committed
579

Vince Loschiavo's avatar
Vince Loschiavo committed
580
581
582
583
Alternative Response:
`{"company":"Tesla Orange County","customer_id":"1234567","phone":"1231234567","email":"...","run_sitemaster":true}`


Vince Loschiavo's avatar
Vince Loschiavo committed
584

Vince Loschiavo's avatar
Vince Loschiavo committed
585

Vince Loschiavo's avatar
Vince Loschiavo committed
586
587
---

Vince Loschiavo's avatar
Vince Loschiavo committed
588
__Others to document__
Vince Loschiavo's avatar
Vince Loschiavo committed
589

Vince Loschiavo's avatar
Vince Loschiavo committed
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
POST /api/sitemaster/run_for_commissioning

GET /api/customer/registration
{"privacy_notice":true,"limited_warranty":true,"grid_services":false,"marketing":true,"registered":true,"emailed_registration":true,"skipped_registration":false,"timed_out_registration":false}

POST /api/customer/registration/skip

GET /api/installer/companies
[{
		"company" : "1 Willpower Ltd",
		"customer_id" : "AN-0000059"
	}, {
		"company" : "1000 Energie",
		"customer_id" : "AN-0000062"
        }, {
                ... <LONG_LIST>
}]

POST /api/networks/wifi_scan

POST /api/networks
"Content-Type": "application/json"
{
        interface: K.InterfaceTypes.WIFI,
        network_name: ???,
	security_type: ???
Vince Loschiavo's avatar
Vince Loschiavo committed
616
617
618
}

POST /api/networks/<...>/disable
Vince Loschiavo's avatar
Vince Loschiavo committed
619
620
621
622
623
624
625
626
627
628
629
630
631
632
POST /api/networks/<...>/enable

POST /api/system/networks/conn_tests

while test is running the request returns:
{"results":null,"timestamp":"0001-01-01T00:00:00Z"}

when test is complete it returns:
{
	"results" : {
		"Config Syncer Test" : {
			"pass" : true,
			"error" : ""
		},
Vince Loschiavo's avatar
Vince Loschiavo committed
633
		"Gle GET Test" : {
Vince Loschiavo's avatar
Vince Loschiavo committed
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
			"pass" : true,
			"error" : ""
		},
		"Hermes Status Test" : {
			"pass" : true,
			"error" : ""
		},
		"Synergy Data Test" : {
			"pass" : true,
			"error" : ""
		}
	},
	"timestamp" : "2018-02-22T17:12:56.296673681-08:00"
}

Also need to research:
??? /api/system/networks/ping_test

POST /api/logging
{
	level: ???,
	log: ???
}

POST /api/customer/registration/emailed

POST /api/customer/registration/legal
"Content-Type": "application/json"
response:
{
	marketing: ???,
	privacy_notice: ???,
	limited_warranty: ???,
	grid_services: ???
}

GET /api/networks
returns all configured network adapters in gateway which seems running Linux:

can0 - very interesting unknown adapter (CAN-bus for the car??)
eth0 - ethernet
rpine0 - seems cellular network adapter (3G)
wifi0 - wireless adapter to connect to home network
wifi1 - configured as access point (TEG-XXXX)

[{
		"id" : 2,
		"name" : "can0",
		"connected" : true,
		"is_dhcp" : true,
		"ip_address" : "",
		"subnet" : "",
		"config" : null
	}, {
		"id" : 3,
		"name" : "eth0",
		"connected" : true,
		"is_dhcp" : true,
		"ip_address" : "",
		"subnet" : "",
		"config" : null
	}, {
		"id" : 170,
		"name" : "rpine0",
		"connected" : true,
		"is_dhcp" : true,
		"ip_address" : "",
		"subnet" : "",
		"config" : null
	}, {
		"id" : 171,
		"name" : "wifi0",
		"connected" : true,
		"is_dhcp" : true,
		"ip_address" : "<IP_ADDRESS>",
		"subnet" : "255.255.255.0",
		"config" : {
			"network_name" : "<AP_NAME>",
			"interface" : "WifiType",
			"security_type" : "WPA2_Personal",
			"dhcp" : true,
			"enabled" : true
		}
	}, {
		"id" : 172,
		"name" : "wifi1",
		"connected" : true,
		"is_dhcp" : true,
		"ip_address" : "192.168.91.1",
		"subnet" : "255.255.255.0",
		"config" : null
	}
]

GET /api/system/networks
[{
		"network_name" : "default_gsm",
		"interface" : "GsmType",
		"security_type" : "NONE",
		"dhcp" : null
	}, {
		"network_name" : "default_eth",
		"interface" : "EthType",
		"security_type" : "NONE",
		"dhcp" : true
	}, {
		"network_name" : "<AP_NAME>",
		"interface" : "WifiType",
		"security_type" : "WPA2_Personal",
		"dhcp" : true,
		"enabled" : true
	}
]

GET /api/networks/wifi_security_types
["NONE","WEP","WPAorWPA2_Personal"]

POST /api/meters/ABC1234567890/verify
"Content-Type": "application/json"
request's body: {"short_id":"12345","serial":" ABC1234567890 "}

GET /api/meters/readings
{
	"ABC1234567890" : {
		"error" : "",
		"data" : {
			"IP" : "Neurio-12345",
			"sensorId" : "0x<EIGHT_BYTES_HERE_IN_HEX_FORMAT>",
			"firmwareVersion" : "Tesla-0.0.7",
			"f_Hz" : 60,
			"cts" : [{
					"ct" : 1,
					"v_V" : 120.1,
					"p_W" : 345.07,
					"q_VAR" : -179.66,
					"eExp_Ws" : 12601671,
					"eImp_Ws" : 579265920
				}, {
					"ct" : 2,
					"v_V" : 120.81,
					"p_W" : 68.48,
					"q_VAR" : -109.03,
					"eExp_Ws" : 76422454,
					"eImp_Ws" : 447595772
				}, {
					"ct" : 3,
					"v_V" : 120.88,
					"p_W" : -0.2,
					"q_VAR" : 0,
					"eExp_Ws" : 258718,
					"eImp_Ws" : 32548
				}, {
					"ct" : 4,
					"v_V" : 120.1,
					"p_W" : -0.06,
					"q_VAR" : -0.17,
					"eExp_Ws" : 112940,
					"eImp_Ws" : 88921
				}
			]
		}
	}
}

GET /api/system/testing
{
	"running" : false,
	"status" : "TestPassed",
	"charge_tests" : [0, -1000, -2000, -1000, 0],
	"meter_results" : [[{
				"Power" : 575.6900024414062,
				"CT" : 1,
				"Serial" : " ABC1234567890",
				"Type" : "site"
			}, {
				"Power" : 71.94999694824219,
				"CT" : 2,
				"Serial" : " ABC1234567890",
				"Type" : "site"
			}
		], [{
				"Power" : 595.2100219726562,
				"CT" : 1,
Vince Loschiavo's avatar
Vince Loschiavo committed
817
				"Serial" : " ABC1234890",
Vince Loschiavo's avatar
Vince Loschiavo committed
818
819
820
821
822
823
824
825
826
				"Type" : "site"
			}, {
				"Power" : 71.5199966430664,
				"CT" : 2,
				"Serial" : " ABC1234567890",
				"Type" : "site"
			}
		], [{
				"Power" : 1064.7099609375,
Vince Loschiavo's avatar
Vince Loschiavo committed
827
828
				"CT" : 1,
				"Serial" : " ABC1234567890",
Vince Loschiavo's avatar
Vince Loschiavo committed
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
				"Type" : "site"
			}, {
				"Power" : 540.1099853515625,
				"CT" : 2,
				"Serial" : " ABC1234567890",
				"Type" : "site"
			}
		], [{
				"Power" : 1283.739990234375,
				"CT" : 1,
				"Serial" : " ABC1234567890",
				"Type" : "site"
			}, {
				"Power" : 779.1300048828125,
				"CT" : 2,
				"Serial" : " ABC1234567890",
				"Type" : "site"
			}
		], [{
				"Power" : 562.5499877929688,
				"CT" : 1,
				"Serial" : " ABC1234567890",
				"Type" : "site"
			}, {
				"Power" : 69.66999816894531,
				"CT" : 2,
				"Serial" : " ABC1234567890",
				"Type" : "site"
			}
		]],
	"inverter_results" : null,
	"hysteresis" : 0.05,
	"error" : "",
	"errors" : null,
	"tests" : null
}
Vince Loschiavo's avatar
Vince Loschiavo committed
865
866
867

---