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 (必填, 引脚模式): SPI 片选引脚。
rst_pin (必填, 引脚模式): 复位引脚。
dio0_pin (可选, 引脚模式): 数字 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。使用 spreading_factor 为 6 时必须大于零。
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 Reference: sx127x.h。

触发器

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

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

动作

`sx127x.run_image_cal` 动作

此动作运行 sx127x 镜像校准，必须处于待机模式。

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

`sx127x.set_mode_tx` 动作

此动作将 sx127x 模式设置为发射。

on_...:
  - sx127x.set_mode_tx

`sx127x.set_mode_rx` 动作

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

on_...:
  - sx127x.set_mode_rx

`sx127x.set_mode_sleep` 动作

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

on_...:
  - sx127x.set_mode_sleep

`sx127x.set_mode_standby` 动作

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

on_...:
  - sx127x.set_mode_standby

`sx127x.send_packet` 动作

此动作发送数据包，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];  // 根据您的数据适当调整大小
          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:
          - 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];  // 根据您的数据适当调整大小
          ESP_LOGD("lambda", "packet %s", format_hex_to(hex, x));

  button:
    - platform: template
      name: "发射数据包"
      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: "发射原始数据"
    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: "发射原始数据"
    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` 动作