在一个ESP-AI程序中esp_ai.begin()、esp_ai.loop()这两个最基本的方法是必须调用的。下面将会列举出全部的方法，这些方法根据需要选择使用。

.begin

参数说明

见：客户端配置

案例代码

ESP_AI esp_ai;  

void setup() {
    Serial.begin(115200);

    ...

    bool debug = true;
    // 开始运行 ESP-AI
    esp_ai.begin({ debug });
}

.loop

固定在Arduino代码中的loop(){}中调用，用于处理硬件内部逻辑。一定要放到 loop() 中最顶部。

案例代码

ESP_AI esp_ai;  

void loop() {
    esp_ai.loop();

    // 其他代码...
}

.setWifiConfig

手动设置 wifi账号/wifi密码/api_key/自定义缓存数据 配置，设置后会重新连接wifi 除了 wifi 账号和和密码外其他都是可选的，不改是传入空字符串即可 设置成功会返回 true，失败返回 false

案例代码

JSONVar data;
data["wifi_name"] = "oldwang";
data["wifi_pwd"] = "oldwang520";
data["api_key"] = "xxx";
data["其他自定义数据"] = "xxx"; 
esp_ai.setWifiConfig(data); // 会重新连接wifi

.wifiIsConnected

返回是否连接 WiFi

案例代码

ESP_AI esp_ai;  
void loop() {
  esp_ai.loop();
  
  // 连接wifi后会返回 True，必须放到 esp_ai.loop(); 后面
  if (!esp_ai.wifiIsConnected()) {
    return;
  }
}

.localIP

返回设备本地IP，连接WiFi后存在

案例代码

Serial.println(esp_ai.localIP().c_str());

.wakeUp

调用这个方法会直接唤醒小明同学 然后进入对话流程。如果官方提供的唤醒方案无法满足你的业务场景，那你需要自行在合适的时机调用本函数。

案例代码

esp_ai.wakeUp()

.setVolume

参数说明

• 类型：float
• 范围：0-1

案例代码

// 设置音量 0-1
esp_ai.setVolume(0.8);

.onEvent

接收到用户的控制指令后的回调，比如用户让开灯或者关灯。你需要在这个回调中进行相应的操作。

这里面也能监听到语音识别后的结果和LLM推理的文字(需要服务端调用 sendToClient())，拿到这些文字后你可以将它渲染到屏幕上或进行其他操作。

案例代码

void on_command(const String& command_id, const String& data) {
  Serial.printf("\n收到指令：%s -- %s\n", command_id, data);

  // 控制小灯演示
  if (command_id == "device_open_001") {
    Serial.println("开灯");
    digitalWrite(led_pin, HIGH);
  }
  if (command_id == "device_close_001") {
    Serial.println("关灯");
    digitalWrite(led_pin, LOW);
  }

  // 对话信息
  if (command_id == "on_llm_cb") { 
    Serial.println(data);
  }
  if (command_id == "on_iat_cb") { 
    Serial.println(data);
  }
  if (command_id == "on_tts_cb") { 
    Serial.println(data);
  }
}

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

.onBegin

返回 false 则在 begin 时就停止程序执行。
如检查到电池没电了，应该提示没电了，而不应该让程序继续执行下去

示例代码:

bool onBegin(){   
  return true;  // 正常执行程序
  return true;  // 终止执行程序
}

void setup() {
    esp_ai.onBegin(onBegin);
    esp_ai.begin({ ... });
}

.onError

统一错误回调

错误码	错误信息
000	未知服务错误
001	服务内部错误
002	服务端认证错误
100	未知 IAT 服务错误
101	未知 IAT 服务连接失败
102	未知 IAT 服务调用错误
200	未知 LLM 服务错误
201	未知 LLM 服务连接失败
202	未知 LLM 服务调用错误
200	未知 TTS 服务错误
201	未知 TTS 服务连接失败
202	未知 TTS 服务调用错误

