NFC Unit

该库用于驱动 Unit NFC（I2C 接口的 ST25R3916）。它可发现 ISO14443 Type A 标签，识别芯片类型（Classic、Ultralight / NTAG 系列、DESFire、Plus 等），并为支持的标签类型提供高级读写辅助接口。

支持以下产品：

UiFlow2 应用示例

检测卡片

在 UiFlow2 中打开 cores3_unit_nfc_example.m5f2 项目。

该示例会轮询读卡器，在屏幕上显示 UID、类型名称和用户内存大小，并在检测到卡片时播放短提示音。

UiFlow2 代码块：

示例输出：

None

MicroPython 应用示例

检测卡片

该示例会轮询读卡器，在屏幕上显示 UID、类型名称和用户内存大小，并在检测到卡片时播放短提示音。

MicroPython 代码块：

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

import os, sys, io
import M5
from M5 import *
import m5ui
import lvgl as lv
from hardware import Pin
from hardware import I2C
from unit import NFCUnit
import time


page0 = None
label_title = None
label_uid = None
label_type = None
label_size = None
i2c0 = None
nfc_0 = None
card_0 = None
card_uid = None
new = None
card_type = None
card_memory = None
write_buf = None
count = None
last_time = None


def setup():
    global \
        page0, \
        label_title, \
        label_uid, \
        label_type, \
        label_size, \
        i2c0, \
        nfc_0, \
        card_0, \
        card_uid, \
        new, \
        card_type, \
        card_memory, \
        write_buf, \
        count, \
        last_time

    M5.begin()
    Widgets.setRotation(1)
    m5ui.init()
    page0 = m5ui.M5Page(bg_c=0x000000)
    label_title = m5ui.M5Label(
        "NFC Card detect",
        x=58,
        y=5,
        text_c=0x14ACDB,
        bg_c=0x000000,
        bg_opa=0,
        font=lv.font_montserrat_24,
        parent=page0,
    )
    label_uid = m5ui.M5Label(
        "UID:",
        x=18,
        y=70,
        text_c=0xFFFFFF,
        bg_c=0x000000,
        bg_opa=0,
        font=lv.font_montserrat_16,
        parent=page0,
    )
    label_type = m5ui.M5Label(
        "Type:",
        x=10,
        y=100,
        text_c=0xFFFFFF,
        bg_c=0x000000,
        bg_opa=0,
        font=lv.font_montserrat_16,
        parent=page0,
    )
    label_size = m5ui.M5Label(
        "Size:",
        x=16,
        y=130,
        text_c=0xFFFFFF,
        bg_c=0x000000,
        bg_opa=0,
        font=lv.font_montserrat_16,
        parent=page0,
    )

    i2c0 = I2C(0, scl=Pin(1), sda=Pin(2), freq=400000)
    nfc_0 = NFCUnit(i2c0)
    page0.screen_load()
    Speaker.begin()
    Speaker.setVolumePercentage(0.5)
    new = True
    write_buf = bytearray(16)
    write_buf[0] = 0x12
    count = 0


def loop():
    global \
        page0, \
        label_title, \
        label_uid, \
        label_type, \
        label_size, \
        i2c0, \
        nfc_0, \
        card_0, \
        card_uid, \
        new, \
        card_type, \
        card_memory, \
        write_buf, \
        count, \
        last_time
    M5.update()
    card_0 = nfc_0.detect()
    if card_0:
        card_uid = card_0.uid_str
        card_type = card_0.type_name
        card_memory = card_0.user_memory
        label_uid.set_text(str((str("UID: ") + str(card_uid))))
        label_type.set_text(str((str("Type: ") + str(card_type))))
        label_size.set_text(str((str("Size: ") + str(card_memory))))
        if (time.ticks_diff((time.ticks_ms()), last_time)) >= 3000 or new:
            last_time = time.ticks_ms()
            Speaker.tone(900, 100)
            print((str("read data befor write ") + str((nfc_0.read(card_0, 1)))))
            count = (count if isinstance(count, (int, float)) else 0) + 1
            write_buf[-1] = 0x12 + count
            time.sleep_ms(100)
            if nfc_0.write(card_0, 1, write_buf):
                print("write success")
                time.sleep_ms(100)
                print((str("read data after write ") + str((nfc_0.read(card_0, 1)))))
        new = False
    else:
        new = True


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

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

示例输出：

None

API参考

NFCUnit

class unit.nfc.NFCUnit

Unit NFC 的驱动程序。请传入已配置好的 I2C 总线实例（例如来自 hardware.I2C）。

