README.adoc

Python API Wrapper Documentation

Table of Contents

• Introduction
• Getting Started
  • Dependencies
  • Project Structure
  • Sample Code
• Examples

Introduction

This unofficial API wrapper written in Python allows your applications to call the APIs and access information.

More general details on the project are available from the project’s homepage.

Getting Started

Dependencies

The wrapper uses a single main third-party library. This can be installed by typing into your terminal:

pip install requests

Project Structure

The main wrapper lives in the src\tesla_api folder and the files in the examples directory are example scripts to show how to use the library. The examples are written to be fairly feature complete and considered fairly protection ready, so they can be used as applications in their own right.

For configuration, each example refers to a credential file in the folder configuration; to make the examples work you will need to edit credentials.json to include your Tesla® Gateway credentials.

Some of the examples either put or get messages from an Advanced Message Queuing Protocol (AMQP) server/broker, this is because the Gateway is not designed for a large number of requests, so it is better to query the data once and then make it available for other consuming clients via a message queue rather than have multiple scripts repeatedly query the same data. A free, open source and recommended AMQP server that runs on a variety of platforms is RabbitMQ®

Sample Code

To make a call to the Gateway you can simply run code similar to the following:

# All the shared Tesla® functions are in this package.
from tesla_api.local.gateway import Gateway

# Connection Variables.
GATEWAY_HOST = 'https://192.168.0.100'
GATEWAY_PASSWORD = 'eyJhbG'

# Connect locally to the Gateway, login and request meter details.
gateway = Gateway(GATEWAY_HOST)
if gateway.login(GATEWAY_PASSWORD):
    response = gateway.api_call('/api/meters/aggregates')
    print(response)

⚠️	Note how the script connected to the gateway via HTTPS but yet did not protest about an invalid certificate? Unfortunately as the Certificate Authority (CA) certificate is not available the connection cannot be verified. Caution should be used using this API on untrusted networks.

It is highly recommended you look at the examples in a text-editor to learn more about the features of the library (and to see how this flow is typically implemented).

The IQ Gateway API endpoints are best documented elsewhere on vloschiavo’s powerwall2 project.

Examples

Filename	Dependencies	Source Data	Output Data	Description
amqp_database_meters.py	mysql.connector and pika	AMQP	MySQL®/MariaDB®	Consumes meter messages from AMQP and stores it in a MySQL®/MariaDB® database (schema is in the resources folder).
amqp_unicorn_hat_hd.py	pika and unicornhathd	AMQP	Unicorn HAT HD	Consumes meter messages from AMQP and displays production and consumption data on a Unicorn HAT HD running on a Raspberry Pi.
gateway_amqp_meters.py	pika	Gateway	AMQP	Obtains meter information and publishes it to AMQP for consumption and statistics in other systems.
gateway_console.py	None	Gateway	Console	Displays production data on the console/terminal then exits. Will attempt to refresh any expired tokens.