SX127x 组件

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

# 示例配置条目
sx127x:
  cs_pin: GPIO18
  rst_pin: GPIO23
  bandwidth: 50_0kHz
  frequency: 433.92MHz
  modulation: OOK
  packet_mode: false
  rx_start: true
  rx_floor: -90

配置变量

cs_pin (必选, Pin Schema): SPI 芯片选择引脚。
rst_pin (必选, Pin Schema): 复位引脚。
dio0_pin (可选, Pin Schema): 数字 IO 引脚 0。
auto_cal (可选, bool): 在温度变化时启用自动图像校准。默认为 true。
frequency (必选, frequency): 收发器的频率（Hz）。
modulation (必选, enum): 调制方式可以是 OOK、FSK 或 LORA。
pa_pin (可选, enum): 发射器输出引脚，可以是 BOOST 或 RFO。
pa_power (可选, int): 发射功率，当 pa_pin 为 BOOST 时范围从 2 到 17 dBm，使用 RFO 时范围为 0 到 15 dBm。
pa_ramp (可选, enum): 发射端 PA 斜坡，可以是 10us、12us、15us、 20us、25us、31us、40us、50us、62us、100us、125us、250us、500us、 1000us、2000us 或 3400us。
rx_start (可选, bool): 在启动或发送后自动启动接收器。

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): 如果大于零，则启用隐式报头模式，数据包大小固定。如果未配置，则启用显式报头模式，可以使用可变数据包大小。最大长度为 256。当使用 6 的 spreading_factor 时必须大于零。
crc_enable (可选, bool): 启用负载 CRC 计算/检查。
preamble_size (可选, int): 前导码长度（以符号计），最少 6 个。
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 (可选, int): 同步字，限制为单个字节。值 0x34 保留用于 LoRaWAN 网络，值 0x12 用于私有网络。建议使用 0x12 或 0x34。默认为 0x12。

FSK/OOK 配置变量

bandwidth (可选, enum): 带宽可以是 2_6kHz、3_1kHz、3_9kHz、 5_2kHz、6_3kHz、7_8kHz、10_4kHz、12_5kHz、15_6kHz、20_8kHz、25_0kHz、 31_3kHz、41_7kHz、50_0kHz、62_5kHz、83_3kHz、100_0kHz、125_0kHz、 166_7kHz、200_0kHz 或 250_0kHz。
packet_mode (可选, bool): 数据包模式下字节通过 send_packet 自动化发送，并通过 on_packet 触发器接收。如果未启用，则使用连续模式，原始数据在 DIO2 上发送和接收。
payload_length (可选, int): 数据包模式下负载的长度。如果未配置，则使用变长数据包格式。最大长度为 64。
crc_enable (可选, bool): 数据包模式下启用 16 位 CRC 计算/检查。
bitrate (可选, int): 信号的比特率。数据包模式下必需，连续模式下推荐。通常为比特持续时间的倒数，例如 1 / 208 us 为 4800 bps。
bitsync (可选, bool): 启用接收位同步器。数据包模式下必需。连续模式下推荐，但如果既有无前导码又有高噪声，可能最好将其关闭。
preamble_polarity (可选, int): 前导码的极性，为 0xAA 或 0x55。
preamble_size (可选, int): 发射器要发送的前导码长度（以字节计）。此值应大于接收侧的 preamble_detect，为接收器的 AFC 和 AGC 留出调整时间。
preamble_detect (可选, int): 接收器所需前导码的最小长度（以字节计）。如果大小为 0 则禁用前导码检测器，其值上限为 3。
preamble_errors (可选, int): 接收器容忍的芯片错误数。
sync_value (可选, list): 同步字节，1 到 8 个字节组成的列表，位于前导码之后、负载之前。
rx_floor (可选, float): 接收 OOK 时，rx_floor 应根据你的环境适当设置。如果设置过高（即接近 0），射频将忽略所有内容。如果设置过低（即接近 -128），会有过多噪声通过。当接收 FSK 且未配置前导码时，rx_floor 用于触发接收器。
deviation (可选, frequency): 发射器 FSK 频率偏移，取值范围为 0 到 100 kHz。默认为 5kHz。
shaping (可选, enum): 发射数据整形。OOK 下可以是 CUTOFF_BR_X_2、 CUTOFF_BR_X_1 或 NONE。FSK 下可以是 GAUSSIAN_BT_0_3、GAUSSIAN_BT_0_5、 GAUSSIAN_BT_1_0 或 NONE。不推荐在连续模式下使用，因为 DIO2 上的数据必须与 DIO1 上的位时钟同步。

NOTE

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

触发器

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

sx127x:
  ...
  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);

动作

`sx127x.run_image_cal` 动作

此 action 运行 sx127x 图像校准，必须处于待机模式。

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

`sx127x.set_mode_tx` 动作

此 action 将 sx127x 模式设置为 tx。

on_...:
  - sx127x.set_mode_tx

`sx127x.set_mode_rx` 动作

此 action 将 sx127x 模式设置为 rx。

on_...:
  - sx127x.set_mode_rx

`sx127x.set_mode_sleep` 动作

此 action 将 sx127x 模式设置为睡眠。

on_...:
  - sx127x.set_mode_sleep

`sx127x.set_mode_standby` 动作

此 action 将 sx127x 模式设置为待机。

on_...:
  - sx127x.set_mode_standby

`sx127x.send_packet` 动作

