宠物检测、宠物档案与宠物音频

一、概述

涂鸦宠物检测 SDK 提供宠物检测、宠物档案管理与宠物音频文件下发MQTT能力。

1.1 能力一览

能力	说明	是否可选
宠物检测	基于视频帧的检测+追踪，结果通过回调上报	核心能力
宠物档案	绑定/解绑/更新/查询档案，特征由 TKL 实现	按需（need_pet_profile）
宠物音频	云端通过 MQTT 下发/删除音频文件，存于指定目录	按需（need_audio_download）

1.2 分层与对接点

应用层（客户）
    ↓ 调用 tuya_pet_detect_init / update / get_pet_list，注册回调
SDK 层（svc_pet_detect_api）
    ↓ 取帧、调度检测、档案同步、MQTT 文件
TAL 层（组件内部）
    ↓ 直接调用 TKL 函数
TKL 层（客户实现）
    ↓ tkl_npu_pet_algo_init、tkl_npu_pet_detect_track 等
算法/硬件（客户）

• 客户直接使用： tuya_pet_detect_api.h 中的 API 与类型。
• 客户必须实现： TKL 层函数（见 tkl_npu_pet_algo.h），在自有工程中实现并参与链接，无需注册。

---

二、集成步骤总览

1. 准备路径与目录
   分配并填写 TUYA_PET_DETECT_PATH_T 的三个目录：model_dir、image_dir、audio_dir（按需必填）。

2. 实现 TKL 层
   至少实现 tkl_npu_pet_algo_init、tkl_npu_pet_detect_track；需要档案能力时再实现特征相关 TKL 函数。

3. 调用初始化 API
   在应用启动合适时机调用 tuya_pet_detect_init()，传入路径、参数、回调和可选 MQTT 参数。

4. 处理回调
   在检测结果回调中强转 result 为自有或示例结果结构体，处理检测/告警；按需处理档案操作结果与 MQTT 文件同步。

---

三、路径与初始化

3.1 路径结构体（必读）

path_opt 必传且不可为 NULL。所有路径通过 一个结构体 传入，三个字段均为 指针（const char *），可指向任意长度字符串；某一路径传 NULL 或空串表示该路径未使用。SDK 在 init 时会将非 NULL 路径拷贝到内部（长度超过 128 会截断），调用方在 init 返回后即可释放或复用原缓冲区。

#define TUYA_PET_DETECT_PATH_LEN (128)  /* SDK 内部拷贝时最大长度，传指针时字符串可更长 */

typedef struct {
    const char *model_dir;   /* 模型文件目录，need_pet_profile=1 时必填（非 NULL 且非空串）；否则可 NULL */
    const char *image_dir;   /* 脸图存放目录，store_pet_face_image=1 时必填（非 NULL 且非空串）；否则可 NULL */
    const char *audio_dir;   /* 音频存放目录，need_audio_download=1 时必填（非 NULL 且非空串）；否则可 NULL */
} TUYA_PET_DETECT_PATH_T;

• model_dir：算法模型文件所在目录，仅当 need_pet_profile=1 时必填（非 NULL 且非空串）。
• image_dir：宠物脸图保存目录，仅当 store_pet_face_image=1 时必填（且仅在 need_pet_profile=1 时生效）。
• audio_dir：宠物音频下载与删除的目录；仅当 need_audio_download=1 时必填。客户需自行保存该路径（如全局变量），供 file_sync_cb 扫描上报、本地播放等使用，SDK 不提供路径查询接口。

3.2 初始化接口

OPERATE_RET tuya_pet_detect_init(
    const TUYA_PET_DETECT_PATH_T        *path_opt,   /* 路径配置，必传且不可为 NULL */
    const void                          *params,     /* 算法配置，need_pet_profile=1 时必填，否则可 NULL */
    const TUYA_PET_DETECT_CB_T          *cb,         /* 检测结果与档案操作回调，不需要时传 NULL */
    const TY_SYS_CUSTOM_MQTT_PARAM_T     *mqtt_param, /* need_audio_download=1 时必填，否则 NULL */
    const TUYA_PET_DETECT_INIT_OPT_T     *init_opt    /* 初始化选项，NULL=默认全关；需传入并置位以开启功能 */
);

初始化选项（init_opt）：

typedef struct {
    unsigned int need_pet_profile     : 1;  /* 1=启用宠物档案（模型、档案同步、档案处理等） */
    unsigned int need_audio_download  : 1;  /* 1=启用 MQTT 宠物音频下载（需传 mqtt_param） */
    unsigned int store_pet_face_image : 1;  /* 1=将宠物脸图下载并保存到 image_dir */
} TUYA_PET_DETECT_INIT_OPT_T;

