diff --git a/content/components/_index.md b/content/components/_index.md index b00c2c89ff..ad39461cc4 100644 --- a/content/components/_index.md +++ b/content/components/_index.md @@ -1036,6 +1036,7 @@ Used for creating infrared (IR) or radio frequency (RF) remote control transmitt ESPHome to cellular networks. **Does not encompass Wi-Fi.** {{< imgtable >}} +"CC1101","components/cc1101","cc1101.webp","" "IR Remote Climate","components/climate/climate_ir","air-conditioner-ir.svg","dark-invert" "Remote Receiver","components/remote_receiver","remote.svg","dark-invert" "Remote Transmitter","components/remote_transmitter","remote.svg","dark-invert" diff --git a/content/components/cc1101.md b/content/components/cc1101.md new file mode 100644 index 0000000000..f24b3103ea --- /dev/null +++ b/content/components/cc1101.md @@ -0,0 +1,204 @@ +--- +title: CC1101 Low-Power Sub-1 GHz RF Transceiver +description: Instructions for setting up CC1101 RF Transceiver in ESPHome. +image: /components/images/cc1101.webp +keywords: [cc1101] +--- + +The **CC1101** component provides a driver for the **Texas Instruments CC1101** Sub-1 GHz RF Transceiver. +It allows you to transmit and receive raw RF signals (ASK/OOK, FSK, etc.) using the standard +[Remote Transmitter](remote_transmitter.md) and [Remote Receiver](remote_receiver.md) components. + +This component requires the [SPI Component](spi.md) to be enabled. + +Image + +## Component Configuration + +```yaml +# Minimal Example (DUAL_PIN is the default operation_mode) +cc1101: + cs_pin: GPIOXX + frequency: 433.92MHz +``` + +## Configuration Variables + +### Hardware Settings +- **cs_pin** (**Required**, [Pin](pin.md)): The SPI Chip Select (CSN) pin connected to the module. + +- **operation_mode** (Optional, enum): Defines the role of the CC1101 GDO pins based on your wiring setup. This is crucial for correct TX/RX operation. + - `DUAL_PIN` (Default): Configures the module for separate TX and RX data pins. Internally sets GDO0 (Module Pin 3) for TX Data Input and GDO2 (Module Pin 8) for RX Data Output. This is the recommended mode. + - `SINGLE_PIN`: Configures GDO0 (Module Pin 3) for bi-directional Serial I/O and sets GDO2 to high impedance. This mode requires only one MCU GPIO pin for both TX and RX. + +### General Settings + +- **frequency** (*Optional*, frequency): The operating frequency. Range: `300MHz` to `928MHz`. Default: `433.92MHz`. +- **output_power** (*Optional*, float): The transmission power in dBm. Range: `-30` to `11`. Default: `10`. +- **modulation_type** (*Optional*, enum): The modulation format. Options: `ASK/OOK` (default), `2-FSK`, `4-FSK`, `GFSK`, `MSK`. +- **symbol_rate** (*Optional*, int): The symbol rate in Baud. Range: `600` to `500000`. Default: `5000`. +- **rx_attenuation** (*Optional*, enum): Internal RX attenuation. Options: `0dB`, `6dB`, `12dB`, `18dB`. Default: `0dB`. +- **dc_blocking_filter** (*Optional*, boolean): Enable the digital DC blocking filter. Default: `True`. + +### Tuner Settings + +- **filter_bandwidth** (*Optional*, frequency): The receive filter bandwidth. Range: `58kHz` to `812kHz`. Default: `203kHz`. +- **fsk_deviation** (*Optional*, frequency): Frequency deviation for FSK/GFSK modulation. +- **channel** (*Optional*, int): Channel number (added to base frequency). +- **channel_spacing** (*Optional*, frequency): Spacing between channels. +- **if_frequency** (*Optional*, frequency): Intermediate Frequency. Default is optimized for 433MHz usage. +- **pktlen** (*Optional*, int): Packet length config. + +### AGC (Automatic Gain Control) Settings + +Advanced users can fine-tune the AGC dynamics. + +- **magn_target** (*Optional*, dB): Target signal amplitude. Range: `24dB` to `42dB` in increments of 3(eg. `33dB`). +- **max_lna_gain** (*Optional*, dB): Maximum LNA gain reduction. Options: `Default`, `2.6dB`, `6.1dB`, `7.4dB`, `9.2dB`, `11.5dB`, `14.6dB`, `17.1dB`. +- **max_dvga_gain** (*Optional*, enum): Maximum Digital Variable Gain reduction. Options: `Default`, `-1`, `-2`, `-3`. +- **lna_priority** (*Optional*, boolean): If true, decrease LNA gain before DVGA gain. +- **carrier_sense_abs_thr** (*Optional*, int): Absolute RSSI threshold for Carrier Sense. +- **carrier_sense_rel_thr** (*Optional*, enum): Relative RSSI threshold for Carrier Sense. +- **filter_length_fsk_msk** (*Optional*, enum): Averaging length for FSK/MSK. +- **filter_length_ask_ook** (*Optional*, enum): Averaging length for ASK/OOK. +- **freeze** (*Optional*, enum): AGC gain freeze behavior. +- **wait_time** (*Optional*, enum): AGC wait time. +- **hyst_level** (*Optional*, enum): AGC hysteresis level. + +## Actions + +This component provides actions to control the radio state, primarily used for coordinating transmission. + +- **cc1101.begin_tx**: Wakes the radio and forces it into TX mode. This **must** be called before `remote_transmitter` starts sending data. +- **cc1101.end_tx**: Puts the radio back into RX mode and resets the pin configuration to safe defaults. +- **cc1101.reset**: Resets the CC1101 chip and re-applies configuration. +- **cc1101.set_idle**: Puts the radio into idle state. + +## Integration with Remote Receiver/Transmitter + +### 1. Dual Pin Wiring (operation_mode: DUAL_PIN) +This mode is recommended for simplicity and clarity. The CC1101 chip handles the input/output logic internally, requiring minimal external pin configuration. + +- **GDO0 (Module Pin 3)**: Connect to the MCU pin used by `remote_transmitter`. +- **GDO2 (Module Pin 8)**: Connect to the MCU pin used by `remote_receiver`. + +```yaml +cc1101: + cs_pin: GPIOXX + +remote_transmitter: + pin: GPIOXX # Must match GDO0 + 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.end_tx: + +remote_receiver: + pin: GPIOXX # CC1101 GDO2 + dump: all +``` + +### 2. Single Pin Wiring - Push-Pull (with State Switching) +This mode requires only one MCU GPIO pin connected to GDO0 (Module Pin 3). Since the MCU pin operates in Push-Pull mode, manual switching between Input and Output logic is required inside the automation to avoid conflicts. + +- **GDO0 (Module Pin 3)**: Connect to a single MCU GPIO pin. +- **GDO2 (Module Pin 8)**: Leave disconnected. + +```yaml +cc1101: + cs_pin: GPIOXX + operation_mode: SINGLE_PIN + +remote_transmitter: + pin: + number: GPIOXX # Must match GDO0 + allow_other_uses: true + carrier_duty_percent: 100% + on_transmit: + then: + - remote_receiver.disable: + - cc1101.set_idle: + - remote_transmitter.digital_write: false + - cc1101.begin_tx: + on_complete: + then: + - cc1101.set_idle: + - remote_transmitter.digital_write: true + - cc1101.end_tx: + - remote_receiver.enable: + +remote_receiver: + pin: + number: GPIOXX # Must match GDO0 + allow_other_uses: true + dump: all +``` + +### 3. Single Pin Wiring - Open Drain +This mode also requires only one MCU GPIO pin connected to GDO0 (Module Pin 3), but is simpler as the Open Drain configuration automatically handles the logic state switching without needing complex on_transmit/on_complete automation logic. + +- **GDO0 (Module Pin 3)**: Connect to a single MCU GPIO pin configured as Open Drain. +- **GDO2 (Module Pin 8)**: Leave disconnected. + +```yaml +cc1101: + cs_pin: GPIOXX + operation_mode: SINGLE_PIN + +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.end_tx: + +remote_receiver: + pin: + number: GPIOXX # Must match GDO0 + mode: + input: true + output: true + pullup: true + open_drain: true + allow_other_uses: true + dump: all +``` + +## Troubleshooting + +### "FF0F was found" Error +If you see a log entry stating `FF0F`, `0000`, or `FFFF` during setup, this indicates an SPI communication failure. Check your wiring (MISO/MOSI/CS). + +### No Signal during Transmit +- **Check Pinout**: For all modes, the data line must be connected to GDO0 (Module Pin 3), as the CC1101 chip only supports transmission input via the GDO0 pin. +- **Check Pin Mode**: If using the Single Pin Push-Pull mode, ensure your on_transmit/on_complete logic correctly flips the pin's status. + +## See Also + +- [I²C Bus](/components/i2c) +- [Remote Receiver](/components/remote_receiver) +- [Remote Transmitter](/components/remote_transmitter) +- [SPI Component](/components/spi) +- [CC1101 Datasheet](https://www.ti.com/lit/ds/symlink/cc1101.pdf) diff --git a/content/components/images/cc1101.webp b/content/components/images/cc1101.webp new file mode 100644 index 0000000000..602fce4c5d Binary files /dev/null and b/content/components/images/cc1101.webp differ