参数:: i2c – 用于与 ST25R3916 通信的 I2C 总线。

UiFlow2 代码块：

MicroPython 代码块：

from hardware import Pin, I2C
from unit import NFCUnit

i2c0 = I2C(0, scl=Pin(1), sda=Pin(2), freq=400000)
nfc = NFCUnit(i2c0)

detect()

轮询射频场内的 Type A 标签。

返回:: 如果找到并识别到标签，则返回 unit.nfc.Card 实例；否则返回 None。

UiFlow2 代码块：

MicroPython 代码块：

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

write(card, index, data)

写入一个**地址单元**。

备注

当前仅支持 MIFARE Classic。

data 必须为 16 字节；index 为块号。扇区尾块和 0 号块需要卡片提供有效的密钥/访问规则。

参数:

card (unit.nfc.Card) – 由 detect() 返回的标签。
index (int) – 块索引。
data (bytes) – Classic 卡必须为 16 字节。

返回:

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

UiFlow2 代码块：

MicroPython 代码块：

ok = nfc.write(card, index, data)

read(card, index)

读取当前标签的一个地址单元。

MIFARE Classic：index 为全局块号（从 0 开始）。成功时返回 16 字节，否则返回 None。
Type 2 系列（Ultralight / NTAG / ST25TA / 适用时 ISO18092）：index 为页号。成功时返回 4 字节，否则返回 None。
其他芯片类型：返回 None（请在该辅助接口之外使用芯片专用流程）。

参数:

card (unit.nfc.Card) – 由 detect() 返回的标签。
index (int) – 块索引（Classic）或页索引（Type 2）。

返回:

bytes 或 None。

UiFlow2 代码块：

MicroPython 代码块：

data = nfc.read(card, index)

halt()

发送 HLTA 命令，将 Type A PICC 置于 HALT 状态。

UiFlow2 代码块：

MicroPython 代码块：

nfc.halt()

rf_off()

关闭读卡器 RF 场。

UiFlow2 代码块：

MicroPython 代码块：

nfc.rf_off()

rf_on()

开启读卡器 RF 场。

UiFlow2 代码块：

MicroPython 代码块：

nfc.rf_on()

Card

class unit.nfc.Card

当检测到标签时，由 NFCUnit.detect() 返回的对象。包含防冲突结果及由协议栈解析出的类型元数据（固件实现中的 SAK/ATQA/version/ATS 路径）。

属性

UiFlow2 代码块：

uid: bytes — UID 字节串（长度为 uid_len）。

type_id: int — 此驱动使用的内部类型 id（与 unit/nfc.py 中 TYPE_NAMES 表一致）。

type_name

str — 由固件识别逻辑解析出的芯片标签；字符串与 unit/nfc.py 中 TYPE_NAMES 一致。type_id 对应下表行（未知或未分类标签使用 Unknown）。

`type_id` 与 type_name``（在 ``TYPE_NAMES 中的索引）
`type_id`	`type_name`
0	`Unknown`
1	`MIFARE_Classic_Mini`
2	`MIFARE_Classic_1K`
3	`MIFARE_Classic_2K`
4	`MIFARE_Classic_4K`
5	`MIFARE_Ultralight`
6	`MIFARE_Ultralight_EV1_1`
7	`MIFARE_Ultralight_EV1_2`
8	`MIFARE_Ultralight_Nano`
9	`MIFARE_UltralightC`
10	`NTAG_203`
11	`NTAG_210u`
12	`NTAG_210`
13	`NTAG_212`
14	`NTAG_213`
15	`NTAG_215`
16	`NTAG_216`
17	`ST25TA_512B`
18	`ST25TA_2K`
19	`ST25TA_16K`
20	`ST25TA_64K`
21	`ISO_14443_4`
22	`MIFARE_Plus_2K`
23	`MIFARE_Plus_4K`
24	`MIFARE_Plus_SE`
25	`MIFARE_DESFire_2K`
26	`MIFARE_DESFire_4K`
27	`MIFARE_DESFire_8K`
28	`MIFARE_DESFire_Light`
29	`NTAG_4XX`
30	`ISO_18092`

user_memory: int — Advertised user memory size in bytes for known types (0 if unknown; used for Type 2 dump heuristics).

uid_str: UID as upper-case hex string.

is_classic()

若 type_id 属于 MIFARE Classic 系列 id（Mini / 1K / 2K / 4K），则返回 True。

UiFlow2 代码块：

MicroPython 代码块：

card.is_classic()