Skip to content

Old AGC reset and new receive refresh

The new periodic method briefly sleeps and wakes the radio, then resumes reception. The old method also runs radio calibration. Both keep the existing agc command name for compatibility. Neither is a crystal frequency-trim adjustment or an MCU reboot.

What changes on Heltec V4 / SX126x

Old full receiver reset New receive refresh
Sequence Warm sleep, RC standby, Calibrate(0x7F), image calibration for the operating frequency, restore RX settings, resume RX. Stage same-channel duty-cycle RX, allow a natural sleep/wake cycle, stop duty cycling and verify continuous RX reentry.
Calibration Recalibrates the radio's internal blocks, including ADC, PLL and image rejection. Restores configured RF-switch/gain settings and applicable register patch. Does not request full or image calibration or change the configured frequency or gain.
Noise-floor estimate The independent legacy reset requests fresh samples, retaining the previously valid estimate while collecting. Keeps the estimate and collection state; applies the normal RSSI settling delay after RX reentry.
Execution Synchronous command sequence, including a 5 ms delay and bounded BUSY polling. The legacy helper continues after command errors. Asynchronous: the main loop advances the operation, checks results and preserves packet ownership. Failed or unconfirmed cycles receive no success credit.
Current control Saved agc.old auto: included after a successful primary refresh at intervals of 240 seconds or longer, where supported. off: disabled. A positive value: independent timer instead. Primary saved agc / agc.reset.interval timer on supported builds.

The sleep/wake cycle affects the radio's receiver circuitry and oscillator; it is more than restarting only the crystal. Receive refresh describes what the new code verifies. Calling it an AGC reset does not establish that the internal automatic gain-control state was reset or that sensitivity improved. See the Semtech SX1261/2 datasheet, sections 9.3 and 13.1.7 for the underlying sleep and duty-cycle modes.

The old method remains available for comparison and existing recovery paths. Its "full reset" name refers to the receiver maintenance sequence above, not asserting the radio's hardware reset pin. Hard radio recovery is separate.

Every board using the SX1262 driver now enables AGC lockup protection and retains it through sleep, without requiring a board flag. This covers ordinary RXPS and the new receive refresh, including when radio.rxps is off. Runtime gain changes and old AGC resets preserve the retention list too. The Ebyte custom initializer applies the same checked protection. This implements upstream PR #3824 together with the sleep-retention fix. SX1268, LLCC68, STM32WL, LR1110 and LR2021 do not receive SX1262-specific register writes. See the V4 sleep-retention hardware results. The T1000-E and W12 sleep checks record observations for those separate radio families.

Automatic selection

With the saved default agc.old auto, the primary interval selects the method on receive-refresh builds:

  • 0: primary maintenance off.
  • Below 240 seconds: new primary receive refresh, without the scheduled old-reset half.
  • 240 seconds (4 minutes) or longer: new receive refresh, followed by the old full receiver reset when that implementation is available in the build.

For example, set agc 236 uses the new method; set agc 240 uses both on V4. The cutoff uses the configured interval, not time spent waiting for an idle radio. A late or deferred short-interval refresh does not enable that scheduled old half.

The cutoff controls the optional old-reset policy, not calibration needed for recovery. Restoring an LR2021 PRAM scanner after a primary sleep/wake may require a cold radio reset and full base/frontend calibration even below 240 seconds. That calibration belongs to primary restoration; it does not satisfy the automatic old half at 240 seconds or longer. W12 hardware testing verified three short primary refreshes and both halves of a real 240-second cycle, including a separate old-helper increment after primary cold restoration.

The combined operation first requires a witnessed refresh and checked RX reentry. Its old-reset half then waits for an idle primary visit, without repeating the pulse or interrupting a packet. Changing or disabling the interval discards an outstanding completion. The next interval starts after both halves complete. Most legacy helpers report admission rather than checked success of every calibration command; the LR2021 periodic path checks command and restore results. Failed or unconfirmed pulses do not trigger the automatic old reset.

LR2021 also supports the old-reset policy. Its checked native sequence uses RC standby, Calibrate(0x6F) and forced frontend calibration at the actual programmed frequency and all enabled profile frequencies. Ordinary single-profile and native RXPS operation include retained sleep/wake. A known-resident PRAM/LDO scanner session omits that sleep/wake step while still performing full calibration in checked RC standby. The scanner is warm-paused and its restart must be verified. A resident image must not be rewritten while active; an actual hard reset invalidates its loaded marker. Descriptor words alone do not verify a working scanner. The wrapper restores modem, protocol, power, gain and receive mode, including multi-SF or RXPS. Noise-floor refresh stays queued for the next host sampling window while PRAM owns reception. A busy receiver or pending packet defers the operation; failed calibration/restoration gets no success credit and waits the normal reset interval before another attempt. Device faults remain visible through the existing LR2021 radio-apply diagnostics.

