meshtastic · vidplace7 · Jul 31, 2026 · Jul 31, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -557,8 +557,9 @@ pio run -e native-macos       # Build headless macOS meshtasticd (Homebrew prere
 1. Create directory under `variants/<arch>/<name>/`
 2. Add `variant.h` with pin definitions and hardware capability defines
 3. Add `platformio.ini` with build config - use `extends` to reference common base (e.g., `esp32s3_base`)
-4. Set `custom_meshtastic_support_level = 1` (PR builds) or `2` (merge builds)
-5. For e-ink displays, add `nicheGraphics.h` for InkHUD configuration
+4. Set `board_level` (required - `release` for a normal variant; see "Build Matrix Generation")
+5. Set `custom_meshtastic_support_level` (1-3) and the other `custom_meshtastic_*` metadata
+6. For e-ink displays, add `nicheGraphics.h` for InkHUD configuration
 
 ### Adding a New Telemetry Sensor
 
@@ -642,11 +643,16 @@ The CI uses `bin/generate_ci_matrix.py` to dynamically select which targets to b
 ./bin/generate_ci_matrix.py all --level pr
 ```
 
-Variants can specify their support level in `platformio.ini`:
+Every variant env **must** declare a `board_level` in its `platformio.ini`; the matrix
+generator exits non-zero if any env is missing it or uses an unrecognized value:
 
-- `custom_meshtastic_support_level = 1` - Actively supported, built on every PR
-- `custom_meshtastic_support_level = 2` - Supported, built on merge to main branches
-- `board_level = extra` - Extra builds, only on full releases
+- `board_level = pr` - Smallest subset, built on every PR (and in every larger matrix)
+- `board_level = release` - The full release matrix, built on push / schedule / `workflow_dispatch`
+- `board_level = extra` - Opt-in only, built when explicitly requested via `--level extra`
+
+`custom_meshtastic_support_level` (1-3) is **not** part of this filtering. It is variant
+metadata that `bin/platformio-custom.py` emits as `supportLevel` in the generated
+hardware list; changing it does not change which targets CI builds.
 
 ### Running Workflows Locally
 

diff --git a/bin/generate_ci_matrix.py b/bin/generate_ci_matrix.py
@@ -5,16 +5,23 @@
 import argparse
 import json
 import re
+
 from platformio.project.config import ProjectConfig
 
+# Every variant env must declare one of these as its 'board_level':
+#   pr      - smallest subset, built on every PR (and in every larger matrix)
+#   release - the full release matrix, built on push / schedule / workflow_dispatch
+#   extra   - opt-in only, built when explicitly requested via '--level extra'
+BOARD_LEVELS = ("pr", "release", "extra")
+
 parser = argparse.ArgumentParser(description="Generate the CI matrix")
 parser.add_argument("platform", help="Platform to build for")
 parser.add_argument(
   "--level",
   choices=["extra", "pr"],
   nargs="*",
   default=[],
-  help="Board level to build for (omit for full release boards)",
+  help="Board level to build for (omit for the 'pr' + 'release' matrix)",
 )
 args = parser.parse_args()
 
@@ -39,10 +46,20 @@
   if not env_platform:
     print(f"Error: Could not determine platform for environment '{pio_env}'")
     exit(1)
+  board_level = cfg.get(f"env:{pio_env}", "board_level", default=None)
+  # Intentionally fail on a missing or unrecognized level: every env must opt in
+  # explicitly, so a new variant can't silently drop out of (or into) the matrix.
+  if board_level not in BOARD_LEVELS:
+    found = f"'{board_level}'" if board_level else "no value"
+    print(
+      f"Error: environment '{pio_env}' has {found} for 'board_level'; "
+      f"expected one of: {', '.join(BOARD_LEVELS)}"
+    )
+    exit(1)
   # Store env details as a dictionary, and add to 'all_envs' list
   env = {
     "ci": {"board": pio_env, "platform": env_platform},
-    "board_level": cfg.get(f"env:{pio_env}", "board_level", default=None),
+    "board_level": board_level,
     "board_check": cfg.get(f"env:{pio_env}", "board_check", default="false").strip().lower() == "true",
   }
   all_envs.append(env)
@@ -52,10 +69,8 @@
 if "check" in args.platform:
   for env in all_envs:
     if env["board_check"]:
-      if "pr" in args.level:
-        if env["board_level"] == "pr":
-          outlist.append(env["ci"])
-      else:
+      # '--level pr' narrows to the PR subset; otherwise check every level
+      if "pr" not in args.level or env["board_level"] == "pr":
         outlist.append(env["ci"])
 # Filter (non-check) builds by platform
 else:
@@ -67,8 +82,8 @@
       # Include board_level = 'extra' when requested
       elif "extra" in args.level and env["board_level"] == "extra":
         outlist.append(env["ci"])
-      # If no board level is specified, include in release builds (not PR)
-      elif "pr" not in args.level and not env["board_level"]:
+      # Include board_level = 'release' unless narrowed to the PR subset
+      elif "pr" not in args.level and env["board_level"] == "release":
         outlist.append(env["ci"])
 
 # Return as a JSON list

diff --git a/variants/esp32/chatter2/platformio.ini b/variants/esp32/chatter2/platformio.ini
@@ -1,6 +1,7 @@
 ; CircuitMess Chatter 2  based on ESP32-WROOM-32 (38 pins) devkit & DeeamLNK DL-LLCC68 or Heltec HT RA62 SX1262/SX1268 module
 [env:chatter2]
 extends = esp32_base
+board_level = release
 board = esp32doit-devkit-v1
 build_flags =
   ${esp32_base.build_flags}

diff --git a/variants/esp32/diy/hydra/platformio.ini b/variants/esp32/diy/hydra/platformio.ini
@@ -9,6 +9,7 @@ custom_meshtastic_display_name = Hydra
 custom_meshtastic_tags = DIY
 
 extends = esp32_base
+board_level = release
 board = esp32doit-devkit-v1
 build_flags =
   ${esp32_base.build_flags}

diff --git a/variants/esp32/diy/v1/platformio.ini b/variants/esp32/diy/v1/platformio.ini
@@ -10,6 +10,7 @@ custom_meshtastic_images = diy.svg
 custom_meshtastic_tags = DIY
 
 extends = esp32_base
+board_level = release
 board = esp32doit-devkit-v1
 board_check = true
 build_flags =

diff --git a/variants/esp32/m5stack_core/platformio.ini b/variants/esp32/m5stack_core/platformio.ini
@@ -8,6 +8,7 @@ custom_meshtastic_display_name = M5 Stack
 custom_meshtastic_tags = M5Stack
 
 extends = esp32_base
+board_level = release
 board = m5stack-core-esp32
 monitor_filters = esp32_exception_decoder
 build_src_filter = 

diff --git a/variants/esp32/m5stack_coreink/platformio.ini b/variants/esp32/m5stack_coreink/platformio.ini
@@ -1,5 +1,6 @@
 [env:m5stack-coreink]
 extends = esp32_base
+board_level = release
 board = m5stack-coreink
 board_check = true
 build_src_filter = 

diff --git a/variants/esp32/nano-g1-explorer/platformio.ini b/variants/esp32/nano-g1-explorer/platformio.ini
@@ -9,6 +9,7 @@ custom_meshtastic_display_name = Nano G1 Explorer
 custom_meshtastic_tags = B&Q
 
 extends = esp32_base
+board_level = release
 board = ttgo-tbeam
 build_flags = 
   ${esp32_base.build_flags}

diff --git a/variants/esp32/nano-g1/platformio.ini b/variants/esp32/nano-g1/platformio.ini
@@ -9,6 +9,7 @@ custom_meshtastic_display_name = Nano G1
 custom_meshtastic_tags = B&Q
 
 extends = esp32_base
+board_level = release
 board = ttgo-tbeam
 build_flags = 
   ${esp32_base.build_flags}

diff --git a/variants/esp32/radiomaster_900_bandit/platformio.ini b/variants/esp32/radiomaster_900_bandit/platformio.ini
@@ -1,5 +1,6 @@
 [env:radiomaster_900_bandit]
 extends = esp32_base
+board_level = release
 board = esp32doit-devkit-v1
 build_flags =
   ${esp32_base.build_flags}

diff --git a/variants/esp32/radiomaster_900_bandit_micro/platformio.ini b/variants/esp32/radiomaster_900_bandit_micro/platformio.ini
@@ -5,6 +5,7 @@
 ;
 [env:radiomaster_900_bandit_micro]
 extends = esp32_base
+board_level = release
 board = esp32doit-devkit-v1
 build_flags =
   ${esp32_base.build_flags}

diff --git a/variants/esp32/radiomaster_900_bandit_nano/platformio.ini b/variants/esp32/radiomaster_900_bandit_nano/platformio.ini
@@ -8,6 +8,7 @@ custom_meshtastic_display_name = RadioMaster 900 Bandit Nano
 custom_meshtastic_tags = RadioMaster
 
 extends = esp32_base
+board_level = release
 board = esp32doit-devkit-v1
 build_flags =
   ${esp32_base.build_flags}

diff --git a/variants/esp32/rak11200/platformio.ini b/variants/esp32/rak11200/platformio.ini
@@ -9,6 +9,7 @@ custom_meshtastic_images = rak11200.svg
 custom_meshtastic_tags = RAK
 
 extends = esp32_base
+board_level = release
 board = wiscore_rak11200
 board_check = true
 build_flags = 

diff --git a/variants/esp32/station-g1/platformio.ini b/variants/esp32/station-g1/platformio.ini
@@ -9,6 +9,7 @@ custom_meshtastic_display_name = Station G1
 custom_meshtastic_tags = B&Q
 
 extends = esp32_base
+board_level = release
 board = ttgo-tbeam
 build_flags = 
   ${esp32_base.build_flags}

diff --git a/variants/esp32/tbeam/platformio.ini b/variants/esp32/tbeam/platformio.ini
@@ -10,6 +10,7 @@ custom_meshtastic_images = tbeam.svg
 custom_meshtastic_tags = LilyGo
 
 extends = esp32_base
+board_level = release
 board = ttgo-tbeam
 
 board_check = true

diff --git a/variants/esp32/tlora_v2_1_16/platformio.ini b/variants/esp32/tlora_v2_1_16/platformio.ini
@@ -9,6 +9,7 @@ custom_meshtastic_images = tlora-v2-1-1_6.svg
 custom_meshtastic_tags = LilyGo
 
 extends = esp32_base
+board_level = release
 board = ttgo-lora32-v21
 board_check = true
 build_flags = 

diff --git a/variants/esp32/tlora_v3_3_0_tcxo/platformio.ini b/variants/esp32/tlora_v3_3_0_tcxo/platformio.ini
@@ -1,5 +1,6 @@
 [env:tlora-v3-3-0-tcxo]
 extends = esp32_base
+board_level = release
 board = ttgo-lora32-v21
 build_flags = 
   ${esp32_base.build_flags}

diff --git a/variants/esp32c3/heltec_hru_3601/platformio.ini b/variants/esp32c3/heltec_hru_3601/platformio.ini
@@ -1,5 +1,6 @@
 [env:heltec-hru-3601]
 extends = esp32c3_base
+board_level = release
 board = adafruit_qtpy_esp32c3
 build_flags =
   ${esp32c3_base.build_flags}

diff --git a/variants/esp32c6/m5stack_unitc6l/platformio.ini b/variants/esp32c6/m5stack_unitc6l/platformio.ini
@@ -9,6 +9,7 @@ custom_meshtastic_images = m5_c6l.svg
 custom_meshtastic_tags = M5Stack
 
 extends = esp32c6_base
+board_level = release
 board = esp32-c6-devkitc-1
 board_upload.flash_size = 16MB
 board_build.partitions = default_16MB.csv

diff --git a/variants/esp32s3/CDEBYTE_EoRa-S3/platformio.ini b/variants/esp32s3/CDEBYTE_EoRa-S3/platformio.ini
@@ -9,6 +9,7 @@ custom_meshtastic_tags = EByte
 custom_meshtastic_requires_dfu = true
 
 extends = esp32s3_base
+board_level = release
 board = CDEBYTE_EoRa-S3
 build_flags =
   ${esp32s3_base.build_flags}

diff --git a/variants/esp32s3/ELECROW-ThinkNode-G3/platformio.ini b/variants/esp32s3/ELECROW-ThinkNode-G3/platformio.ini
@@ -1,5 +1,6 @@
 [env:thinknode_g3]
 extends = esp32s3_base
+board_level = release
 board = ESP32-S3-WROOM-1-N4
 board_build.psram_type = opi
 

diff --git a/variants/esp32s3/ELECROW-ThinkNode-M2/platformio.ini b/variants/esp32s3/ELECROW-ThinkNode-M2/platformio.ini
@@ -10,6 +10,7 @@ custom_meshtastic_tags = Elecrow
 custom_meshtastic_requires_dfu = false
 
 extends = esp32s3_base
+board_level = release
 board = ESP32-S3-WROOM-1-N4
 build_flags =
   ${esp32s3_base.build_flags}

diff --git a/variants/esp32s3/ELECROW-ThinkNode-M5/platformio.ini b/variants/esp32s3/ELECROW-ThinkNode-M5/platformio.ini
@@ -10,6 +10,7 @@ custom_meshtastic_tags = Elecrow
 custom_meshtastic_requires_dfu = false
 
 extends = esp32s3_base
+board_level = release
 board = ESP32-S3-WROOM-1-N4
 build_src_filter =
   ${esp32s3_base.build_src_filter}

diff --git a/variants/esp32s3/elecrow_panel/platformio.ini b/variants/esp32s3/elecrow_panel/platformio.ini
@@ -91,6 +91,7 @@ custom_meshtastic_partition_scheme = 16MB
 custom_meshtastic_has_mui = true
 
 extends = crowpanel_small_esp32s3_base
+board_level = release
 build_flags =
   ${crowpanel_small_esp32s3_base.build_flags}
   -D SPI_FREQUENCY=80000000
@@ -127,6 +128,7 @@ custom_meshtastic_partition_scheme = 16MB
 custom_meshtastic_has_mui = true
 
 extends = crowpanel_small_esp32s3_base
+board_level = release
 build_flags =
   ${crowpanel_small_esp32s3_base.build_flags}
   -D LV_CACHE_DEF_SIZE=2097152
@@ -166,6 +168,7 @@ custom_meshtastic_partition_scheme = 16MB
 custom_meshtastic_has_mui = true
 
 extends = crowpanel_large_esp32s3_base
+board_level = release
 build_flags =
   ${crowpanel_large_esp32s3_base.build_flags}
   -D VIEW_320x240

diff --git a/variants/esp32s3/hackaday-communicator/platformio.ini b/variants/esp32s3/hackaday-communicator/platformio.ini
@@ -1,6 +1,7 @@
 ; Hackaday Communicator
 [env:hackaday-communicator]
 extends = esp32s3_base
+board_level = release
 board = hackaday-communicator
 board_check = true
 board_build.partitions = default_16MB.csv

diff --git a/variants/esp32s3/heltec_capsule_sensor_v3/platformio.ini b/variants/esp32s3/heltec_capsule_sensor_v3/platformio.ini
@@ -1,5 +1,6 @@
 [env:heltec_capsule_sensor_v3]
 extends = esp32s3_base
+board_level = release
 board = heltec_wifi_lora_32_V3
 board_check = true
 board_build.partitions = default_8MB.csv

diff --git a/variants/esp32s3/heltec_sensor_hub/platformio.ini b/variants/esp32s3/heltec_sensor_hub/platformio.ini
@@ -1,5 +1,6 @@
 [env:heltec_sensor_hub]
 extends = esp32s3_base
+board_level = release
 board = heltec_wifi_lora_32_V3
 board_check = true
 

diff --git a/variants/esp32s3/heltec_v4/platformio.ini b/variants/esp32s3/heltec_v4/platformio.ini
@@ -24,6 +24,7 @@ custom_meshtastic_partition_scheme = 16MB
 custom_meshtastic_has_mui = true
 
 extends = heltec_v4_base
+board_level = release
 build_flags =
   ${heltec_v4_base.build_flags}
   -D HELTEC_V4_OLED
@@ -48,6 +49,7 @@ custom_meshtastic_requires_dfu = true
 custom_meshtastic_partition_scheme = 16MB
 
 extends = heltec_v4_base
+board_level = release
 build_flags = 
   ${heltec_v4_base.build_flags} ;-Os
   -D HELTEC_V4_TFT

diff --git a/variants/esp32s3/heltec_v4_r8/platformio.ini b/variants/esp32s3/heltec_v4_r8/platformio.ini
@@ -24,6 +24,7 @@ custom_meshtastic_requires_dfu = true
 custom_meshtastic_partition_scheme = 16MB
 
 extends = heltec_v4_r8_base
+board_level = release
 build_flags = 
   ${heltec_v4_r8_base.build_flags}
   -D HELTEC_V4_R8_OLED
@@ -46,6 +47,7 @@ custom_meshtastic_requires_dfu = true
 custom_meshtastic_partition_scheme = 16MB
 
 extends = heltec_v4_r8_base
+board_level = release
 build_flags = 
   ${heltec_v4_r8_base.build_flags} ;-Os
   -D HELTEC_V4_R8_TFT

diff --git a/variants/esp32s3/heltec_vision_master_e213/platformio.ini b/variants/esp32s3/heltec_vision_master_e213/platformio.ini
@@ -12,6 +12,7 @@ custom_meshtastic_partition_scheme = 8MB
 custom_meshtastic_has_ink_hud = true
 
 extends = esp32s3_base
+board_level = release
 board = heltec_vision_master_e213
 board_build.partitions = default_8MB.csv
 build_flags = 

diff --git a/variants/esp32s3/heltec_vision_master_e290/platformio.ini b/variants/esp32s3/heltec_vision_master_e290/platformio.ini
@@ -13,6 +13,7 @@ custom_meshtastic_partition_scheme = 8MB
 custom_meshtastic_has_ink_hud = true
 
 extends = esp32s3_base
+board_level = release
 board = heltec_vision_master_e290
 board_build.partitions = default_8MB.csv
 build_flags = 
@@ -38,6 +39,7 @@ upload_speed = 115200
 
 [env:heltec-vision-master-e290-inkhud]
 extends = esp32s3_base, inkhud
+board_level = release
 board = heltec_vision_master_e290
 board_build.partitions = default_8MB.csv
 build_src_filter = 

diff --git a/variants/esp32s3/heltec_vision_master_t190/platformio.ini b/variants/esp32s3/heltec_vision_master_t190/platformio.ini
@@ -11,6 +11,7 @@ custom_meshtastic_requires_dfu = true
 custom_meshtastic_partition_scheme = 8MB
 
 extends = esp32s3_base
+board_level = release
 board = heltec_vision_master_t190
 board_build.partitions = default_8MB.csv
 build_flags = 

diff --git a/variants/esp32s3/heltec_wireless_paper/platformio.ini b/variants/esp32s3/heltec_wireless_paper/platformio.ini
@@ -12,6 +12,7 @@ custom_meshtastic_partition_scheme = 8MB
 custom_meshtastic_has_ink_hud = true
 
 extends = esp32s3_base
+board_level = release
 board = heltec_wifi_lora_32_V3
 board_build.partitions = default_8MB.csv
 build_flags = 
@@ -35,6 +36,7 @@ upload_speed = 115200
 
 [env:heltec-wireless-paper-inkhud]
 extends = esp32s3_base, inkhud
+board_level = release
 board = heltec_wifi_lora_32_V3
 board_build.partitions = default_8MB.csv
 build_src_filter =