CC1101 低功耗 Sub-1 GHz RF 收发器

CC1101 组件为 Texas Instruments CC1101 Sub-1 GHz RF 收发器提供驱动程序（数据手册）。CC1101 是一款低成本、低功耗的无线电芯片，常用于 300-928 MHz 频段的无线通信，包括流行的 315 MHz、433 MHz、868 MHz 和 915 MHz ISM 频段。

CC1101 支持多种调制方式（ASK/OOK、2-FSK、4-FSK、GFSK、MSK），可配置的数据速率从 600 到 500,000 波特，可调节的输出功率从 -30 dBm 到 +11 dBm。它通过 SPI 总线连接到 ESPHome。

该组件支持两种操作模式：

• 异步模式（默认）：与远程发射器和远程接收器组件集成，用于编码和解码 RF 协议。
• 数据包模式：内置数据包处理，具有同步字检测、CRC 和 on_packet 触发器。适用于与其他基于数据包的无线电通信时的 FSK/GFSK 调制。

组件配置

# 最小示例
cc1101:
  cs_pin: GPIOXX
  frequency: 433.92MHz

配置变量

硬件设置

• cs_pin (必需, 引脚): 连接到模块的 SPI 片选 (CSN) 引脚。
• gdo0_pin (可选, 引脚): GDO0 引脚。启用 packet_mode 时需要，也用于单引脚模式切换。

通用设置

• frequency (可选, 频率): 工作频率。 范围：300MHz 到 928MHz。默认为 433.92MHz。
• output_power (可选, 浮点数): 发射功率，单位 dBm。 范围：-30 到 11。默认为 10。
• modulation_type (可选, 枚举): 调制格式。 选项：ASK/OOK（默认）、2-FSK、4-FSK、GFSK、MSK。
• symbol_rate (可选, 整数): 符号速率，单位波特。 范围：600 到 500000。默认为 5000。
• rx_attenuation (可选, 枚举): 内部 RX 衰减。 选项：0dB、6dB、12dB、18dB。默认为 0dB。
• dc_blocking_filter (可选, 布尔值): 启用数字直流阻塞滤波器。默认为 true。
• manchester (可选, 布尔值): 启用曼彻斯特编码。默认为 false。

调谐器设置

• filter_bandwidth (可选, 频率): 接收滤波器带宽。 范围：58kHz 到 812kHz。默认为 203kHz。
• fsk_deviation (可选, 频率): FSK/GFSK 调制的频率偏移。 范围：1.5kHz 到 381kHz。
• msk_deviation (可选, 整数): MSK 调制的偏移指数。范围：1 到 8。
• channel (可选, 整数): 信道编号（添加到基准频率）。默认为 0。
• channel_spacing (可选, 频率): 信道之间的间隔。 范围：25kHz 到 405kHz。默认为 200kHz。
• if_frequency (可选, 频率): 中频。 范围：25kHz 到 788kHz。默认为 153kHz。

数据包模式设置

这些设置启用 CC1101 的内置数据包处理，包括 FIFO 缓冲、同步字检测和可选的 CRC 校验。

• packet_mode (可选, 布尔值): 启用 FIFO 数据包模式。启用时，需要 gdo0_pin。默认为 false。
• packet_length (可选, 整数): 数据包长度（字节）。设置为 0 表示可变长度数据包（长度字节前置在数据前）。范围：0 到 64。默认为 0。
• crc_enable (可选, 布尔值): 启用 CRC-16 计算和校验。CC1101 使用 CRC-16-IBM（多项式 0x8005）。默认为 false。
• whitening (可选, 布尔值): 启用数据白化以改善直流平衡。默认为 false。
• sync_mode (可选, 枚举): 同步字检测模式。 选项：None、15/16、16/16、30/32。默认为 16/16。
• sync0 (可选, 十六进制): 同步字低位字节。默认为 0x91。
• sync1 (可选, 十六进制): 同步字高位字节。默认为 0xD3。
• num_preamble (可选, 整数): 要发送的前导字节数。 范围：0 到 7（映射为 2、3、4、6、8、12、16、24 字节）。默认为 2（4 字节）。

