Merge pull request #16 from AndrewDemsDS/devops/tier1-hardening

DevOps hardening + ESP32 softwareVersion fix

Author: AndrewDemsDS

.github/dependabot.yml

@@ -0,0 +1,29 @@
+version: 2
+# Automated dependency-update PRs. GitHub Actions are SHA-pinned in the workflows
+# (supply-chain safety); Dependabot proposes the bumps as reviewable PRs so the pins
+# stay current without hand-resolving SHAs. Python ecosystems track the pinned
+# requirements files added for the OTA + reverse-engineering tooling.
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci
+    groups:
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: pip
+    directory: /firmware/scripts
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: build
+
+  - package-ecosystem: pip
+    directory: /reverse-engineering/tools
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: build

.github/workflows/amebaz2-release.yaml

@@ -16,7 +16,7 @@ jobs:
   build:
     runs-on: [self-hosted, sdk-builder]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Provision build env from the runner host
         run: |
@@ -43,8 +43,9 @@ jobs:
           sha256sum "flash_rac-integrated-v$V.bin" "rac-v$V.ota" "rac-v$V.json" > "SHA256SUMS-v$V.txt"
 
       - name: Attach to the GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2.6.2
         with:
+          generate_release_notes: true   # auto "What's Changed" from commits/PRs since the last tag
           files: |
             firmware/built-images/flash_rac-integrated-v${{ env.V }}.bin
             firmware/built-images/rac-v${{ env.V }}.ota

.github/workflows/esp32-release.yaml

@@ -21,7 +21,7 @@ jobs:
       run:
         shell: bash   # ESP-IDF export.sh + esp-matter export.sh are bash
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Tag must match CMake PROJECT_VER
         run: |
@@ -48,8 +48,9 @@ jobs:
             partition_table/partition-table.bin ota_data_initial.bin flasher_args.json > SHA256SUMS.txt
 
       - name: Attach to the GitHub Release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65 # v2.6.2
         with:
+          generate_release_notes: true   # auto "What's Changed" from commits/PRs since the last tag
           files: |
             firmware/esp32-matter/build/hisense_ac_matter.bin
             firmware/esp32-matter/build/bootloader/bootloader.bin

.github/workflows/qa.yaml

@@ -17,10 +17,26 @@ jobs:
   host-qa:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
         with:
           fetch-depth: 0   # PR version-diff needs base history
 
