跳转到内容
ESPHome - 让智能家居更简单2026.7.0

CC1101 低功耗 Sub-1 GHz 射频收发器

CC1101 组件为 Texas Instruments CC1101 Sub-1 GHz 射频收发器提供驱动 （数据手册）。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。

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

  • 异步模式（默认）：与 Remote Transmitter 和 Remote Receiver 组件集成，用于对 RF 协议进行编码和解码。
  • 数据包模式：内置数据包处理功能，包括同步字检测、CRC 以及 on_packet 触发器。 在与其它基于数据包的无线电通信时，最适合 FSK/GFSK 调制。
CC1101 模块

组件配置

Section titled “组件配置”
# Minimal Example
cc1101:
  cs_pin: GPIOXX
  frequency: 433.92MHz

配置变量

Section titled “配置变量”

硬件设置

Section titled “硬件设置”
  • cs_pin (必选, Pin)： 连接到模块的 SPI 片选（CSN）引脚。
  • gdo0_pin (可选, Pin)： GDO0 引脚。启用 packet_mode 时必需，也用于单引脚模式切换。

常规设置

Section titled “常规设置”
  • frequency (可选, frequency)：工作频率。 范围：300MHz 至 928MHz。默认为 433.92MHz。
  • output_power (可选, float)：发射功率，单位为 dBm。 范围：-30 至 11。默认为 10。
  • modulation_type (可选, enum)：调制格式。 选项：ASK/OOK（默认）、2-FSK、4-FSK、GFSK、MSK。
  • symbol_rate (可选, int)：符号速率，单位为波特。 范围：600 至 500000。默认为 5000。
  • rx_attenuation (可选, enum)：内部接收（RX）衰减。 选项：0dB、6dB、12dB、18dB。默认为 0dB。
  • dc_blocking_filter (可选, boolean)：启用数字直流隔直滤波器。默认为 true。
  • manchester (可选, boolean)：启用曼彻斯特编码。默认为 false。

调谐器设置

Section titled “调谐器设置”
  • filter_bandwidth (可选, frequency)：接收滤波器带宽。 范围：58kHz 至 812kHz。默认为 203kHz。
  • fsk_deviation (可选, frequency)：FSK/GFSK 调制的频偏。 范围：1.5kHz 至 381kHz。
  • msk_deviation (可选, int)：MSK 调制的频偏指数。范围：1 至 8。
  • channel (可选, int)：信道编号（加在基础频率之上）。默认为 0。
  • channel_spacing (可选, frequency)：信道间隔。 范围：25kHz 至 405kHz。默认为 200kHz。
  • if_frequency (可选, frequency)：中频。 范围：25kHz 至 788kHz。默认为 153kHz。

数据包模式设置

Section titled “数据包模式设置”

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

  • packet_mode (可选, boolean)：启用 FIFO 数据包模式。启用后，必须配置 gdo0_pin。默认为 false。
  • packet_length (可选, int)：数据包长度，单位为字节。设为 0 表示可变 长度数据包（长度字节会加在数据前面）。范围：0 至 64。默认为 0。
  • crc_enable (可选, boolean)：启用 CRC-16 计算和校验。CC1101 使用 CRC-16-IBM（多项式 0x8005）。默认为 false。
  • whitening (可选, boolean)：启用数据白化以改善直流平衡。默认为 false。
  • sync_mode (可选, enum)：同步字检测模式。 选项：None、15/16、16/16、30/32。默认为 16/16。
  • sync0 (可选, hex)：同步字低字节。默认为 0x91。
  • sync1 (可选, hex)：同步字高字节。默认为 0xD3。
  • num_preamble (可选, int)：要发送的前导字节数。 范围：0 至 7（对应 2、3、4、6、8、12、16、24 字节）。默认为 2（4 字节）。

AGC（自动增益控制）设置

