CC1101 Cap

Cap CC1101 是一款扩展 Cap，集成了 CC1101 Sub-GHz 射频收发器和 ST25R3916 NFC 读卡器。

MicroPython API 按功能拆分：

• CC1101Cap 用于 Sub-GHz 发送和接收。

• NFCCap 用于 NFC 卡片检测和读写操作。

支持以下产品：

频率范围

CC1101Cap 支持以下实测频率范围：

范围	频段
315000~348000 kHz	315MHz 频段
415000~464000 kHz	433MHz 频段
830000~928000 kHz	868MHz 频段

当 freq_khz 改变时，会自动更新 RF switch。

UiFlow2 应用示例

CC1101 RF 发送

在 UiFlow2 中打开 cc1101_cap_rf_tx_example.m5f2 项目。

此示例在 868MHz 下每秒发送一次 payload，并显示 SEQ、OK 和 FAIL 计数。

UiFlow2 代码块：

示例输出：

无

CC1101 RF 接收

在 UiFlow2 中打开 cc1101_cap_rf_rx_example.m5f2 项目。

此示例在 868MHz 下接收数据包，并显示 payload、RSSI、LQI 和 CRC 状态。

UiFlow2 代码块：

示例输出：

无

NFC 卡片检测

在 UiFlow2 中打开 cc1101_cap_nfc_read_id_example.m5f2 项目。

此示例扫描 ISO14443A 卡片，并显示 UID、卡片类型和用户区容量。

UiFlow2 代码块：

示例输出：

无

MicroPython 应用示例

CC1101 RF 发送

此示例在 868MHz 下每秒发送一次 payload，并显示发送计数。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from cap import CC1101Cap
import time


label_title = None
label_status = None
label_seq = None
label_ok = None
label_fail = None
label_payload = None
cap_cc1101 = None


seq = None
last_tx_ms = None
ok_count = None
payload = None
fail_count = None
tx_ok = None


def setup():
    global \
        label_title, \
        label_status, \
        label_seq, \
        label_ok, \
        label_fail, \
        label_payload, \
        cap_cc1101, \
        seq, \
        last_tx_ms, \
        ok_count, \
        payload, \
        fail_count, \
        tx_ok

    M5.begin()
    Widgets.fillScreen(0x101418)
    label_title = Widgets.Label(
        "CC1101 TX", 76, 3, 1.0, 0x22D3A6, 0x101418, Widgets.FONTS.Montserrat18
    )
    label_status = Widgets.Label(
        "Auto TX every 1s", 5, 28, 1.0, 0x22D3A6, 0x101418, Widgets.FONTS.Montserrat16
    )
    label_seq = Widgets.Label("SEQ: 0", 5, 50, 1.0, 0xEAF2F8, 0x101418, Widgets.FONTS.Montserrat16)
    label_ok = Widgets.Label("OK: 0", 5, 72, 1.0, 0x22D3A6, 0x101418, Widgets.FONTS.Montserrat16)
    label_fail = Widgets.Label(
        "FAIL: 0", 120, 72, 1.0, 0xFF5C5C, 0x101418, Widgets.FONTS.Montserrat16
    )
    label_payload = Widgets.Label(
        "TX:", 5, 100, 1.0, 0xEAF2F8, 0x101418, Widgets.FONTS.Montserrat18
    )

    cap_cc1101 = CC1101Cap(868000, 2.4, 25.4, 58, 10, 64, 0x12, 0xAD)
    seq = 0
    ok_count = 0
    fail_count = 0
    last_tx_ms = 0
    Speaker.begin()
    Speaker.setVolumePercentage(0.5)
    label_status.setText(str("Auto TX every 1s"))
    label_seq.setText(str("SEQ: 0"))
    label_ok.setText(str("OK: 0"))
    label_fail.setText(str("FAIL: 0"))
    label_payload.setText(str("TX: "))
    Speaker.tone(3600, 40)
    time.sleep_ms(35)
    Speaker.tone(4800, 45)


