The Arduino library for the TI CC1101 sub-1 GHz RF transceiver.
CC1101 key features:
- Modulations: ASK (OOK), 2-FSK, GFSK, 4-FSK, MSK
- Frequency bands: 300-348 MHz, 387-464 MHz, 779-928 MHz
- Data rate: 0.6 to 600 kbps
- Output power up to +12 dBm
- Support for sync word detection, address check, flexible packet length, and automatic CRC handling
For more information, check out the datasheet.
The CC1101 module uses the SPI interface for communication. The SI, SO, and SCLK pins should be connected to dedicated SPI pins on your Arduino board. The CSn can be connected to any digital pin.
On an ESP32, any GPIOs can be used; you can specify alternate ones in the constructor.
The CC1101 also exposes two general-purpose pins (GDO0 and GDO2) that can trigger MCU interrupts on specific events (such as when the RX FIFO fills up). Using these pins is optional for basic operations, but GDO0 must be connected to an interrupt-capable pin on the MCU if you want to use the interrupt-driven (callback-based) non-blocking RX/TX APIs.
void setModulation(Modulation mod)Sets the modulation. Allowed modulations: MOD_2FSK, MOD_GFSK, MOD_ASK_OOK, MOD_4FSK, MOD_MSK.
Status setFrequency(double freq)Sets the frequency (in MHz). Allowed frequency bands: 300-348 MHz, 387-464 MHz, 779-928 MHz.
Returns STATUS_INVALID_PARAM on bad frequency.
Status setFrequencyDeviation(double dev)Sets the frequency deviation. Allowed frequency deviation range: 1.587 to 380.859 kHz (assuming 26.0 MHz crystal frequency). For MOD_ASK_OOK modulation, this setting has no effect.
Returns STATUS_INVALID_PARAM on bad frequency deviation.
void setChannel(uint8_t ch)Sets the channel frequency. The channel frequency is multiplied by the channel spacing setting and added to the base frequency.
Status setChannelSpacing(double sp)Sets the channel spacing (in kHz). Allowed channel spacing range: 25.390 to 405.456 kHz (assuming 26.0 MHz crystal frequency).
Returns STATUS_INVALID_PARAM on bad channel spacing.
Status setDataRate(double drate)Sets the data rate (in kBaud). The allowed data rate depends on the selected modulation (see the General Characteristics Table in the datasheet).
Returns STATUS_INVALID_PARAM on bad data rate.
Status setRxBandwidth(double bw)Sets the receiver channel filter bandwidth (in kHz). Allowed bandwidth range: 58 to 812 kHz (assuming 26.0 MHz crystal frequency).
Returns STATUS_INVALID_PARAM on bad bandwidth.
void setOutputPower(int8_t power)Sets the RF output power (in dBm). Allowed output powers: -30, -20, -15, -10, 0, 5, 7 and 10 dBm.
Status transmit(uint8_t *data, size_t length, uint8_t addr = 0)Transmits the data. This method blocks until the transmission is complete or times out. The addr parameter is used when the address filtering mode is enabled.
Returns
STATUS_LENGTH_TOO_BIGif thelengthparameter is greater than 255, or if thelengthis greater than required in fixed packet modeSTATUS_LENGTH_TOO_SMALLif thelengthis smaller than required in fixed packet modeSTATUS_TXFIFO_UNDERFLOWif the TX FIFO buffer runs out of data during transmissionSTATUS_TIMEOUTif the packet is not fully transmitted within the timeout
Status startTransmit(uint8_t *data, size_t length, uint8_t addr = 0)Starts a non-blocking transmission. The entire packet (including payload, optional address, and optional length byte) must fit within the 64-byte TX FIFO buffer. For longer payloads, use the blocking transmit() method instead.
Important
The methods startTransmit(), setTransmitAction(), clearTransmitAction(), and finishTransmit() form the non-blocking transmission API and are designed to be used together. Do not mix the blocking transmit() method with these non-blocking transmission methods.
Returns
STATUS_LENGTH_TOO_BIGif the total packet length is greater than the 64-byte TX FIFO capacity, or if thelengthis greater than required in fixed packet modeSTATUS_LENGTH_TOO_SMALLif thelengthis smaller than required in fixed packet modeSTATUS_OKif transmission has successfully started
Status setTransmitAction(void (*func)(void), GdoPin pin = GDO0)Registers an interrupt callback function to be executed when the transmission is complete. The function uses the specified GDO pin (default GDO0) to detect the falling edge of the sync word signal.
Returns
STATUS_INVALID_PARAMif the specified GDO pin was not configuredSTATUS_BAD_STATEif sync word transmission is disabled (sync mode is set toSYNC_MODE_NO_PREAMBLEorSYNC_MODE_NO_PREAMBLE_CS)STATUS_OKon success
void clearTransmitAction()Detaches the interrupt callback for transmission from the GDO pin registered by setTransmitAction().
Status finishTransmit()Finalizes the non-blocking transmission, transitions the radio state back to idle, and flushes the TX buffer.
Returns
STATUS_TXFIFO_UNDERFLOWif the TX FIFO underflowed during transmissionSTATUS_OKon success
Status receive(uint8_t *data, size_t length, size_t *read = nullptr, uint8_t addr = 0)Receives the data. This method blocks until a packet is received or times out. The read parameter indicates the number of bytes actually received. The addr parameter is used when the address filtering mode is enabled.
Returns
STATUS_LENGTH_TOO_BIGif thelengthparameter is greater than 255STATUS_LENGTH_TOO_SMALLif thedatabuffer is too small to hold the entire packetSTATUS_CRC_MISMATCHif the received CRC does not match the calculated CRCSTATUS_RXFIFO_OVERFLOWif the RX FIFO overflows due to unread incoming dataSTATUS_TIMEOUTif no complete packet is received
Status startReceive(uint8_t addr = 0)Puts the radio into receive mode. When the GDO0 pin is configured, GDO0 is set to assert when the RX FIFO is filled at or above the threshold, or when a packet ends.
Important
The methods startReceive(), setReceiveAction(), clearReceiveAction(), and readData() form the non-blocking reception API and are designed to be used together. Do not mix the blocking receive() method with these non-blocking reception methods.
Returns
STATUS_OKon success
Status setReceiveAction(void (*func)(void), GdoPin pin = GDO0)Registers an interrupt callback function to be executed when the specified GDO pin (default GDO0) goes high (rising edge), indicating that the RX FIFO threshold is reached or a packet has been fully received.
Returns
STATUS_INVALID_PARAMif specified GDO pin was not configuredSTATUS_OKon success
void clearReceiveAction()Detaches the interrupt callback for packet receipt from the GDO pin registered by setReceiveAction().
Status readData(uint8_t *data, size_t length, size_t *read = nullptr)Reads the received packet payload from the RX FIFO into the provided buffer data. The read parameter indicates the actual number of bytes read.
Returns
STATUS_LENGTH_TOO_BIGif the requestedlengthis greater than 255STATUS_LENGTH_TOO_SMALLif thedatabuffer is too small to hold the received packetSTATUS_CRC_MISMATCHif the received CRC does not match the calculated CRCSTATUS_RXFIFO_OVERFLOWif the RX FIFO overflowedSTATUS_TIMEOUTif no complete packet is received
int8_t getRSSI()Returns RSSI (Received Signal Strength Indicator) of the last received packet.
uint8_t getLQI()Returns LQI (Link Quality Indicator) of the last received packet.
void setSyncMode(SyncMode mode)Sets the sync word mode.
SYNC_MODE_NO_PREAMBLE- Disables preamble and sync word transmission in TX and preamble and sync word detection in RX.SYNC_MODE_15_16- Enables 16-bit sync word transmission in TX and 16-bit sync word detection in RX. Only 15 of 16 bits need to match in RX.SYNC_MODE_16_16- Enables 16-bit sync word transmission in TX and 16-bit sync word detection in RX. All 16 bits need to match in RX.SYNC_MODE_30_32- Enables repeated sync word transmission in TX and 32-bit sync word detection in RX. Only 30 of 32 bits need to match in RX. The sync word is transmitted twice.SYNC_MODE_NO_PREAMBLE_CS- Disables preamble and sync word transmission in TX and preamble and sync word detection in RX.SYNC_MODE_15_16_CS- Enables 16-bit sync word transmission in TX and 16-bit sync word detection in RX. Only 15 of 16 bits need to match in RX. Requires carrier sense above threshold in addition to sync word.SYNC_MODE_16_16_CS- Enables 16-bit sync word transmission in TX and 16-bit sync word detection in RX. All 16 bits need to match in RX. Requires carrier sense above threshold in addition to sync word.SYNC_MODE_30_32_CS- Enables repeated sync word transmission in TX and 32-bit sync word detection in RX. Only 30 of 32 bits need to match in RX. The sync word is transmitted twice. Requires carrier sense above threshold in addition to sync word.
Status setPreambleLength(uint8_t length)Sets the preamble length (in bits). Allowed lengths: 16, 24, 32, 48, 64, 96, 128 and 192.
Returns STATUS_INVALID_PARAM on bad length.
void setSyncWord(uint16_t sync)Sets the 16-bit sync word.
void setPacketLengthMode(PacketLengthMode mode, uint8_t length = 255)Sets the packet length mode. Packet length types:
PKT_LEN_MODE_FIXED- Fixed packet length mode. The length field is not transmitted in TX and thelengthparameter indicates the number of bytes that the handler will accept in RX.PKT_LEN_MODE_VARIABLE- Variable packet length mode. The length field is transmitted in TX. The packet handler assumes that the first byte (after the sync word) is the length byte and receives the number of bytes indicated by its value. Thelengthparameter is used to set the maximum packet length allowed in RX. Any packet whose length byte exceedslengthwill be discarded.
Important
The library supports only packets up to 255 bytes.
void setAddressFilteringMode(AddressFilteringMode mode)Sets the address filtering mode.
ADDR_FILTER_MODE_NONE- Disables address transmission in TX and address checking in RX.ADDR_FILTER_MODE_CHECK- Enables address transmission in TX and address checking in RX. No broadcast address.ADDR_FILTER_MODE_CHECK_BC_0- Enables address transmission in TX and address checking in RX. Address 0 is a broadcast address.ADDR_FILTER_MODE_CHECK_BC_0_255- Enables address transmission in TX and address checking in RX. Addresses 0 and 255 are broadcast addresses.
void setCrc(bool enable)Enables/disables CRC calculation in TX and CRC checking in RX.
void setDataWhitening(bool enable)Enables/disables data whitening.
If whitening is enabled, everything following the sync word will be whitened. This is done before the optional FEC/Interleaver stage.
Status setManchester(bool enable)Enables/disables Manchester encoding in TX and Manchester decoding in RX.
Note
Manchester encoding is not supported at the same time as using the FEC/Interleaver option or when using MSK and 4-FSK modulation.
Returns STATUS_BAD_STATE if Manchester encoding cannot be enabled.
Status setFEC(bool enable)Enables/disables Forward Error Correction (FEC) with interleaving for the packet payload.
Note
Only supported for fixed packet length mode and when Manchester encoding is disabled.
Returns STATUS_BAD_STATE if FEC cannot be enabled.
Warning
The following methods are not part of the standard library API. Modifying register values directly may cause other library methods to work incorrectly. Use these methods only when the desired functionality is not available through the standard API. Refer to the datasheet and the library's source code before use to ensure the changes do not conflict with the library's internal state.
uint8_t readReg(uint8_t addr)Reads a single register value.
uint8_t readRegField(uint8_t addr, uint8_t hi, uint8_t lo)Reads a specific bit field from a register. The hi and lo parameters specify the inclusive bit range.
void readRegBurst(uint8_t addr, uint8_t *buff, size_t size)Reads multiple consecutive registers into a buffer.
void writeReg(uint8_t addr, uint8_t data)Writes a single register value.
void writeRegField(uint8_t addr, uint8_t data, uint8_t hi, uint8_t lo)Writes a value to a specific bit field of a register. The hi and lo parameters specify the inclusive bit range.
void writeRegBurst(uint8_t addr, uint8_t *data, size_t size)Writes multiple consecutive registers from a buffer.
The library was tested on the following boards: