[cc1101] Add packet mode documentation (#5776)

swoboda1337 · claude · bdraco · swoboda1337 · commit 05cef93f284e · 2025-12-14T18:17:01.000-05:00
* [cc1101] Add packet mode documentation - Document new packet mode with FIFO buffering, sync word detection, and CRC - Add on_packet trigger and cc1101.send_packet action - Document missing config options: sync_mode, sync0, sync1, num_preamble, manchester - Document automatic pin mode switching in begin_tx/begin_rx - Add CRC troubleshooting section - Simplify single-pin wiring examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Clean * Clean * [cc1101] Add on_packet trigger section * Clean * Clean * Clean * Update content/components/cc1101.md Co-authored-by: J. Nick Koston <nick+github@koston.org> --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: J. Nick Koston <nick+github@koston.org>
diff --git a/content/components/cc1101.md b/content/components/cc1101.md
@@ -12,9 +12,14 @@ chip commonly used for wireless communication in the 300-928 MHz frequency 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.
+ESPHome via the [SPI Bus](/components/spi).
+
+The component supports two operating modes:
+
+- **Async Mode** (default): Integrates with the [Remote Transmitter](/components/remote_transmitter)
+  and [Remote Receiver](/components/remote_receiver) components for encoding and decoding RF protocols.
+- **Packet Mode**: Built-in packet handling with sync word detection, CRC, and the `on_packet` trigger.
+  Best for FSK/GFSK modulation when communicating with other packet-based radios.
 
 {{< img src="cc1101-full.webp" alt="CC1101 Module" width="50.0%" class="align-center" >}}
 
@@ -33,6 +38,8 @@ cc1101:
 
 - **cs_pin** (**Required**, [Pin](/guides/configuration-types/#pin)):
   The SPI Chip Select (CSN) pin connected to the module.
+- **gdo0_pin** (*Optional*, [Pin](/guides/configuration-types/#pin)):
+  The GDO0 pin. Required when `packet_mode` is enabled, also used for single pin mode switching.
 
 ### General Settings
 
@@ -47,6 +54,7 @@ cc1101:
 - **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`.
+- **manchester** (*Optional*, boolean): Enable Manchester encoding. Defaults to `false`.
 
 ### Tuner Settings
 
@@ -60,8 +68,25 @@ cc1101:
   Range: `25kHz` to `405kHz`. Defaults to `200kHz`.
 - **if_frequency** (*Optional*, frequency): Intermediate Frequency.
   Range: `25kHz` to `788kHz`. 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.
+
+### Packet Mode Settings
+
+These settings enable the CC1101's built-in packet handling with FIFO buffering, sync word detection,
+and optional CRC checking.
+
+- **packet_mode** (*Optional*, boolean): Enable FIFO packet mode. When enabled, `gdo0_pin` is
+  required. Defaults to `false`.
+- **packet_length** (*Optional*, int): Packet length in bytes. Set to `0` for variable length packets
+  (length byte prepended to data). Range: `0` to `64`. Defaults to `0`.
+- **crc_enable** (*Optional*, boolean): Enable CRC-16 calculation and checking. The CC1101 uses
+  CRC-16-IBM (polynomial 0x8005). Defaults to `false`.
+- **whitening** (*Optional*, boolean): Enable data whitening to improve DC balance. Defaults to `false`.
+- **sync_mode** (*Optional*, enum): Sync word detection mode.
+  Options: `None`, `15/16`, `16/16`, `30/32`. Defaults to `16/16`.
+- **sync0** (*Optional*, hex): Lower sync word byte. Defaults to `0x91`.
+- **sync1** (*Optional*, hex): Upper sync word byte. Defaults to `0xD3`.
+- **num_preamble** (*Optional*, int): Number of preamble bytes to transmit.
+  Range: `0` to `7` (maps to 2, 3, 4, 6, 8, 12, 16, 24 bytes). Defaults to `2` (4 bytes).
 
 ### AGC (Automatic Gain Control) Settings
 
@@ -79,8 +104,10 @@ See the [CC1101 Datasheet](https://www.ti.com/lit/ds/symlink/cc1101.pdf) for det
   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_above_threshold** (*Optional*, boolean): Only accept packets when carrier sense
+  indicates a signal is present. 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.
+  considers a carrier present when RSSI exceeds this level. Range: `-8` to `7`.
 - **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.
@@ -94,20 +121,67 @@ See the [CC1101 Datasheet](https://www.ti.com/lit/ds/symlink/cc1101.pdf) for det
 - **hyst_level** (*Optional*, enum): Hysteresis level to prevent gain oscillation on borderline signals.
   Options: `None`, `Low`, `Medium`, `High`.
 
+## Triggers
+
+### `on_packet` Trigger
+
+In packet mode, this trigger fires when a packet has been received. A variable `x` of type
+`std::vector<uint8_t>` containing the packet data is passed to the automation. The variables
+`rssi` (signal strength in dBm) and `lqi` (link quality indicator, 0-127, lower is better)
+are also available.
+
+```yaml
+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: |-
+          ESP_LOGD("cc1101", "packet %s rssi %.1f dBm lqi %u", format_hex(x).c_str(), rssi, lqi);
+```
+
 ## Actions
 
-This component provides actions to control the radio state, primarily used for coordinating transmission.
+### `cc1101.begin_tx` Action
+
+This [action](/automations/actions#all-actions) puts the radio into TX mode and switches `gdo0_pin` to output mode.
+
+### `cc1101.begin_rx` Action
 
-- **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.
+This [action](/automations/actions#all-actions) puts the radio into RX mode and switches `gdo0_pin` to input mode.
+
+### `cc1101.set_idle` Action
+
+This [action](/automations/actions#all-actions) puts the radio into an idle state.
+
+### `cc1101.reset` Action
+
+This [action](/automations/actions#all-actions) resets the CC1101 chip and re-applies configuration.
+
+### `cc1101.send_packet` Action
+
+This [action](/automations/actions#all-actions) transmits a packet. Only available when `packet_mode` is enabled.
+
+#### Configuration variables
+
+- **data** (**Required**, list): The packet to send, length should match the configured `packet_length`.
+
+```yaml
+on_...:
+  - cc1101.send_packet:
+      data: [0x12, 0x34, 0x56, 0x78]
+```
 
 ## 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.
+For ASK/OOK modulation, the CC1101 integrates with Remote Receiver/Transmitter for protocol encoding
+and decoding. The component automatically configures the GDO pins to support both dual and single pin
+wiring schemes.
 
 ### 1. Dual Pin Wiring (Recommended)
 
@@ -121,7 +195,7 @@ cc1101:
   cs_pin: GPIOXX
 
 remote_transmitter:
-  pin: GPIOXX # Must match GDO0
+  pin: GPIOXX  # Must match GDO0
   carrier_duty_percent: 100%
   on_transmit:
     then:
@@ -131,15 +205,14 @@ remote_transmitter:
       - cc1101.begin_rx
 
 remote_receiver:
-  pin: GPIOXX # CC1101 GDO2
+  pin: GPIOXX  # Must match 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.
@@ -155,10 +228,11 @@ before `begin_rx`.
 ```yaml
 cc1101:
   cs_pin: GPIOXX
+  gdo0_pin: GPIOXX
 
 remote_receiver:
   pin:
-    number: GPIOXX # Must match GDO0
+    number: GPIOXX  # Must match GDO0
     mode:
       input: true
       output: true
@@ -169,7 +243,7 @@ remote_receiver:
 
 remote_transmitter:
   pin:
-    number: GPIOXX # Must match GDO0
+    number: GPIOXX  # Must match GDO0
     mode:
       input: true
       output: true
@@ -190,43 +264,32 @@ remote_transmitter:
       - cc1101.begin_rx
 ```
 
-#### Single Pin with Mode Switching
+#### Single Pin with Automatic 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.
+When `gdo0_pin` is configured, `begin_tx` and `begin_rx` automatically switch the pin between output
+and input modes, simplifying the configuration.
 
 ```yaml
-esphome:
-  on_boot:
-    - priority: 0
-      then:
-        - lambda: id(rx_pin)->pin_mode(gpio::FLAG_INPUT);
-
 cc1101:
   cs_pin: GPIOXX
+  gdo0_pin: GPIOXX
 
 remote_receiver:
   pin:
-    id: rx_pin
-    number: GPIOXX # Must match GDO0
+    number: GPIOXX  # Must match GDO0
     allow_other_uses: true
   dump: all
 
 remote_transmitter:
   pin:
-    id: tx_pin
-    number: GPIOXX # Must match GDO0
+    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
 ```
 
@@ -237,12 +300,11 @@ remote_transmitter:
 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
+### 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.
+- **Check Pin Mode**: Ensure `gdo0_pin` is configured for automatic pin mode switching.
 
 ## See Also
 
