Faces Keyboard3 模块

Faces Keyboard3 是一个键盘输入模块，提供字符映射的 Normal 模式和原始矩阵的 Direct 模式。在 Direct 模式下，回调函数会收到当前按下的按键名称元组，并且可以控制两个键盘 LED。

支持以下产品：

UiFlow2 应用示例

Normal 模式按键事件

该示例使用 Normal 模式，并在 CoreS3 显示屏上报告映射后的按键。

在 UiFlow2 中打开 faces_keyboard3_cores3_example.m5f2 项目。

UiFlow2 代码块：

MicroPython 应用示例

Normal 模式按键事件

Normal 模式将按键映射为字符编码。Direct 模式报告当前按下的矩阵按键名称元组，并支持 LED 控制。

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

import os, sys, io
import M5
from M5 import *
from module import FacesKeyboard3Module


title0 = None
label0 = None
faces_keyboard3_0 = None


normal_args = None


def faces_keyboard3_0_normal_event(args):
    global title0, label0, faces_keyboard3_0, normal_args
    normal_args = chr(args)
    label0.setText(str((str("Key: ") + str(normal_args))))


def setup():
    global title0, label0, faces_keyboard3_0, normal_args

    M5.begin()
    Widgets.setRotation(1)
    Widgets.fillScreen(0x222222)
    title0 = Widgets.Title(
        "Faces Keyboard3 CoreS3 Example", 3, 0xFFFFFF, 0x0000FF, Widgets.FONTS.Montserrat18
    )
    label0 = Widgets.Label("label0", 3, 110, 1.0, 0xFFFFFF, 0x222222, Widgets.FONTS.Montserrat18)

    faces_keyboard3_0 = FacesKeyboard3Module(address=0x08)
    faces_keyboard3_0.set_callback(faces_keyboard3_0_normal_event)
    faces_keyboard3_0.set_mode(FacesKeyboard3Module.NORMAL)


def loop():
    global title0, label0, faces_keyboard3_0, normal_args
    M5.update()
    faces_keyboard3_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 module.faces.FacesKeyboard3Module(address=8)

基类：_FacesModule

创建 Faces Keyboard3 Module 对象。

参数:: address (int) – I2C 地址，默认为 0x08。

UiFlow2 代码块：

MicroPython 代码块：

from module import FacesKeyboard3Module

faces_keyboard3 = FacesKeyboard3Module()

get_mode()

获取当前键盘工作模式。

NORMAL (0x00) 将按键映射为字符；DIRECT (0x01) 报告矩阵按键名称。

UiFlow2 代码块：

MicroPython 代码块：

faces_keyboard3.get_mode()

返回类型:: int

set_mode(mode)

设置映射字符模式或原始矩阵模式。

参数:: mode (int) – NORMAL 或 DIRECT。
返回类型:: None

UiFlow2 代码块：

MicroPython 代码块：

faces_keyboard3.set_mode(faces_keyboard3.DIRECT)

set_led_effect(effect)

在 Direct 模式下设置键盘 LED 效果。

效果对应键盘固件状态和 LED 模式：

LED_EFFECT_1：aA 单击；左侧 LED 常亮。
LED_EFFECT_2：aA 双击锁定；左侧 LED 每 500 ms 闪烁一次。
LED_EFFECT_3：ALT 激活；左侧 LED 每 150 ms 闪烁一次。
LED_EFFECT_4：FN 单击；右侧 LED 常亮。
LED_EFFECT_5：FN 双击锁定；右侧 LED 每 500 ms 闪烁一次。
LED_EFFECT_6：SYM 双击锁定；右侧 LED 每 150 ms 闪烁一次。
LED_EFFECT_7：SYM 单击；两侧 LED 每 500 ms 交替闪烁。
LED_EFFECT_8：外部效果；两侧 LED 每 200 ms 交替闪烁。

参数:: effect (int) – LED_EFFECT_* 常量之一。
返回类型:: None

UiFlow2 代码块：

MicroPython 代码块：

faces_keyboard3.set_led_effect(faces_keyboard3.LED_EFFECT_1)

set_led(left, right)

在 Direct 模式下直接设置左右 LED。

UiFlow2 代码块：

MicroPython 代码块：

faces_keyboard3.set_led(True, False)

参数:

left (bool)
right (bool)

返回类型:

None

set_callback(handler)

设置按键回调。

在 Normal 模式下，回调函数会收到整数按键编码。在 Direct 模式下，回调函数会收到包含当前按下按键名称的元组。传入 None 可禁用回调。

参数:: handler – 接收按键事件值或 None 的可调用对象。
返回类型:: None

tick()

轮询一次，并为新的按键事件调度回调。

UiFlow2 代码块：

MicroPython 代码块：

faces_keyboard3.tick()

返回类型:: None

get_device_id()

获取 Faces 模块的设备类型 ID。

返回:: 设备类型 ID。
返回类型:: int

UiFlow2 代码块：

MicroPython 代码块：

device.get_device_id()

get_firmware_version()

获取固件版本。

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

UiFlow2 代码块：

MicroPython 代码块：

device.get_firmware_version()

get_i2c_address()

获取当前 7 位 I2C 地址。

返回:: 当前 I2C 地址。
返回类型:: int

UiFlow2 代码块：

MicroPython 代码块：

device.get_i2c_address()

get_uid()

获取 MCU 的 96 位唯一标识符。

返回:: 12 字节的唯一标识符。
返回类型:: bytes

UiFlow2 代码块：

MicroPython 代码块：

device.get_uid()

set_i2c_address(address)

设置并保存新的 7 位 I2C 地址。

参数:: address (int) – 新地址范围为 0x08 到 0x77。
返回类型:: None

UiFlow2 代码块：

MicroPython 代码块：

device.set_i2c_address(0x08)

键盘 LED 常量：

常量	值	说明
`LED_EFFECT_OFF`	`0x00`	关闭预设效果
`LED_EFFECT_1`	`0x01`	左灯常亮
`LED_EFFECT_2`	`0x02`	左灯慢闪
`LED_EFFECT_3`	`0x03`	左灯快闪
`LED_EFFECT_4`	`0x04`	右灯常亮
`LED_EFFECT_5`	`0x05`	右灯慢闪
`LED_EFFECT_6`	`0x06`	右灯快闪
`LED_EFFECT_7`	`0x07`	两侧灯交替慢闪
`LED_EFFECT_8`	`0x08`	两侧灯交替快闪

在 Normal 模式下，KEY_BACKSPACE 为 0x08，KEY_ENTER 为 0x0D，KEY_DELETE 为 0x7F。LED 效果和手动 LED 状态仅在 Direct 模式下可用。