SX126x 组件

SX126x 组件允许你在 ESPHome 中配置 SX1261、SX1262、SX1268 和 LLCC68 收发器 (数据手册)。收发器通过 SPI 总线连接。支持的频率范围为 150 MHz 至 960 MHz，包括常用的 315 MHz、433 MHz、868 MHz 和 915 MHz ISM 频段。支持的调制方式包括 LoRa、FSK、GFSK、MSK 和 GMSK。SX126x 组件可作为数据包传输组件的平台，使传感器数据能够从一个 ESPHome 节点直接发送到另一个节点。

# 示例配置条目
sx126x:
  dio1_pin: GPIO14
  cs_pin: GPIO8
  busy_pin: GPIO13
  rst_pin: GPIO12
  pa_power: 3
  bandwidth: 125_0kHz
  crc_enable: true
  frequency: 433.92MHz
  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

配置变量

busy_pin (必选, Pin Schema): 忙信号引脚。
cs_pin (必选, Pin Schema): SPI 芯片选择引脚。
dio1_pin (必选, Pin Schema): 数字 IO 引脚 1。
rst_pin (必选, Pin Schema): 复位引脚。
frequency (必选, frequency): 收发器的频率（Hz）。
hw_version (必选, enum): 有效值为 sx1261、sx1262、sx1268 或 llcc68。
modulation (必选, enum): 调制方式可以是 FSK 或 LORA。
pa_power (可选, int): 发射功率，hw_version 为 sx1261 时范围从 -3 到 15 dBm，其他情况范围从 -3 到 22 dBm。
pa_ramp (可选, enum): 发射端 PA 斜坡，可以是 10us、20us、40us、80us、 200us、800us、1700us 或 3400us。
rf_switch (必选, bool): 用于指示 DIO2 是否控制外部 RF 开关。
rx_start (可选, bool): 在启动或发送后自动启动接收器。
tcxo_delay (可选, Time): TCXO 稳定所需的时间。
tcxo_voltage (可选, enum): 由 DIO3 控制的外部 TCXO 参考电压。如果没有 TCXO，应设为 NONE。取值可为 1_6V、1_7V、1_8V、2_2V、 2_4V、2_7V、3_0V、3_3V 或 NONE。

LoRa 配置变量

bandwidth (可选, enum): 带宽可以是 7_8kHz、10_4kHz、15_6kHz、20_8kHz、 31_3kHz、41_7kHz、62_5kHz、125_0kHz、250_0kHz 或 500_0kHz。
payload_length (可选, int): 如果大于零，则启用隐式报头模式，数据包大小固定。如果未配置，则启用显式报头模式，可以使用可变数据包大小。最大长度为 255。当使用 6 的扩频因子时必须大于零。
crc_enable (可选, bool): 启用负载 CRC 计算/检查。
preamble_size (可选, int): 前导码长度（以符号计），最少 6 个。默认为 8。
spreading_factor (可选, int): 扩频因子，取值范围为 6 到 12。默认为 7。
coding_rate (可选, enum): 编码率，取值可为 CR_4_5、CR_4_6、CR_4_7 或 CR_4_8。默认为 CR_4_5。
sync_value (可选, list): 同步字，最多两个字节。值 [0x34, 0x44] 保留用于 LoRaWAN 网络，值 [0x14, 0x24] 用于私有网络。建议只使用这两组值。默认为 [0x14, 0x24]。

FSK 配置变量

bandwidth (可选, enum): 带宽可以是 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 或 467_0kHz。
payload_length (可选, int): 数据包长度。最大长度为 255。
crc_enable (可选, bool): 启用 16 位 CRC 计算/检查。默认为 false。
crc_inverted (可选, bool): 启用时反转 CRC。默认为 true。
crc_size (可选, int): CRC 大小（字节），为 1 或 2。默认为 2。
crc_initial (可选, int): 初始 CRC 值（十六进制整数）。默认为 0x1D0F。
crc_polynomial (可选, int): CRC 多项式（十六进制整数）。默认为 0x1021。
bitrate (可选, int): 信号的比特率。通常为比特持续时间的倒数，例如 1 / 208 us 为 4800 bps。
preamble_size (可选, int): 发射器要发送的前导码长度（以字节计）。此值应大于接收侧的 preamble_detect，为接收器的 AFC 和 AGC 留出调整时间。
preamble_detect (可选, int): 接收器所需前导码的最小长度（以字节计）。如果大小为 0 则禁用前导码检测器，其值上限为 4。
sync_value (可选, list): 同步字节，1 到 8 个字节组成的列表，位于前导码之后、负载之前。
deviation (可选, frequency): 发射器 FSK 频率偏移，取值范围为 0 到 100 kHz。默认为 5kHz。
shaping (可选, enum): 发射数据整形方式可以是 GAUSSIAN_BT_0_3、GAUSSIAN_BT_0_5、 GAUSSIAN_BT_0_7、GAUSSIAN_BT_1_0 或 NONE。
whitening_enable (可选, bool): 启用使用固定多项式 0x21 的 CCITT 数据加白。默认为 false。
whitening_initial (可选, int): 加白移位寄存器的初始值。默认为 0x100。

