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..2785db6db6 --- /dev/null +++ b/content/components/cc1101.md @@ -0,0 +1,248 @@ +--- +title: CC1101 Low-Power Sub-1 GHz RF Transceiver +description: Instructions for setting up CC1101 RF Transceiver in ESPHome. +image: /components/images/cc1101-full.webp +keywords: [cc1101] +--- + +The **CC1101** component provides a driver for the **Texas Instruments CC1101** Sub-1 GHz RF Transceiver +([datasheet](https://www.ti.com/lit/ds/symlink/cc1101.pdf)). The CC1101 is a low-cost, low-power radio +chip commonly used for wireless communication in the 300-928 MHz frequency bands, including the popular +315 MHz, 433 MHz, 868 MHz, and 915 MHz ISM bands. + +The **CC1101** supports multiple modulation schemes (ASK/OOK, 2-FSK, 4-FSK, GFSK, MSK), configurable data +rates from 600 to 500,000 baud, and adjustable output power from -30 dBm to +11 dBm. It connects to +ESPHome via the [SPI Bus](/components/spi) and integrates with the +[Remote Transmitter](/components/remote_transmitter) and +[Remote Receiver](/components/remote_receiver) components for encoding and decoding RF protocols. + +{{< img src="cc1101-full.webp" alt="CC1101 Module" width="50.0%" class="align-center" >}} + +## 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`. Defaults to `433.92MHz`. +- **output_power** (*Optional*, float): The transmission power in dBm. + Range: `-30` to `11`. Defaults to `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`. Defaults to `5000`. +- **rx_attenuation** (*Optional*, enum): Internal RX attenuation. + Options: `0dB`, `6dB`, `12dB`, `18dB`. Defaults to `0dB`. +- **dc_blocking_filter** (*Optional*, boolean): Enable the digital DC blocking filter. Defaults to `true`. + +### Tuner Settings + +- **filter_bandwidth** (*Optional*, frequency): The receive filter bandwidth. + Range: `58kHz` to `812kHz`. Defaults to `203kHz`. +- **fsk_deviation** (*Optional*, frequency): Frequency deviation for FSK/GFSK modulation. +- **channel** (*Optional*, int): Channel number (added to base frequency). Defaults to `0`. +- **channel_spacing** (*Optional*, frequency): Spacing between channels. Defaults to `200kHz`. +- **if_frequency** (*Optional*, frequency): Intermediate Frequency. Defaults to `153kHz`. +- **pktlen** (*Optional*, int): Packet length configuration. Sets the expected packet size for + fixed-length packet mode. Range: `1` to `255`. Not typically needed for OOK/ASK modulation. + +### AGC (Automatic Gain Control) Settings + +Advanced users can fine-tune the AGC dynamics. The AGC automatically adjusts receiver gain to handle +signals of varying strength. These settings control how aggressively and quickly the gain adapts. +See the [CC1101 Datasheet](https://www.ti.com/lit/ds/symlink/cc1101.pdf) for detailed information. + +- **magn_target** (*Optional*, dB): Target signal amplitude for the AGC loop. Higher values increase + sensitivity but may cause clipping on strong signals. + Range: `24dB` to `42dB` in increments of 3 (e.g., `33dB`). Defaults to `42dB`. +- **max_lna_gain** (*Optional*, dB): Limits the maximum LNA (Low Noise Amplifier) gain. Use to prevent + saturation in high-signal environments. Defaults to `Default`. + Options: `Default`, `2.6dB`, `6.1dB`, `7.4dB`, `9.2dB`, `11.5dB`, `14.6dB`, `17.1dB`. +- **max_dvga_gain** (*Optional*, enum): Limits the maximum DVGA (Digital Variable Gain Amplifier) gain. + Options: `Default`, `-1`, `-2`, `-3`. Defaults to `-3`. +- **lna_priority** (*Optional*, boolean): If true, reduce LNA gain before DVGA gain when decreasing + overall gain. Useful for optimizing noise figure. Defaults to `false`. +- **carrier_sense_abs_thr** (*Optional*, int): Absolute RSSI threshold for carrier sense. The radio + considers a carrier present when RSSI exceeds this level. +- **carrier_sense_rel_thr** (*Optional*, enum): Relative RSSI threshold for carrier sense, compared + to the current noise floor. Options: `Default`, `+6dB`, `+10dB`, `+14dB`. +- **filter_length_fsk_msk** (*Optional*, enum): Averaging length for AGC in FSK/MSK modes. + Longer values provide more stable gain but slower response. Options: `8`, `16`, `32`, `64`. +- **filter_length_ask_ook** (*Optional*, enum): Averaging length for AGC in ASK/OOK modes. + Longer values provide more stable gain but slower response. Options: `4dB`, `8dB`, `12dB`, `16dB`. +- **freeze** (*Optional*, enum): Controls when AGC gain is frozen (held constant). + Options: `Default`, `On Sync`, `Analog Only`, `Analog And Digital`. +- **wait_time** (*Optional*, enum): Time to wait after a gain change before allowing another adjustment. + Options: `8`, `16`, `24`, `32`. Defaults to `32`. +- **hyst_level** (*Optional*, enum): Hysteresis level to prevent gain oscillation on borderline signals. + Options: `None`, `Low`, `Medium`, `High`. + +## Actions + +This component provides actions to control the radio state, primarily used for coordinating transmission. + +- **cc1101.begin_tx**: Puts the radio into TX mode. Must be called before transmitting. +- **cc1101.begin_rx**: Puts the radio into RX mode. Call after transmitting to resume receiving. +- **cc1101.set_idle**: Puts the radio into an idle state. In single-pin configurations, this should be + called before switching between TX and RX modes to ensure clean state transitions. +- **cc1101.reset**: Resets the CC1101 chip and re-applies configuration. + +## 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.begin_tx + on_complete: + then: + - cc1101.begin_rx + +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 + +ESP32 must use this method when using single-pin wiring. The shared pin should be set to open-drain with a +pullup. The `eot_level` option (from `remote_transmitter`) controls the pin state after transmission +completes - setting it to `false` keeps the pin low until explicitly released. In addition to setting the +CC1101 mode in `on_transmit`/`on_complete`, the pin should be driven low before `begin_tx` and released +before `begin_rx`. + +```yaml +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 +``` + +#### Single Pin with Mode Switching + +This method requires lambdas to manually switch the pin mode between input and output around transmissions. +On boot, the pin must be set to input mode so the receiver can operate. + +```yaml +esphome: + on_boot: + - priority: 0 + then: + - lambda: id(rx_pin)->pin_mode(gpio::FLAG_INPUT); + +cc1101: + cs_pin: GPIOXX + +remote_receiver: + pin: + id: rx_pin + number: GPIOXX # Must match GDO0 + allow_other_uses: true + dump: all + +remote_transmitter: + pin: + id: tx_pin + number: GPIOXX # Must match GDO0 + allow_other_uses: true + carrier_duty_percent: 100% + on_transmit: + then: + - cc1101.set_idle + - lambda: id(tx_pin)->pin_mode(gpio::FLAG_OUTPUT); + - cc1101.begin_tx + on_complete: + then: + - cc1101.set_idle + - lambda: id(rx_pin)->pin_mode(gpio::FLAG_INPUT); + - cc1101.begin_rx +``` + +## 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 with Mode Switching method, + ensure your `on_transmit`/`on_complete` logic correctly flips the pin mode. + +## See Also + +- [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-full.webp b/content/components/images/cc1101-full.webp new file mode 100644 index 0000000000..f99bf15e97 Binary files /dev/null and b/content/components/images/cc1101-full.webp differ diff --git a/static/images/cc1101.webp b/static/images/cc1101.webp new file mode 100644 index 0000000000..f99bf15e97 Binary files /dev/null and b/static/images/cc1101.webp differ