SX126x Component

The SX126x component allows you to configure the SX1261, SX1262, SX1268 and LLCC68 transceivers (datasheet) in ESPHome. Transceivers are connected via the SPI Bus. Supported frequencies range from 150 MHz to 960 MHz. Supported modulations include LoRa, FSK, GFSK, MSK and GMSK. The SX126x component may be used as a platform for the Packet Transport Component component, enabling sensor data to be sent directly from one ESPHome node to another.

# Example configuration entry
sx126x:
  dio1_pin: GPIO14
  cs_pin: GPIO8
  busy_pin: GPIO13
  rst_pin: GPIO12
  pa_power: 3
  bandwidth: 125_0kHz
  crc_enable: true
  frequency: 433920000
  modulation: LORA
  hw_version: sx1262
  rf_switch: true
  sync_value: [0x14, 0x24]
  preamble_size: 8
  spreading_factor: 7
  coding_rate: CR_4_6
  tcxo_voltage: 1_8V
  tcxo_delay: 5ms

Configuration variables

busy_pin (Required, Pin Schema): Busy pin.
cs_pin (Required, Pin Schema): SPI chip select pin.
dio1_pin (Optional, Pin Schema): Digital IO pin 1.
rst_pin (Required, Pin Schema): Reset pin.
frequency (Required, int): Frequency in Hz of the transceiver.
hw_version (Required, enum): Valid values are sx1261, sx1262, sx1268 or llcc68.
modulation (Required, enum): Modulation can be FSK or LORA.
pa_power (Optional, int): Transmitter power, range is from -3 to 15 dBm when hw_version is sx1261 and from -3 to 22 dBm otherwise.
pa_ramp (Optional, enum): Transmitter PA ramp, can be 10us, 20us, 40us, 80us, 200us, 800us, 1700us or 3400us.
rf_switch (Required, bool): Used to indicate if DIO2 controls an external RF switch.
rx_start (Optional, bool): Start the receiver automatically on boot or after transmitting.
tcxo_delay (Optional, Time): The time needed for the TCXO to stabilize.
tcxo_voltage (Optional, enum): Reference voltage of the external TCXO controlled by DIO3. If there is no TCXO this should be set to NONE. Values can be 1_6V, 1_7V, 1_8V, 2_2V, 2_4V, 2_7V, 3_0V, 3_3V or NONE.

LoRa configuration variables

bandwidth (Optional, enum): Bandwidth can be 7_8kHz, 10_4kHz, 15_6kHz, 20_8kHz, 31_3kHz, 41_7kHz, 62_5kHz, 125_0kHz, 250_0kHz or 500_0kHz.
payload_length (Optional, int): If greater than zero implicit header mode is enabled and the packet size is fixed. If not configured explicit header mode is enabled and variable packet sizes can be used. Maximum length is 256. Must be greater than zero when using a spreading_factor of 6.
crc_enable (Optional, bool): Enables a payload CRC calculation/check.
preamble_size (Optional, int): Length of the preamble in symbols, minimum of 6. Defaults to 8.
spreading_factor (Optional, int): Spreading factor, values range from 6 to 12. Defaults to 7.
coding_rate (Optional, enum): Coding rate, values can be CR_4_5, CR_4_6, CR_4_7 or CR_4_8. Defaults to CR_4_5.
sync_value (Optional, list): Synchronization words, limited to two bytes. The value [0x34, 0x44] is reserved for LoRaWAN networks and the value [0x14, 0x24] is meant for private networks. It is recommended to use only these two sets of values. Defaults to [0x14, 0x24].

FSK configuration variables

bandwidth (Optional, enum): Bandwidth can be 4_8kHz, 5_8kHz, 7_3kHz, 9_7kHz, 11_7kHz, 14_6kHz, 19_5kHz, 23_4kHz, 29_3kHz, 39_0kHz, 46_9kHz, 58_6kHz, 78_2kHz, 93_8kHz, 117_3kHz, 156_2kHz, 187_2kHz, 234_3kHz, 312_0kHz, 373_6kHz or 467_0kHz.
payload_length (Optional, int): Length of the packet. Maximum length is 256.
crc_enable (Optional, bool): Enables a 16 bit CRC calculation/check. Defaults to false.
crc_inverted (Optional, bool): Inverts the CRC if enabled. Defaults to true.
crc_size (Optional, int): Size of the CRC in bytes, either 1 or 2. Defaults to 2.
crc_initial (Optional, int): Initial CRC value as a hex integer. Defaults to 0x1D0F.
crc_polynomial (Optional, int): CRC polynomial as a hex integer. Defaults to 0x1021.
bitrate (Optional, int): Bit rate of the signal. Normally the inverse of the bit duration, eg 1 / 208 us is 4800 bps.
preamble_size (Optional, int): Length of the preamble in bytes to be sent by the transmitter. This value should be larger than preamble_detect on the receive side to allow time for the receiver’s AFC and AGC to adjust.
preamble_detect (Optional, int): Minimum length of the preamble in bytes required by the receiver. Preamble detector is disabled if the size is 0 and its value capped at 4.
sync_value (Optional, list): Synchronization bytes, list of 1 to 8 bytes, found after the preamble and before the payload.
deviation (Optional, int): Transmitter FSK frequency deviation, values range from 0 to 100,000 Hz.
shaping (Optional, enum): Transmitter data shaping can be GAUSSIAN_BT_0_3, GAUSSIAN_BT_0_5, GAUSSIAN_BT_0_7, GAUSSIAN_BT_1_0 or NONE.

