chore: archive diagnostics and project documentation

tools/firmware_info.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+FIRMWARE_PATH="${1:-${ROOT_DIR}/build/TQ_Cat_Code.bin}"
+VERSION_FILE="${ROOT_DIR}/version.txt"
+
+fail() {
+    echo "Error: $1" >&2
+    exit 1
+}
+
+if [[ ! -f "${FIRMWARE_PATH}" ]]; then
+    fail "firmware binary not found: ${FIRMWARE_PATH}"
+fi
+
+# ESP-IDF places esp_app_desc_t at image offset 0x20. Its magic word is
+# 0xABCD5432 and its 32-byte application version starts at offset 0x30.
+APP_DESC_MAGIC="$(od -An -tx1 -j 32 -N 4 "${FIRMWARE_PATH}" | tr -d '[:space:]')"
+if [[ "${APP_DESC_MAGIC}" != "3254cdab" ]]; then
+    fail "not a supported ESP-IDF application image: ${FIRMWARE_PATH}"
+fi
+
+FIRMWARE_VERSION="$(
+    dd if="${FIRMWARE_PATH}" bs=1 skip=48 count=32 2>/dev/null |
+        LC_ALL=C tr -d '\000'
+)"
+if [[ -z "${FIRMWARE_VERSION}" ]]; then
+    fail "firmware version is empty: ${FIRMWARE_PATH}"
+fi
+
+SIZE_BYTES="$(wc -c < "${FIRMWARE_PATH}" | tr -d '[:space:]')"
+if command -v sha256sum >/dev/null 2>&1; then
+    SHA256="$(sha256sum "${FIRMWARE_PATH}" | awk '{print $1}')"
+elif command -v shasum >/dev/null 2>&1; then
+    SHA256="$(shasum -a 256 "${FIRMWARE_PATH}" | awk '{print $1}')"
+else
+    fail "neither sha256sum nor shasum is available"
+fi
+
+echo "version=${FIRMWARE_VERSION}"
+echo "sizeBytes=${SIZE_BYTES}"
+echo "sha256=${SHA256}"
+
+if [[ -f "${VERSION_FILE}" ]]; then
+    SOURCE_VERSION="$(tr -d '\r\n' < "${VERSION_FILE}")"
+    if [[ -n "${SOURCE_VERSION}" && "${SOURCE_VERSION}" != "${FIRMWARE_VERSION}" ]]; then
+        echo "Warning: version.txt=${SOURCE_VERSION}, but the binary contains ${FIRMWARE_VERSION}; rebuild the firmware." >&2
+    fi
+fi