RTC Client SDK Reference

1. Overview​

1.1 SDK Introduction​

The RTC Client SDK (API prefix stm_open_*) is intended for external developers. It simplifies the workflow of the standard STM SDK, enabling rapid integration of AI capabilities without requiring an understanding of lower-level concepts such as Connect, Stream, and Event.

It is provided as a precompiled library and supports multiple platform architectures. For source-level integration or a simpler API, consider the RTC TCP Client.

1.2 Core Concepts​

1.2.1 Session​

Definition:
A Session represents an AI business session, corresponding to an independent conversation or task context. When creating a Session, you must provide the session_token issued by the server; the SDK uses it internally to establish the connection and perform authentication.

Lifecycle:

• Create: Call stm_open_session_create(stm_open_session_config_t *config) and provide client_type, token, id, encrypt_key, and callbacks (such as on_state and on_data_recv). On success, it returns stm_open_session_t*.
• Use: Call stm_open_session_send multiple times on the same Session to send request data, and receive AI responses in on_data_recv.
• Close: Call stm_open_session_close(session) to release resources when the business operation ends or the Session is no longer needed.

Example:
A user opens a page for "Chat with AI" -> the application calls a platform interface to obtain the session_token and session_id -> the RTC Client SDK creates the Session -> when the user sends text or voice, the application sends it through stm_open_session_send, receives the AI response in on_data_recv, and displays it; when the user leaves the page, the application calls stm_open_session_close.

1.2.2 Requests and Data Packets (event_id, fin)​

Definition:
A complete request-response exchange may consist of multiple packets (for example, a voice segment uploaded as multiple frames). The RTC Client SDK uses an Event to represent such a group of packets: packets belonging to the same request/response turn share the same event_id; the first packet can carry the data type and parameters (such as audio sample rate or image dimensions); and the last packet is marked with fin=1, allowing the foundation service and the device to agree that "this input segment has ended."

Send side (when you call stm_open_session_send):

• event_id: Event ID. Set it only in the first packet of the Event so the foundation service and business layer can associate multiple data packets with the same request.
• data_type: Data type (such as text, audio, or image). Required in the first packet.
• payload / payload_length: The data carried by this packet.
• fin: 0 means more packets follow; 1 means this packet is the last packet of the Event.

Receive side (on_data_recv callback):

• fin=0 means the current AI response has not ended; fin=1 means this is the last packet of the response.
• Use data_type, payload, and other fields in data to distinguish text, audio, images, and other data.

2. Prerequisites​

2.1 AI Agent Configuration​

Create a product on the Tuya IoT Platform and bind or create an AI Agent. For details, see Create an Agent. To customize a workflow, see Create a Workflow.

2.2 Device Activation​

Activate the device through provisioning and obtain the device credentials (devid, secret_key, and local_key). For details, see the tutorial.

2.3 Obtain a Session Token​

Initialize the IoT Client by calling iot_client_init(), and then call iot_client_get_session_token() to obtain the session_token. For details, see the IoT Client API.

3. SDK Initialization and Configuration​

3.1 Initialize the SDK (stm_open_init)​

stm_ret stm_open_init(stm_open_config_t *config);

Initializes the SDK and sets the log callback. It must be called before any other API and can be called only once during the SDK lifecycle.

Configuration structure stm_open_config_t:

Return values: STM_OK on success; STM_EINVALID_PARM if a parameter is invalid.

3.2 Reset the SDK (stm_open_reset)​

stm_ret stm_open_reset(stm_open_config_t *config);

Resets the SDK to its initial state, releases all Sessions, and reapplies the configuration.

3.3 Deinitialize the SDK (stm_open_deinit)​

void stm_open_deinit(void);

Releases all resources. After calling it, you must call stm_open_init again before using the SDK.

3.4 Get Version Information (stm_open_get_version)​

uint32_t stm_open_get_version(void);

Returns the version number (major version in the high 8 bits, minor version in the middle 8 bits, and revision in the low 16 bits).

3.5 Configure Logging (stm_open_set_log_level)​

stm_ret stm_open_set_log_level(stm_log_level_e level);

Note: rtc-client is a prebuilt library — its logs go through the on_log callback set at init, and the level is controlled by this runtime API, outside the SDK's compile-time AGENTIC_KIT_LOG_LEVEL / AGENTIC_KIT_LOG facade (modules compiled from source go through the facade; see Compile-Time Configuration).

4. Session Management​

4.1 Create a Session (stm_open_session_create)​

stm_open_session_t* stm_open_session_create(stm_open_session_config_t *config);

Configuration structure stm_open_session_config_t:

Return value: A Session handle on success; NULL on failure.

4.2 Send Data (stm_open_session_send)​

stm_ret stm_open_session_send(stm_open_session_t *session, stm_open_data_t *data, int8_t fin);

Fields of stm_open_data_t:

4.3 Close a Session (stm_open_session_close)​

void stm_open_session_close(stm_open_session_t *session);

5. Data Types​

Audio Parameters (stm_audio_params_t)​

Image Parameters (stm_image_params_t)​

6. Error Codes​

For the complete list of error codes, see the stm_errno.h header.

7. Quick Examples​

Text Chat​

stm_open_config_t config = { .on_log = my_log_cb };
stm_open_init(&config);

stm_open_session_config_t sess_cfg = {
    .client_type   = STM_CLIENT_TYPE_DEVICE,
    .session_token = token,
    .session_id    = sid,
    .encrypt_key   = local_key,
    .on_data_recv  = on_recv,
};
stm_open_session_t *sess = stm_open_session_create(&sess_cfg);

stm_open_data_t d = {0};
d.event_id       = "t1";
d.data_type      = STM_DATA_TYPE_TEXT;
d.payload        = (uint8_t *)"hello";
d.payload_length = 5;
stm_open_session_send(sess, &d, 1);

// ... wait for on_recv callbacks ...
stm_open_session_close(sess);
stm_open_deinit();

Audio Chat​

// First packet: includes audio parameters
stm_open_data_t first = {0};
first.event_id   = "a1";
first.data_type  = STM_DATA_TYPE_AUDIO;
first.audio_params = (stm_audio_params_t){
    .codec_type  = 101,   // PCM
    .sample_rate = 16000,
    .channels    = 1,
    .bit_depth   = 16,
};
first.payload        = pcm_chunk1;
first.payload_length = chunk_len;
stm_open_session_send(sess, &first, 0);

// Middle packet
stm_open_data_t mid = {0};
mid.data_type      = STM_DATA_TYPE_AUDIO;
mid.payload        = pcm_chunk2;
mid.payload_length = chunk_len;
stm_open_session_send(sess, &mid, 0);

// Last packet
stm_open_data_t last = {0};
last.data_type      = STM_DATA_TYPE_AUDIO;
last.payload        = pcm_chunk3;
last.payload_length = chunk_len;
stm_open_session_send(sess, &last, 1);  // fin=1

8. Comparison with RTC TCP Client​