The command mask, frontend frequency encoding and retained-sleep behavior follow Semtech's LR20xx driver.

This LR2021 implementation has host command/fault/ownership tests and build checks. The W12 hardware test passed single-profile legacy calibration (12/12 RF), native RXPS (12/12 incoming, 1/1 outgoing), single-profile multi-SF (8/8), and nine quiet dual-profile/multi-SF calibrations followed by 18/18 RF probes with maintenance disabled. The final candidate also completed three independent old calibrations, three short primary cold-restoration cycles and a real four-minute primary-plus-old cycle, with verified scanner return and no reported failure or unplanned recovery. Its four old-helper calls took 26.301-26.357 ms, excluding scanner pause/rehook. A concurrent-traffic scanner handoff limitation remains unresolved; these tests do not establish sensitivity, RF downtime or lossless traffic handling. Builds that omit legacy support with MESH_ENABLE_OLD_AGC=0, including the default compact STM32 builds, retain the new method alone. Drivers without receive-refresh support keep their existing method.

Settings

Read the current settings before changing them:

get agc
get agc.old
get agc.status

Use the new primary method every 16 seconds, with the independent old timer off:

set agc.old 0
set agc 16

For an old-method-only comparison at the same 16-second interval:

set agc 0
set agc.old 16

Both settings survive reboot. Restore the recorded values after a comparison. agc.old accepts these saved policies:

  • set agc.old auto: default; add the old reset after a successful primary refresh when agc is at least 240 seconds. No independent old timer.
  • set agc.old off or set agc.old 0: disable the old timer and the automatic old half, including when agc is 240 seconds or longer. Recovery watchdogs remain independent of these periodic-maintenance controls.
  • set agc.old 1 through set agc.old 86400: run an independent old timer at that interval in seconds, replacing the automatic old half. The primary timer continues using the new method on its own schedule.

For only the old reset every 4 seconds, including after reboot:

set agc 0
set agc.old 4

For only the new method every four minutes:

set agc.old off
set agc 240

New configurations default to a 16-second primary interval. Existing saved primary values survive upgrades. Primary intervals use four-second steps; device powersaving can extend the actual interval adaptively. The independent old timer has no adaptive backoff. Compact builds can omit old-reset support and return Error: unsupported.

The old policy is saved separately from existing application preferences. A missing record uses auto; an unreadable or corrupt record disables old resets for that boot. A failed save reports an error and attempts to restore the previous runtime setting; it does not claim the setting survived reboot.

Active duty-cycle radio.rxps suspends the primary timer because the radio is already sleeping and waking. Continuous-RX fallback still permits maintenance. This suspension includes the automatic combined operation. The independent old timer is not automatically suspended. With radio2 enabled, the new method waits for an idle primary visit and temporarily extends that visit; packets on the secondary profile can be missed during that time.

For full ranges, diagnostics and scheduling details, see AGC CLI settings. get agc.status and the pulse timing counters describe the receive-refresh half; they do not measure the subsequent full calibration.

Timing and V4 test evidence

The V4's default compensated sleep request is 3116 microseconds with a 1600-microsecond TCXO startup allowance. This encodes 33 sleep-timer ticks after transition compensation. It is not the duration of the whole operation or a measured RF outage.

In the November 5 V4 test, sampled BUSY-high spans were 3.041-3.082 ms. Whole operations took about 126-128 ms, including about 120 ms of initial RX listening. Listening time is not dead time. Timing depends on radio settings and packet activity. Those measurements cover the new refresh alone, not the combined operation. The four-minute selection rule is covered by host regression tests for the boundary, ownership deferrals, configuration changes and unsupported backends; it has not been timed on hardware as a combined sequence.

The tests verified natural wakes, RTC cleanup, RX reentry and subsequent packet reception. They did not measure internal AGC state, calibrated sensitivity, or battery savings. The uncontrolled antenna comparison did not establish the cause of the reported V4 sensitivity/noise-floor difference or prove this refresh fixes it. Displayed noise-floor differences alone did not predict which receiver decoded more packets.

Other radio families

Supported SX126x, LR1110, LR1121 and LR2021 drivers use their chip's duty-cycle mechanism. SX1276 instead uses a checked, host-timed sleep/wake sequence. The old reset's exact calibration sequence is driver-specific; the table above describes SX126x. Other drivers retain their existing maintenance behavior. Building with MESH_WARM_RX_REFRESH=0 selects the previous primary method; it is not a runtime CLI setting.

Implementation: SX126x legacy reset, SX126x receive refresh, shared scheduling and recovery.