sx127x: add an option to fix the LNA gain (turn off AGC)

[Jeremy Pack (scriptengine)]

Component name

sx127x

Link to component documentation on our website

https://esphome.io/components/sx127x/

Describe the enhancement

Background

I humbly request that an option is added to the sx127x (radio) component that allows the
gain to be set to a specific value rather than "Automatic Gain Control" (AGC).
Basically the radio I want to receive is close and powerful but only transmits intermittently
and typically the AGC sets its gain from weak signals when it starts and keeps that setting and the
station I want to listen to never gets decoded.

I have working code that I could offer in a PR, but I'm way out of my depth here. The code
was developed by an AI (Claude Code), and I know the Home Assistant and I suspect the ESPHome
projects are (rightly) sensitive to AI contributions that have not been human-reviewed, and I could not
walk anyone through the code line by line.

In summary, I'm either asking a dev to develop this on their own, or I can offer my working code
changes in PR form (tested in my environment), which I'm asking someone else with more knowledge
than myself to review and if appropriate submit into ESPHome.

How can I best contribute this change within the limits of my ability?

Summary

The sx127x component always switches on the radio's AGC. With a strong transmitter close by,
in FSK mode, the AGC regularly picks maximum gain, overloading the receiver, so nothing is
decoded. Fixing the gain solved it completely. I'd like to propose an optional lna_gain:
setting so this can be done in YAML. The default would keep today's behaviour.

Proposal

A new optional setting:

sx127x:
  # ...
  lna_gain: G5   # AUTO (default) | G1 | G2 | G3 | G4 | G5 | G6

• AUTO (the default) is the current behaviour, with AGC on, so existing configs don't change.
• G1–G6 turns AGC off and writes that gain to RegLna during configure().
• In FSK mode the AGC is the AgcAutoOn bit in RegRxConfig. In LoRa mode it is the equivalent
  bit in RegModemConfig3, which the component already sets.
• LNA boost (RegLna bits 1-0) could be a separate option later. I didn't need it.

The change looks small:

• a register constant and an enum;
• a few lines in configure();
• the schema and codegen in __init__.py;
• a docs paragraph.

What I can offer

• The working code changes, tested on the hardware described below.
• Testing any proposed implementation on that hardware, with before/after frame counts.
• The full test data behind the tables below.

Questions for maintainers:

• Is lna_gain with AUTO / G1…G6 the right shape and naming?
• Should it apply to LoRa mode as well as FSK?

The problem

Setup:

• LILYGO T3 V1.6.1 (ESP32 + SX1276).
• ESPHome 2026.9.0.
• sx127x in FSK continuous mode, with data on DIO2 into remote_receiver.
• Receiving a Bresser 6-in-1 weather station (868.3 MHz, ~8.2 kbps, one frame every 12 s).
• The station is about 8 m away and strong (~-45 dBm).

The SX1276's AGC chooses the LNA gain once, when reception starts, from whatever signal
triggers it. That is usually background noise, so it picks G1 (maximum gain). The station's
strong signal then overloads the receiver, and the demodulated data is garbage. In my tests:

• every trial where the AGC chose G1 decoded nothing (44 of 44);
• every trial that worked had the AGC at G3–G5 by chance (9 of 9).

Several things that looked like the cause did not fix it: frequency offset, AFC, bandwidth,
packet mode and the RSSI threshold (rx_floor).

Evidence: fixed-gain sweep

AGC off, LNA gain fixed at each step (RegLna 0x0C bits 7-5), tested in two positions about
20 cm apart. The second position is indoors behind glass, with a noisier RF floor.

LNA gain	Outside: frames per 3-min trial (15 possible)	Inside: frames decoded / possible
G1 (max)	0	0 / 105
G2	0–1	0 / 105
G3	9–13 (marginal)	0 / 90
G4	15	59 / 90 (89 / 90 with AFC on)
G5	15	90 / 90
G6 (min)	15	90 / 90
AGC on (current behaviour)	0	0 / 90

With G5, AGC off and AFC on (my other settings unchanged):

• about 300 frames an hour, which is effectively every transmission;
• that held over soaks of 22 h and 91 h;
• reception now works reliably from boot.

BTW as an aside, apparently RegRssiValue is not gain-compensated. With a fixed gain, the
reported RSSI steps with the gain setting (about -103 dBm at G1 to -61 dBm at G6).

Current workaround

To get this I copied the sx127x component locally and made read_register_ /
write_register_ public. A YAML script then clears AgcAutoOn (RegRxConfig 0x0D bit 3) and
sets RegLna, with a 60-second check that re-applies it if anything resets the radio. This
works, but it means maintaining a forked copy of the component and re-checking it on every
ESPHome release.

The bigger goal, though, is to make this option available to the community.

Use cases

To receive data from a specific station that only works at a specific gain. (My example is a near by weather station that transmits infrequently, and the AGC is locking onto more frequent weaker transmisssions)

Anything else?

No response

[github-actions[bot]]

🏷️ I've automatically added the component: sx127x label to help categorize this feature request.