Tesla Cloud Option (#59)

* TeslaCloud class

* Placeholder TeslaCloud class

* Unpack API dictionary

* Add functions and tests

* Add cache and setup

* Remove TODOs

* Add cloud setup to CLI

* Fix log bug

* Add teslapy to tests

* CI test remove py 3.5

* Remove sample data

* Add file types

* Add cloud mode

* Add missing data

* Fix bug for sites without inverters

* Add test proxy using cloud and local

* Fix hash issue

* Build t31

* Fix style

* Fix grid services data mapping which relates to VPP events

* Build t32

* Unpin pypowerwall library

* Fix backup reserve percent scaling

* Fix API mismatch

* Fix percentage_charged

* Prep for v0.7.0

* Minor fixes for consistency

* Fix exception when vitals is None

* Add get_time_remaining()

* Remove vitals mock data

* Fix vitals response

* Add siteid selection to setup

* Update setup install_requires

* Fix duplicate line

* Remove test servers

* Update docs for v0.7.0

* Add simulated vitals

* Remove poll() cache

* Add counter param to SITE_DATA call

* Revise handling of siteid selection

* Stagger TTL to reduce rate limit

* Infinite loop to keep container running

* Allow no cache option with pwcacheexpire = 0

* Add stats for cloud mode

* Startup details logging

* Fix local log details

* Limit cloud API requests to single thread

* Reduce http timeout and remove retries

* Change elapsed time measurements to monotonic clock

* Fix exceptions and invalid return data

* Add _site_api() to broker  calls

* Revise debug log order, fix sites exception

* Updates to documentation and error logging

* Proxy t35

* Counter param starts at 1

---------

Co-authored-by: Michael Birse <michael@birse.com.au>

.github/workflows/simtest.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.5", "3.6", "3.7", "3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "3.11"]
 
     services:
       simulator:
@@ -33,7 +33,7 @@ jobs:
           python -VV
           python -m site
           python -m pip install --upgrade pip setuptools wheel
-          pip install --upgrade requests protobuf
+          pip install --upgrade requests protobuf teslapy
 
       - name: "Run test.py on ${{ matrix.python-version }}"
         run: "python example.py"

.github/workflows/test.yml

@@ -14,7 +14,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.5", "3.6", "3.7", "3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "3.11"]
 
     steps:
       - uses: "actions/checkout@v2"
@@ -27,7 +27,7 @@ jobs:
           python -VV
           python -m site
           python -m pip install --upgrade pip setuptools wheel
-          pip install --upgrade requests protobuf
+          pip install --upgrade requests protobuf teslapy
 
       - name: "Run test.py on ${{ matrix.python-version }}"
         run: "python test.py"

.gitignore

@@ -144,3 +144,7 @@ tools/set-mode.auth
 tools/set-mode.conf
 tools/tedapi/request.bin
 tools/tedapi/app*
+.pypowerwall.auth
+.pypowerwall.site
+proxy/pypowerwall
+proxy/teslapy

README.md

