Require version suffix for loaner firmware

Enforce the calendar-style OEFW-LNR banner and document the workflow so CHIRP recognises the build. closes #10

Author: aditaa

BUILDING.md

@@ -32,14 +32,15 @@ When you already have the toolchain locally, you can mirror the Docker steps:
    ```
    The above command produces `loaner-firmware.bin`. If Python with `crcmod` is installed you will also get `loaner-firmware.packed.bin`.  
    If you omit `TARGET=...` the files are named `firmware.bin` / `firmware.packed.bin`.
+   The build also exports `VERSION_SUFFIX` into the binaries. Set it explicitly (for example `make TARGET=loaner-firmware VERSION_SUFFIX=LNR24A5`) or create an `LNR*` git tag that the Makefile can discover. The build errors out if neither is present.
 
 ## Creating a Packed Binary Manually
 If the packed image was not produced automatically (for example on a minimal native setup), run:
 ```sh
 python3 fw-pack.py loaner-firmware.bin LNR24.03 loaner-firmware.packed.bin
 ```
 
-- The second argument is the version tag embedded in both the welcome screen and the packed metadata.  
+- The second argument is the version tag embedded in both the welcome screen and the packed metadata (mirror the `VERSION_SUFFIX` you build with).  
   Keep it under 10 ASCII characters (the script rejects longer strings).
 - The packed image is required for PC loader flashing because it carries the metadata Quansheng's tool expects.
 
@@ -60,13 +61,14 @@ Feature flags live near the top of `Makefile` as `ENABLE_*` macros. Adjust them
 
 ## Firmware Metadata and Releases
 - A successful build leaves you with `firmware.bin` (raw) and, when Python and `crcmod` are available, `firmware.packed.bin`. The packed image is what Quansheng's loader validates.
-- Use `fw-pack.py` to stamp a release tag into the packed image. The second argument becomes the welcome banner and metadata field:
+- Use `fw-pack.py` to stamp a release tag into the packed image. `make` already invokes the script with `VERSION_SUFFIX`, so the packed file inherits the same banner. To repack manually, pass the suffix yourself:
   ```sh