案例代码

void onError(const String& code, const String& at_pos, const String& message) {
  // some code...
}

void setup() {
  Serial.begin(115200); 
  // 错误监听, 需要放到 begin 前面，否则可能监听不到一些数据
  esp_ai.onError(onError);
  esp_ai.begin({ ...  });
}

.onAPInfo

板子连接不上时会启动热点并且调用本回调，收到这个回调说明该提示用户打开配网页面了

案例代码

// @url 配网地址, 有屏幕的情况下建议将 url 生成为二维码显示
void onAPInfo(const String& url, const String& ip, const String& onAPInfoap_name) {
  // some code...
}

void setup() {
  Serial.begin(115200); 
  esp_ai.begin({ ...  });
  // 用户指令监听
  esp_ai.onAPInfo(onAPInfo);
}

.onNetStatus

设备网络状态、与服务连接状态改变的回调

标志符	说明
"0"	未连接wifi
"0_ing"	正在连接wifi
"0_ap"	已经打开了配网热点，需要用户配网
"2"	未连接服务
"3"	已连接服务器

案例代码

void onNetStatus(const String& status) {
  // some code...
}

void setup() {
  Serial.begin(115200); 
  // 设备网络状态监听, 需要放到 begin 前面，否则可能监听不到一些数据
  esp_ai.onNetStatus(onNetStatus);
  esp_ai.begin({ ...  });
}

.onConnectedWifi

设备连接上wifi后的回调 device_ip 是局域网ip

案例代码

void onConnectedWifi(const String& status) {
  // some code...
}

void setup() {
  Serial.begin(115200);  
  esp_ai.onConnectedWifi(onConnectedWifi);
  esp_ai.begin({ ...  });
}

我会帮你将这些API方法整理成文档格式。以下是中文版本的整理:

.onSessionStatus

设备会话状态的回调函数。

状态标志说明:

标志符	说明
"xxx"	休息状态
"iat_start"	开始进行语音识别
"iat_end"	语音识别结束
"tts_chunk_start"	TTS片段开始(单次对话会存在多次)
"tts_chunk_end"	TTS片段结束(单次对话会存在多次)
"tts_real_end"	整个会话的TTS真正结束
"llm_end"	LLM推理完毕(推理完毕并不代表TTS完毕)
"session_end"	会话结束

示例代码:

void onSessionStatus(const String& status) {
    // 处理会话状态
}

void setup() {
    esp_ai.onSessionStatus(onSessionStatus);
    esp_ai.begin({ ... });
}

.onVolumeCb

监听设备音量变化。

void on_volume(float volume)
{ 
  Serial.printf("[Info] 当前音量: %f\n", volume);
}

esp_ai.onVolume(on_volume);

.onBindDevice

用户在配网页面点击 确认 按钮提交填写的表单数据后，并且wifi连接成功后会触发本回调。

开发者可以在本函数中发出设备绑定的请求。

并根据业务服务返回的结果来返回数据。

data 参数是配网页面中给到 set_config 接口的数据，直接使用 data["xxx"] 来读取数据，如：data["wifi_name"]

参数说明:

• device_id: 设备ID
• wifi_name: WiFi名称
• wifi_pwd: WiFi密码
• 其他: 其他扩展参数

返回值:

• 返回JSON字符串，message会直接在配网页面弹出
• 返回true表示绑定成功，将自动保存wifi等信息
• 返回false表示绑定失败

示例代码:

String onBindDevice(JSONVar data) {
    Serial.println("[Info] device_id: " + data["device_id"]);
    Serial.println("[Info] wifi_name: " + data["wifi_name"]);
    Serial.println("[Info] wifi_pwd: " + data["wifi_pwd"]);
    Serial.println("[Info] api_key: " + data["ext1"]);
    Serial.println("[Info] ext2: " + data["ext2"]);
    Serial.println("[Info] ext3: " + data["ext3"]);


    // 成功示例
    return "{\"success\":true,\"message\":\"设备激活成功，即将重启设备。\"}";
    
    // 失败示例
    return "{\"success\":false,\"message\":\"设备绑定失败，重启设备试试呢。\"}";
}

