python-openevse-http 1.6.0__tar.gz → 1.7.1__tar.gz

{python_openevse_http-1.6.0 → python_openevse_http-1.7.1}/.agents/skills/openevse-api-guide/SKILL.md

@@ -19,6 +19,9 @@ The main client `OpenEVSE` combines several mixins:
 
 ## Endpoints & RAPI Commands Reference
 
+For a comprehensive matrix of all endpoints across firmware generations (v2.x, v3.x, and active v4.x/v5.x), field variations (`/config`, `/status`), and RAPI fallbacks, see:
+- [OpenEVSE Endpoints Matrix](file:///home/firstof9/github/python-openevse-http/.agents/skills/openevse-api-guide/references/endpoints_matrix.md)
+
 | Action | HTTP Endpoint (v4+) | RAPI Command (v2/v3) | Method |
 | :--- | :--- | :--- | :--- |
 | Status | `/status` | N/A | GET |
@@ -29,6 +32,17 @@ The main client `OpenEVSE` combines several mixins:
 | Divert Mode | `/divertmode` or `/config` | N/A | POST |
 | Module Restart | `/restart` (`device: gateway\|evse`) | `$FR` (evse restart) | POST |
 | Firmware Update | `/update` | N/A | POST (multipart or JSON URL) |
+| Relay Stuck Recovery | `/relay/recovery` | `$FK` (controller stuck recovery) | POST |
+| Relay Health Reset | `/relay/reset` | `$FH` (controller health reset) | POST |
+| Cable Temperature | `/cabletemp` | `$GN` / `$SN` (cable temp monitor) | GET / POST |
+| Time Settings | `/time` (v4+) / `/settime` (v3) | `$S1` (RTC set) | GET / POST |
+| Event Logs | `/logs` / `/logs/{index}` | N/A | GET |
+| Certificates | `/certificates` (`/root`, `/{id}`) | N/A | GET / POST / DELETE |
+| RFID Tag Pairing | `/rfid/add` | N/A | POST |
+| RFID Users | `/rfid/users` | N/A | GET / POST / DELETE |
+
+> [!NOTE]
+> Firmware development for **v2.x (ESP8266)** and **v3.x (ESP32)** has ended. Active development occurs in **`OpenEVSE/openevse_esp32_firmware`** (v4.x/v5.x). Always check `openevse_esp32_firmware` as the primary reference when evaluating new endpoints, features, or behaviors.
 
 ## Firmware Version Branching
 
@@ -67,19 +81,20 @@ from .exceptions import CommandFailedError, UnknownStateError, UnsupportedFeatur
 
 When adding, modifying, or debugging endpoints and RAPI commands, cross-reference against the upstream OpenEVSE firmware sources:
 
-- **WiFi Gateway Firmware (v3/v4/v5)**: [`OpenEVSE/ESP32_WiFi_V4.x`](https://github.com/OpenEVSE/ESP32_WiFi_V4.x)
-- **Legacy WiFi Firmware (v2)**: [`OpenEVSE/ESP8266_WiFi_v2.x`](https://github.com/OpenEVSE/ESP8266_WiFi_v2.x)
+- **WiFi Gateway Firmware (Current ESP32 v4/v5)**: [`OpenEVSE/openevse_esp32_firmware`](https://github.com/OpenEVSE/openevse_esp32_firmware) (formerly [`OpenEVSE/ESP32_WiFi_V4.x`](https://github.com/OpenEVSE/ESP32_WiFi_V4.x))
+- **WiFi Gateway Firmware (Legacy ESP32 v3.x)**: [`OpenEVSE/ESP32_WiFi_V3.x`](https://github.com/OpenEVSE/ESP32_WiFi_V3.x)
+- **Legacy WiFi Firmware (ESP8266 v2.x)**: [`OpenEVSE/ESP8266_WiFi_v2.x`](https://github.com/OpenEVSE/ESP8266_WiFi_v2.x)
 - **OpenEVSE Controller Firmware (RAPI)**: [`OpenEVSE/open_evse`](https://github.com/OpenEVSE/open_evse)
 
 ### What to Verify in Firmware Sources:
 1. **Route & Method Handlers**:
-   - Check `src/http.cpp`, `src/web_server.cpp`, or `src/web_server.h` in `ESP32_WiFi_V4.x` to confirm HTTP methods (`GET`, `POST`, `PATCH`, `DELETE`).
+   - Check `src/web_server.cpp`, `src/web_server_config.cpp`, `src/web_server_*.cpp` (in `openevse_esp32_firmware` / `ESP32_WiFi_V4.x`) or `src/web_server.cpp` (in `ESP32_WiFi_V3.x` / `ESP8266_WiFi_v2.x`) to confirm HTTP methods (`GET`, `POST`, `PATCH`, `DELETE`).
    - Confirm expected query parameters or JSON body fields (e.g. `divertmode=...`, `{"device": "gateway"}`, `{"charge_current": ...}`).
 2. **Response Formats & Statuses**:
    - Verify success and error response payloads (e.g., `{"msg": "done"}`, `{"result": "OK", "msg": "..."}`, or plain string messages like `"Current Shaper state changed"`).
    - Update `SUCCESS_ANSWERS` in `openevsehttp/const.py` if new success indicators are introduced.
 3. **Firmware Version Thresholds**:
-   - Check git history or release tags in `ESP32_WiFi_V4.x` to determine when a route or feature was introduced, ensuring accurate `_version_check("x.y.z")` values.
+   - Check git history or release tags across `openevse_esp32_firmware`, `ESP32_WiFi_V3.x`, and `ESP8266_WiFi_v2.x` to determine when a route or feature was introduced, ensuring accurate `_version_check("x.y.z")` values.
 4. **RAPI Command Specifications**:
    - Check `src/rapi.cpp` or OpenEVSE controller docs for valid RAPI commands (e.g., `$SC`, `$FE`, `$FS`, `$FR`, `$ST`) and return formats (`$OK`, `$NK`).
 5. **Mock Test Fixtures**:

python_openevse_http-1.7.1/.agents/skills/openevse-api-guide/references/endpoints_matrix.md

@@ -0,0 +1,110 @@
+# OpenEVSE HTTP API & Firmware Endpoint Matrix
+
+This reference document compiles all known HTTP REST API endpoints, WebSocket paths, and RAPI fallback commands across OpenEVSE WiFi firmware generations:
+- **v4.x / v5.x (Active Development)**: [`OpenEVSE/openevse_esp32_firmware`](https://github.com/OpenEVSE/openevse_esp32_firmware) (formerly `ESP32_WiFi_V4.x`).
+- **v3.x (Legacy ESP32 - EOL)**: [`OpenEVSE/ESP32_WiFi_V3.x`](https://github.com/OpenEVSE/ESP32_WiFi_V3.x) (e.g. v3.3.1).
+- **v2.x (Legacy ESP8266 - EOL)**: [`OpenEVSE/ESP8266_WiFi_v2.x`](https://github.com/OpenEVSE/ESP8266_WiFi_v2.x) (up to v2.9.1).
+- **Controller Firmware**: [`OpenEVSE/open_evse`](https://github.com/OpenEVSE/open_evse) (RAPI backend).
+
+> [!IMPORTANT]
+> **Active Development Warning**: Development on **v2.x** and **v3.x** has ended. Active development occurs exclusively on **v4.x / v5.x** in `OpenEVSE/openevse_esp32_firmware`. Whenever validating new features, routes, or bugfixes, always inspect `OpenEVSE/openevse_esp32_firmware` as the primary source of truth.
+
+---
+
+## 1. Endpoint Availability Matrix
+
+| Route | Supported Methods | v2.x (ESP8266) | v3.x (ESP32) | v4.x / v5.x (ESP32) | RAPI Fallback (v2/v3) | python-openevse-http Status |
+| :--- | :--- | :---: | :---: | :---: | :--- | :---: |
+| `/status` | `GET`, `POST` | `GET` only | `GET` only | `GET`, `POST` | N/A | ✅ Fully Supported |
+| `/config` | `GET`, `POST` | `GET`, `POST` | `GET`, `POST` | `GET`, `POST` | N/A | ✅ Fully Supported |
+| `/override` | `GET`, `POST`, `PATCH`, `DELETE` | ❌ | ❌ | ✅ (v4.0.0+) | `$FE` (enable) / `$FS` (sleep), `$SC` | ✅ Fully Supported |
+| `/claims` | `GET`, `POST`, `DELETE` | ❌ | ❌ | ✅ (v4.0.0+) | N/A | ✅ Fully Supported |
+| `/limit` | `GET`, `POST`, `DELETE` | ❌ | ❌ | ✅ (v4.0.0+) | `$SH` (kWh limit), `$S3` (time limit) | ✅ Fully Supported |
+| `/shaper` | `POST` | ❌ | ❌ | ✅ (v4.0.0+) | N/A | ✅ Fully Supported |
+| `/divertmode` | `POST` | ✅ (`/divertmode`) | ✅ (`/divertmode`) | ✅ (`/divertmode`) | N/A (updates config flags) | ✅ Fully Supported |
+| `/restart` | `POST` | ✅ (`/restart`) | ✅ (`/restart`) | ✅ (`/restart`) | `$FR` (EVSE controller reboot) | ✅ Fully Supported |
+| `/r` or `/rapi` | `GET`, `POST` | `GET` (html/json) | `GET`, `POST` | `POST` (Mongoose) | Direct RAPI | ✅ Fully Supported |
+| `/ws` | `WebSocket` | ✅ | ✅ | ✅ | N/A | ✅ Fully Supported |
+| `/schedule` | `GET`, `POST`, `DELETE` | ❌ | ❌ | ✅ (v4.0.0+) | `$ST` / `$GD` | ✅ Fully Supported |
+| `/schedule/plan` | `GET` | ❌ | ❌ | ✅ (v4.1.0+) | N/A | ✅ Fully Supported |
+| `/time` | `GET`, `POST` | ❌ | ❌ (`/settime`) | ✅ (v4.0.0+) | `$S1` (RTC set) | ✅ Fully Supported |
+| `/settime` | `GET`, `POST` | ❌ | ✅ | ⚠️ Legacy alias | `$S1` | ✅ Fully Supported |
+| `/emeter` | `DELETE` | ❌ | ❌ | ✅ (v4.0.0+) | N/A | ❌ Not Implemented |
+| `/notifications` | `GET` | ❌ | ❌ | ✅ (v5.1.0+) | N/A | ❌ Not Implemented |
+| `/notifications/ack` | `POST` | ❌ | ❌ | ✅ (v5.1.0+) | N/A | ❌ Not Implemented |
+| `/update` | `GET`, `POST` | `GET`, `POST` | `GET`, `POST` | `GET`, `POST` | N/A | ✅ Fully Supported |
+| `/logs` | `GET` | ❌ | ❌ | ✅ (v4.0.0+) | N/A | ✅ Fully Supported |
+| `/logs/export` | `GET` | ❌ | ❌ | ✅ (v4.0.0+) | N/A | ❌ Not Implemented |
+| `/certificates` | `GET`, `POST`, `DELETE` | ❌ | ❌ | ✅ (v4.0.0+) | N/A | ✅ Fully Supported |
+| `/scan` | `GET` | ✅ | ✅ | ✅ | N/A | ❌ Not Implemented |
+| `/apoff` | `GET`, `POST` | ✅ | ✅ | ✅ | N/A | ❌ Not Implemented |
+| `/reset` | `GET`, `POST` | ✅ | ✅ | ✅ | N/A | ❌ Not Implemented |
+| `/rfid/add` | `POST` | ❌ | ❌ | ✅ (v4.0.0+) | N/A | ✅ Fully Supported |
+| `/rfid/users` | `GET`, `POST`, `DELETE` | ❌ | ❌ | ✅ (v5.0.0+) | N/A | ✅ Fully Supported |
+| `/relay/reset` | `POST` | ❌ | ❌ | ✅ (v5.1.0+) | `$FH` | ✅ Fully Supported |
+| `/relay/recovery` | `POST` | ❌ | ❌ | ✅ (v5.1.0+) | `$FK` | ✅ Fully Supported |
+| `/cabletemp` | `GET`, `POST` | ❌ | ❌ | ✅ (v5.1.0+) | `$GN`, `$SN` | ✅ Fully Supported |
+| `/teslaveh` / `/tesla/vehicles` | `GET` | ❌ | ✅ (`/teslaveh`) | ✅ | N/A | ❌ Not Implemented |
+| `/energy/raw`, `/daily`, etc. | `GET` | ❌ | ❌ | ✅ (v4.0.0+) | N/A | ❌ Not Implemented |
+| `/migrate/expand16mb` | `POST` | ❌ | ❌ | ✅ (v5.1.0+) | N/A | ❌ Not Implemented |
+
+---
+
+## 2. Core Endpoint Payload Differences
+
+### A. `/config` (Device Configuration & Identification)
+
+| Field Key | Type | v2.x (ESP8266) | v3.x (ESP32) | v4.x / v5.x (ESP32) | Notes |
+| :--- | :--- | :---: | :---: | :---: | :--- |
+| `wifi_serial` | `string` | ❌ (None) | ❌ (None) | ✅ | Formatted uppercase hardware MAC (e.g. `1234567890AB`). **Missing on v2/v3!** |
+| `hostname` | `string` | ✅ (`"openevse"`) | ✅ (`"openevse-XXXX"`) | ✅ (`"openevse-XXXX"`) | Configured hostname. |
+| `mqtt_announce_topic` | `string` | ✅ | ✅ | ✅ | Defaults to `"openevse/announce/XXXX"`. |
+| `version` | `string` | ✅ (`"2.9.1"`) | ✅ (`"3.3.1"`) | ✅ (`"4.1.2"`) | WiFi gateway firmware version string. |
+| `firmware` | `string` | ✅ (`"5.0.1"`) | ✅ | ✅ (`"7.1.3"`) | EVSE controller firmware version string. |
+| `protocol` | `string` | ✅ (`"4.0.1"`) | ✅ (`"-"`) | ✅ (`"-"`) | RAPI protocol version. |
+| `buildenv` | `string` | ❌ | ❌ | ✅ (e.g. `"openevse_wifi_v1"`) | PlatformIO build target name. |
+| `d9_support` | `bool` | ❌ | ❌ | ✅ (v5.x) | Signals OpenEVSE D9+ controller hardware support. |
+| `rfid_enabled` | `bool` | ❌ | ❌ | ✅ (v4.1.0+) | Virtual flag mask. |
+| `led_brightness` | `int` | ❌ | ❌ | ✅ (v4.1.0+) | RGB LED brightness (0-255). |
+| `flags` | `int` | ✅ (24-bit) | ✅ (24-bit) | ✅ (32-bit) | Bitmask of enabled services and configurations. |
+
+### B. `/status` (Telemetry & State Monitoring)
+
+| Field Key | Type | v2.x (ESP8266) | v3.x (ESP32) | v4.x / v5.x (ESP32) | Notes |
+| :--- | :--- | :---: | :---: | :---: | :--- |
+| `state` | `int` | ✅ | ✅ | ✅ | EVSE state: 1=Ready, 2=Connected, 3=Charging, 254=Sleeping, 255=Disabled. |
+| `amp` | `float` | ✅ | ✅ | ✅ | Charging current in Amperes. |
+| `voltage` | `int\|float` | ✅ | ✅ | ✅ | Voltage in Volts (e.g. 240). |
+| `pilot` | `int` | ✅ | ✅ | ✅ | Pilot limit in Amperes. |
+| `macaddress` | `string` | ❌ | ❌ | ✅ (v4.x+) | Hardware MAC address (e.g. `"AA:BB:CC:DD:EE:FF"`). |
+| `ipaddress` | `string` | ✅ | ✅ | ✅ | Local IP address. |
+| `shaper` | `int` | ❌ | ❌ | ✅ (v4.0.0+) | Current Shaper active: 0=Disabled, 1=Enabled. |
+| `shaper_live_pwr` | `int` | ❌ | ❌ | ✅ (v4.0.0+) | Shaper live grid power (W). |
+| `shaper_cur` | `float` | ❌ | ❌ | ✅ (v4.0.0+) | Shaper dynamically calculated max current (A). |
+| `vehicle_soc` | `int` | ❌ | ❌ | ✅ (v4.1.0+) | Vehicle battery SoC (%). Pushed via `POST /status`. |
+| `vehicle_range` | `int` | ❌ | ❌ | ✅ (v4.1.0+) | Vehicle range (km or miles). |
+| `time_to_full_charge` | `int` | ❌ | ❌ | ✅ (v4.1.0+) | Seconds until complete charge. |
+| `notifications` | `object` | ❌ | ❌ | ✅ (v5.1.0+) | Summary notifications object `{"count": N, "severity": "..."}`. |
+
+---
+
+## 3. Actuator Security & CSRF (`actuatorMethodAllowed`)
+
+In **v4.x / v5.x** firmware, destructive actuators (`/reset`, `/restart`, `/apoff`, `/divertmode`, `/shaper`, `/settime`, `/rfid/add`, `/relay/reset`, `/relay/recovery`) include CSRF protection:
+- Calls must be sent via **`POST`** (or non-GET HTTP methods).
+- If sent via `GET`, the firmware rejects with `403 Forbidden` unless the header `X-Requested-With: OpenEVSE` is present.
+- `python-openevse-http` always sends actuators via `POST` or `PATCH`.
+
+---
+
+## 4. Upstream Repository Reference Links
+
+When cross-checking implementation or adding support for new firmware features:
+- **Active WiFi Gateway Codebase**: [`OpenEVSE/openevse_esp32_firmware`](https://github.com/OpenEVSE/openevse_esp32_firmware)
+  - HTTP routes & endpoints: `src/web_server.cpp`
+  - `/config` serialization: `src/web_server_config.cpp` & `src/app_config.cpp`
+  - Shaper & Claims: `src/current_shaper.cpp`, `src/web_server_claims.cpp`
+  - Override handler: `src/web_server.cpp` (`handleOverride`)
+- **Legacy ESP32 Firmware (EOL)**: [`OpenEVSE/ESP32_WiFi_V3.x`](https://github.com/OpenEVSE/ESP32_WiFi_V3.x)
+- **Legacy ESP8266 Firmware (EOL)**: [`OpenEVSE/ESP8266_WiFi_v2.x`](https://github.com/OpenEVSE/ESP8266_WiFi_v2.x)
+- **Controller RAPI Source**: [`OpenEVSE/open_evse`](https://github.com/OpenEVSE/open_evse) (specifically `src/rapi.cpp`)

{python_openevse_http-1.6.0 → python_openevse_http-1.7.1}/.github/workflows/publish-to-pypi.yml

@@ -31,7 +31,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d  # v10.0.1
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7  # v10.2.0
         with:
           enable-cache: true
           version: "0.10.9"

{python_openevse_http-1.6.0 → python_openevse_http-1.7.1}/.github/workflows/test.yml

@@ -82,6 +82,6 @@ jobs:
         with:
           name: coverage-data
       - name: Upload coverage report
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f  # v6
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5  # v7.1.1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

{python_openevse_http-1.6.0 → python_openevse_http-1.7.1}/AGENTS.md

@@ -32,8 +32,9 @@ OpenEVSE chargers run various firmware versions (v2.x, v3.x, v4.x, v5.x) with di
 
 ### Validating Endpoints Against Firmware Sources
 When adding or updating endpoints, payload keys, or RAPI commands, cross-reference against:
-- **WiFi Gateway (v3/v4/v5)**: [`OpenEVSE/ESP32_WiFi_V4.x`](https://github.com/OpenEVSE/ESP32_WiFi_V4.x) (routes in `src/http.cpp`, `src/web_server.cpp`)
-- **Legacy WiFi (v2)**: [`OpenEVSE/ESP8266_WiFi_v2.x`](https://github.com/OpenEVSE/ESP8266_WiFi_v2.x)
+- **WiFi Gateway (Current ESP32 v4/v5)**: [`OpenEVSE/openevse_esp32_firmware`](https://github.com/OpenEVSE/openevse_esp32_firmware) (formerly [`OpenEVSE/ESP32_WiFi_V4.x`](https://github.com/OpenEVSE/ESP32_WiFi_V4.x))
+- **WiFi Gateway (Legacy ESP32 v3.x)**: [`OpenEVSE/ESP32_WiFi_V3.x`](https://github.com/OpenEVSE/ESP32_WiFi_V3.x)
+- **Legacy WiFi (ESP8266 v2.x)**: [`OpenEVSE/ESP8266_WiFi_v2.x`](https://github.com/OpenEVSE/ESP8266_WiFi_v2.x)
 - **Controller / RAPI**: [`OpenEVSE/open_evse`](https://github.com/OpenEVSE/open_evse) (commands in `src/rapi.cpp`)
 Verify HTTP methods, expected JSON fields, success/error payload shapes, and version thresholds.
 

{python_openevse_http-1.6.0/python_openevse_http.egg-info → python_openevse_http-1.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python_openevse_http
-Version: 1.6.0
+Version: 1.7.1
 Summary: Python wrapper for OpenEVSE HTTP API
 Home-page: https://github.com/firstof9/python-openevse-http
 Download-URL: https://github.com/firstof9/python-openevse-http
@@ -51,6 +51,9 @@ A Python library for communicating with [OpenEVSE](https://www.openevse.com/) ch
     - Control charging claims and limits.
     - Handle schedules.
     - **Shaper Toggle**: Enable or disable the grid shaper feature (requires firmware 4.0.0+).
+    - **Time Synchronization & RTC**: Manage time, timezone, and NTP sync (requires firmware 4.0.0+).
+    - **Event Logs**: Retrieve diagnostic log blocks and log event history (requires firmware 4.0.0+).
+    - **Certificates**: Manage SSL/TLS Root CA and client certificates (requires firmware 4.0.0+).
 
 ## Installation
 
@@ -116,6 +119,25 @@ To bypass certificate verification:
         )
 ```
 
+### GitHub API Token (Optional)
+
+When performing firmware update checks (`charger.firmware_check()`) or automatic firmware updates (`charger.update_firmware()`), the library queries GitHub's Releases API. To avoid hitting unauthenticated rate limits (60 requests/hour), you can supply a GitHub personal access token (PAT):
+
+```python
+        # Provide a GitHub token during client initialization
+        charger = OpenEVSE(
+            "192.168.1.30",
+            session=session,
+            github_token="ghp_your_github_token_here",
+        )
+
+        # Or set / update dynamically via property
+        charger.github_token = "ghp_your_github_token_here"
+
+        # Or pass per-call
+        latest = await charger.firmware_check(github_token="ghp_your_github_token_here")
+```
+
 ## API Support Matrix
 
 | Endpoint | Methods | Supported | Description |
@@ -124,22 +146,27 @@ To bypass certificate verification:
 | `/config` | GET, POST | ✅ | System and WiFi configuration |
 | `/override` | GET, POST, PATCH, DELETE | ✅ | Manual charging overrides & current limits |
 | `/claims` | GET, POST, DELETE | ✅ | Client-based charging claims |
-| `/schedule` | GET, POST | ⚠️ | Charging schedule management (Retrieval only) |
+| `/schedule` | GET, POST, DELETE | ✅ | Charging schedule management (v4.0.0+) |
 | `/limit` | GET, POST, DELETE | ✅ | Charge limits (Time, Energy, SoC) |
 | `/shaper` | POST | ✅ | Grid shaper control (v4.0.0+) |
 | `/restart` | POST | ✅ | Reboot WiFi gateway or EVSE module |
 | `/divertmode` | POST | ✅ | Solar divert mode control |
 | `/r` (RAPI) | POST | ✅ | Direct RAPI command interface |
 | `/ws` | GET | ✅ | WebSocket real-time updates |
-| `/time` | GET, POST | ❌ | RTC and NTP time settings |
-| `/logs` | GET | ❌ | System and debug event logs |
+| `/time` | GET, POST | ✅ | RTC and NTP time settings (v4.0.0+) |
+| `/settime` | POST | ✅ | Legacy time setting interface (v3.x / fallback to `$S1` on v2.x) |
+| `/logs` | GET | ✅ | Event log block bounds and block events (v4.0.0+) |
 | `/emeter` | DELETE | ❌ | Energy meter reset |
 | `/wifi` | GET, POST | ❌ | Network scanning and AP configuration |
 | `/tesla` | GET | ❌ | Tesla vehicle integration |
-| `/certificates`| GET, POST, DELETE | ❌ | SSL/TLS certificate management |
-| `/schedule/plan`| GET | ❌ | Schedule planning and optimization |
+| `/certificates`| GET, POST, DELETE | ✅ | SSL/TLS certificate management (v4.0.0+) |
+| `/schedule/plan`| GET | ✅ | Schedule planning and optimization (v4.1.0+) |
 | `/update` | POST | ✅ | Firmware update interface |
-| `/rfid/add` | POST | ❌ | RFID tag management |
+| `/relay/recovery` | POST | ✅ | Stuck relay recovery cycle (v5.1.0+ / `$FK`) |
+| `/relay/reset` | POST | ✅ | Relay contact-life health estimation reset (v5.1.0+ / `$FH`) |
+| `/cabletemp` | GET, POST | ✅ | Cable temperature monitor configuration and status (v5.1.0+) |
+| `/rfid/add` | POST | ✅ | RFID tag pairing mode (v4.0.0+) |
+| `/rfid/users` | GET, POST, DELETE | ✅ | RFID tag to user mappings (v5.0.0+) |
 
 ✅ = Fully Supported \| ⚠️ = Partial Support \| ❌ = Not yet implemented
 

{python_openevse_http-1.6.0 → python_openevse_http-1.7.1}/README.md

@@ -18,6 +18,9 @@ A Python library for communicating with [OpenEVSE](https://www.openevse.com/) ch
     - Control charging claims and limits.
     - Handle schedules.
     - **Shaper Toggle**: Enable or disable the grid shaper feature (requires firmware 4.0.0+).
+    - **Time Synchronization & RTC**: Manage time, timezone, and NTP sync (requires firmware 4.0.0+).
+    - **Event Logs**: Retrieve diagnostic log blocks and log event history (requires firmware 4.0.0+).
+    - **Certificates**: Manage SSL/TLS Root CA and client certificates (requires firmware 4.0.0+).
 
 ## Installation
 
@@ -83,6 +86,25 @@ To bypass certificate verification:
         )
 ```
 
+### GitHub API Token (Optional)
+
+When performing firmware update checks (`charger.firmware_check()`) or automatic firmware updates (`charger.update_firmware()`), the library queries GitHub's Releases API. To avoid hitting unauthenticated rate limits (60 requests/hour), you can supply a GitHub personal access token (PAT):
+
+```python
+        # Provide a GitHub token during client initialization
+        charger = OpenEVSE(
+            "192.168.1.30",
+            session=session,
+            github_token="ghp_your_github_token_here",
+        )
+
+        # Or set / update dynamically via property
+        charger.github_token = "ghp_your_github_token_here"
+
+        # Or pass per-call
+        latest = await charger.firmware_check(github_token="ghp_your_github_token_here")
+```
+
 ## API Support Matrix
 
 | Endpoint | Methods | Supported | Description |
@@ -91,22 +113,27 @@ To bypass certificate verification:
 | `/config` | GET, POST | ✅ | System and WiFi configuration |
 | `/override` | GET, POST, PATCH, DELETE | ✅ | Manual charging overrides & current limits |
 | `/claims` | GET, POST, DELETE | ✅ | Client-based charging claims |
-| `/schedule` | GET, POST | ⚠️ | Charging schedule management (Retrieval only) |
+| `/schedule` | GET, POST, DELETE | ✅ | Charging schedule management (v4.0.0+) |
 | `/limit` | GET, POST, DELETE | ✅ | Charge limits (Time, Energy, SoC) |
 | `/shaper` | POST | ✅ | Grid shaper control (v4.0.0+) |
 | `/restart` | POST | ✅ | Reboot WiFi gateway or EVSE module |
 | `/divertmode` | POST | ✅ | Solar divert mode control |
 | `/r` (RAPI) | POST | ✅ | Direct RAPI command interface |
 | `/ws` | GET | ✅ | WebSocket real-time updates |
-| `/time` | GET, POST | ❌ | RTC and NTP time settings |
-| `/logs` | GET | ❌ | System and debug event logs |
+| `/time` | GET, POST | ✅ | RTC and NTP time settings (v4.0.0+) |
+| `/settime` | POST | ✅ | Legacy time setting interface (v3.x / fallback to `$S1` on v2.x) |
+| `/logs` | GET | ✅ | Event log block bounds and block events (v4.0.0+) |
 | `/emeter` | DELETE | ❌ | Energy meter reset |
 | `/wifi` | GET, POST | ❌ | Network scanning and AP configuration |
 | `/tesla` | GET | ❌ | Tesla vehicle integration |
-| `/certificates`| GET, POST, DELETE | ❌ | SSL/TLS certificate management |
-| `/schedule/plan`| GET | ❌ | Schedule planning and optimization |
+| `/certificates`| GET, POST, DELETE | ✅ | SSL/TLS certificate management (v4.0.0+) |
+| `/schedule/plan`| GET | ✅ | Schedule planning and optimization (v4.1.0+) |
 | `/update` | POST | ✅ | Firmware update interface |
-| `/rfid/add` | POST | ❌ | RFID tag management |
+| `/relay/recovery` | POST | ✅ | Stuck relay recovery cycle (v5.1.0+ / `$FK`) |
+| `/relay/reset` | POST | ✅ | Relay contact-life health estimation reset (v5.1.0+ / `$FH`) |
+| `/cabletemp` | GET, POST | ✅ | Cable temperature monitor configuration and status (v5.1.0+) |
+| `/rfid/add` | POST | ✅ | RFID tag pairing mode (v4.0.0+) |
+| `/rfid/users` | GET, POST, DELETE | ✅ | RFID tag to user mappings (v5.0.0+) |
 
 ✅ = Fully Supported \| ⚠️ = Partial Support \| ❌ = Not yet implemented
 

{python_openevse_http-1.6.0 → python_openevse_http-1.7.1}/openevsehttp/client.py

@@ -21,13 +21,16 @@ from .const import (
     ERROR_SESSION_REQUIRED,
     ERROR_TIMEOUT,
     UPDATE_TRIGGERS,
+    USER_AGENT,
 )
 from .exceptions import (
     AlreadyListening,
     AuthenticationError,
+    CommandFailedError,
     MissingMethod,
     MissingSerial,
     ParseJSONError,
+    UnsupportedFeature,
 )
 from .managers import ManagersMixin
 from .properties import PropertiesMixin
@@ -55,6 +58,7 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
         session: aiohttp.ClientSession | None = None,
         ssl: bool = False,
         ssl_verify: bool = True,
+        github_token: str | None = None,
     ) -> None:
         """Connect to an OpenEVSE charger equipped with wifi or ethernet."""
         self._user = user or ""
@@ -75,6 +79,11 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
         self._owns_loop = False
         self._loop_thread: threading.Thread | None = None
         self._session = session
+        self._github_token = (
+            github_token.strip()
+            if isinstance(github_token, str) and github_token.strip()
+            else None
+        )
 
     def _get_session(self) -> aiohttp.ClientSession:
         """Return the configured HTTP session or fail fast."""
@@ -93,6 +102,7 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
         method: str = "",
         data: Any = None,
         rapi: Any = None,
+        headers: dict[str, str] | None = None,
     ) -> Mapping[str, Any] | list[Any] | str | bool:
         """Return result of processed HTTP request."""
         auth = None
@@ -105,7 +115,7 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
 
         session = self._get_session()
         return await self._process_request_with_session(
-            session, url, method, data, rapi, auth
+            session, url, method, data, rapi, auth, headers
         )
 
     def _normalize_response(self, response: Any) -> dict[str, Any] | list[Any]:
@@ -123,6 +133,7 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
         data: Any,
         rapi: Any,
         auth: Any,
+        headers: dict[str, str] | None = None,
     ) -> Mapping[str, Any] | list[Any] | str | bool:
         """Process a request with a given session."""
         if not hasattr(session, method):
@@ -136,7 +147,17 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
             method,
         )
         try:
-            kwargs = {"data": rapi, "auth": auth}
+            req_headers: dict[str, str] = {
+                "User-Agent": USER_AGENT,
+                "X-Requested-With": "OpenEVSE",
+            }
+            if headers:
+                req_headers.update(headers)
+            kwargs: dict[str, Any] = {
+                "data": rapi,
+                "auth": auth,
+                "headers": req_headers,
+            }
             if data is not None:
                 kwargs["json"] = data
             if url.startswith("https://") and not self.ssl_verify:
@@ -166,15 +187,16 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
 
                 if resp.status == 400:
                     if isinstance(response_content, dict) and "msg" in response_content:
-                        _LOGGER.error("Error 400: %s", response_content["msg"])
+                        msg = str(response_content["msg"])
                     elif (
                         isinstance(response_content, dict)
                         and "error" in response_content
                     ):
-                        _LOGGER.error("Error 400: %s", response_content["error"])
+                        msg = str(response_content["error"])
                     else:
-                        _LOGGER.error("Error 400: %s", response_content)
-                    raise ParseJSONError
+                        msg = str(response_content)
+                    _LOGGER.error("Error 400: %s", msg)
+                    raise CommandFailedError(msg)
                 if resp.status == 401:
                     _LOGGER.error("Authentication error: %s", response_content)
                     raise AuthenticationError
@@ -517,3 +539,66 @@ class OpenEVSE(CommandsMixin, ManagersMixin, SensorsMixin, PropertiesMixin):
     def version_check(self, min_version: str, max_version: str = "") -> bool:
         """Unprotected function call for version checking."""
         return self._version_check(min_version=min_version, max_version=max_version)
+
+    def _controller_version_check(
+        self, min_version: str, max_version: str = ""
+    ) -> bool:
+        """Return bool if minimum controller (open_evse) version is met."""
+        if "firmware" not in self._config:
+            _LOGGER.debug("Unable to find controller firmware version.")
+            return False
+        cutoff = AwesomeVersion(min_version)
+        limit = ""
+        if max_version != "":
+            limit = AwesomeVersion(max_version)
+
+        current = get_awesome_version(self._config["firmware"])
+        if current.strategy == "unknown":
+            _LOGGER.debug(
+                "Non-semver controller firmware version detected: %s",
+                self._config["firmware"],
+            )
+            return False
+
+        if limit:
+            try:
+                if cutoff <= current < limit:
+                    return True
+            except AwesomeVersionCompareException:
+                _LOGGER.debug("Non-semver controller firmware version detected.")
+            return False
+
+        try:
+            if current >= cutoff:
+                return True
+        except AwesomeVersionCompareException:
+            _LOGGER.debug("Non-semver controller firmware version detected.")
+        return False
+
+    def controller_version_check(self, min_version: str, max_version: str = "") -> bool:
+        """Unprotected function call for controller version checking."""
+        return self._controller_version_check(
+            min_version=min_version, max_version=max_version
+        )
+
+    def _require_firmware(
+        self, min_version: str, feature: str, max_version: str = ""
+    ) -> None:
+        """Verify minimum gateway firmware version or log and raise UnsupportedFeature."""
+        if not self._version_check(min_version, max_version):
+            err = UnsupportedFeature(
+                feature, min_version=min_version, component="gateway"
+            )
+            _LOGGER.debug("%s", err)
+            raise err
+
+    def _require_controller_firmware(
+        self, min_version: str, feature: str, max_version: str = ""
+    ) -> None:
+        """Verify minimum OpenEVSE controller firmware version or log and raise UnsupportedFeature."""
+        if not self._controller_version_check(min_version, max_version):
+            err = UnsupportedFeature(
+                feature, min_version=min_version, component="OpenEVSE controller"
+            )
+            _LOGGER.debug("%s", err)
+            raise err

python_openevse_http-1.7.1/openevsehttp/commands.py

@@ -0,0 +1,33 @@
+"""Commands mixin for OpenEVSE HTTP client."""
+
+from __future__ import annotations
+
+from .commands_base import BaseCommandMixin
+from .commands_core import CoreCommandsMixin
+from .commands_diagnostics import DiagnosticsCommandsMixin
+from .commands_firmware import FirmwareCommandsMixin
+from .commands_schedule import ScheduleCommandsMixin
+from .commands_security import SecurityCommandsMixin
+from .commands_time import TimeCommandsMixin
+
+__all__ = [
+    "BaseCommandMixin",
+    "CommandsMixin",
+    "CoreCommandsMixin",
+    "DiagnosticsCommandsMixin",
+    "FirmwareCommandsMixin",
+    "ScheduleCommandsMixin",
+    "SecurityCommandsMixin",
+    "TimeCommandsMixin",
+]
+
+
+class CommandsMixin(
+    CoreCommandsMixin,
+    FirmwareCommandsMixin,
+    ScheduleCommandsMixin,
+    SecurityCommandsMixin,
+    DiagnosticsCommandsMixin,
+    TimeCommandsMixin,
+):
+    """Composite mixin providing all command methods for OpenEVSE."""

python_openevse_http-1.7.1/openevsehttp/commands_base.py

@@ -0,0 +1,66 @@
+"""Base mixin providing protocol stubs and common helpers for command mixins."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from typing import Any
+
+import aiohttp
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class BaseCommandMixin:
+    """Base mixin defining internal attributes and stub methods required by command mixins."""
+
+    url: str
+    ssl: bool
+    ssl_verify: bool
+    _status: dict[str, Any]
+    _config: dict[str, Any]
+    _session: aiohttp.ClientSession | None
+    _github_token: str | None
+
+    # These are implemented in OpenEVSE (client.py)
+    def _version_check(self, min_version: str, max_version: str = "") -> bool:
+        raise NotImplementedError
+
+    def _controller_version_check(
+        self, min_version: str, max_version: str = ""
+    ) -> bool:
+        raise NotImplementedError
+
+    def _require_firmware(
+        self, min_version: str, feature: str, max_version: str = ""
+    ) -> None:
+        raise NotImplementedError
+
+    def _require_controller_firmware(
+        self, min_version: str, feature: str, max_version: str = ""
+    ) -> None:
+        raise NotImplementedError
+
+    async def process_request(
+        self,
+        url: str,
+        method: str = "",
+        data: Any = None,
+        rapi: Any = None,
+        headers: dict[str, str] | None = None,
+    ) -> Mapping[str, Any] | list[Any] | str | bool:
+        raise NotImplementedError
+
+    async def send_command(self, command: str) -> tuple[Any, Any]:
+        raise NotImplementedError
+
+    async def update(self, force_status: bool = False) -> None:
+        raise NotImplementedError
+
+    def _normalize_response(self, response: Any) -> dict[str, Any] | list[Any]:
+        """Normalize response to a dict or list."""
+        raise NotImplementedError
+
+    def _get_session(self) -> aiohttp.ClientSession:
+        """Return the configured HTTP session."""
+        raise NotImplementedError