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
spi:
clk_pin: GPIO9
mosi_pin: GPIO10
miso_pin: GPIO11
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
orllcc68
.modulation (Required, enum): Modulation can be
FSK
orLORA
.pa_power (Optional, int): Transmitter power, range is from -3 to 15 dBm when
hw_version
issx1261
and from -3 to 22 dBm otherwise.pa_ramp (Optional, enum): Transmitter PA ramp, can be
10us
,20us
,40us
,80us
,200us
,800us
,1700us
or3400us
.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 be1_6V
,1_7V
,1_8V
,2_2V
,2_4V
,2_7V
,3_0V
,3_3V
orNONE
.
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
or500_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
orCR_4_8
. Defaults toCR_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
or467_0kHz
.payload_length (Optional, int): Length of the packet. Maximum length is 256.
crc_enable (Optional, bool): Enables a 16 bit CRC calculation/check.
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
orNONE
.
Note
Configuration variables can be changed at runtime using lambdas. Settings will only be applied
after calling configure
. See API Reference.
Automations:¶
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 typefloat
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]