AGC（自动增益控制）设置

高级用户可以微调 AGC 动态特性。AGC 自动调整接收器增益以处理不同强度的信号。这些设置控制增益调整的激进程度和速度。 详细信息请参阅 CC1101 数据手册。

• magn_target (可选, dB): AGC 环路的目标信号幅度。较高的值可提高灵敏度，但在强信号下可能导致削波。 范围：24dB 到 42dB，以 3 为增量（例如 33dB）。默认为 42dB。
• max_lna_gain (可选, dB): 限制最大 LNA（低噪声放大器）增益。用于防止高信号环境下的饱和。默认为 Default。 选项：Default、2.6dB、6.1dB、7.4dB、9.2dB、11.5dB、14.6dB、17.1dB。
• max_dvga_gain (可选, 枚举): 限制最大 DVGA（数字可变增益放大器）增益。 选项：Default、-1、-2、-3。默认为 -3。
• lna_priority (可选, 布尔值): 如果为 true，在降低整体增益时先减少 LNA 增益再减少 DVGA 增益。有助于优化噪声系数。默认为 false。
• carrier_sense_above_threshold (可选, 布尔值): 仅在载波检测指示存在信号时接受数据包。默认为 false。
• carrier_sense_abs_thr (可选, 整数): 载波检测的绝对 RSSI 阈值。当 RSSI 超过此电平时，无线电认为存在载波。范围：-8 到 7。
• carrier_sense_rel_thr (可选, 枚举): 载波检测的相对 RSSI 阈值，与当前噪声底进行比较。选项：Default、+6dB、+10dB、+14dB。
• filter_length_fsk_msk (可选, 枚举): FSK/MSK 模式下 AGC 的平均长度。 较长的值提供更稳定的增益但响应较慢。选项：8、16、32、64。
• filter_length_ask_ook (可选, 枚举): ASK/OOK 模式下 AGC 的平均长度。 较长的值提供更稳定的增益但响应较慢。选项：4dB、8dB、12dB、16dB。
• freeze (可选, 枚举): 控制 AGC 增益何时冻结（保持恒定）。 选项：Default、On Sync、Analog Only、Analog And Digital。
• wait_time (可选, 枚举): 增益更改后等待再次调整的时间。 选项：8、16、24、32。默认为 32。
• hyst_level (可选, 枚举): 滞后电平，用于防止边界信号上的增益振荡。 选项：None、Low、Medium、High。

触发器

on_packet 触发器

在数据包模式下，当收到数据包时触发此触发器。一个类型为 std::vector<uint8_t> 的变量 x（包含数据包数据）会传递给自动化。以下变量也可用：

• freq_offset: 频率偏移估计值，单位 Hz。
• rssi: 信号强度，单位 dBm。
• lqi: 链路质量指示器（0-127，越低越好）。

cc1101:
  cs_pin: GPIOXX
  gdo0_pin: GPIOXX
  frequency: 433.92MHz
  modulation_type: GFSK
  symbol_rate: 4800
  packet_mode: true
  packet_length: 8
  on_packet:
    then:
      - lambda: |-
          char hex[256];  // 根据您的数据适当调整大小
          ESP_LOGD("cc1101", "packet %s freq_offset %.0f Hz rssi %.1f dBm lqi %u",
                   format_hex_to(hex, x), freq_offset, rssi, lqi);

动作

cc1101.begin_tx 动作

此动作将无线电置于 TX 模式并将 gdo0_pin 切换为输出模式。

cc1101.begin_rx 动作

此动作将无线电置于 RX 模式并将 gdo0_pin 切换为输入模式。

cc1101.set_idle 动作

此动作将无线电置于空闲状态。

cc1101.reset 动作

此动作重置 CC1101 芯片并重新应用配置。

cc1101.send_packet 动作

此动作发送数据包。仅在启用 packet_mode 时可用。

配置变量

• data (必需, 列表): 要发送的数据包，长度应与配置的 packet_length 匹配。

