37 exfacecam-人脸识别摄像头管理

作者：王城钧　|　最后修改：2026-10-22

一、概述

exfacecam 扩展库用于AirCAMERA_1034摄像头通信管理。通过 UART 串口与合宙主控模组交互，同时支持 USB 摄像头初始化，实现人脸录入、验证、用户管理等功能。

二、核心示例

1、核心示例是指：使用本扩展库文件提供的 API，开发的基础业务逻辑的演示代码；

2、核心示例的作用是：帮助开发者快速理解如何使用本库，所以核心示例的逻辑都比较简单；

3、 完整的 demo，请参考 LuatOS 仓库 中Air1601/ 1602 / 8101 目录下的 demo/accessory_board/AirCAMERA_1034

-- Air1601/Air1602 人脸识别 Demo
local exfacecam = require "exfacecam"

-- 12号GPIO配置（AirCAMERA_1034摄像头供电控制引脚），需要拉高使能
gpio.setup(12, 1, gpio.PULLUP)

-- 实时人脸状态回调（录入/验证过程中持续触发）
local function onFaceState(state, left, top, right, bottom)
    if state == 0 then log.info("已检测到人脸") end
end

-- 录入用户
local function doRegister()
    log.info("开始录入, 请正对摄像头...")
    local ok, uid = exfacecam.register({
        name = "TestUser", admin = 0, timeout = 15,
        on_state = onFaceState,
    })
    log.info("录入结果:", ok, uid)
    return ok, uid
end

-- 验证用户
local function doVerify()
    log.info("开始验证, 请正对摄像头...")
    local ok, result = exfacecam.verify({
        timeout = 15,
        on_state = onFaceState,
    })
    if ok and result and result.user_id then
        log.info("验证成功!", "user_id=", result.user_id, "name=", result.name)
        return true
    elseif ok then
        log.info("验证通过但无用户数据")
        return true
    else
        log.error("验证失败, 错误码=", result)
        return false
    end
end

local function face_recognition()
    -- 1. 初始化
    local result = exfacecam.open({
        id = camera.USB,
        sensor_width = 1280, sensor_height = 720,
        usb_port = 1,
        face_uart = 2,
        face_rst = nil,
    })
    if not result then log.error("初始化失败"); return end

    -- 2. 查询固件版本
    local ok, ver = exfacecam.get_version()
    if ok then log.info("模组固件:", ver) end

    -- 3. 列出现有用户
    local ok, count, ids = exfacecam.list()
    for i, id in ipairs(ids) do
        local ok2, info = exfacecam.query(id)
        if ok2 then log.info("id=", id, "name=", info.name) end
    end

    -- 4. 清空并重新录入
    exfacecam.clear()
    doRegister()
    sys.wait(2000) -- 供测试者从"录入"姿态调整到正常站姿，实际业务可去掉
    -- 5. 验证用户
    doVerify()

    -- 6. 清理
    exfacecam.close()
end

sys.taskInit(face_recognition)

三、常量详解

核心库常量，顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值，在脚本代码中不需要声明，可直接调用；

合宙LuatOS内核固件中定义的核心库常量，和此扩展库功能有关，所以也会放到本文描述。

关于人脸识别模组返回错误码的常量：

扩展库常量，由 exfacecam 扩展库中定义的、不可重新赋值或修改的固定值；

3.1 exfacecam.MR_SUCCESS

常量含义：指令执行成功，值为0；
数据类型：number；
示例代码：if result_code == exfacecam.MR_SUCCESS then
            log.info("操作成功")
          end

3.2 exfacecam.MR_REJECTED

常量含义：AirCAMERA_1034摄像头拒绝该命令，值为1；
数据类型：number；
注意事项：模块当前忙或状态不允许时拒绝命令；
示例代码：if result_code == exfacecam.MR_REJECTED then
            log.info("人脸识别模组拒绝该命令")
          end

3.3 exfacecam.MR_ABORTED

常量含义：AirCAMERA_1034摄像头录入/解锁算法已终止，值为2；
数据类型：number；
注意事项：通常因为检测到异常状态导致算法终止；
示例代码：if result_code == exfacecam.MR_ABORTED then
            log.info("算法已终止")
          end

3.4 exfacecam.MR_FAILED4_CAMERA

常量含义：相机打开失败，值为4；
数据类型：number；
注意事项：检查摄像头连接和初始化；
示例代码：if result_code == exfacecam.MR_FAILED4_CAMERA then
            log.info("相机打开失败")
          end

3.5 exfacecam.MR_FAILED4_INVALIDPARAM

常量含义：无效的参数，值为6；
数据类型：number；
注意事项：检查传入的指令参数格式是否正确；
示例代码：if result_code == exfacecam.MR_FAILED4_INVALIDPARAM then
            log.info("参数无效")
          end

