sx126x: add cold sleep support to set_mode_sleep action

[joaopedros2]

Describe the enhancement

Feature Request

Summary

The sx126x.set_mode_sleep action currently sends a warm sleep command
(sleepConfig = 0x04, RTC active), which keeps the SX1262 consuming ~600µA.
For battery-powered nodes that use ESP32 deep sleep, this makes the radio the
dominant power consumer during sleep — completely defeating the purpose of
deep sleep.

Cold sleep (sleepConfig = 0x00, no RTC, no config retained) brings the
SX1262 down to ~0.6µA, a 1000× improvement.

Proposed API

- sx126x.set_mode_sleep:
    cold: true   # sleepConfig=0x00 (~0.6µA), default false = current behaviour

Or equivalently expose the raw byte for full flexibility:

- sx126x.set_mode_sleep:
    sleep_config: 0x00

Datasheet reference

SX1262 datasheet section 13.1.2 — SetSleep command:

sleepConfig	Meaning	Current (typ)
0x04	Warm sleep — RTC active, config retained	~600 µA
0x00	Cold sleep — no RTC, no config retained	~0.6 µA

Use case

Battery-powered LoRa sender node:

1. ESP32-S3 wakes from deep sleep
2. Reads sensors
3. Transmits one LoRa packet via SX1262
4. Puts SX1262 into cold sleep (~0.6µA)
5. ESP32-S3 enters deep sleep

Without cold sleep, the SX1262 alone consumes ~600µA during the entire
deep sleep period, making sub-mA operation impossible.

Current workaround

Users are forced to bit-bang the SPI bus manually after set_mode_standby,
which is fragile and requires direct GPIO manipulation inside a lambda:

- sx126x.set_mode_standby
- delay: 2ms
- lambda: |-
    gpio_set_direction(GPIO_NUM_9,  GPIO_MODE_OUTPUT);
    gpio_set_direction(GPIO_NUM_10, GPIO_MODE_OUTPUT);
    gpio_set_direction(GPIO_NUM_8,  GPIO_MODE_OUTPUT);
    gpio_set_direction(GPIO_NUM_13, GPIO_MODE_INPUT);
    gpio_set_level(GPIO_NUM_8, 1);
    // ... wait BUSY low, bit-bang 0x84 0x00, etc.

This should not be necessary for something as fundamental as low-power sleep.

Implementation notes

The change is minimal — in sx126x.cpp, the set_mode_sleep handler
sends RADIO_SET_SLEEP with a hardcoded sleepConfig byte. Adding a boolean
cold parameter (defaulting to false for backwards compatibility) and
passing 0x00 vs 0x04 accordingly is a one-line logic change, plus
schema additions in __init__.py.

Hardware tested

• Heltec WiFi LoRa 32 V3 (ESP32-S3 + SX1262)
• ESPHome 2026.4.x

Use cases

Battery-powered LoRa sensor nodes that wake, transmit one packet, and return
to deep sleep. Without cold sleep the SX1262 alone consumes ~600µA during
the entire sleep period, making sub-mA operation impossible regardless of
ESP32 deep sleep configuration.

Visual examples

No response

Anything else?

https://github.com/jgromes/RadioLib/blob/master/src/modules/SX126x/SX126x.h
https://github.com/jgromes/RadioLib/blob/master/src/modules/SX126x/SX126x.cpp

[swoboda1337]

esphome/esphome#16144

[joaopedros2]

Hi @swoboda1337 — great work on this PR, exactly what battery-powered nodes needed!

With sx126x.set_mode_sleep: cold: true now properly sending 0x00 before deep sleep, I'm wondering which parts of my pre-sleep cleanup lambda are still necessary.

Currently I'm doing this before deep_sleep.enter:

