After the server starts, you can call instance methods to operate devices from Node.js, such as restarting a device, updating Wi-Fi info, setting local storage data, making a device speak, and more.

.getClients

Get all connected devices, or get a specific device by device ID.

Example

const espAiIns = espAi({ ... });

// Get all connected devices on current server
const clients = espAiIns.getClients();

// Get one specific device by ID
const client = espAiIns.getClients("xxx-xxx-xxx-xxx");

.updateClientConfig

Update client runtime config returned by gen_client_config. Useful for hot-updating TTS / LLM / IAT settings without restarting the server.

const espAiIns = espAi({ ... });
espAiIns.updateClientConfig("xxx-xxx-xxx-xxx", {
    tts_config: { ... },
    ...
});

.setWifiConfig

Set client Wi-Fi and provisioning data from the server side. Equivalent to the hardware-side .setWifiConfig.

If you only need to update storage data, .setLocalData is recommended.

const espAiIns = espAi({ ... });
espAiIns.setWifiConfig("xxx-xxx-xxx-xxx", {
    wifi_name:"",
    wifi_pwd:"",
    api_key:"",
    ext1:"",
    ext2:"",
    ext3:"",
    ext4:"",
    ext5:"",
    ext6:"",
    ext7:"",
})

.tts

Make the client speak a sentence.

const espAiIns = espAi({ ... });
await espAiIns.tts("xxx-xxx-xxx-xxx", "Hi, I am your AI assistant!")

.stop

Terminate current session, including IAT, TTS, and LLM.

const espAiIns = espAi({ ... });

/**
 * Stop session
 * Usually paired with .newSession to restart a session.
 *
 * @param {String} device_id Device ID
 * @param {String} at Description of interruption context
 * @param {Boolean} stop_all Stop everything (including audio started by .tts)
 */
await espAiIns.stop("xxx-xxx-xxx-xxx", "user_interrupt", true);

.newSession

Create a new session (commonly after .stop) and return session_id.

const espAiIns = espAi({ ... });
await espAiIns.newSession("xxx-xxx-xxx-xxx");

.matchIntention

Match and execute an intention command directly. Useful for simulating user commands on server side.

The 3rd argument can override spoken reply after command execution.

const espAiIns = espAi({ ... });
await espAiIns.matchIntention("xxx-xxx-xxx-xxx", "turn on the light", "OK");

.restart

Restart the target device.

const espAiIns = espAi({ ... });
await espAiIns.restart("xxx-xxx-xxx-xxx");

.setLocalData

Set local data stored on device. If value is empty string, the value is cleared. Difference from setWifiConfig: this method allows explicitly writing empty string fields, while setWifiConfig batch updates and skips empty fields.

Supported keys: api_key, ext1, ext2, ext3, ext4, ext5, ext6, ext7

const espAiIns = espAi({ ... });
await espAiIns.setLocalData("xxx-xxx-xxx-xxx", "ext1", "business_data");

.setLLMHistorys

Set user conversation context. When your business logic uses multiple roles, switch context by calling this method.

const espAiIns = espAi({ ... });
espAiIns.setLLMHistorys("xxx-xxx-xxx-xxx", [
    { role: 'system', content: 'You are a translator. Only translate what the user says.' },
]);

.getLLMHistorys

Get current user context. When switching roles, store current history first so you can restore it later.

const espAiIns = espAi({ ... });
const curHistory = espAiIns.getLLMHistorys("xxx-xxx-xxx-xxx");

.isPlaying (removed in v2.74.49)

Previously used to check whether a device was playing __play_music__ audio (not TTS).

const espAiIns = espAi({ ... });
const isPlaying = espAiIns.isPlaying("xxx-xxx-xxx-xxx");
console.log(isPlaying)

.pinMode

Set pin mode (same concept as Arduino pinMode).

const espAiIns = espAi({ ... });
espAiIns.pinMode(
    "xxx-xxx-xxx-xxx",
    21,
    "OUTPUT"
);

espAiIns.digitalWrite(
    "xxx-xxx-xxx-xxx",
    21,
    "HIGH"
);

.digitalWrite

Write digital pin level. Equivalent to Arduino digitalWrite. Pin must first be configured as OUTPUT via pinMode.

Typical scenarios: relay control, LED control, etc.

const espAiIns = espAi({ ... });
espAiIns.pinMode("xxx-xxx-xxx-xxx", 21, "OUTPUT");
espAiIns.digitalWrite("xxx-xxx-xxx-xxx", 21, "HIGH");

.digitalRead

Read digital pin state. Equivalent to Arduino digitalRead. Pin must first be configured as INPUT. Note: this API introduces ~100ms delay.

const espAiIns = espAi({ ... });
espAiIns.pinMode("xxx-xxx-xxx-xxx", 21, "INPUT");

instance.digitalRead(
    "xxx-xxx-xxx-xxx",
    21,
    function(val){
        console.log('Pin state changed:', val);
    }
)

.analogWrite

Analog output (PWM-style). Equivalent to Arduino analogWrite. Pin must be set to OUTPUT first.

Typical scenarios: motor speed control, servo angle control, etc.

const espAiIns = espAi({ ... });
espAiIns.pinMode("xxx-xxx-xxx-xxx", 21, "OUTPUT");

instance.analogWrite(
    "xxx-xxx-xxx-xxx",
    21,
    250
)

.analogRead

Read analog input. Equivalent to Arduino analogRead. Note: this API introduces ~100ms delay.

const espAiIns = espAi({ ... });
espAiIns.pinMode("xxx-xxx-xxx-xxx", 21, "INPUT");

instance.analogRead(
    "xxx-xxx-xxx-xxx",
    21,
    function(val){
        console.log('Pin value changed:', val);
    }
)

.awaitPlayerDone

Wait until playback is completed.

const espAiIns = espAi({ ... });
await espAiIns.awaitPlayerDone("xxx-xxx-xxx-xxx");

.isSpeaking

Check whether a specific device is currently speaking/playing audio.

const espAiIns = espAi({ ... });
const isSpeaking = espAiIns.isSpeaking("xxx-xxx-xxx-xxx");