python-openevse-http 1.5.0__tar.gz → 1.7.0__tar.gz

python_openevse_http-1.7.0/.agents/skills/openevse-api-guide/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: openevse-api-guide
+description: >-
+  Use this skill when implementing, refactoring, or testing OpenEVSE charger
+  commands, REST API endpoints, RAPI commands, properties, or exception handling in python-openevse-http.
+---
+
+# OpenEVSE API & Command Implementation Guide
+
+This skill provides architectural guidelines, endpoint conventions, and error handling patterns for developing `python-openevse-http`.
+
+## Architecture
+
+The main client `OpenEVSE` combines several mixins:
+- `CommandsMixin` (`openevsehttp/commands.py`): Command execution methods.
+- `PropertiesMixin` (`openevsehttp/properties.py`): Configuration & state properties.
+- `SensorsMixin` (`openevsehttp/sensors.py`): Energy, current, voltage, temperature telemetry.
+- `WebsocketMixin` (`openevsehttp/websocket.py`): Real-time event streams.
+
+## 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 |
+| Config | `/config` | N/A | GET / POST |
+| Manual Override | `/override` | `$FE` (enable) / `$FS` (sleep) | GET / POST / PATCH / DELETE |
+| Soft Current Limit | `/override` (charge_current) | `$SC <amps> [N\|V]` | POST |
+| Shaper Mode | `/shaper` | N/A | POST |
+| 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
+
+Always check firmware compatibility using `self._version_check(min_version)`:
+```python
+if self._version_check("4.0.1"):
+    # Use HTTP REST endpoint
+    response = await self.process_request(url=f"{self.url}override", method="patch")
+else:
+    # Fallback to RAPI command for older firmware
+    response, msg = await self.send_command("$FE" if state == 254 else "$FS")
+```
+
+If a feature is not supported on older firmware:
+```python
+if not self._version_check("4.1.0"):
+    _LOGGER.debug("Feature not supported for older firmware.")
+    raise UnsupportedFeature
+```
+
+## Exception Handling Conventions
+
+All custom exceptions inherit from `OpenEVSEError(Exception)`.
+
+- **`CommandFailedError`**: Raise when a command returns an error response, fails HTTP verification, or returns `$NK` / `RAPI_ERRORS`.
+- **`UnknownStateError`**: Raise when prior charger state or configuration is required to determine the command payload (e.g. toggling) but is missing or `None`.
+- **`FirmwareResolutionError`**: Raise when GitHub release download URL cannot be determined from the release metadata.
+- **`UnsupportedFeature`**: Raise when charger firmware is below the minimum supported version for a feature.
+- **`AuthenticationError`**: Raise on 401 unauthorized.
+
+```python
+from .exceptions import CommandFailedError, UnknownStateError, UnsupportedFeature
+```
+
+## Validating Endpoints Against Firmware Repositories
+
+When adding, modifying, or debugging endpoints and RAPI commands, cross-reference against the upstream OpenEVSE firmware sources:
+
+- **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/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 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**:
+   - Update or add mock JSON payloads under `tests/fixtures/v4_json/` and `tests/fixtures/v2_json/` to mirror real firmware response shapes.
+
+## Writing Tests for Commands
+
+When testing command methods:
+1. Use fixtures from `tests/conftest.py` (`test_charger`, `test_charger_v2`, `test_charger_new`).
+2. Mock responses using `mock_aioclient`:
+   ```python
+   mock_aioclient.post(
+       TEST_URL_CONFIG,
+       status=200,
+       body='{"msg": "done"}',
+   )
+   ```
+3. Test success paths, failure responses (`CommandFailedError`), missing state paths (`UnknownStateError`), and older firmware version behavior (`UnsupportedFeature` / RAPI commands).

