CC1101 Module
=============

.. sku: 

.. include:: ../refs/module.cc1101.ref

This library is the driver for Module CC1101, a low-cost sub-1 GHz transceiver designed for very low-power wireless applications. It operates in the 855-928 MHz frequency bands and provides excellent performance at very low current consumption.

The module features a highly configurable baseband modem supporting various modulation formats and has a flexible data rate from 0.6 to 6.0 kbps. It includes built-in support for packet handling, data buffering, burst transmissions, clear channel assessment, link quality indication, and wake-on-radio functionality.

Support the following products:

    |CC1101Module|

UiFlow2 Example
---------------

Transmit Data
^^^^^^^^^^^^^

Open the |m5cores3_cc1101_tx_example.m5f2| project in UiFlow2.

This example shows how to send data using the CC1101 module. The module will continuously send messages with incrementing counter values.

UiFlow2 Code Block:

    |example_tx.png|

Example output:

    None

Receive Data with IRQ
^^^^^^^^^^^^^^^^^^^^^

Open the |m5cores3_cc1101_rx_example.m5f2| project in UiFlow2.

This example shows how to receive data using interrupt-based reception. The module will display received messages, RSSI values on the screen.

UiFlow2 Code Block:

    |example_rx.png|

Example output:

    None

MicroPython Example
-------------------

Transmit Data
^^^^^^^^^^^^^

This example shows how to send data using the CC1101 module. The module continuously sends messages with incrementing counter values every second.

MicroPython Code Block:

    .. literalinclude:: ../../../examples/module/cc1101/m5cores3_cc1101_tx_example.py
        :language: python
        :linenos:

Example output:

    None

Receive Data with IRQ
^^^^^^^^^^^^^^^^^^^^^

This example shows how to receive data using interrupt-based reception. The module will display received messages, RSSI values on the screen.

MicroPython Code Block:

    .. literalinclude:: ../../../examples/module/cc1101/m5cores3_cc1101_rx_example.py
        :language: python
        :linenos:

Example output:

    None


**API**
-------

class CC1101Module  
^^^^^^^^^^^^^^^^^^
 
