Code by Scott שאול בן ישוע
README.md 25.7 KB
Newer Older
1
======
Vince Loschiavo's avatar
Vince Loschiavo committed
2
Tesla Powerwall 2 - Local Gateway API documentation
Vince Loschiavo's avatar
Vince Loschiavo committed
3
4
======

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
5
This is a list of api URLs all from  reverse engineer from the local gateway.  This is not the [Tesla Owner API] which you can find here: (https://tesla-api.timdorr.com) with a Python library that works nicely to control a Powerwall 2 here: (https://github.com/mlowijs/tesla_api), which is actively being developed here: (https://github.com/swm11/tesla_api).
gpeszek's avatar
gpeszek committed
6

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
7
8
9
10
Hubitat Elevation Hub (Home Automation)
---
The driver located under [Hubitat/driver](https://gitlab.borgnet.us:8443/sgrayban/powerwall2/-/tree/master/Hubitat) is not open for public use but works for all Tesla Powerwall II systems.

Vince Loschiavo's avatar
Vince Loschiavo committed
11
Powerwall 2 Web UI
Vince Loschiavo's avatar
Vince Loschiavo committed
12
---
Vince Loschiavo's avatar
Vince Loschiavo committed
13
The web UI provides ~~an instantaneous~~ a 250-500ms average(?) power flow diagram an access to the wizard.
Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
14
Hit your local gateway IP with a browser, i.e. _https://POWERWALL-IP/
Vince Loschiavo's avatar
Vince Loschiavo committed
15
16
17

You should see something like this:

18
![GatewayUI](https://gitlab.borgnet.us:8443/sgrayban/powerwall2/-/raw/master/img/TeslaPowerwallGatewayUI.jpg "Gateway Web UI")
Vince Loschiavo's avatar
Vince Loschiavo committed
19
20

---
Vince Loschiavo's avatar
Vince Loschiavo committed
21
**Wizard**
22
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
23

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

26
27
`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
28

Vince Loschiavo's avatar
Vince Loschiavo committed
29

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

**Meters / Power output stats**
34
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
35

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

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
38
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/meters/aggregates`
Vince Loschiavo's avatar
Vince Loschiavo committed
39

40
response: [see sample response here](https://gitlab.borgnet.us:8443/sgrayban/powerwall2/-/raw/master/samples/api_meters_aggregates.json
Vince Loschiavo's avatar
Vince Loschiavo committed
41
42
43
)

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
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
60
61
When site master or the Powerwalls are off, the response is: HTTP Status 502

vls29's avatar
vls29 committed
62
63
64
65
_GET /api/meters/site_

Detailed information about the site specific meter.

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
66
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/meters/site`
vls29's avatar
vls29 committed
67

68
response: [see sample response here](https://gitlab.borgnet.us:8443/sgrayban/powerwall2/-/raw/master/samples/api-meters-site.json)
vls29's avatar
vls29 committed
69
70
71
72
73

_GET /api/meters/solar_

Detailed information about the solar specific meter.

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
74
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/meters/solar`
vls29's avatar
vls29 committed
75

76
response: [see sample response here](https://gitlab.borgnet.us:8443/sgrayban/powerwall2/-/raw/master/samples/api-meters-solar.json)
vls29's avatar
vls29 committed
77
78


Vince Loschiavo's avatar
Vince Loschiavo committed
79
80
---
**State of Charge / State of Energy**
Vince Loschiavo's avatar
Vince Loschiavo committed
81
_GET /api/system_status/soe_
Vince Loschiavo's avatar
Vince Loschiavo committed
82
83

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

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
85
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/system_status/soe`
Vince Loschiavo's avatar
Vince Loschiavo committed
86

Vince Loschiavo's avatar
Vince Loschiavo committed
87
88
response:	`{"percentage":69.1675560298826}`

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

Vince Loschiavo's avatar
Vince Loschiavo committed
91
92
---

Vince Loschiavo's avatar
Vince Loschiavo committed
93
94
95
96
97
_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
98

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
99
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/sitemaster`
Vince Loschiavo's avatar
Vince Loschiavo committed
100

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

Vince Loschiavo's avatar
Vince Loschiavo committed
103
104
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
105
106
---

Vince Loschiavo's avatar
Vince Loschiavo committed
107
108
_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
109

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
110
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/powerwalls`
Vince Loschiavo's avatar
Vince Loschiavo committed
111

112
response:	[see sample response here](https://gitlab.borgnet.us:8443/sgrayban/powerwall2/-/raw/master/samples/api-powerwalls.json)
Vince Loschiavo's avatar
Vince Loschiavo committed
113
114
115

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
116
117
118

---

Vince Loschiavo's avatar
Vince Loschiavo committed
119
120
_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
121

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
122
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/customer/registration`
Vince Loschiavo's avatar
Vince Loschiavo committed
123

124
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
125
126
127

---

Vince Loschiavo's avatar
Vince Loschiavo committed
128
129
130
_GET /api/system_status/grid_status_
Determine if the Grid is up or down.

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
131
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/system_status/grid_status`
Vince Loschiavo's avatar
Vince Loschiavo committed
132

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

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

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

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

Vince Loschiavo's avatar
Vince Loschiavo committed
141
---
Vince Loschiavo's avatar
Vince Loschiavo committed
142
_GET /api/system/update/status_
143
_UPDATE: You need to be authenticated for this command_
144
145
146
147
148
149
150
151
152
153
154

From: @kylerove:
"After digging, the answer was right on Tesla's website:
https://www.tesla.com/support/energy/powerwall/own/monitoring-from-home-network

username=customer
email=your Tesla account email address
password=last 5 digits of your gateway serial number

You can then reset/choose your own customer password, if you want to make it stronger."

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
155
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/system/update/status`
Vince Loschiavo's avatar
Vince Loschiavo committed
156

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

Vince Loschiavo's avatar
Vince Loschiavo committed
159
160
161
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
162
	
Vince Loschiavo's avatar
Vince Loschiavo committed
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
	  
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
209
---	
Vince Loschiavo's avatar
Vince Loschiavo committed
210
_GET /api/site_info_
Vince Loschiavo's avatar
Vince Loschiavo committed
211

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
212
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/site_info`
Vince Loschiavo's avatar
Vince Loschiavo committed
213

214
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
215
216
217

---

Vince Loschiavo's avatar
Vince Loschiavo committed
218
_GET /api/site_info/site_name_
Vince Loschiavo's avatar
Vince Loschiavo committed
219

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
220
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/site_info/site_name`
Vince Loschiavo's avatar
Vince Loschiavo committed
221

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

224
225
The site_name value can be changed from the Tesla Mobile app settings.

Vince Loschiavo's avatar
Vince Loschiavo committed
226
---
Vince Loschiavo's avatar
Vince Loschiavo committed
227
_GET /api/status_
Vince Loschiavo's avatar
Vince Loschiavo committed
228

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
229
request: `curl --cacert cacert.pem https://POWERWALL-IP/api/status`
Vince Loschiavo's avatar
Vince Loschiavo committed
230

231
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
232

233
Useful here: Gateway Version:  "version":"1.40.2\n"
Vince Loschiavo's avatar
Vince Loschiavo committed
234
235
236

---

Vince Loschiavo's avatar
Vince Loschiavo committed
237
238
239
_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).
240
_This is untested. Question for the community: Does this still work? Soliciting for pull requests! :)_
Vince Loschiavo's avatar
Vince Loschiavo committed
241

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
242
Request: `curl --cacert cacert.pem -i https://POWERWALL-IP/api/logout`
Vince Loschiavo's avatar
Vince Loschiavo committed
243

244
245
Response: `HTTP/2 204 
date: Thu, 03 Oct 2019 13:48:10 GMT`
Vince Loschiavo's avatar
Vince Loschiavo committed
246

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

Vince Loschiavo's avatar
Vince Loschiavo committed
249
---
Vince Loschiavo's avatar
Vince Loschiavo committed
250
251
252
253
_GET /api/system_status/grid_faults_

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

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
254
Request: `curl --cacert cacert.pem https://POWERWALL-IP/api/system_status/grid_faults`
Vince Loschiavo's avatar
Vince Loschiavo committed
255

256
Response: `[{"timestamp":1569976192352,"alert_name":"PINV_a006_vfCheckUnderFrequency","alert_is_fault":false,"decoded_alert":"[{\"name\":\"PINV_alertID\",\"value\":\"PINV_a006_vfCheckUnderFrequency\"},{\"name\":\"PINV_alertType\",\"value\":\"Warning\"},{\"name\":\"PINV_a006_frequency\",\"value\":57.207,\"units\":\"Hz\"}]","alert_raw":432406325129904128,"git_hash":"14f7c1769ec307","site_uid":"xxxx","ecu_type":"TEPINV","ecu_package_part_number":"xxxxx","ecu_package_serial_number":"xxxxxx"}]`
Vince Loschiavo's avatar
Vince Loschiavo committed
257
258

---
Vince Loschiavo's avatar
Vince Loschiavo committed
259
_GET /api/sitemaster/stop_
260
_UPDATE: You need to be authenticated for this command_
Vince Loschiavo's avatar
Vince Loschiavo committed
261
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
262

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
263
Request: `curl --cacert cacert.pem https://POWERWALL-IP/api/sitemaster/stop`
Vince Loschiavo's avatar
Vince Loschiavo committed
264

Vince Loschiavo's avatar
Vince Loschiavo committed
265
Response:  
Vince Loschiavo's avatar
Vince Loschiavo committed
266

Vince Loschiavo's avatar
Vince Loschiavo committed
267
268
269
270
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
271
---
Vince Loschiavo's avatar
Vince Loschiavo committed
272
_GET /api/sitemaster/run_
273
_UPDATE: You need to be authenticated for this command_
Vince Loschiavo's avatar
Vince Loschiavo committed
274
This starts the powerwalls & gateway.  Use this after getting an authentication token to restart the powerwalls.
Vince Loschiavo's avatar
Vince Loschiavo committed
275

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
276
Request: `curl --cacert cacert.pem https://POWERWALL-IP/api/sitemaster/run`
Vince Loschiavo's avatar
Vince Loschiavo committed
277

Vince Loschiavo's avatar
Vince Loschiavo committed
278
Response:  
Vince Loschiavo's avatar
Vince Loschiavo committed
279
280
Returns HTTPS Status 202 if request is accepted

Vince Loschiavo's avatar
Vince Loschiavo committed
281
282
283

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

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
287
Request: `curl --cacert cacert.pem https://POWERWALL-IP/api/config/completed`
Vince Loschiavo's avatar
Vince Loschiavo committed
288

Vince Loschiavo's avatar
Vince Loschiavo committed
289
Response:
Vince Loschiavo's avatar
Vince Loschiavo committed
290
291
Returns HTTP Status 202 if input accepted

Vince Loschiavo's avatar
Vince Loschiavo committed
292
293

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

296
297
298
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
299
300

**Login**
Vince Loschiavo's avatar
Vince Loschiavo committed
301
_POST /api/login/Basic_
Vince Loschiavo's avatar
Vince Loschiavo committed
302

303
304
Note: _This section needs updating: Does this work?_

Vince Loschiavo's avatar
Vince Loschiavo committed
305
**Authentication example:**
306
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
307
308
309
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
310

Vince Loschiavo's avatar
Vince Loschiavo committed
311
Request: 
Vince Loschiavo's avatar
Vince Loschiavo committed
312

Sha'ul ben Yeshua's avatar
Sha'ul ben Yeshua committed
313
`curl --cacert cacert.pem -s -i -X POST -H "Content-Type: application/json" -d '{"username":"","password":"ST123456789","force_sm_off":false}' https://POWERWALL-IP/api/login/Basic`
Vince Loschiavo's avatar
Vince Loschiavo committed
314
315
316
317

Response: 

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

Vince Loschiavo's avatar
Vince Loschiavo committed
319
Save the token for use with the below calls.
Vince Loschiavo's avatar
Vince Loschiavo committed
320

Vince Loschiavo's avatar
Vince Loschiavo committed
321
322
323
324
325
326
**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
327
328
Windows Example Request: 

gpeszek's avatar
gpeszek committed
329
`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
330
331


Vince Loschiavo's avatar
Vince Loschiavo committed
332
---
Vince Loschiavo's avatar
Vince Loschiavo committed
333
_GET & POST /api/operation_
Vince Loschiavo's avatar
Vince Loschiavo committed
334
Change the Powerwall mode and Reserve Percentage
Vince Loschiavo's avatar
Vince Loschiavo committed
335
336
337
338
339
340
341

_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
342
343
344

_GET_

gpeszek's avatar
gpeszek committed
345
request: `curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/operation`
Vince Loschiavo's avatar
Vince Loschiavo committed
346
347
348
349
350
351

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


_POST_

Vince Loschiavo's avatar
Vince Loschiavo committed
352
353
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
354
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
355

Vince Loschiavo's avatar
Vince Loschiavo committed
356
response: `{"mode":"self_consumption","backup_reserve_percent":24.6}`
Vince Loschiavo's avatar
Vince Loschiavo committed
357
358
359
360

Valid Modes:
1. `self_consumption`
2. `backup`
Vince Loschiavo's avatar
Vince Loschiavo committed
361
362
363
364
365
366
367
368
369
370
371
372
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
373

Vince Loschiavo's avatar
Vince Loschiavo committed
374
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
375
376
377
378
379

`{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
380
___**Tested values:**___
Vince Loschiavo's avatar
Vince Loschiavo committed
381

Vince Loschiavo's avatar
Vince Loschiavo committed
382
383
384
385
386
387
388
389
390
| 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
391

Vince Loschiavo's avatar
Vince Loschiavo committed
392

Vince Loschiavo's avatar
Vince Loschiavo committed
393
394
---

Vince Loschiavo's avatar
Vince Loschiavo committed
395
_GET /api/powerwalls/status_
Vince Loschiavo's avatar
Vince Loschiavo committed
396

Vince Loschiavo's avatar
Vince Loschiavo committed
397
Informational:
Vince Loschiavo's avatar
Vince Loschiavo committed
398

Vince Loschiavo's avatar
Vince Loschiavo committed
399
400
Request:

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

Response:
Vince Loschiavo's avatar
Vince Loschiavo committed
404

Vince Loschiavo's avatar
Vince Loschiavo committed
405
406
407
408
409
410
411
412
`{"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
413
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/site_info/grid_codes`
Vince Loschiavo's avatar
Vince Loschiavo committed
414
415
416

Response: 

417
[ Grid Codes Long JSON response here](https://gitlab.borgnet.us:8443/sgrayban/powerwall2/-/raw/master/samples/api_site_info_grid_codes.json)
Vince Loschiavo's avatar
Vince Loschiavo committed
418
419
420
421

---

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

Vince Loschiavo's avatar
Vince Loschiavo committed
423
424
425
426
Informational: responds with the solar inverter brand, model, and max power rating as stored on the gateway.

Request:

gpeszek's avatar
gpeszek committed
427
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/solars`
Vince Loschiavo's avatar
Vince Loschiavo committed
428
429
430
431
432
433
434
435

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
436

Vince Loschiavo's avatar
Vince Loschiavo committed
437
438
439
440
Informational: responds with the Solar inverter Brand options for the wizard.

Request:

gpeszek's avatar
gpeszek committed
441
`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
442

443
[ Solar Brands - Long JSON response here](https://gitlab.borgnet.us:8443/sgrayban/powerwall2/-/raw/master/samples/api_solars_brands.json)
Vince Loschiavo's avatar
Vince Loschiavo committed
444
445
446

---

Vince Loschiavo's avatar
Vince Loschiavo committed
447
448
449
450
451
452
453

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

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

Request:

gpeszek's avatar
gpeszek committed
454
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/solars/brands/SolarEdge%20Technologies`
Vince Loschiavo's avatar
Vince Loschiavo committed
455
456
457

Response

458
[ SolarEdge Models - Long JSON response here](https://gitlab.borgnet.us:8443/sgrayban/powerwall2/-/raw/master/samples/solar_edge_models.json)
Vince Loschiavo's avatar
Vince Loschiavo committed
459
460
461

---

Vince Loschiavo's avatar
Vince Loschiavo committed
462
463
464
465
466
467
_GET /api/generators_

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

Request:

gpeszek's avatar
gpeszek committed
468
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" httsp://192.168.xxx.xxx/api/generators`
Vince Loschiavo's avatar
Vince Loschiavo committed
469
470
471
472
473
474
475
476

Response:

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

---


Vince Loschiavo's avatar
Vince Loschiavo committed
477
478
479
480
481
482
_GET /api/customer_

Informational:

Request: 

gpeszek's avatar
gpeszek committed
483
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/customer`
Vince Loschiavo's avatar
Vince Loschiavo committed
484
485
486
487

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
488
489
490
491

---


Vince Loschiavo's avatar
Vince Loschiavo committed
492
_GET /api/config_
Vince Loschiavo's avatar
Vince Loschiavo committed
493

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

Vince Loschiavo's avatar
Vince Loschiavo committed
496
Request:
Vince Loschiavo's avatar
Vince Loschiavo committed
497

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

Vince Loschiavo's avatar
Vince Loschiavo committed
500
Response:
Vince Loschiavo's avatar
Vince Loschiavo committed
501

Vince Loschiavo's avatar
Vince Loschiavo committed
502
503
504
505
506
507
508
509
510
511
`{vin: "0123456-00-E--T1234567890"}`


---
__Others to be documented:__

_GET /api/generators/disconnect_types_

Request:

gpeszek's avatar
gpeszek committed
512
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/generators/disconnect_types`
Vince Loschiavo's avatar
Vince Loschiavo committed
513
514
515
516
517
518
519
520
521
522
523
524


Response:

`["DownstreamATS"]`

---

_GET /api/meters_

Request: 

gpeszek's avatar
gpeszek committed
525
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/meters`
Vince Loschiavo's avatar
Vince Loschiavo committed
526
527
528
529
530
531
532
533
534
535
536
537
538
539

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
540
`curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" https://192.168.xxx.xxx/api/installer`
Vince Loschiavo's avatar
Vince Loschiavo committed
541
542
543
544

Response:

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

Vince Loschiavo's avatar
Vince Loschiavo committed
546
547
548
549
Alternative Response:
`{"company":"Tesla Orange County","customer_id":"1234567","phone":"1231234567","email":"...","run_sitemaster":true}`


Vince Loschiavo's avatar
Vince Loschiavo committed
550

Vince Loschiavo's avatar
Vince Loschiavo committed
551

Vince Loschiavo's avatar
Vince Loschiavo committed
552
553
---

Vince Loschiavo's avatar
Vince Loschiavo committed
554
__Others to document__
Vince Loschiavo's avatar
Vince Loschiavo committed
555

Vince Loschiavo's avatar
Vince Loschiavo committed
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
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
582
583
584
}

POST /api/networks/<...>/disable
Vince Loschiavo's avatar
Vince Loschiavo committed
585
586
587
588
589
590
591
592
593
594
595
596
597
598
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
599
		"Gle GET Test" : {
Vince Loschiavo's avatar
Vince Loschiavo committed
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
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
			"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
783
				"Serial" : " ABC1234890",
Vince Loschiavo's avatar
Vince Loschiavo committed
784
785
786
787
788
789
790
791
792
				"Type" : "site"
			}, {
				"Power" : 71.5199966430664,
				"CT" : 2,
				"Serial" : " ABC1234567890",
				"Type" : "site"
			}
		], [{
				"Power" : 1064.7099609375,
Vince Loschiavo's avatar
Vince Loschiavo committed
793
794
				"CT" : 1,
				"Serial" : " ABC1234567890",
Vince Loschiavo's avatar
Vince Loschiavo committed
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
				"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
831
832
833

---