python_openevse_http-1.7.0/.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.7.0/.agents/skills/openevse-dev-workflow/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: openevse-dev-workflow
+description: >-
+  Use this skill when running tests, formatting code, checking linters,
+  running type checks, or managing tox environments in python-openevse-http.
+---
+
+# OpenEVSE Development & Testing Workflow
+
+This skill guides you through executing tests, linting, formatting, and type checks within the `python-openevse-http` repository.
+
+## Environment & Tooling
+
+The project uses `tox` for managing isolated virtual environments and running test tools (`pytest`, `ruff`, `mypy`).
+
+### 1. Running Unit Tests
+
+Run full test suite via tox:
+```bash
+tox -e py314
+```
+
+To run fast targeted test runs with the existing tox environment:
+```bash
+# Run all tests
+.tox/py314/bin/pytest
+
+# Run a specific test file
+.tox/py314/bin/pytest tests/test_commands.py
+
+# Run a single test function
+.tox/py314/bin/pytest tests/test_commands.py -k "test_toggle_override"
+
+# Run with verbose output and stdout
+.tox/py314/bin/pytest -v -s tests/test_client.py
+```
+
+### 2. Formatting & Linting (Ruff)
+
+Check formatting and linting:
+```bash
+tox -e lint
+```
+
+To auto-format or auto-fix lint errors:
+```bash
+# Format code
+.tox/lint/bin/ruff format ./
+
+# Auto-fix linting issues
+.tox/lint/bin/ruff check --fix openevsehttp tests
+```
+
+### 3. Type Checking (Mypy)
+
+Run static type checks:
+```bash
+tox -e mypy
+```
+Or directly:
+```bash
+.tox/mypy/bin/mypy openevsehttp
+```
+
+### 4. Running All CI Checks Together
+
+Before submitting PRs or finalizing tasks, verify everything in one step:
+```bash
+tox -e py314,lint,mypy
+```
+
+### 5. Pre-commit Hooks
+
+Pre-commit hooks are configured via `.pre-commit-config.yaml`. They run automatically on `git commit`, or you can trigger them manually:
+```bash
+pre-commit run --all-files
+```
+
+### 6. Pull Requests & Issue Creation
+
+- **Pull Requests**:
+  - Always use the template in [`.github/pull_request_template.md`](../../.github/pull_request_template.md).
+  - Include a summary, issue link (`Fixes #<number>`), type of change, and completed checklist.
+  - Follow conventional commits in PR titles (`feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`).
+- **Issues & Feature Requests**:
+  - Use [`.github/ISSUE_TEMPLATE/bug_report.yml`](../../.github/ISSUE_TEMPLATE/bug_report.yml) for bugs (`[Bug]: <summary>`).
+  - Use [`.github/ISSUE_TEMPLATE/feature_request.yml`](../../.github/ISSUE_TEMPLATE/feature_request.yml) for feature requests (`[Feature Request]: <summary>`).

{python_openevse_http-1.5.0 → python_openevse_http-1.7.0}/.github/release-drafter.yml

@@ -20,6 +20,7 @@ categories:
     labels:
       - "performance"
   - title: "🔧 Maintenance 🔧"
+    collapse-after: 2
     labels:
       - "chore"
       - "documentation"

{python_openevse_http-1.5.0 → python_openevse_http-1.7.0}/.github/workflows/autolabeler.yml

@@ -34,10 +34,10 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 3
     steps:
-      - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411  # v2.19.4
+      - uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1  # v2.21.1
         with:
           egress-policy: audit
 
-      - uses: release-drafter/release-drafter/autolabeler@ed4bc48ec97379be2258e7b7ac2624a3e26ab809  # v7
+      - uses: release-drafter/release-drafter/autolabeler@34d80673e067bdc0c24568d3af899c216adcfaa9  # v7
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{python_openevse_http-1.5.0 → python_openevse_http-1.7.0}/.github/workflows/links.yml

@@ -15,13 +15,13 @@ jobs:
   linkChecker:
     runs-on: ubuntu-latest
     steps:
-      - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411  # v2.19.4
+      - uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1  # v2.21.1
         with:
           egress-policy: audit
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
       - name: Link Checker
-        uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411  # v2
+        uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8  # v2
         with:
           args: --verbose --no-progress './**/*.md'

{python_openevse_http-1.5.0 → python_openevse_http-1.7.0}/.github/workflows/publish-to-pypi.yml

@@ -21,17 +21,17 @@ jobs:
       contents: read
       id-token: write
     steps:
-      - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411  # v2.19.4
+      - uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1  # v2.21.1
         with:
           egress-policy: audit
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           ref: ${{ inputs.tag || github.ref }}
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39  # v8.2.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7  # v10.2.0
         with:
           enable-cache: true
           version: "0.10.9"
@@ -43,4 +43,4 @@ jobs:
         run: uv build
 
       - name: Publish release to PyPI
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2

{python_openevse_http-1.5.0 → python_openevse_http-1.7.0}/.github/workflows/release-drafter.yml

@@ -13,11 +13,11 @@ jobs:
   update_release_draft:
     runs-on: ubuntu-latest
     steps:
-      - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411  # v2.19.4
+      - uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1  # v2.21.1
         with:
           egress-policy: audit
 
       # Drafts your next Release notes as Pull Requests are merged into "main"