3.6 exfacecam.MR_FAILED4_NOMEMORY

常量含义：内存不足，值为7；
数据类型：number；
注意事项：模组内部存储空间不足；
示例代码：if result_code == exfacecam.MR_FAILED4_NOMEMORY then
            log.info("模组存储空间不足")
          end

3.7 exfacecam.MR_FAILED4_UNKNOWNUSER

常量含义：未匹配到已录入用户，值为8；
数据类型：number；
注意事项：验证时人脸不匹配任何已注册用户；
示例代码：if result_code == exfacecam.MR_FAILED4_UNKNOWNUSER then
            log.info("人脸未识别")
          end

3.8 exfacecam.MR_FAILED4_MAXUSER

常量含义：录入超过最大用户数量，值为9；
数据类型：number；
注意事项：需先删除部分用户再录入；
示例代码：if result_code == exfacecam.MR_FAILED4_MAXUSER then
            log.info("用户数量已达上限")
          end

3.9 exfacecam.MR_FAILED4_FACEENROLLED

常量含义：人脸已录入，值为10；
数据类型：number；
注意事项：不允许重复录入同一人脸；
示例代码：if result_code == exfacecam.MR_FAILED4_LIVENESSCHECK then
            log.info("活体检测失败")
          end

3.10 exfacecam.MR_FAILED4_LIVENESSCHECK

常量含义：活体检测失败，值为12；
数据类型：number；
注意事项：可能使用了照片或视频攻击；
示例代码：if result_code == exfacecam.MR_ABORTED then
            log.info("人脸识别模组录入/解锁算法已终止")
          end

3.11 exfacecam.MR_FAILED4_TIMEOUT

常量含义：录入或验证超时，值为13；
数据类型：number；
注意事项：增加 timeout 参数或检查摄像头工作状态；
示例代码：if result_code == exfacecam.MR_FAILED4_TIMEOUT then
            log.info("操作超时，请重试")
          end

3.12 exfacecam.MR_FAILED4_AUTHORIZATION

常量含义：加密芯片授权失败，值为14；
数据类型：number；
注意事项：检查加密芯片连接和授权状态；
示例代码：if result_code == exfacecam.MR_FAILED4_AUTHORIZATION then
            log.info("授权失败")
          end

四、函数详解

4.1 exfacecam.open(param)

功能

初始化AirCAMERA_1034人脸识别模组和摄像头。 AirCAMERA_1034摄像头自带红外摄像头与识别算法，通过 UART 独立完成注册、验证、删人等人脸业务；USB 摄像头 则经 USB 接口初始化，仅用于拍照归档，不参与识别。open() 依次复位并探测人脸模组，再按需初始化 USB 摄像头，两者通道独立、互不依赖。

注意事项

• 必须在 task 中调用；

参数

param

参数含义：人脸识别初始化配置表； 数据类型：table； 是否必选：必须传入此参数； 参数示例： param { 参数含义：人脸模组连接的 UART 编号； 数据类型：number； 是否必选：必选； 注意事项：波特率固定为 115200/8N1/无校验/无流控； 参数示例: 2 **参数名称： param.face_uart **

参数含义：人脸模组复位 GPIO； 数据类型：number/nil； 是否必选：可选； 注意事项：先拉低 100ms 再拉高 500ms 完成复位，之后保持高电平，不填或填 nil 则跳过； 参数示例: nil **参数名称： param.face_rst **

参数含义：摄像头接口类型； 数据类型：number； 是否必选：可选； 注意事项：填写 camera.USB 或 camera.DVP，不填则只初始化人脸模组； 参数示例: camera.USB **参数名称： param.id **

参数含义：摄像头像素宽度； 数据类型：number； 是否必选：使用摄像头时必选； 参数示例: 1280 **参数名称： param.sensor_width **

参数含义：摄像头像素高度； 数据类型：number； 是否必选：使用摄像头时必选； 参数示例: 720 **参数名称： param.sensor_height **

参数含义：USB 端口号； 数据类型：number； 是否必选：使用摄像头时必选； 参数示例: 1 **参数名称： param.usb_port **

}

返回值

local result = exfacecam.open(param)

此处有一个返回值 result

result

含义说明：初始化是否成功；
数据类型：boolean；
取值范围：true/false；
注意事项：失败返回 false，需检查接线和供电；
返回示例：true

示例

local result = exfacecam.open({
    id = camera.USB,
    sensor_width = 1280,
    sensor_height = 720,
    usb_port = 1,
    save_path = "/ram/face_test.jpg",
    face_uart = 2,
    face_rst = nil,
})
log.info("初始化结果:", result)

4.2 exfacecam.register(opt)

功能

人脸录入。只需拍摄一张正脸照片即可完成录入，不需要多方向配合。

注意事项

• 必须在 exfacecam.open() 成功后调用；

