Tesla Powerwall 2 - Local Gateway API documentation

Contributing

(This documentation is currently in flux: portions are updated and portions aren't updated. Use at your own risk)

(If you find issues, please submit pull requests - currently testing on firmware version 20.49.0)

*** Please be patient as I have an unrelated day job! ***

Please help me update this: Pull requests are welcome!

Overview

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://tesla-api.timdorr.com) with a Python library that works nicely to control a Powerwall 2 here: (https://github.com/mlowijs/tesla_api).

Libraries / apps using this API

The following projects are known to be using portions of this API, and may be useful for those looking to interact with Powerwall devices:

• tesla_powerwall client library for Python
• go-powerwall client library for Go
• Powerwall exporter for Prometheus (uses the go-powerwall library)
• powerwall-to-pvoutput-uploader sends solar panel and battery data from the Powerwall to pvoutput.org

Getting Started

A note about HTTPS and SSL Certificates

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.

You have three ways around a certificate error:

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.

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.

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.

I recommend option 3 above.

In addition to the issues of validating the certificate itself, the Powerwall gateway also apparently uses SNI when serving the TLS certificate, and will simply abort the connection if the wrong hostname is presented via SNI when establishing the TLS connection. It can therefore only be accessed using a few set hostnames (and if you put its IP address in your local DNS or hosts file with a different name, it will likely not work).

Hostnames which are known to work to access a Powerwall:

• (IP address)
• teg
• powerwall
• powerpack

Note that none of these names have any domain component. That means you must access the Powerwall as, for example, https://powerwall/. Something like https://powerwall.mycooldomain.net/ will not work (even if mycooldomain.net is configured to have the necessary DNS entry).

If you want to access your Powerwall using a name other than one of the above, you will likely need to do some custom hacking with your client's HTTPS/TLS settings to provide one of these names via SNI instead of the actual hostname (note that not all clients support this).

Here's what worked for me:

Step 1: DNS

Enable DNS lookups, on your local network, for one of the hostnames listed above (for example, powerwall) pointing to the device's IP address.

You can add this to your local DNS server as an A Record or /etc/hosts file or other DNS name resolution service.

For /etc/hosts add an entry that looks like this if your Powerwall gateway's IP was 192.168.99.99:

192.168.99.99 powerwall

Step 2: Get the certificate openssl s_client -showcerts -connect powerwall:443 < /dev/null | sed --quiet '/BEGIN CERTIFICATE/,/END CERTIFICATE/p' > cacert.pem

This grabs the certificate from the powerwall using the DNS entry you setup in step 1.

Step 3: use the certificate in your curl statements e.g. curl --cacert cacert.pem https://powerwall/api/status

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.

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.

Powerwall 2 Web UI

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. _https://powerwall/

You should see something like this:

---

Wizard You can hit the "Login" link on this page and go through the setup (be careful what you change in the wizard).

username: <Enter whatever you like here>

password: Follow the instructions on the web page to set/change/recover the password. Whatever you set here will be used later.

As of version 20.49.0, the password you set here will be required to pull any of the URIs (statistics & settings) listed below.

Check out the bash script powerwallstats.sh in the samples directory for an example:

---

API Reference

Alternative API documentation in the form of OpenAPI Spec

An alternative to the below README form of documenting the APIs can be seen in openapi folder. OpenAPI spec is a machine-readable format that can be used to generate documentation, client libraries, and more.

You can also view the OpenAPI spec using the Swagger viewer by going to https://vloschiavo.github.io/powerwall2/openapi/

Advantages of OpenAPI spec:

• Industry standard format for documenting APIs
• Machine-readable format
• Can be used to generate client libraries
• Swagger UI presents the spec in an easy to read format
• With the right setup, you can use the Swagger UI to test the API endpoints against your own Powerwall

Disadvantages of OpenAPI spec:

• Not as human-readable as the README format
• Not as easy to contribute to as the README format

---

Base Endpoint

https://<tesla-powerwall-ip>/api/

Key

| Symbol | Meaning | | - | - | | :heavy_check_mark: | Yes | | :x: or <blank> | No | | 🚧 | Requires updating or has partial info |

Overview

Endpoint | Method | Requires Authentication? | Documented? | Summary | - | - | - | - | - | | /${e} | GET | | | | | /auth/toggle/login | POST | | | | | | DELETE | | | | | /auth/toggle/start | POST | | | | | /auth/toggle/supported | GET | | | | | /autoconfig/cancel | POST | | | | | /autoconfig/retry | POST | | | | | /autoconfig/run | POST | | | | | /autoconfig/status | GET | | | | | /config | GET | :heavy_check_mark: | 🚧 | | | /config/completed | GET | :heavy_check_mark: | :heavy_check_mark: | Applies config changes | | /customer | GET | :heavy_check_mark: | :heavy_check_mark: | | | | POST | | | | | /customer/registration | GET | :x: | :heavy_check_mark: | | | /customer/registration/legal | POST | 🚧 | 🚧 | | | /customer/registration/skip | POST | 🚧 | 🚧 | | | /devices/vitals | GET | :heavy_check_mark: | 🚧 | | | /generators | GET | :heavy_check_mark: | 🚧 | | | /generators/disconnect_types | GET | :heavy_check_mark: | 🚧 | | | /installer | GET | :heavy_check_mark: | :heavy_check_mark: | | | /installer/companies | GET | 🚧 | 🚧 | | | /logging | POST | | | | | /login/Basic | POST | :x: | 🚧 | | | /logout | GET | 🚧 | 🚧 | | | /meters | GET | :heavy_check_mark: | 🚧 | | | | POST | | | | | /meters/${e}/ct_config | GET | | | | | | POST | | | | | /meters/${e}/cts | DELETE | | | | | /meters/${e}/invert_cts | POST | | | | | /meters/${i}/commission | POST | | | | | /meters/${o.serial}/cts | POST | | | | | /meters/${t}