什么是用户指令？

用户和设备进行对话时候，有可能让向设备发出一些指令，比如：开关灯、唱首歌、跳个舞 等等。
针对上面这些情况，就需使用指令配置intention 来完成。

内置指令

指令配置 intention 中, 为了方便，提供了一些自定义预先定义好的指令，开发者只需要按需配置上即可，并不需要写任何逻辑。

目前内置的指令有：

指令	功能
__sleep__	进入休眠状态
__play_music__	播放音频(只支持16k/24k)
__io_high__	让硬件引脚输出高电平
__io_low__	让硬件引脚输出低电平

const espAi = require("esp-ai"); 
const config = { 
    gen_client_config: ()=>({ 
        // ...
        /**
         * 意图表：当用户唤醒 小明同学 后，小明同学可以做下面的任务
        */
        intention: [ 
            // 休眠
            {
                // 关键词
                key: ["退下吧", "退下"],
                // 内置的睡眠指令
                instruct: "__sleep__",
                message: "我先退下了，有需要再叫我。"
            },
            // 高电平指令
            { 
                key: ["帮我开灯"], 
                instruct: "__io_high__", // 向客户端发送的指令
                message: "开啦！",
                pin: 21                 // 控制的引脚
            },
            // 低电平指令
            { 
                key: ["帮我关灯"], 
                instruct: "__io_low__", // 向客户端发送的指令
                message: "关啦！",
                pin: 21                 // 控制的引脚
            },
            // 音频播放
            {
                /**
                 * 正则匹配
                 * 如：播放音乐最后的倔强  
                 * 返回匹配的字符串为匹配成功
                */
                key: async (text = "", llm_historys) => {
                    const regex = /^(播放音乐)(.*)$/;
                    const match = text.match(regex);
                    if (match) {
                        const songName = match[2];
                        console.log("音乐名称:", songName);
                        return songName;
                    } else {
                        return false;
                    }
                },
                // 向客户端发送的指令
                instruct: "__play_music__",
                message: "好的！",
                /**
                 * 用于返回音频地址和播放进度
                 * 目前只支持 mp3、wav 格式
                 * @param {String} name 是歌曲名称
                 * @return {number} seek 进度： （以秒为单位）
                 * @return {message} 找不到数据时的TTS
                */ 
                music_server: async (name, { user_config }) => { 
                    return {
                        url:"https://xiaomingio.top/music.mp3",
                        seek: 0,
                        message: message
                    };
                },
                /**
                 * 当音频结束后的回调
                 * @param {object} arg.break_second  停止时的进度，单位秒。也就是用户播放了到了多少秒（seek+play_time）
                 * @param {object} arg.play_time     实际播放音频的时间，单位秒。
                 * @param {object} arg.seek          音频开始播放时间，其实也就是 music_server 函数中返回的 seek 值
                 * @param {object} arg.start_time    开始播放音频的 Unix 毫秒数时间戳
                 * @param {object} arg.end_time      结束播放音频的 Unix 毫秒数时间戳
                 * @param {object} arg.event         结束原因： "user_break" 用户打断 | play_end 播放完毕 | foo 未知事件 
                */
                on_end: (arg) => {
                    // 请求业务服务器保存进度信息 ...
                    console.log(arg);
                }
            },
        ],

    })
};

const espAiIns = espAi(config);

自定义指令

如果内置指令无法满足你的业务，你可以使用自定义指令来做任何事情。

就像下面这样，你在的服务端配置一个指令，指令词为：开灯/打开灯。
如果用户说了这两个词，那你的客户端将会接收到 device_open_001 指令。

Nodejs

const config = {
    gen_client_config: async (){
        return {
            intention: [
                { 
                    key: ["开灯", "打开灯"], 
                    // 向设备发送一个字符串，客户端使用 onEvent 监听
                    instruct: "device_open_001", 
                    message: "好的"
                }, 
            ]
        }
    }
}

Arduino

void on_command(String command_id, String data) { 
    if (command_id == "device_open_001") { 
        digitalWrite(led_pin, LOW);
    }
}

void setup() {
    Serial.begin(115200);  
    pinMode(led_pin, OUTPUT);   
    
    esp_ai.begin({ ...  });
    // 用户指令监听
    esp_ai.onEvent(on_command);
}