• 此接口是阻塞接口，必须在 task 中调用，调用后需等待录入结束才返回。结束并返回的三种情况：录入成功、录入失败、或录入超时；

• 录入过程中 on_state 回调持续触发，返回人脸位置和姿态信息；

• exfacecam.register() 不禁止重复录入，但模组对已录入人脸会返回 MR_FAILED4_FACEENROLLED(10) 拒绝；

参数

opt

参数含义：录入配置表； 数据类型：table； 是否必选：必须传入此参数； 参数示例： opt { 参数含义：用户姓名(“UTF-8”编码格式)； 数据类型：string； 是否必选：必选； 注意事项：最长 32 字节，超出自动截断； 参数示例: "TestUser" **参数名称： opt.name **

参数含义：是否管理员； 数据类型：number； 取值范围：0/1； 是否必选：可选，默认 0； 注意事项：1=管理员，0=普通用户； 参数示例: 0 **参数名称： opt.admin **

参数含义：录入超时时间(秒)； 数据类型：number； 是否必选：可选，默认 15； 注意事项：超时后返回 exfacecam.MR_FAILED4_TIMEOUT 错误码； 参数示例: 15 **参数名称： opt.timeout **

参数含义：实时人脸状态回调函数； 数据类型：function； 是否必选：可选； 注意事项：回调原型为 function(state, left, top, right, bottom, yaw, pitch, roll)； state 取值：0=正常, 1=无人脸, 2=偏上, 3=偏下, 4=偏左, 5=偏右, 6=太远, 7=太近, 8=眉毛遮挡, 9=眼睛遮挡, 10=面部遮挡, 11=角度异常； left, top, right, bottom 为人脸框距图片四边距离(像素)； yaw, pitch, roll 为头部姿态角(度)； **参数名称： opt.on_state **

}

返回值

local ok, user_id = exfacecam.register(opt)

此处有两个返回值 ok, user_id

ok

含义说明：录入是否成功；
数据类型：boolean；
取值范围：true/false；
注意事项：成功返回 true，失败返回 false，失败时 user_id 为错误码(见第三章常量)；
返回示例：true

user_id

含义说明：录入结果；
数据类型：number；
取值范围：成功时返回用户 ID（正整数），失败时返回错误码，当前数字错误码取值：{1, 2, 4, 5, 6, 7, 8, 9, 10, 12, 13, 14}，加上字符串 "timeout"（通信超时）；
注意事项：每次录入成功后 user_id 自增；
返回示例：1

示例

local function faceStateCallback(state, left, top, right, bottom, yaw, pitch, roll)
    if state == 0 then
        log.info("录入中", "已检测到人脸")
    elseif state == 1 then
        log.info("录入中", "请正对摄像头")
    end
end


local ok, user_id = exfacecam.register({
    name = "TestUser",
    admin = 0,
    timeout = 15,
    on_state = faceStateCallbackd
})
if ok then
    log.info("录入成功, user_id=", user_id)
else
    log.error("录入失败, 错误码=", user_id)
end

4.3 exfacecam.verify(opt)

功能

人脸验证/解锁。用户正对摄像头，合宙主控模组实时检测人脸并与已录入用户比对，返回匹配结果。

注意事项

• 必须在 exfacecam.open() 成功后调用；

• 此接口是阻塞接口，必须在 task 中调用，调用后需等待验证结束才返回。结束并返回的三种情况：验证成功、验证失败、或验证超时；

• 验证过程中 on_state 回调持续触发；

参数

opt

参数含义：验证配置表； 数据类型：table； 是否必选：必须传入此参数； 参数示例： opt { 参数含义：验证超时时间(秒)； 数据类型：number； 是否必选：可选，默认 30； 注意事项：超时后返回错误码 13(MR_FAILED4_TIMEOUT)； 参数示例: 15 **参数名称： opt.timeout **

参数含义：实时人脸状态回调函数； 数据类型：function； 是否必选：可选； 注意事项：回调原型同 register 的 on_state； 参数示例: function(state, left, top, right, bottom, yaw, pitch, roll) ... end **参数名称： opt.on_state **

}

返回值

local ok, result = exfacecam.verify(opt)

此处有两个返回值 ok, result

ok

含义说明：验证是否成功；
数据类型：boolean；
取值范围：true/false；
注意事项：成功返回 true，失败返回 false。失败时 result 为错误码；
返回示例：true

result

含义说明：验证结果；
数据类型：table 或 number；
取值范围：成功时返回 {user_id, name, admin, unlock_status} 表格；
          user_id - 匹配到的用户 ID(number)；
          name - 用户姓名(string)；
          admin - 是否管理员(number, 1/0)；
          unlock_status - 解锁状态(number, 200=验证成功, 204=闭眼验证成功)；
          失败时返回错误码(number，见第三部分)；