NOTE

可以通过 lambda 在运行时更改配置变量。设置只有在调用 configure 之后才会生效。参见 API 参考：sx126x.h。

触发器

on_packet (可选, Automation): 数据包解码完成后执行的自动化。类型为 std::vector<uint8_t> 的变量 x 和类型为 float 的 rssi 会传递给自动化，用于在 lambda 中使用。在 LoRa 模式下，变量 snr 也可用。

sx126x:
  ...
  on_packet:
    then:
      - lambda: |-
          char hex[256];  // Size appropriately for your data
          ESP_LOGD("lambda", "packet %s", format_hex_to(hex, x));
          ESP_LOGD("lambda", "rssi %.2f", rssi);
          ESP_LOGD("lambda", "snr %.2f", snr);

动作

`sx126x.run_image_cal` 动作

此动作运行 sx126x 图像校准。

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

`sx126x.set_mode_tx` 动作

此动作将 sx126x 模式设置为 tx。

on_...:
  - sx126x.set_mode_tx

`sx126x.set_mode_rx` 动作

此动作将 sx126x 模式设置为 rx。

on_...:
  - sx126x.set_mode_rx

`sx126x.set_mode_sleep` 动作

此动作将 sx126x 模式设置为睡眠。默认情况下射频进入暖睡眠——配置寄存器会被保留，这样唤醒后就可以再次用于 sx126x.set_mode_rx / sx126x.set_mode_tx。对于电池供电的节点，如果射频与深度睡眠配对，使用 cold: true 切换到冷睡眠（约 0.6 µA，暖睡眠约 600 µA）。冷睡眠不会保留配置，因此唤醒后必须重新初始化射频。使用深度睡眠时这会自动完成——设备在唤醒时重启，组件在启动期间重新初始化射频。

on_...:
  - sx126x.set_mode_sleep:
      cold: true

配置变量

cold (可选, 可模板化, boolean): 如果为真，则进入冷睡眠而不是暖睡眠。默认为 false。

`sx126x.set_mode_standby` 动作

此动作将 sx126x 模式设置为待机。

on_...:
  - sx126x.set_mode_standby

`sx126x.send_packet` 动作

此动作发送一个数据包。

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

配置变量

data (必选, list, 可模板化): 要发送的数据包，长度应与配置的 payload_length 相匹配。

LoRa

使用显式报头、扩频因子 7 和编码率 4/6 的 LoRa 示例。

# 示例配置条目
sx126x:
  dio1_pin: GPIO14
  cs_pin: GPIO8
  busy_pin: GPIO13
  rst_pin: GPIO12
  pa_power: 3
  bandwidth: 125_0kHz
  crc_enable: true
  frequency: 433.92MHz
  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: |-
          char hex[256];  // Size appropriately for your data
          ESP_LOGD("lambda", "packet %s", format_hex_to(hex, x));
          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

使用 4800 比特率的 FSK 示例。

# 示例配置条目
sx126x:
  dio1_pin: GPIO14
  cs_pin: GPIO8
  busy_pin: GPIO13
  rst_pin: GPIO12
  pa_power: 3
  bandwidth: 78_2kHz
  crc_enable: true
  frequency: 433.92MHz
  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: |-
          char hex[256];  // Size appropriately for your data
          ESP_LOGD("lambda", "packet %s", format_hex_to(hex, x));
          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]

参见

API 参考：sx126x.h

SX126x 组件

配置变量

LoRa 配置变量

FSK 配置变量

触发器

动作

sx126x.run_image_cal 动作

sx126x.set_mode_tx 动作

sx126x.set_mode_rx 动作

sx126x.set_mode_sleep 动作

配置变量

sx126x.set_mode_standby 动作

sx126x.send_packet 动作

配置变量

LoRa

FSK

参见

`sx126x.run_image_cal` 动作

`sx126x.set_mode_tx` 动作

`sx126x.set_mode_rx` 动作

`sx126x.set_mode_sleep` 动作

`sx126x.set_mode_standby` 动作

`sx126x.send_packet` 动作