ℹ️ Note
Configuration variables can be changed at runtime using lambdas. Settings will only be applied after calling configure. See API Reference .

Triggers

on_packet (Optional, Automation): An automation to perform when a packet has been decoded. Variable x of type std::vector<uint8_t> and rssi of type float are passed to the automation for use in lambdas. In LoRa mode the variable snr is also available.

sx126x:
  ...
  on_packet:
    then:
      - lambda: |-
          ESP_LOGD("lambda", "packet %s", format_hex(x).c_str());
          ESP_LOGD("lambda", "rssi %.2f", rssi);
          ESP_LOGD("lambda", "snr %.2f", snr);

Actions

`sx126x.run_image_cal` Action

This action runs the sx126x image calibration.

interval:
  - interval: 10min
    then:
      - sx126x.set_mode_standby
      - sx126x.run_image_cal
      - sx126x.set_mode_rx

`sx126x.set_mode_tx` Action

This action sets the sx126x mode to tx.

on_...:
  - sx126x.set_mode_tx

`sx126x.set_mode_rx` Action

This action sets the sx126x mode to rx.

on_...:
  - sx126x.set_mode_rx

`sx126x.set_mode_sleep` Action

This action sets the sx126x mode to sleep.

on_...:
  - sx126x.set_mode_sleep

`sx126x.set_mode_standby` Action

This action sets the sx126x mode to standby.

on_...:
  - sx126x.set_mode_standby

`sx126x.send_packet` Action

This action sends a packet.

on_...:
  - sx126x.send_packet:
      data: [0x1F, 0x3E, 0x06, 0x5F, 0x4F, 0x5F, 0xAC, 0xB1]

Configuration variables

data (Required, list): The packet to send, length should match the configured payload_length.

LoRa

LoRa example using an explicit header, spreading factor 7 and coding rate 4/6.

# Example configuration entry
sx126x:
  dio1_pin: GPIO14
  cs_pin: GPIO8
  busy_pin: GPIO13
  rst_pin: GPIO12
  pa_power: 3
  bandwidth: 125_0kHz
  crc_enable: true
  frequency: 433920000
  modulation: LORA
  hw_version: sx1262
  rf_switch: true
  sync_value: [0x14, 0x24]
  preamble_size: 8
  spreading_factor: 7
  coding_rate: CR_4_6
  tcxo_voltage: 1_8V
  tcxo_delay: 5ms
  on_packet:
    then:
      - lambda: |-
          ESP_LOGD("lambda", "packet %s", format_hex(x).c_str());
          ESP_LOGD("lambda", "rssi %.2f", rssi);
          ESP_LOGD("lambda", "snr %.2f", snr);

  button:
    - platform: template
      name: "Transmit Packet"
      on_press:
        then:
          - sx126x.send_packet:
             data: [0xC5, 0x51, 0x78, 0x82, 0xB7, 0xF9, 0x9C, 0x5C]

FSK

FSK example using a bit rate of 4800.

# Example configuration entry
sx126x:
  dio1_pin: GPIO14
  cs_pin: GPIO8
  busy_pin: GPIO13
  rst_pin: GPIO12
  pa_power: 3
  bandwidth: 78_2kHz
  crc_enable: true
  frequency: 433920000
  modulation: FSK
  payload_length: 8
  hw_version: sx1262
  bitrate: 4800
  rf_switch: true
  sync_value: [0x33, 0x33]
  preamble_size: 4
  preamble_detect: 2
  tcxo_voltage: 1_8V
  tcxo_delay: 5ms
  on_packet:
    then:
      - lambda: |-
          ESP_LOGD("lambda", "packet %s", format_hex(x).c_str());
          ESP_LOGD("lambda", "rssi %.2f", rssi);

  button:
    - platform: template
      name: "Transmit Packet"
      on_press:
        then:
          - sx126x.send_packet:
             data: [0xC5, 0x51, 0x78, 0x82, 0xB7, 0xF9, 0x9C, 0x5C]