- lambda: |-
    // Free SPI bus
    spi_bus_free(SPI2_HOST);

    // Disable SX1262 GPIOs (DIO1, NSS, RESET, BUSY, CLK, MISO, MOSI)
    gpio_set_direction(GPIO_NUM_14, GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_8,  GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_12, GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_13, GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_9,  GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_11, GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_10, GPIO_MODE_DISABLE);

    // Disable OLED SSD1306 GPIOs
    gpio_set_direction(GPIO_NUM_17, GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_18, GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_21, GPIO_MODE_DISABLE);

    // Disable misc GPIOs (VEXT, LED, VBAT_CTRL, VBAT_ADC, soil sensor)
    gpio_set_direction(GPIO_NUM_36, GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_35, GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_37, GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_1,  GPIO_MODE_DISABLE);
    gpio_set_direction(GPIO_NUM_4,  GPIO_MODE_DISABLE);

    // Power domains
    esp_sleep_pd_config(ESP_PD_DOMAIN_XTAL,    ESP_PD_OPTION_OFF);
    esp_sleep_pd_config(ESP_PD_DOMAIN_RC_FAST, ESP_PD_OPTION_OFF);

My questions:

1. spi_bus_free(SPI2_HOST) — since cold: true already puts the SX1262 into 0x00 sleep via the ESPHome SPI driver, is freeing the SPI bus still needed or beneficial before deep sleep? Or does ESPHome / IDF handle this automatically?

2. SX1262 GPIO directions — with cold sleep active and the chip at ~0.6 µA, do the SPI/control pins (NSS, CLK, MOSI, MISO, BUSY, RESET, DIO1) need to be explicitly set to GPIO_MODE_DISABLE to avoid leakage through the ESP32-S3's internal pull-up/down resistors, or is that negligible?

3. Other peripheral GPIOs (OLED, VEXT, LED, soil sensor) — these are unrelated to the sx126x change, but while I have your attention: is GPIO_MODE_DISABLE the right approach, or is it better to drive them LOW as outputs before sleep to avoid floating inputs drawing current?

4. esp_sleep_pd_config for XTAL / RC_FAST — is this still worth doing explicitly, or does IDF deep sleep handle these automatically when no wakeup sources require them?

Hardware: Heltec WiFi LoRa 32 V3 (ESP32-S3 + SX1262).

My goal is to reach the <10 µA deep sleep figure that Heltec advertises in the V3 ( datasheet section 3.4 ).

Thanks!

[swoboda1337]

For SPI you should not have to do spi bus free and doubt you have to set the sx126x gpio directions. Not sure about the other stuff.

[joaopedros2]

Hi,

Following up on this discussion where I initially requested the sx126x.set_mode_sleep action — I've now implemented it and I'm running into a consistent issue.

---

Project context:

Deep sleep soil sensor node (ESP32-S3, SX1261) that wakes on timer, reads battery voltage (ADC) + soil temp/moisture (Modbus RTU over RS485) + internal temperature, sends one LoRa packet, and goes back to deep sleep. The entire active window is ~4–5 seconds.

Key radio config:

• Frequency: 433 MHz
• Modulation: LoRa SF12 / BW125 / CR 4/8
• PA power: -2 dBm
• TCXO: 1.8V, 5ms delay
• Payload: ~12 bytes

Pins: CS=GPIO8, BUSY=GPIO13, RST=GPIO12, DIO1=GPIO14

on_boot sequence:

1. Read sensors (script)
2. sx126x.send_packet with payload
3. sx126x.set_mode_sleep
4. deep_sleep.enter

---

What I'm seeing:

Immediately after sx126x.send_packet returns (payload is logged correctly), I get:

[E][sx126x:480]: Wait busy timeout
[E][component:284]: sx126x was marked as failed
[E][component:405]: sx126x set Error flag: unspecified
[E][sx126x:480]: Wait busy timeout
[E][component:284]: sx126x was marked as failed

Things I've tried:

• cold: true vs cold: false — same result
• delay: 2500ms between send_packet and set_mode_sleep — error still occurs at the same timestamp as the send

---

Questions:

