CardKB2 Unit

这是 CardKB2 单元的驱动库，用于获取按键输入数据。

支持以下产品：

UiFlow2 示例

CardKB2 I2C 模式

在 UiFlow2 中打开 cardkb2_i2c_core2_example.m5f2 项目。

此示例将在屏幕和串口上显示键盘输入内容。

UiFlow2 代码块：

示例输出：

输入的按键字符

CardKB2 UART 模式

在 UiFlow2 中打开 cardkb2_uart_core2_example.m5f2 项目。

此示例将在屏幕和串口上显示键盘输入内容。

UiFlow2 代码块：

示例输出：

输入的按键字符及状态

CardKB2 ESP-NOW 模式

在 UiFlow2 中打开 cardkb2_espnow_core2_example.m5f2 项目。

此示例将在屏幕和串口上显示键盘输入内容。

UiFlow2 代码块：

示例输出：

输入的按键字符及状态

MicroPython 示例

CardKB2 I2C 模式

此示例将在屏幕和串口上显示键盘输入内容。

MicroPython 代码块：

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

import os, sys, io
import M5
from M5 import *
from unit import CardKBUnit
from hardware import Pin
from hardware import I2C


title0 = None
label0 = None
i2c0 = None
cardkb2_0 = None


char = None


def cardkb2_0_i2c_pressed_event(kb):
    global title0, label0, i2c0, cardkb2_0, char
    char = cardkb2_0.get_char()
    label0.setText(str((str(char) + str(" was pressed"))))
    print((str(char) + str(" was pressed")))


def setup():
    global title0, label0, i2c0, cardkb2_0, char

    M5.begin()
    Widgets.setRotation(1)
    Widgets.fillScreen(0x222222)
    title0 = Widgets.Title(
        "CardKB2 I2C Mode Example", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu18
    )
    label0 = Widgets.Label("label0", 3, 90, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)

    i2c0 = I2C(0, scl=Pin(33), sda=Pin(32), freq=100000)
    cardkb2_0 = CardKBUnit(i2c0, mode=CardKBUnit.CardKB_I2C_MODE)
    cardkb2_0.set_callback(cardkb2_0_i2c_pressed_event)
    char = ""


def loop():
    global title0, label0, i2c0, cardkb2_0, char
    M5.update()
    cardkb2_0.tick()


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")

示例输出：

输入的按键字符

CardKB2 UART 模式

此示例将在屏幕和串口上显示键盘输入内容。

MicroPython 代码块：

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

import os, sys, io
import M5
from M5 import *
from unit import CardKBUnit


title0 = None
label0 = None
cardkb2_0 = None


key_id = None
key_status = None


def cardkb2_0_pressed_event(kb):
    global title0, label0, cardkb2_0, key_id, key_status
    key_id, key_status = kb
    if key_status == (CardKBUnit.KEY_STATE_PRESS):
        label0.setText(str((str("Key ID ") + str((str(key_id) + str(" Press"))))))
        print((str("Key ID ") + str((str(key_id) + str(" Press")))))
    elif key_status == (CardKBUnit.KEY_STATE_RELEASE):
        label0.setText(str((str("Key ID ") + str((str(key_id) + str(" Release"))))))
        print((str("Key ID ") + str((str(key_id) + str(" Release")))))


def setup():
    global title0, label0, cardkb2_0, key_id, key_status

    M5.begin()
    Widgets.setRotation(1)
    Widgets.fillScreen(0x222222)
    title0 = Widgets.Title(
        "CardKB2 UART Mode Example", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu18
    )
    label0 = Widgets.Label("label0", 3, 107, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)

    cardkb2_0 = CardKBUnit(2, port=(33, 32), mode=CardKBUnit.CardKB_UART_MODE)
    cardkb2_0.set_callback(cardkb2_0_pressed_event)


def loop():
    global title0, label0, cardkb2_0, key_id, key_status
    M5.update()
    cardkb2_0.tick()


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")

示例输出：

输入的按键字符及状态

CardKB2 ESP-NOW 模式

此示例将在屏幕和串口上显示键盘输入内容。

MicroPython 代码块：

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

import os, sys, io
import M5
from M5 import *
from unit import CardKBUnit


