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.