Powerwall 2 Gateway API Documentation

[vloschiavo]

Hello everyone.

I'm currently working on documenting the local gateway API for the Powerwall 2.

Additions, feedback, corrections are welcome!

vloschiavo/powerwall2

Additionally I'm interested in adding the API calls for Powerwall via the Owner's API to Tesla's servers (ala Tesla Model S JSON API · Apiary) - any information would be appreciated.

Thanks!
-Vince

 

[power.saver]

Thank you for starting this thread. The information in your GitHub is very useful.

I'm not versed in JSON and use an embedded controller to monitor my current system (no PW2 yet) to get information from the smart meter. I have a Rainforest Automation device that connects to the smart meter, and it has an API that uses HTTP POST requests to obtain data. My embedded system has a Ethernet connection to my LAN, and I am able to send simple text commands to get the data.

For example, to get the instantaneous demand, I send:

<LocalCommand>
<Name>get_instantaneous_demand</Name>
<MacID>0xd8d5b90000453b52</MacID>
</LocalCommand>

and in response, I get:

<InstantaneousDemand>
<DeviceMacId>0xd8d5b90000453b52</DeviceMacId>
<MeterMacId>0x00078100006aab7b</MeterMacId>
<TimeStamp>0x21dfec68</TimeStamp>
<Demand>0xffffffb3</Demand>
<Multiplier>0x00000001</Multiplier>
<Divisor>0x000003e8</Divisor>
<DigitsRight>0x03</DigitsRight>
<DigitsLeft>0x06</DigitsLeft>
<SuppressLeadingZero>Y</SuppressLeadingZero>
</InstantaneousDemand>

which I parse out to get the data I need.

Can you describe how the PW API commands look in plain text, or give me an example of what is actually sent and received on the API connection?

Any help would be much appreciated.

Sean

 

[liuping]

Thanks for the documentation.

Hopefully the new TOU hours will be adjustable in a similar way. That would give us the ability to adjust the flow pretty to just about anything we want/need (i.e all solar to grid+powerwall to cover house usage, solar to powerwall+house from grid, solar to cover house and charge, etc.)

 

[vloschiavo]

Thank you for starting this thread. The information in your GitHub is very useful.

I'm not versed in JSON and use an embedded controller to monitor my current system (no PW2 yet) to get information from the smart meter. I have a Rainforest Automation device that connects to the smart meter, and it has an API that uses HTTP POST requests to obtain data. My embedded system has a Ethernet connection to my LAN, and I am able to send simple text commands to get the data.

For example, to get the instantaneous demand, I send:


and in response, I get:


which I parse out to get the data I need.

Can you describe how the PW API commands look in plain text, or give me an example of what is actually sent and received on the API connection?

Any help would be much appreciated.

Sean

Sure, here's an example response from the Powerwall 2 gateway. This is similar to a hash (in perl) or a dictionary in Python. They are key-value pairs.
https://raw.githubusercontent.com/vloschiavo/powerwall2/master/samples/api_meters_aggregates.json

Cut and paste into a JSON parser like this: Json Parser Online to see a slightly more human readable format.

FYI - That Rainforest device that you are currently using is expecting XML and responding in XML.

 

[vloschiavo]

Thanks for the documentation.

Hopefully the new TOU hours will be adjustable in a similar way. That would give us the ability to adjust the flow pretty to just about anything we want/need (i.e all solar to grid+powerwall to cover house usage, solar to powerwall+house from grid, solar to cover house and charge, etc.)

Agree! If anyone here has TOU enabled, please reach out to me via private message so we can get that documented.

 

[power.saver]

Sure, here's an example response from the Powerwall 2 gateway. This is similar to a hash (in perl) or a dictionary in Python. They are key-value pairs.
https://raw.githubusercontent.com/vloschiavo/powerwall2/master/samples/api_meters_aggregates.json

Cut and paste into a JSON parser like this: Json Parser Online to see a slightly more human readable format.

FYI - That Rainforest device that you are currently using is expecting XML and responding in XML.

Yes, I saw that in your GitHub repository. I can easily parse that string.

The Rainforest is using XML fragments, so I guess I am wondering if the API calls to the PW2 are similar? In other words, what did the query look like that produced that response?

Thanks.

 

[vloschiavo]

Yes, I saw that in your GitHub repository. I can easily parse that string.

The Rainforest is using XML fragments, so I guess I am wondering if the API calls to the PW2 are similar? In other words, what did the query look like that produced that response?

Thanks.

Ah! I see...For that particular request, you don't have to supply any data. You can hit this URL http://192.168.xxx.xxx/api/meters/aggregates with a wget, curl, or simply your web browser. (replace the IP with the IP of your gateway).

 

[power.saver]

Thanks! As soon as my gateway is installed, I'll give that a try.

 

[vloschiavo]

Yes, I saw that in your GitHub repository. I can easily parse that string.

The Rainforest is using XML fragments, so I guess I am wondering if the API calls to the PW2 are similar? In other words, what did the query look like that produced that response?

Thanks.

-Typically you are only posting data to the gateway when you want to change a setting.
-Otherwise you are doing a http get to a specific/unique URL without sending any data.

There are a few requests where you need to post data: authentication for example. Here you need to send data in a header.

Here's an example using curl.

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"

In this request, we are doing an HTTP POST with the application/json header and the stuff in curly brackets {} as the data.

