In an ESP-AI program, esp_ai.begin() and esp_ai.loop() are the two required baseline methods. The sections below list all available instance methods so you can choose based on your scenario.

.begin

Parameter

See: Client Configuration

Example

ESP_AI esp_ai;  

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

    ...

    bool debug = true;
    // Start ESP-AI
    esp_ai.begin({ debug });
}

.loop

Call this method inside the Arduino loop(){} function to process internal runtime tasks. Place it at the very top of loop().

Example

ESP_AI esp_ai;  

void loop() {
    esp_ai.loop();

    // other code...
}

.setWifiConfig

Manually set Wi-Fi name / Wi-Fi password / api_key / custom cached fields. After setting, the device reconnects to Wi-Fi. Other fields are optional (besides Wi-Fi credentials). Pass empty strings if unchanged. Returns true on success and false on failure.

Example

JSONVar data;
data["wifi_name"] = "oldwang";
data["wifi_pwd"] = "oldwang520";
data["api_key"] = "xxx";
data["custom_field"] = "xxx"; 
esp_ai.setWifiConfig(data); // reconnects Wi-Fi

.wifiIsConnected

Returns whether Wi-Fi is connected.

Example

ESP_AI esp_ai;  
void loop() {
  esp_ai.loop();
  
  // Returns true after Wi-Fi is connected. Must be called after esp_ai.loop();
  if (!esp_ai.wifiIsConnected()) {
    return;
  }
}

.localIP

Returns the device LAN IP after Wi-Fi connection is established.

Example

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

.wakeUp

Calling this method wakes up the assistant directly and enters the conversation flow. If built-in wake-up solutions don't fit your business scenario, invoke this method at your own trigger point.

Example

esp_ai.wakeUp()

.setVolume

Parameter

• Type: float
• Range: 0-1

Example

// Set volume: 0-1
esp_ai.setVolume(0.8);

.onEvent

Callback after receiving control commands (for example, user says turn on the light / turn off the light). Handle your device logic in this callback.

You can also listen for ASR and LLM text results here (server side must call sendToClient()). After receiving text, you can render it on a screen or trigger other actions.

Example

void on_command(const String& command_id, const String& data) {
  Serial.printf("\nCommand received: %s -- %s\n", command_id, data);

  // LED control demo
  if (command_id == "device_open_001") {
    Serial.println("Turn on light");
    digitalWrite(led_pin, HIGH);
  }
  if (command_id == "device_close_001") {
    Serial.println("Turn off light");
    digitalWrite(led_pin, LOW);
  }

  // Conversation stream
  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({ ...  });
  // Register command callback
  esp_ai.onEvent(on_command);
}

.onError

Unified error callback.

Error Code	Description
000	Unknown service error
001	Internal server error
002	Server auth error
100	Unknown IAT error
101	IAT connection failed
102	IAT call failed
200	Unknown LLM error
201	LLM connection failed
202	LLM call failed
200	Unknown TTS error
201	TTS connection failed
202	TTS call failed

Example

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

void setup() {
  Serial.begin(115200); 
  // Register error callback before begin() to avoid missing startup errors
  esp_ai.onError(onError);
  esp_ai.begin({ ...  });
}

.onAPInfo

When the device cannot connect to Wi-Fi, it starts AP mode and triggers this callback. When this callback fires, prompt the user to open the provisioning page.

Example

// @url provisioning URL. If your device has a screen, render it as a QR code.
void onAPInfo(const String& url, const String& ip, const String& onAPInfoap_name) {
  // some code...
}

void setup() {
  Serial.begin(115200); 
  esp_ai.begin({ ...  });
  // Register AP callback
  esp_ai.onAPInfo(onAPInfo);
}

.onNetStatus

Callback for network status and server connection status changes.

Status	Description
"0"	Wi-Fi not connected
"0_ing"	Connecting to Wi-Fi
"0_ap"	AP mode opened for provisioning
"2"	Server not connected
"3"	Server connected

Example

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

void setup() {
  Serial.begin(115200); 
  // Register before begin() to avoid missing early status events
  esp_ai.onNetStatus(onNetStatus);
  esp_ai.begin({ ...  });
}

.onConnectedWifi

