chore: release 0.13.0

.claude/commands/release.md

@@ -0,0 +1,27 @@
+Cut a release candidate or stable release.
+
+Usage:
+- `/release rc` — tag the current `develop` HEAD as the next RC (e.g. `0.13.0-rc2`)
+- `/release stable` — merge `develop` into `main` and tag the final release
+
+## RC release (`/release rc`)
+
+1. Confirm the current branch is `develop` and is up to date with `origin/develop`.
+2. Read CHANGELOG.md to find the version being prepared (the top-most `## X.Y.Z` entry).
+3. List existing tags to determine the next RC number (e.g. if `0.13.0-rc1` exists, use `rc2`).
+4. Run `poetry run pytest tests` and check that CI on `develop` HEAD is green (`gh run list --branch develop --limit 3`) — do not tag if either fails.
+5. Tag `develop` HEAD as `<version>-rc<N>` and push the tag.
+6. Create the GitHub pre-release with generated notes:
+   `gh release create <tag> --verify-tag --prerelease --title <tag> --generate-notes --notes-start-tag <prev-tag>`
+7. Report the tag name, the release URL and the `git log --oneline <prev-tag>..HEAD` summary. Mention that the "build dev images" run was started by the tag.
+
+## Stable release (`/release stable`)
+
+1. Confirm CHANGELOG.md has a section for the version being released.
+2. Open a PR from `develop` → `main` titled `chore: release <version>`.
+3. After the user confirms the PR is merged, tag `main` HEAD as `<version>` and push.
+4. Create the GitHub release with generated notes, starting from the previous stable tag (not an RC) so the notes cover the whole release:
+   `gh release create <version> --verify-tag --latest --title <version> --generate-notes --notes-start-tag <prev-stable-tag>`
+5. Report the tag and the GitHub release URL.
+
+**RC tags always go on `develop`. Stable tags always go on `main`.**

.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(poetry run pytest:*)",
+      "Bash(poetry run mypy:*)",
+      "Bash(poetry run ruff check:*)",
+      "Bash(poetry run ruff format:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)"
+    ]
+  }
+}

.dockerignore

@@ -187,4 +187,9 @@ fabric.properties
 # Test results
 junit/
 
-.github/
+.github/
+
+# Not needed to build the image
+.git/
+.claude/
+tests/

.github/dependabot.yml

@@ -0,0 +1,20 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    target-branch: develop
+    schedule:
+      interval: weekly
+  - package-ecosystem: pip
+    directory: /
+    target-branch: develop
+    schedule:
+      interval: weekly
+    groups:
+      dev-dependencies:
+        dependency-type: development
+  - package-ecosystem: docker
+    directory: /
+    target-branch: develop
+    schedule:
+      interval: weekly

.github/workflows/build_and_test_python.yml

@@ -18,15 +18,16 @@ jobs:
 
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
-        python-version: [ "3.12", "3.13", "3.14" ]
+        python-version: [ "3.12", "3.13", "3.14", "3.15" ]
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'
@@ -38,10 +39,10 @@ jobs:
 
       - name: Load cached venv
         id: cached-poetry-dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@v6
         with:
           path: .venv
-          key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+          key: venv-${{ runner.os }}-py${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
 
       - name: Install dependencies
         if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'

.github/workflows/build_docker_images.yml

@@ -31,16 +31,20 @@ env:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.runner }}
     strategy:
       fail-fast: false
       matrix:
-        platform:
-          - linux/amd64
-          - linux/arm64
-          - linux/arm/v7
+        include:
+          # Native Arm runners build both Arm platforms without QEMU
+          - platform: linux/amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+          - platform: linux/arm/v7
+            runner: ubuntu-24.04-arm
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Set platform slug
         id: platform
@@ -50,9 +54,6 @@ jobs:
         id: repo
         run: echo "lowercase=${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
 
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
-
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v4
 

.gitignore