此 action 发送一个数据包，sx127x 需要处于数据包模式。

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

配置变量

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

LoRa

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

# 示例配置条目
sx127x:
  dio0_pin: GPIO26
  cs_pin: GPIO18
  rst_pin: GPIO23
  pa_pin: BOOST
  pa_power: 4
  bandwidth: 125_0kHz
  crc_enable: true
  frequency: 433.92MHz
  modulation: LORA
  rx_start: true
  sync_value: 0x33
  spreading_factor: 7
  coding_rate: CR_4_5
   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:
          - sx127x.send_packet:
             data: [0xC5, 0x51, 0x78, 0x82, 0xB7, 0xF9, 0x9C, 0x5C]

FSK/OOK 数据包模式

使用 4800 比特率的 FSK 数据包模式示例。

# 示例配置条目
sx127x:
  cs_pin: GPIO18
  rst_pin: GPIO23
  dio0_pin: GPIO26
  pa_pin: BOOST
  pa_power: 17
  bitrate: 4800
  bitsync: true
  crc_enable: true
  frequency: 433.92MHz
  modulation: FSK
  packet_mode: true
  payload_length: 8
  rx_start: true
  sync_value: [0x33, 0x33]
  preamble_size: 4
  preamble_detect: 2
  preamble_errors: 8
  preamble_polarity: 0x55
  on_packet:
    then:
      - lambda: |-
          char hex[256];  // Size appropriately for your data
          ESP_LOGD("lambda", "packet %s", format_hex_to(hex, x));

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

FSK/OOK 连续模式

作为接收器

sx127x 会将解调后的数据输出到 DIO2，并使用 remote_receiver 在 pin（必须连接到 DIO2）上接收这些数据。

# 示例配置条目
sx127x:
  cs_pin: GPIO18
  rst_pin: GPIO23
  bandwidth: 50_0kHz
  frequency: 433.92MHz
  modulation: OOK
  packet_mode: false
  rx_start: true
  rx_floor: -90

remote_receiver:
  pin: GPIO32
  dump: raw

NOTE

不建议在连续模式下接收 FSK，因为会有过多噪声。请改用数据包模式。

作为发射器

sx127x 期望在 DIO2 上传输原始数据，使用 remote_transmitter 在 pin（必须连接到 DIO2）上传输这些数据。传输之前和之后必须使用 on_transmit 和 on_complete 自动化设置合适的 sx127x 模式。

# 示例配置条目
sx127x:
  cs_pin: GPIO18
  rst_pin: GPIO23
  bandwidth: 50_0kHz
  frequency: 433.92MHz
  modulation: OOK
  packet_mode: false
  rx_start: false
  pa_pin: BOOST
  pa_power: 17

remote_transmitter:
  pin: GPIO32
  carrier_duty_percent: 100%
  on_transmit:
    then:
      - sx127x.set_mode_tx
  on_complete:
    then:
      - sx127x.set_mode_standby

button:
  - platform: template
    name: "Transmit Raw"
    on_press:
      then:
        - remote_transmitter.transmit_raw:
            code: [614, -614, 600, -614, 614, -614, 601, -614]

作为发射器和接收器

共享的 pin 应设置为开漏并带上拉。在 remote_transmitter 中 eot_level 应设为 false。除了在 on_transmit / on_complete 中设置 sx127x 模式外，还应在 set_mode_tx 之前将引脚拉低，并在 set_mode_rx 之前将其上拉 / 释放。

# 示例配置条目
sx127x:
  cs_pin: GPIO18
  rst_pin: GPIO23
  bandwidth: 50_0kHz
  frequency: 433.92MHz
  modulation: OOK
  packet_mode: false
  rx_start: true
  rx_floor: -90
  pa_pin: BOOST
  pa_power: 17

remote_receiver:
  pin:
    number: GPIO32
    mode:
      input: true
      output: true
      pullup: true
      open_drain: true
    allow_other_uses: true
  dump: raw

remote_transmitter:
  pin:
    number: GPIO32
    mode:
      input: true
      output: true
      pullup: true
      open_drain: true
    allow_other_uses: true
  eot_level: false
  carrier_duty_percent: 100%
  on_transmit:
    then:
      - sx127x.set_mode_standby
      - remote_transmitter.digital_write: false
      - sx127x.set_mode_tx
  on_complete:
    then:
      - sx127x.set_mode_standby
      - remote_transmitter.digital_write: true
      - sx127x.set_mode_rx

button:
  - platform: template
    name: "Transmit Raw"
    on_press:
      then:
        - remote_transmitter.transmit_raw:
            code: [614, -614, 600, -614, 614, -614, 601, -614]

SX127x 组件

配置变量

LoRa 配置变量

FSK/OOK 配置变量

触发器

动作

sx127x.run_image_cal 动作

sx127x.set_mode_tx 动作

sx127x.set_mode_rx 动作

sx127x.set_mode_sleep 动作

sx127x.set_mode_standby 动作

sx127x.send_packet 动作

配置变量

LoRa

FSK/OOK 数据包模式

FSK/OOK 连续模式

作为接收器

作为发射器

作为发射器和接收器

参见

`sx127x.run_image_cal` 动作

`sx127x.set_mode_tx` 动作

`sx127x.set_mode_rx` 动作

`sx127x.set_mode_sleep` 动作

`sx127x.set_mode_standby` 动作

`sx127x.send_packet` 动作