diff --git a/content/components/_index.md b/content/components/_index.md index 513795af1b..dd0551e0b1 100644 --- a/content/components/_index.md +++ b/content/components/_index.md @@ -1041,6 +1041,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..f7cc18dd12 --- /dev/null +++ b/content/components/cc1101.md @@ -0,0 +1,208 @@ +--- +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](/components/remote_transmitter) and [Remote Receiver](/components/remote_receiver) components. + +This component requires the [SPI Component](/components/spi) to be enabled. + +Image + +## Component Configuration + +```yaml +# Minimal Example +cc1101: + cs_pin: GPIOXX + frequency: 433.92MHz +``` + +## Configuration Variables + +### Hardware Settings + +- **cs_pin** (**Required**, [Pin](/guides/configuration-types/#pin)): The SPI Chip Select (CSN) pin connected to the module. + +### 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 + +The component automatically configures the GDO pins to support both dual and single pin wiring schemes without any extra configuration. + +### 1. Dual Pin Wiring (Recommended) + +This is the simplest and recommended wiring scheme. It uses separate pins for transmitting and receiving data. + +- **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 + +This wiring scheme uses a single MCU pin for both transmitting and receiving data, connected to GDO0. This requires careful configuration of the `remote_transmitter` and `remote_receiver` to avoid conflicts. Using an open-drain pin mode is recommended to simplify the setup. + +- **GDO0 (Module Pin 3)**: Connect to a single MCU GPIO pin. +- **GDO2 (Module Pin 8)**: Leave disconnected. + +#### Single Pin with Open-Drain (Recommended for Single Pin) + +This is the recommended method for single-pin wiring as it avoids complex automations to switch pin modes. + +```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 +``` + +#### Single Pin with Push-Pull + +This method requires automations to manually enable and disable the receiver around transmissions to prevent the transmitter from receiving its own signals. + +```yaml +cc1101: + cs_pin: GPIOXX + +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 +``` + +## 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