客户端实例

2148字约7分钟

2024-11-7

在一个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

案例代码

esp_ai.setWifiConfig("oldwang", "oldwang520"); // 会重新连接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(String command_id, 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);
}

.onError

统一错误回调

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

案例代码

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

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

.onAPInfo

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

案例代码

// @url 配网地址, 有屏幕的情况下建议将 url 生成为二维码显示
void onAPInfo(String url, String ip, 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(String status) {
  // some code...
}

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

.onConnectedWifi

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

案例代码

void onConnectedWifi(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完毕)

示例代码:

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

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

onBindDevice

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

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

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

参数说明:

device_id: 设备ID
wifi_name: WiFi名称
wifi_pwd: WiFi密码
ext1-ext5: 扩展参数

返回值:

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

示例代码:

String onBindDevice(String device_id, String wifi_name, String wifi_pwd, 
                   String ext1, String ext2, String ext3, String ext4, String ext5, String ext6, String ext7) {
    // 成功示例
    return "{\"success\":true,\"message\":\"设备激活成功，即将重启设备。\"}";
    
    // 失败示例
    return "{\"success\":false,\"message\":\"设备绑定失败，重启设备试试呢。\"}";
}

特别说明:

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

getLocalData / setLocalData

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

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

可操作的数据项:

device_id 设备ID (仅可读)
wifi_name
wifi_pwd
api_key
ext1-ext5

示例代码:

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

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

tts

手动控制设备输出语音。

示例代码:

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

stopSession

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

示例代码:

esp_ai.stopSession();

onPosition

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

参数说明:

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

示例代码:

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

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

客户端实例

🎉 ESP-AI 公告 🎉