-      - uses: release-drafter/release-drafter@ed4bc48ec97379be2258e7b7ac2624a3e26ab809  # v7
+      - uses: release-drafter/release-drafter@34d80673e067bdc0c24568d3af899c216adcfaa9  # v7
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{python_openevse_http-1.5.0 → python_openevse_http-1.7.0}/.github/workflows/test.yml

@@ -18,17 +18,17 @@ jobs:
   prek:
     runs-on: ubuntu-latest
     steps:
-      - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411  # v2.19.4
+      - uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1  # v2.21.1
         with:
           egress-policy: audit
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
         with:
           python-version: "3.14"
-      - name: Install prek
-        run: pip install prek==0.4.0
+      - name: Install dependencies
+        run: pip install -r requirements_lint.txt
       - name: Run prek
         run: prek run --all-files --skip no-commit-to-branch
   build:
@@ -41,15 +41,15 @@ jobs:
           - "3.14"
 
     steps:
-      - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411  # v2.19.4
+      - uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1  # v2.21.1
         with:
           egress-policy: audit
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           fetch-depth: 2
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -69,12 +69,12 @@ jobs:
     runs-on: ubuntu-latest
     needs: build
     steps:
-      - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411  # v2.19.4
+      - uses: step-security/harden-runner@e14015d583714f6e62063499dc959a02595150a1  # v2.21.1
         with:
           egress-policy: audit
 
       - name: Check out the repository
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
         with:
           fetch-depth: 2
       - name: Download coverage data
@@ -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.7.0/AGENTS.md

