TeslaPowerwallLibrary 1.0.3

TeslaPowerwallLibrary

A .NET client library for the Tesla™ Powerwall™ Energy Gateway, providing direct local-network access and Tesla Owners (cloud) API access to status, power flow, energy history, and control operations.

Tesla and Powerwall are trademarks of Tesla, Inc. This project is an independent, unofficial .NET library and is not affiliated with or endorsed by Tesla.

Supported Platforms

Overview

TeslaPowerwallLibrary provides a strongly typed, async-first .NET wrapper around the Tesla Energy Gateway's local API and the Tesla Owners cloud API. It supports:

• Local network access to the Powerwall gateway (status, power flow, grid status, system status, and energy/calendar history)
• Tesla Owners (cloud) API access, including interactive OAuth login and automatic token persistence
• Control operations such as backup reserve level, operating mode, grid charging, grid export, and Storm Watch (cloud only)
• Response caching with configurable expiry to reduce load on the gateway
• Multi-target support for .NET Framework 4.7.2 and .NET 10

This .NET library is adapted from the Python pypowerwall project by Jason A. Cox. See the license for attribution details.

Connection modes

Gateway hardware compatibility: Local mode's plain HTTPS/JSON REST API (/api/login/Basic plus endpoints such as /api/system_status/soe and /api/meters/aggregates) is the original Gateway 2 / Powerwall+ local interface and is well established on that hardware. On Powerwall 3, Tesla replaced this local REST API with TEDAPI (protobuf-encoded, RSA-signed); the plain REST endpoints return 403 Unable to GET to resource on a Powerwall 3 gateway. Powerwall 3 owners need TEDAPI support (not yet implemented — see the table above) for local access; Cloud mode works today regardless of gateway generation.

Installation

The library is available as the TeslaPowerwallLibrary NuGet package.

dotnet add package TeslaPowerwallLibrary

Quick Start

Connect to a local gateway

using TeslaPowerwallLibrary;

var options = new PowerwallOptions
{
	 Host = "10.0.1.99",
	 Password = "your-customer-password"
};

using var powerwall = new Powerwall(options);
await powerwall.ConnectAsync();

var status = await powerwall.StatusAsync();

Connect using the Tesla Owners cloud API

using TeslaPowerwallLibrary;

var options = new PowerwallOptions
{
	 Email = "you@example.com",
	 CloudMode = true,
	 AccessToken = "your-access-token",
	 RefreshToken = "your-refresh-token"
};

using var powerwall = new Powerwall(options);
await powerwall.ConnectAsync();

After the first successful cloud connect, the library persists the (possibly rotated) tokens internally, keyed by Email, so later runs can omit AccessToken and RefreshToken entirely. AccessToken is optional even on a first connect: when omitted (or stale), the library silently derives a new one from RefreshToken. When a non-empty AuthPath is supplied, that location is authoritative — no fallback is attempted, and an inaccessible path throws PowerwallCloudTokenCacheStorageException instead of silently continuing without persistence.

Cloud mode without library-owned token storage

Set NoCloudTokenPersistence when the host has no suitable place for the library to keep a file (for example a Mono-hosted embedded environment). No cache file is ever read or written; AuthPath is ignored, and Email is not validated since it is otherwise used only as the cache key. Only RefreshToken needs to be supplied on every run — AccessToken remains optional and is silently (re)derived from it when absent or stale. Because AccessToken was not supplied here, CloudTokensRefreshed only fires when Tesla rotates the refresh token itself, and e.AccessToken is null in that case:

using TeslaPowerwallLibrary;

var options = new PowerwallOptions
{
	 CloudMode = true,
	 RefreshToken = "your-refresh-token",
	 NoCloudTokenPersistence = true
};

using var powerwall = new Powerwall(options);
powerwall.CloudTokensRefreshed += (sender, e) =>
{
	 // Only raised here because RefreshToken alone was supplied above: fires when Tesla rotates the
	 // refresh token itself (not on every access-token renewal), and e.AccessToken is null.
	 // Persist e.RefreshToken using your own storage so the next run can reuse it.
};

await powerwall.ConnectAsync();

Repository Contents

• TeslaPowerwallLibrary — the main library project published to NuGet
• TeslaPowerwallLibrary.Login — shared Tesla cloud OAuth login library (interactive WebView2-based browser login), used by both the app and the test console; not published to NuGet, distributed as a DLL attached to each GitHub release — see the Tesla cloud login guide
• TeslaPowerwallLibrary.App — a WPF dashboard application with live energy charts, system status, and site/account management
• TeslaPowerwallLibrary.TestConsole — a command-line and interactive test harness covering the library's read and control operations
• TeslaPowerwallLibrary.Setup — a small WPF wrapper around TeslaPowerwallLibrary.Login that performs a standalone Tesla cloud login and displays the resulting tokens
• TeslaPowerwallLibrary.Tests — MSTest-based deterministic unit test coverage

Documentation

Public documentation for this repository is available on GitHub Pages:

• https://oznetmaster.github.io/TeslaPowerwallLibrary/

Acknowledgements

This library is adapted from the Python pypowerwall project by Jason A. Cox.

License

MIT © 2026 Neil Colvin, © 2022 Jason Cox — see LICENSE.