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 (必填, 引脚模式): 忙碌引脚。

• cs_pin (必填, 引脚模式): SPI 片选引脚。

• dio1_pin (可选, 引脚模式): 数字 IO 引脚 1。

• rst_pin (必填, 引脚模式): 复位引脚。

• 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 (可选, 时间): 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。

NOTE

配置变量可以在运行时使用 lambda 更改。设置只有在调用 configure 后才会应用。参见 API Reference: sx126x.h。

触发器

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

sx126x:
  ...
  on_packet:
    then:
      - lambda: |-
          char hex[256];  // 根据您的数据适当调整大小
          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 模式设置为发射。

on_...:
  - sx126x.set_mode_tx

sx126x.set_mode_rx 动作

此动作将 sx126x 模式设置为接收。

on_...:
  - sx126x.set_mode_rx

sx126x.set_mode_sleep 动作

此动作将 sx126x 模式设置为休眠。

on_...:
  - sx126x.set_mode_sleep

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];  // 根据您的数据适当调整大小
          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: "发射数据包"
      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];  // 根据您的数据适当调整大小
          ESP_LOGD("lambda", "packet %s", format_hex_to(hex, x));
          ESP_LOGD("lambda", "rssi %.2f", rssi);

  button:
    - platform: template
      name: "发射数据包"
      on_press:
        then:
          - sx126x.send_packet:
             data: [0xC5, 0x51, 0x78, 0x82, 0xB7, 0xF9, 0x9C, 0x5C]

另见

• API Reference: sx126x.h