CC1101 docs

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"

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)