1. Is this a known issue with send_packet followed by set_mode_sleep?
2. Is there a correct way to use these two actions together?

Happy to share full YAML or logs if helpful. Thanks!

[swoboda1337]

Yeah yaml would help

[joaopedros2]

Yeah yaml would help

substitutions:
  sector: 3

  battery_low_level_phase_1: 3.34
  battery_low_level_phase_2: 3.32
  battery_low_level_phase_3: 3.30
  battery_charging_delta: 0.05
  battery_charging_full_voltage: 4.2

  send_interval_normal: 1min
  send_interval_phase_1: 2min
  send_interval_phase_2: 3min

  battery_power_stabilize: 100ms
  sensor_power_stabilize: 3500ms
  soil_read_timeout: 6s
  reading_script_timeout: 12s

esphome:
  name: esp-kiwi-soil-sender
  friendly_name: "ESP Kiwi Soil - Sender"
  on_boot:
    #- priority: -100
      then:

        # 1. Pequena estabilizacao inicial apos boot
        - delay: 50ms

        # 2. Executa leitura de bateria, sensor de solo e temperatura interna
        - script.execute: reading

        # 3. Aguarda conclusao da leitura, mas nunca fica bloqueado indefinidamente
        - wait_until:
            timeout: ${reading_script_timeout}
            condition:
              not:
                script.is_running: reading

        # 4. Se a leitura ficou presa, para o script e corta alimentacao dos perifericos
        - if:
            condition:
              script.is_running: reading
            then:
              - script.stop: reading
              - output.turn_off: vext_control
              - output.turn_off: vbat_control
              - lambda: |-
                  ESP_LOGW("boot", "Reading script timeout; stopped script and powered off sensors");

        # 4. Envia pacote LoRa
        - sx126x.send_packet:
            data: !lambda |-
              uint8_t sector = ${sector};

              float battery_voltage_state = id(battery_voltage).state;
              float battery_percentage_state = id(battery_percentage).state;
              float device_temperature_state = id(device_temperature).state;
              float soil_temperature_state = id(soil_temperature).state;
              float soil_moisture_state = id(soil_moisture).state;

              bool battery_valid = !isnan(battery_voltage_state);
              bool battery_percentage_valid = !isnan(battery_percentage_state);
              bool device_temperature_valid = !isnan(device_temperature_state);
              bool soil_valid = !isnan(soil_temperature_state) && !isnan(soil_moisture_state);

              uint16_t batt_volt = battery_valid
                ? (uint16_t) roundf(battery_voltage_state * 100)
                : 0;

              uint8_t batt_pct = battery_percentage_valid
                ? (uint8_t) roundf(battery_percentage_state)
                : 255;

              int16_t dev_temp = device_temperature_valid
                ? (int16_t) roundf(device_temperature_state * 10)
                : 32767;

              int16_t soil_temp = soil_valid
                ? (int16_t) roundf(soil_temperature_state * 10)
                : 32767;

              uint8_t soil_mois = soil_valid
                ? (uint8_t) roundf(soil_moisture_state)
                : 255;

              uint8_t battery_ok = (
                battery_valid &&
                battery_voltage_state > ${battery_low_level_phase_1}
              ) ? 1 : 0;

              uint8_t battery_charging = (
                battery_valid &&
                (
                  battery_voltage_state > ${battery_charging_full_voltage} ||
                  (
                    id(previous_battery_voltage) >= 3.0f &&
                    id(previous_battery_voltage) <= 4.3f &&
                    battery_voltage_state - id(previous_battery_voltage) >= ${battery_charging_delta}
                  )
                )
              ) ? 1 : 0;

              if (battery_valid) {
                id(previous_battery_voltage) = battery_voltage_state;
              }

              std::vector<uint8_t> payload;

              // 1 byte: sector
              payload.push_back(sector);

              // 2 bytes: battery voltage x100
              payload.push_back((batt_volt >> 8) & 0xFF);
              payload.push_back(batt_volt & 0xFF);

              // 1 byte: battery percentage
              payload.push_back(batt_pct);

              // 2 bytes: device temperature x10
              payload.push_back((dev_temp >> 8) & 0xFF);
              payload.push_back(dev_temp & 0xFF);

              // 2 bytes: soil temperature x10
              payload.push_back((soil_temp >> 8) & 0xFF);
              payload.push_back(soil_temp & 0xFF);

              // 1 byte: soil moisture
              payload.push_back(soil_mois);

              // 1 byte: battery ok
              payload.push_back(battery_ok);

              // 1 byte: battery charging
              payload.push_back(battery_charging);

              ESP_LOGI(
                "lora_tx",
                "Sent: Sector=%d Volt=%.2fV Batt=%d%% DeviceTempRaw=%d SoilTempRaw=%d SoilMoist=%d SoilValid=%s BatteryState=%s Charging=%s",
                sector,
                batt_volt / 100.0,
                batt_pct,
                dev_temp,
                soil_temp,
                soil_mois,
                soil_valid ? "yes" : "no",
                battery_ok ? "ok" : "not_ok",
                battery_charging ? "yes" : "no"
              );

              return payload;

        # 6. Coloca radio LoRa em sleep
        - sx126x.set_mode_sleep:
            cold: true

        # 7. Pequena estabilizacao antes de dormir/desligar
        - delay: 100ms

        # 6. desabilita todos os GPIOs
        # - lambda: |-

        #     // === OLED SSD1306 ===
        #     gpio_set_direction(GPIO_NUM_17, GPIO_MODE_DISABLE);  // SDA
        #     gpio_set_direction(GPIO_NUM_18, GPIO_MODE_DISABLE);  // SCL
        #     gpio_set_direction(GPIO_NUM_21, GPIO_MODE_DISABLE);  // RST

        #     // === VEXT GPIO36 ===
        #     gpio_set_direction(GPIO_NUM_36, GPIO_MODE_DISABLE);

        #     // === LED GPIO35 ===
        #     gpio_set_direction(GPIO_NUM_35, GPIO_MODE_DISABLE);

        #     // === BATTERY ===
        #     gpio_set_direction(GPIO_NUM_37, GPIO_MODE_DISABLE);  // VBAT_CTRL
        #     gpio_set_direction(GPIO_NUM_1,  GPIO_MODE_DISABLE);  // VBAT_ADC

        #     // === SOIL SENSOR GPIO4 ===
        #     gpio_set_direction(GPIO_NUM_4, GPIO_MODE_DISABLE);

        #     // === POWER DOMAINS ===
        #     esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_OFF);
        #     esp_sleep_pd_config(ESP_PD_DOMAIN_XTAL,    ESP_PD_OPTION_OFF);
        #     esp_sleep_pd_config(ESP_PD_DOMAIN_RC_FAST, ESP_PD_OPTION_OFF);

        # 7. aguarda estabilizar
        #- delay: 50ms

        # 8. Decide shutdown ou deep sleep conforme nivel da bateria
        - if:
            condition:
              lambda: |-
                return !isnan(id(battery_voltage).state) &&
                      id(battery_voltage).state <= ${battery_low_level_phase_3};
            then:
              # 8.1. Bateria criticamente baixa: corta perifericos e desliga
              - output.turn_off: vext_control
              - output.turn_off: vbat_control
              - button.press: shutdown_button
            else:
              # 8.2. Corta perifericos antes de entrar em deep sleep
              - output.turn_off: vext_control
              - output.turn_off: vbat_control
              - delay: 50ms

              # 8.3. Escolhe intervalo de deep sleep conforme tensao da bateria
              - if:
                  condition:
                    lambda: |-
                      return !isnan(id(battery_voltage).state) &&
                            id(battery_voltage).state <= ${battery_low_level_phase_2};
                  then:
                    - deep_sleep.enter:
                        id: deep_sleep_1
                        sleep_duration: ${send_interval_phase_2}
                  else:
                    - if:
                        condition:
                          lambda: |-
                            return !isnan(id(battery_voltage).state) &&
                                  id(battery_voltage).state <= ${battery_low_level_phase_1};
                        then:
                          - deep_sleep.enter:
                              id: deep_sleep_1
                              sleep_duration: ${send_interval_phase_1}
                        else:
                          - deep_sleep.enter:
                              id: deep_sleep_1
                              sleep_duration: ${send_interval_normal}