注意事项：验证成功时返回用户信息表 {user_id, name, admin, unlock_status}；若成功但模组回复的用户数据不完整（不足 36 字节或缺失），则返回空表 {}，仅表示验证通过但无法解析出用户详情。；
返回示例：{user_id=1, name="TestUser", admin=0, unlock_status=200}

示例

local function verifyCallback(state, left, top, right, bottom, yaw, pitch, roll)
    if state == 0 then
        log.info("验证中", "已检测到人脸")
    end
end

local ok, result = exfacecam.verify({
    timeout = 15,
    on_state = verifyCallback
})
if ok and result and result.user_id then
    log.info("验证成功", "user_id=", result.user_id, "name=", result.name)
else
    log.error("验证失败", "错误码=", result)
end

4.4 exfacecam.list()

功能

获取所有已注册用户的数量和 ID 列表。

注意事项

• 必须在 task 中调用；

参数

无参数

返回值

local ok, count, ids = exfacecam.list_users()

此处有三个返回值 ok, count, ids

ok

含义说明：查询是否成功；
数据类型：boolean；
取值范围：true/false；
返回示例：true

count

含义说明：已注册用户数量；
数据类型：number；
取值范围：大于等于 0；
返回示例：4

ids

含义说明：已注册用户 ID 数组；
数据类型：table；
取值范围：number 数组，每个元素为一个用户 ID；
注意事项：数组索引从 1 开始；
返回示例：{1, 2, 3, 4}

示例

local ok, count, ids = exfacecam.list()
if ok then
    log.info("共", count, "个用户")
    for i, id in ipairs(ids) do
        log.info("  id=", id)
    end
end

4.5 exfacecam.query(uid)

功能

获取指定用户的信息。

注意事项

• 必须在 task 中调用；

参数

uid

参数含义：用户 ID； 数据类型：number； 是否必选：必须传入此参数； 参数示例: 1 **参数名称： uid **

返回值

local ok, info = exfacecam.get_user(uid)

此处有两个返回值 ok, info

ok

含义说明：查询是否成功；
数据类型：boolean；
取值范围：true/false；
返回示例：true

info

含义说明：用户信息；
数据类型：table；
取值范围：{name, admin}；
          name - 用户姓名(string)；
          admin - 是否管理员(number, 1/0)；
返回示例：{name="TestUser", admin=0}

示例

local ok, info = exfacecam.get_user(1)
if ok then
    log.info("用户1:", info.name, info.admin == 1 and "(管理员)" or "")
end

4.6 exfacecam.delete(uid)

功能

删除指定 ID 的用户。

注意事项

• 必须在 task 中调用；

参数

uid

参数含义：用户 ID； 数据类型：number； 是否必选：必须传入此参数； 参数示例: 1 **参数名称： uid **

返回值

local ok = exfacecam.delete(uid)

此处有一个返回值 ok

ok

含义说明：删除是否成功；
数据类型：boolean；
取值范围：true/false；
返回示例：true

示例

local ok = exfacecam.delete(1)
log.info("清空结果:", ok)

4.7 exfacecam.clear()

功能

删除所有已注册用户（包括人脸用户和掌静脉用户）。

参数

无参数

返回值

local ok = exfacecam.clear()

此处有一个返回值 ok

ok

含义说明：删除是否成功；
数据类型：boolean；
取值范围：true/false；
返回示例：true

示例

local ok = exfacecam.clear()
log.info("清空结果:", ok)

4.8 exfacecam.get_version()

功能

获取人脸识别模组固件版本信息。

注意事项

• 必须在 task 中调用；

参数

无参数

返回值

local ok, version = exfacecam.get_version()

此处有两个返回值 ok, version

ok

含义说明：查询是否成功；
数据类型：boolean；
取值范围：true/false；
返回示例：true

version

含义说明：固件版本字符串；
数据类型：string；
取值范围：人脸识别模组返回的原始版本信息；
返回示例："#BFP3E2V1.2.8"

示例

local ok, ver = exfacecam.get_version()
if ok then
    log.info("人脸识别模组固件:", ver)
end

4.9 exfacecam.close()

功能

关闭人脸识别模组和摄像头。

参数

无参数

返回值

无

示例

exfacecam.close()

4.10 exfacecam.version()

功能

获取库文件版本信息。

参数

无参数

返回值

local ver = exfacecam.version()

此处有一个返回值 ver

ver

含义说明：库文件版本信息，string 类型；
数据类型：string；
取值范围：14 位数字（年月日时分），例如："202607301800"；
返回示例："202607301800"

示例

log.info("exfacecam version:", exfacecam.version())

五、版本更新说明

版本号：202607311200

1、更新时间：2026-07-31 12:00

2、更新内容

• 新增exfacecam相关接口

六、产品支持说明

目前仅Air 1601/1602/8101支持 exfacecam 扩展库；