Section titled “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 (可选, enum)：限制 DVGA（数字可变增益放大器）的最大增益。 选项：Default、-1、-2、-3。默认为 -3。
  • lna_priority (可选, boolean)：若为 true，在降低总增益时先降低 LNA 增益再降低 DVGA 增益。 有助于优化噪声系数。默认为 false。
  • carrier_sense_above_threshold (可选, boolean)：仅在载波检测 指示存在信号时才接受数据包。默认为 false。
  • carrier_sense_abs_thr (可选, int)：载波检测的绝对 RSSI 阈值。当 RSSI 超过此电平时，无线电判定存在载波。范围：-8 至 7。
  • carrier_sense_rel_thr (可选, enum)：载波检测的相对 RSSI 阈值，与 当前噪声底比较。选项：Default、+6dB、+10dB、+14dB。
  • filter_length_fsk_msk (可选, enum)：FSK/MSK 模式下 AGC 的平均长度。 较大的值可获得更稳定的增益，但响应较慢。选项：8、16、32、64。
  • filter_length_ask_ook (可选, enum)：ASK/OOK 模式下 AGC 的平均长度。 较大的值可获得更稳定的增益，但响应较慢。选项：4dB、8dB、12dB、16dB。
  • freeze (可选, enum)：控制 AGC 增益何时被冻结（保持不变）。 选项：Default、On Sync、Analog Only、Analog And Digital。
  • wait_time (可选, enum)：增益改变后、允许再次调整前需要等待的时间。 选项：8、16、24、32。默认为 32。
  • hyst_level (可选, enum)：迟滞电平，用于防止临界信号上的增益振荡。 选项：None、Low、Medium、High。

触发器

Section titled “触发器”

on_packet 触发器

Section titled “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];  // Size appropriately for your data
          ESP_LOGD("cc1101", "packet %s freq_offset %.0f Hz rssi %.1f dBm lqi %u",
                   format_hex_to(hex, x), freq_offset, rssi, lqi);

动作

Section titled “动作”

cc1101.begin_tx 动作

Section titled “cc1101.begin_tx 动作”

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

cc1101.begin_rx 动作

Section titled “cc1101.begin_rx 动作”

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

cc1101.set_idle 动作

Section titled “cc1101.set_idle 动作”

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

cc1101.reset 动作

Section titled “cc1101.reset 动作”

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

cc1101.send_packet 动作

Section titled “cc1101.send_packet 动作”

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

配置变量

Section titled “配置变量”
  • data (必选, list, 可模板化)：要发送的数据包，长度应与配置的 packet_length 匹配。
on_...:
  - cc1101.send_packet:
      data: [0x12, 0x34, 0x56, 0x78]

cc1101.set_frequency 动作

Section titled “cc1101.set_frequency 动作”

此动作在运行时更改工作频率。

配置变量

Section titled “配置变量”
  • value (必选, frequency)： 要设置的频率。范围：300MHz 至 928MHz。
on_...:
  - cc1101.set_frequency: 433.92MHz
  - cc1101.set_frequency:
      value: !lambda "return 868.0e6;"

cc1101.set_output_power 动作

Section titled “cc1101.set_output_power 动作”

此动作在运行时更改发射功率。

配置变量

Section titled “配置变量”
  • value (必选, float)：输出功率，单位为 dBm。范围：-30 至 11。

cc1101.set_modulation_type 动作

Section titled “cc1101.set_modulation_type 动作”

此动作在运行时更改调制类型。

配置变量

Section titled “配置变量”
  • value (必选, enum)：调制类型。 选项：ASK/OOK、2-FSK、4-FSK、GFSK、MSK。
on_...:
  - cc1101.set_modulation_type: "GFSK"
  - cc1101.set_modulation_type:
      value: !lambda |-
        return cc1101::Modulation::MODULATION_2_FSK;

cc1101.set_symbol_rate 动作

Section titled “cc1101.set_symbol_rate 动作”

此动作在运行时更改符号速率。

配置变量

Section titled “配置变量”
  • value (必选, float)：符号速率，单位为波特。范围：600 至 500000。

cc1101.set_rx_attenuation 动作

Section titled “cc1101.set_rx_attenuation 动作”

此动作在运行时更改内部接收（RX）衰减。

配置变量

Section titled “配置变量”
  • value (必选, enum)：衰减级别。 选项：0dB、6dB、12dB、18dB。
on_...:
  - cc1101.set_rx_attenuation: "12dB"
  - cc1101.set_rx_attenuation:
      value: !lambda |-
        return cc1101::RxAttenuation::RX_ATTENUATION_0DB;

cc1101.set_dc_blocking_filter 动作

Section titled “cc1101.set_dc_blocking_filter 动作”

此动作在运行时启用或禁用直流隔直滤波器。

配置变量

Section titled “配置变量”
  • value (必选, boolean)：true 启用，false 禁用。

cc1101.set_manchester 动作

