(Based on firmware version 1.15.0)
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).
The web UI provides an instantaneous a 250-500ms average(?) power flow diagram an access to the wizard.
Hit your local gateway IP with a browser, i.e. _http://192.168.xxx.xxx/
You should see something like this:
Wizard You can hit the "Run Wizard" button here and go through the setup (be careful what you change in the wizard).
username: <leave this blank as it's ignored (and/or logged)>
password: S + <gateway serial number>
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:
Original image taken from www.tesla.com here
Meters / Power output stats Calling the below URLs does not require authentication. Each will return JSON output with key-value pairs.
GET /api/meters/aggregates
request: curl http://192.168.xxx.xxx/api/meters/aggregates
response: see sample response here
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.
- "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
- "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
- "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
- "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.
- "busway" - Unknown - my numbers show 0 for this.
- "frequency" - Unknown - my numbers show 0 for this.
- "generator" - Unknown I don't have a generator - my numbers show 0 for this.
When site master or the Powerwalls are off, the response is: HTTP Status 502
GET /api/meters/site
Detailed information about the site specific meter.
request: curl http://192.168.xxx.xxx/api/meters/site
response: see sample response here
GET /api/meters/solar
Detailed information about the solar specific meter.
request: curl http://192.168.xxx.xxx/api/meters/solar
response: see sample response here
State of Charge / State of Energy GET /api/system_status/soe
This returns the aggregate charge state in percent of the powerwall(s).
request: curl http://192.168.xxx.xxx/api/system_status/soe
response: {"percentage":69.1675560298826}
When site master or the Powerwalls are off, the response is: HTTP Status 502
GET /api/sitemaster Use this URL to determine:
- Powerwall state {running|stopped}
- How long the powerwall has been set to the running state {in seconds}
- Is the powerwall gateway connected to Tesla's servers {true|false}}
request: curl http://192.168.xxx.xxx/api/sitemaster
response: {"running":true,"uptime":"166594s,","connected_to_tesla":true}
When site master or the Powerwalls are off, the response is: {"running":false,"uptime":"log:","connected_to_tesla":false}
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).
request: curl http://192.168.xxx.xxx/api/powerwalls
response: {"powerwalls":[{"PackagePartNumber":"1092170-03-E","PackageSerialNumber":"T1234567890"},{"PackagePartNumber":"1092170-03-E","PackageSerialNumber":"T1234567891"}],"has_sync":true}
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)
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.
request: curl http://192.168.xxx.xxx/api/customer/registration
response: {"privacy_notice":true,"limited_warranty":true,"grid_services":null,"marketing":null,"registered":true,"emailed_registration":true,"skipped_registration":false,"timed_out_registration":false}
GET /api/system_status/grid_status Determine if the Grid is up or down.
request: curl http://192.168.xxx.xxx/api/system_status/grid_status
response:
{"grid_status":"SystemGridConnected"} = grid is up
{"grid_status":"SystemIslandedActive"} = grid is down
{"grid_status":"SystemTransitionToGrid"} = grid is restored but not yet in sync.
GET /api/system/update/status
request: curl http://192.168.xxx.xxx/api/system/update/status
response: {"state":"/update_failed","info":{"status":["nonactionable"]},"current_time":1422697552910}
- update_failed / status nonactionable = I tried to do an upgrade but I have the latest firmware version already installed.
- current_time in EPOC. -1422697552910 = GMT: Monday, April 2, 2018 8:09:17.447 PM
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
GET /api/site_info
request: curl http://192.168.xxx.xxx/api/site_info
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"}
GET /api/site_info/site_name
request: curl http://192.168.xxx.xxx/api/site_info/site_name
response: {"site_name":"Home Energy Gateway","timezone":"America/Los_Angeles"}
GET /api/status
request: curl http://192.168.xxx.xxx/api/status
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"
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).
Request: curl -i 192.168.xxx.xxx/api/logout
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
returns HTTP Status 204, no content, if request is accepted
GET /api/system_status/grid_faults
Not sure what this does...does it list the recent grid failure dates/times?
Request: curl 192.168.xxx.xxx/api/system_status/grid_faults
Response: []
GET /api/sitemaster/stop
This stops the powerwalls & gateway. In the stopped state, the powerwall will not charge, discharge, or monitor solar, grid, battery, home statistics.
Request: curl http://192.168.xxx.xxx/api/sitemaster/stop
Response:
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"}
GET /api/sitemaster/run
This starts the powerwalls & gateway. Use this after getting an authentication token to restart the powerwalls.
Request: curl http://192.168.xxx.xxx/api/sitemaster/run
Response:
Returns HTTPS Status 202 if request is accepted
GET /api/config/completed
This applies configuration changes.
This is a GET request and doesn't require an authentication token.
Request: curl /api/config/completed
Response: Returns HTTP Status 202 if input accepted
Note: *** The below API calls require authentication ***
Login POST /api/login/Basic
Authentication example:
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.
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
Response:
{"email":null,"firstname":"Tesla","lastname":"Energy","roles":["Provider_Engineer"],"token":"OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==","provider":"Basic"}
Save the token for use with the below calls.
Note for Windows users: Windows shell handles quotes differently than linux Bash. In windows, the above example works by:
- changing the single quotes to double quotes
- escape the double quotes inside the -d section
Windows Example 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
GET & POST /api/operation Change the Powerwall mode and Reserve Percentage
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.
GET
request: curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/operation
response: {"mode":"self_consumption","backup_reserve_percent":15}
POST
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":24.6}' http://192.168.xxx.xxx/api/operation
response: {"mode":"self_consumption","backup_reserve_percent":24.6}
Valid Modes:
self_consumptionbackupautonomous(aka Time of Use (TOU) as reported by dlieu on the teslamotorsclub.com forums)scheduleraka 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"}
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.
{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:
| APP Setting | API Setting |
|---|---|
| 5% | 10% |
| 16% | 20% |
| 16% | 20.6% |
| 20% | 24% |
| 21% | 24.6% |
| 30% | 33% |
| 100% | 100% |
GET /api/powerwalls/status
Informational:
Request:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/powerwalls/status
Response:
{"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:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/site_info/grid_codes
Response:
Grid Codes Long JSON response here
GET /api/solars
Informational: responds with the solar inverter brand, model, and max power rating as stored on the gateway.
Request:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/solars
Reply:
[{"brand":"SolarEdge Technologies","model":"SE5000 (240V) w/ -ER-US or A-US","power_rating_watts":6000}]
GET /api/solars/brands
Informational: responds with the Solar inverter Brand options for the wizard.
Request:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/solars/brands > api_solars_brands.json
Solar Brands - Long JSON response here
GET /api/solars/brands/SolarEdge%20Technologies
Informational: Get a list of SolarEdge models - used in the wizard.
Request:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/solars/brands/SolarEdge%20Technologies
Response
SolarEdge Models - Long JSON response here
GET /api/generators
Note: I don't have a generator tied to my system.
Request:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/generators
Response:
{"disconnect_type":"None","generators":[]}
GET /api/customer
Informational:
Request:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/customer
Response:
{"city":"New York","state":"New York ","zip":"10010","country":"US","registered":true,"privacy_notice":true,"limited_warranty":true,"emailed_registration":true}
GET /api/config
Informational - I'm not sure what this is...
Request:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/config
Response:
{vin: "0123456-00-E--T1234567890"}
Others to be documented:
GET /api/generators/disconnect_types
Request:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/generators/disconnect_types
Response:
["DownstreamATS"]
GET /api/meters
Request:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/meters
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:
curl --header "Authorization: Bearer OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==" http://192.168.xxx.xxx/api/installer
Response:
{company: "Tesla Timbuktu", customer_id: "01234567", phone: "8885551212"}
Alternative Response:
{"company":"Tesla Orange County","customer_id":"1234567","phone":"1231234567","email":"...","run_sitemaster":true}
Others to document
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: ??? }
POST /api/networks/<...>/disable 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" : "" }, "Google GET Test" : { "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, "Serial" : " ABC1234567890", "Type" : "site" }, { "Power" : 71.5199966430664, "CT" : 2, "Serial" : " ABC1234567890", "Type" : "site" } ], [{ "Power" : 1064.7099609375, "CT" : 1, "Serial" : " ABC1234567890", "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 }
dlieu: "i've decoded and have been using most of the api and decode to the degree Wizard does and wrote CLI to control PW2 pre-TBC. i can show all the status the gateway web ui does, and switch between various operations and reserves.
One important thing to add is that api/operation is not only POST but also GET which reports about the same thing. The reserve is actually double (not just int), so one can put reserve at say 66.6%.
In time based control the mode = "autonomous". It is coming from GET however the api to configure autonomous via POST produces 50x -- most likely the configuration api for autonomous is significantly expanded and it is not possible to infer via wizard alone since wizard does not attempt to configure it. And i am too lazy to investigate gateway traffic sniffing beyond the wizard itself. I am interested to find out the spec for autonomous (aka TBC) configuration. but since standard TBC works for my needs, i guess i am not too eager to dig myself."