[sx126x] Heltec WiFi LoRa 32 V4: board support + external FEM PA power above 22 dBm

[cn-schuh]

Component name

sx126x + heltec v4

Link to component documentation on our website

https://esphome.io/components/sx126x/

Describe the enhancement

Two related improvements for the sx126x component, both motivated by the
Heltec WiFi LoRa 32 V4 (ESP32-S3 + SX1262):

─── 1. External FEM support for TX power above 22 dBm ───────────────────

The Heltec V4 places an external RF Front-End Module (FEM) between the
SX1262 output and the antenna, giving the board its advertised 28 ± 1 dBm
transmit power. The SX1262 chip itself is hard-limited to 22 dBm by the
Semtech datasheet, so pa_power: 22 in ESPHome only drives the chip — the
FEM contribution is invisible to the driver.

Today: pa_power accepts -3 to 22 dBm, which is correct for the chip but
does not reflect the real ERP on boards with an external amplifier.

Proposed additions to sx126x:

fem_power_offset: 6 # dBm gain added by external FEM (informational,
# used for logging and sensor reporting only)

fem_enable_pin: GPIOX # optional: pulled HIGH during TX to explicitly
# enable boards whose FEM is not self-activating

For boards where the FEM is activated automatically via rf_switch / DIO2
(as on the Heltec V4), fem_enable_pin would not be required.
fem_power_offset alone would allow ESPHome to log and report the correct
effective radiated power without changing the TX path.

For reference, Heltec's own Arduino driver handles this via a
board-specific polynomial remapping of the user dBm value onto the
SX1262 SetTxParams register value, combined with implicit FEM enable.

Regulatory note: for EU 868 MHz the legal ERP ceiling is 14 dBm
(ETSI EN 300 220). pa_power would remain the chip-level control and the
sole value that affects actual transmission. fem_power_offset is metadata
only — the user stays responsible for regional compliance, as today.

─── 2. Board definition for Heltec WiFi LoRa 32 V4 ─────────────────────

There is no heltec_wifi_lora_32_V4 board identifier in ESPHome. Users
currently fall back to heltec_wifi_lora_32_V3 (pin-compatible) or the
generic esp32-s3-devkitc-1, both of which use incorrect flash/partition
settings for the V4.

The V4 ships with 2 MB PSRAM and 16 MB Flash vs. the V3's 8 MB Flash —
this difference affects OTA partition layout and available flash. A
dedicated board entry would resolve silent mismatches.

Correct pin mapping for reference (identical to V3):
SPI: CLK=GPIO9, MOSI=GPIO10, MISO=GPIO11
sx126x: CS=GPIO8, RST=GPIO12, DIO1=GPIO14, BUSY=GPIO13
I2C OLED: SDA=GPIO17, SCL=GPIO18, RST=GPIO21
TCXO: 1.8 V, 5 ms delay
rf_switch: true

Use cases

I run a two-node peer-to-peer LoRa telemetry link using ESPHome's
packet_transport over sx126x on Heltec WiFi LoRa 32 V4 hardware.
The V4's higher hardware TX power is essential for reliable link margin
over a ~300 m urban path with building obstructions.

Current workaround: board: heltec_wifi_lora_32_V3 with pa_power: 14
(EU legal limit). This works functionally, but:

• Flash layout is wrong for the V4's 16 MB chip.
• There is no way to log or verify the actual ERP including the FEM's
  contribution.
• Users in regions with higher legal TX limits (e.g. 27 dBm EIRP in
  some non-EU bands) have no path to use the full hardware capability
  from within ESPHome.

Alternatives tried and their shortcomings:

• board: esp32-s3-devkitc-1 → compiles, but wrong flash size and no
  Heltec boot config.
• board: heltec_wifi_lora_32_V3 → pins correct, flash layout wrong.
• Heltec Arduino library → FEM and 28 dBm work correctly, confirming
  the hardware is capable; the gap is purely in the ESPHome driver.

Anything else?

Heltec V4 product page (specs, pinout, schematic download):
https://heltec.org/project/wifi-lora-32-v4/

Heltec V4 datasheet PDF (pin table, RF characteristics, schematic):
https://resource.heltec.cn/download/WiFi_LoRa_32_V4/datasheet/WiFi_LoRa_32_V4.2.0.pdf

Semtech SX1262 datasheet (SetTxParams, PA config, 22 dBm chip max):
https://cdn.sparkfun.com/assets/6/b/5/1/4/SX1262_datasheet.pdf

Heltec community thread — "How to get 28 dBm on V4" (FEM + power remap):
http://community.heltec.cn/t/how-to-get-28dbm-on-the-module-heltec-esp32-v4/22101

ESPHome devices entry for Heltec V3 (closest existing reference config):
https://devices.esphome.io/devices/heltec-wifi-lora-32-v3/

Original sx126x component PR by @swoboda1337 (merged ESPHome 2025.7):
esphome/esphome#8516

I am willing to provide a tested YAML config and verified pin mapping
from a real V4 unit, and can contribute a PR for the board definition
if that is the preferred starting point.