@@ -189,4 +189,7 @@ junit/
 .run/
 
 # macOS
-.DS_Store
+.DS_Store
+# Claude Code local state (commands/ is tracked)
+.claude/settings.local.json
+.claude/worktrees/

.pre-commit-config.yaml

@@ -9,12 +9,12 @@ default_language_version:
 
 repos:
   - repo: https://github.com/python-poetry/poetry
-    rev: '2.1.3'
+    rev: '2.5.1'
     hooks:
       - id: poetry-check
       - id: poetry-lock
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.0
+    rev: v0.17.1
     hooks:
       - id: ruff
         args:
@@ -38,7 +38,7 @@ repos:
         pass_filenames: false
         stages: [pre-push]
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: check-yaml
       - id: check-added-large-files

CHANGELOG.md

@@ -1,5 +1,105 @@
 # Change Log
 
+## 0.13.0
+
+### Added
+
+* Publish `drivetrain/chargingDataAvailable` (`online`/`offline`). The Battery
+  Charging sensor, Remaining charging time and Charging finished entities go
+  unavailable in Home Assistant after 3 consecutive failed charge status
+  requests, for example when the car falls into deep sleep right after a
+  charge, instead of showing a stale value. The Charging switch stays
+  available (#471).
+
+* Document the observed `chargingType` values and the availability topics in
+  the README (#472, #476).
+
+### Changed
+
+* Replace gmqtt with aiomqtt for MQTT connectivity. The new client uses a
+  pure-asyncio architecture — no more `run_coroutine_threadsafe` cross-thread
+  calls. Reconnect now uses exponential backoff (5 s → 10 s → … → 5 min)
+  instead of a fixed interval (#457).
+
+* Mark a vehicle `offline` only after 3 consecutive failed polls, so a single
+  "try again later" reply from the SAIC server no longer makes every entity
+  unavailable in Home Assistant (#475).
+
+* Require `saic-ismart-client-ng` 0.10.0 and close its HTTP client on shutdown
+  (#479).
+
+* Shut down gracefully on SIGTERM, so `docker stop` no longer ends in a
+  SIGKILL after 10 s (#481).
+
+* Upgrade development dependencies (ruff 0.17, mypy 2.4), bump the GitHub
+  Actions and pre-commit hooks, and add Dependabot (#480).
+
+* Build the Docker image on the Poetry 2.5.1 base image, build the Arm images
+  on native Arm runners instead of QEMU, and run the tests on Python 3.15 as a
+  non-blocking check (#495, #496).
+
+### Fixed
+
+* Exit immediately on permanent MQTT connection failures (bad credentials,
+  unknown protocol version, identifier rejected, not authorised) instead of
+  looping forever (#457).
+
+* Restore MQTT subscriptions and trigger HA re-discovery on broker reconnect
+  after a transient disconnect (#457).
+
+* Suppress spurious `WARNING: Could not extract a valid SoC kWh` log on every
+  poll for non-EV vehicles. The warning is preserved for EVs where the BMS
+  returns invalid data (#460).
+
+* Publish command result topics (`Success` / `Failed: …`) with `retain=False`
+  so a stale result from a previous session does not persist on the broker
+  across restarts (#461).
+
+* Emit `retain` as a JSON boolean (`true`/`false`) in Home Assistant MQTT
+  discovery payloads instead of the string `"true"`/`"false"` that the HA
+  schema requires (#459).
+
+* Do not publish the charging cable lock state for models that do not report
+  it, such as the MG ZS EV, instead of always publishing "unlocked". The
+  commanded state is published after a lock or unlock command (#477).
+
+* List what is missing when an ABRP update is skipped, instead of always
+  reporting a missing configuration (#470).
+
+* Log SAIC API timeouts and "try again later" replies as a short warning
+  without a traceback, and log failed commands on transient API errors at
+  ERROR level (#473, #474).
+
+* Fix the scheduled charging job failing with `no running event loop` since
+  the aiomqtt migration, which meant the gateway never switched to `force`
+  refresh at the scheduled charging start time (#484, #485).
+
+* Exit when the MQTT connection task ends, so Docker or Kubernetes can restart
+  the gateway instead of it running without MQTT. Running with MQTT disabled
+  is not affected (#491).
+
+* Do not hang at startup when the MQTT connection task crashes before the first
+  connection (#489), and log such crashes instead of leaving them unreported
+  (#488, #490).
+
+* Keep references to the tasks that publish to MQTT, so they cannot be
+  garbage collected before they finish, and report a clear error when
+  publishing from outside the event loop (#487, #488).
+
+* Wait up to 2 s for pending MQTT publishes on shutdown, including when the
+  shutdown happens during startup, instead of dropping them (#492).
+
+* Prefer the `RELEASE_VERSION` set at build time over the package metadata for
+  the reported gateway version (#493).
+
+* Install only the main dependency group in the Docker image (#469).
+
+* Warn when TLS hostname verification is disabled regardless of whether a
+  custom CA certificate is configured. Self-signed cert users (who typically
+  have no CA file) now see the warning too (#462).
+
+**Full Changelog**: https://github.com/SAIC-iSmart-API/saic-python-mqtt-gateway/compare/0.12.0...0.13.0
+
 ## 0.12.0
 
 ### Added

CLAUDE.md

@@ -9,6 +9,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **Always branch from `develop` for features and bugfixes.** PRs must target `develop`, not `main`. The only exception is a hotfix that must go directly to `main`.
 
+## Release process
+
+1. Merge all relevant PRs into `develop`.
+2. Add a `## <version>` section to `CHANGELOG.md` and commit it directly to `develop`.
+3. Tag `develop` as `<version>-rc<N>` (e.g. `0.13.0-rc1`) and push the tag — **RC tags live on `develop`, not `main`**.
+4. After the RC is validated, open a PR from `develop` → `main` and merge it.
+5. Tag the resulting `main` commit as the final release (e.g. `0.13.0`) and push the tag.
+6. Create a GitHub release for every tag, RC or final, with generated notes (`gh release create <tag> --verify-tag --generate-notes`). Add `--prerelease` for RCs and `--latest` for the final release. `/release` does this.
+
 ## Commands
 
 ```bash

Dockerfile

@@ -1,4 +1,4 @@
-ARG POETRY_VERSION=2.3.2
+ARG POETRY_VERSION=2.5.1
 ARG PYTHON_VERSION=3.14
 
 FROM nanomad/poetry:${POETRY_VERSION}-python-${PYTHON_VERSION} AS builder
@@ -12,7 +12,7 @@ COPY pyproject.toml poetry.lock /usr/src/app/
 
 # Install the dependencies and clear the cache afterwards.
 #   This may save some MBs.
-RUN poetry install --no-root && rm -rf $POETRY_CACHE_DIR
+RUN poetry install --no-root --only main && rm -rf $POETRY_CACHE_DIR
 
 # Now let's build the runtime image from the builder.
 #   We'll just copy the env and the PATH reference.

README.md

@@ -73,7 +73,7 @@ The following are the known available endpoints:
 |-----------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | --ha-discovery        | HA_DISCOVERY_ENABLED | Home Assistant auto-discovery is enabled (True) by default. It can be disabled (False) with this parameter.                                                                         |
 | --ha-discovery-prefix | HA_DISCOVERY_PREFIX  | The default MQTT prefix for Home Assistant auto-discovery is 'homeassistant'. Another prefix can be configured with this parameter                                                  |
-| --ha-show-unavailable | HA_SHOW_UNAVAILABLE  | Show entities as Unavailable in Home Assistant when car polling fails. Enabled (True) by default. Can be disabled, to retain the pre 0.6.x behaviour, but do that at your own risk. |
+| --ha-show-unavailable | HA_SHOW_UNAVAILABLE  | Show entities as Unavailable in Home Assistant after 3 consecutive failed polls (a single failed poll is tolerated). Enabled (True) by default. Can be disabled, to retain the pre 0.6.x behaviour, but do that at your own risk. |
 
 ### A Better Route Planner (ABRP) integration
 
@@ -229,6 +229,27 @@ with the default vehicle prefix: `saic/<saic_user>/vehicles/<vehicle_id>`
 | /refresh/period/inActiveGrace/set        | grace period (sec)                                   | After the vehicle has been shutdown, the gateway continues to query the state for 600 seconds (default value). The duration of this extended query period can be modified with this topic.                                            |
 | /location/findMyCar/set                  | [activate,lights_only,horn_only,stop]                | Activate 'find my car' with lights and horn (activate), with lights only (lights_only), with horn only (horn_only) or deactivate it (stop).                                                                                           |
 
+## Charging type values
+
+The `/drivetrain/chargingType` topic publishes the raw `chargingType` value reported by the SAIC API. The API does not
+document it. The meanings below were reported by users in
+[#398](https://github.com/SAIC-iSmart-API/saic-python-mqtt-gateway/issues/398) and checked against about 89k logged
+API responses from one vehicle (Mar 2024 – Oct 2026). They may differ between models.
+
+| Value | Reported meaning                                   | Checked against logged data                                                      |
+|-------|----------------------------------------------------|----------------------------------------------------------------------------------|
+| 0     | Car in deep sleep                                  | Not supported: 31 isolated samples between values 1 and 3, not a sustained state |
+| 1     | Car just parked                                    | Consistent (near-zero battery current)                                           |
+| 3     | HV battery in use (driving, or remote A/C on)      | Consistent (battery current under load)                                          |
+| 6     | AC charging                                        | Confirmed (on-board charger input current present)                               |
+| 7     | DC charging                                        | Confirmed (about 200 A battery current, no AC input)                             |
+| 9     | Charging stopped from the infotainment             | Unclear: both samples follow DC charging while plugged in                        |
+| 10    | Charging ended                                     | Supported: 17 of 24 samples follow AC charging while plugged in                  |
+| 16    | Car unplugged while charging was still in progress | Never observed                                                                   |
+
+Values 2, 4 and 12 were seen only 1 to 3 times each. 4 and 12 appeared around the start or end of charging, which could
+mean a transition state. Their meaning is unknown.
+
 ## Home Assistant auto-discovery
 
 The gateway supports [Home Assistant MQTT discovery](https://www.home-assistant.io/integrations/mqtt#mqtt-discovery). It
@@ -252,3 +273,17 @@ This device provides visibility into the gateway's status even when no vehicles
 ### Vehicle devices
 
 Each vehicle registered to your account appears as a separate device with sensors for drivetrain, climate, location, and more.
+
+#### Availability
+
+Two topics control when vehicle entities show as unavailable. Both publish `online` or `offline`, and both tolerate
+short glitches: they switch to `offline` only after 3 consecutive failures, and back to `online` on the next success.
+
+| Topic                                    | Goes `offline` when                                  | Entities affected                                                                       |
+|------------------------------------------|------------------------------------------------------|-----------------------------------------------------------------------------------------|
+| `<vin>/available`                        | 3 consecutive polls of the vehicle API fail          | All vehicle entities (unless `HA_SHOW_UNAVAILABLE` is disabled)                         |
+| `<vin>/drivetrain/chargingDataAvailable` | 3 consecutive charge status requests fail            | Battery Charging, Remaining charging time and Charging finished                         |
+
+The charge status request is the one that fails when the car goes into deep sleep right after a charge. The vehicle stays
+`online` in that case, so the two topics are separate. Other entities keep their last known value. The **Charging**
+switch stays available, so you can still start or stop charging from Home Assistant while the car is asleep.