Skip to content

Offband offband-v1.2.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 21 Jul 06:48
offband-v1.2.0
1e73bd2

Adds MeshSmith Photon‑1W support (both MCU flavors) on the MeshCore 1.16.0 base, and receive-sensitivity recovery on Heltec V4 (external FEM LNA control, which stock MeshCore leaves bypassed),
plus the ESP32‑C6 I2C‑scan boot‑hang fix found bench‑validating it, a NimBLE build fix,
and flashing‑docs corrections.

Added

  • MeshSmith Photon‑1W support — ESP32‑C6 + nRF52 (#193, #194) — vendors MeshSmith's MIT Photon
    variants (meshsmith_photon_esp32c6, meshsmith_photon_nrf52; Seeed XIAO ESP32‑C6 / XIAO nRF52840 +
    Ebyte E22‑900M30S 1W radio) and wires all roles into CI + the release pipeline. ESP32‑C6 needed
    minimal MeshCore‑consistent base edits (antenna‑switch virtuals, protected _gps_serial, NimBLE dep);
    nRF52 needed none. The ESP32‑C6 companion + repeater are bench‑verified on hardware; the
    nRF52 variant is not yet bench‑verified — review findings tracked as bench checkpoints on #193/#194.
  • External FEM LNA control on Heltec V4 companions (#298). MeshCore leaves the Heltec V4
    front-end module's LNA bypassed at boot, so V4 companions ran with degraded receive
    sensitivity. Offband now enables it at companion boot from a persisted radio_fem_rxgain
    preference (default on), on the boards whose FEM exposes an independent LNA line
    (heltec_v4, heltec_tracker_v2, heltec_t096). A new companion-API command (0xC3,
    SET/GET) plus a capability bit lets the client show a user toggle, gated on the
    runtime-detected FEM chip. FIRMWARE_VER_CODE 15 -> 16. Verified end-to-end on a
    KCT8103L (V4.3) board.
  • Model string names the detected FEM part (#327) — reads Heltec V4 OLED (KCT8103L)
    or (GC1109), so a V4.3 (independent LNA control) is distinguishable from a V4.2 in the app.

Fixed

  • Photon‑1W ESP32‑C6 hung at boot, dead on the mesh (#294). The C6 variant declares its I2C bus,
    but EnvironmentSensorManager::begin() ran the blind I2C scan regardless; on the C6 the scan wedges
    the I2C peripheral (hangs at addr 0x0d) and never returns, so setup() never reached loop().
    The scan is now skipped on boards that set ENV_SKIP_I2C_SENSOR_SCAN (guard vendored verbatim from
    MeshSmith's fork); every other board is unchanged.
  • CLI accepted garbage after a valid key (#299). get radio foobar returned the radio
    settings, and set radio 910.525,62.5,7,5,junk silently applied the first four values and
    dropped the rest. Keys now require a whole-token match; extra set radio parameters are rejected.
  • 64 ESP32 BLE companion environments could not build (#199, #90). The NimBLE dependency was
    declared per-variant with no shared source, and the greedy source filter pulled the BLE
    interface into non-BLE (usb/wifi) builds too. Factored into a shared config; restores
    boards silently absent from prior releases, including Heltec_v2_companion_radio_usb and
    Xiao_C3_companion_radio_usb. A CI invariant now guards every ESP32 env. (The #89 fix below
    is the first, single-env instance of this class.)
  • FEM auto-detect source comment corrected (#318, #321). The Heltec V4 FEM type is set by a
    board strap, not chip-internal pulls as the code claimed; documented against schematics + the
    GC1109 datasheet. A boot detection probe is available behind -D FEM_DEBUG_PROBE (off by default).
  • pio-flash identified devices by USB port-path, not identity (#336, #323). Boards were
    misidentified after any USB port or device swap, and a no-discriminator registry entry
    wildcard-matched its whole chip family. Now keys on the device-unique USB serial and refuses
    ambiguous matches; hardware-verified across colliding same-VID:PID boards. Bench tooling, not
    shipped firmware.
  • pio-flash bootstrap parses the ESP32-C6/H2 base MAC and anchors its MAC regexes (#290, #292).
    Bench tooling.
  • Xiao_S3_WIO_companion_radio_usb build (#89) — exclude SerialBLEInterface.cpp from the USB
    companion env (it has no BLE), resolving the NimBLEDevice.h regression from the #288 NimBLE migration.
  • Flashing docs pointed at the wrong page and omitted a release file (#326). The
    README's web-flasher link went to meshcore.co.uk/flasher.html — a wrapper page that
    forwards to a configurator, not the flasher. It now points at
    flasher.meshcore.io. The per-release download table
    (README + .github/release-footer.md) also never listed the nRF52 *.zip DFU package —
    40 of the 130 assets in a release — so it now has a row, pointing at serial DFU tooling
    while steering most users to the simpler *.uf2. Both tables described the merged image as a web-flasher "Full Firmware"
    option; that is the device-catalog flow, and an Offband user takes the Custom Firmware
    flow instead, where the flasher auto-detects the -merged.bin suffix and prompts before
    erasing. Corrected, and both surfaces gained a short "how do I flash it" section covering
    the nRF52 UF2 drag-drop path, the ESP32 web-flasher path, and building from source.
    Documentation only — no firmware change.

Changed

  • CLAUDE.md: no‑upstream‑merge policy (#197) — Offband does not merge from upstream MeshCore; the
    upstream remote stays fetch‑only for reference. Keep MeshCore nomenclature/coding‑standard consistency
    for clean rebasing.

Documentation

  • Heltec V4 FEM/LNA ground-truth from schematics, the GC1109 datasheet, and on-device
    measurement, including V4.2-vs-V4.3 RX-path differences (#320, #321).
  • Repeater WiFi-telemetry genericization design-of-record (#296, design only).
  • Block-user companion-API contract reconciled to as-built (#313, #315).

Which file do I download?

File What it is When to use it
*-merged.bin (ESP32 — Heltec V3/V4, XIAO) Full image — bootloader + partition table + app in one, flashed at 0x0 after a chip erase. Self-contained, works on a blank chip. First install / clean setup.
*.bin (ESP32) App only — flashed at the app offset (0x10000); the bootloader must already be on the chip. Updating an existing node — OTA. Keeps the device identity + WiFi/MQTT config.
*.uf2 (nRF52 — RAK, T-Echo, XIAO nRF52) Complete self-contained image. First install and updates — double-tap reset, then drag-drop onto the USB drive. (nRF52 has no merged/app split.)
*.zip (nRF52) Adafruit DFU package — the same image as the *.uf2, DFU-wrapped. Serial DFU tooling (adafruit-nrfutil). Most people want the *.uf2 instead.

⚠️ ESP32: the app-only *.bin will not boot if flashed at 0x0 — use *-merged.bin for a fresh install. A full erase wipes the device's identity + saved config, so use it only for a first install or recovery, never a routine update.

How do I flash it?

  • nRF52 — double-tap reset; the board mounts as a USB drive; drag the *.uf2 onto it. No tools needed.
  • ESP32 — MeshCore web flasher → Custom Firmware, which takes a file straight off your disk. Chromium-based browser required (Web Serial). It detects the -merged.bin suffix and warns before erasing — expected on a first install.
  • From source — pio run -e <env> -t upload.

What's Changed

  • chore(#278): per-session identity hooks (AM-valid derive) by @Strycher in #279
  • chore(#280): per-session identity hooks (ruff-clean hooks #212) by @Strycher in #281
  • fix(#290): parse ESP32-C6/H2 base MAC in pio-flash bootstrap by @Strycher in #291
  • chore(#292): line-anchor pio-flash MAC regexes to match canonical by @Strycher in #293
  • docs(#313): reconcile block contract doc to as-built by @Strycher in #314
  • docs(#315): drop ephemeral agent codename from block contract by @Strycher in #316
  • docs(#296): design-of-record — genericize repeater WiFi telemetry for third-party deployment by @Strycher in #309
  • docs(#321): Heltec V4 FEM/LNA verified ground truth vs manufacturer sources by @Strycher in #322
  • fix(#199, #90): correct all 64 ESP32 envs that compile SerialBLEInterface.cpp by @Strycher in #328
  • feat(#298): apply FEM LNA on all FEM-capable boards + 0xC3 client control surface by @Strycher in #329
  • fix(#299): whole-token match for CLI get keys + reject extra set radio params by @Strycher in #330
  • fix(#318): correct FEM detect comment + land CSD probe behind FEM_DEBUG_PROBE by @Strycher in #332
  • docs(#326): point community flashing at flasher.meshcore.io, document the nRF52 .zip by @Strycher in #333
  • fix(#336): identify devices by USB serial, not Windows port-path by @Strycher in #337
  • task(#327): report the FEM part in the model string; audit GPIO46 strapping by @Strycher in #335
  • Photon-1W ESP32-C6/nRF52 firmware support + C6 I2C-scan boot-hang fix (#294) by @Strycher in #342
  • chore: Offband 1.2.0 release content (CHANGELOG + Discord) by @Strycher in #344
  • chore(#345): date CHANGELOG [1.2.0] for stable release by @Strycher in #346

Full Changelog: offband-v1.1.2...offband-v1.2.0

Contributors

Strycher
Assets 164
Loading