def loop():
    global \
        label_title, \
        label_status, \
        label_seq, \
        label_ok, \
        label_fail, \
        label_payload, \
        cap_cc1101, \
        seq, \
        last_tx_ms, \
        ok_count, \
        payload, \
        fail_count, \
        tx_ok
    M5.update()
    if (time.ticks_diff((time.ticks_ms()), last_tx_ms)) >= 1000:
        last_tx_ms = time.ticks_ms()
        payload = str((str("CC1101, SEQ=") + str(seq))) + str(", Hello")
        tx_ok = cap_cc1101.send(payload)
        if tx_ok:
            ok_count = (ok_count if isinstance(ok_count, (int, float)) else 0) + 1
            label_status.setText(str("TX OK"))
            Speaker.tone(3600, 25)
        else:
            fail_count = (fail_count if isinstance(fail_count, (int, float)) else 0) + 1
            label_status.setText(str("TX failed"))
            Speaker.tone(900, 100)
        label_payload.setText(str((str("TX: ") + str(payload))))
        seq = (seq if isinstance(seq, (int, float)) else 0) + 1
        label_seq.setText(str((str("SEQ: ") + str(seq))))
        label_ok.setText(str((str("OK: ") + str(ok_count))))
        label_fail.setText(str((str("FAIL: ") + str(fail_count))))


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

无

CC1101 RF 接收

此示例在 868MHz 下接收数据包，并显示 payload、RSSI、LQI 和 CRC 状态。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from cap import CC1101Cap
import time


label_title = None
label_status = None
label_counts = None
label_rssi = None
label_lqi = None
label_payload = None
cap_cc1101 = None


cc1101_data = None
rx_count = None
crc_count = None
last_rx_ms = None
last_anim_ms = None


def setup():
    global \
        label_title, \
        label_status, \
        label_counts, \
        label_rssi, \
        label_lqi, \
        label_payload, \
        cap_cc1101, \
        cc1101_data, \
        rx_count, \
        crc_count, \
        last_rx_ms, \
        last_anim_ms

    M5.begin()
    Widgets.fillScreen(0x101418)
    label_title = Widgets.Label(
        "CC1101 RX", 75, 3, 1.0, 0x22D3A6, 0x101418, Widgets.FONTS.Montserrat18
    )
    label_status = Widgets.Label(
        "Listening...", 5, 28, 1.0, 0x22D3A6, 0x101418, Widgets.FONTS.Montserrat16
    )
    label_counts = Widgets.Label(
        "RX:0 CRC:0", 5, 50, 1.0, 0xEAF2F8, 0x101418, Widgets.FONTS.Montserrat16
    )
    label_rssi = Widgets.Label(
        "RSSI: -", 5, 72, 1.0, 0xEAF2F8, 0x101418, Widgets.FONTS.Montserrat16
    )
    label_lqi = Widgets.Label(
        "LQI: -", 136, 72, 1.0, 0xEAF2F8, 0x101418, Widgets.FONTS.Montserrat16
    )
    label_payload = Widgets.Label(
        "RX:", 5, 100, 1.0, 0x22D3A6, 0x101418, Widgets.FONTS.Montserrat18
    )

    cap_cc1101 = CC1101Cap(868000, 2.4, 25.4, 58, 10, 64, 0x12, 0xAD)
    cap_cc1101.start_recv()
    rx_count = 0
    crc_count = 0
    last_rx_ms = time.ticks_ms()
    last_anim_ms = time.ticks_ms()
    Speaker.begin()
    Speaker.setVolumePercentage(0.5)
    label_status.setText(str("Listening..."))
    label_counts.setText(str("RX:0 CRC:0"))
    label_rssi.setText(str("RSSI: -"))
    label_lqi.setText(str("LQI: -"))
    label_payload.setText(str("RX: "))
    Speaker.tone(3600, 40)
    time.sleep_ms(35)
    Speaker.tone(4800, 45)


def loop():
    global \
        label_title, \
        label_status, \
        label_counts, \
        label_rssi, \
        label_lqi, \
        label_payload, \
        cap_cc1101, \
        cc1101_data, \
        rx_count, \
        crc_count, \
        last_rx_ms, \
        last_anim_ms
    M5.update()
    cc1101_data = cap_cc1101.recv(timeout_ms=0)
    if cc1101_data:
        if cc1101_data.crc_ok:
            last_rx_ms = time.ticks_ms()
            rx_count = (rx_count if isinstance(rx_count, (int, float)) else 0) + 1
            label_status.setText(str("Packet received"))
            label_counts.setText(
                str((str((str("RX:") + str(rx_count))) + str((str(" CRC:") + str(crc_count)))))
            )
            label_rssi.setText(str((str((str("RSSI: ") + str((cc1101_data.rssi)))) + str(" dBm"))))
            label_lqi.setText(str((str("LQI: ") + str((cc1101_data.lqi)))))
            label_payload.setText(str((str("RX:") + str(((cc1101_data.data).decode())))))
            Speaker.tone(5200, 35)
            cap_cc1101.start_recv()
        else:
            crc_count = (crc_count if isinstance(crc_count, (int, float)) else 0) + 1
            label_status.setText(str("CRC error"))
            label_counts.setText(
                str((str((str("RX:") + str(rx_count))) + str((str(" CRC:") + str(crc_count)))))
            )
            Speaker.tone(900, 100)
            cap_cc1101.start_recv()
    else:
        if (time.ticks_diff((time.ticks_ms()), last_anim_ms)) >= 1000:
            last_anim_ms = time.ticks_ms()
            label_status.setText(str("Listening..."))


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