esp32:
  variant: esp32s3
  flash_size: 8MB
  cpu_frequency: 80MHZ
  #cpu_frequency: 160MHZ
  #cpu_frequency: 240MHZ
  framework:
    type: esp-idf

logger:
  hardware_uart: UART0
  level: DEBUG
  logs:
    component: ERROR
    modbus: DEBUG
    modbus_controller: DEBUG

deep_sleep:
  id: deep_sleep_1

globals:
   # Tensao anterior da bateria, usada para estimar se esta a carregar
  - id: previous_battery_voltage
    type: float
    restore_value: yes
    initial_value: '0.0'

button:
  # Shutdown por software quando a bateria esta criticamente baixa
  - platform: shutdown
    id: shutdown_button

spi:
  clk_pin: GPIO9
  mosi_pin: GPIO10
  miso_pin: GPIO11

sx126x:
  # --- PINS / HARDWARE ---
  dio1_pin: GPIO14
  cs_pin: GPIO8
  busy_pin: GPIO13
  rst_pin: GPIO12
  hw_version: sx1262
  rf_switch: true

  # --- BASE CONFIG ---
  frequency: 433.0MHz
  modulation: LORA
  bandwidth: 125_0kHz
  crc_enable: true
  sync_value: [0x14, 0x24]
  preamble_size: 8
  rx_start: false

  # --- TCXO ---
  tcxo_voltage: 1_8V
  tcxo_delay: 5ms

  # --- TUNING PROFILES ---

  # Ultra eficiente (usar por defeito)
  #pa_power: 2
  #spreading_factor: 7
  #coding_rate: CR_4_5

  # Médio alcance (fallback)
  #pa_power: 5
  #spreading_factor: 8
  #coding_rate: CR_4_5

  # Longo alcance (emergência)
  pa_power: -2
  spreading_factor: 12
  coding_rate: CR_4_8

