# T1 band-bridge — integration notes

`band_bridge.h/.cpp` + `radio_abstraction.h/.cpp` add last-hop cross-band
relay capability to a T1 sensor. This document describes the minimal
`main.cpp` + `platformio.ini` edits needed to enable it, **without**
modifying the files themselves (the other concurrent agent owns those).

## platformio.ini

Add a new build env derived from `env:heltec_wifi_lora_v4`:

```ini
[env:heltec_wifi_lora_v4_uav_bridge]
extends = env:heltec_wifi_lora_v4
build_flags =
    ${env:heltec_wifi_lora_v4.build_flags}
    -DPDL_ENABLE_UAV_RELAY
    -DPDL_ENABLE_BAND_BRIDGE
    -DPDL_RADIO_LORA_915
    -DPDL_RADIO_CC1101_433
```

Optional per-hardware radios (enable only the daughterboards present on
your sensor):

```
    -DPDL_RADIO_NRF24        # nRF24L01+ on spare SPI
    -DPDL_RADIO_ESP32_C5     # ESP32-C5 companion over UART
```

The `PDL_ENABLE_BAND_BRIDGE` macro is required — without it, the whole
module compiles to no-op stubs (zero flash cost).

## main.cpp — setup() addition

```cpp
#include "band_bridge.h"
#include "radio_abstraction.h"

// ... after mesh_init(s_lora_spi) succeeds:
radio_abstraction_init();

// Pull the HMAC key from the same place uav_relay does (provided at pair
// time; here we start with a null key for dev-mode test build):
band_bridge_init(nullptr, 0);
```

## main.cpp — LoRa RX switch-statement addition

Extend the existing switch in the RX path with one new case:

```cpp
case MSG_TYPE_BAND_BRIDGE:               // 0x0F — NEW
    band_bridge_handle_route_delivery(rx_buf, rx_len, rx_band_from_header);
    break;
```

`rx_band_from_header` is sourced from the mesh_routing layer the other
agent owns: the route-termination record on a band-bridge leaf carries
a `target_band` byte that this sensor hands through. If the other
agent exposes a helper like `mesh_routing_target_band(rx_buf)`, use it
here; otherwise fall back to a compile-time default:

```cpp
BandId dst = BandId::CC1101_433;   // hard-coded at build time
band_bridge_handle_route_delivery(rx_buf, rx_len, dst);
```

## Compile-out behavior

When `PDL_ENABLE_BAND_BRIDGE` is undefined:
- Every public entry point returns `NOT_ENABLED` / false.
- `band_bridge.cpp` still compiles (all code is under `#else` stubs).
- `radio_abstraction.cpp` always builds (the abstraction is useful even
  without the bridge — uav_relay could in principle pick its TX band
  through the same table).

## Memory footprint (Heltec V4, PSRAM = 8 MB)

- band_bridge.o: ~3.5 KB .text, ~64 B .bss
- radio_abstraction.o: ~1.8 KB .text, ~108 B .bss (duty counters)

Well within the 4 MB model budget + 1 MB OTA + remainder heap.

## Flow summary

```
  (915 MHz LoRa mesh)
       │
       ▼
+-------------------+         mesh_routing (owned by other agent)
|  mesh_receive()   |  ───►   dispatches MSG_TYPE_BAND_BRIDGE to us
+-------------------+
       │
       ▼
+-----------------------------+
| band_bridge_handle_route_   |  verify HMAC, check duty budget
| delivery(frame, len, band)  |
+-----------------------------+
       │
       ▼                    (via radio_tx on dst_band)
+-----------------------------+
|  radio_abstraction          |  ───► CC1101 / nRF24 / ESP32-C5
+-----------------------------+
       │
       ▼ (optional ACK wait up to 500 ms)
       │
       ▼
+-----------------------------+
|  mesh_publish_raw           |  ───► MESH_ACK back to originator on 915
+-----------------------------+
```