• init_opt == NULL：默认全关，三者均为 0；需显式传入 init_opt 并设置相应位为 1 以开启宠物档案/音频下载/存脸图。
• 仅用音频下载：need_pet_profile = 0，need_audio_download = 1，只填 path_opt.audio_dir，params 可传 NULL，mqtt_param 必填。

功能与必填参数对照（防错）：

开启的功能	条件	必填参数
宠物档案	need_pet_profile == 1	path_opt->model_dir 非 NULL 且非空串；params 非 NULL
存宠物脸图	store_pet_face_image == 1	path_opt->image_dir 非 NULL 且非空串（且仅 need_pet_profile=1 时生效）
音频下载	need_audio_download == 1	path_opt->audio_dir 非 NULL 且非空串；mqtt_param 非 NULL

参数校验与兜底：
SDK 在 init 内会按上表做参数校验；必填项不满足时返回错误码（如 OPRT_INVALID_PARM），不进行初始化，不访问非法指针。调用方应始终检查 tuya_pet_detect_init 返回值，仅当返回 OPRT_OK 后再使用宠物检测相关能力，避免乱填参数导致异常。

3.3 对接示例（完整功能）

#include "tuya_pet_detect_api.h"

/* 客户自存音频目录，供 file_sync_cb / 播放等使用 */
static char s_pet_audio_dir[TUYA_PET_DETECT_PATH_LEN] = {0};

void app_pet_detect_init(const char *base_path)
{
    static char s_model_dir[TUYA_PET_DETECT_PATH_LEN];
    static char s_image_dir[TUYA_PET_DETECT_PATH_LEN];
    static char s_audio_dir[TUYA_PET_DETECT_PATH_LEN];
    snprintf(s_model_dir, sizeof(s_model_dir), "%s/model", base_path);
    snprintf(s_image_dir, sizeof(s_image_dir), "%s/face_image", base_path);
    snprintf(s_audio_dir, sizeof(s_audio_dir), "%s/audio", base_path);
    strncpy(s_pet_audio_dir, s_audio_dir, sizeof(s_pet_audio_dir) - 1);

    TUYA_PET_DETECT_PATH_T path_opt = {
        .model_dir = s_model_dir,
        .image_dir = s_image_dir,
        .audio_dir = s_audio_dir,
    };

    /* 算法配置：类型由客户与 SDK 约定，此处为示例结构体 */
    TUYA_PET_DETECT_CONFIG_T pet_config = {0};
    pet_config.detect_body_opt = true;
    pet_config.detect_face_opt = true;
    pet_config.track_opt = true;
    /* ... 其他字段按需赋值 ... */

    TUYA_PET_DETECT_CB_T cb = {
        .pet_detect_result_get_cb = my_detect_result_cb,
        .oper_result_cb           = my_operate_result_cb,
    };

    TY_SYS_CUSTOM_MQTT_PARAM_T mqtt_param = {
        .status_cb    = my_audio_status_cb,
        .file_sync_cb = my_pet_file_sync_cb,
    };

    /* 默认全关，完整功能需显式传 init_opt 并置位 */
    TUYA_PET_DETECT_INIT_OPT_T init_opt = {
        .need_pet_profile = 1,
        .need_audio_download = 1,
        .store_pet_face_image = 1,
    };
    OPERATE_RET ret = tuya_pet_detect_init(&path_opt, &pet_config, &cb, &mqtt_param, &init_opt);
    if (ret != OPRT_OK) {
        /* 初始化失败处理 */
    }
}

---

四、回调说明

4.1 检测结果回调

typedef int (*TUYA_PET_DETECT_GET_DETECT_RESULT_CB)(void *result, int result_count);

• result：本帧检测结果缓冲区，在回调内强转为客户自定义或 Demo 提供的结果结构体（如 TUYA_PET_DETECT_RESULT_T*）。
• result_count：本帧检测到的目标数量。
• 重要： result 所指内存在回调返回后可能被 SDK 复用或释放，不可在回调外持有该指针；如需保留请于回调内拷贝。

4.2 档案操作结果回调

typedef int (*TUYA_PET_DETECT_GET_OPERATE_RESULT_CB)(TUYA_PET_FILE_OPERATE_E operate, int err_code);

绑定/解绑/更新/查询完成后触发；operate 表示操作类型，err_code == 0 表示成功。