无

NFC 卡片检测

此示例扫描 ISO14443A 卡片，并显示 UID、卡片类型和用户区容量。

MicroPython 代码块：

# SPDX-FileCopyrightText: 2026 M5Stack Technology CO LTD
#
# SPDX-License-Identifier: MIT

import os, sys, io
import M5
from M5 import *
from cap import NFCCap
import time


label_title = None
label_status = None
label_uid = None
label_type = None
label_mem = None
cap_nfc = None
last_scan_ms = None
card_0 = None
last_uid = None
card_uid = None
card_type = None
card_size = None


def setup():
    global \
        label_title, \
        label_status, \
        label_uid, \
        label_type, \
        label_mem, \
        cap_nfc, \
        last_scan_ms, \
        card_0, \
        last_uid, \
        card_uid, \
        card_type, \
        card_size

    M5.begin()
    Widgets.fillScreen(0x101418)
    label_title = Widgets.Label(
        "NFC card detect", 44, 3, 1.0, 0x22D3A6, 0x101418, Widgets.FONTS.Montserrat18
    )
    label_status = Widgets.Label(
        "Scanning...", 5, 28, 1.0, 0x22D3A6, 0x101418, Widgets.FONTS.Montserrat14
    )
    label_uid = Widgets.Label("UID: -", 5, 50, 1.0, 0xEAF2F8, 0x101418, Widgets.FONTS.Montserrat14)
    label_type = Widgets.Label(
        "Type: -", 5, 72, 1.0, 0xEAF2F8, 0x101418, Widgets.FONTS.Montserrat14
    )
    label_mem = Widgets.Label(
        "Memory: -", 5, 94, 1.0, 0xEAF2F8, 0x101418, Widgets.FONTS.Montserrat14
    )

    Speaker.begin()
    Speaker.setVolumePercentage(0.6)
    cap_nfc = NFCCap()
    last_uid = ""
    last_scan_ms = time.ticks_ms()
    label_status.setText(str("Scanning..."))
    label_uid.setText(str("UID: -"))
    label_type.setText(str("Type: -"))
    label_mem.setText(str("Memory: -"))
    Speaker.tone(3600, 40)
    time.sleep_ms(35)
    Speaker.tone(4800, 45)


def loop():
    global \
        label_title, \
        label_status, \
        label_uid, \
        label_type, \
        label_mem, \
        cap_nfc, \
        last_scan_ms, \
        card_0, \
        last_uid, \
        card_uid, \
        card_type, \
        card_size
    M5.update()
    if (time.ticks_diff((time.ticks_ms()), last_scan_ms)) >= 180:
        last_scan_ms = time.ticks_ms()
        card_0 = cap_nfc.detect()
        if card_0:
            card_uid = card_0.uid_str
            if card_uid != last_uid:
                last_uid = card_uid
                card_type = card_0.type_name
                card_size = card_0.user_memory
                label_status.setText(str("Card detected"))
                label_uid.setText(str((str("UID: ") + str(card_uid))))
                label_type.setText(str((str("Type: ") + str(card_type))))
                label_mem.setText(str((str((str("Memory: ") + str(card_size))) + str(" bytes"))))
                Speaker.tone(4200, 45)
                time.sleep_ms(35)
                Speaker.tone(5600, 55)
            cap_nfc.halt()
        else:
            last_uid = ""
            label_status.setText(str("Scanning..."))
            label_uid.setText(str("UID: -"))
            label_type.setText(str("Type: -"))
            label_mem.setText(str("Memory: -"))