on_...:
  - cc1101.send_packet:
      data: [0x12, 0x34, 0x56, 0x78]

与远程接收器/发射器集成

对于 ASK/OOK 调制，CC1101 与远程接收器/发射器集成用于协议编码和解码。该组件自动配置 GDO 引脚以支持双引脚和单引脚接线方案。

1. 双引脚接线（推荐）

这是最简单且推荐的接线方案。它使用单独的引脚进行数据发送和接收。

• GDO0（模块引脚 3）: 连接到 remote_transmitter 使用的 MCU 引脚。
• GDO2（模块引脚 8）: 连接到 remote_receiver 使用的 MCU 引脚。

cc1101:
  cs_pin: GPIOXX

remote_transmitter:
  pin: GPIOXX  # 必须匹配 GDO0
  carrier_duty_percent: 100%
  on_transmit:
    then:
      - cc1101.begin_tx
  on_complete:
    then:
      - cc1101.begin_rx

remote_receiver:
  pin: GPIOXX  # 必须匹配 GDO2
  dump: all

2. 单引脚接线

此接线方案使用单个 MCU 引脚同时进行数据发送和接收，连接到 GDO0。 这需要仔细配置 remote_transmitter 和 remote_receiver 以避免冲突。

• GDO0（模块引脚 3）: 连接到单个 MCU GPIO 引脚。
• GDO2（模块引脚 8）: 保持未连接。

开漏单引脚模式

ESP32 在使用单引脚接线时必须使用此方法。共享引脚应设置为带上拉的开漏模式。eot_level 选项（来自 remote_transmitter）控制传输完成后的引脚状态 - 将其设置为 false 可保持引脚低电平直到显式释放。除了在 on_transmit/on_complete 中设置 CC1101 模式外，还应在 begin_tx 之前将引脚驱动为低电平，并在 begin_rx 之前释放。

cc1101:
  cs_pin: GPIOXX

remote_receiver:
  pin:
    number: GPIOXX  # 必须匹配 GDO0
    mode:
      input: true
      output: true
      pullup: true
      open_drain: true
    allow_other_uses: true
  dump: all

remote_transmitter:
  pin:
    number: GPIOXX  # 必须匹配 GDO0
    mode:
      input: true
      output: true
      pullup: true
      open_drain: true
    allow_other_uses: true
  eot_level: false
  carrier_duty_percent: 100%
  on_transmit:
    then:
      - cc1101.set_idle
      - remote_transmitter.digital_write: false
      - cc1101.begin_tx
  on_complete:
    then:
      - cc1101.set_idle
      - remote_transmitter.digital_write: true
      - cc1101.begin_rx

自动模式切换的单引脚模式

当配置了 gdo0_pin 时，begin_tx 和 begin_rx 会自动在输出和输入模式之间切换引脚，从而简化配置。

cc1101:
  cs_pin: GPIOXX
  gdo0_pin:
    number: GPIOXX  # 必须匹配 GDO0
    allow_other_uses: true

remote_receiver:
  pin:
    number: GPIOXX  # 必须匹配 GDO0
    allow_other_uses: true
  dump: all

remote_transmitter:
  pin:
    number: GPIOXX  # 必须匹配 GDO0
    allow_other_uses: true
  carrier_duty_percent: 100%
  on_transmit:
    then:
      - cc1101.begin_tx
  on_complete:
    then:
      - cc1101.begin_rx

故障排除

”FF0F was found” 错误

如果您在设置期间看到日志条目显示 FF0F、0000 或 FFFF，这表示 SPI 通信失败。请检查您的接线（MISO/MOSI/CS）。

发射时无信号

• 检查引脚定义：对于所有模式，数据线必须连接到 GDO0（模块引脚 3），因为 CC1101 芯片仅支持通过 GDO0 引脚进行传输输入。
• 检查引脚模式：确保 gdo0_pin 已配置为自动引脚模式切换。

另见

• 远程接收器
• 远程发射器
• SPI 组件
• CC1101 数据手册