特别说明:

用户激活设备成功的条件：连网成功 && onBindDevice 返回成功

.getLocalData / .setLocalData

用于读取和设置存储在芯片中的数据。其实在硬件代码中主要是使用 getLocalData 而 setLocalData 一般用不上，因为配网页面一般就把用户数据存起来了，代码中只需要读取和验证即可。

连接业务服务是 device_id 一般需要传给服务器。

可操作的数据项:

• device_id 设备ID (仅可读)
• wifi_name
• wifi_pwd
• api_key
• 任何自定义数据

示例代码:

// 读取数据
String ext1 = getLocalData("ext1");

// 设置数据
setLocalData("ext1", "自定义数据xxx");

.getLocalAllData

获取存储在芯片中的全部数据

示例代码:

JSONVar data = getLocalAllData(); 
Serial.println(data["wifi_name"]);

.tts

手动控制设备输出语音。

示例代码:

esp_ai.tts("要播放的文本内容");

.stopSession

停止当前会话，会打断TTS等操作。当硬件端需要停止会话时，必须使用此方法。

示例代码:

esp_ai.stopSession();

.onPosition

获取设备地理位置信息的回调函数。利用设备连接的WiFi或IPv4地址进行解析，设备连接WiFi后会执行一次。

参数说明:

• ip: WiFi的公网临时IP
• nation: 国家
• province: 省份
• city: 城市

示例代码:

void onPosition(const String& ip, const String& nation, const String& province, const String& city, const String& latitude, const String& longitude) {
    // 处理位置信息
}

void setup() {
    esp_ai.onPosition(onPosition);
    esp_ai.begin({ ... });
}

.clearData

清除设备所有数据，包括开发者存储的数据和配网信息

示例代码:

void setup() {
    esp_ai.begin({ ... });

    esp_ai.clearData();
}

.onRepeatedlyClick

按五次按钮回调，内部会自动执行清除配网信息的操作， 如果开发者还需要执行其他操作，请在函数回调中执行

示例代码:

void onRepeatedlyClick(const String& ip, const String& nation, const String& province, const String& city) {
    // 处理连续按五次按钮的逻辑
}

void setup() {
    esp_ai.onRepeatedlyClick(onRepeatedlyClick);
    esp_ai.begin({ ... });
}

.onEmotion

AI 情绪回调，可以根据不同的情绪来渲染不同的灯光或者表情。
情绪有：无情绪、快乐、伤心、愤怒、意外、专注、发愁、懊恼、困倦、疑问、恐惧、敬畏、肯定、否定

示例代码:

void onEmotion(const String& emotion) { 
  Serial.print("情绪： ");
  Serial.println(emotion);
}

void setup() {
    esp_ai.onEmotion(onEmotion);
    esp_ai.begin({ ... });
}

.playBuiltinAudio

播放 MP3 音频流: 16k采样率，16位深度，单声道音频 示例代码:

// ...
esp_ai.playBuiltinAudio(const unsigned char *data, size_t len);

.suspendAllTask

挂起所有 xTaskCreate 任务 示例代码:

// ...
esp_ai.suspendAllTask();

.resumeAllTask

恢复所有 xTaskCreate 任务 示例代码:

// ...
esp_ai.resumeAllTask();

.resumeAllTask

删除所有 delAllTask 任务 示例代码:

// ...
esp_ai.delAllTask();

.isSpeaking

获取设备是否正在播放音频 示例代码:

// ...
bool isSpeaking = esp_ai.isSpeaking();

.awaitPlayerDone

等待设备播放完毕 示例代码:

// ...
esp_ai.awaitPlayerDone();