@@ -7,7 +7,7 @@
 [![Python Version](https://img.shields.io/pypi/pyversions/pypowerwall)](https://img.shields.io/pypi/pyversions/pypowerwall)
 [![PyPI Downloads](https://static.pepy.tech/badge/pypowerwall/month)](https://static.pepy.tech/badge/pypowerwall/month)
 
-Python module to interface with Tesla Energy Gateways for Powerwall and solar power data. Currently supporting Powerwall, Powerwall 2 and Powerwall+ systems.
+Python module to interface with Tesla Energy Gateways for Powerwall and solar power data. Currently supporting local access to Powerwall, Powerwall 2 and Powerwall+ systems and Tesla Owner cloud API for all systems including Solar Only and Powerwall 3 systems.
 
 ## Description
 
@@ -33,10 +33,13 @@ You can clone this repo or install the package with pip.  Once installed, pyPowe
 
 ```bash
 # Install pyPowerwall
-python -m pip install pypowerwall
+python3 -m pip install pypowerwall
 
 # Scan Network for Powerwalls
-python -m pypowerwall scan
+python3 -m pypowerwall scan
+
+# (optional) Setup to use Tesla Owners cloud API
+python3 -m pypowerwall setup
 ```
 
 FreeBSD users can install from ports or pkg [FreshPorts](https://www.freshports.org/net-mgmt/py-pypowerwall):
@@ -51,7 +54,7 @@ Via ports:
 # cd /usr/ports/net-mgmt/py-pypowerwall/ && make install clean
 ```
 
-Note: pyPowerwall installation will attempt to install these required python packages: _requests_ and _protobuf_.
+Note: pyPowerwall installation will attempt to install these required python packages: _requests_, _protobuf_ and _teslapy_.
 
 ## Programming with pyPowerwall
 
@@ -64,11 +67,17 @@ and call function to poll data.  Here is an example:
     # Optional: Turn on Debug Mode
     # pypowerwall.set_debug(True)
 
-    # Credentials for your Powerwall - Customer Login Data
+    # Local Mode - Credentials for your Powerwall - Customer Login
     password='password'
     email='email@example.com'
     host = "10.0.1.123"               # Address of your Powerwall Gateway
     timezone = "America/Los_Angeles"  # Your local timezone
+
+    # (Optional) Cloud Mode - Requires Setup
+    password = ""
+    email='email@example.com'
+    host = ""
+    timezone = "America/Los_Angeles"  # Your local timezone
 
     # Connect to Powerwall
     pw = pypowerwall.Powerwall(host,password,email,timezone)
@@ -114,6 +123,17 @@ and call function to poll data.  Here is an example:
  Classes
     Powerwall(host, password, email, timezone, pwcacheexpire, timeout, poolmaxsize)
 
+ Parameters
+    host                      # Hostname or IP of the Tesla gateway
+    password                  # Customer password for gateway
+    email                     # (required) Customer email for gateway / cloud
+    timezone                  # Desired timezone
+    pwcacheexpire = 5         # Set API cache timeout in seconds
+    timeout = 5               # Timeout for HTTPS calls in seconds
+    poolmaxsize = 10          # Pool max size for http connection re-use (persistent
+                                connections disabled if zero)
+    cloudmode = False         # If True, use Tesla cloud for data (default is False)
+
  Functions 
     poll(api, json, force)    # Return data from Powerwall api (dict if json=True, bypass cache force=True)
     level()                   # Return battery power level percentage
@@ -134,20 +154,16 @@ and call function to poll data.  Here is an example:
     temps()                   # Return Powerwall Temperatures
     alerts()                  # Return array of Alerts from devices
     system_status(json)       # Returns the system status
-    battery_blocks(json)      # Returns battery specific information merged from system_status() and vitals()
-    grid_status(type)         # Return the power grid status, type ="string" (default), "json", or "numeric"
+    battery_blocks(json)      # Returns battery specific information merged from 
+                              # system_status() and vitals()
+    grid_status(type)         # Return the power grid status, type ="string" (default),
+                              # "json", or "numeric":
                               #     - "string": "UP", "DOWN", "SYNCING"
                               #     - "numeric": -1 (Syncing), 0 (DOWN), 1 (UP)
-    is_connected()            # Returns True if able to connect and login to Powerwall
+    is_connected()            # Returns True if able to connect to Powerwall
+    get_reserve(scale)        # Get Battery Reserve Percentage
+    get_time_remaining()      # Get the backup time remaining on the battery
     
- Parameters
-    host                    # (required) hostname or IP of the Tesla gateway
-    password                # (required) password for logging into the gateway
-    email                   # (required) email used for logging into the gateway
-    timezone                # (required) desired timezone
-    pwcacheexpire = 5       # Set API cache timeout in seconds
-    timeout = 10            # Timeout for HTTPS calls in seconds
-    poolmaxsize = 10        # Pool max size for http connection re-use (persistent connections disabled if zero)
 ```
 
 ## Tools

RELEASE.md

@@ -1,9 +1,34 @@
 # RELEASE NOTES
 
+## v0.7.1 - Tesla Cloud Mode
+
+* Simulate Powerwall Energy Gateway via Tesla Cloud API calls. In `cloudmode` API calls to pypowerwall APIs will result in calls made to the Tesla API to fetch the data.
+
+Cloud Mode Setup - Use pypowerwall to fetch your Tesla Owners API Token
+
+```bash
+python3 -m pypowerwall setup
+
+# Token and site information stored in .pypowerwall.auth and .pypowerwall.site
+```
+
+Cloud Mode Code Example
+
+```python
+import pypowerwall
+pw = pypowerwall.Powerwall(email="email@example.com",cloudmode=True)
+pw.power()
+# Output: {'site': 2977, 'solar': 1820, 'battery': -3860, 'load': 937}
+pw.poll('/api/system_status/soe')
+# Output: '{"percentage": 26.403205103271222}'
+```
+
+* Added new API function to compute estimated backup time remaining on the battery: `get_time_remaining()`
+
 ## v0.6.4 - Power Flow Animation
 
 Proxy t29 Updates
-* Default page rendered by proxy (http://pypowerwall/) will render Powerflow Animation
+* Default page rendered by proxy (http://pypowerwall:8675/) will render Powerflow Animation
 * Animation assets (html, css, js, images, fonts, svg) will render from local filesystem instead of pulling from Powerwall TEG portal.
 * Start prep for possible API removals from Powerwall TEG portal (see NOAPI settings)
 

proxy/Dockerfile

@@ -1,6 +1,6 @@
 FROM python:3.10-alpine
 WORKDIR /app
-RUN pip3 install pypowerwall==0.6.4 bs4
+RUN pip3 install pypowerwall==0.7.1 bs4
 COPY . .
 CMD ["python3", "server.py"]
 EXPOSE 8675 

proxy/RELEASE.md

@@ -1,5 +1,13 @@
 ## pyPowerwall Proxy Release Notes
 
+### Proxy t35 (29 Dec 2023)
+
+* Add `cloudmode` support for pypowerwall v0.7.1. 
+
+### Proxy t32 (20 Dec 2023)
+
+* Fix "flashing animation" problem by matching `hash` variable in index.html to firmware version `git_hash`.
+
 ### Proxy t29 (16 Dec 2023)
 
 * Default page rendered by proxy (http://pypowerwall/) will render Powerflow Animation