output:
  # Controlo do divisor/circuito de leitura da bateria
  - platform: gpio
    pin: 37
    id: vbat_control
    inverted: true
  # Alimentacao VEXT para sensor de solo / RS485
  - platform: gpio
    pin: 36
    id: vext_control
    inverted: false

  #- platform: gpio
    #pin: 5
    #id: rs485_control

uart:
  # UART ligada ao MAX485
  - id: rs485_uart
    tx_pin: 47                # MAX485 DI
    rx_pin: 48                # MAX485 RO
    baud_rate: 9600
    data_bits: 8
    parity: NONE
    stop_bits: 1

modbus:
  # Bus Modbus RTU via RS485
  - id: rs485_bus
    uart_id: rs485_uart
    flow_control_pin: 5       # MAX485 DE/RE
    send_wait_time: 1000ms

modbus_controller:
  # Sensor de solo no endereco Modbus 0x02
  - id: soil_sensor
    address: 0x02
    modbus_id: rs485_bus
    command_throttle: 1000ms
    update_interval: never

sensor:
# -------------------------------------------------------------------
# Battery Voltage
# -------------------------------------------------------------------
  - platform: adc
    pin: GPIO1
    id: battery_voltage
    attenuation: 2.5db #12db
    samples: 64
    sampling_mode: avg
    update_interval: never
    filters:
      #- round: 2
      - multiply: 5.1205 #5.2
      - round: 2
  # -----------------------------------------------------------------
  # Battery Percentage (Li-Ion OCV Curve)
  # -----------------------------------------------------------------
  - platform: copy
    id: battery_percentage
    source_id: battery_voltage
    unit_of_measurement: "%"
    filters:
      - calibrate_linear:
          - 3.10 -> 0
          - 3.30 -> 10
          - 3.42 -> 20
          - 3.53 -> 30
          - 3.63 -> 40
          - 3.72 -> 50
          - 3.80 -> 60
          - 3.89 -> 70
          - 3.99 -> 80
          - 4.05 -> 90
          - 4.19 -> 100
      - clamp:
          min_value: 0
          max_value: 100

  # Temperatura do solo via Modbus, em graus Celsius
  - platform: modbus_controller
    id: soil_temperature
    modbus_controller_id: soil_sensor
    register_type: holding
    address: 0x0000
    value_type: U_WORD
    filters:
      - multiply: 0.1

  # Humidade do solo via Modbus, em percentagem
  - platform: modbus_controller
    id: soil_moisture
    modbus_controller_id: soil_sensor
    register_type: holding
    address: 0x0001
    value_type: U_WORD
    filters:
      - multiply: 0.1
      - round: 0

  # Temperatura interna do ESP32
  - platform: internal_temperature
    id: device_temperature
    accuracy_decimals: 1
    update_interval: never