Callback after Wi-Fi connection succeeds. device_ip is the LAN IP address.

Example

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

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

.onSessionStatus

Callback for device session status.

Status values:

Status	Description
"xxx"	Idle
"iat_start"	ASR started
"iat_end"	ASR ended
"tts_chunk_start"	TTS chunk started (can happen multiple times per session)
"tts_chunk_end"	TTS chunk ended (can happen multiple times per session)
"tts_real_end"	Entire session TTS truly finished
"llm_end"	LLM inference finished (TTS may still continue)
"session_end"	Session ended

Example:

void onSessionStatus(const String& status) {
    // Handle session status
}

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

.onVolumeCb

Listen for device volume changes.

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

esp_ai.onVolume(on_volume);

.onBindDevice

Triggered after the user submits provisioning form data and Wi-Fi connection succeeds.

Use this callback to send your device-binding request.

Return values based on your business service response.

data contains fields submitted to the set_config API from the provisioning page. Read values by key, for example data["wifi_name"].

Parameters:

• device_id: device ID
• wifi_name: Wi-Fi SSID
• wifi_pwd: Wi-Fi password
• others: extended custom parameters

Return Value:

• Return a JSON string: message is shown directly on provisioning page
• Return true: binding succeeded and Wi-Fi data is saved automatically
• Return false: binding failed

Example:

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"]);


    // Success example
    return "{\"success\":true,\"message\":\"Device activated successfully, restarting soon.\"}";
    
    // Failure example
    return "{\"success\":false,\"message\":\"Device binding failed. Please reboot and try again.\"}";
}

Notes:

A device is considered activated only when: Wi-Fi connected successfully && onBindDevice returned success.

.getLocalData / .setLocalData

Read and write data stored on the chip. In most hardware code, getLocalData is used more often. setLocalData is less common because provisioning flow usually stores the data already.

When connecting to your business service, device_id is typically required by the server.

Data keys:

• device_id (read-only)
• wifi_name
• wifi_pwd
• api_key
• any custom fields

Example:

// Read data
String ext1 = getLocalData("ext1");

// Write data
setLocalData("ext1", "custom_data_xxx");

.getLocalAllData

Get all data stored on the chip.

Example:

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

.tts

Manually make the device speak.

Example:

esp_ai.tts("Text to be spoken");

.stopSession

Stop the current session, including interrupting TTS and related tasks. When the hardware side needs to stop a session, this is the required method.

Example:

esp_ai.stopSession();

.onPosition

Callback for geolocation info. Location is resolved by Wi-Fi network / IPv4 info and is triggered once after Wi-Fi connection.

Parameters:

• ip: temporary public IP of current Wi-Fi network
• nation: country
• province: province/state
• city: city

Example:

void onPosition(const String& ip, const String& nation, const String& province, const String& city) {
    // Handle location
}

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

.clearData

Clear all device data, including developer-stored fields and provisioning data.

Example:

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

    esp_ai.clearData();
}

.onRepeatedlyClick

Callback when the button is pressed five times. The framework automatically clears provisioning data internally. If you need extra logic, add it in this callback.

Example:

void onRepeatedlyClick(const String& ip, const String& nation, const String& province, const String& city) {
    // Handle custom logic for repeated clicks
}

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

.onEmotion

AI emotion callback. You can render different lights or expressions based on emotion. Supported emotions include: none, happy, sad, angry, surprised, focused, worried, annoyed, sleepy, questioning, fearful, awed, affirmative, negative.

Example:

void onEmotion(const String& emotion) {
  Serial.print("Emotion: ");
  Serial.println(emotion);
}

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

.playBuiltinAudio

Play MP3 audio stream: 16k sample rate, 16-bit depth, mono.

Example:

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

.suspendAllTask

Suspend all xTaskCreate tasks.

Example:

// ...
esp_ai.suspendAllTask();

.resumeAllTask

Resume all xTaskCreate tasks.

Example:

// ...
esp_ai.resumeAllTask();

.delAllTask

Delete all created tasks.

Example:

// ...
esp_ai.delAllTask();

.isSpeaking

Check whether the device is currently playing audio.

Example:

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

.awaitPlayerDone

Wait until playback is complete.

Example:

// ...
esp_ai.awaitPlayerDone();