pypowerwall 0.18.0__py3-none-any.whl

pypowerwall/__init__.py

@@ -0,0 +1,1282 @@
+# pyPowerWall Module
+# -*- coding: utf-8 -*-
+"""
+ Python module to interface with Tesla Solar Powerwall Gateway
+
+ Author: Jason A. Cox
+ For more information see https://github.com/jasonacox/pypowerwall
+
+ Features
+    * Works with Tesla Energy Gateways - Powerwall+
+    * Simple access through easy to use functions using customer credentials
+    * Will cache authentication to reduce load on Powerwall Gateway
+    * Will cache responses for 5s to limit number of calls to Powerwall Gateway
+    * Will re-use http connections to Powerwall Gateway for reduced load and faster response times
+    * Can use Tesla Cloud API instead of local Powerwall Gateway (if enabled)
+    * Uses Auth Cookie or Bearer Token for authorization (configurable)
+
+ Classes
+    Powerwall(host, password, email, timezone, pwcacheexpire, timeout, poolmaxsize, 
+        cloudmode, siteid, authpath, authmode, cachefile, fleetapi, auto_select, retry_modes, gw_pwd)
+
+ Parameters
+    host                      # Hostname or IP of the Tesla gateway (optionally host:port for 
+                                non-standard HTTPS port, e.g. 10.0.1.99:8443; default port is 443)
+    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)
+    siteid = None             # If cloudmode is True, use this siteid (default is None)
+    authpath = ""             # Path to cloud auth and site files (default current directory)
+    authmode = "cookie"       # "cookie" (default) or "token" - use cookie or bearer token for auth
+    cachefile = ".powerwall"  # Path to cache file (default current directory)
+    fleetapi = False          # If True, use Tesla FleetAPI for data (default is False)
+    auto_select = False       # If True, select the best available mode to connect (default is False)
+    retry_modes = False       # If True, retry connection to Powerwall - WARNING: blocks
+                                indefinitely until a connection succeeds (daemon use)
+    gw_pwd = None             # TEG Gateway password (used for local mode access to tedapi)
+    wifi_host = None          # Optional WiFi TEDAPI host for v1r follower fallback
+    
+ Functions 
+    poll(api, jsonformat, raw, force)   # Return data from Powerwall api (JSON string if jsonformat=True, bypass cache force=True)
+    post(api, payload, din, jsonformat) # Send payload to Powerwall api (JSON string if jsonformat=True)
+    level()                   # Return battery power level percentage
+    power()                   # Return power data returned as dictionary
+    site(verbose)             # Return site sensor data (W or raw JSON if verbose=True)
+    solar(verbose):           # Return solar sensor data (W or raw JSON if verbose=True)
+    battery(verbose):         # Return battery sensor data (W or raw JSON if verbose=True)
+    load(verbose)             # Return load sensor data (W or raw JSON if verbose=True)
+    grid()                    # Alias for site()
+    home()                    # Alias for load()
+    vitals(json)              # Return Powerwall device vitals (dict or json if True)
+    strings(json, verbose)    # Return solar panel string data
+    din()                     # Return DIN
+    uptime()                  # Return uptime - string hms format
+    version()                 # Return system version
+    status(param)             # Return status (JSON) or individual param
+    site_name()               # Return site name
+    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"
+                              #     - "string": "UP", "DOWN", "SYNCING"
+                              #     - "numeric": -1 (Syncing), 0 (DOWN), 1 (UP)
+    is_connected()            # Returns True if able to connect and login to Powerwall
+    get_reserve(scale)        # Get Battery Reserve Percentage
+    get_mode()                # Get Current Battery Operation Mode
+    set_reserve(level)        # Set Battery Reserve Percentage
+    set_mode(mode)            # Set Current Battery Operation Mode
+    get_time_remaining()      # Get the backup time remaining on the battery
+    set_operation(level, mode, json)        # Set Battery Reserve Percentage and/or Operation Mode
+    set_grid_charging(mode)   # Enable or disable grid charging (mode = True or False)
+    set_grid_export(mode)     # Set grid export mode (mode = battery_ok, pv_only, never)
+    get_grid_charging()       # Get the current grid charging mode
+    get_grid_export()         # Get the current grid export mode
+    go_off_grid(confirm)      # USE WITH EXTREME CARE: open the grid contactor (island the home) - requires confirm=True
+    reconnect_grid()          # USE WITH EXTREME CARE: close the grid contactor (reconnect to grid)
+
+ Requirements
+    This module requires the following modules: requests, protobuf, teslapy
+    pip install requests protobuf teslapy
+"""
+import json
+import logging
+import os.path
+import re
+import sys
+import time
+from typing import Optional, Union
+
+
+def _release_tuple(version_string):
+    """Numeric release components of a version, e.g. "0.18.0rc1" -> (0, 18, 0).
+    Never raises, so a pre-release version string can't break import."""
+    return tuple(int(n) for n in re.findall(r"\d+", version_string.split("+")[0])[:3])
+
+
+# Single source of truth for the package version — keep this a plain literal.
+# pyproject.toml reads it at build time via [tool.setuptools.dynamic]
+# (attr:), which parses this file without importing it.
+__version__ = version = "0.18.0"
+version_tuple = _release_tuple(__version__)
+__author__ = 'jasonacox'
+
+# noinspection PyPackageRequirements
+import urllib3
+
+from pypowerwall.cloud.pypowerwall_cloud import AUTHFILE, PyPowerwallCloud
+from pypowerwall.exceptions import (InvalidBatteryReserveLevelException,
+                                    PyPowerwallInvalidConfigurationParameter)
+from pypowerwall.fleetapi.fleetapi import CONFIGFILE
+from pypowerwall.fleetapi.pypowerwall_fleetapi import PyPowerwallFleetAPI
+from pypowerwall.local.pypowerwall_local import PyPowerwallLocal
+from pypowerwall.pypowerwall_base import PyPowerwallBase, parse_version
+from pypowerwall.regex import EMAIL_REGEX, HOST_REGEX, IPV4_6_REGEX
+from pypowerwall.tedapi.api_version import TEDAPIApiVersion
+from pypowerwall.tedapi.auth_mode import AuthMode
+from pypowerwall.tedapi.pypowerwall_tedapi import PyPowerwallTEDAPI
+
+urllib3.disable_warnings()  # Disable SSL warnings
+
+
+log = logging.getLogger(__name__)
+log.debug('%s version %s', __name__, __version__)
+log.debug('Python %s on %s', sys.version, sys.platform)
+
+def set_debug(toggle=True, color=True):
+    """Enable verbose logging"""
+    if toggle:
+        if color:
+            logging.basicConfig(format='\x1b[31;1m%(levelname)s:%(message)s\x1b[0m', level=logging.DEBUG)
+        else:
+            logging.basicConfig(format='%(levelname)s:%(message)s', level=logging.DEBUG)
+        log.setLevel(logging.DEBUG)
+        log.debug("%s [%s]\n" % (__name__, __version__))
+    else:
+        log.setLevel(logging.NOTSET)
+
+
+# pylint: disable=too-many-public-methods
+class Powerwall(object):
+    def __init__(self, host="", password="", email="nobody@nowhere.com",
+                 timezone="America/Los_Angeles", pwcacheexpire=5, timeout=5, poolmaxsize=10,
+                 cloudmode=False, siteid=None, authpath="", authmode="cookie", cachefile=".powerwall",
+                 fleetapi=False, auto_select=False, retry_modes=False, gw_pwd=None,
+                 rsa_key_path=None, wifi_host=None, tedapi_api_version=TEDAPIApiVersion.V2024_06,
+                 tedapi_auth_mode=AuthMode.BASIC):
+        """
+        Represents a Tesla Energy Gateway Powerwall device.
+
+        Args:
+            host        = Hostname or IP address of Powerwall (e.g. 10.0.1.99); optionally
+                          include a port for non-standard HTTPS access (e.g. 10.0.1.99:8443);
+                          defaults to port 443 when no port is specified
+            password    = Customer password set up on Powerwall gateway
+            email       = Customer email
+            timezone    = Timezone for location of Powerwall
+                (see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
+            pwcacheexpire = Seconds to expire cached entries
+            timeout      = Seconds for the timeout on http requests
+            poolmaxsize  = Pool max size for http connection re-use (persistent connections disabled if zero)
+            cloudmode    = If True, use Tesla cloud for data (default is False)
+            siteid       = If cloudmode is True, use this siteid (default is None)
+            authpath     = Path to cloud auth and site cache files (default current directory)
+            authmode     = "cookie" (default) or "token" - use cookie or bearer token for authorization
+            cachefile    = Path to cache file (default current directory)
+            fleetapi     = If True, use Tesla FleetAPI for data (default is False)
+            auto_select  = If True, select the best available mode to connect (default is False)
+            retry_modes  = If True, retry connection to Powerwall - WARNING: blocks
+                           indefinitely until a connection succeeds (daemon use)
+            gw_pwd       = Full gateway password from QR sticker; used for TEDAPI (mode 4)
+                           and auto-derived (last 5 chars) for v1r login (mode 5)
+            rsa_key_path = Path to RSA-4096 private key PEM for v1r LAN TEDapi access
+            tedapi_auth_mode = TEDAPI authentication mode: "basic" (default) HTTP
+                           Basic Auth to 192.168.91.1, which is only reachable
+                           over the Gateway's Wi-Fi; or "bearer" to log in via
+                           /api/login/Basic and wrap queries in an AuthEnvelope,
+                           which also works over the wired LAN IP. Bearer works
+                           on solar-only gateways but NOT Powerwall 2 or
+                           Powerwall 3 — for PW3 wired access use v1r mode
+                           (rsa_key_path)
+        """
+
+        # Attributes
+        self.cachefile = cachefile  # Stores auth session information
+        self.host = host
+        self.password = password
+        self.email = email
+        self.timezone = timezone
+        self.timeout = timeout  # 5s timeout for http calls
+        self.poolmaxsize = poolmaxsize  # pool max size for http connection re-use
+        self.auth = {}  # caches auth cookies
+        self.token = None  # caches bearer token
+        self.pwcacheexpire = pwcacheexpire  # seconds to expire cache
+        self.cloudmode = cloudmode  # cloud mode or local mode (default)
+        self.siteid = siteid  # siteid for cloud mode
+        self.authpath = os.path.expanduser(authpath)  # path to auth and site cache files
+        self.authmode = authmode  # cookie or token
+        self.pwcooldown = 0  # rate limit cooldown time - pause api calls
+        self.vitals_api = True  # vitals api is available for local mode
+        # Backend client - remains None if connect() fails for all modes so that
+        # method calls degrade to None instead of raising AttributeError
+        self.client: Optional[PyPowerwallBase] = None
+        self.fleetapi = fleetapi
+        self.retry_modes = retry_modes
+        self.mode = "unknown"
+        self.gw_pwd = gw_pwd # TEG Gateway password for TEDAPI mode
+        self.rsa_key_path = rsa_key_path  # RSA key for v1r LAN TEDapi
+        self.wifi_host = wifi_host  # WiFi TEDAPI host for v1r wifi fallback
+        # TEDAPIApiVersion.V2024_06 (default) or .V2026_06; coerce str inputs.
+        self.tedapi_api_version = TEDAPIApiVersion.coerce(tedapi_api_version)
+        # basic / bearer for TEDAPI; coerce str inputs (raises on bad).
+        self.tedapi_auth_mode = AuthMode.coerce(tedapi_auth_mode)
+        self.tedapi = False
+        self.tedapi_mode = "off"  # off, full, hybrid
+
+        # Make certain assumptions here
+        if not self.host:
+            self.cloudmode = True
+        if self.cloudmode and not self.fleetapi:
+            self.mode = "cloud"
+        elif self.cloudmode and self.fleetapi:
+            self.mode = "fleetapi"
+        elif not self.cloudmode and not self.fleetapi:
+            self.mode = "local"
+        else:
+            self.mode = "unknown"
+
+        # Auto select mode if requested
+        if auto_select:
+            if self.host and not self.cloudmode and not self.fleetapi:
+                log.debug("Auto selecting local mode")
+                self.cloudmode = self.fleetapi = False
+                self.mode = "local"
+            elif os.path.exists(os.path.join(self.authpath, CONFIGFILE)):
+                log.debug("Auto selecting FleetAPI Mode")
+                self.cloudmode = self.fleetapi = True
+                self.mode = "fleetapi"
+            elif os.path.exists(os.path.join(self.authpath, AUTHFILE)):
+                if not self.email or self.email == "nobody@nowhere.com":
+                    auth_file_path = os.path.join(self.authpath, AUTHFILE)
+                    try:
+                        with open(auth_file_path, 'r') as file:
+                            auth = json.load(file)
+                        self.email = list(auth.keys())[0]
+                    except Exception as exc:
+                        log.debug(f"Failed to load auth file '{auth_file_path}': {exc}")
+                self.cloudmode = True
+                self.fleetapi = False
+                self.mode = "cloud"
+                log.debug("Auto selecting Cloud Mode (email: %s)" % self.email)
+            else:
+                log.debug("Auto Select Failed: Unable to use local, cloud or fleetapi mode.")
+
+        # Validate provided parameters
+        self._validate_init_configuration()
+
+        # Connect to Powerwall
+        if not self.connect(self.retry_modes):
+            log.error("Unable to connect to Powerwall. Verify host, credentials, and network connectivity."
+                     " Enable debug logging for detailed diagnostics.")
+
+    def connect(self, retry=False) -> bool:
+        """
+        Connect to Tesla Energy Gateway Powerwall
+
+        Tries the configured mode first and falls back to the other modes
+        (local -> fleetapi -> cloud -> local) on failure. If every mode fails,
+        the configured mode is restored so a later connect() retries in the
+        configured order.
+
+        Args:
+            retry = If True, keep cycling through the modes until one connects.
+                    WARNING: this blocks the calling thread indefinitely (by
+                    design for daemon use, e.g. the proxy) - it only returns
+                    once a connection succeeds.
+        """
+        if self.mode == "unknown":
+            log.error("Unable to determine mode to connect.")
+            return False
+        # Snapshot the configured mode - fallback mutates self.mode/cloudmode/
+        # fleetapi/tedapi/tedapi_mode, and a total failure must not leave that
+        # mutation behind. tedapi/tedapi_mode matter as much as mode: the local-
+        # mode exception handler zeroes them, and a stale tedapi=False after a
+        # fully-failed connect(retry=False) wedged the proxy's TEDAPI recovery
+        # thread forever - its loop gate (`if not pw.tedapi: continue`) never
+        # reached the reconnect call again (#366).
+        configured_mode = (self.mode, self.cloudmode, self.fleetapi,
+                           self.tedapi, self.tedapi_mode)
+        total_wait = 0
+        count = 0
+        while count < 3:
+            count += 1
+            if retry and count == 3:
+                log.warning("Failed to connect to Powerwall with all modes. Waiting 30s to retry "
+                            "(retry enabled - blocking until a connection succeeds; "
+                            "%ds cumulative wait so far)." % total_wait)
+                time.sleep(30)
+                total_wait += 30
+                count = 0
+            if self.mode == "local":
+                log.debug(f"password = {'[set]' if self.password else '[empty]'}, "
+                          f"gw_pwd = {'[set]' if self.gw_pwd else '[empty]'}, "
+                          f"rsa_key_path = {'[set]' if self.rsa_key_path else '[empty]'}")
+                try:
+                    if self.rsa_key_path:  # v1r LAN TEDapi mode (mode 5)
+                        # Auto-derive customer password from gw_pwd if not explicitly set
+                        pw = self.password
+                        if not pw and self.gw_pwd:
+                            pw = self.gw_pwd[-5:]
+                            log.debug("Derived customer password from gw_pwd (last 5 characters)")
+                        if not pw:
+                            raise ValueError("v1r mode requires password or gw_pwd")
+                        self.tedapi_mode = "v1r"
+                        if self.gw_pwd and self.wifi_host:
+                            log.debug("TEDAPI ** v1r (wifi fallback available) **")
+                        else:
+                            log.debug("TEDAPI ** v1r **")
+                        self.client = PyPowerwallTEDAPI(
+                            gw_pwd=self.gw_pwd or "",
+                            pwcacheexpire=self.pwcacheexpire,
+                            pwconfigexpire=self.pwcacheexpire,
+                            timeout=self.timeout, host=self.host,
+                            poolmaxsize=self.poolmaxsize,
+                            v1r=True, password=pw,
+                            rsa_key_path=self.rsa_key_path,
+                            wifi_host=self.wifi_host,
+                            tedapi_api_version=self.tedapi_api_version)
+                    elif not self.password and self.gw_pwd:  # Full TEDAPI WiFi (mode 4)
+                        log.debug("TEDAPI ** full **")
+                        self.tedapi_mode = "full"
+                        self.client = PyPowerwallTEDAPI(self.gw_pwd, pwcacheexpire=self.pwcacheexpire,
+                                                        pwconfigexpire=self.pwcacheexpire,
+                                                        timeout=self.timeout, host=self.host,
+                                                        poolmaxsize=self.poolmaxsize,
+                                                        tedapi_api_version=self.tedapi_api_version,
+                                                        auth_mode=self.tedapi_auth_mode,
+                                                        timezone=self.timezone)
+                    else:  # Hybrid (password + gw_pwd) or local-only (password only)
+                        self.tedapi_mode = "hybrid"
+                        self.client = PyPowerwallLocal(self.host, self.password, self.email, self.timezone, self.timeout,
+                                                       self.pwcacheexpire, self.poolmaxsize, self.authmode, self.cachefile,
+                                                       self.gw_pwd)
+                    self.client.authenticate()
+                    self.cloudmode = self.fleetapi = False
+                    self.tedapi = self.client.tedapi
+                    if not self.tedapi:
+                        self.tedapi_mode = "off"
+                    return True
+                except Exception as exc:
+                    log.warning(f"Failed to connect using Local mode: {exc} - trying fleetapi mode.")
+                    self.tedapi = False
+                    self.tedapi_mode = "off"
+                    self.mode = "fleetapi"
+                    continue
+            if self.mode == "fleetapi":
+                try:
+                    self.client = PyPowerwallFleetAPI(self.email, self.pwcacheexpire, self.timeout, self.siteid,
+                                                    self.authpath)
+                    self.client.authenticate()
+                    self.cloudmode = self.fleetapi = True
+                    self.siteid = self.client.siteid
+                    return True
+                except Exception as exc:
+                    log.warning(f"Failed to connect using FleetAPI mode: {exc} - trying cloud mode.")
+                    self.mode = "cloud"
+                    continue
+            if self.mode == "cloud":
+                try:
+                    self.client = PyPowerwallCloud(self.email, self.pwcacheexpire, self.timeout, self.siteid, self.authpath)
+                    self.client.authenticate()
+                    self.cloudmode = True
+                    self.fleetapi = False
+                    self.siteid = self.client.siteid
+                    return True
+                except Exception as exc:
+                    log.warning(f"Failed to connect using Cloud mode: {exc} - trying local mode.")
+                    self.mode = "local"
+                    continue
+        # Total failure - restore the configured mode so a subsequent
+        # connect() retries in the configured order, not where fallback left off
+        (self.mode, self.cloudmode, self.fleetapi,
+         self.tedapi, self.tedapi_mode) = configured_mode
+        return False
+
+    def _no_client(self) -> bool:
+        """Return True (and log an error) if no backend client is connected."""
+        if self.client is None:
+            log.error("Not connected to Powerwall - no backend client available. "
+                      "Check connection settings and call connect().")
+            return True
+        return False
+
+    def is_connected(self):
+        """
+        Attempt connection with Tesla Energy Gateway
+        
+        Return True if able to successfully connect and login to Powerwall
+        """
+        # noinspection PyBroadException
+        try:
+            if self.status() is None:
+                return False
+            return True
+        except Exception:
+            return False
+
+    # pylint: disable=inconsistent-return-statements
+    def poll(self, api='/api/site_info/site_name', jsonformat=False, raw=False, recursive=False,
+             force=False) -> Optional[Union[dict, list, str, bytes]]:
+        """
+        Query Tesla Energy Gateway Powerwall for API Response
+        
+        Args:
+            api         = URI 
+            jsonformat  = If True, return JSON format otherwise return Python Dictionary
+            raw         = If True, send raw data back (useful for binary responses, has no meaning in Cloud mode)
+            recursive   = If True, this is a recursive call and do not allow additional recursive calls
+            force       = If True, bypass the cache and make the API call to the gateway, has no meaning in Cloud mode
+        """
+        if self._no_client():
+            return None
+        payload = self.client.poll(api, force, recursive, raw)
+        if jsonformat:
+            try:
+                return json.dumps(payload)
+            except (TypeError, ValueError):
+                log.error(f"Unable to dump response '{payload}' as JSON. I know you asked for it, sorry.")
+                return None
+        else:
+            return payload
+
+    def post(self, api: str, payload: Optional[dict], din: Optional[str] = None, jsonformat=False, raw=False,
+             recursive=False) -> Optional[Union[dict, list, str, bytes]]:
+        """
+        Send a command to Tesla Energy Gateway
+
+        Args:
+            api         = URI
+            payload     = Arbitrary payload to send
+            din         = System DIN (ignored in Cloud mode)
+            raw         = If True, send raw data back (useful for binary responses, has no meaning in Cloud mode)
+            recursive   = If True, this is a recursive call and do not allow additional recursive calls
+        """
+        if self._no_client():
+            return None
+        response = self.client.post(api, payload, din, recursive, raw)
+        if jsonformat:
+            try:
+                return json.dumps(response)
+            except (TypeError, ValueError):
+                log.error(f"Unable to dump response '{response}' as JSON. I know you asked for it, sorry.")
+                return None
+        else:
+            return response
+
+    def level(self, scale=False):
+        """
+        Battery Level Percentage 
+            Note: Tesla App reserves 5% of battery => ( (batterylevel / 0.95) - (5 / 0.95) )
+        Args:
+            scale = If True, convert battery level to app scale value
+        """
+        # Return power level percentage for battery
+        try:
+            payload = self.poll('/api/system_status/soe')
+            if payload is not None and 'percentage' in payload:
+                level = payload['percentage']
+                if scale:
+                    level = (level / 0.95) - (5 / 0.95)
+                return level
+            return None
+        except Exception as e:
+            log.error(f"level(): Exception {type(e).__name__}: {e}")
+            raise
+
+    def power(self) -> dict:
+        """
+        Power Usage for Site, Solar, Battery and Load
+        """
+        # Return power for (site, solar, battery, load) as dictionary
+        if self._no_client():
+            return None
+        return self.client.power()
+
+    def vitals(self, jsonformat=False):
+        """
+        Device Vitals Data
+
+        Args:
+           jsonformat = If True, return JSON format otherwise return Python Dictionary
+        """
+        if self._no_client():
+            return None
+        output = self.client.vitals()
+
+        # Return result
+        if jsonformat:
+            json_out = json.dumps(output, indent=4, sort_keys=True)
+            return json_out
+        else:
+            return output
+
+    def strings(self, jsonformat=False, verbose=False):
+        """
+        Solar Strings Data (current, voltage, power, state, connected)
+
+        Args:
+           jsonformat = If True, return JSON format otherwise return Python Dictionary
+           verbose    = If True, return all String data details otherwise basics
+        """
+        result = {}
+        devicemap = ['', '1', '2', '3', '4', '5', '6', '7', '8']
+        deviceidx = 0
+        v: dict = self.vitals() or {}
+        for device in v:
+            if device.split('--')[0] == 'PVAC':
+                # Check for PVS data
+                look = "PVS" + str(device)[4:]
+                if look in v:
+                    # Inject the PVS string data into the dictionary
+                    for ee in v[look]:
+                        if 'String' in ee:
+                            v[device][ee] = v[look][ee]
+                if verbose:
+                    result[device] = {}
+                    # PVAC_Pout may be missing depending on firmware - default to None
+                    result[device]['PVAC_Pout'] = v[device].get('PVAC_Pout')
+                    for e in v[device]:
+                        if 'PVAC_PVCurrent' in e or 'PVAC_PVMeasuredPower' in e or \
+                                'PVAC_PVMeasuredVoltage' in e or 'PVAC_PvState' in e or \
+                                'PVS_String' in e:
+                            result[device][e] = v[device][e]
+                else:  # simplified results
+                    for e in v[device]:
+                        if 'PVAC_PVCurrent' in e or 'PVAC_PVMeasuredPower' in e or \
+                                'PVAC_PVMeasuredVoltage' in e or 'PVAC_PvState' in e or \
+                                'PVS_String' in e:
+                            # Guard against more PVAC devices than devicemap entries
+                            name = e[-1] + devicemap[deviceidx % len(devicemap)]
+                            if 'Current' in e:
+                                idxname = 'Current'
+                            elif 'Power' in e:
+                                idxname = 'Power'
+                            elif 'Voltage' in e:
+                                idxname = 'Voltage'
+                            elif 'State' in e:
+                                idxname = 'State'
+                            elif 'Connected' in e:
+                                idxname = 'Connected'
+                                name = e[10] + devicemap[deviceidx % len(devicemap)]
+                            else:
+                                idxname = 'Unknown'
+                            if name not in result:
+                                result[name] = {}
+                            result[name][idxname] = v[device][e]
+                        # if
+                    # for
+                    deviceidx += 1
+                # else
+        # If no devices found pull from /api/solar_powerwall
+        if not v:
+            # Build a string map: A, B, C, D, A1, B2, etc.
+            string_map = []
+            for number in ['', '1', '2', '3', '4', '5', '6', '7', '8']:
+                for letter in ['A', 'B', 'C', 'D']:
+                    string_map.append(letter + number)
+            payload: dict = self.poll('/api/solar_powerwall') or {}
+            if payload and 'pvac_status' in payload:
+                # Strings are in PVAC status section
+                pvac = payload['pvac_status']
+                if 'string_vitals' in pvac:
+                    i = 0
+                    for string in pvac['string_vitals']:
+                        if i >= len(string_map):
+                            # More strings than the map can name - ignore the extras
+                            log.debug("strings(): more than %d string_vitals entries - ignoring extras"
+                                      % len(string_map))
+                            break
+                        name = string_map[i]
+                        result[name] = {}
+                        result[name]['Connected'] = string['connected']
+                        result[name]['Voltage'] = string['measured_voltage']
+                        result[name]['Current'] = string['current']
+                        result[name]['Power'] = string['measured_power']
+                        i += 1
+        # Return result
+        if jsonformat:
+            return json.dumps(result, indent=4, sort_keys=True)
+        else:
+            return result
+
+    # Pull Power Data
+    def site(self, verbose=False):
+        """ Grid Usage """
+        if self._no_client():
+            return None
+        return self.client.fetchpower('site', verbose)
+
+    def solar(self, verbose=False):
+        """" Solar Power Generation """
+        if self._no_client():
+            return None
+        return self.client.fetchpower('solar', verbose)
+
+    def battery(self, verbose=False):
+        """ Battery Power Flow """
+        if self._no_client():
+            return None
+        return self.client.fetchpower('battery', verbose)
+
+    def load(self, verbose=False):
+        """ Home Power Usage """
+        if self._no_client():
+            return None
+        return self.client.fetchpower('load', verbose)
+
+    # Helpful Power Aliases
+    def grid(self, verbose=False):
+        """ Grid Power Usage """
+        return self.site(verbose)
+
+    def home(self, verbose=False):
+        """ Home Power Usage """
+        return self.load(verbose)
+
+    # Shortcut Functions
+    def site_name(self) -> Optional[str]:
+        """ System Site Name """
+        payload = self.poll('/api/site_info/site_name')
+        try:
+            site_name = payload['site_name']
+        except Exception as exc:
+            log.debug(f"ERROR unable to parse payload '{payload}' for site_name: {exc}")
+            site_name = None
+        return site_name
+
+    def status(self, param=None, jsonformat=False) -> Union[dict, str, None]:
+        """ 
+        Return Systems Status
+
+        Args: 
+          param = only respond with this param data
+          jsonformat = If True, return JSON format otherwise return Python Dictionary
+
+          Available param:
+            din = payload['din']
+            start_time = payload['start_time-time']
+            up_time_seconds = payload['up_time_seconds']
+            is_new = payload['is_new']
+            version = payload['version']
+            githash = payload['git_hash']
+            commission_count = payload['commission_count']
+            device_type = payload['device_type']
+            sync_type = payload['sync_type']
+            leader = payload['leader']
+            followers = payload['followers']
+            cellular_disabled = payload['cellular_disabled']
+        """
+        if self._no_client():
+            return None
+        payload = self.client.poll('/api/status')
+        if payload is None:
+            return None
+        if param is None:
+            if jsonformat:
+                return json.dumps(payload, indent=4, sort_keys=True)
+            else:
+                return payload
+        else:
+            if param in payload:
+                return payload[param]
+            else:
+                log.debug('ERROR unable to find %s in payload: %r' % (param, payload))
+                return None
+
+    def version(self, int_value=False) -> Union[int, str, None]:
+        """ Firmware Version """
+        if not int_value:
+            return self.status('version')
+        # Convert version to integer
+        return parse_version(self.status('version'))
+
+    def uptime(self) -> Union[str, None]:
+        """ System Uptime """
+        return self.status('up_time_seconds')
+
+    def din(self) -> Optional[str]:
+        """ System DIN """
+        return self.status('din')
+
+    def temps(self, jsonformat=False) -> Optional[Union[dict, str]]:
+        """
+        Temperatures of Powerwalls
+
+        Powerwall 2 reports the thermal controller ambient (TETHC blocks,
+        THC_AmbientTemp). Powerwall 3 has no thermal controller; it reports the
+        hottest battery-pack reading (TEPOD blocks, HVP_PackTempMax) for each
+        Powerwall 3 and expansion pack - None for a battery without a reading
+        while others report one, so positions match the /pod numbering. All
+        values are degrees C. The full PW3 breakdown (pack min, shunt, inverter
+        ambient) is in vitals().
+
+        Args:
+          jsonformat = If True, return JSON format otherwise return Python Dictionary
+        """
+        temps = {}
+        devices: dict = self.vitals() or {}
+        # PW3 battery blocks always carry HVP_PackTempMax (None when unavailable).
+        # Once any reports a reading, list every PW3 block - None included - so the
+        # proxy's /temps/pw PWn numbering stays aligned with /pod; with no readings
+        # at all, list none (unchanged {} on firmware without the signal).
+        pw3_blocks = [d for d in devices if d.startswith('TEPOD')
+                      and isinstance(devices[d], dict) and 'HVP_PackTempMax' in devices[d]]
+        pw3_has_reading = any(devices[d]['HVP_PackTempMax'] is not None for d in pw3_blocks)
+        for device in devices:
+            if device.startswith('TETHC'):
+                temps[device] = devices[device].get('THC_AmbientTemp')
+            elif pw3_has_reading and device in pw3_blocks:
+                temps[device] = devices[device]['HVP_PackTempMax']
+        if jsonformat:
+            return json.dumps(temps, indent=4, sort_keys=True)
+        else:
+            return temps
+
+    def alerts(self, jsonformat=False, alertsonly=True) -> Union[list, str]:
+        """ 
+        Return Array of Alerts from all Devices 
+        
+        Args: 
+          jsonformat = If True, return JSON format otherwise return Python Dictionary
+          alertonly  = If True, return only alerts without device name
+        """
+        alerts = set()
+        device_alerts = set()  # (device, alert) tuples - dicts are unhashable, rebuilt at return
+        devices: dict = self.vitals() or {}
+        if devices:
+            for device in devices:
+                if not 'alerts' in devices[device]:
+                    continue
+                for i in devices[device]['alerts']:
+                    if alertsonly:
+                        alerts.add(i)
+                        continue
+                    device_alerts.add((device, i))
+        elif not devices and alertsonly is True:
+            # Vitals API is not present in firmware versions > 23.44 for local mode.
+            # This is a workaround to get alerts from the /api/solar_powerwall endpoint
+            data: dict = self.poll('/api/solar_powerwall') or {}
+            pvac_alerts = data.get('pvac_alerts') or {}
+            for alert, value in pvac_alerts.items():
+                if value is True:
+                    alerts.add(alert)
+            pvs_alerts = data.get('pvs_alerts') or {}
+            for alert, value in pvs_alerts.items():
+                if value is True:
+                    alerts.add(alert)
+
+        # Augment with inferred alerts from the grid_status
+        grid_status = self.poll('/api/system_status/grid_status')
+        if grid_status:
+            alert = grid_status.get('grid_status')
+            if grid_status.get('grid_services_active'):
+                alerts.add('GridServicesActive')
+            elif alert:
+                alerts.add(alert)
+
+        # In the future, if more replacements are needed, create a utility function here.
+        normalized_alerts = list({s.replace("SystemGridConnected", "SystemConnectedToGrid") for s in alerts})
+        if not alertsonly:
+            # Append per-device alerts as {device: alert} entries
+            normalized_alerts += [{device: alert} for device, alert in sorted(device_alerts)]
+
+        if jsonformat:
+            return json.dumps(normalized_alerts, indent=4, sort_keys=True)
+        return normalized_alerts
+
+    def get_reserve(self, scale=True, force=False) -> Optional[float]:
+        """
+        Get Battery Reserve Percentage  
+        Tesla App reserves 5% of battery => ( (batterylevel / 0.95) - (5 / 0.95) )
+
+        Args:
+            scale    = If True (default) use Tesla's 5% reserve calculation
+        """
+        data = self.poll('/api/operation', force=force)
+        if data is not None and 'backup_reserve_percent' in data:
+            percent = float(data['backup_reserve_percent'])
+            if scale:
+                # Get percentage based on Tesla App scale
+                percent = max(0, float((percent / 0.95) - (5 / 0.95)))
+            return percent
+        return None
+
+    def get_mode(self, force=False) -> Optional[float]:
+        """
+        Get Battery Operation Mode
+        """
+        data = self.poll('/api/operation', force=force)
+        if data and data.get('real_mode'):
+            return data['real_mode']
+        return None
+
+    def set_reserve(self, level: float) -> Optional[dict]:
+        """
+        Set battery reserve level.
+
+        Args:
+            level:   Set battery reserve level in percents (range of 0-100 is accepted)
+
+        Returns:
+            Dictionary with operation results.
+        """
+        return self.set_operation(level=level)
+
+    def set_mode(self, mode: str) -> Optional[dict]:
+        """
+        Set battery operation mode.
+
+        Args:
+            mode:    Set battery operation mode (self_consumption, backup, autonomous, etc.)
+
+        Returns:
+            Dictionary with operation results.
+        """
+        return self.set_operation(mode=mode)
+
+    def set_operation(self, level: Optional[float] = None, mode: Optional[str] = None,
+                      jsonformat: bool = False) -> Optional[Union[dict, str]]:
+        """
+        Set battery operation mode and reserve level.
+
+        Args:
+            level:   Set battery reserve level in percents (range of 0-100 is accepted)
+            mode:    Set battery operation mode (self_consumption, backup, autonomous, etc.)
+            jsonformat:  Set to True to receive json formatted string
+
+        Returns:
+            Dictionary with operation results, if jsonformat is False, else a JSON string
+        """
+        if level is not None and (level < 0 or level > 100):
+            log.error("Level can be in range of 0 to 100 only.")
+            return None
+
+        # The local gateway /api/operation is a full overwrite: an omitted field
+        # would clobber the current setting, so back-fill from the live values.
+        # Cloud/fleetapi/tedapi accept partial payloads, and back-filling there is
+        # actively harmful: Tesla applies BACKUP_RESERVE and OPERATION_MODE as two
+        # asynchronous commands, so a back-filled reserve write races the mode
+        # change and the mode command can be silently dropped (observed on PW3
+        # whenever the current reserve is 0). Partial-payload backends therefore
+        # write only the fields the caller actually set.
+        full_overwrite = isinstance(self.client, PyPowerwallLocal)
+
+        payload = {}
+        if level is not None:
+            # Explicit reserve: keep the numeric value. In particular 0 must stay
+            # 0 - the legacy coercion of 0 to boolean False (a v1-local-API-era
+            # "leave unchanged" marker) made the cloud path treat every
+            # reserve-0 write as a real BACKUP_RESERVE=0 command racing any mode
+            # change in the same call.
+            payload['backup_reserve_percent'] = level
+        elif full_overwrite:
+            # Back-fill the current reserve so the write does not change it. The
+            # local backend passes the payload verbatim to the gateway's raw-scale
+            # /api/operation, so read it back raw.
+            level = self.get_reserve(scale=False)
+            if level is None:
+                log.error("Unable to determine current reserve level - unable to set operation.")
+                return None
+            payload['backup_reserve_percent'] = level
+
+        if mode:
+            payload['real_mode'] = mode
+        elif full_overwrite:
+            mode = self.get_mode()
+            if mode:
+                payload['real_mode'] = mode
+
+        if not payload and not full_overwrite:
+            # Partial-payload backends raise on an empty body; without a
+            # caller-set field there is nothing to write, so fail soft like
+            # the other invalid-input paths instead of raising.
+            log.error("No operation to set - pass level and/or mode.")
+            return None
+
+        log.debug(f"Setting operation: {payload}")
+
+        result = self.post(api='/api/operation', payload=payload, din=self.din(), jsonformat=jsonformat)
+        return result
+
+    def schedule_max_backup(self, duration_seconds=7200):
+        """Schedule manual backup event (max backup / storm watch mode) via v1r TEGMessages."""
+        if self.tedapi_mode != "v1r":
+            log.error("schedule_max_backup requires v1r LAN mode (tedapi_mode=%s)", self.tedapi_mode)
+            return None
+        return self.client.schedule_max_backup(duration_seconds=duration_seconds)
+
+    def cancel_max_backup(self):
+        """Cancel the current manual backup event via v1r TEGMessages."""
+        if self.tedapi_mode != "v1r":
+            log.error("cancel_max_backup requires v1r LAN mode (tedapi_mode=%s)", self.tedapi_mode)
+            return None
+        return self.client.cancel_max_backup()
+
+    def get_backup_events(self):
+        """Get current backup events via v1r TEGMessages."""
+        if self.tedapi_mode != "v1r":
+            log.error("get_backup_events requires v1r LAN mode (tedapi_mode=%s)", self.tedapi_mode)
+            return None
+        return self.client.get_backup_events()
+
+    # noinspection PyShadowingBuiltins
+    def grid_status(self, output_type="string", type=None) -> Optional[Union[str, int]]:
+        """
+        Get the status of the grid  
+        
+        Args:
+            output_type == "string" (default) returns: "UP", "DOWN", "SYNCING"
+            output_type == "json" return raw JSON
+            output_type == "numeric" return -1 (Syncing), 0 (DOWN), 1 (UP)
+
+            If type (deprecated) is set, it will override output_type
+        """
+        if type:
+            output_type = type # Backward compatibility
+        if output_type not in ['json', 'string', 'numeric']:
+            log.error(f"Invalid value for parameter 'output_type': {output_type}")
+            raise ValueError("Invalid value for parameter 'output_type': " + str(output_type))
+
+        try:
+            payload: dict = self.poll('/api/system_status/grid_status')
+
+            if payload is None:
+                log.error("Failed to get /api/system_status/grid_status")
+                return None
+
+            if output_type == "json":
+                return json.dumps(payload, indent=4, sort_keys=True)
+
+            gridmap = {'SystemGridConnected': {'string': 'UP', 'numeric': 1},
+                       'SystemIslandedActive': {'string': 'DOWN', 'numeric': 0},
+                       'SystemTransitionToGrid': {'string': 'SYNCING', 'numeric': -1},
+                       'SystemTransitionToIsland': {'string': 'SYNCING', 'numeric': -1},
+                       'SystemIslandedReady': {'string': 'SYNCING', 'numeric': -1},
+                       'SystemMicroGridFaulted': {'string': 'DOWN', 'numeric': 0},
+                       'SystemWaitForUser': {'string': 'DOWN', 'numeric': 0}}
+
+            grid_status = payload.get('grid_status')
+            status = gridmap.get(grid_status, {}).get(output_type)
+            if status is None:
+                log.warning(f"Unable to parse payload '{payload}' for grid_status of output_type: {output_type}")
+            return status
+        except Exception as e:
+            log.error(f"grid_status(): Exception {type(e).__name__}: {e}")
+            raise
+
+    def system_status(self, jsonformat=False) -> Optional[Union[dict, str]]:
+        """
+        Get the full system status and basically do a straight passthrough return
+
+        Some data points of note are
+            nominal_full_pack_energy
+            nominal_energy_remaining
+            system_island_state - returns same value as grid_status
+            available_blocks - number of batteries
+            battery_blocks - array of batteries
+                PackageSerialNumber
+                disabled_reasons
+                nominal_energy_remaining
+                nominal_full_pack_energy
+                v_out - voltage out
+                f_out - frequency out
+                energy_charged
+                energy_discharged
+                backup_ready
+            grid_faults - array of faults
+
+        Args:
+            jsonformat = If True, return JSON format otherwise return Python Dictionary
+        """
+        payload: dict = self.poll('/api/system_status')
+        if payload is None:
+            return None
+
+        if jsonformat:
+            return json.dumps(payload, indent=4, sort_keys=True)
+        else:
+            return payload
+
+    def battery_blocks(self, jsonformat=False):
+        """
+        Get detailed information about each battery. If you want to get aggregate power information 
+        on all the batteries, use battery() 
+
+        This function actually makes two API calls. The primary data is harvested from the 
+        battery_blocks section in /api/system_status but the temperature data is only 
+        available via /api/devices/vitals
+
+        Some data points of note are
+            battery_blocks - array of batteries
+                disabled_reasons
+                nominal_energy_remaining
+                nominal_full_pack_energy
+                v_out - voltage out
+                f_out - frequency out
+                energy_charged
+                energy_discharged
+                backup_ready
+            grid_faults - array of faults
+
+        Args:
+            jsonformat = If True, return JSON format otherwise return Python Dictionary
+        """
+        system_status: dict = self.system_status()
+        if system_status is None:
+            return None
+
+        devices: dict = self.vitals() or {}
+
+        result = {}
+        # copy the info from system_status into result
+        # but change the key to the battery serial number
+        # battery_blocks and PackageSerialNumber may be missing depending on
+        # firmware/mode - guard with .get() instead of direct indexing
+        for bat in system_status.get('battery_blocks') or []:
+            sn = bat.get('PackageSerialNumber')
+            bat_res = {}
+            for j in bat:
+                if j != 'PackageSerialNumber':
+                    bat_res[j] = bat[j]
+            result[sn] = bat_res
+
+        # now merge in the "interesting" data from vitals
+        # Right now we're just pulling in the temp and state from the TETHC block
+        # There is also info in TPOD and TINV that could be associated with the battery.
+        for device in devices:
+            if device.startswith("TETHC--"):
+                sn = device.split("--")[2]
+                bat_res = {
+                    'THC_State': devices[device].get('THC_State'),
+                    'temperature': devices[device].get('THC_AmbientTemp')
+                }
+                # Some firmware or modes may return vitals entries before /api/system_status
+                # includes corresponding battery_blocks. Guard against missing keys.
+                if sn not in result:
+                    result[sn] = {}
+                result[sn].update(bat_res)
+
+        if jsonformat:
+            return json.dumps(result, indent=4, sort_keys=True)
+        else:
+            return result
+
+    def get_time_remaining(self) -> Optional[float]:
+        """
+        Get the backup time remaining on the battery
+
+        Returns:
+            The time remaining in hours
+        """
+        if self._no_client():
+            return None
+        return self.client.get_time_remaining()
+
+    def set_grid_charging(self, mode) -> Optional[dict]:
+        """
+        Enable or disable grid charging
+
+        Args:
+            mode: Set to True to enable grid charging, False to disable it
+
+        Returns:
+            Dictionary with operation results.
+        """
+        if self._no_client():
+            return None
+        return self.client.set_grid_charging(mode)
+
+    def get_grid_charging(self) -> Optional[bool]:
+        """
+        Get the current grid charging mode
+
+        Note:
+            This function requires FleetAPI or Cloud mode. It is not available
+            in local TEDAPI mode. Returns None if not supported by the current mode.
+
+        Returns:
+            True if grid charging is enabled, False if it is disabled, None if unsupported
+        """
+        if self._no_client():
+            return None
+        return self.client.get_grid_charging()
+
+    def set_grid_export(self, mode: str) -> Optional[dict]:
+        """
+        Set grid export mode
+
+        Args:
+            mode: Set grid export mode (battery_ok, pv_only, or never)
+
+        Returns:
+            Dictionary with operation results.
+        """
+        # Check for valid mode
+        if mode not in ['battery_ok', 'pv_only', 'never']:
+            raise ValueError(f"Invalid value for parameter 'mode': {mode}")
+        if self._no_client():
+            return None
+        return self.client.set_grid_export(mode)
+
+    def get_grid_export(self) -> Optional[str]:
+        """
+        Get the current grid export mode
+
+        Note:
+            This function requires FleetAPI or Cloud mode. It is not available
+            in local TEDAPI mode. Returns None if not supported by the current mode.
+
+        Returns:
+            The current grid export mode, or None if unsupported
+        """
+        if self._no_client():
+            return None
+        return self.client.get_grid_export()
+
+    def go_off_grid(self, confirm: bool = False) -> Optional[dict]:
+        """
+        Physically disconnect the Powerwall from the grid (open contactor).
+
+        USE WITH EXTREME CARE: this operates the physical grid contactor.
+        While islanded, the home runs on battery + solar alone — a depleted
+        battery means the home loses power until reconnect_grid() succeeds.
+        Do not automate without handling those failure modes; verify grid
+        status after the command rather than assuming success.
+
+        Sends setIslandModeRequest(mode=6, force=True) which physically
+        opens the grid contactor, islanding the home. Solar continues
+        producing and the battery serves home load. Causes ~30s solar
+        dropout during the contactor transition.
+
+        Note:
+            This operation requires explicit confirmation. Pass
+            confirm=True to send the command.
+
+            On both Powerwall 2 and Powerwall 3, this requires a signed
+            command: either a signed RoutableMessage via the cloud
+            device_command endpoint's routable_message field, or — when a
+            v1r RSA key is paired — Tesla's signed setIslandMode command
+            sent locally over the TEDAPI v1r transport. The unsigned
+            grpc_command path is
+            accepted by the gateway but does not physically operate the
+            contactor. The local REST endpoint /api/v2/islanding/mode
+            requires installer-level auth and is not usable with the
+            customer login role.
+
+            force=True is required — without it the gateway acknowledges
+            the command but does not open the contactor.
+
+        Returns:
+            Dictionary with operation results, or None if unsupported.
+        """
+        if not confirm:
+            log.error("go_off_grid requires confirm=True")
+            return None
+        if hasattr(self.client, 'go_off_grid'):
+            return self.client.go_off_grid()
+        log.error("go_off_grid is not supported by %s backend", type(self.client).__name__)
+        return None
+
+    def reconnect_grid(self) -> Optional[dict]:
+        """
+        Reconnect the Powerwall to the grid (close contactor).
+
+        USE WITH EXTREME CARE: this operates the physical grid contactor.
+        Verify grid status after the command rather than assuming success.
+
+        Sends setIslandModeRequest(mode=1) which physically closes the
+        grid contactor, reconnecting the home to the utility grid.
+
+        Returns:
+            Dictionary with operation results, or None if unsupported.
+        """
+        if hasattr(self.client, 'reconnect_grid'):
+            return self.client.reconnect_grid()
+        log.error("reconnect_grid is not supported by %s backend", type(self.client).__name__)
+        return None
+
+    def _validate_init_configuration(self):
+
+        # Basic user input validation for starters. Can be expanded to limit other parameters such as cache
+        # expiration range, timeout range, etc
+
+        # Check for valid hostname/IP address.
+        # Supports optional :port suffix (e.g. "192.168.1.50:8443") — strip the port
+        # before regex validation since IPV4_6_REGEX and HOST_REGEX only match bare hosts.
+        #
+        # IMPORTANT: only attempt port-stripping when the value does NOT already validate
+        # as a bare host/IP. This prevents false port detection in IPv6 addresses, where
+        # colons are part of the address itself (e.g. "2001:db8::1" must not have its
+        # trailing ":1" mistaken for a port number).
+        if self.host:
+            host_part = self.host
+            if (
+                isinstance(host_part, str) and
+                not IPV4_6_REGEX.match(host_part) and
+                not HOST_REGEX.match(host_part)
+            ):
+                # Not a bare host — check if a trailing :port suffix can be stripped.
+                # Only consider single-colon strings (hostname:port or IPv4:port);
+                # multi-colon strings are IPv6 or malformed and must not be treated as host:port.
+                if host_part.count(":") == 1:
+                    last_part = host_part.rsplit(":", 1)[1]
+                    if last_part.isdigit():
+                        port = int(last_part)
+                        if not (1 <= port <= 65535):
+                            raise PyPowerwallInvalidConfigurationParameter(
+                                f"Invalid port in host '{self.host}': port {port} is out of the "
+                                f"valid TCP range 1-65535.")
+                        host_part = host_part.rsplit(":", 1)[0]
+            if (
+                not isinstance(host_part, str) or
+                (not IPV4_6_REGEX.match(host_part) and not HOST_REGEX.match(host_part))
+            ):
+                raise PyPowerwallInvalidConfigurationParameter(f"Invalid powerwall host: '{self.host}'. Must be in the "
+                                                               f"form of IP address or a valid form of a hostname or FQDN.")
+            # TODO: IPv6 support - bare IPv6 addresses (e.g. "2001:db8::1") pass validation via
+            # IPV4_6_REGEX but URL construction produces malformed URLs. If IPv6 is ever needed,
+            # detect a validated bare IPv6 host here and wrap it in brackets so that all downstream
+            # callers automatically produce RFC 2732-compliant URLs (e.g. "https://[2001:db8::1]/...").
+
+        # If cloud mode requested, check appropriate parameters
+        if self.cloudmode and not self.fleetapi:
+            # Ensure email is set and syntactically correct
+            if not self.email or not isinstance(self.email, str) or not EMAIL_REGEX.match(self.email):
+                raise PyPowerwallInvalidConfigurationParameter(f"A valid email address is required to run in "
+                                                               f"cloud mode: '{self.email}' did not pass validation.")
+
+            # Ensure we can write to the provided authpath
+            dirname = self.authpath
+            if not dirname:
+                log.debug("No authpath provided, using current directory.")
+                dirname = '.'
+            self._check_if_dir_is_writable(dirname, "authpath")
+        elif self.fleetapi:
+            # Ensure we can write to the configfile (or its directory if it doesn't exist yet)
+            self.configfile = os.path.join(self.authpath, CONFIGFILE)
+            if os.path.exists(self.configfile):
+                if os.access(self.configfile, os.W_OK):
+                    log.debug(f"Config file '{self.configfile}' is writable.")
+                else:
+                    raise PyPowerwallInvalidConfigurationParameter(f"Config file '{self.configfile}' is not writable.")
+            else:
+                dirname = self.authpath or '.'
+                self._check_if_dir_is_writable(dirname, "authpath")
+        else:
+            # If local mode, check appropriate parameters, and ensure we can write to the provided cachefile
+            dirname = os.path.dirname(self.cachefile)
+            if not dirname:
+                log.debug("No cachefile provided, using current directory.")
+                dirname = '.'
+            self._check_if_dir_is_writable(dirname, "cachefile")
+
+    @staticmethod
+    def _check_if_dir_is_writable(dirpath, name=""):
+        # Ensure we can write to the provided authpath
+        if not os.path.exists(dirpath):
+            try:
+                os.makedirs(dirpath, exist_ok=True)
+            except Exception as exc:
+                raise PyPowerwallInvalidConfigurationParameter(f"Unable to create {name} directory at "
+                                                               f"'{dirpath}': {exc}") from exc
+        elif not os.path.isdir(dirpath):
+            raise PyPowerwallInvalidConfigurationParameter(f"'{dirpath}' must be a directory ({name}).")
+        else:
+            if not os.access(dirpath, os.W_OK):
+                raise PyPowerwallInvalidConfigurationParameter(f"Directory '{dirpath}' is not writable for {name}. "
+                                                               f"Check permissions.")