.. class:: module.cc1101.CC1101Module(pin_cs = 5, \
                            pin_gdo0 = 7, \
                            pin_gdo2 = 10, \
                            freq_khz = 868000, \
                            bitrate_kbps = 2.4, \
                            freq_dev_khz = 25.4, \
                            rx_bw_khz = 58.0, \
                            output_power = 10, \
                            preamble_length = 16, \
                            sync_word_h = 0x12, \
                            sync_word_l = 0xAD)

    Create a CC1101Module object.

    :param int pin_cs: (CS) Chip select pin number.
    :param int pin_gdo0: (GDO0) Interrupt pin number.
    :param int pin_gdo2: (GDO2) Optional interrupt pin number.
    :param int freq_khz: CC1101 RF frequency in kHz, with a range of 855000 kHz to 928000 kHz.
    :param float bitrate_kbps: Data rate in kbps, range from 0.6 to 6.0 kbps.
    :param float freq_dev_khz: Frequency deviation in kHz, range from 1.6 to 380 kHz.
    :param float rx_bw_khz: Receiver bandwidth in kHz, range from 58 to 812 kHz.
    :param int output_power: Output power in dBm, range from -30 to 10 dBm.
    :param int preamble_length: Preamble length in bits, options: 16, 24, 32, 48, 64, 96, 128, 192.
    :param int sync_word_h: High byte of sync word (0x00 to 0xFF).
    :param int sync_word_l: Low byte of sync word (0x00 to 0xFF).

    UiFlow2 Code Block:

        |init.png|

    MicroPython Code Block:

        .. code-block:: python

            from module import CC1101Module

            module_cc1101_0 = CC1101Module(5, 7, 10, 868000, 2.4, 25.4, 58.0, 10, 16, 0x12, 0xAD)

    .. method:: set_freq(freq_khz)

        Set frequency in kHz.

        :param int freq_khz: Frequency in kHz (855000 ~ 928000), default is 868000.

        UiFlow2 Code Block:

            |set_freq.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.set_freq(868000)

    .. method:: set_bitrate(bitrate_kbps)

        Set data rate in kbps.

        :param float bitrate_kbps: Data rate in kbps (0.6 ~ 6.0)

        UiFlow2 Code Block:

            |set_bitrate.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.set_bitrate(2.4)

    .. method:: set_freq_dev(freq_dev_khz)

        Set frequency deviation in kHz.

        :param float freq_dev_khz: Frequency deviation in kHz (1.6 ~ 380)

        UiFlow2 Code Block:

            |set_freq_dev.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.set_freq_dev(25.4)

    .. method:: set_rx_bw(rx_bw_khz)

        Set receiver bandwidth in kHz.

        :param float rx_bw_khz: Receiver bandwidth in kHz (58 ~ 812)

        UiFlow2 Code Block:

            |set_rx_bw.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.set_rx_bw(58.0)

    .. method:: set_output_power(output_power)

        Set output power in dBm.

        :param int output_power: Output power in dBm (-30 ~ 10)

        UiFlow2 Code Block:

            |set_output_power.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.set_output_power(10)

    .. method:: set_preamble_length(preamble_length)

        Set preamble length in bits.

        :param int preamble_length: Preamble length in bits, must be one of:
                                   16, 24, 32, 48, 64, 96, 128, 192.

        UiFlow2 Code Block:

            |set_preamble_length.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.set_preamble_length(16)

    .. method:: set_sync_word(sync_word_h, sync_word_l)

        Set sync word.

        :param int sync_word_h: High byte of sync word (0 ~ 0xFF)
        :param int sync_word_l: Low byte of sync word (0 ~ 0xFF)

        UiFlow2 Code Block:

            |set_sync_word.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.set_sync_word(0x12, 0xAD)

    .. method:: send(packet)

        Send data.

        :param str | list | tuple | int | bytearray packet: The data to be sent.
        :returns: True if successful, False otherwise
        :rtype: bool

        Send a data packet and return True if successful.

        UiFlow2 Code Block:

            |send.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.send("Hello World")

    .. method:: recv(timeout_ms)

        Receive data.

        :param int timeout_ms: Timeout in milliseconds (optional). Default is None.
        :returns: Received packet instance or None if timeout
        :rtype: CC1101Packet | None

        Attempt to receive a CC1101 packet. Returns `None` if timeout occurs, or returns the received packet instance.

        UiFlow2 Code Block:

            |recv.png|

        MicroPython Code Block:

            .. code-block:: python

                packet = module_cc1101_0.recv()
                if packet:
                    if packet.crc_ok:
                        print(f"Received: {packet.decode()}")
                        print(f"RSSI: {packet.rssi} dBm")
                        print(f"LQI: {packet.lqi}")
                    else:
                        print("CRC error")

    .. method:: start_recv()

        Start receive data.

        This method initiates the process to begin receiving data.

        UiFlow2 Code Block:

            |start_recv.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.start_recv()

    .. method:: set_rx_irq_callback(callback)

        Set the receive interrupt callback function to be executed on IRQ.

        :param callback: The callback function to be invoked when the interrupt is triggered.
                          The callback should take a CC1101Packet parameter and return nothing.

        UiFlow2 Code Block:

            |set_rx_irq_callback.png|

        MicroPython Code Block:

            .. code-block:: python

                def on_packet_received(packet):
                    print(f"Received: {packet.decode()}")
                
                module_cc1101_0.set_rx_irq_callback(on_packet_received)

    .. method:: set_tx_irq_callback(callback)

        Set the transmit interrupt callback function to be executed on IRQ.

        :param callback: The callback function to be invoked when the interrupt is triggered.
                          The callback should take one parameter (pin object, can be ignored) and return nothing.

        UiFlow2 Code Block:

            |set_tx_irq_callback.png|

        MicroPython Code Block:

            .. code-block:: python

                def on_packet_sent(_):
                    print("Packet sent successfully")
                
                module_cc1101_0.set_tx_irq_callback(on_packet_sent)

    .. method:: standby()

        Set module to standby mode.

        Puts the CC1101 module into standby mode, consuming less power.

        UiFlow2 Code Block:

            |standby.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.standby()

    .. method:: rx_irq_triggered()

        Check RX IRQ trigger.

        :returns: Returns `True` if an interrupt service routine (ISR) has been triggered since the last send or receive started.
        :rtype: bool

        UiFlow2 Code Block:

            |rx_irq_triggered.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.rx_irq_triggered()

    .. method:: tx_irq_triggered()

        Check TX IRQ trigger.

        :returns: Returns `True` if an interrupt service routine (ISR) has been triggered since the last send or a receive started.
        :rtype: bool

        UiFlow2 Code Block:

            |tx_irq_triggered.png|

        MicroPython Code Block:

            .. code-block:: python

                module_cc1101_0.tx_irq_triggered()


.. _cc1101_packet:

class CC1101Packet   
^^^^^^^^^^^^^^^^^^

.. class:: driver.cc1101.CC1101Packet()

    Create a CC1101Packet object.

    .. method:: decode()

        Decode the received data.

        :returns: Decoded data as string
        :rtype: str

    .. method:: data

        Raw packet data.

    .. method:: rssi

        Received signal strength (units: dBm).

    .. method:: lqi

        Link Quality Indicator (0-127).

    .. method:: crc_ok

        CRC validity check. Returns True if CRC is valid, False otherwise.