From 9844b541b6e37b9fbcbe789f28590fede7c72515 Mon Sep 17 00:00:00 2001
From: Ben Allfree <ben@benallfree.com>
Date: Thu, 26 Feb 2026 20:37:27 -0800
Subject: [PATCH 01/29] fix: JSON parsing regression in build

---
 build.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/build.sh b/build.sh
index 313c4c47a..23e31ab25 100755
--- a/build.sh
+++ b/build.sh
@@ -93,7 +93,7 @@ get_pio_envs_ending_with_string() {
 # $1 should be the environment name
 get_platform_for_env() {
   local env_name=$1
-  echo "$PIO_CONFIG_JSON" | python3 -c "
+  printf '%s' "$PIO_CONFIG_JSON" | python3 -c "
 import sys, json, re
 data = json.load(sys.stdin)
 for section, options in data:

From b8b6598dd3ab47489767167aa85ce727c5823054 Mon Sep 17 00:00:00 2001
From: UltimateCodeWarrior <UltimateCodeWarrior@users.noreply.github.com>
Date: Mon, 22 Jun 2026 23:30:35 -0700
Subject: [PATCH 02/29] Fix blank OLED on T-Beam Supreme V3 (I2C bus + 0x3D
 address)

The SH1106 OLED on the LilyGo T-Beam Supreme V3 never lights up because:

1. The primary I2C bus (Wire) that the OLED, BME280 and magnetometer share
   is never initialized. The PMU/RTC use Wire1 (via XPowersLib); nothing
   brings up Wire on PIN_BOARD_SDA/PIN_BOARD_SCL, so the display driver
   talks on the wrong default pins.
2. The OLED is at I2C address 0x3D on this board (0x3C is taken by the
   QMC6310 magnetometer), but SH1106Display::begin() only tried 0x3C.

Initialize Wire for TBEAM_SUPREME_SX1262, and have SH1106Display::begin()
prefer 0x3D (only ever used by the OLED) before falling back to 0x3C.
Backwards-compatible for boards with the OLED at 0x3C.

Closes #2609
---
 src/helpers/esp32/TBeamBoard.cpp | 10 ++++++++++
 src/helpers/ui/SH1106Display.cpp | 12 +++++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/src/helpers/esp32/TBeamBoard.cpp b/src/helpers/esp32/TBeamBoard.cpp
index 5f708d71d..d9f6e0227 100644
--- a/src/helpers/esp32/TBeamBoard.cpp
+++ b/src/helpers/esp32/TBeamBoard.cpp
@@ -16,6 +16,16 @@ void TBeamBoard::begin() {
     
     ESP32Board::begin();
 
+#ifdef TBEAM_SUPREME_SX1262
+    // On the T-Beam S3 Supreme the PMU + RTC sit on Wire1 (GPIO 42/41, brought
+    // up by XPowersLib), while the SH1106 OLED and the BME280/QMC6310 sensors
+    // sit on the primary bus, Wire (GPIO PIN_BOARD_SDA/PIN_BOARD_SCL). Nothing
+    // else initialises Wire on this board, so the display driver would
+    // otherwise talk on the wrong (default) pins and display.begin() fails,
+    // leaving the screen blank. Bring the OLED bus up here.
+    Wire.begin(PIN_BOARD_SDA, PIN_BOARD_SCL);
+#endif
+
     power_init();
 
     //Configure user button
diff --git a/src/helpers/ui/SH1106Display.cpp b/src/helpers/ui/SH1106Display.cpp
index f383bb005..86c6089bc 100644
--- a/src/helpers/ui/SH1106Display.cpp
+++ b/src/helpers/ui/SH1106Display.cpp
@@ -11,7 +11,17 @@ bool SH1106Display::i2c_probe(TwoWire &wire, uint8_t addr)
 
 bool SH1106Display::begin()
 {
-  return display.begin(DISPLAY_ADDRESS, true) && i2c_probe(Wire, DISPLAY_ADDRESS);
+  // Address selection: on some board revisions (notably the LilyGo T-Beam
+  // Supreme V3) the OLED lives at 0x3D because 0x3C is occupied by a
+  // magnetometer (QMC6310N). 0x3D is only ever used by the OLED, so prefer it
+  // when present, otherwise fall back to the standard 0x3C (DISPLAY_ADDRESS).
+  uint8_t addr = 0;
+  if (i2c_probe(Wire, 0x3D)) {
+    addr = 0x3D;
+  } else if (i2c_probe(Wire, DISPLAY_ADDRESS)) {
+    addr = DISPLAY_ADDRESS;
+  }
+  return addr && display.begin(addr, true);
 }
 
 void SH1106Display::turnOn()

From 3af5ffe11923eff8da35a14baf505f207fc33d2d Mon Sep 17 00:00:00 2001
From: Naomi Smith <naomi@spinda.net>
Date: Fri, 3 Jul 2026 11:55:06 -0700
Subject: [PATCH 03/29] Fix GPS and LEDs on ThinkNode M3

GPS support was implemented incorrectly for the ThinkNode M3. The reset
pin was being driven when it should be left floating for this unit. The
enable pin also wasn't being picked up by `MicroNMEALocationProvider`
because of a mismatch in constant naming conventions. I did a general
cleanup of the GPS and ThinkNode M3 bring-up code so that constant names
line up and "*_ACTIVE" constants are used consistently vs hardcoding
`HIGH`/`LOW`. After making these changes, serial data immediately starts
streaming in from the NMEA on boot and GPS detection just works.

LED handling was also not quite right for the ThinkNode M3. The LoRa TX
LED was being driven high to turn it on when it should actually be
driven low. I changed the code to use the `LED_STATE_ON` constant and
also added a little code to the shutdown path to properly make sure that
all LEDs are turned off.

Tested and confirmed working on real hardware.

Resolves both #1864 and #2879.
---
 .../sensors/MicroNMEALocationProvider.h       | 32 +++++++++++--------
 variants/thinknode_m3/ThinkNodeM3Board.h      | 12 +++----
 variants/thinknode_m3/platformio.ini          |  2 --
 variants/thinknode_m3/variant.cpp             |  8 +++--
 variants/thinknode_m3/variant.h               |  9 +++---
 5 files changed, 34 insertions(+), 29 deletions(-)

diff --git a/src/helpers/sensors/MicroNMEALocationProvider.h b/src/helpers/sensors/MicroNMEALocationProvider.h
index eec466d3a..9d697fed3 100644
--- a/src/helpers/sensors/MicroNMEALocationProvider.h
+++ b/src/helpers/sensors/MicroNMEALocationProvider.h
@@ -13,8 +13,12 @@
     #endif
 #endif
 
-#ifndef PIN_GPS_EN_ACTIVE
-    #define PIN_GPS_EN_ACTIVE HIGH
+#ifndef GPS_EN_ACTIVE
+    #ifdef PIN_GPS_EN_ACTIVE
+        #define GPS_EN_ACTIVE PIN_GPS_EN_ACTIVE
+    #else
+        #define GPS_EN_ACTIVE HIGH
+    #endif
 #endif
 
 #ifndef GPS_RESET
@@ -25,11 +29,11 @@
     #endif
 #endif
 
-#ifndef GPS_RESET_FORCE
+#ifndef GPS_RESET_ACTIVE
     #ifdef PIN_GPS_RESET_ACTIVE
-        #define GPS_RESET_FORCE PIN_GPS_RESET_ACTIVE
+        #define GPS_RESET_ACTIVE PIN_GPS_RESET_ACTIVE
     #else
-        #define GPS_RESET_FORCE LOW
+        #define GPS_RESET_ACTIVE LOW
     #endif
 #endif
 
@@ -52,11 +56,11 @@ public :
     _gps_serial(&ser), nmea(_nmeaBuffer, sizeof(_nmeaBuffer)), _pin_reset(pin_reset), _pin_en(pin_en), _clock(clock), _peripher_power(peripher_power) {
         if (_pin_reset != -1) {
             pinMode(_pin_reset, OUTPUT);
-            digitalWrite(_pin_reset, GPS_RESET_FORCE);
+            digitalWrite(_pin_reset, GPS_RESET_ACTIVE);
         }
         if (_pin_en != -1) {
             pinMode(_pin_en, OUTPUT);
-            digitalWrite(_pin_en, LOW);
+            digitalWrite(_pin_en, !GPS_EN_ACTIVE);
         }
     }
 
@@ -76,27 +80,27 @@ public :
     void begin() override {
         claim();
         if (_pin_en != -1) {
-            digitalWrite(_pin_en, PIN_GPS_EN_ACTIVE);
+            digitalWrite(_pin_en, GPS_EN_ACTIVE);
         }
         if (_pin_reset != -1) {
-            digitalWrite(_pin_reset, !GPS_RESET_FORCE);
+            digitalWrite(_pin_reset, !GPS_RESET_ACTIVE);
         }
     }
 
     void reset() override {
         if (_pin_reset != -1) {
-            digitalWrite(_pin_reset, GPS_RESET_FORCE);
+            digitalWrite(_pin_reset, GPS_RESET_ACTIVE);
             delay(10);
-            digitalWrite(_pin_reset, !GPS_RESET_FORCE);
+            digitalWrite(_pin_reset, !GPS_RESET_ACTIVE);
         }
     }
 
     void stop() override {
         if (_pin_en != -1) {
-            digitalWrite(_pin_en, !PIN_GPS_EN_ACTIVE);
+            digitalWrite(_pin_en, !GPS_EN_ACTIVE);
         }
         if (_pin_reset != -1) {
-            digitalWrite(_pin_reset, GPS_RESET_FORCE);
+            digitalWrite(_pin_reset, GPS_RESET_ACTIVE);
         }
         release();
     }
@@ -105,7 +109,7 @@ public :
         // directly read the enable pin if present as gps can be
         // activated/deactivated outside of here ...
         if (_pin_en != -1) {
-            return digitalRead(_pin_en) == PIN_GPS_EN_ACTIVE;
+            return digitalRead(_pin_en) == GPS_EN_ACTIVE;
         } else {
             return true; // no enable so must be active
         }
diff --git a/variants/thinknode_m3/ThinkNodeM3Board.h b/variants/thinknode_m3/ThinkNodeM3Board.h
index 1435d31d4..63b141161 100644
--- a/variants/thinknode_m3/ThinkNodeM3Board.h
+++ b/variants/thinknode_m3/ThinkNodeM3Board.h
@@ -18,12 +18,12 @@ public:
   void begin();
   uint16_t getBattMilliVolts() override;
 
-#if defined(P_LORA_TX_LED)
+#ifdef P_LORA_TX_LED
   void onBeforeTransmit() override {
-    digitalWrite(P_LORA_TX_LED, HIGH);   // turn TX LED on
+    digitalWrite(P_LORA_TX_LED, LED_STATE_ON);  // turn TX LED on
   }
   void onAfterTransmit() override {
-    digitalWrite(P_LORA_TX_LED, LOW);   // turn TX LED off
+    digitalWrite(P_LORA_TX_LED, !LED_STATE_ON); // turn TX LED off
   }
 #endif
 
@@ -44,9 +44,9 @@ public:
 
   void powerOff() override {
     // turn off all leds, sd_power_system_off will not do this for us
-    #ifdef P_LORA_TX_LED
-    digitalWrite(P_LORA_TX_LED, LOW);
-    #endif
+    digitalWrite(PIN_LED_BLUE, !LED_STATE_ON);
+    digitalWrite(PIN_LED_GREEN, !LED_STATE_ON);
+    digitalWrite(PIN_LED_RED, !LED_STATE_ON);
 
     // power off board
     sd_power_system_off();
diff --git a/variants/thinknode_m3/platformio.ini b/variants/thinknode_m3/platformio.ini
index 0a3d4eda9..0004f4c73 100644
--- a/variants/thinknode_m3/platformio.ini
+++ b/variants/thinknode_m3/platformio.ini
@@ -24,7 +24,6 @@ build_flags = ${nrf52_base.build_flags}
   -D P_LORA_MOSI=46
   -D P_LORA_RESET=42
   -D P_LORA_TX_LED=PIN_LED_BLUE
-  -D P_LORA_TX_LED_ON=LOW
   -D LR11X0_DIO_AS_RF_SWITCH=true
   -D LR11X0_DIO3_TCXO_VOLTAGE=3.3
   -D MESH_DEBUG=1
@@ -105,7 +104,6 @@ build_flags = ${ThinkNode_M3.build_flags}
   -D BLE_TX_POWER=0
 ;  -D BLE_DEBUG_LOGGING=1
 ;  -D MESH_PACKET_LOGGING=1
-  -D GPS_NMEA_DEBUG
   -D OFFLINE_QUEUE_SIZE=256
   -D DISPLAY_CLASS=NullDisplayDriver
   -D PIN_BUZZER=23
diff --git a/variants/thinknode_m3/variant.cpp b/variants/thinknode_m3/variant.cpp
index dad0f3f55..b47b83543 100644
--- a/variants/thinknode_m3/variant.cpp
+++ b/variants/thinknode_m3/variant.cpp
@@ -80,16 +80,18 @@ void initVariant()
   digitalWrite(LED_POWER, HIGH);
 
   pinMode(PIN_LED_BLUE, OUTPUT);
+  digitalWrite(PIN_LED_BLUE, !LED_STATE_ON);
   pinMode(PIN_LED_GREEN, OUTPUT);
+  digitalWrite(PIN_LED_GREEN, !LED_STATE_ON);
   pinMode(PIN_LED_RED, OUTPUT);
+  digitalWrite(PIN_LED_RED, !LED_STATE_ON);
 
   pinMode(BUTTON_PIN, INPUT_PULLUP);
 
   pinMode(PIN_GPS_POWER, OUTPUT);
   pinMode(PIN_GPS_EN, OUTPUT);
-  pinMode(PIN_GPS_RESET, OUTPUT);
 
   // Power on gps but in standby
-  digitalWrite(PIN_GPS_EN, LOW);
-  digitalWrite(PIN_GPS_POWER, HIGH);
+  digitalWrite(PIN_GPS_EN, !GPS_EN_ACTIVE);
+  digitalWrite(PIN_GPS_POWER, GPS_POWER_ACTIVE);
 }
diff --git a/variants/thinknode_m3/variant.h b/variants/thinknode_m3/variant.h
index 02ed78a84..78dfab85d 100644
--- a/variants/thinknode_m3/variant.h
+++ b/variants/thinknode_m3/variant.h
@@ -32,7 +32,7 @@
 #define EXT_CHRG_DETECT         (32)            // P1.3
 #define EXT_PWR_DETECT          (31)             // P0.5
 
-#define PIN_VBAT_READ           (5) 
+#define PIN_VBAT_READ           (5)
 #define AREF_VOLTAGE            (2.4f)
 #define ADC_MULTIPLIER          (2.0)           //(1.75f)
 // 2.0 gives more coherent value, 4.2V when charged, needs tweaking
@@ -92,18 +92,19 @@
 // GPS
 
 #define HAS_GPS                     1
-#define PIN_GPS_RX                  (22)    
+#define PIN_GPS_RX                  (22)
 #define PIN_GPS_TX                  (20)
 
 #define PIN_GPS_POWER               (14)
 #define PIN_GPS_EN                  (21)            // STANDBY
 #define PIN_GPS_RESET               (25)            // REINIT
-#define GPS_RESET_ACTIVE            LOW
+#define GPS_POWER_ACTIVE            HIGH
 #define GPS_EN_ACTIVE               HIGH
+#define GPS_RESET                   (-1)
 #define GPS_BAUDRATE                9600
 
 ////////////////////////////////////////////////////////////////////////////////
 // Buzzer
 
 #define BUZZER_EN               (37)            // P1.5
-#define BUZZER_PIN              (25)            // P0.25
\ No newline at end of file
+#define BUZZER_PIN              (25)            // P0.25

From 57563ab8f92be3a6396b3eead4898b36f186a44b Mon Sep 17 00:00:00 2001
From: liamcottle <liam@liamcottle.com>
Date: Mon, 6 Jul 2026 02:04:56 +1200
Subject: [PATCH 04/29] update qr code docs

---
 docs/qr_codes.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/qr_codes.md b/docs/qr_codes.md
index 364efa8ac..3516a76a4 100644
--- a/docs/qr_codes.md
+++ b/docs/qr_codes.md
@@ -12,8 +12,10 @@ meshcore://channel/add?name=Public&secret=8b3387e9c5cdea6ac9e5edbaa115cd72
 
 **Parameters**:
 
-- `name`: Channel name (URL-encoded if needed)
+- `name`: Channel name (URL-encoded)
 - `secret`: 16-byte secret represented as 32 hex characters
+- `region_scope`: Region Scope (optional, URL-encoded if provided)
+    - Supported by MeshCore App v1.47.0+
 
 ## Add Contact
 

From 54234b58371d2ecbf3031d807156277e1afff3a1 Mon Sep 17 00:00:00 2001
From: liamcottle <liam@liamcottle.com>
Date: Mon, 6 Jul 2026 22:18:49 +1200
Subject: [PATCH 05/29] implement matrix builds for faster firmware releases

---
 .../setup-build-environment/action.yml        | 13 ++-
 .../workflows/build-companion-firmwares.yml   | 35 ++------
 .../workflows/build-repeater-firmwares.yml    | 35 ++------
 .../workflows/build-room-server-firmwares.yml | 35 ++------
 .github/workflows/firmware-builder.yml        | 90 +++++++++++++++++++
 build.sh                                      | 10 +++
 6 files changed, 126 insertions(+), 92 deletions(-)
 create mode 100644 .github/workflows/firmware-builder.yml

diff --git a/.github/actions/setup-build-environment/action.yml b/.github/actions/setup-build-environment/action.yml
index 02aaf4249..cba2d2e56 100644
--- a/.github/actions/setup-build-environment/action.yml
+++ b/.github/actions/setup-build-environment/action.yml
@@ -25,5 +25,14 @@ runs:
     - name: Extract Version from Git Tag
       shell: bash
       run: |
-        GIT_TAG_NAME="${GITHUB_REF#refs/tags/}"
-        echo "GIT_TAG_VERSION=${GIT_TAG_NAME##*-}" >> $GITHUB_ENV
+        if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+          # triggered by a tag push (e.g: refs/tags/companion-v1.2.3)
+          GIT_TAG_NAME="${GITHUB_REF#refs/tags/}"
+          VERSION_STRING="${GIT_TAG_NAME##*-}"
+        else
+          # triggered by a workflow dispatch (e.g: refs/heads/main)
+          # strip "refs/heads/" prefix and replace any remaining "/" with "-" to protect file paths
+          BRANCH_NAME="${GITHUB_REF#refs/heads/}"
+          VERSION_STRING=$(echo "$BRANCH_NAME" | tr '/' '-')
+        fi
+        echo "GIT_TAG_VERSION=${VERSION_STRING}" >> $GITHUB_ENV
diff --git a/.github/workflows/build-companion-firmwares.yml b/.github/workflows/build-companion-firmwares.yml
index 771fa6d5b..8fd796f74 100644
--- a/.github/workflows/build-companion-firmwares.yml
+++ b/.github/workflows/build-companion-firmwares.yml
@@ -10,33 +10,8 @@ on:
       - 'companion-*'
 
 jobs:
-
-  build:
-    runs-on: ubuntu-latest
-    steps:
-
-      - name: Clone Repo
-        uses: actions/checkout@v6
-
-      - name: Setup Build Environment
-        uses: ./.github/actions/setup-build-environment
-
-      - name: Build Firmwares
-        env:
-          FIRMWARE_VERSION: ${{ env.GIT_TAG_VERSION }}
-        run: /usr/bin/env bash build.sh build-companion-firmwares
-
-      - name: Upload Workflow Artifacts
-        uses: actions/upload-artifact@v7
-        with:
-          name: companion-firmwares
-          path: out
-
-      - name: Create Release
-        uses: softprops/action-gh-release@v3
-        if: startsWith(github.ref, 'refs/tags/')
-        with:
-          name: Companion Firmware ${{ env.GIT_TAG_VERSION }}
-          body: ""
-          draft: true
-          files: out/*
\ No newline at end of file
+  build-companion-firmwares:
+    uses: ./.github/workflows/firmware-builder.yml
+    with:
+      firmware_type: 'companion'
+      release_title_prefix: 'Companion Firmware'
diff --git a/.github/workflows/build-repeater-firmwares.yml b/.github/workflows/build-repeater-firmwares.yml
index 3185d4b21..46b9076cc 100644
--- a/.github/workflows/build-repeater-firmwares.yml
+++ b/.github/workflows/build-repeater-firmwares.yml
@@ -10,33 +10,8 @@ on:
       - 'repeater-*'
 
 jobs:
-
-  build:
-    runs-on: ubuntu-latest
-    steps:
-
-      - name: Clone Repo
-        uses: actions/checkout@v6
-
-      - name: Setup Build Environment
-        uses: ./.github/actions/setup-build-environment
-
-      - name: Build Firmwares
-        env:
-          FIRMWARE_VERSION: ${{ env.GIT_TAG_VERSION }}
-        run: /usr/bin/env bash build.sh build-repeater-firmwares
-
-      - name: Upload Workflow Artifacts
-        uses: actions/upload-artifact@v7
-        with:
-          name: repeater-firmwares
-          path: out
-
-      - name: Create Release
-        uses: softprops/action-gh-release@v3
-        if: startsWith(github.ref, 'refs/tags/')
-        with:
-          name: Repeater Firmware ${{ env.GIT_TAG_VERSION }}
-          body: ""
-          draft: true
-          files: out/*
\ No newline at end of file
+  build-repeater-firmwares:
+    uses: ./.github/workflows/firmware-builder.yml
+    with:
+      firmware_type: 'repeater'
+      release_title_prefix: 'Repeater Firmware'
diff --git a/.github/workflows/build-room-server-firmwares.yml b/.github/workflows/build-room-server-firmwares.yml
index 127095a8d..c8bd19f7f 100644
--- a/.github/workflows/build-room-server-firmwares.yml
+++ b/.github/workflows/build-room-server-firmwares.yml
@@ -10,33 +10,8 @@ on:
       - 'room-server-*'
 
 jobs:
-
-  build:
-    runs-on: ubuntu-latest
-    steps:
-
-      - name: Clone Repo
-        uses: actions/checkout@v6
-
-      - name: Setup Build Environment
-        uses: ./.github/actions/setup-build-environment
-
-      - name: Build Firmwares
-        env:
-          FIRMWARE_VERSION: ${{ env.GIT_TAG_VERSION }}
-        run: /usr/bin/env bash build.sh build-room-server-firmwares
-
-      - name: Upload Workflow Artifacts
-        uses: actions/upload-artifact@v7
-        with:
-          name: room-server-firmwares
-          path: out
-
-      - name: Create Release
-        uses: softprops/action-gh-release@v3
-        if: startsWith(github.ref, 'refs/tags/')
-        with:
-          name: Room Server Firmware ${{ env.GIT_TAG_VERSION }}
-          body: ""
-          draft: true
-          files: out/*
\ No newline at end of file
+  build-room-server-firmwares:
+    uses: ./.github/workflows/firmware-builder.yml
+    with:
+      firmware_type: 'room-server'
+      release_title_prefix: 'Room Server Firmware'
diff --git a/.github/workflows/firmware-builder.yml b/.github/workflows/firmware-builder.yml
new file mode 100644
index 000000000..adc9e4248
--- /dev/null
+++ b/.github/workflows/firmware-builder.yml
@@ -0,0 +1,90 @@
+name: Firmware Builder
+
+on:
+  workflow_call:
+    inputs:
+      firmware_type:
+        required: true
+        type: string
+      release_title_prefix:
+        required: true
+        type: string
+
+jobs:
+
+  generate-build-matrix:
+    runs-on: ubuntu-latest
+    outputs:
+      targets: ${{ steps.get-build-targets.outputs.targets }}
+    steps:
+
+      - name: Clone Repo
+        uses: actions/checkout@v6
+
+      - name: Setup Build Environment
+        uses: ./.github/actions/setup-build-environment
+
+      - name: Get Build Targets
+        id: get-build-targets
+        run: |
+          # get list of firmwares to build
+          TARGET_LIST=$(/usr/bin/env bash build.sh get-${{ inputs.firmware_type }}-firmwares-to-build)
+          
+          # convert targets separated by new line into a json array string
+          JSON_ARRAY=$(echo "$TARGET_LIST" | jq -R -s -c 'split("\n") | map(select(length > 0))')
+          
+          # use json array as targets result
+          echo "targets=$JSON_ARRAY" >> $GITHUB_OUTPUT
+
+  build:
+    needs: generate-build-matrix
+    runs-on: ubuntu-latest
+    continue-on-error: true # don't fail entire build if one board fails to build
+    strategy:
+      matrix:
+        target: ${{ fromJson(needs.generate-build-matrix.outputs.targets) }}
+      fail-fast: false # don't cancel other builds if one board fails to build
+    steps:
+
+      - name: Clone Repo
+        uses: actions/checkout@v6
+
+      - name: Setup Build Environment
+        uses: ./.github/actions/setup-build-environment
+
+      - name: Build Firmware
+        env:
+          FIRMWARE_VERSION: ${{ env.GIT_TAG_VERSION }}
+        run: /usr/bin/env bash build.sh build-firmware ${{ matrix.target }}
+
+      - name: Upload Workflow Artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: "${{ matrix.target }}"
+          path: out
+
+  create-release:
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/') # only create release for tagged builds
+    steps:
+
+      - name: Clone Repo
+        uses: actions/checkout@v6
+
+      - name: Setup Build Environment
+        uses: ./.github/actions/setup-build-environment
+
+      - name: Download All Artifacts
+        uses: actions/download-artifact@v8
+        with:
+          merge-multiple: true
+          path: out
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v3
+        with:
+          name: "${{ inputs.release_title_prefix }} ${{ env.GIT_TAG_VERSION }}"
+          body: ""
+          draft: true
+          files: out/*
diff --git a/build.sh b/build.sh
index 313c4c47a..41719a44a 100755
--- a/build.sh
+++ b/build.sh
@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
 
+# exit when any command fails
+set -e
+
 global_usage() {
   cat - <<EOF
 Usage:
@@ -275,4 +278,11 @@ elif [[ $1 == "build-repeater-firmwares" ]]; then
   build_repeater_firmwares
 elif [[ $1 == "build-room-server-firmwares" ]]; then
   build_room_server_firmwares
+elif [[ $1 == "get-companion-firmwares-to-build" ]]; then
+  get_pio_envs_ending_with_string "_companion_radio_usb"
+  get_pio_envs_ending_with_string "_companion_radio_ble"
+elif [[ $1 == "get-repeater-firmwares-to-build" ]]; then
+  get_pio_envs_ending_with_string "_repeater"
+elif [[ $1 == "get-room-server-firmwares-to-build" ]]; then
+  get_pio_envs_ending_with_string "_room_server"
 fi

From 754fcb1fae19c2f4b1af2dfe248a809c68438401 Mon Sep 17 00:00:00 2001
From: Will Dillon <william@housedillon.com>
Date: Thu, 9 Jul 2026 11:43:20 -0700
Subject: [PATCH 06/29] Update number_allocations.md

Adds a small allocation for groupdata packets for the Meshcore firmware for the StreamSensor product.  It was previously a LoRaWAN platform, and we've moved to Meshcore.
---
 docs/number_allocations.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/number_allocations.md b/docs/number_allocations.md
index 857525d46..84b9cba04 100644
--- a/docs/number_allocations.md
+++ b/docs/number_allocations.md
@@ -17,6 +17,7 @@ Once you have a working app/project, you need to be able to demonstrate it exist
 | 0000 - 00FF     | -reserved for internal use- |                                                                   |
 | 0100            | MeshCore Open               | zsylvester@monitormx.com — https://github.com/zjs81/meshcore-open |
 | 0110 - 011F     | Ripple                      | ripple_biz@protonmail.com — https://buymeacoffee.com/ripplebiz    |
+| 0120 - 012F     | StreamSensor                | william@housedillon.com - https://housedillon.com/blog/lora-e5-with-seeed-fusion |
 | FF00 - FFFF     | -reserved for testing/dev-  |                                                                   |
 
 (add rows, inside the range 0100 - FEFF for custom apps)

From d9cd3ea03a41f74a1869210b0c4330d8f92668f2 Mon Sep 17 00:00:00 2001
From: ripplebiz <ripple_biz@protonmail.com>
Date: Mon, 13 Jul 2026 19:30:11 +1000
Subject: [PATCH 07/29] Revert "Add StreamSensor allocation for GroupData"

---
 docs/number_allocations.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/number_allocations.md b/docs/number_allocations.md
index 84b9cba04..857525d46 100644
--- a/docs/number_allocations.md
+++ b/docs/number_allocations.md
@@ -17,7 +17,6 @@ Once you have a working app/project, you need to be able to demonstrate it exist
 | 0000 - 00FF     | -reserved for internal use- |                                                                   |
 | 0100            | MeshCore Open               | zsylvester@monitormx.com — https://github.com/zjs81/meshcore-open |
 | 0110 - 011F     | Ripple                      | ripple_biz@protonmail.com — https://buymeacoffee.com/ripplebiz    |
-| 0120 - 012F     | StreamSensor                | william@housedillon.com - https://housedillon.com/blog/lora-e5-with-seeed-fusion |
 | FF00 - FFFF     | -reserved for testing/dev-  |                                                                   |
 
 (add rows, inside the range 0100 - FEFF for custom apps)

From 975a673efd4fcabc21becb8f92f434b432f43265 Mon Sep 17 00:00:00 2001
From: taco <taco@sly.nu>
Date: Fri, 17 Jul 2026 21:15:09 +1000
Subject: [PATCH 08/29] add calcMaxPacketMillis

---
 src/helpers/radiolib/RadioLibWrappers.cpp | 18 ++++++++++++++++++
 src/helpers/radiolib/RadioLibWrappers.h   |  6 ++++++
 2 files changed, 24 insertions(+)

diff --git a/src/helpers/radiolib/RadioLibWrappers.cpp b/src/helpers/radiolib/RadioLibWrappers.cpp
index 5e72336c0..7146e47b6 100644
--- a/src/helpers/radiolib/RadioLibWrappers.cpp
+++ b/src/helpers/radiolib/RadioLibWrappers.cpp
@@ -228,3 +228,21 @@ float RadioLibWrapper::packetScoreInt(float snr, int sf, int packet_len) {
 
   return max(0.0, min(1.0, success_rate_based_on_snr * collision_penalty));
 }
+
+PacketMillis RadioLibWrapper::calcMaxPacketMillis(uint8_t sf, float bw, uint8_t cr, uint8_t preambleSymbols) {
+  // based on RadioLib's calculateTimeOnAir()
+  uint32_t tsym_us = ((uint32_t)10000 << sf) / (bw * 10);
+  uint32_t sfCoeff1_x4 = (sf == 5 || sf == 6) ? 25 : 17; // 6.25 : 4.25, semtech magic numbers to account for sync word + sfd
+
+  // preamble + syncword + sfd + header
+  uint32_t preamble_us = (((preambleSymbols + 8) * 4 + sfCoeff1_x4) * tsym_us) / 4;
+  
+  // airtime for max packet at current radio settings
+  uint32_t total_us   = _radio->getTimeOnAir(MAX_TRANS_UNIT);
+  // airtime for payload only (no preamble, header or SOF)
+  uint32_t payload_us = total_us > preamble_us ? total_us - preamble_us : 4000 - preamble_us; // fallback to 4 secs at worst case
+  // rescale payload_us for max possible CR
+  if (cr >= 5 && cr < 8) { payload_us = (payload_us * 8) / cr; }
+
+  return PacketMillis {(preamble_us + 999) / 1000, (payload_us + 999) / 1000};
+}
\ No newline at end of file
diff --git a/src/helpers/radiolib/RadioLibWrappers.h b/src/helpers/radiolib/RadioLibWrappers.h
index 3091832f1..e7fef9104 100644
--- a/src/helpers/radiolib/RadioLibWrappers.h
+++ b/src/helpers/radiolib/RadioLibWrappers.h
@@ -3,6 +3,11 @@
 #include <Mesh.h>
 #include <RadioLib.h>
 
+struct PacketMillis {
+  uint32_t preambleMillis;  // preamble-detect -> header-valid deadline
+  uint32_t payloadMillis;   // header-valid   -> rx-done deadline
+};
+
 class RadioLibWrapper : public mesh::Radio {
 protected:
   PhysicalLayer* _radio;
@@ -47,6 +52,7 @@ public:
   virtual uint8_t getSpreadingFactor() const { return LORA_SF; }
   static uint16_t preambleLengthForSF(uint8_t sf) { return sf <= 8 ? 32 : 16; }
   void updatePreamble(uint8_t sf) { _preamble_sf = sf; _radio->setPreambleLength(preambleLengthForSF(sf)); }
+  PacketMillis calcMaxPacketMillis(uint8_t sf, float bw, uint8_t cr, uint8_t preambleSymbols);
   virtual int16_t performChannelScan();
 
   int getNoiseFloor() const override { return _noise_floor; }

From 79ef74ea8def0195ddbe340441fec7ce5c943051 Mon Sep 17 00:00:00 2001
From: taco <taco@sly.nu>
Date: Fri, 17 Jul 2026 21:33:57 +1000
Subject: [PATCH 09/29] add IRQ timeout logic for SX1262

---
 src/helpers/radiolib/CustomSX1262.h        | 51 +++++++++++++++++++---
 src/helpers/radiolib/CustomSX1262Wrapper.h |  1 +
 2 files changed, 46 insertions(+), 6 deletions(-)

diff --git a/src/helpers/radiolib/CustomSX1262.h b/src/helpers/radiolib/CustomSX1262.h
index ca62fc26a..284b79c02 100644
--- a/src/helpers/radiolib/CustomSX1262.h
+++ b/src/helpers/radiolib/CustomSX1262.h
@@ -3,10 +3,12 @@
 #include <RadioLib.h>
 #include "MeshCore.h"
 
-#define SX126X_IRQ_HEADER_VALID                0b0000010000  //  4     4     valid LoRa header received
-#define SX126X_IRQ_PREAMBLE_DETECTED           0x04
-
 class CustomSX1262 : public SX1262 {
+  uint32_t _preambleMillis = 66;
+  uint32_t _maxPayloadMillis = 3934;
+  uint32_t _activityAt = 0;
+  bool _headerSeen = false;
+
   public:
     CustomSX1262(Module *mod) : SX1262(mod) { }
 
@@ -99,9 +101,46 @@ class CustomSX1262 : public SX1262 {
     }
 
     bool isReceiving() {
-      uint16_t irq = getIrqFlags();
-      bool detected = (irq & SX126X_IRQ_HEADER_VALID) || (irq & SX126X_IRQ_PREAMBLE_DETECTED);
-      return detected;
+      uint32_t irq = getIrqFlags();
+      bool preamble = irq & RADIOLIB_SX126X_IRQ_PREAMBLE_DETECTED; // bit 2
+      bool header   = irq & RADIOLIB_SX126X_IRQ_HEADER_VALID;      // bit 4
+      bool hdrErr   = irq & RADIOLIB_SX126X_IRQ_HEADER_ERR;        // bit 5
+      uint32_t now  = millis();
+      if (hdrErr) {
+        clearIrqFlags(RADIOLIB_SX126X_IRQ_PREAMBLE_DETECTED | RADIOLIB_SX126X_IRQ_HEADER_VALID | RADIOLIB_SX126X_IRQ_HEADER_ERR | RADIOLIB_SX126X_IRQ_SYNC_WORD_VALID);
+        _activityAt = 0;
+        _headerSeen = false;
+        return false;
+      }
+      if (header) {
+        if (!_headerSeen) { _headerSeen = true; _activityAt = now; };
+        if (now - _activityAt > _maxPayloadMillis) {
+          MESH_DEBUG_PRINTLN("Clearing header IRQ after %ums", _maxPayloadMillis);
+          clearIrqFlags(RADIOLIB_SX126X_IRQ_PREAMBLE_DETECTED | RADIOLIB_SX126X_IRQ_HEADER_VALID | RADIOLIB_SX126X_IRQ_HEADER_ERR | RADIOLIB_SX126X_IRQ_SYNC_WORD_VALID);
+          _activityAt = 0; _headerSeen = false;
+          return false;
+        }
+        return true;
+      }
+      if (preamble) {
+        if (_activityAt == 0) _activityAt = now;
+        if (now - _activityAt > _preambleMillis) {
+          clearIrqStatus(RADIOLIB_IRQ_PREAMBLE_DETECTED);
+          _activityAt = 0;
+          MESH_DEBUG_PRINTLN("Clearing preamble IRQ after %ums", _preambleMillis);
+
+          return false;
+        }
+        return true;
+      }
+      _activityAt = 0; _headerSeen = false;
+      return false;
+    }
+
+    PacketMillis setMaxPacketMillis(PacketMillis maxPacketMillis) {
+      MESH_DEBUG_PRINTLN("Setting _preambleMillis=%u, _maxPacketMillis=%u", maxPacketMillis.preambleMillis, maxPacketMillis.payloadMillis);
+      _preambleMillis = maxPacketMillis.preambleMillis;
+      _maxPayloadMillis = maxPacketMillis.payloadMillis;
     }
 
     bool getRxBoostedGainMode() {
diff --git a/src/helpers/radiolib/CustomSX1262Wrapper.h b/src/helpers/radiolib/CustomSX1262Wrapper.h
index 1d103f579..45af4cb4b 100644
--- a/src/helpers/radiolib/CustomSX1262Wrapper.h
+++ b/src/helpers/radiolib/CustomSX1262Wrapper.h
@@ -18,6 +18,7 @@ public:
     ((CustomSX1262 *)_radio)->setBandwidth(bw);
     ((CustomSX1262 *)_radio)->setCodingRate(cr);
     updatePreamble(sf);
+    ((CustomSX1262 *)_radio)->setMaxPacketMillis(calcMaxPacketMillis(sf, bw, cr, preambleLengthForSF(sf)));
   }
 
   bool isReceivingPacket() override { 

From 0bd871cde6e3256c7de7518c703bb3827d3f9fa2 Mon Sep 17 00:00:00 2001
From: taco <taco@sly.nu>
Date: Fri, 17 Jul 2026 21:45:31 +1000
Subject: [PATCH 10/29] add IRQ timeout logic for LR11X0

---
 src/helpers/radiolib/CustomLR1110.h        | 47 ++++++++++++++++++++--
 src/helpers/radiolib/CustomLR1110Wrapper.h |  2 +
 2 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/src/helpers/radiolib/CustomLR1110.h b/src/helpers/radiolib/CustomLR1110.h
index 4061c6b1a..db0f2af3d 100644
--- a/src/helpers/radiolib/CustomLR1110.h
+++ b/src/helpers/radiolib/CustomLR1110.h
@@ -4,6 +4,10 @@
 #include "MeshCore.h"
 
 class CustomLR1110 : public LR1110 {
+  uint32_t _preambleMillis = 66;
+  uint32_t _maxPayloadMillis = 3934;
+  uint32_t _activityAt = 0;
+  bool _headerSeen = false;
   bool _rx_boosted = false;
 
   public:
@@ -32,9 +36,46 @@ class CustomLR1110 : public LR1110 {
     bool getRxBoostedGainMode() const { return _rx_boosted; }
 
     bool isReceiving() {
-      uint16_t irq = getIrqStatus();
-      bool detected = ((irq & RADIOLIB_LR11X0_IRQ_SYNC_WORD_HEADER_VALID) || (irq & RADIOLIB_LR11X0_IRQ_PREAMBLE_DETECTED));
-      return detected;
+      uint32_t irq = getIrqStatus();
+      bool preamble = irq & RADIOLIB_LR11X0_IRQ_PREAMBLE_DETECTED;      // bit 4
+      bool header   = irq & RADIOLIB_LR11X0_IRQ_SYNC_WORD_HEADER_VALID; // bit 5
+      bool hdrErr   = irq & RADIOLIB_LR11X0_IRQ_HEADER_ERR;             // bit 6
+      uint32_t now  = millis();
+      if (hdrErr) {
+        clearIrqState(RADIOLIB_LR11X0_IRQ_PREAMBLE_DETECTED | RADIOLIB_LR11X0_IRQ_SYNC_WORD_HEADER_VALID | RADIOLIB_LR11X0_IRQ_HEADER_ERR);
+        _activityAt = 0;
+        _headerSeen = false;
+        return false;
+      }
+      if (header) {
+        if (!_headerSeen) { _headerSeen = true; _activityAt = now; };
+        if (now - _activityAt > _maxPayloadMillis) {
+          MESH_DEBUG_PRINTLN("Clearing header IRQ after %ums", _maxPayloadMillis);
+          clearIrqState(RADIOLIB_LR11X0_IRQ_PREAMBLE_DETECTED | RADIOLIB_LR11X0_IRQ_SYNC_WORD_HEADER_VALID | RADIOLIB_LR11X0_IRQ_HEADER_ERR);
+          _activityAt = 0; _headerSeen = false;
+          return false;
+        }
+        return true;
+      }
+      if (preamble) {
+        if (_activityAt == 0) _activityAt = now;
+        if (now - _activityAt > _preambleMillis) {
+          clearIrqState(RADIOLIB_LR11X0_IRQ_PREAMBLE_DETECTED);
+          _activityAt = 0;
+          MESH_DEBUG_PRINTLN("Clearing preamble IRQ after %ums", _preambleMillis);
+
+          return false;
+        }
+        return true;
+      }
+      _activityAt = 0; _headerSeen = false;
+      return false;
+    }
+
+    PacketMillis setMaxPacketMillis(PacketMillis maxPacketMillis) {
+      MESH_DEBUG_PRINTLN("Setting _preambleMillis=%u, _maxPacketMillis=%u", maxPacketMillis.preambleMillis, maxPacketMillis.payloadMillis);
+      _preambleMillis = maxPacketMillis.preambleMillis;
+      _maxPayloadMillis = maxPacketMillis.payloadMillis;
     }
 
     uint8_t getSpreadingFactor() const { return spreadingFactor; }
diff --git a/src/helpers/radiolib/CustomLR1110Wrapper.h b/src/helpers/radiolib/CustomLR1110Wrapper.h
index c6b1acb47..981faf092 100644
--- a/src/helpers/radiolib/CustomLR1110Wrapper.h
+++ b/src/helpers/radiolib/CustomLR1110Wrapper.h
@@ -14,6 +14,8 @@ public:
     ((CustomLR1110 *)_radio)->setBandwidth(bw);
     ((CustomLR1110 *)_radio)->setCodingRate(cr);
     updatePreamble(sf);
+    ((CustomLR1110 *)_radio)->setMaxPacketMillis(calcMaxPacketMillis(sf, bw, cr, preambleLengthForSF(sf)));
+
   }
 
   void doResetAGC() override { lr11x0ResetAGC((LR11x0 *)_radio, ((CustomLR1110 *)_radio)->getFreqMHz()); }

From fb2c61f862fcd4c6e08cf0f882175ca260052b13 Mon Sep 17 00:00:00 2001
From: ViezeVingertjes <michael.overhorst@gmail.com>
Date: Mon, 22 Jun 2026 16:12:00 +0200
Subject: [PATCH 11/29] fix: prevent ESP32 KISS modem stalls under USB
 backpressure

Switch ESP32-S3 KISS modem environments to HWCDC and move outbound KISS writes to a non-blocking queued frame path so loop() and TX completion keep progressing when the host reads slowly. Add native backpressure regression tests and correct the native_kiss_modem test filter so this suite runs directly with pio test.
---
 docs/kiss_modem_protocol.md                   |  14 +-
 examples/kiss_modem/KissModem.cpp             | 199 ++++++++++--
 examples/kiss_modem/KissModem.h               |  36 ++-
 examples/kiss_modem/main.cpp                  |  10 +-
 platformio.ini                                |  15 +
 test/mocks/Arduino.h                          |  17 +
 test/mocks/CayenneLPP.h                       |  11 +
 test/mocks/Identity.h                         |  39 +++
 test/mocks/Mesh.h                             |  27 ++
 test/mocks/Stream.h                           |  21 +-
 test/mocks/Utils.h                            |  44 +++
 test/mocks/helpers/SensorManager.h            |  10 +
 test/test_kiss_modem/test_tx_backpressure.cpp | 294 ++++++++++++++++++
 variants/heltec_v4/platformio.ini             |   5 +
 variants/station_g2/platformio.ini            |   5 +
 15 files changed, 701 insertions(+), 46 deletions(-)
 create mode 100644 test/mocks/Arduino.h
 create mode 100644 test/mocks/CayenneLPP.h
 create mode 100644 test/mocks/Identity.h
 create mode 100644 test/mocks/Mesh.h
 create mode 100644 test/mocks/Utils.h
 create mode 100644 test/mocks/helpers/SensorManager.h
 create mode 100644 test/test_kiss_modem/test_tx_backpressure.cpp

diff --git a/docs/kiss_modem_protocol.md b/docs/kiss_modem_protocol.md
index 9a9962248..3f4dbf9c4 100644
--- a/docs/kiss_modem_protocol.md
+++ b/docs/kiss_modem_protocol.md
@@ -41,7 +41,7 @@ Maximum unescaped frame size: 512 bytes.
 
 | Command     | Value  | Data               | Description                                                 |
 |-------------|--------|--------------------|-------------------------------------------------------------|
-| Data        | `0x00` | Raw packet         | Queue packet for transmission                               |
+| Data        | `0x00` | Raw packet         | Queue packet for transmission (one pending at a time)       |
 | TXDELAY     | `0x01` | Delay (1 byte)     | Transmitter keyup delay in 10ms units (default: 50 = 500ms) |
 | Persistence | `0x02` | P (1 byte)         | CSMA persistence parameter 0-255 (default: 63)              |
 | SlotTime    | `0x03` | Interval (1 byte)  | CSMA slot interval in 10ms units (default: 10 = 100ms)      |
@@ -58,6 +58,12 @@ Maximum unescaped frame size: 512 bytes.
 
 Data frames carry raw packet data only, with no metadata prepended. The Data command payload is limited to 255 bytes to match the MeshCore maximum transmission unit (MAX_TRANS_UNIT); frames larger than 255 bytes are silently dropped. The KISS specification recommends at least 1024 bytes for general-purpose TNCs; this modem is intended for MeshCore packets only, whose protocol MTU is 255 bytes.
 
+Only one packet may be pending for radio transmission at a time. If the host sends a second Data frame before the first has completed, the modem responds with Error (0xF1) and TxBusy (0x07).
+
+### Host Output Backpressure
+
+Outbound frames are encoded into a 2-slot queue and flushed when serial output space is available; `loop()` never blocks on writes. Radio TX state advances independently of host read speed. TxDone is retained until it can be queued. If the outbound queue is full, the modem responds with Error (0xF1) and TxBusy (0x07). Hosts should read serial promptly to avoid delayed responses.
+
 ### CSMA Behavior
 
 The TNC implements p-persistent CSMA for half-duplex operation:
@@ -156,15 +162,15 @@ Response codes use the high-bit convention: `response = command | 0x80`. Generic
 | MacFailed     | `0x04` | MAC verification failed |
 | UnknownCmd    | `0x05` | Unknown sub-command     |
 | EncryptFailed | `0x06` | Encryption failed       |
-| TxBusy        | `0x07` | Transmit busy           |
+| TxBusy        | `0x07` | Radio TX busy, or host output queue full |
 
 ### Unsolicited Events
 
 The TNC sends these SetHardware frames without a preceding request:
 
-**TxDone (0xF8)**: Sent after a packet has been transmitted. Contains a single byte: 0x01 for success, 0x00 for failure.
+**TxDone (0xF8)**: Sent after radio transmission completes. Contains a single byte: 0x01 for success, 0x00 for failure. Delivery to the host may be delayed under serial backpressure but is not dropped.
 
-**RxMeta (0xF9)**: Sent immediately after each standard data frame (type 0x00) with metadata for the received packet. Contains SNR (1 byte, signed, value x4 for 0.25 dB precision) followed by RSSI (1 byte, signed, dBm). Enabled by default; can be toggled with SetSignalReport. Standard KISS clients ignore this frame.
+**RxMeta (0xF9)**: Sent after each standard data frame (type 0x00) with SNR (1 byte, signed, value x4) and RSSI (1 byte, signed, dBm). Queued with the data frame; omitted if the data frame cannot be queued. Enabled by default; toggle with SetSignalReport. Standard KISS clients ignore this frame.
 
 ## Data Formats
 
diff --git a/examples/kiss_modem/KissModem.cpp b/examples/kiss_modem/KissModem.cpp
index eeab1501d..7dcfc8d7d 100644
--- a/examples/kiss_modem/KissModem.cpp
+++ b/examples/kiss_modem/KissModem.cpp
@@ -22,6 +22,7 @@ KissModem::KissModem(Stream& serial, mesh::LocalIdentity& identity, mesh::RNG& r
   _getStatsCallback = nullptr;
   _config = {0, 0, 0, 0, 0};
   _signal_report_enabled = true;
+  resetOutputQueue();
 }
 
 void KissModem::begin() {
@@ -30,37 +31,168 @@ void KissModem::begin() {
   _rx_active = false;
   _has_pending_tx = false;
   _tx_state = TX_IDLE;
+  resetOutputQueue();
 }
 
-void KissModem::writeByte(uint8_t b) {
-  if (b == KISS_FEND) {
-    _serial.write(KISS_FESC);
-    _serial.write(KISS_TFEND);
-  } else if (b == KISS_FESC) {
-    _serial.write(KISS_FESC);
-    _serial.write(KISS_TFESC);
-  } else {
-    _serial.write(b);
+void KissModem::resetOutputQueue() {
+  _tx_frame_head = 0;
+  _tx_frame_tail = 0;
+  _tx_frame_count = 0;
+  _tx_busy_error_pending = false;
+  _tx_done_pending = false;
+  _tx_done_result = 0;
+}
+
+void KissModem::popTxFrame() {
+  _tx_frame_head = (uint8_t)((_tx_frame_head + 1) % KISS_TX_FRAME_QUEUE_DEPTH);
+  _tx_frame_count--;
+}
+
+uint16_t KissModem::appendEscapedByte(uint8_t* dest, uint16_t idx, uint16_t max_len, uint8_t b) {
+  if (b == KISS_FEND || b == KISS_FESC) {
+    if (idx + 2 > max_len) {
+      return 0;
+    }
+    dest[idx++] = KISS_FESC;
+    dest[idx++] = (b == KISS_FEND) ? KISS_TFEND : KISS_TFESC;
+    return idx;
   }
+  if (idx + 1 > max_len) {
+    return 0;
+  }
+  dest[idx++] = b;
+  return idx;
 }
 
-void KissModem::writeFrame(uint8_t type, const uint8_t* data, uint16_t len) {
-  _serial.write(KISS_FEND);
-  writeByte(type);
+uint16_t KissModem::encodeFrame(uint8_t type, const uint8_t* data, uint16_t len, uint8_t* dest, uint16_t max_len) {
+  if (max_len < KISS_FRAME_BOUNDARY_BYTES) {
+    return 0;
+  }
+
+  uint16_t idx = 0;
+  dest[idx++] = KISS_FEND;
+
+  idx = appendEscapedByte(dest, idx, max_len, type);
+  if (idx == 0) {
+    return 0;
+  }
+
   for (uint16_t i = 0; i < len; i++) {
-    writeByte(data[i]);
+    idx = appendEscapedByte(dest, idx, max_len, data[i]);
+    if (idx == 0) {
+      return 0;
+    }
   }
-  _serial.write(KISS_FEND);
+
+  if (idx + 1 > max_len) {
+    return 0;
+  }
+  dest[idx++] = KISS_FEND;
+  return idx;
 }
 
-void KissModem::writeHardwareFrame(uint8_t sub_cmd, const uint8_t* data, uint16_t len) {
-  _serial.write(KISS_FEND);
-  writeByte(KISS_CMD_SETHARDWARE);
-  writeByte(sub_cmd);
-  for (uint16_t i = 0; i < len; i++) {
-    writeByte(data[i]);
+bool KissModem::tryFlushFrames() {
+  while (_tx_frame_count > 0) {
+    const uint8_t idx = _tx_frame_head;
+    const uint16_t frame_len = _tx_frame_len[idx];
+    uint16_t written_len = _tx_frame_written[idx];
+
+    if (written_len >= frame_len) {
+      popTxFrame();
+      continue;
+    }
+
+    const int available = _serial.availableForWrite();
+    if (available <= 0) {
+      return false;
+    }
+
+    const uint16_t remaining = frame_len - written_len;
+    const uint16_t chunk_len = (available < (int)remaining) ? (uint16_t)available : remaining;
+    if (chunk_len == 0) {
+      return false;
+    }
+
+    size_t chunk_written = _serial.write(_tx_frame_buf[idx] + written_len, chunk_len);
+    if (chunk_written == 0) {
+      return false;
+    }
+
+    written_len += (uint16_t)chunk_written;
+    _tx_frame_written[idx] = written_len;
+
+    if (written_len < frame_len) {
+      return false;
+    }
+
+    popTxFrame();
   }
-  _serial.write(KISS_FEND);
+  return true;
+}
+
+bool KissModem::queueFrame(uint8_t type, const uint8_t* data, uint16_t len, bool mark_busy_error) {
+  if (_tx_frame_count >= KISS_TX_FRAME_QUEUE_DEPTH && !tryFlushFrames()) {
+    if (mark_busy_error) {
+      _tx_busy_error_pending = true;
+    }
+    return false;
+  }
+  const uint8_t idx = _tx_frame_tail;
+  uint16_t frame_len = encodeFrame(type, data, len, _tx_frame_buf[idx], sizeof(_tx_frame_buf[idx]));
+  if (frame_len == 0) {
+    return false;
+  }
+
+  _tx_frame_len[idx] = frame_len;
+  _tx_frame_written[idx] = 0;
+  _tx_frame_tail = (uint8_t)((_tx_frame_tail + 1) % KISS_TX_FRAME_QUEUE_DEPTH);
+  _tx_frame_count++;
+  tryFlushFrames();
+  return true;
+}
+
+bool KissModem::queuePendingBusyError() {
+  if (!_tx_busy_error_pending) {
+    return true;
+  }
+  const uint8_t err = HW_ERR_TX_BUSY;
+  if (!queueHardwareFrame(HW_RESP_ERROR, &err, 1, false)) {
+    return false;
+  }
+  _tx_busy_error_pending = false;
+  return true;
+}
+
+bool KissModem::queueHardwareFrame(uint8_t sub_cmd, const uint8_t* data, uint16_t len, bool mark_busy_error) {
+  if (len > KISS_MAX_FRAME_SIZE) {
+    return false;
+  }
+  _tx_hw_payload[0] = sub_cmd;
+  if (len > 0) {
+    memcpy(_tx_hw_payload + 1, data, len);
+  }
+  return queueFrame(KISS_CMD_SETHARDWARE, _tx_hw_payload, len + 1, mark_busy_error);
+}
+
+bool KissModem::queuePendingTxDone() {
+  if (!_tx_done_pending) {
+    return true;
+  }
+  if (!queueHardwareFrame(HW_RESP_TX_DONE, &_tx_done_result, 1, false)) {
+    return false;
+  }
+  _tx_done_pending = false;
+  return true;
+}
+
+void KissModem::setTxDonePending(uint8_t result) {
+  _tx_done_result = result;
+  _tx_done_pending = true;
+  _tx_state = TX_DONE_PENDING;
+}
+
+bool KissModem::writeHardwareFrame(uint8_t sub_cmd, const uint8_t* data, uint16_t len) {
+  return queueHardwareFrame(sub_cmd, data, len, true);
 }
 
 void KissModem::writeHardwareError(uint8_t error_code) {
@@ -68,6 +200,8 @@ void KissModem::writeHardwareError(uint8_t error_code) {
 }
 
 void KissModem::loop() {
+  tryFlushFrames();
+
   while (_serial.available()) {
     uint8_t b = _serial.read();
 
@@ -106,6 +240,8 @@ void KissModem::loop() {
   }
 
   processTx();
+  tryFlushFrames();
+  queuePendingBusyError();
 }
 
 void KissModem::processFrame() {
@@ -295,10 +431,7 @@ void KissModem::processTx() {
           _tx_timer = millis();
           _tx_state = TX_SENDING;
         } else {
-          uint8_t result = 0x00;
-          writeHardwareFrame(HW_RESP_TX_DONE, &result, 1);
-          _has_pending_tx = false;
-          _tx_state = TX_IDLE;
+          setTxDonePending(0x00);
         }
       }
       break;
@@ -306,14 +439,15 @@ void KissModem::processTx() {
     case TX_SENDING:
       if (_radio.isSendComplete()) {
         _radio.onSendFinished();
-        uint8_t result = 0x01;
-        writeHardwareFrame(HW_RESP_TX_DONE, &result, 1);
-        _has_pending_tx = false;
-        _tx_state = TX_IDLE;
+        setTxDonePending(0x01);
       } else if (millis() - _tx_timer >= _radio.getEstAirtimeFor(_pending_tx_len) * KISS_TX_TIMEOUT_FACTOR) {
         _radio.onSendFinished();
-        uint8_t result = 0x00;
-        writeHardwareFrame(HW_RESP_TX_DONE, &result, 1);
+        setTxDonePending(0x00);
+      }
+      break;
+
+    case TX_DONE_PENDING:
+      if (queuePendingTxDone()) {
         _has_pending_tx = false;
         _tx_state = TX_IDLE;
       }
@@ -322,8 +456,7 @@ void KissModem::processTx() {
 }
 
 void KissModem::onPacketReceived(int8_t snr, int8_t rssi, const uint8_t* packet, uint16_t len) {
-  writeFrame(KISS_CMD_DATA, packet, len);
-  if (_signal_report_enabled) {
+  if (queueFrame(KISS_CMD_DATA, packet, len) && _signal_report_enabled) {
     uint8_t meta[2] = { (uint8_t)snr, (uint8_t)rssi };
     writeHardwareFrame(HW_RESP_RX_META, meta, 2);
   }
diff --git a/examples/kiss_modem/KissModem.h b/examples/kiss_modem/KissModem.h
index bbe99d6de..a23e459be 100644
--- a/examples/kiss_modem/KissModem.h
+++ b/examples/kiss_modem/KissModem.h
@@ -13,6 +13,14 @@
 
 #define KISS_MAX_FRAME_SIZE  512
 #define KISS_MAX_PACKET_SIZE 255
+#define KISS_FRAME_BOUNDARY_BYTES 2
+#define KISS_TYPE_BYTES 1
+#define KISS_HW_SUBCMD_BYTES 1
+#define KISS_MAX_ESCAPABLE_BYTES (KISS_MAX_FRAME_SIZE + KISS_TYPE_BYTES + KISS_HW_SUBCMD_BYTES)
+#define KISS_MAX_ESCAPED_PAYLOAD_SIZE (2 * KISS_MAX_ESCAPABLE_BYTES)
+#define KISS_MAX_ENCODED_FRAME_SIZE (KISS_FRAME_BOUNDARY_BYTES + KISS_MAX_ESCAPED_PAYLOAD_SIZE)
+#define KISS_TX_FRAME_QUEUE_DEPTH 2
+#define KISS_HW_MAX_PAYLOAD_SIZE (KISS_MAX_FRAME_SIZE + KISS_HW_SUBCMD_BYTES)
 
 #define KISS_CMD_DATA        0x00
 #define KISS_CMD_TXDELAY     0x01
@@ -94,7 +102,8 @@ enum TxState {
   TX_WAIT_CLEAR,
   TX_SLOT_WAIT,
   TX_DELAY,
-  TX_SENDING
+  TX_SENDING,
+  TX_DONE_PENDING
 };
 
 class KissModem {
@@ -130,10 +139,28 @@ class KissModem {
 
   RadioConfig _config;
   bool _signal_report_enabled;
+  uint8_t _tx_frame_buf[KISS_TX_FRAME_QUEUE_DEPTH][KISS_MAX_ENCODED_FRAME_SIZE];
+  uint16_t _tx_frame_len[KISS_TX_FRAME_QUEUE_DEPTH];
+  uint16_t _tx_frame_written[KISS_TX_FRAME_QUEUE_DEPTH];
+  uint8_t _tx_frame_head;
+  uint8_t _tx_frame_tail;
+  uint8_t _tx_frame_count;
+  bool _tx_busy_error_pending;
+  bool _tx_done_pending;
+  uint8_t _tx_done_result;
+  uint8_t _tx_hw_payload[KISS_HW_MAX_PAYLOAD_SIZE];
 
-  void writeByte(uint8_t b);
-  void writeFrame(uint8_t type, const uint8_t* data, uint16_t len);
-  void writeHardwareFrame(uint8_t sub_cmd, const uint8_t* data, uint16_t len);
+  static uint16_t appendEscapedByte(uint8_t* dest, uint16_t idx, uint16_t max_len, uint8_t b);
+  static uint16_t encodeFrame(uint8_t type, const uint8_t* data, uint16_t len, uint8_t* dest, uint16_t max_len);
+  void resetOutputQueue();
+  void popTxFrame();
+  bool tryFlushFrames();
+  bool queueFrame(uint8_t type, const uint8_t* data, uint16_t len, bool mark_busy_error = true);
+  bool queuePendingBusyError();
+  bool queueHardwareFrame(uint8_t sub_cmd, const uint8_t* data, uint16_t len, bool mark_busy_error);
+  bool queuePendingTxDone();
+  void setTxDonePending(uint8_t result);
+  bool writeHardwareFrame(uint8_t sub_cmd, const uint8_t* data, uint16_t len);
   void writeHardwareError(uint8_t error_code);
   void processFrame();
   void handleHardwareCommand(uint8_t sub_cmd, const uint8_t* data, uint16_t len);
@@ -182,4 +209,5 @@ public:
   bool isTxBusy() const { return _tx_state != TX_IDLE; }
   /** True only when radio is actually transmitting; use to skip recvRaw in main loop. */
   bool isActuallyTransmitting() const { return _tx_state == TX_SENDING; }
+  bool isHostOutputBackedUp() const { return _tx_frame_count > 0 || _tx_busy_error_pending || _tx_done_pending; }
 };
diff --git a/examples/kiss_modem/main.cpp b/examples/kiss_modem/main.cpp
index 7fbcaed12..95a06ee63 100644
--- a/examples/kiss_modem/main.cpp
+++ b/examples/kiss_modem/main.cpp
@@ -20,6 +20,8 @@
 
 #define NOISE_FLOOR_CALIB_INTERVAL_MS 2000
 #define AGC_RESET_INTERVAL_MS 30000
+#define USB_TX_TIMEOUT_MS 50
+#define USB_TX_BUFFER_SIZE 1024
 
 StdRNG rng;
 mesh::LocalIdentity identity;
@@ -111,6 +113,12 @@ void setup() {
   uint32_t start = millis();
   while (!Serial && millis() - start < 3000) delay(10);
   delay(100);
+#if defined(ESP32)
+  Serial.setTxTimeoutMs(USB_TX_TIMEOUT_MS);
+#if ARDUINO_USB_MODE
+  Serial.setTxBufferSize(USB_TX_BUFFER_SIZE);
+#endif
+#endif
   modem = new KissModem(Serial, identity, rng, radio_driver, board, sensors);
 #endif
 
@@ -126,7 +134,7 @@ void setup() {
 void loop() {
   modem->loop();
 
-  if (!modem->isActuallyTransmitting()) {
+  if (!modem->isActuallyTransmitting() && !modem->isHostOutputBackedUp()) {
     if (!modem->isTxBusy()) {
       if ((uint32_t)(millis() - next_agc_reset_ms) >= AGC_RESET_INTERVAL_MS) {
         radio_driver.resetAGC();
diff --git a/platformio.ini b/platformio.ini
index f3ada1338..2de71a37f 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -169,3 +169,18 @@ build_src_filter =
   +<../src/Packet.cpp>
 lib_deps =
   google/googletest @ 1.17.0
+
+[env:native_kiss_modem]
+platform = native
+test_framework = googletest
+build_flags = -std=c++17
+  -I test/mocks
+  -I src
+  -I examples/kiss_modem
+test_build_src = yes
+test_filter = test_kiss_modem
+build_src_filter =
+  -<*>
+  +<../examples/kiss_modem/KissModem.cpp>
+lib_deps =
+  google/googletest @ 1.17.0
diff --git a/test/mocks/Arduino.h b/test/mocks/Arduino.h
new file mode 100644
index 000000000..77499fe41
--- /dev/null
+++ b/test/mocks/Arduino.h
@@ -0,0 +1,17 @@
+#pragma once
+
+#include <cstdint>
+#include <cmath>
+#include "Stream.h"
+
+inline uint32_t g_mock_millis = 0;
+
+using std::isnan;
+
+inline uint32_t millis() {
+  return g_mock_millis;
+}
+
+inline void delay(uint32_t ms) {
+  g_mock_millis += ms;
+}
diff --git a/test/mocks/CayenneLPP.h b/test/mocks/CayenneLPP.h
new file mode 100644
index 000000000..9d51c0fcf
--- /dev/null
+++ b/test/mocks/CayenneLPP.h
@@ -0,0 +1,11 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+class CayenneLPP {
+public:
+  explicit CayenneLPP(size_t) {}
+  const uint8_t* getBuffer() const { return nullptr; }
+  uint16_t getSize() const { return 0; }
+};
diff --git a/test/mocks/Identity.h b/test/mocks/Identity.h
new file mode 100644
index 000000000..5c3d25e94
--- /dev/null
+++ b/test/mocks/Identity.h
@@ -0,0 +1,39 @@
+#pragma once
+
+#include <cstdint>
+#include <cstring>
+#include "Utils.h"
+
+namespace mesh {
+
+class Identity {
+public:
+  uint8_t pub_key[PUB_KEY_SIZE];
+
+  Identity() {
+    std::memset(pub_key, 0, sizeof(pub_key));
+  }
+
+  explicit Identity(const uint8_t* src) {
+    std::memcpy(pub_key, src, PUB_KEY_SIZE);
+  }
+
+  bool verify(const uint8_t*, const uint8_t*, int) const {
+    return true;
+  }
+};
+
+class LocalIdentity : public Identity {
+public:
+  LocalIdentity() : Identity() {}
+
+  void sign(uint8_t* sig, const uint8_t*, int) const {
+    std::memset(sig, 0x5A, SIGNATURE_SIZE);
+  }
+
+  void calcSharedSecret(uint8_t* secret, const uint8_t*) const {
+    std::memset(secret, 0x11, PUB_KEY_SIZE);
+  }
+};
+
+}
diff --git a/test/mocks/Mesh.h b/test/mocks/Mesh.h
new file mode 100644
index 000000000..b6c263c19
--- /dev/null
+++ b/test/mocks/Mesh.h
@@ -0,0 +1,27 @@
+#pragma once
+
+#include <cstdint>
+
+namespace mesh {
+
+class Radio {
+public:
+  virtual ~Radio() = default;
+  virtual bool isReceiving() { return false; }
+  virtual uint32_t getEstAirtimeFor(uint16_t) { return 10; }
+  virtual bool startSendRaw(const uint8_t*, uint16_t) { return true; }
+  virtual bool isSendComplete() { return true; }
+  virtual void onSendFinished() {}
+  virtual int16_t getNoiseFloor() { return -120; }
+};
+
+class MainBoard {
+public:
+  virtual ~MainBoard() = default;
+  virtual uint16_t getBattMilliVolts() { return 4200; }
+  virtual float getMCUTemperature() { return 25.0f; }
+  virtual const char* getManufacturerName() { return "mock-board"; }
+  virtual void reboot() {}
+};
+
+}
diff --git a/test/mocks/Stream.h b/test/mocks/Stream.h
index 195a30297..cf33785d1 100644
--- a/test/mocks/Stream.h
+++ b/test/mocks/Stream.h
@@ -1,10 +1,23 @@
 #pragma once
 
-// Mock Stream class for native testing
-// Provides minimal interface needed by Utils.h
+#include <cstddef>
+#include <cstdint>
 
 class Stream {
 public:
-    virtual void print(char c) {}
-    virtual void print(const char* str) {}
+    virtual ~Stream() = default;
+    virtual size_t write(uint8_t) { return 1; }
+    virtual size_t write(const uint8_t* buffer, size_t size) {
+        size_t total = 0;
+        for (size_t i = 0; i < size; i++) {
+            total += write(buffer[i]);
+        }
+        return total;
+    }
+    virtual int available() { return 0; }
+    virtual int availableForWrite() { return 0; }
+    virtual int read() { return -1; }
+    virtual void flush() {}
+    virtual void print(char) {}
+    virtual void print(const char*) {}
 };
diff --git a/test/mocks/Utils.h b/test/mocks/Utils.h
new file mode 100644
index 000000000..9bb6b060b
--- /dev/null
+++ b/test/mocks/Utils.h
@@ -0,0 +1,44 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <algorithm>
+
+#define PUB_KEY_SIZE 32
+#define PRV_KEY_SIZE 64
+#define SIGNATURE_SIZE 64
+#define CIPHER_MAC_SIZE 16
+
+namespace mesh {
+
+class RNG {
+public:
+  virtual ~RNG() = default;
+  virtual void random(uint8_t* dest, size_t sz) = 0;
+};
+
+class Utils {
+public:
+  static void sha256(uint8_t* hash, size_t hash_len, const uint8_t*, int) {
+    std::memset(hash, 0, hash_len);
+  }
+
+  static int encryptThenMAC(const uint8_t*, uint8_t* dest, const uint8_t* src, int src_len) {
+    int out_len = src_len + CIPHER_MAC_SIZE;
+    std::memset(dest, 0xAA, CIPHER_MAC_SIZE);
+    std::memcpy(dest + CIPHER_MAC_SIZE, src, src_len);
+    return out_len;
+  }
+
+  static int MACThenDecrypt(const uint8_t*, uint8_t* dest, const uint8_t* src, int src_len) {
+    if (src_len < CIPHER_MAC_SIZE) {
+      return 0;
+    }
+    int out_len = src_len - CIPHER_MAC_SIZE;
+    std::memcpy(dest, src + CIPHER_MAC_SIZE, out_len);
+    return out_len;
+  }
+};
+
+}
diff --git a/test/mocks/helpers/SensorManager.h b/test/mocks/helpers/SensorManager.h
new file mode 100644
index 000000000..d1a41cb5d
--- /dev/null
+++ b/test/mocks/helpers/SensorManager.h
@@ -0,0 +1,10 @@
+#pragma once
+
+#include <cstdint>
+#include "CayenneLPP.h"
+
+class SensorManager {
+public:
+  virtual ~SensorManager() = default;
+  virtual bool querySensors(uint8_t, CayenneLPP&) { return false; }
+};
diff --git a/test/test_kiss_modem/test_tx_backpressure.cpp b/test/test_kiss_modem/test_tx_backpressure.cpp
new file mode 100644
index 000000000..39a5e3b74
--- /dev/null
+++ b/test/test_kiss_modem/test_tx_backpressure.cpp
@@ -0,0 +1,294 @@
+#include <gtest/gtest.h>
+
+#include <atomic>
+#include <cstddef>
+#include <condition_variable>
+#include <future>
+#include <mutex>
+#include <queue>
+#include <vector>
+
+#include "KissModem.h"
+
+static constexpr int TEST_TX_AVAILABLE_BYTES = 4096;
+static constexpr size_t TEST_DEFAULT_MAX_WRITE_CHUNK = SIZE_MAX;
+static constexpr size_t TEST_PARTIAL_WRITE_CHUNK = 2;
+static constexpr int TEST_PARTIAL_WRITE_FLUSH_LOOPS = 3;
+static constexpr uint8_t TEST_SNR = 8;
+static constexpr uint8_t TEST_RSSI = 200;
+
+class BlockingStream : public Stream {
+public:
+  void pushRx(const std::vector<uint8_t>& bytes) {
+    std::lock_guard<std::mutex> lock(_mutex);
+    for (uint8_t b : bytes) {
+      _rx.push(b);
+    }
+  }
+
+  void setBlockWrites(bool blocked) {
+    {
+      std::lock_guard<std::mutex> lock(_mutex);
+      _block_writes = blocked;
+    }
+    _cv.notify_all();
+  }
+
+  bool isWriteBlocked() const {
+    return _entered_block.load();
+  }
+
+  size_t writesCount() const {
+    std::lock_guard<std::mutex> lock(_mutex);
+    return _writes.size();
+  }
+
+  std::vector<uint8_t> writesSnapshot() const {
+    std::lock_guard<std::mutex> lock(_mutex);
+    return _writes;
+  }
+
+  int availableForWrite() override {
+    std::lock_guard<std::mutex> lock(_mutex);
+    return _block_writes ? 0 : TEST_TX_AVAILABLE_BYTES;
+  }
+
+  void setMaxWriteChunk(size_t chunk) {
+    std::lock_guard<std::mutex> lock(_mutex);
+    _max_write_chunk = chunk;
+  }
+
+  size_t write(const uint8_t* buffer, size_t size) override {
+    std::unique_lock<std::mutex> lock(_mutex);
+    while (_block_writes) {
+      _entered_block.store(true);
+      _cv.wait(lock);
+    }
+    const size_t chunk = (size < _max_write_chunk) ? size : _max_write_chunk;
+    for (size_t i = 0; i < chunk; i++) {
+      _writes.push_back(buffer[i]);
+    }
+    return chunk;
+  }
+
+  size_t write(uint8_t b) override {
+    return write(&b, 1);
+  }
+
+  int available() override {
+    std::lock_guard<std::mutex> lock(_mutex);
+    return static_cast<int>(_rx.size());
+  }
+
+  int read() override {
+    std::lock_guard<std::mutex> lock(_mutex);
+    if (_rx.empty()) {
+      return -1;
+    }
+    int b = _rx.front();
+    _rx.pop();
+    return b;
+  }
+
+private:
+  mutable std::mutex _mutex;
+  std::condition_variable _cv;
+  std::queue<uint8_t> _rx;
+  std::vector<uint8_t> _writes;
+  bool _block_writes = false;
+  std::atomic<bool> _entered_block = false;
+  size_t _max_write_chunk = TEST_DEFAULT_MAX_WRITE_CHUNK;
+};
+
+class FakeRNG : public mesh::RNG {
+public:
+  void random(uint8_t* dest, size_t sz) override {
+    for (size_t i = 0; i < sz; i++) {
+      dest[i] = 0;
+    }
+  }
+};
+
+class FakeRadio : public mesh::Radio {
+public:
+  bool isReceiving() override { return false; }
+  uint32_t getEstAirtimeFor(uint16_t) override { return 10; }
+  bool startSendRaw(const uint8_t*, uint16_t) override {
+    _start_send_count++;
+    return _start_send_result;
+  }
+  bool isSendComplete() override { return _send_complete; }
+  void onSendFinished() override { _send_finished_count++; }
+  int16_t getNoiseFloor() override { return -120; }
+
+  void setStartSendResult(bool result) { _start_send_result = result; }
+  void setSendComplete(bool complete) { _send_complete = complete; }
+  int startSendCount() const { return _start_send_count; }
+  int sendFinishedCount() const { return _send_finished_count; }
+
+private:
+  bool _start_send_result = true;
+  bool _send_complete = true;
+  int _start_send_count = 0;
+  int _send_finished_count = 0;
+};
+
+class FakeBoard : public mesh::MainBoard {
+public:
+  uint16_t getBattMilliVolts() override { return 4200; }
+  float getMCUTemperature() override { return 24.0f; }
+  const char* getManufacturerName() override { return "test-board"; }
+  void reboot() override {}
+};
+
+class FakeSensors : public SensorManager {
+public:
+  bool querySensors(uint8_t, CayenneLPP&) override { return false; }
+};
+
+class KissModemFixture : public ::testing::Test {
+protected:
+  BlockingStream serial;
+  mesh::LocalIdentity identity;
+  FakeRNG rng;
+  FakeRadio radio;
+  FakeBoard board;
+  FakeSensors sensors;
+  KissModem modem;
+
+  KissModemFixture()
+    : modem(serial, identity, rng, radio, board, sensors) {
+    modem.begin();
+  }
+
+  static std::vector<uint8_t> dataFrame(const std::vector<uint8_t>& packet) {
+    std::vector<uint8_t> frame = {KISS_FEND, KISS_CMD_DATA};
+    frame.insert(frame.end(), packet.begin(), packet.end());
+    frame.push_back(KISS_FEND);
+    return frame;
+  }
+
+  void advanceToTxSending() {
+    modem.loop();
+    modem.loop();
+    delay((uint32_t)KISS_DEFAULT_TXDELAY * 10);
+    modem.loop();
+  }
+};
+
+TEST_F(KissModemFixture, PingResponseShouldNotStallLoopUnderTxBackpressure) {
+  serial.setBlockWrites(true);
+  serial.pushRx({KISS_FEND, KISS_CMD_SETHARDWARE, HW_CMD_PING, KISS_FEND});
+
+  auto future = std::async(std::launch::async, [this]() {
+    modem.loop();
+  });
+
+  auto status = future.wait_for(std::chrono::milliseconds(100));
+  EXPECT_EQ(status, std::future_status::ready) << "KissModem::loop blocked in serial write under TX backpressure";
+  EXPECT_FALSE(serial.isWriteBlocked()) << "KissModem entered blocking write path";
+
+  serial.setBlockWrites(false);
+  future.wait();
+  modem.loop();
+  EXPECT_GT(serial.writesCount(), 0U) << "KissModem did not flush queued response after backpressure cleared";
+}
+
+TEST_F(KissModemFixture, PingResponseKeepsStandardKissFraming) {
+  serial.pushRx({KISS_FEND, KISS_CMD_SETHARDWARE, HW_CMD_PING, KISS_FEND});
+  modem.loop();
+
+  const std::vector<uint8_t> expected = {KISS_FEND, KISS_CMD_SETHARDWARE, HW_RESP(HW_CMD_PING), KISS_FEND};
+  EXPECT_EQ(serial.writesSnapshot(), expected);
+}
+
+TEST_F(KissModemFixture, PingResponseKeepsFramingWithPartialBulkWrites) {
+  serial.setMaxWriteChunk(TEST_PARTIAL_WRITE_CHUNK);
+  serial.pushRx({KISS_FEND, KISS_CMD_SETHARDWARE, HW_CMD_PING, KISS_FEND});
+  for (int i = 0; i < TEST_PARTIAL_WRITE_FLUSH_LOOPS; i++) {
+    modem.loop();
+  }
+
+  const std::vector<uint8_t> expected = {KISS_FEND, KISS_CMD_SETHARDWARE, HW_RESP(HW_CMD_PING), KISS_FEND};
+  EXPECT_EQ(serial.writesSnapshot(), expected);
+}
+
+TEST_F(KissModemFixture, PacketAndMetaAreQueuedTogetherUnderBackpressure) {
+  static constexpr uint8_t TEST_PACKET[] = {0x01, 0x02, 0x03};
+
+  serial.setBlockWrites(true);
+  modem.onPacketReceived((int8_t)TEST_SNR, (int8_t)TEST_RSSI, TEST_PACKET, sizeof(TEST_PACKET));
+  serial.setBlockWrites(false);
+  modem.loop();
+  modem.loop();
+
+  const std::vector<uint8_t> expected = {
+      KISS_FEND, KISS_CMD_DATA, TEST_PACKET[0], TEST_PACKET[1], TEST_PACKET[2], KISS_FEND,
+      KISS_FEND, KISS_CMD_SETHARDWARE, HW_RESP_RX_META, TEST_SNR, TEST_RSSI, KISS_FEND};
+  EXPECT_EQ(serial.writesSnapshot(), expected);
+}
+
+TEST_F(KissModemFixture, RadioTxCompletionAdvancesWhileHostOutputIsBackedUp) {
+  serial.pushRx(dataFrame({0x42}));
+  advanceToTxSending();
+  ASSERT_EQ(radio.startSendCount(), 1);
+
+  serial.setBlockWrites(true);
+  modem.loop();
+  EXPECT_EQ(radio.sendFinishedCount(), 1);
+  EXPECT_TRUE(modem.isTxBusy());
+
+  serial.setBlockWrites(false);
+  modem.loop();
+
+  const std::vector<uint8_t> expected = {KISS_FEND, KISS_CMD_SETHARDWARE, HW_RESP_TX_DONE, 0x01, KISS_FEND};
+  EXPECT_EQ(serial.writesSnapshot(), expected);
+  EXPECT_FALSE(modem.isTxBusy());
+}
+
+TEST_F(KissModemFixture, QueueFullReportsBusyWithoutDroppingQueuedFrames) {
+  static constexpr uint8_t TEST_PACKET_ONE[] = {0x11, 0x12};
+  static constexpr uint8_t TEST_PACKET_TWO[] = {0x21, 0x22};
+
+  serial.setBlockWrites(true);
+  modem.onPacketReceived((int8_t)TEST_SNR, (int8_t)TEST_RSSI, TEST_PACKET_ONE, sizeof(TEST_PACKET_ONE));
+  modem.onPacketReceived((int8_t)TEST_SNR, (int8_t)TEST_RSSI, TEST_PACKET_TWO, sizeof(TEST_PACKET_TWO));
+  serial.setBlockWrites(false);
+  modem.loop();
+
+  const std::vector<uint8_t> expected = {
+      KISS_FEND, KISS_CMD_DATA, TEST_PACKET_ONE[0], TEST_PACKET_ONE[1], KISS_FEND,
+      KISS_FEND, KISS_CMD_SETHARDWARE, HW_RESP_RX_META, TEST_SNR, TEST_RSSI, KISS_FEND,
+      KISS_FEND, KISS_CMD_SETHARDWARE, HW_RESP_ERROR, HW_ERR_TX_BUSY, KISS_FEND};
+  EXPECT_EQ(serial.writesSnapshot(), expected);
+}
+
+TEST_F(KissModemFixture, QueuedEncoderEscapesKissSpecialBytes) {
+  static constexpr uint8_t TEST_PACKET[] = {KISS_FEND, KISS_FESC, 0x01};
+
+  modem.onPacketReceived((int8_t)TEST_SNR, (int8_t)TEST_RSSI, TEST_PACKET, sizeof(TEST_PACKET));
+
+  const std::vector<uint8_t> expected = {
+      KISS_FEND, KISS_CMD_DATA, KISS_FESC, KISS_TFEND, KISS_FESC, KISS_TFESC, 0x01, KISS_FEND,
+      KISS_FEND, KISS_CMD_SETHARDWARE, HW_RESP_RX_META, TEST_SNR, TEST_RSSI, KISS_FEND};
+  EXPECT_EQ(serial.writesSnapshot(), expected);
+}
+
+TEST_F(KissModemFixture, MaxPacketWorstCaseEscapingFitsQueuedFrame) {
+  std::vector<uint8_t> packet(KISS_MAX_PACKET_SIZE, KISS_FEND);
+  std::vector<uint8_t> expected = {KISS_FEND, KISS_CMD_DATA};
+  for (size_t i = 0; i < packet.size(); i++) {
+    expected.push_back(KISS_FESC);
+    expected.push_back(KISS_TFEND);
+  }
+  expected.push_back(KISS_FEND);
+  expected.insert(expected.end(), {KISS_FEND, KISS_CMD_SETHARDWARE, HW_RESP_RX_META, TEST_SNR, TEST_RSSI, KISS_FEND});
+
+  modem.onPacketReceived((int8_t)TEST_SNR, (int8_t)TEST_RSSI, packet.data(), packet.size());
+  EXPECT_EQ(serial.writesSnapshot(), expected);
+}
+
+int main(int argc, char** argv) {
+  ::testing::InitGoogleTest(&argc, argv);
+  return RUN_ALL_TESTS();
+}
diff --git a/variants/heltec_v4/platformio.ini b/variants/heltec_v4/platformio.ini
index fabf38272..cb76beb3d 100644
--- a/variants/heltec_v4/platformio.ini
+++ b/variants/heltec_v4/platformio.ini
@@ -432,5 +432,10 @@ lib_deps =
 
 [env:heltec_v4_kiss_modem]
 extends = Heltec_lora32_v4
+build_unflags =
+  -DARDUINO_USB_MODE=0
+build_flags =
+  ${Heltec_lora32_v4.build_flags}
+  -DARDUINO_USB_MODE=1
 build_src_filter = ${Heltec_lora32_v4.build_src_filter}
   +<../examples/kiss_modem/>
diff --git a/variants/station_g2/platformio.ini b/variants/station_g2/platformio.ini
index 6432b5238..508ffe4b5 100644
--- a/variants/station_g2/platformio.ini
+++ b/variants/station_g2/platformio.ini
@@ -241,5 +241,10 @@ lib_deps =
 
 [env:Station_G2_kiss_modem]
 extends = Station_G2
+build_unflags =
+  -DARDUINO_USB_MODE=0
+build_flags =
+  ${Station_G2.build_flags}
+  -DARDUINO_USB_MODE=1
 build_src_filter = ${Station_G2.build_src_filter}
   +<../examples/kiss_modem/>

From 39ff5b879acadb124ee535fcf2386a83cfff08e0 Mon Sep 17 00:00:00 2001
From: ViezeVingertjes <michael.overhorst@gmail.com>
Date: Tue, 23 Jun 2026 15:15:13 +0200
Subject: [PATCH 12/29] fix: run KISS modem unit tests in CI via
 native_kiss_modem env

The new test_kiss_modem suite needs KissModem headers and sources that
only native_kiss_modem provides. Scope native to test_utils and run both
envs in the unit test workflow.
---
 .github/workflows/run-unit-tests.yml | 2 +-
 platformio.ini                       | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/run-unit-tests.yml b/.github/workflows/run-unit-tests.yml
index e3af3aafb..5d48f4c67 100644
--- a/.github/workflows/run-unit-tests.yml
+++ b/.github/workflows/run-unit-tests.yml
@@ -20,7 +20,7 @@ jobs:
         uses: ./.github/actions/setup-build-environment
 
       - name: Run Unit Tests
-        run: pio test -e native -vv
+        run: pio test -e native -e native_kiss_modem -vv
 
       - name: Upload Test Results
         # Upload test results even if the test step failed.
diff --git a/platformio.ini b/platformio.ini
index 2de71a37f..cdd67d277 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -163,6 +163,7 @@ build_flags = -std=c++17
   -I src
   -I test/mocks
 test_build_src = yes
+test_filter = test_utils
 build_src_filter =
   -<*>
   +<../src/Utils.cpp>

From 3b69e7873bd76b52c3d3469d7496ff64a9048db5 Mon Sep 17 00:00:00 2001
From: ViezeVingertjes <michael.overhorst@gmail.com>
Date: Fri, 26 Jun 2026 00:11:33 +0200
Subject: [PATCH 13/29] fix: guard HWCDC serial config behind ARDUINO_USB_MODE

setTxTimeoutMs() and setTxBufferSize() are HWCDC-only APIs; calling
them on HardwareSerial (UART-bridge boards like T-Beam) fails to compile.

Co-Authored-By: Adam Gessaman <adam@gessaman.com>
---
 examples/kiss_modem/main.cpp | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/examples/kiss_modem/main.cpp b/examples/kiss_modem/main.cpp
index 95a06ee63..5836a6941 100644
--- a/examples/kiss_modem/main.cpp
+++ b/examples/kiss_modem/main.cpp
@@ -113,11 +113,9 @@ void setup() {
   uint32_t start = millis();
   while (!Serial && millis() - start < 3000) delay(10);
   delay(100);
-#if defined(ESP32)
+#if defined(ESP32) && ARDUINO_USB_MODE
   Serial.setTxTimeoutMs(USB_TX_TIMEOUT_MS);
-#if ARDUINO_USB_MODE
   Serial.setTxBufferSize(USB_TX_BUFFER_SIZE);
-#endif
 #endif
   modem = new KissModem(Serial, identity, rng, radio_driver, board, sensors);
 #endif

From b28bf00348c1cf555a88a5988bd0e889958a2517 Mon Sep 17 00:00:00 2001
From: taco <taco@sly.nu>
Date: Sun, 19 Jul 2026 22:06:36 +1000
Subject: [PATCH 14/29] fix: setMaxPacketMillis() should return void

---
 src/helpers/radiolib/CustomLR1110.h | 2 +-
 src/helpers/radiolib/CustomSX1262.h | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/helpers/radiolib/CustomLR1110.h b/src/helpers/radiolib/CustomLR1110.h
index db0f2af3d..87a7005f5 100644
--- a/src/helpers/radiolib/CustomLR1110.h
+++ b/src/helpers/radiolib/CustomLR1110.h
@@ -72,7 +72,7 @@ class CustomLR1110 : public LR1110 {
       return false;
     }
 
-    PacketMillis setMaxPacketMillis(PacketMillis maxPacketMillis) {
+    void setMaxPacketMillis(PacketMillis maxPacketMillis) {
       MESH_DEBUG_PRINTLN("Setting _preambleMillis=%u, _maxPacketMillis=%u", maxPacketMillis.preambleMillis, maxPacketMillis.payloadMillis);
       _preambleMillis = maxPacketMillis.preambleMillis;
       _maxPayloadMillis = maxPacketMillis.payloadMillis;
diff --git a/src/helpers/radiolib/CustomSX1262.h b/src/helpers/radiolib/CustomSX1262.h
index 284b79c02..18932488a 100644
--- a/src/helpers/radiolib/CustomSX1262.h
+++ b/src/helpers/radiolib/CustomSX1262.h
@@ -137,7 +137,7 @@ class CustomSX1262 : public SX1262 {
       return false;
     }
 
-    PacketMillis setMaxPacketMillis(PacketMillis maxPacketMillis) {
+    void setMaxPacketMillis(PacketMillis maxPacketMillis) {
       MESH_DEBUG_PRINTLN("Setting _preambleMillis=%u, _maxPacketMillis=%u", maxPacketMillis.preambleMillis, maxPacketMillis.payloadMillis);
       _preambleMillis = maxPacketMillis.preambleMillis;
       _maxPayloadMillis = maxPacketMillis.payloadMillis;

From aee53a8c3e3176eb9e26fd781774f198d4bb6f30 Mon Sep 17 00:00:00 2001
From: entr0p1 <1475255+entr0p1@users.noreply.github.com>
Date: Sun, 19 Jul 2026 23:59:12 +1000
Subject: [PATCH 15/29] NRF52Board - ShutdownPeripherals() housekeeping

Improvements:
- Add condition to only turn off display if on (avoids wedging the shutdown on some displays)
- Reset LoRa radio before calling radio_driver.powerOff() to ensure it is in a known good state (and will accept the command)
- Ensure SPI is started so LoRa radio commands can be sent (some shutdowns can happen before this)
- Add gate for P_LORA_NSS pin defined before writing to the pin
---
 src/helpers/NRF52Board.cpp | 30 +++++++++++++++++++++++++++---
 1 file changed, 27 insertions(+), 3 deletions(-)

diff --git a/src/helpers/NRF52Board.cpp b/src/helpers/NRF52Board.cpp
index 5fb1e55ed..23f7cafc2 100644
--- a/src/helpers/NRF52Board.cpp
+++ b/src/helpers/NRF52Board.cpp
@@ -314,14 +314,38 @@ float NRF52Board::getMCUTemperature() {
 void NRF52Board::shutdownPeripherals() {
   // Power off the display if any
 #ifdef DISPLAY_CLASS
-  display.turnOff();
+  if (display.isOn()) {
+    display.turnOff();
+  }
 #endif
-
+  // Prep LoRa radio for power down
+  #ifdef P_LORA_RESET
+    digitalWrite(P_LORA_RESET, HIGH);  // preload OUT latch so pinMode can't glitch NRESET low
+    pinMode(P_LORA_RESET, OUTPUT);
+    digitalWrite(P_LORA_RESET, LOW);   // deliberate hardware reset (datasheet: >=100us)
+    delayMicroseconds(200);
+    digitalWrite(P_LORA_RESET, HIGH);
+  #endif
+  #if defined(P_LORA_SCLK) && defined(P_LORA_MISO) && defined(P_LORA_MOSI)
+    SPI.setPins(P_LORA_MISO, P_LORA_SCLK, P_LORA_MOSI);
+    SPI.begin(); // SPI may not be started on some shutdown paths, need it to shut down radio
+  #endif
+  #ifdef P_LORA_BUSY
+    pinMode(P_LORA_BUSY, INPUT);
+    uint32_t started_at = millis();
+    while (digitalRead(P_LORA_BUSY) && millis() - started_at < 10) {} //wait for radio to be ready
+  #endif
+  #ifdef P_LORA_NSS
+    pinMode(P_LORA_NSS, OUTPUT);
+    digitalWrite(P_LORA_NSS, HIGH);
+  #endif
   // Power off LoRa
   radio_driver.powerOff();
 
   // Keep LoRa inactive during deepsleep
-  digitalWrite(P_LORA_NSS, HIGH);
+  #ifdef P_LORA_NSS
+    digitalWrite(P_LORA_NSS, HIGH);
+  #endif
 
   // Power off GPS if any
   if(sensors.getLocationProvider() != NULL) {

From cc221330ba1dbac71d2214dbcdb3699d74b02e83 Mon Sep 17 00:00:00 2001
From: Ryan Gregg <github@ryangregg.com>
Date: Sun, 19 Jul 2026 10:17:08 -0700
Subject: [PATCH 16/29] Fix nRF52 builds: guard SerialEthernetInterface with
 ETHERNET_ENABLED

SerialEthernetInterface.cpp is compiled for every nRF52 target because
PlatformIO builds all .cpp files under src/. It includes
SerialEthernetInterface.h, which unconditionally pulls in
<RAK13800_W5100S.h> -- a library only present in the RAK4631 Ethernet
env's lib_deps. As a result any other nRF52 board (e.g. Heltec T114)
fails to build with 'RAK13800_W5100S.h: No such file or directory'.

Wrap the contents of both files in '#ifdef ETHERNET_ENABLED' so they
compile to empty translation units on non-Ethernet builds. RAK4631
Ethernet envs define ETHERNET_ENABLED and are unaffected.

Fixes #2985
---
 src/helpers/nrf52/SerialEthernetInterface.cpp | 4 ++++
 src/helpers/nrf52/SerialEthernetInterface.h   | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/src/helpers/nrf52/SerialEthernetInterface.cpp b/src/helpers/nrf52/SerialEthernetInterface.cpp
index 708910232..36a998a4e 100644
--- a/src/helpers/nrf52/SerialEthernetInterface.cpp
+++ b/src/helpers/nrf52/SerialEthernetInterface.cpp
@@ -1,3 +1,5 @@
+#ifdef ETHERNET_ENABLED
+
 #include "SerialEthernetInterface.h"
 #include "EthernetMac.h"
 #include <SPI.h>
@@ -262,3 +264,5 @@ bool SerialEthernetInterface::isConnected() const {
 void SerialEthernetInterface::loop() {
   Ethernet.maintain();
 }
+
+#endif // ETHERNET_ENABLED
diff --git a/src/helpers/nrf52/SerialEthernetInterface.h b/src/helpers/nrf52/SerialEthernetInterface.h
index 95ce8a521..b8b4e94b2 100644
--- a/src/helpers/nrf52/SerialEthernetInterface.h
+++ b/src/helpers/nrf52/SerialEthernetInterface.h
@@ -1,5 +1,7 @@
 #pragma once
 
+#ifdef ETHERNET_ENABLED
+
 #include "helpers/BaseSerialInterface.h"
 #include <SPI.h>
 #include <RAK13800_W5100S.h>
@@ -76,3 +78,5 @@ class SerialEthernetInterface : public BaseSerialInterface {
   #define ETHERNET_DEBUG_PRINTLN(...) {}
   #define ETHERNET_DEBUG_PRINT_IP(...) {}
 #endif
+
+#endif // ETHERNET_ENABLED

From ae48072ff059c53c94803cd9e6583c763a13a703 Mon Sep 17 00:00:00 2001
From: taco <taco@sly.nu>
Date: Mon, 20 Jul 2026 19:40:49 +1000
Subject: [PATCH 17/29] SX1262: add setter methods for preambleMillis and
 payloadMillis

---
 src/helpers/radiolib/CustomSX1262.h        | 11 +++++++----
 src/helpers/radiolib/CustomSX1262Wrapper.h |  4 +++-
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/src/helpers/radiolib/CustomSX1262.h b/src/helpers/radiolib/CustomSX1262.h
index 18932488a..103f51672 100644
--- a/src/helpers/radiolib/CustomSX1262.h
+++ b/src/helpers/radiolib/CustomSX1262.h
@@ -137,10 +137,13 @@ class CustomSX1262 : public SX1262 {
       return false;
     }
 
-    void setMaxPacketMillis(PacketMillis maxPacketMillis) {
-      MESH_DEBUG_PRINTLN("Setting _preambleMillis=%u, _maxPacketMillis=%u", maxPacketMillis.preambleMillis, maxPacketMillis.payloadMillis);
-      _preambleMillis = maxPacketMillis.preambleMillis;
-      _maxPayloadMillis = maxPacketMillis.payloadMillis;
+    void setPreambleMillis(uint32_t preambleMillis) {
+      _preambleMillis = preambleMillis;
+      MESH_DEBUG_PRINTLN("Set _preambleMillis=%u", _preambleMillis);
+    }
+    void setMaxPayloadMillis(uint32_t payloadMillis) {
+      _maxPayloadMillis = payloadMillis;
+      MESH_DEBUG_PRINTLN("Set _maxPayloadMillis=%u", _maxPayloadMillis);
     }
 
     bool getRxBoostedGainMode() {
diff --git a/src/helpers/radiolib/CustomSX1262Wrapper.h b/src/helpers/radiolib/CustomSX1262Wrapper.h
index 45af4cb4b..bfea50ec9 100644
--- a/src/helpers/radiolib/CustomSX1262Wrapper.h
+++ b/src/helpers/radiolib/CustomSX1262Wrapper.h
@@ -18,7 +18,9 @@ public:
     ((CustomSX1262 *)_radio)->setBandwidth(bw);
     ((CustomSX1262 *)_radio)->setCodingRate(cr);
     updatePreamble(sf);
-    ((CustomSX1262 *)_radio)->setMaxPacketMillis(calcMaxPacketMillis(sf, bw, cr, preambleLengthForSF(sf)));
+    PacketMillis pm = calcMaxPacketMillis(sf, bw, cr, preambleLengthForSF(sf));
+    ((CustomSX1262 *)_radio)->setPreambleMillis(pm.preambleMillis);
+    ((CustomSX1262 *)_radio)->setMaxPayloadMillis(pm.payloadMillis);
   }
 
   bool isReceivingPacket() override { 

From 121b72712b361eaa5685f8c90144e5fccad5690d Mon Sep 17 00:00:00 2001
From: taco <taco@sly.nu>
Date: Mon, 20 Jul 2026 19:42:22 +1000
Subject: [PATCH 18/29] LR1110: add setter methods for preambleMillis and
 payloadMillis

---
 src/helpers/radiolib/CustomLR1110.h        | 13 ++++++++-----
 src/helpers/radiolib/CustomLR1110Wrapper.h |  5 +++--
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/src/helpers/radiolib/CustomLR1110.h b/src/helpers/radiolib/CustomLR1110.h
index 87a7005f5..0470e48f2 100644
--- a/src/helpers/radiolib/CustomLR1110.h
+++ b/src/helpers/radiolib/CustomLR1110.h
@@ -71,11 +71,14 @@ class CustomLR1110 : public LR1110 {
       _activityAt = 0; _headerSeen = false;
       return false;
     }
-
-    void setMaxPacketMillis(PacketMillis maxPacketMillis) {
-      MESH_DEBUG_PRINTLN("Setting _preambleMillis=%u, _maxPacketMillis=%u", maxPacketMillis.preambleMillis, maxPacketMillis.payloadMillis);
-      _preambleMillis = maxPacketMillis.preambleMillis;
-      _maxPayloadMillis = maxPacketMillis.payloadMillis;
+    
+    void setPreambleMillis(uint32_t preambleMillis) {
+      _preambleMillis = preambleMillis;
+      MESH_DEBUG_PRINTLN("Set _preambleMillis=%u", _preambleMillis);
+    }
+    void setMaxPayloadMillis(uint32_t payloadMillis) {
+      _maxPayloadMillis = payloadMillis;
+      MESH_DEBUG_PRINTLN("Set _maxPayloadMillis=%u", _maxPayloadMillis);
     }
 
     uint8_t getSpreadingFactor() const { return spreadingFactor; }
diff --git a/src/helpers/radiolib/CustomLR1110Wrapper.h b/src/helpers/radiolib/CustomLR1110Wrapper.h
index 981faf092..44230c61c 100644
--- a/src/helpers/radiolib/CustomLR1110Wrapper.h
+++ b/src/helpers/radiolib/CustomLR1110Wrapper.h
@@ -14,8 +14,9 @@ public:
     ((CustomLR1110 *)_radio)->setBandwidth(bw);
     ((CustomLR1110 *)_radio)->setCodingRate(cr);
     updatePreamble(sf);
-    ((CustomLR1110 *)_radio)->setMaxPacketMillis(calcMaxPacketMillis(sf, bw, cr, preambleLengthForSF(sf)));
-
+    PacketMillis pm = calcMaxPacketMillis(sf, bw, cr, preambleLengthForSF(sf));
+    ((CustomLR1110 *)_radio)->setPreambleMillis(pm.preambleMillis);
+    ((CustomLR1110 *)_radio)->setMaxPayloadMillis(pm.payloadMillis);
   }
 
   void doResetAGC() override { lr11x0ResetAGC((LR11x0 *)_radio, ((CustomLR1110 *)_radio)->getFreqMHz()); }

From 91e65af9dd8514627b320f19a442100bafb868d7 Mon Sep 17 00:00:00 2001
From: taco <taco@sly.nu>
Date: Mon, 20 Jul 2026 20:28:38 +1000
Subject: [PATCH 19/29] fix: heltec t1: add missing bodmer TFT_eSPI library

---
 variants/heltec_t1/platformio.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/variants/heltec_t1/platformio.ini b/variants/heltec_t1/platformio.ini
index d5c3caf18..eaa8af378 100644
--- a/variants/heltec_t1/platformio.ini
+++ b/variants/heltec_t1/platformio.ini
@@ -23,7 +23,7 @@ build_src_filter = ${nrf52_base.build_src_filter}
 lib_deps =
   ${nrf52_base.lib_deps}
   ${sensor_base.lib_deps}
-  adafruit/Adafruit ST7735 and ST7789 Library @ ^1.11.0
+  bodmer/TFT_eSPI @ ^2.4.31
 debug_tool = jlink
 upload_protocol = nrfutil
 

From ab5c45f51612c268b7fa4dca423d5b3dab88df8e Mon Sep 17 00:00:00 2001
From: taco <taco@sly.nu>
Date: Mon, 20 Jul 2026 21:05:12 +1000
Subject: [PATCH 20/29] fix: clear the correct IRQ flag for timeout on preamble
 detected

---
 src/helpers/radiolib/CustomSX1262.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/helpers/radiolib/CustomSX1262.h b/src/helpers/radiolib/CustomSX1262.h
index 103f51672..15efed5ca 100644
--- a/src/helpers/radiolib/CustomSX1262.h
+++ b/src/helpers/radiolib/CustomSX1262.h
@@ -125,7 +125,7 @@ class CustomSX1262 : public SX1262 {
       if (preamble) {
         if (_activityAt == 0) _activityAt = now;
         if (now - _activityAt > _preambleMillis) {
-          clearIrqStatus(RADIOLIB_IRQ_PREAMBLE_DETECTED);
+          clearIrqFlags(RADIOLIB_SX126X_IRQ_PREAMBLE_DETECTED);
           _activityAt = 0;
           MESH_DEBUG_PRINTLN("Clearing preamble IRQ after %ums", _preambleMillis);
 

From d2bbe4d8d3629f1d44b27b8af0264799ce54c63e Mon Sep 17 00:00:00 2001
From: entr0p1 <1475255+entr0p1@users.noreply.github.com>
Date: Mon, 20 Jul 2026 22:43:25 +1000
Subject: [PATCH 21/29] Fix Xiao nRF52840 repeater compile failure

Compile fails due to user_btn not declared in board target.

Fixes:
- Add MomentaryButton declaration for user_btn in variants/xiao_nrf52/target.cpp
- Add momentary button helper include in variants/xiao_nrf52/target.h
- Add extern linkage for MomentaryButton -> user_btn in variants/xiao_nrf52/target.h
---
 variants/xiao_nrf52/XiaoNrf52Board.h | 2 +-
 variants/xiao_nrf52/target.cpp       | 1 +
 variants/xiao_nrf52/target.h         | 2 ++
 3 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/variants/xiao_nrf52/XiaoNrf52Board.h b/variants/xiao_nrf52/XiaoNrf52Board.h
index b2638a440..e71e7f651 100644
--- a/variants/xiao_nrf52/XiaoNrf52Board.h
+++ b/variants/xiao_nrf52/XiaoNrf52Board.h
@@ -47,7 +47,7 @@ public:
 
 #ifdef PIN_USER_BTN
     // configure button press to wake up when in powered off state
-    nrf_gpio_cfg_sense_input(digitalPinToInterrupt(g_ADigitalPinMap[PIN_USER_BTN]), NRF_GPIO_PIN_NOPULL, NRF_GPIO_PIN_SENSE_LOW);
+    nrf_gpio_cfg_sense_input(digitalPinToInterrupt(g_ADigitalPinMap[PIN_USER_BTN]), NRF_GPIO_PIN_PULLUP, NRF_GPIO_PIN_SENSE_LOW);
 #endif
 
     NRF52Board::powerOff();
diff --git a/variants/xiao_nrf52/target.cpp b/variants/xiao_nrf52/target.cpp
index ab6fe279a..def1dbbea 100644
--- a/variants/xiao_nrf52/target.cpp
+++ b/variants/xiao_nrf52/target.cpp
@@ -4,6 +4,7 @@
 
 #ifdef DISPLAY_CLASS
   DISPLAY_CLASS display;
+  MomentaryButton user_btn(PIN_USER_BTN, 1000, true, true);
 #endif
 
 XiaoNrf52Board board;
diff --git a/variants/xiao_nrf52/target.h b/variants/xiao_nrf52/target.h
index bb3d2a81f..20093904a 100644
--- a/variants/xiao_nrf52/target.h
+++ b/variants/xiao_nrf52/target.h
@@ -11,7 +11,9 @@
 
 #ifdef DISPLAY_CLASS
   #include <helpers/ui/NullDisplayDriver.h>
+  #include <helpers/ui/MomentaryButton.h>
   extern DISPLAY_CLASS display;
+  extern MomentaryButton user_btn;
 #endif
 
 extern XiaoNrf52Board board;

From 3885c67c8eaf46ce66e28252338df783ca178a95 Mon Sep 17 00:00:00 2001
From: Alexander Hoffer <contact@alexanderhoffer.com>
Date: Mon, 20 Jul 2026 15:47:03 +0100
Subject: [PATCH 22/29] fix: synchronize BLE receive queue

---
 src/helpers/BoundedQueue.h                    | 39 +++++++++++++
 src/helpers/esp32/SerialBLEInterface.cpp      | 41 ++++++++-----
 src/helpers/esp32/SerialBLEInterface.h        | 10 ++--
 .../test_bounded_queue/test_bounded_queue.cpp | 58 +++++++++++++++++++
 4 files changed, 129 insertions(+), 19 deletions(-)
 create mode 100644 src/helpers/BoundedQueue.h
 create mode 100644 test/test_bounded_queue/test_bounded_queue.cpp

diff --git a/src/helpers/BoundedQueue.h b/src/helpers/BoundedQueue.h
new file mode 100644
index 000000000..07ecb4fff
--- /dev/null
+++ b/src/helpers/BoundedQueue.h
@@ -0,0 +1,39 @@
+#pragma once
+
+#include <stddef.h>
+
+namespace mesh {
+
+template <typename T, size_t Capacity>
+class BoundedQueue {
+  static_assert(Capacity > 0, "BoundedQueue capacity must be greater than zero");
+
+  T _items[Capacity];
+  size_t _head = 0;
+  size_t _size = 0;
+
+public:
+  bool push(const T& item) {
+    if (_size == Capacity) return false;
+    _items[(_head + _size) % Capacity] = item;
+    _size++;
+    return true;
+  }
+
+  bool pop(T& item) {
+    if (_size == 0) return false;
+    item = _items[_head];
+    _head = (_head + 1) % Capacity;
+    _size--;
+    return true;
+  }
+
+  void clear() {
+    _head = 0;
+    _size = 0;
+  }
+
+  size_t size() const { return _size; }
+};
+
+}  // namespace mesh
diff --git a/src/helpers/esp32/SerialBLEInterface.cpp b/src/helpers/esp32/SerialBLEInterface.cpp
index dcfa0e1e3..9c81dc7bc 100644
--- a/src/helpers/esp32/SerialBLEInterface.cpp
+++ b/src/helpers/esp32/SerialBLEInterface.cpp
@@ -118,17 +118,30 @@ void SerialBLEInterface::onWrite(BLECharacteristic* pCharacteristic, esp_ble_gat
 
   if (len > MAX_FRAME_SIZE) {
     BLE_DEBUG_PRINTLN("ERROR: onWrite(), frame too big, len=%d", len);
-  } else if (recv_queue_len >= FRAME_QUEUE_SIZE) {
-    BLE_DEBUG_PRINTLN("ERROR: onWrite(), recv_queue is full!");
   } else {
-    recv_queue[recv_queue_len].len = len;
-    memcpy(recv_queue[recv_queue_len].buf, rxValue, len);
-    recv_queue_len++;
+    Frame frame = {};
+    frame.len = len;
+    memcpy(frame.buf, rxValue, len);
+
+    portENTER_CRITICAL(&recv_queue_mux);
+    bool queued = recv_queue.push(frame);
+    portEXIT_CRITICAL(&recv_queue_mux);
+
+    if (!queued) {
+      BLE_DEBUG_PRINTLN("ERROR: onWrite(), recv_queue is full!");
+    }
   }
 }
 
 // ---------- public methods
 
+void SerialBLEInterface::clearBuffers() {
+  portENTER_CRITICAL(&recv_queue_mux);
+  recv_queue.clear();
+  portEXIT_CRITICAL(&recv_queue_mux);
+  send_queue_len = 0;
+}
+
 void SerialBLEInterface::enable() { 
   if (_isEnabled) return;
 
@@ -202,17 +215,15 @@ size_t SerialBLEInterface::checkRecvFrame(uint8_t dest[]) {
     }
   }
 
-  if (recv_queue_len > 0) {   // check recv queue
-    size_t len = recv_queue[0].len;   // take from top of queue
-    memcpy(dest, recv_queue[0].buf, len);
+  Frame frame = {};
+  portENTER_CRITICAL(&recv_queue_mux);
+  bool received = recv_queue.pop(frame);
+  portEXIT_CRITICAL(&recv_queue_mux);
 
-    BLE_DEBUG_PRINTLN("readBytes: sz=%d, hdr=%d", len, (uint32_t) dest[0]);
-
-    recv_queue_len--;
-    for (int i = 0; i < recv_queue_len; i++) {   // delete top item from queue
-      recv_queue[i] = recv_queue[i + 1];
-    }
-    return len;
+  if (received) {
+    memcpy(dest, frame.buf, frame.len);
+    BLE_DEBUG_PRINTLN("readBytes: sz=%d, hdr=%d", (uint32_t) frame.len, (uint32_t) dest[0]);
+    return frame.len;
   }
 
   if (pServer->getConnectedCount() == 0)  deviceConnected = false;
diff --git a/src/helpers/esp32/SerialBLEInterface.h b/src/helpers/esp32/SerialBLEInterface.h
index 965e90fd1..e2d600a0e 100644
--- a/src/helpers/esp32/SerialBLEInterface.h
+++ b/src/helpers/esp32/SerialBLEInterface.h
@@ -1,10 +1,12 @@
 #pragma once
 
 #include "../BaseSerialInterface.h"
+#include "../BoundedQueue.h"
 #include <BLEDevice.h>
 #include <BLEServer.h>
 #include <BLEUtils.h>
 #include <BLE2902.h>
+#include <freertos/FreeRTOS.h>
 
 class SerialBLEInterface : public BaseSerialInterface, BLESecurityCallbacks, BLEServerCallbacks, BLECharacteristicCallbacks {
   BLEServer *pServer;
@@ -24,12 +26,12 @@ class SerialBLEInterface : public BaseSerialInterface, BLESecurityCallbacks, BLE
   };
 
   #define FRAME_QUEUE_SIZE  4
-  int recv_queue_len;
-  Frame recv_queue[FRAME_QUEUE_SIZE];
+  portMUX_TYPE recv_queue_mux = portMUX_INITIALIZER_UNLOCKED;
+  mesh::BoundedQueue<Frame, FRAME_QUEUE_SIZE> recv_queue;
   int send_queue_len;
   Frame send_queue[FRAME_QUEUE_SIZE];
 
-  void clearBuffers() { recv_queue_len = 0; send_queue_len = 0; }
+  void clearBuffers();
 
 protected:
   // BLESecurityCallbacks methods
@@ -58,7 +60,7 @@ public:
     _isEnabled = false;
     _last_write = 0;
     last_conn_id = 0;
-    send_queue_len = recv_queue_len = 0;
+    send_queue_len = 0;
   }
 
   /**
diff --git a/test/test_bounded_queue/test_bounded_queue.cpp b/test/test_bounded_queue/test_bounded_queue.cpp
new file mode 100644
index 000000000..3e2e2de7f
--- /dev/null
+++ b/test/test_bounded_queue/test_bounded_queue.cpp
@@ -0,0 +1,58 @@
+#include <gtest/gtest.h>
+
+#include <helpers/BoundedQueue.h>
+
+TEST(BoundedQueue, PreservesOrderAcrossWraparound) {
+  mesh::BoundedQueue<int, 4> queue;
+  int value = 0;
+
+  for (int i = 0; i < 4; i++) EXPECT_TRUE(queue.push(i));
+  EXPECT_FALSE(queue.push(4));
+
+  EXPECT_TRUE(queue.pop(value));
+  EXPECT_EQ(0, value);
+  EXPECT_TRUE(queue.pop(value));
+  EXPECT_EQ(1, value);
+
+  EXPECT_TRUE(queue.push(4));
+  EXPECT_TRUE(queue.push(5));
+
+  for (int expected = 2; expected < 6; expected++) {
+    EXPECT_TRUE(queue.pop(value));
+    EXPECT_EQ(expected, value);
+  }
+  EXPECT_FALSE(queue.pop(value));
+}
+
+TEST(BoundedQueue, SurvivesRepeatedFillAndDrainCycles) {
+  mesh::BoundedQueue<int, 4> queue;
+  int value = 0;
+
+  for (int cycle = 0; cycle < 1000; cycle++) {
+    for (int i = 0; i < 4; i++) EXPECT_TRUE(queue.push(cycle * 4 + i));
+    for (int i = 0; i < 4; i++) {
+      EXPECT_TRUE(queue.pop(value));
+      EXPECT_EQ(cycle * 4 + i, value);
+    }
+  }
+}
+
+TEST(BoundedQueue, ClearDropsPendingItems) {
+  mesh::BoundedQueue<int, 4> queue;
+  int value = 0;
+
+  EXPECT_TRUE(queue.push(1));
+  EXPECT_TRUE(queue.push(2));
+  queue.clear();
+
+  EXPECT_EQ(0u, queue.size());
+  EXPECT_FALSE(queue.pop(value));
+  EXPECT_TRUE(queue.push(3));
+  EXPECT_TRUE(queue.pop(value));
+  EXPECT_EQ(3, value);
+}
+
+int main(int argc, char **argv) {
+  ::testing::InitGoogleTest(&argc, argv);
+  return RUN_ALL_TESTS();
+}

From 60030469c93c592bddb5f1a4123717484a7db857 Mon Sep 17 00:00:00 2001
From: Alexander Hoffer <contact@alexanderhoffer.com>
Date: Mon, 20 Jul 2026 15:47:03 +0100
Subject: [PATCH 23/29] fix: enable Heltec V4 USB serial

---
 boards/heltec_v4.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/boards/heltec_v4.json b/boards/heltec_v4.json
index 36cdfc043..0d3a52cd0 100644
--- a/boards/heltec_v4.json
+++ b/boards/heltec_v4.json
@@ -9,7 +9,7 @@
     "extra_flags": [
       "-DBOARD_HAS_PSRAM",
       "-DARDUINO_USB_CDC_ON_BOOT=1",
-      "-DARDUINO_USB_MODE=0",
+      "-DARDUINO_USB_MODE=1",
       "-DARDUINO_RUNNING_CORE=1",
       "-DARDUINO_EVENT_RUNNING_CORE=1"
     ],
@@ -40,4 +40,4 @@
   },
   "url": "https://heltec.org/",
   "vendor": "heltec"
-}
\ No newline at end of file
+}

From 9fd6b419e5d134811e1775e7e3d129df9b83f12f Mon Sep 17 00:00:00 2001
From: Alexander Hoffer <contact@alexanderhoffer.com>
Date: Mon, 20 Jul 2026 15:47:03 +0100
Subject: [PATCH 24/29] fix: preserve bonded BLE reconnects

---
 src/helpers/esp32/SerialBLEInterface.cpp | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/helpers/esp32/SerialBLEInterface.cpp b/src/helpers/esp32/SerialBLEInterface.cpp
index dcfa0e1e3..c1c046021 100644
--- a/src/helpers/esp32/SerialBLEInterface.cpp
+++ b/src/helpers/esp32/SerialBLEInterface.cpp
@@ -103,10 +103,9 @@ void SerialBLEInterface::onMtuChanged(BLEServer* pServer, esp_ble_gatts_cb_param
 
 void SerialBLEInterface::onDisconnect(BLEServer* pServer) {
   BLE_DEBUG_PRINTLN("onDisconnect()");
+  deviceConnected = false;
   if (_isEnabled) {
     adv_restart_time = millis() + ADVERT_RESTART_DELAY;
-
-    // loop() will detect this on next loop, and set deviceConnected to false
   }
 }
 
@@ -215,8 +214,6 @@ size_t SerialBLEInterface::checkRecvFrame(uint8_t dest[]) {
     return len;
   }
 
-  if (pServer->getConnectedCount() == 0)  deviceConnected = false;
-
   if (deviceConnected != oldDeviceConnected) {
     if (!deviceConnected) {    // disconnecting
       clearBuffers();

From 0de2b4fc5f208489a8523882f050ead033ed3d8b Mon Sep 17 00:00:00 2001
From: =UltimateCodeWarrior <shanechambers@earthlink.net>
Date: Mon, 20 Jul 2026 19:24:38 -0700
Subject: [PATCH 25/29] Move Supreme OLED address to variant config

Keep SH1106Display generic by relying on DISPLAY_ADDRESS while the T-Beam Supreme variant declares its 0x3D OLED address.
---
 src/helpers/ui/SH1106Display.cpp                  | 15 ++++-----------
 .../lilygo_tbeam_supreme_SX1262/platformio.ini    |  1 +
 2 files changed, 5 insertions(+), 11 deletions(-)

diff --git a/src/helpers/ui/SH1106Display.cpp b/src/helpers/ui/SH1106Display.cpp
index 86c6089bc..57ccfc2e4 100644
--- a/src/helpers/ui/SH1106Display.cpp
+++ b/src/helpers/ui/SH1106Display.cpp
@@ -11,17 +11,10 @@ bool SH1106Display::i2c_probe(TwoWire &wire, uint8_t addr)
 
 bool SH1106Display::begin()
 {
-  // Address selection: on some board revisions (notably the LilyGo T-Beam
-  // Supreme V3) the OLED lives at 0x3D because 0x3C is occupied by a
-  // magnetometer (QMC6310N). 0x3D is only ever used by the OLED, so prefer it
-  // when present, otherwise fall back to the standard 0x3C (DISPLAY_ADDRESS).
-  uint8_t addr = 0;
-  if (i2c_probe(Wire, 0x3D)) {
-    addr = 0x3D;
-  } else if (i2c_probe(Wire, DISPLAY_ADDRESS)) {
-    addr = DISPLAY_ADDRESS;
-  }
-  return addr && display.begin(addr, true);
+  // Wire must already be initialised by board.begin() before this is called.
+  // Boards with non-standard SH1106 addresses should define DISPLAY_ADDRESS
+  // in their variant/platformio configuration.
+  return i2c_probe(Wire, DISPLAY_ADDRESS) && display.begin(DISPLAY_ADDRESS, true);
 }
 
 void SH1106Display::turnOn()
diff --git a/variants/lilygo_tbeam_supreme_SX1262/platformio.ini b/variants/lilygo_tbeam_supreme_SX1262/platformio.ini
index 029461565..8bfc4093a 100644
--- a/variants/lilygo_tbeam_supreme_SX1262/platformio.ini
+++ b/variants/lilygo_tbeam_supreme_SX1262/platformio.ini
@@ -18,6 +18,7 @@ build_flags =
   -D RADIO_CLASS=CustomSX1262
   -D WRAPPER_CLASS=CustomSX1262Wrapper
   -D DISPLAY_CLASS=SH1106Display
+  -D DISPLAY_ADDRESS=0x3D
   -D LORA_TX_POWER=22
   -D P_LORA_TX_LED=6
   -D PIN_BOARD_SDA=17

From 4d4d7c37467ce2ad2255f70e53ea40624834393a Mon Sep 17 00:00:00 2001
From: Alexander Hoffer <contact@alexanderhoffer.com>
Date: Tue, 21 Jul 2026 07:17:01 +0100
Subject: [PATCH 26/29] refactor: use FreeRTOS BLE receive queue

---
 src/helpers/BoundedQueue.h                    | 39 -------------
 src/helpers/esp32/SerialBLEInterface.cpp      | 16 +----
 src/helpers/esp32/SerialBLEInterface.h        | 10 +++-
 .../test_bounded_queue/test_bounded_queue.cpp | 58 -------------------
 4 files changed, 10 insertions(+), 113 deletions(-)
 delete mode 100644 src/helpers/BoundedQueue.h
 delete mode 100644 test/test_bounded_queue/test_bounded_queue.cpp

diff --git a/src/helpers/BoundedQueue.h b/src/helpers/BoundedQueue.h
deleted file mode 100644
index 07ecb4fff..000000000
--- a/src/helpers/BoundedQueue.h
+++ /dev/null
@@ -1,39 +0,0 @@
-#pragma once
-
-#include <stddef.h>
-
-namespace mesh {
-
-template <typename T, size_t Capacity>
-class BoundedQueue {
-  static_assert(Capacity > 0, "BoundedQueue capacity must be greater than zero");
-
-  T _items[Capacity];
-  size_t _head = 0;
-  size_t _size = 0;
-
-public:
-  bool push(const T& item) {
-    if (_size == Capacity) return false;
-    _items[(_head + _size) % Capacity] = item;
-    _size++;
-    return true;
-  }
-
-  bool pop(T& item) {
-    if (_size == 0) return false;
-    item = _items[_head];
-    _head = (_head + 1) % Capacity;
-    _size--;
-    return true;
-  }
-
-  void clear() {
-    _head = 0;
-    _size = 0;
-  }
-
-  size_t size() const { return _size; }
-};
-
-}  // namespace mesh
diff --git a/src/helpers/esp32/SerialBLEInterface.cpp b/src/helpers/esp32/SerialBLEInterface.cpp
index 9c81dc7bc..2dd20b2ff 100644
--- a/src/helpers/esp32/SerialBLEInterface.cpp
+++ b/src/helpers/esp32/SerialBLEInterface.cpp
@@ -123,11 +123,7 @@ void SerialBLEInterface::onWrite(BLECharacteristic* pCharacteristic, esp_ble_gat
     frame.len = len;
     memcpy(frame.buf, rxValue, len);
 
-    portENTER_CRITICAL(&recv_queue_mux);
-    bool queued = recv_queue.push(frame);
-    portEXIT_CRITICAL(&recv_queue_mux);
-
-    if (!queued) {
+    if (xQueueSend(recv_queue, &frame, 0) != pdTRUE) {
       BLE_DEBUG_PRINTLN("ERROR: onWrite(), recv_queue is full!");
     }
   }
@@ -136,9 +132,7 @@ void SerialBLEInterface::onWrite(BLECharacteristic* pCharacteristic, esp_ble_gat
 // ---------- public methods
 
 void SerialBLEInterface::clearBuffers() {
-  portENTER_CRITICAL(&recv_queue_mux);
-  recv_queue.clear();
-  portEXIT_CRITICAL(&recv_queue_mux);
+  xQueueReset(recv_queue);
   send_queue_len = 0;
 }
 
@@ -216,11 +210,7 @@ size_t SerialBLEInterface::checkRecvFrame(uint8_t dest[]) {
   }
 
   Frame frame = {};
-  portENTER_CRITICAL(&recv_queue_mux);
-  bool received = recv_queue.pop(frame);
-  portEXIT_CRITICAL(&recv_queue_mux);
-
-  if (received) {
+  if (xQueueReceive(recv_queue, &frame, 0) == pdTRUE) {
     memcpy(dest, frame.buf, frame.len);
     BLE_DEBUG_PRINTLN("readBytes: sz=%d, hdr=%d", (uint32_t) frame.len, (uint32_t) dest[0]);
     return frame.len;
diff --git a/src/helpers/esp32/SerialBLEInterface.h b/src/helpers/esp32/SerialBLEInterface.h
index e2d600a0e..9fb6adba9 100644
--- a/src/helpers/esp32/SerialBLEInterface.h
+++ b/src/helpers/esp32/SerialBLEInterface.h
@@ -1,12 +1,12 @@
 #pragma once
 
 #include "../BaseSerialInterface.h"
-#include "../BoundedQueue.h"
 #include <BLEDevice.h>
 #include <BLEServer.h>
 #include <BLEUtils.h>
 #include <BLE2902.h>
 #include <freertos/FreeRTOS.h>
+#include <freertos/queue.h>
 
 class SerialBLEInterface : public BaseSerialInterface, BLESecurityCallbacks, BLEServerCallbacks, BLECharacteristicCallbacks {
   BLEServer *pServer;
@@ -26,8 +26,9 @@ class SerialBLEInterface : public BaseSerialInterface, BLESecurityCallbacks, BLE
   };
 
   #define FRAME_QUEUE_SIZE  4
-  portMUX_TYPE recv_queue_mux = portMUX_INITIALIZER_UNLOCKED;
-  mesh::BoundedQueue<Frame, FRAME_QUEUE_SIZE> recv_queue;
+  StaticQueue_t recv_queue_state;
+  uint8_t recv_queue_storage[FRAME_QUEUE_SIZE * sizeof(Frame)];
+  QueueHandle_t recv_queue;
   int send_queue_len;
   Frame send_queue[FRAME_QUEUE_SIZE];
 
@@ -60,6 +61,9 @@ public:
     _isEnabled = false;
     _last_write = 0;
     last_conn_id = 0;
+    recv_queue = xQueueCreateStatic(
+      FRAME_QUEUE_SIZE, sizeof(Frame), recv_queue_storage, &recv_queue_state
+    );
     send_queue_len = 0;
   }
 
diff --git a/test/test_bounded_queue/test_bounded_queue.cpp b/test/test_bounded_queue/test_bounded_queue.cpp
deleted file mode 100644
index 3e2e2de7f..000000000
--- a/test/test_bounded_queue/test_bounded_queue.cpp
+++ /dev/null
@@ -1,58 +0,0 @@
-#include <gtest/gtest.h>
-
-#include <helpers/BoundedQueue.h>
-
-TEST(BoundedQueue, PreservesOrderAcrossWraparound) {
-  mesh::BoundedQueue<int, 4> queue;
-  int value = 0;
-
-  for (int i = 0; i < 4; i++) EXPECT_TRUE(queue.push(i));
-  EXPECT_FALSE(queue.push(4));
-
-  EXPECT_TRUE(queue.pop(value));
-  EXPECT_EQ(0, value);
-  EXPECT_TRUE(queue.pop(value));
-  EXPECT_EQ(1, value);
-
-  EXPECT_TRUE(queue.push(4));
-  EXPECT_TRUE(queue.push(5));
-
-  for (int expected = 2; expected < 6; expected++) {
-    EXPECT_TRUE(queue.pop(value));
-    EXPECT_EQ(expected, value);
-  }
-  EXPECT_FALSE(queue.pop(value));
-}
-
-TEST(BoundedQueue, SurvivesRepeatedFillAndDrainCycles) {
-  mesh::BoundedQueue<int, 4> queue;
-  int value = 0;
-
-  for (int cycle = 0; cycle < 1000; cycle++) {
-    for (int i = 0; i < 4; i++) EXPECT_TRUE(queue.push(cycle * 4 + i));
-    for (int i = 0; i < 4; i++) {
-      EXPECT_TRUE(queue.pop(value));
-      EXPECT_EQ(cycle * 4 + i, value);
-    }
-  }
-}
-
-TEST(BoundedQueue, ClearDropsPendingItems) {
-  mesh::BoundedQueue<int, 4> queue;
-  int value = 0;
-
-  EXPECT_TRUE(queue.push(1));
-  EXPECT_TRUE(queue.push(2));
-  queue.clear();
-
-  EXPECT_EQ(0u, queue.size());
-  EXPECT_FALSE(queue.pop(value));
-  EXPECT_TRUE(queue.push(3));
-  EXPECT_TRUE(queue.pop(value));
-  EXPECT_EQ(3, value);
-}
-
-int main(int argc, char **argv) {
-  ::testing::InitGoogleTest(&argc, argv);
-  return RUN_ALL_TESTS();
-}

From 78240e9477feab86b2ea1d24073ca580f9e59415 Mon Sep 17 00:00:00 2001
From: Scott Powell <ripple_biz@protonmail.com>
Date: Tue, 21 Jul 2026 19:22:09 +1000
Subject: [PATCH 27/29] * optimised: value-init not needed

---
 src/helpers/esp32/SerialBLEInterface.cpp | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/helpers/esp32/SerialBLEInterface.cpp b/src/helpers/esp32/SerialBLEInterface.cpp
index 7084b7d9e..6371cf335 100644
--- a/src/helpers/esp32/SerialBLEInterface.cpp
+++ b/src/helpers/esp32/SerialBLEInterface.cpp
@@ -208,7 +208,7 @@ size_t SerialBLEInterface::checkRecvFrame(uint8_t dest[]) {
     }
   }
 
-  Frame frame = {};
+  Frame frame;
   if (xQueueReceive(recv_queue, &frame, 0) == pdTRUE) {
     memcpy(dest, frame.buf, frame.len);
     BLE_DEBUG_PRINTLN("readBytes: sz=%d, hdr=%d", (uint32_t) frame.len, (uint32_t) dest[0]);

From a71cc238546e36c5c31c196eb4ec0cf528746017 Mon Sep 17 00:00:00 2001
From: agessaman <adam@gessaman.com>
Date: Tue, 21 Jul 2026 12:23:20 -0700
Subject: [PATCH 28/29] fix(room_server): support RX boosted gain

The room server never supported RX boosted gain, while the repeater
does. Three consequences on SX1262/SX1268 boards:

- boosted gain was never applied to the radio at boot, so a room server
  ran in power-saving RX mode while an identical repeater ran boosted -
  a real receive-sensitivity difference with nothing pointing at it
- _prefs.rx_boosted_gain was never initialised (the prefs are memset to
  0 before defaults are set), so it defaulted to off
- 'set radio.rxgain on' replied "Error: unsupported" but CommonCLI had
  already written the value to prefs and saved them, so a stale setting
  survived reboot and was never applied

Mirror the repeater's implementation: initialise the pref default under
the same USE_SX1262/USE_SX1268 and SX126X_RX_BOOSTED_GAIN guards, apply
it during radio init, and override setRxBoostedGain() so the CLI reports
success and takes effect.

Built Heltec_v3_room_server (SX1262) and LilyGo_T3S3_sx1276_room_server
(guards compile out cleanly).
---
 examples/simple_room_server/MyMesh.cpp | 13 +++++++++++++
 examples/simple_room_server/MyMesh.h   |  1 +
 2 files changed, 14 insertions(+)

diff --git a/examples/simple_room_server/MyMesh.cpp b/examples/simple_room_server/MyMesh.cpp
index 36978e808..b64851285 100644
--- a/examples/simple_room_server/MyMesh.cpp
+++ b/examples/simple_room_server/MyMesh.cpp
@@ -658,6 +658,14 @@ MyMesh::MyMesh(mesh::MainBoard &board, mesh::Radio &radio, mesh::MillisecondCloc
   _prefs.gps_enabled = 0;
   _prefs.gps_interval = 0;
   _prefs.advert_loc_policy = ADVERT_LOC_PREFS;
+
+#if defined(USE_SX1262) || defined(USE_SX1268)
+#ifdef SX126X_RX_BOOSTED_GAIN
+  _prefs.rx_boosted_gain = SX126X_RX_BOOSTED_GAIN;
+#else
+  _prefs.rx_boosted_gain = 1; // enabled by default;
+#endif
+#endif
   _prefs.radio_fem_rxgain = 1;
 
   next_post_idx = 0;
@@ -700,6 +708,7 @@ void MyMesh::begin(FILESYSTEM *fs) {
 
   radio_driver.setParams(_prefs.freq, _prefs.bw, _prefs.sf, _prefs.cr);
   radio_driver.setTxPower(_prefs.tx_power_dbm);
+  radio_driver.setRxBoostedGainMode(_prefs.rx_boosted_gain);
   board.setLoRaFemLnaEnabled(_prefs.radio_fem_rxgain);
 
   updateAdvertTimer();
@@ -807,6 +816,10 @@ void MyMesh::setTxPower(int8_t power_dbm) {
   radio_driver.setTxPower(power_dbm);
 }
 
+bool MyMesh::setRxBoostedGain(bool enable) {
+  return radio_driver.setRxBoostedGainMode(enable);
+}
+
 void MyMesh::saveIdentity(const mesh::LocalIdentity &new_id) {
 #if defined(NRF52_PLATFORM) || defined(STM32_PLATFORM)
   IdentityStore store(*_fs, "");
diff --git a/examples/simple_room_server/MyMesh.h b/examples/simple_room_server/MyMesh.h
index 6bab9dc2d..caef69209 100644
--- a/examples/simple_room_server/MyMesh.h
+++ b/examples/simple_room_server/MyMesh.h
@@ -206,6 +206,7 @@ public:
 
   void dumpLogFile() override;
   void setTxPower(int8_t power_dbm) override;
+  bool setRxBoostedGain(bool enable) override;
 
   void formatNeighborsReply(char *reply) override {
     strcpy(reply, "not supported");

From 520fa77f4fedfe0d39eb0c472f7c7346f470df82 Mon Sep 17 00:00:00 2001
From: liamcottle <liam@liamcottle.com>
Date: Fri, 24 Jul 2026 15:31:01 +1200
Subject: [PATCH 29/29] increase tbeam sx1276 max group channels from 8 to 40

---
 variants/lilygo_tbeam_SX1276/platformio.ini | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/variants/lilygo_tbeam_SX1276/platformio.ini b/variants/lilygo_tbeam_SX1276/platformio.ini
index cb25903ce..f5f490479 100644
--- a/variants/lilygo_tbeam_SX1276/platformio.ini
+++ b/variants/lilygo_tbeam_SX1276/platformio.ini
@@ -45,7 +45,7 @@ build_flags =
   ${LilyGo_TBeam_SX1276.build_flags}
   -I examples/companion_radio/ui-new
   -D MAX_CONTACTS=160
-  -D MAX_GROUP_CHANNELS=8
+  -D MAX_GROUP_CHANNELS=40
   -D BLE_PIN_CODE=123456
 ;  -D BLE_DEBUG_LOGGING=1
   -D OFFLINE_QUEUE_SIZE=128