+      # Static lint first (cheap, fails fast). Run these same two commands locally for parity.
+      # shellcheck ships on the runner image; --severity=warning gates real bugs (quoting, unset
+      # vars, logic) and skips the info/style nits the scripts intentionally use. ruff reads the
+      # committed ruff.toml; it's pinned via pipx (bump with the local version + Dependabot).
+      - name: Shell lint (shellcheck)
+        run: |
+          shellcheck --version
+          shellcheck --severity=warning firmware/scripts/*.sh firmware/test/*.sh \
+            firmware/.githooks/pre-commit firmware/.githooks/prepare-commit-msg
+
+      - name: Python lint (ruff)
+        run: pipx run ruff==0.15.20 check .
+
+      - name: ESP32 version consistency
+        run: bash firmware/scripts/esp32-lint.sh
+
       - name: Host QA + lint
         run: bash firmware/scripts/ota-release.sh lint
 
@@ -29,9 +45,12 @@ jobs:
         env:
           BASE: ${{ github.base_ref }}
         run: |
+          # Scope to firmware/src (the shipped image is built from it + the .zap under sdk-edits).
+          # firmware/test is host-only QA that never changes the image, so a test-tooling edit must
+          # NOT force a softwareVersion bump.
           git fetch --no-tags --depth=1 origin "$BASE" || true
-          if git diff --quiet FETCH_HEAD -- firmware/src firmware/test; then
-            echo "no firmware/src|test change vs $BASE -- bump not required"; exit 0
+          if git diff --quiet FETCH_HEAD -- firmware/src; then
+            echo "no firmware/src change vs $BASE -- bump not required"; exit 0
           fi
           new=$(bash firmware/scripts/ota-release.sh verint "$(cat firmware/src/version.txt)")
           oldsem=$(git show "FETCH_HEAD:firmware/src/version.txt" 2>/dev/null | tr -d '[:space:]' || true)

CHANGELOG.md

@@ -21,4 +21,4 @@ First public cut. Everything below already ran privately; this release drops the
   covers codec, Matter↔A/C mapping, and virtual-A/C round-trip checks.
 - Reverse-engineering docs: RS-485 protocol, cloud/firewall, stock-FW init, hardware.
 - CI: a host lint gate on every push/PR, plus tagged-release builds that attach `.bin`/`.ota` to
-  GitHub Releases (ESP32 on a hosted runner, AmebaZ2 on a self-hosted SDK runner).
+  GitHub Releases (both the AmebaZ2 and ESP32 builds run on a self-hosted SDK runner).

firmware/.githooks/pre-commit

@@ -10,6 +10,13 @@ if git diff --cached --name-only | grep -qE '^firmware/(src|test)/|room-air-cond
     echo "[pre-commit] LINT FAILED. Fix, or bypass with: git commit --no-verify"; exit 1; }
 fi
 
+# ESP32 tree has no SDK-free build gate; esp32-lint.sh checks version consistency (host-only).
+if git diff --cached --name-only | grep -qE '^firmware/esp32-matter/'; then
+  echo "[pre-commit] esp32 firmware changed -> esp32-lint.sh"
+  bash "$REPO/firmware/scripts/esp32-lint.sh" || {
+    echo "[pre-commit] ESP32 LINT FAILED. Fix, or bypass with: git commit --no-verify"; exit 1; }
+fi
+
 # Prose slop gate: block em dashes in newly-added markdown (no-op when no .md is staged).
 bash "$REPO/firmware/scripts/stop-slop.sh" || exit 1
 

firmware/esp32-matter/.gitignore

@@ -1,7 +1,8 @@
-# ESP-IDF / esp-matter build outputs (all regenerable from source + sdkconfig.defaults)
+# ESP-IDF / esp-matter build outputs (regenerable from source + sdkconfig.defaults).
+# NOTE: dependencies.lock is intentionally TRACKED (not ignored) -- it pins the exact
+# managed-component versions/hashes for reproducible builds, per ESP-IDF's own guidance.
 build/
 .cache/
 managed_components/
-dependencies.lock
 sdkconfig
 sdkconfig.old

firmware/esp32-matter/CMakeLists.txt

@@ -2,7 +2,7 @@
 #   . ~/esp/esp-idf-v5.5.4/export.sh && . $ESP_MATTER_PATH/export.sh
 #   idf.py set-target esp32 && idf.py build flash monitor
 cmake_minimum_required(VERSION 3.16)
-set(PROJECT_VER "1.0.7")
+set(PROJECT_VER "1.0.8")
 
 # Unified versioning (issue #77): the Matter softwareVersion INT is DERIVED from PROJECT_VER --
 # MAJOR*10000+MINOR*100+PATCH -> a readable, strictly-monotonic uint32. This keeps the human
@@ -15,6 +15,14 @@ list(GET _ver_parts 1 _ver_minor)
 list(GET _ver_parts 2 _ver_patch)
 math(EXPR PROJECT_VER_INT "${_ver_major}*10000 + ${_ver_minor}*100 + ${_ver_patch}")
 
+# esp-matter's build reads PROJECT_VER_NUMBER (NOT our PROJECT_VER_INT) to set the GN arg
+# chip_config_software_version_number -> CHIP_CONFIG_SOFTWARE_VERSION_NUMBER, and that macro is what
+# ESP32 ConfigurationManagerImpl::GetSoftwareVersion() returns -- i.e. the BasicInformation
+# SoftwareVersion attribute (0/40/9) that HA + Matter OTA see. esp-matter/CMakeLists.txt defaults it
+# to 0 when PROJECT_VER_NUMBER is undefined, which is why the device reported softwareVersion 0
+# despite the correct semver string. Define the name esp-matter looks for. (issue #77)
+set(PROJECT_VER_NUMBER ${PROJECT_VER_INT})
+
 if(NOT DEFINED ENV{ESP_MATTER_PATH})
     message(FATAL_ERROR "ESP_MATTER_PATH not set -- run: . <esp-matter>/export.sh")
 endif()
@@ -48,9 +56,9 @@ idf_build_set_property(COMPILE_OPTIONS "-Wno-format-nonliteral;-Wno-format-secur
 # keeps the literal path out of this tracked file; everything (IDF, esp-matter, project) sits under it.
 idf_build_set_property(COMPILE_OPTIONS "-ffile-prefix-map=$ENV{HOME}=/build" APPEND)
 
-# Force the Matter softwareVersion int from PROJECT_VER (issue #77). Wins over sdkconfig's
-# CONFIG_DEVICE_SOFTWARE_VERSION_NUMBER because CHIPDeviceConfig.h guards the macro with #ifndef,
-# so the OTA int can never drift from the semver. (The string stays in sdkconfig.defaults, kept
-# equal to PROJECT_VER.)
+# Also pin CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION (a DIFFERENT macro from the
+# CHIP_CONFIG_SOFTWARE_VERSION_NUMBER above that GetSoftwareVersion actually returns) for the CHIP
+# code paths that read it (e.g. some OTA-requestor defaults). Belt-and-suspenders; the reported
+# softwareVersion attribute comes from PROJECT_VER_NUMBER -> chip_config_software_version_number.
 idf_build_set_property(COMPILE_DEFINITIONS "CHIP_DEVICE_CONFIG_DEVICE_SOFTWARE_VERSION=${PROJECT_VER_INT}" APPEND)
 message(STATUS "hisense: Matter softwareVersion ${PROJECT_VER_INT} (\"${PROJECT_VER}\") [issue #77]")

firmware/esp32-matter/dependencies.lock

@@ -0,0 +1,70 @@
+dependencies:
+  espressif/cjson:
+    component_hash: e788323270d90738662d66fffa910bfe1fba019bba087f01557e70c40485b469
+    dependencies:
+    - name: idf
+      require: private
+      version: '>=5.0'
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 1.7.19~2
+  espressif/esp_delta_ota:
+    component_hash: 147161b602ef51e9f6649eb6d90c4d4ac3c94228cb264fa0e68be7877180462d
+    dependencies:
+    - name: idf
+      require: private
+      version: '>=4.3'
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 1.1.4
+  espressif/esp_encrypted_img:
+    component_hash: a3d20984246263bf8f3fabb0cf5ced72e1499dcc0073fc7334646c0882fd1b3c
+    dependencies:
+    - name: espressif/esp_secure_cert_mgr
+      registry_url: https://components.espressif.com
+      require: private
+      rules:
+      - if: idf_version >= 5.3
+      version: '>=2.5.1'
+    - name: idf
+      require: private
+      version: '>=5.0'
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 2.7.0
+  espressif/esp_secure_cert_mgr:
+    component_hash: 40a986c1f45d91eb6d339ca51dcab90c4ecce2a6622c268edaaa05887852d464
+    dependencies:
+    - name: idf
+      require: private
+      version: '>=4.3'
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 2.9.2
+  espressif/mdns:
+    component_hash: e81ca7a7f53ea34e78274df054da692c272e1315572876b237b1748e267c013b
+    dependencies:
+    - name: idf
+      require: private
+      version: '>=5.0'
+    source:
+      registry_url: https://components.espressif.com/
+      type: service
+    version: 1.11.3
+  idf:
+    source:
+      type: idf
+    version: 5.5.4
+direct_dependencies:
+- espressif/cjson
+- espressif/esp_delta_ota
+- espressif/esp_encrypted_img
+- espressif/esp_secure_cert_mgr
+- espressif/mdns
+manifest_hash: 23158991195c91464282b0a6d37181b80b3866864ee8d0b7330ae1c3b40c7681
+target: esp32
+version: 2.0.0

firmware/esp32-matter/sdkconfig.defaults

@@ -42,10 +42,12 @@ CONFIG_ENABLE_OTA_REQUESTOR=y
 CONFIG_CUSTOM_DEVICE_INFO_PROVIDER=y
 # Matter OTA software version. Unified scheme (issue #77): the int is DERIVED from PROJECT_VER
 # in CMakeLists.txt (MAJOR*10000+MINOR*100+PATCH) and injected as a compile definition that WINS
-# over this Kconfig value (CHIPDeviceConfig.h #ifndef guard). These are kept equal to PROJECT_VER
-# "1.0.3" (-> 10003) for clarity/fallback; edit PROJECT_VER, not this, and they stay in sync.
-CONFIG_DEVICE_SOFTWARE_VERSION_NUMBER=10005
-CONFIG_DEVICE_SOFTWARE_VERSION_STRING="1.0.5"
+# over this Kconfig NUMBER (CHIPDeviceConfig.h #ifndef guard). The STRING is NOT overridden by CMake,
+# so it (and the fallback NUMBER) MUST stay equal to PROJECT_VER or the device reports a stale
+# softwareVersionString. Edit PROJECT_VER in CMakeLists.txt, then update both lines below.
+# esp32-lint.sh enforces this equality (fails the commit/CI if they drift).
+CONFIG_DEVICE_SOFTWARE_VERSION_NUMBER=10008
+CONFIG_DEVICE_SOFTWARE_VERSION_STRING="1.0.8"
 # --- OTA hardening (faster + reliable on marginal Wi-Fi) ---
 # Delta OTA: ship a diff (tens of KB) instead of the full ~1.5MB image over BDX.
 CONFIG_ENABLE_DELTA_OTA=y