script:
  - id: reading
    mode: single
    then:
      # -----------------------------------------------------------------
      # BAT VOLT
      # -----------------------------------------------------------------
      # 1. Liga circuito de leitura da bateria
      - output.turn_on: vbat_control
      - delay: ${battery_power_stabilize}
      # 2. Atualiza leitura da bateria
      - component.update: battery_voltage
      - lambda: |-
          ESP_LOGI("reading", "Battery: %.3fV", id(battery_voltage).state);
      #- delay: 8s
      # 3. Desliga circuito de leitura da bateria
      - output.turn_off: vbat_control
      - delay: 50ms

      # -----------------------------------------------------------------
      # SOIL HUM TEMP
      # -----------------------------------------------------------------
      # 4. Liga alimentacao do sensor de solo / MAX485
      - output.turn_on: vext_control
      - delay: ${sensor_power_stabilize}
      # 5. Limpa valores anteriores para nao aceitar leituras antigas
      - lambda: |-
          id(soil_temperature).publish_state(NAN);
          id(soil_moisture).publish_state(NAN);
      # 6. Pede leitura Modbus
      - component.update: soil_sensor
      # 7. Aguarda resposta Modbus com timeout
      - wait_until:
          timeout: ${soil_read_timeout}
          condition:
            lambda: |-
              return !isnan(id(soil_moisture).state) &&
                     !isnan(id(soil_temperature).state);
      # 8. Regista se a leitura foi valida ou falhou
      - if:
          condition:
            lambda: |-
              return !isnan(id(soil_moisture).state) &&
                     !isnan(id(soil_temperature).state);
          then:
            - lambda: |-
                ESP_LOGI("reading", "Soil Moisture: %.1f%%", id(soil_moisture).state);
                ESP_LOGI("reading", "Soil Temperature: %.1fC", id(soil_temperature).state);
          else:
            - lambda: |-
                ESP_LOGW("reading", "Soil sensor timeout or invalid Modbus reading");

      # 9. Desliga alimentacao do sensor/MAX485 mesmo em caso de falha
      - output.turn_off: vext_control

      # -----------------------------------------------------------------
      # DEV TEMP
      # -----------------------------------------------------------------
      # 10. Atualiza temperatura interna do ESP32
      - delay: 50ms
      - component.update: device_temperature
      - lambda: |-
          ESP_LOGI("reading", "Device Temperature: %.1fC", id(device_temperature).state);

[swoboda1337]

Can you try with esphome/esphome#16546

[joaopedros2]

Confirmed fixed with the external component from PR #16546. Log is clean, no more busy timeout errors. Thanks for the quick turnaround!