Stamp firmware with git hash: boot log, /debug page

README.md

@@ -186,7 +186,7 @@ its own, and the board can be driven remotely too:
 
 | Route | Returns |
 |---|---|
-| `GET /log` | Plain-text Serial log |
+| `GET /log` | Plain-text Serial log — first line includes the firmware's git hash (see `docs/versioning.md`) |
 | `GET /last.jpg` | The last successfully fetched photo (JPEG) |
 | `GET /current` | Live capture of the panel right now, full resolution (BMP) |
 | `GET /previous` | Capture of the panel just before the most recent redraw, downscaled to a ~400px thumbnail (BMP) |

docs/versioning.md

@@ -0,0 +1,21 @@
+# Firmware versioning
+
+There's no manual version number (no semver, no CHANGELOG, no git tags) —
+one dev, no release process to serve, and a hand-bumped number is just
+another thing to forget.
+
+Instead, every build is stamped with the git commit it came from:
+`tools/version.py` runs as a PlatformIO pre-build hook and injects
+`FW_GIT_HASH` (an 8-char short hash, e.g. `a1b2c3d`, or `a1b2c3d-dirty` if
+the working tree had uncommitted changes at build time) as a compile-time
+`-D` define, shared by all board envs via `xiao_base` in `platformio.ini`.
+
+It shows up in two places on the running board:
+
+- the first line of the boot log (`/log`, `/debug`)
+- the header of the `/debug` page
+
+To find out what's actually flashed on a board, hit `/log` or `/debug` and
+read the hash — then `git show <hash>` locally to see what it was built
+from. If a build ever runs outside a git checkout (e.g. a source tarball),
+`FW_GIT_HASH` falls back to `"unknown"` rather than failing the build.

platformio.ini

@@ -13,6 +13,10 @@ board = seeed_xiao_esp32s3
 framework = arduino
 monitor_speed = 115200
 
+; Stamps FW_GIT_HASH (short commit hash, "-dirty" if uncommitted changes)
+; into every board env below. See tools/version.py and docs/versioning.md.
+extra_scripts = pre:tools/version.py
+
 ; XIAO ESP32-S3 Plus has 16 MB flash (stock board def assumes 8 MB)
 board_upload.flash_size = 16MB
 board_build.partitions = default_16MB.csv

src/main.cpp

@@ -144,7 +144,8 @@ void setup() {
     delay(esp_sleep_get_wakeup_cause() == ESP_SLEEP_WAKEUP_UNDEFINED ? 2000
                                                                      : 200);
     bootCount++;
-    devLog.printf("open-xiao-epaper: boot #%u, wake: %s\n", bootCount, wakeReason());
+    devLog.printf("open-xiao-epaper: boot #%u, wake: %s, firmware: %s\n",
+                  bootCount, wakeReason(), FW_GIT_HASH);
 
     prefs.begin("frame", false);
     loadSettings();

src/portal.cpp

@@ -225,6 +225,8 @@ static void handleLog() {
 
 static void handleDebug() {
     String page = FPSTR(DEBUG_HTML);
+    page.replace("%BOARD%", BOARD_MODEL);
+    page.replace("%HASH%", FW_GIT_HASH);
     page.replace("%LOG%", htmlEscape(devLog.snapshot()));
     server.send(200, "text/html", page);
 }

src/portal_html.h

@@ -72,6 +72,7 @@ pre{white-space:pre-wrap;word-break:break-word;background:#f4f4f4;border-radius:
 h2{font-size:1rem;margin:1.4rem 0 .3rem}</style>
 </head><body>
 <h1>Debug</h1>
+<p class="note">%BOARD% &middot; firmware %HASH%</p>
 <h2>Displayed now (last fetched photo)</h2>
 <img src="/last.jpg" alt="last fetched photo">
 <h2>On the panel right now (full resolution)</h2>

tools/version.py

@@ -0,0 +1,30 @@
+# PlatformIO pre-build hook: stamps the firmware with the git commit it was
+# built from (short hash, "-dirty" suffix if the tree has uncommitted
+# changes). This is the only versioning scheme in the project — no manual
+# semver to forget to bump; see docs/versioning.md.
+Import("env")
+
+import subprocess
+
+
+def git_hash():
+    try:
+        h = subprocess.check_output(
+            ["git", "rev-parse", "--short=8", "HEAD"],
+            stderr=subprocess.DEVNULL,
+        ).decode().strip()
+    except (subprocess.CalledProcessError, OSError):
+        return "unknown"
+
+    try:
+        dirty = subprocess.call(
+            ["git", "diff", "--quiet", "HEAD"],
+            stderr=subprocess.DEVNULL,
+        ) != 0
+    except OSError:
+        dirty = False
+
+    return h + "-dirty" if dirty else h
+
+
+env.Append(CPPDEFINES=[("FW_GIT_HASH", '\\"%s\\"' % git_hash())])