@@ -0,0 +1,129 @@
+# Agent Guidelines for python-openevse-http
+
+This document outlines key architecture, conventions, workflows, and testing practices for agentic assistants operating in this repository.
+
+---
+
+## 1. Project Overview & Architecture
+
+`python-openevse-http` is an asynchronous Python library for interacting with OpenEVSE electric vehicle chargers via their HTTP REST API, WebSocket streams, and RAPI commands.
+
+### Core Modules & Mixins
+The main client class `OpenEVSE` in `openevsehttp/client.py` inherits from multiple mixins:
+- **`openevsehttp/client.py`**: Core client lifecycle, authentication, request processing (`process_request`, `send_command`), status updates (`update`), and session management.
+- **`openevsehttp/commands.py` (`CommandsMixin`)**: Charger commands (e.g. `set_override`, `toggle_override`, `clear_override`, `set_current`, `set_charge_mode`, `divert_mode`, `set_shaper`, `toggle_shaper`, `restart_wifi`, `restart_evse`, `update_firmware`).
+- **`openevsehttp/properties.py` (`PropertiesMixin`)**: Charger properties, configuration parsing, state decoding (`states`, `divert_mode`), firmware version parsing.
+- **`openevsehttp/sensors.py` (`SensorsMixin`)**: Sensor values, telemetry, power/voltage calculations.
+- **`openevsehttp/websocket.py` (`WebsocketMixin`, `OpenEVSEWebsocket`)**: Real-time websocket communication and state change listeners.
+- **`openevsehttp/exceptions.py`**: Typed library exceptions inheriting from `OpenEVSEError`.
+
+### Client Session Requirement
+- `OpenEVSE` uses caller-provided `aiohttp.ClientSession` (via `session=...`). If not provided, accessing network operations raises `RuntimeError(ERROR_SESSION_REQUIRED)`.
+- The session must run on the active event loop.
+
+---
+
+## 2. Firmware Version Handling & Upstream Validation
+
+OpenEVSE chargers run various firmware versions (v2.x, v3.x, v4.x, v5.x) with different capabilities:
+- **`self._version_check(min_version, max_version="")`**: Use this helper to conditionally execute HTTP API endpoints (v4+) versus RAPI command fallbacks (v2/v3, e.g. `$FE`, `$FS`, `$SC`, `$FR`).
+- Always handle version edge cases (e.g. non-semver development strings like `4.1.2.dev`).
+- Raise `UnsupportedFeature` if a feature is not supported on older firmware.
+
+### Validating Endpoints Against Firmware Sources
+When adding or updating endpoints, payload keys, or RAPI commands, cross-reference against:
+- **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.
+
+---
+
+## 3. Exception Handling
+
+All custom exceptions inherit from `OpenEVSEError(Exception)`:
+- `CommandFailedError`: Command execution failure, RAPI rejection (`$NK`), or error HTTP response.
+- `UnknownStateError`: Required state or configuration missing before command execution (e.g. toggle state).
+- `FirmwareResolutionError`: GitHub release asset resolution failure.
+- `AuthenticationError`: HTTP 401 / auth failures.
+- `UnsupportedFeature`: Feature not available for current firmware version.
+- `ParseJSONError`, `InvalidType`, `MissingMethod`, `MissingSerial`, `AlreadyListening`.
+
+Export all public exception classes in `openevsehttp/__init__.py`.
+
+---
+
+## 4. Development & Testing Workflow
+
+### Running Tests
+Use `tox` for isolated environments:
+```bash
+# Run unit tests on Python 3.14 / active environment
+tox -e py314
+
+# Or run pytest directly within the tox environment
+.tox/py314/bin/pytest
+
+# Target specific test files
+.tox/py314/bin/pytest tests/test_commands.py -k "test_toggle_override"
+```
+
+### Linting & Formatting
+```bash
+# Run ruff formatting check & linter
+tox -e lint
+
+# Format code automatically
+.tox/lint/bin/ruff format ./
+
+# Run linter with auto-fixes
+.tox/lint/bin/ruff check --fix openevsehttp tests
+```
+
+### Type Checking
+```bash
+tox -e mypy
+# Or directly:
+.tox/mypy/bin/mypy openevsehttp
+```
+
+---
+
+## 5. Testing & Mocking Guidelines
+
+- Tests use `pytest` with `pytest-asyncio` (`asyncio_default_fixture_loop_scope = "function"`).
+- Test fixtures in `tests/conftest.py`:
+  - `test_charger`: Standard v4 charger client with mocked endpoints.
+  - `test_charger_v2`: Legacy v2 firmware mock.
+  - `test_charger_new`: Newer v4 fixture with shaper and modern endpoints.
+  - `test_charger_auth`: Authenticated charger mock.
+  - `mock_aioclient`: `AiohttpClientMocker` instance for intercepting HTTP requests (`get`, `post`, `patch`, `delete`).
+- Fixture data files are located in `tests/fixtures/` (`v4_json/`, `v2_json/`).
+
+---
+
+## 6. Commit, Pull Request & Issue Guidelines
+
+### Creating Pull Requests
+- **Use the PR Template**: Always structure PR descriptions according to [`.github/pull_request_template.md`](.github/pull_request_template.md):
+  - **Description**: Provide a clear summary of changes, motivation, and link related issues (`Fixes #<number>`).
+  - **Type of change**: Check the relevant boxes (`Bug fix`, `New feature`, `Breaking change`, `Code quality / Refactoring`, `Documentation update`).
+  - **Checklist**: Complete all checklist items before opening or marking ready for review.
+- **Semantic PR Titles**: Use conventional commit titles matching [`.github/release-drafter.yml`](.github/release-drafter.yml):
+  - `feat:` New features / enhancements
+  - `fix:` Bug fixes
+  - `refactor:` Refactoring / code quality
+  - `test:` Test additions / updates
+  - `docs:` Documentation changes
+  - `chore:` Maintenance / dependency updates
+- Ensure all tests (`tox -e py314`), linting (`tox -e lint`), and type checks (`tox -e mypy`) pass before submitting PRs.
+
+### Creating Issues & Feature Requests
+Always follow the templates in [`.github/ISSUE_TEMPLATE/`](.github/ISSUE_TEMPLATE/):
+- **Bug Reports** ([`bug_report.yml`](.github/ISSUE_TEMPLATE/bug_report.yml)):
+  - Prefix title with `[Bug]: <summary>`.
+  - Include: Description, Steps to Reproduce, Expected Behavior, Environment Info (Library version, Python version, OpenEVSE WiFi Firmware version), and Debug Logs / Stack Trace.
+- **Feature Requests** ([`feature_request.yml`](.github/ISSUE_TEMPLATE/feature_request.yml)):
+  - Prefix title with `[Feature Request]: <summary>`.
+  - Include: Problem statement, Desired solution, Alternatives considered, and Context.

{python_openevse_http-1.5.0 → python_openevse_http-1.7.0}/EXTERNAL_SESSION.md

@@ -19,6 +19,7 @@ The `python-openevse-http` library requires you to pass an external `aiohttp.Cli
 import aiohttp
 from openevsehttp import OpenEVSE
 
+
 async def main():
     timeout = aiohttp.ClientTimeout(total=30)
     async with aiohttp.ClientSession(timeout=timeout) as session:
@@ -34,6 +35,7 @@ async def main():
 import aiohttp
 from openevsehttp import OpenEVSE
 
+
 async def main():
     async with aiohttp.ClientSession() as session:
         charger1 = OpenEVSE("charger1.local", session=session)
@@ -52,6 +54,7 @@ Start websocket listening from the same event loop that owns the
 import aiohttp
 from openevsehttp import OpenEVSE
 
+
 async def main():
     async with aiohttp.ClientSession() as session:
         charger = OpenEVSE("openevse.local", session=session)