if __name__ == "__main__":
    try:
        setup()
        while True:
            loop()
    except (Exception, KeyboardInterrupt) as e:
        try:
            from utility import print_error_msg

            print_error_msg(e)
        except ImportError:
            print("please update to latest firmware")

示例输出：

无

API参考

class CC1101Cap

class cap.cc1101.CC1101Cap(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)

创建用于 Sub-GHz 射频通信的 CC1101Cap 对象。

参数:

• freq_khz (int) – CC1101 射频频率，单位 kHz。有效范围：315000~348000 kHz、415000~464000 kHz、830000~928000 kHz。

• bitrate_kbps (float) – 数据速率，单位 kbps，范围 0.6 到 6.0 kbps。

• freq_dev_khz (float) – 频偏，单位 kHz，范围 1.6 到 380 kHz。

• rx_bw_khz (float) – 接收带宽，单位 kHz，范围 58 到 812 kHz。

• output_power (int) – 输出功率，单位 dBm，范围 -30 到 10 dBm。

• preamble_length (int) – 前导码长度，单位 bit，可选值：16、24、32、48、64、96、128、192。

• sync_word_h (int) – 同步字高字节（0x00 到 0xFF）。

• sync_word_l (int) – 同步字低字节（0x00 到 0xFF）。

UiFlow2 代码块：

MicroPython 代码块：

from cap import CC1101Cap

cap_cc1101 = CC1101Cap(868000, 2.4, 25.4, 58.0, 10, 64, 0x12, 0xAD)

set_freq(freq_khz)

设置频率，单位 kHz，并自动更新 Cap RF switch。

参数:

freq_khz (int) – 频率，单位 kHz。有效范围：315000~348000 kHz、415000~464000 kHz、830000~928000 kHz。

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.set_freq(868000)

set_bitrate(bitrate_kbps)

设置数据速率，单位 kbps。

参数:

bitrate_kbps (float) – 数据速率，单位 kbps，范围 0.6 到 6.0。

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.set_bitrate(2.4)

set_freq_dev(freq_dev_khz)

设置频偏，单位 kHz。

参数:

freq_dev_khz (float) – 频偏，单位 kHz，范围 1.6 到 380。

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.set_freq_dev(25.4)

set_rx_bw(rx_bw_khz)

设置接收带宽，单位 kHz。

参数:

rx_bw_khz (float) – 接收带宽，单位 kHz，范围 58 到 812。

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.set_rx_bw(58.0)

set_output_power(output_power)

设置输出功率，单位 dBm。

参数:

output_power (int) – 输出功率，单位 dBm，范围 -30 到 10。

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.set_output_power(10)

set_preamble_length(preamble_length)

设置前导码长度，单位 bit。

参数:

preamble_length (int) – 前导码长度，单位 bit。必须是 16、24、32、48、64、96、128、192 之一。

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.set_preamble_length(64)

set_sync_word(sync_word_h, sync_word_l)

设置 2 字节同步字。

参数:

• sync_word_h (int) – 同步字高字节（0x00 到 0xFF）。

• sync_word_l (int) – 同步字低字节（0x00 到 0xFF）。

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.set_sync_word(0x12, 0xAD)

send(packet)

发送数据。

参数:

packet (str | list | tuple | int | bytearray | bytes) – 要发送的数据。

返回:

数据包发送成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.send("Hello World")

recv(timeout_ms=None)

接收数据。

参数:

timeout_ms (int) – 超时时间，单位 ms。None 表示非阻塞轮询。

返回:

接收到的数据包实例，或 None。

返回类型:

CC1101Packet | None

UiFlow2 代码块：

MicroPython 代码块：

packet = cap_cc1101.recv()
if packet and packet.crc_ok:
    print(packet.decode(), packet.rssi, packet.lqi)

start_recv()

启动接收模式。

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.start_recv()

set_rx_irq_callback(callback)

设置接收中断回调。

参数:

callback – 收到数据包时调用该回调，参数为 CC1101Packet。

UiFlow2 代码块：

MicroPython 代码块：

def on_rx(packet):
    print(packet.decode())

cap_cc1101.set_rx_irq_callback(on_rx)

set_tx_irq_callback(callback)

设置发送回调。

参数:

callback – 发送完成后调用该回调。在 CC1101Cap 上，GDO2 用于 RF switch 控制，因此该 API 主要用于兼容。

UiFlow2 代码块：

MicroPython 代码块：

def on_tx(_):
    print("TX done")

cap_cc1101.set_tx_irq_callback(on_tx)

