Initial commit: FranklinWH AGATE client library reverse engineered from Family Energy app

- Reverse engineered network I/O stack for AGATE device
- Bluetooth LE and Wi-Fi onboard communication support
- Discovered operations: queryAgateInfo, queryDeviceInfoHttp, queryModesByHttp, queryConnectWifi, connectViaBluetooth, startBluetoothHeartbeat
- Cloud API endpoints identified: e-api.franklinwh.com, energy.franklinwh.com, hes-gateway
- Python library structure with client, bluetooth, wifi, api modules
- Documentation for reverse engineering findings

README.md

@@ -0,0 +1,50 @@
+# FranklinWH AGATE Client
+
+Python client library for interacting with FranklinWH AGATE energy storage device.
+
+## Reverse Engineering Summary
+
+This library was reverse engineered from the official FranklinWH Family Energy Android app (`com.Franklinwh.FamilyEnergy`).
+
+### Network I/O Stack
+
+The device communicates via:
+- **Bluetooth LE**: Direct connection to AGATE device
+- **Onboard Wi-Fi**: Local network connection via device hotspot
+- **Cloud APIs**: `https://e-api.franklinwh.com`, `https://energy.franklinwh.com`
+
+### Key Operations Discovered
+
+- `queryAgateInfo` - Get device information
+- `queryDeviceInfoHttp` - HTTP device info query
+- `queryModesByHttp` - Query operating modes
+- `queryConnectWifi` - Wi-Fi connection management
+- `connectViaBluetooth` - Bluetooth connection
+- `startBluetoothHeartbeat` - Keepalive
+- `BluetoothManager` - Bluetooth service management
+- `WifiOnboarding` - Wi-Fi setup flows
+
+### Endpoints Found
+
+- `https://e-api.franklinwh.com/api/appapi`
+- `https://energy.franklinwh.com/api-energy/deviceGroup/electric`
+- `https://energy.franklinwh.com/hes-gateway`
+- `https://dev.franklinwh.com/hes-gateway`
+- `https://uat.franklinwh.com/api-vpp-portal`
+
+## Usage
+
+```python
+from franklinwh_agate_client import AgateClient
+
+client = AgateClient()
+device_info = client.query_agate_info(device_id)
+```
+
+## Development
+
+This library is a work in progress. Additional operations will be added as reverse engineering continues.
+
+## License
+
+Internal use only. Reverse engineering findings for research purposes.

franklinwh_agate_client/__init__.py

@@ -0,0 +1,14 @@
+"""
+FranklinWH AGATE Device Client
+
+Reverse engineered from com.Franklinwh.FamilyEnergy Android app.
+Provides access to Bluetooth and Wi-Fi network I/O stack for AGATE devices.
+"""
+
+from .client import AgateClient
+from .bluetooth import BluetoothManager
+from .wifi import WifiManager
+from .api import ApiClient
+
+__version__ = "0.1.0"
+__all__ = ["AgateClient", "BluetoothManager", "WifiManager", "ApiClient"]

franklinwh_agate_client/api.py

@@ -0,0 +1,22 @@
+"""
+API Client for FranklinWH cloud services.
+"""
+
+class ApiClient:
+    """Client for FranklinWH cloud API endpoints."""
+    
+    BASE_URLS = {
+        "api": "https://e-api.franklinwh.com/api/appapi",
+        "energy": "https://energy.franklinwh.com/api-energy/deviceGroup/electric",
+        "gateway": "https://energy.franklinwh.com/hes-gateway",
+        "dev": "https://dev.franklinwh.com/hes-gateway",
+        "uat": "https://uat.franklinwh.com/api-vpp-portal",
+        "test": "https://test.franklinwh.com",
+    }
+    
+    def __init__(self, base_url=None):
+        self.base_url = base_url or self.BASE_URLS["api"]
+    
+    def query_device_info(self, device_id):
+        """Query device information from cloud API."""
+        pass

franklinwh_agate_client/bluetooth.py

@@ -0,0 +1,27 @@
+"""
+Bluetooth Manager for AGATE device communication.
+"""
+
+class BluetoothManager:
+    """Manages Bluetooth LE connection to AGATE device."""
+    
+    SERVICE_UUIDS = []
+    DEVICE_NAME_PREFIX = "AGATE"
+    
+    def __init__(self):
+        self.connected = False
+        self.heartbeat_active = False
+    
+    def connect_via_bluetooth(self, device_address):
+        """Connect to AGATE device via Bluetooth."""
+        # Reverse engineered operation: connectViaBluetooth
+        pass
+    
+    def start_bluetooth_heartbeat(self):
+        """Start Bluetooth heartbeat keepalive."""
+        # Reverse engineered operation: startBluetoothHeartbeat
+        pass
+    
+    def disconnect_bluetooth(self):
+        """Disconnect from AGATE device."""
+        pass

franklinwh_agate_client/client.py

@@ -0,0 +1,26 @@
+"""
+Agate Client - Main interface for AGATE device operations.
+"""
+
+class AgateClient:
+    """Main client for FranklinWH AGATE device operations."""
+    
+    def __init__(self, device_id=None):
+        self.device_id = device_id
+        self.bluetooth_manager = None
+        self.wifi_manager = None
+    
+    def query_agate_info(self, device_id=None):
+        """Query AGATE device information."""
+        # Reverse engineered operation: queryAgateInfo
+        pass
+    
+    def query_device_info_http(self, device_id=None):
+        """Query device info via HTTP."""
+        # Reverse engineered operation: queryDeviceInfoHttp
+        pass
+    
+    def query_modes_by_http(self, device_id=None):
+        """Query operating modes via HTTP."""
+        # Reverse engineered operation: queryModesByHttp
+        pass

franklinwh_agate_client/wifi.py

@@ -0,0 +1,23 @@
+"""
+Wi-Fi Manager for AGATE device network operations.
+"""
+
+class WifiManager:
+    """Manages Wi-Fi connection to AGATE device onboard hotspot."""
+    
+    def __init__(self):
+        self.connected = False
+    
+    def query_connect_wifi(self, ssid, password=None):
+        """Query/connect to AGATE Wi-Fi."""
+        # Reverse engineered operation: queryConnectWifi
+        pass
+    
+    def wifi_onboarding_add_wifi(self, ssid, password):
+        """Add Wi-Fi network via onboarding."""
+        # Reverse engineered operation: wifiOnboardingAddWifi
+        pass
+    
+    def get_wifi_signal_strength(self):
+        """Get current Wi-Fi signal strength."""
+        pass

setup.json

@@ -0,0 +1,15 @@
+{
+    "name": "franklinwh-agate-client",
+    "version": "0.1.0",
+    "description": "Python client library for FranklinWH AGATE device network I/O (Bluetooth & Wi-Fi) - reverse engineered",
+    "author": "robot",
+    "author_email": "robot@westerntechnologies.duckdns.org",
+    "packages": ["franklinwh_agate_client"],
+    "python_requires": ">=3.8",
+    "classifiers": [
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3"
+    ]
+}