The response would look something like this:
{"email":null,"firstname":"Tesla","lastname":"Energy","roles":["Provider_Engineer"],"token":"OgiGHjoNvwx17SRIaYFIOWPJSaKBYwmMGc5K4tTz57EziltPYsdtjU_DJ08tJqaWbWjTuI3fa_8QW32ED5zg1A==","provider":"Basic"}

 

[power.saver]

Thank you again for the additional info, and curl link. I've got the manual and will give this a try soon...

 

[Cottonwood]

Tesla Energy just completed installation of a Gateway and two PowerWall 2's in my house yesterday. I still do not have access to them on my Tesla App. I tried calling the Tesla Hotline number, 669-243-4032, but cannot get through to a Person of Intelligence. A Solar person took my info and said a PowerWall person will call back.

I looked up the Gateway IP address in the DHCP lease table on my local router, and was able to get to the local Web Page from the gateway yesterday. Today, I tried again, and get no response from the Gateway. Interestingly, there are two DHCP entries for the Gateway. I tried both. See router screenshot below. The MAC addresses and the Hostnames (based on Serial Number) are the same in each entry.

Any help or advice would be appreciated. Does anyone know why I can't get to the local Gateway web page today, but could yesterday?

 

[miimura]

Can you see the internal WiFi TEG... SSID?

 

[Cottonwood]

Can you see the internal WiFi TEG... SSID?

Yes, I can see the Gateway SSID. Do you know what the Gateway WiFi password is, or how to calculate it from the TSN?

 

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

 

[cwied]

Tesla Energy just completed installation of a Gateway and two PowerWall 2's in my house yesterday. I still do not have access to them on my Tesla App. I tried calling the Tesla Hotline number, 669-243-4032, but cannot get through to a Person of Intelligence. A Solar person took my info and said a PowerWall person will call back.

I was referred to this page to get the powerwall to show up in the app: Powerwall Self Registration | Tesla

After I registered it, it showed up in the app after a few minutes.

 

[Cottonwood]

I was referred to this page to get the powerwall to show up in the app: Powerwall Self Registration | Tesla

After I registered it, it showed up in the app after a few minutes.

I filled out that form and my PowerWall Display appeared on the App in about 15 minutes. I went through the same screens on the installer's Droid Phone yesterday, and probably screwed something up on the little screen. If he had just e-mailed me the link, that would have helped.

Thanks!


One of the IP addresses seems to have expired in the DHCP lease list, but I still can't open the gateway local web page. I showed the installer that I was looking at the local page. Could he have disabled the local web view?

 

[vloschiavo]

One of the IP addresses seems to have expired in the DHCP lease list, but I still can't open the gateway local web page. I showed the installer that I was looking at the local page. Could he have disabled the local web view?

You could try a few things.
1) I assume that your gateway is connected over WiFi. If that's correct, try connecting it to your network via an ethernet cable. I realize logistics may be difficult. You could setup a laptop with a DHCP server and connect your laptop's ethernet directly to the gateway. A ethernet cross-over cable may be necessary if your nic doesn't automatically cross-over.

2) You could try to restart the gateway- that will force it to DHCP again.
My gateway has a cellular connection too that it can use in a fall-back scenario...that may be what's happen to your gateway.

 

[Cottonwood]

You could try a few things.
1) I assume that your gateway is connected over WiFi. If that's correct, try connecting it to your network via an ethernet cable. I realize logistics may be difficult. You could setup a laptop with a DHCP server and connect your laptop's ethernet directly to the gateway. A ethernet cross-over cable may be necessary if your nic doesn't automatically cross-over.

2) You could try to restart the gateway- that will force it to DHCP again.
My gateway has a cellular connection too that it can use in a fall-back scenario...that may be what's happen to your gateway.

1. My Gateway is connected via a hardware ethernet cable to an ethernet switch in the basement.
2. I tried to reset the Gateway with its "reset" button. The status lights stopped blinking and went out while I held the reset button down. After about 15 seconds, I let the reset button up and the lights came back on and started their blinking again. After the reset, I can still see the Powerwall on the App, but nothing in the DHCP Lease table. Maybe, I will try a hard, power-down reset later.
3. Could the Gateway still be communicating on cellular? The cellular coverage where the PowerWalls and Gateway are in the basement, is really bad. In addition, in case of the Zombie Apocalypse, I would like to have standalone survivability (assume no cellular or internet connectivity) and be able to view system status locally on my LAN.
4. I am looking at some "off-grid" systems in the future. Using these API's to get battery state, etc, will be essential to doing effective control of non-critical, but useful loads like water heaters and irrigation pumps. Getting to the Gateway on the LAN is necessary to use these API's...

 

[cwied]

When my Powerwalls were installed, they left the gateway plugged in to the ethernet cable, but did not set it up to actually use the Ethernet. The steps I used were the following:
1. Connect to the gateway's wifi SSID using password "S" + gateway serial ("STG...").
2. Run setup wizard on http://192.168.89.1 (I think that's the right subnet - check what you're connected to)- installer email doesn't matter, password as above.
3. In network section, turn on Ethernet.
4. Run through rest of setup wizard without changing anything.

After I did this, the gateway was on the Ethernet and I was able to connect to it using the address it retrieved over DHCP. I added the address to the static IP table on my DHCP server after I discovered that it grabbed a different one after a software update.

 

[dlieu]

2. Run setup wizard on http://192.168.89.1 (I think that's the right subnet - check what you're connected to)- installer email doesn't matter, password as above.

on mine it is 192.168.91.1