title0 = None
label0 = None
cardkb2_0 = None


key_id = None
key_status = None


def cardkb2_0_pressed_event(kb):
    global title0, label0, cardkb2_0, key_id, key_status
    key_id, key_status = kb
    if key_status == (CardKBUnit.KEY_STATE_PRESS):
        label0.setText(str((str("Key ID ") + str((str(key_id) + str(" Press"))))))
        print((str("Key ID ") + str((str(key_id) + str(" Press")))))
    elif key_status == (CardKBUnit.KEY_STATE_RELEASE):
        label0.setText(str((str("Key ID ") + str((str(key_id) + str(" Release"))))))
        print((str("Key ID ") + str((str(key_id) + str(" Release")))))


def setup():
    global title0, label0, cardkb2_0, key_id, key_status

    M5.begin()
    Widgets.setRotation(1)
    Widgets.fillScreen(0x222222)
    title0 = Widgets.Title(
        "CardKB2 ESPNOW Mode Example", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.DejaVu18
    )
    label0 = Widgets.Label("label0", 3, 107, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.DejaVu18)

    cardkb2_0 = CardKBUnit(mode=CardKBUnit.CardKB_ESP_NOW_MODE)
    cardkb2_0.set_callback(cardkb2_0_pressed_event)


def loop():
    global title0, label0, cardkb2_0, key_id, key_status
    M5.update()
    cardkb2_0.tick()


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 CardKB2Unit

class unit.cardkb.CardKBUnit(*args, **kwargs)

基类：object

创建一个 CardKBUnit 对象。

参数:

args – 传递给底层通信类的位置参数。
mode (int) – 通信模式。默认模式包括： - CardKBUnit.CardKB_I2C_MODE：I2C 模式 - CardKBUnit.CardKB_UART_MODE：UART 模式 - CardKBUnit.CardKB_ESP_NOW_MODE：ESP-NOW 模式

备注

这是一个工厂类。它会根据指定的模式返回相应的子类实例。

UiFlow2 代码块：

MicroPython 代码块：

from cardkb import CardKBUnit
from hardware import I2C, Pin

# I2C mode
i2c0 = I2C(0, scl=Pin(33), sda=Pin(32), freq=100000)
cardkb_0 = CardKBUnit(i2c0, mode=CardKBUnit.CardKB_I2C_MODE)

# UART mode
cardkb_0 = CardKBUnit(2, port=(33, 32), mode=CardKBUnit.CardKB_UART_MODE)

# ESP-NOW mode
cardkb_0 = CardKBUnit(mode=CardKBUnit.CardKB_ESP_NOW_MODE)

class unit.cardkb.CardKBBase

基类：object

CardKB 单元通信的基类。

该类为所有 CardKB 通信模式提供通用接口和逻辑。

get_key()

从按键缓冲区获取下一个按键。

返回:: 按键值（根据模式不同为 int 或 tuple）。

UiFlow2 代码块：

MicroPython 代码块：

key = cardkb_0.get_key()
print(key)

get_string()

将下一个按键以字符串形式获取。

返回:: 下一个按键的字符串表示。
返回类型:: str

UiFlow2 代码块：

MicroPython 代码块：

s = cardkb_0.get_string()
print(s)

get_char()

将下一个按键以字符形式获取。

返回:: 与下一个按键码对应的字符。
返回类型:: str

UiFlow2 代码块：

MicroPython 代码块：

c = cardkb_0.get_char()
print(c)

is_pressed()

检查当前是否有按键被按下。

返回:: 若有按键被按下返回 True，否则返回 False。
返回类型:: bool

UiFlow2 代码块：

MicroPython 代码块：

if cardkb_0.is_pressed():
    print("Key pressed!")

set_callback(handler)

设置按键按下事件的回调函数。

参数:: handler – 当按键被按下时调用的回调函数。该回调函数接收 CardKB 实例作为其参数。

UiFlow2 代码块：

MicroPython 代码块：

# I2C mode example
def on_key_pressed(kb):
    print("Key pressed:", kb.get_char())

cardkb_0.set_callback(on_key_pressed)

# UART/ESP-NOW mode example
def on_key_event(kb):
    key_id, key_state = kb.get_key()
    print("Key event - ID:", key_id, "State:", key_state)