standby()

使 CC1101 进入 standby 模式。

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.standby()

rx_irq_triggered()

检查 RX IRQ 是否已触发。

返回:

RX IRQ 已触发返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.rx_irq_triggered()

tx_irq_triggered()

检查 TX IRQ 是否已触发。

返回:

TX IRQ 已触发返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

MicroPython 代码块：

cap_cc1101.tx_irq_triggered()

get_rssi()

获取最近一次 RSSI 值。

返回:

RSSI，单位 dBm。

返回类型:

float

get_lqi()

获取最近一次链路质量指示值。

返回:

LQI 值。

返回类型:

int

get_status()

获取 CC1101 射频状态。

返回:

状态字典，包含 marc_state、rssi 和 lqi。

返回类型:

dict

class CC1101Packet

class driver.cc1101.CC1101Packet

CC1101Cap.recv() 和 RX 回调返回的数据包对象。

data

原始数据包数据。

rssi

接收信号强度，单位 dBm。

lqi

链路质量指示。

crc_ok

CRC 结果。True 表示数据包通过 CRC 校验。

decode()

将数据包数据按 UTF-8 解码为字符串。

返回:

解码后的字符串。

返回类型:

str

class NFCCap

class cap.cc1101.NFCCap

创建用于 Cap CC1101 硬件上 ST25R3916 NFC 读卡器的 NFCCap 对象。

NFCCap 内部以 SPI 模式使用 ST25R3916，应用层不需要传入 I2C 总线或 SPI 对象。

UiFlow2 代码块：

MicroPython 代码块：

from cap import NFCCap

nfc = NFCCap()

detect()

轮询检测 ISO14443A 卡片。

返回:

检测到卡片时返回 Card 对象，否则返回 None。

UiFlow2 代码块：

MicroPython 代码块：

card = nfc.detect()
if card:
    print(card.uid_str, card.type_name, card.user_memory)

read(card, index, key=FACTORY_KEY)

从检测到的卡片读取一个地址单元。

• MIFARE Classic：index 为全局块号，返回值为 16 字节或 None。

• Type 2 / Ultralight / NTAG：index 为页号，返回值为 4 字节或 None。

参数:

• card – 由 detect() 返回的 Card 对象。

• index (int) – Classic 卡为块索引，Type 2 卡为页索引。

• key (bytes) – MIFARE Classic 密钥。默认值为 FF FF FF FF FF FF。

返回:

bytes 或 None。

UiFlow2 代码块：

MicroPython 代码块：

data = nfc.read(card, 4)

write(card, index, data, key=FACTORY_KEY)

向检测到的卡片写入一个地址单元。

• MIFARE Classic：data 必须为 16 字节，index 为全局块号。

• Type 2 / Ultralight / NTAG：data 必须为 4 字节，index 为页号。

仅使用可写测试卡。不要写入 UID 页、锁定位、扇区尾块、访问控制块、支付卡、门禁卡或身份卡。

参数:

• card – 由 detect() 返回的 Card 对象。

• index (int) – Classic 卡为块索引，Type 2 卡为页索引。

• data (bytes) – 要写入的数据。

• key (bytes) – MIFARE Classic 密钥。默认值为 FF FF FF FF FF FF。

返回:

成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

MicroPython 代码块：

ok = nfc.write(card, 4, bytes(16))

halt()

发送 HLTA，使 Type A 卡片进入 HALT 状态。

UiFlow2 代码块：

MicroPython 代码块：

nfc.halt()

rf_off()

关闭 NFC RF 场。

UiFlow2 代码块：

MicroPython 代码块：

nfc.rf_off()

rf_on()

开启 NFC RF 场。

UiFlow2 代码块：

MicroPython 代码块：

nfc.rf_on()

Card 对象

NFCCap.detect() 返回的 Card 对象包含检测到的卡片信息。

UiFlow2 代码块：

属性 / 方法	说明
uid	原始 UID 字节。
uid_len	UID 长度。
uid_str	大写十六进制 UID 字符串。
atqa	ISO14443A ATQA 值。
sak	ISO14443A SAK 值。
type_id	卡片类型 ID。
type_name	卡片类型名称。
user_memory	检测到的用户区容量，单位 byte。
is_classic()	MIFARE Classic 系列卡片返回 True。
is_type2_family()	Type 2 / Ultralight / NTAG 系列卡片返回 True。

UiFlow2 代码块：