4.3 MQTT 文件状态与同步（可选）

• status_cb：文件下发/删除状态变更（下载中、成功、失败等），eventType 区分下载/删除，status 使用文档中的 DOWNLOAD_STATUS_* / DELETE_STATUS_*。
• file_sync_cb：文件操作完成后由 SDK 调用；回调内客户使用自存的音频目录（如上面的 s_pet_audio_dir）扫描文件（如 .wav），将列表通过 DP 上报与面板同步。

---

五、其他 API

5.1 运行时更新参数

OPERATE_RET tuya_pet_detect_update(const void *params);

params 与 tuya_pet_detect_init 时传入类型一致，透传到 TKL 的 tkl_npu_pet_algo_update()。

5.2 查询档案列表

OPERATE_RET tuya_pet_detect_get_pet_list(TUYA_PET_FILE_INFO_T *pet_list, OUT int *count);

调用方预分配 pet_list（建议长度 PET_MEMBER_MAX），返回时 count 为实际档案数量。

---

六、TKL 层对接清单

算法能力由 TKL 独立函数 提供，声明于 tkl_npu_pet_algo.h（由 SDK 或适配层提供头文件，客户实现并参与链接）。

6.1 必须实现（仅检测）

函数	说明
tkl_npu_pet_algo_init(const char *model_path, const void *params)	加载模型、初始化算法；返回 0 成功，非 0 失败。
tkl_npu_pet_detect_track(const void *image, void *result_out, int *result_count)	检测+追踪；image 强转为 tkl_pet_image_t*，结果写入 result_out，并设置 *result_count。

6.2 按需实现（档案能力）

函数	说明
tkl_npu_pet_feature_extract_from_data(...)	从图片数据（JPEG/PNG 等）提取单张脸特征。
tkl_npu_pet_face_feature_add	档案添加时写入特征。
tkl_npu_pet_face_feature_update	档案更新时刷新特征。
tkl_npu_pet_face_feature_delete	档案删除时移除特征。

6.3 可选

函数	说明
tkl_npu_pet_algo_release(void)	检测线程退出时释放资源。
tkl_npu_pet_algo_update(const void *params)	对应 tuya_pet_detect_update()。
tkl_npu_pet_detect_result_buffer_size(void)	返回结果缓冲区所需字节数，未实现则默认 4096。
tkl_npu_pet_face_feature_query	按档案 ID 查询特征，可用于删除前校验。

未实现的 TKL 函数由 SDK 提供弱符号桩参与链接（检测结果为空或对应档案能力不可用）。

6.4 图像与结果类型

• 输入图像：TAL 取帧后填充 tkl_pet_image_t（含 width、height、format、pic_data、pic_len 等），以 const void* 传入 tkl_npu_pet_detect_track，客户强转为 tkl_pet_image_t* 使用。
• 输出结果：result_out 由 SDK 分配，客户在 TKL 内强转为自有结果结构体并写入；结果结构体需与上层回调中强转类型一致（可参考 Demo 的 TUYA_PET_DETECT_RESULT_T 等）。

---

七、配置与结果类型参考

• 算法配置（params）：SDK 接口层使用 const void *params，具体类型由客户与 SDK 约定。Demo 中提供示例类型 TUYA_PET_DETECT_CONFIG_T（见 tuya_pet_detect_demo_types.h），客户可复用或自定义。
• 检测结果（result）：回调中 result 可强转为 Demo 提供的 TUYA_PET_DETECT_RESULT_T* 或客户自定义结构体，需与 TKL 写入的 result_out 布局一致。

详细字段与枚举见《涂鸦宠物SDK接口说明文档》及 Demo 头文件 tuya_pet_detect_demo_types.h。

---

八、注意事项与 FAQ

1. 路径
   三个目录均由客户分配并传入 path_opt；音频目录客户自存，用于 file_sync_cb 与播放。

2. 仅用 MQTT 音频、不用档案
   init_opt.need_pet_profile = 0，path_opt 只填 audio_dir，params 可 NULL，mqtt_param 必填。

3. result 指针生命周期
   仅在回调内有效，不可在回调外使用；需持久化请在回调内拷贝。

4. TKL 是否需要注册
   不需要。实现 TKL 函数并参与链接即可，SDK 通过 TAL 直接调用。

5. 结果缓冲区大小
   默认 4096 字节；若结果结构体更大，需实现 tkl_npu_pet_detect_result_buffer_size() 并返回实际所需字节数。

---