Client Configuration
About 806 wordsAbout 3 min
2024-11-7
Configuration tells the ESP-AI hardware library how to run, including Wi-Fi credentials, server address, wake-up mode, microphone/speaker pins, volume behavior, and more.
Configuration Struct
Parameters must be passed in the same order as the struct fields.
struct ESP_AI_CONFIG
{
// Debug mode, outputs more logs
bool debug;
// Wi-Fi config
ESP_AI_wifi_config wifi_config;
// Server config
ESP_AI_server_config server_config;
// Offline wake-up config
ESP_AI_wake_up_config wake_up_config;
// Volume control config
ESP_AI_volume_config volume_config;
// Microphone pin config
ESP_AI_i2s_config_mic i2s_config_mic;
// Speaker pin config
ESP_AI_i2s_config_speaker i2s_config_speaker;
// Reset button config
ESP_AI_i2s_reset_btn_config reset_btn_config;
// Light config
ESP_AI_lights_config lights_config;
};Debug Mode (debug)
Debug mode prints more logs for easier development and troubleshooting.
Example
bool debug = true;
esp_ai.begin({ debug });Wi-Fi Config (ESP_AI_wifi_config)
Configure Wi-Fi connection parameters. If both wifi_name and wifi_pwd are empty strings, provisioning starts automatically. After connecting to the device hotspot, open 192.168.4.1 to access the provisioning page. This URL is also printed over serial. You can also listen for it via the onAPInfo callback.
Example
ESP_AI_wifi_config wifi_config = {
.wifi_name = "MyWiFi",
.wifi_pwd = "12345678",
// Hotspot name, default: ESP-AI + last 4 chars of MAC
.ap_name = "ESP-AI",
// Custom provisioning page
// .html_str = "xxx";
// Provisioning mode: AP | BLE
// .way = "AP";
};
// Custom provisioning page (optional)
char html_str[] = "<html><body>Provisioning Page</body></html>";
wifi_config.html_str = html_str;
esp_ai.begin({ debug, wifi_config });Custom Provisioning Page
You can reference client\esp-ai\src\webServer\index.html in the repository.
During provisioning, you can save Wi-Fi and custom business fields together into device storage. Submit custom fields to the provisioning API. Supported custom fields are: ext1 | ext2 | ext3 | ext4 | ext5 | ext6 | ext7
After storing, you can read values like getLocalData("ext1").
How ESP-AI persists these fields is handled internally. You only need to send them from your provisioning page to the ESP-AI provisioning service API.
Server Config (ESP_AI_server_config)
Configure server connection parameters. This can be omitted if users enter the Open Platform super-agent api_key on the provisioning page.
Note: when protocol is https, you must use port 443 (or your custom HTTPS port).
Purpose of .params: if you deploy your own service and need extra connection params, pass them through .params; the server can receive them in auth.
Example
ESP_AI_server_config server_config = {
.protocol = "http"
.ip = "192.168.1.100",
.port = 8080,
.params = "key1=value1&key2=value2",
.path = "/api/v1"
};
esp_ai.begin({ debug, ..., server_config });Using Open Platform Service
// Fill in your Open Platform API key
// Note: device binding is required. See the `esp_ai.onBindDevice` function in:
// https://gitee.com/xm124/esp-ai-business-arduino
ESP_AI_server_config server_config = {"http", "node.espai.fun", 80, "api_key=your_open_platform_api_key"};Wake-up Config (ESP_AI_wake_up_config)
Configures device wake-up behavior. This part must be set manually.
Struct Definition
struct ESP_AI_wake_up_config
{
// Offline wake-up scheme
char wake_up_scheme[20];
// Wake-up threshold: 0-1
float threshold;
// Pin used in pin-based wake-up
int pin;
// Wake-up keyword for serial wake-up
char str[32];
// // Silence timeout before user starts speaking, default 5000
// int vad_first;
// // Silence timeout after user starts speaking, default 1500
// int vad_course;
};Example
ESP_AI_wake_up_config wake_up_config = {};
// Mode 1: Voice wake-up (ASRPro module)
strcpy(wake_up_config.wake_up_scheme, "asrpro");
strcpy(wake_up_config.str, "hello xiaoming");
// Mode 2: Pin wake-up
strcpy(wake_up_config.wake_up_scheme, "pin_high");
wake_up_config.pin = 10;
// Mode 3: Serial wake-up
strcpy(wake_up_config.wake_up_scheme, "serial");
strcpy(wake_up_config.str, "start");
esp_ai.begin({ debug, ..., wake_up_config });Microphone Config [Optional] (ESP_AI_i2s_config_mic)
Configure I2S microphone pins.
Example
ESP_AI_i2s_config_mic i2s_config_mic = {
.bck_io_num = 4, // BCK pin
.ws_io_num = 5, // WS pin
.data_in_num = 6 // DATA input pin
.bits_per_sample=16, // MIC valid bits
.channel_format=I2S_CHANNEL_FMT_ONLY_LEFT, // Channel selection
};
esp_ai.begin({ debug, ..., i2s_config_mic });Speaker Config [Optional] (ESP_AI_i2s_config_speaker)
Configure I2S speaker pins and sample rate.
Example
ESP_AI_i2s_config_speaker i2s_config_speaker = {
.bck_io_num = 16, // BCK pin
.ws_io_num = 17, // WS pin
.data_in_num = 15, // DATA input pin
.sample_rate = 16000 // Sample rate
};
esp_ai.begin({ debug, ..., i2s_config_speaker });Volume Config [Optional] (ESP_AI_volume_config)
Configure volume control behavior. Wire a potentiometer and set the pin to enable hardware volume control.
Example
// Default config below, do not change unless needed
ESP_AI_volume_config volume_config = {
.input_pin = 7, // Input pin, default 7
.max_val = 4096, // Maximum output value
.volume = 0.5, // Default volume
.enable = true // Enable potentiometer
};
esp_ai.begin({ debug, ..., volume_config });Reset Button (ESP_AI_i2s_reset_btn_config)
Default pin is IO10.
Example
// Pin number and trigger level
ESP_AI_reset_btn_config reset_btn_config = { 10, "high" };
esp_ai.begin({ debug, ..., reset_btn_config });Light Config (ESP_AI_lights_config)
Default pin is IO18. On common ESP32-S3 boards, this is usually 48.
Example
// IO pin, LED count
ESP_AI_lights_config lights_config = { 18, 1 };
esp_ai.begin({ debug, ..., lights_config });