-  python3 fw-pack.py firmware.bin LNR24.03 loaner-firmware.packed.bin
+  python3 fw-pack.py firmware.bin "${VERSION_SUFFIX}" loaner-firmware.packed.bin
   ```
+- When building outside of Docker, set `VERSION_SUFFIX` in your environment once (for example `export VERSION_SUFFIX=LNR24A5`) so every command picks up the same value.
 - Change the `TARGET` on the `make` command line to tweak the output filenames without editing source, for example `make TARGET=loaner-firmware`.
 - Before publishing a release, spot-check the welcome screen on hardware to make sure the tag matches what you intend to share with end users.
-- Recommended version format: mirror other UV-K5 firmware projects (Quansheng's stock firmware ships as `v2.1.27`, Open Edition uses `OEFW-2023.09`). Tag milestones as `vYY.MM[.PATCH]` and feed a matching, <=10 character suffix to `fw-pack.py` (for example `LNR24.03`). CHIRP reads the full `*OEFW-LNR24.03` banner and treats it as a known build.
+- Recommended version format: mirror other UV-K5 firmware projects (Quansheng's stock firmware ships as `v2.1.27`, Open Edition uses `OEFW-2023.09`). Tag milestones as `vYY.MM[.PATCH]` and feed a matching, <=10 character `VERSION_SUFFIX` (for example `LNR24.03`). CHIRP reads the full `*OEFW-LNR24.03` banner and treats it as a known build.
 
 ## Branching and Release Flow
 1. Start work on a fresh branch instead of `main`:

Makefile

@@ -115,13 +115,30 @@ SIZE = arm-none-eabi-size
 
 GIT_HASH := $(shell git rev-parse --short HEAD)
 
+VERSION_SUFFIX ?= $(shell git describe --tags --match 'LNR*' --abbrev=0 2>/dev/null)
+
+ifeq ($(MAKECMDGOALS),)
+  ifeq ($(strip $(VERSION_SUFFIX)),)
+    $(error VERSION_SUFFIX is required. Set VERSION_SUFFIX=LNR24A5 or create an LNR* tag.)
+  endif
+else
+  ifneq ($(filter-out clean,$(MAKECMDGOALS)),)
+    ifeq ($(strip $(VERSION_SUFFIX)),)
+      $(error VERSION_SUFFIX is required. Set VERSION_SUFFIX=LNR24A5 or create an LNR* tag.)
+    endif
+  endif
+endif
+
+VERSION_SUFFIX_ESCAPED := $(subst ",\",$(VERSION_SUFFIX))
+
 ASFLAGS = -c -mcpu=cortex-m0
 ifeq ($(ENABLE_OVERLAY),1)
 ASFLAGS += -DENABLE_OVERLAY
 endif
 CFLAGS = -Os -Wall -Werror -mcpu=cortex-m0 -fno-builtin -fshort-enums -fno-delete-null-pointer-checks -std=c11 -MMD
 CFLAGS += -DPRINTF_INCLUDE_CONFIG_H
 CFLAGS += -DGIT_HASH=\"$(GIT_HASH)\"
+CFLAGS += -DVERSION_SUFFIX=\"$(VERSION_SUFFIX_ESCAPED)\"
 ifeq ($(ENABLE_AIRCOPY),1)
 CFLAGS += -DENABLE_AIRCOPY
 endif
@@ -165,8 +182,8 @@ DEPS = $(OBJS:.o=.d)
 
 all: $(TARGET)
 	$(OBJCOPY) -O binary $< $<.bin
-	-python fw-pack.py $<.bin $(GIT_HASH) $<.packed.bin
-	-python3 fw-pack.py $<.bin $(GIT_HASH) $<.packed.bin
+	-python fw-pack.py $<.bin $(VERSION_SUFFIX) $<.packed.bin
+	-python3 fw-pack.py $<.bin $(VERSION_SUFFIX) $<.packed.bin
 	$(SIZE) $<
 
 debug:
@@ -194,4 +211,3 @@ bsp/dp32g030/%.h: hardware/dp32g030/%.def
 
 clean:
 	rm -f $(TARGET).bin $(TARGET).packed.bin $(TARGET) $(OBJS) $(DEPS)
-

README.md

@@ -36,6 +36,8 @@ This build assumes the channel plan lives on your ICS-205. To move that plan int
 5. Upload the plan with `Radio -> Upload To Radio`. After the radio reboots, rotate the channel knob and verify that the display shows the ICS-205 names.
 6. Repeat for each handset; the standard workflow keeps the handset in channel mode, so operators only see the memories you defined.
 
+Use a CHIRP build that includes the UV-K5 loaner whitelist from PR #1414 (or any newer release); older builds will block uploads because they do not recognise the `OEFW-LNR` banner yet.
+
 Tip: Keep a CHIRP image with the baseline loaner plan in source control so teams can diff changes before distributing updates.
 
 ## Flashing

main.c

@@ -37,8 +37,12 @@
 #include "ui/lock.h"
 #include "ui/welcome.h"
 
+#ifndef VERSION_SUFFIX
+#define VERSION_SUFFIX GIT_HASH
+#endif
+
 #if defined(ENABLE_UART)
-static const char Version[] = "UV-K5 Firmware, Open Edition, OEFW-"GIT_HASH"\r\n";
+static const char Version[] = "UV-K5 Firmware, Open Edition, OEFW-" VERSION_SUFFIX "\r\n";
 #endif
 
 void _putchar(char c)
@@ -149,4 +153,3 @@ void Main(void)
 		}
 	}
 }
-

version.c

@@ -1,2 +1,5 @@
-const char Version[] = "OEFW-" GIT_HASH;
+#ifndef VERSION_SUFFIX
+#define VERSION_SUFFIX GIT_HASH
+#endif
 
+const char Version[] = "OEFW-" VERSION_SUFFIX;