Wukong AI

基于 TuyaOS Wukong AI 硬件开发框架，IPC 开发框架深度融合听觉 + 视觉感知能力，对外能够提供多模态对话能力。可以应用于日常对话、家庭安防、老人看护、儿童玩具、儿童教辅等各领域。

相关文件

• tuya_ipc_ai_station.h：AI 对话核心
• tuya_ipc_ai_player.h：音频播放（TTS + 音乐）
• tuya_mcp_server.h：MCP 工具服务

AI 对话

API 说明

初始化

/**
 * @brief init ai chat
 * 
 * @param[in] event_cb: ai event cb
 * @param[in] audio_cb: audio play cb
 * @param[in] cloud_vad_flag. TRUE: enable cloud vad; FALSE: disable cloud vad
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h 
 */
OPERATE_RET tuya_ipc_ai_chat_init(TUYA_IPC_AI_CMD_CB event_cb, TUYA_IPC_AI_AUDIO_PLAY_CB audio_cb, BOOL_T cloud_vad_flag);

参数说明

参数	说明
event_cb	需要您对接的一些操作命令或者状态
audio_cb	音频播放的回调函数
cloud_vad_flag	是否开启云端 VAD

开启数据发送

用于开始一次 AI 对话，并发送数据。调用后，会从 ring buffer 中取当前时间往前 0.5 秒左右的音视频数据发送给云端。

/**
 * @brief start a conversation
 * 
 * @param VOID 
 * 
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h 
 */
OPERATE_RET tuya_ipc_ai_station_start_act();

停止数据发送

用于结束 AI 对话的数据发送。调用后，设备会停止向云端发送数据，并开始接受云端返回的数据。云端数据会通过 TUYA_IPC_AI_CMD_CB event_cb, TUYA_IPC_AI_AUDIO_PLAY_CB audio_cb 通知给您。

/**
 * @brief stop a conversation
 * 
 * @param VOID
 * 
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h 
 */
OPERATE_RET tuya_ipc_ai_station_stop_act();

对接说明

单次对话模式

一次 Start 和 Stop 后，等待云端数据返回完成后，才进行下一次对话。

连续对话模式

通过设备本地音频检测算法，来感知是否有人在问话。这种情况下，需要处理 AI 对话被打断的场景，也需要重点关注设备本身音频检测算法的效果。

音乐技能

音乐技能基于悟空 AI 对话框架扩展，支持通过语音指令控制音乐播放。云端识别意图后下发 E_AI_CMD_MUSIC_CONTROL 事件，设备调用播放接口完成播放。

API 说明

播放音乐

从指定 URL 开始播放音乐。

/**
 * @brief start music playback
 *
 * @param[in] url: audio stream URL
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ai_player_start_music(CHAR_T *url);

停止音乐

停止当前音乐播放并清空播放进度。

/**
 * @brief stop music playback
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ai_player_stop_music(VOID);

暂停音乐

暂停当前音乐播放，保留播放进度。

/**
 * @brief pause music playback
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ai_player_pause_music(VOID);

恢复音乐

从暂停位置继续播放音乐。

/**
 * @brief resume music playback
 *
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_ipc_ai_player_resume_music(VOID);

实现方式

在 TUYA_IPC_AI_CMD_CB 回调中处理音乐相关事件：

• E_AI_CMD_MUSIC_CONTROL：收到云端指令，args 为 TUYA_IPC_AI_MUSIC_INFO_T *，包含 action（play/stop/resume/prev/next）、url 和 has_tts 标志。
• E_AI_CMD_CHAT_PLAYER_FIN：TTS 播放完毕，若 has_tts=TRUE 需等此事件后再开始播放音乐。
• E_AI_CMD_MUSIC_PLAYER_START/FIN/PAUSE：音乐播放状态通知。

示例请参考 ty_sdk_ai_chat.c。

技术说明

当 has_tts=TRUE 时，需等 TTS 播放完毕（E_AI_CMD_CHAT_PLAYER_FIN）后再调用 tuya_ipc_ai_player_start_music()，否则两路音频会冲突。

MCP（模型上下文协议）

MCP 允许大模型在对话中调用设备本地 “工具”（如查询状态、设置音量），SDK 负责协议解析与工具调度，开发者只需注册工具和回调。

API 说明

初始化服务

/**
 * @brief init MCP server
 *
 * @param[in] name: server name
 * @param[in] version: server version
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
OPERATE_RET tuya_mcp_server_init(CONST CHAR_T *name, CONST CHAR_T *version);

注册工具

向 MCP 服务注册一个工具。推荐使用便捷宏 TUYA_MCP_TOOL_ADD，支持通过可变参数直接追加参数定义。

TUYA_MCP_TOOL_ADD(name, description, callback, user_data, ...properties);

参数说明

参数	说明
name	工具名称，模型通过此名称识别和调用工具
description	工具描述，直接影响模型能否正确理解工具用途
callback	工具被调用时的回调函数
user_data	传递给回调的自定义数据，不需要时传 NULL
properties	工具参数定义，通过以下宏声明

参数定义宏

宏	说明
MCP_PROP_INT(name, desc)	整型参数
MCP_PROP_INT_DEF(name, desc, def_val)	整型参数，带默认值
MCP_PROP_INT_RANGE(name, desc, min, max)	整型参数，带取值范围
MCP_PROP_INT_DEF_RANGE(name, desc, def_val, min, max)	整型参数，带默认值和取值范围
MCP_PROP_BOOL(name, desc)	布尔类型参数
MCP_PROP_BOOL_DEF(name, desc, def_val)	布尔类型参数，带默认值
MCP_PROP_STR(name, desc)	字符串类型参数
MCP_PROP_STR_DEF(name, desc, def_val)	字符串类型参数，带默认值

工具回调原型

/**
 * @param[in] properties: parameters passed by the model
 * @param[out] ret_val: result returned to the model
 * @param[in] user_data: user defined data
 * @return OPRT_OK on success. Others on error, please refer to tuya_error_code.h
 */
typedef OPERATE_RET (*MCP_TOOL_CALLBACK)(
    CONST MCP_PROPERTY_LIST_T *properties,
    MCP_RETURN_VALUE_T *ret_val,
    VOID *user_data);

销毁服务

释放所有已注册的工具及相关资源。

/**
 * @brief destroy MCP server and release all tools
 */
VOID tuya_mcp_server_destroy(VOID);

实现方式举例

tuya_mcp_server_init("AI_Ipc", "1.0");

TUYA_MCP_TOOL_ADD("device.info.get", "Get device info.", __get_device_info, NULL);

TUYA_MCP_TOOL_ADD("device.audio.volume_set", "Set volume.",
    __set_volume, NULL,
    MCP_PROP_INT_RANGE("volume", "Volume level (0-100).", 0, 100));

在回调中通过 tuya_mcp_return_value_set_json()、set_bool()、set_image() 等设置返回值。完整示例请参考 ty_sdk_ai_mcp_example.c。

技术说明

工具的 description 直接影响模型能否正确调用，建议使用清晰的英文描述。

常见问题

为什么没有收到云端的音频数据？

目前云端只支持 pcm 和 opus 的音频格式，可能是由于放入 ring buffer 的音频数据编码格式不符合要求。