Section titled “cc1101.set_manchester 动作”

此动作在运行时启用或禁用曼彻斯特编码。

配置变量

Section titled “配置变量”
  • value (必选, boolean)：true 启用，false 禁用。

cc1101.set_filter_bandwidth 动作

Section titled “cc1101.set_filter_bandwidth 动作”

此动作在运行时更改接收滤波器带宽。

配置变量

Section titled “配置变量”
  • value (必选, frequency)： 滤波器带宽。范围：58kHz 至 812kHz。

cc1101.set_fsk_deviation 动作

Section titled “cc1101.set_fsk_deviation 动作”

此动作在运行时更改 FSK/GFSK 频偏。

配置变量

Section titled “配置变量”
  • value (必选, frequency)： 频偏。范围：1.5kHz 至 381kHz。

cc1101.set_msk_deviation 动作

Section titled “cc1101.set_msk_deviation 动作”

此动作在运行时更改 MSK 频偏指数。

配置变量

Section titled “配置变量”
  • value (必选, int)：频偏指数。范围：1 至 8。

cc1101.set_channel 动作

Section titled “cc1101.set_channel 动作”

此动作在运行时更改信道编号。

配置变量

Section titled “配置变量”
  • value (必选, int)：信道编号。范围：0 至 255。

cc1101.set_channel_spacing 动作

Section titled “cc1101.set_channel_spacing 动作”

此动作在运行时更改信道间隔。

配置变量

Section titled “配置变量”
  • value (必选, frequency)： 信道间隔。范围：25kHz 至 405kHz。

cc1101.set_if_frequency 动作

Section titled “cc1101.set_if_frequency 动作”

此动作在运行时更改中频。

配置变量

Section titled “配置变量”
  • value (必选, frequency)： 中频。范围：25kHz 至 788kHz。

与 Remote Receiver/Transmitter 集成

Section titled “与 Remote Receiver/Transmitter 集成”

对于 ASK/OOK 调制，CC1101 与 Remote Receiver/Transmitter 集成，用于协议编码 和解码。该组件会自动配置 GDO 引脚，以支持双引脚和单引脚两种接线方案。

1. 双引脚接线（推荐）

Section titled “1. 双引脚接线（推荐）”

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

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


remote_transmitter:
  pin: GPIOXX  # Must match GDO0
  carrier_duty_percent: 100%
  on_transmit:
    then:
      - cc1101.begin_tx
  on_complete:
    then:
      - cc1101.begin_rx


remote_receiver:
  pin: GPIOXX  # Must match GDO2
  dump: all

2. 单引脚接线

Section titled “2. 单引脚接线”

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

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

带开漏输出的单引脚接线

Section titled “带开漏输出的单引脚接线”

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

cc1101:
  cs_pin: GPIOXX


remote_receiver:
  pin:
    number: GPIOXX  # Must match GDO0
    mode:
      input: true
      output: true
      pullup: true
      open_drain: true
    allow_other_uses: true
  dump: all


remote_transmitter:
  pin:
    number: GPIOXX  # Must match 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

带自动模式切换的单引脚接线

Section titled “带自动模式切换的单引脚接线”

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

cc1101:
  cs_pin: GPIOXX
  gdo0_pin:
    number: GPIOXX  # Must match GDO0
    allow_other_uses: true


remote_receiver:
  pin:
    number: GPIOXX  # Must match GDO0
    allow_other_uses: true
  dump: all


remote_transmitter:
  pin:
    number: GPIOXX  # Must match GDO0
    allow_other_uses: true
  carrier_duty_percent: 100%
  on_transmit:
    then:
      - cc1101.begin_tx
  on_complete:
    then:
      - cc1101.begin_rx

故障排除

Section titled “故障排除”

”FF0F was found” 错误

Section titled “”FF0F was found” 错误”

如果在启动阶段看到日志中出现 FF0F、0000 或 FFFF，这表示 SPI 通信失败。请检查您的接线（MISO/MOSI/CS）。

发送期间无信号

Section titled “发送期间无信号”
  • 检查引脚连接：在所有模式下，数据线都必须连接到 GDO0（模块引脚 3）， 因为 CC1101 芯片仅支持通过 GDO0 引脚输入发射数据。
  • 检查引脚模式：确保 gdo0_pin 已配置为自动引脚模式切换。

另请参阅

Section titled “另请参阅”