tick()

轮询按键事件，并在按键被按下时触发回调函数。

此方法应在主循环中定期调用，以处理按键事件。

UiFlow2 代码块：

MicroPython 代码块：

while True:
    cardkb_0.tick()

返回类型:: None

class unit.cardkb.CardKBI2C(i2c, address=95, mode=None)

基类：CardKBBase

基于 I2C 通信的 CardKB 单元驱动程序。

参数:

i2c (I2C) – I2C 总线实例。
address (int) – CardKB 单元的 I2C 地址。默认值为 0x5F。
mode – 已忽略。保留用于工厂兼容性。

抛出:

Exception – 如果在 I2C 总线上未找到 CardKB 单元。

备注

不要直接实例化此类。请改用 CardKBUnit 并设置 mode=CardKBUnit.CardKB_I2C_MODE。

MicroPython 代码块：

from hardware import I2C, Pin
from cardkb import CardKBUnit

i2c0 = I2C(0, scl=Pin(33), sda=Pin(32), freq=100000)
cardkb_0 = CardKBUnit(i2c0, mode=CardKBUnit.CardKB_I2C_MODE)

get_firmware_version()

从 CardKB 单元读取固件版本。

返回:: 固件版本字节。
返回类型:: int

MicroPython 代码块：

version = cardkb_0.get_firmware_version()
print("Firmware version:", version)

class unit.cardkb.CardKBUART(id=1, port=None, mode=None)

基类：CardKBBase

基于 UART 通信的 CardKB 单元驱动程序。

参数:

id (int) – UART 总线 ID（0、1 或 2）。默认值为 1。
port (list | tuple) – 包含 (rx_pin, tx_pin) 的列表或元组。
mode – 已忽略。保留用于工厂兼容性。

备注

不要直接实例化此类。请改用 CardKBUnit 并设置 mode=CardKBUnit.CardKB_UART_MODE。

MicroPython 代码块：

from cardkb import CardKBUnit

cardkb_0 = CardKBUnit(2, port=(33, 32), mode=CardKBUnit.CardKB_UART_MODE)

tick()

轮询按键缓冲区，并在有可用按键时触发回调函数。

此方法应在主循环中定期调用，以处理通过 UART 接收的按键事件。

MicroPython 代码块：

while True:
    cardkb_0.tick()

class unit.cardkb.CardKBESPNOW(mode=None)

基类：CardKBBase

基于 ESP-NOW 无线通信的 CardKB 单元驱动程序。

参数:: mode – 已忽略。保留用于工厂兼容性。

备注

不要直接实例化此类。请改用 CardKBUnit 并设置 mode=CardKBUnit.CardKB_ESP_NOW_MODE。

备注

此类使用广播 MAC 地址（ffffffffffff），并将 Wi-Fi 信道固定为 0。按键数据通过 IRQ 回调异步接收。

MicroPython 代码块：

from cardkb import CardKBUnit

cardkb_0 = CardKBUnit(mode=CardKBUnit.CardKB_ESP_NOW_MODE)

espnow_recv_callback(espnow_obj)

在接收到 ESP-NOW 数据包时调用的回调函数。

参数:: espnow_obj – 包含接收数据的 ESP-NOW 对象。
返回:: 如果帧有效并且已追加按键数据，则为 True，否则为 False。
返回类型:: bool

get_key()

从通过 ESP-NOW 接收的缓冲区中获取下一个按键。

返回:: 按键元组 (key_id, key_state)，如果缓冲区为空则返回 None。
返回类型:: tuple or None

MicroPython 代码块：

key = cardkb_0.get_key()
if key:
    print("key_id:", key[0], "key_state:", key[1])

is_pressed()

检查是否存在来自 ESP-NOW 的按键数据缓冲。

返回:: 如果存在缓冲的按键数据则为 True，否则为 False。
返回类型:: bool

MicroPython 代码块：

if cardkb_0.is_pressed():
    print("Key received via ESP-NOW!")

tick()

轮询按键缓冲区，并在有可用按键时触发回调函数。

此方法应在主循环中定期调用，以处理通过 ESP-NOW 接收的按键事件。

MicroPython 代码块：

while True:
    cardkb_0.tick()