Skip to main content
Version: Next

IoT SDK Methods

videosdk_set_log_mode()​

The videosdk_set_log_mode function selects how much the SDK logs. Call it once, before init(). It only changes the SDK's own log tags (ESP-IDF and other components keep their existing levels).

Parameters​

  • mode
    • type: videosdk_log_mode_t
    • REQUIRED
typedef enum {
  VIDEOSDK_LOG_NORMAL = 0,  // lifecycle, warnings and errors
  VIDEOSDK_LOG_DEBUG,       // adds periodic heartbeats and diagnostics
} videosdk_log_mode_t;

Returns​

  • void

Example​

videosdk_set_log_mode(VIDEOSDK_LOG_DEBUG);

create_meeting()​

The create_meeting function creates a new meeting using the provided token and returns a create_meeting_result_t structure. This structure contains two fields: code and room_id.

  • If the operation succeeds, code is set to 0 and room_id holds the newly generated meeting ID.
  • In case of an error, code will be non-zero and room_id will be NULL.

Parameters​

  • token
    • type: char*
    • REQUIRED

Returns​

  • create_meeting_result_t containing code and room_id

On failure, code is one of SSL_CONNECT_FAILED (could not reach the API over TLS), HTTP_REQUEST_FAILED (the request failed, or the response did not contain a room id), or MEMORY_ALLOC_FAILED. See result_t.

caution

room_id is allocated by the SDK. Once you are done with it, the caller must call free(result.room_id) to release it.

Example​

  create_meeting_result_t result = create_meeting("Your - generated - token");
  if (result.room_id)
  {
    ESP_LOGI("IOT-SDK", "Created meeting roomId = %s", result.room_id);
    free(result.room_id);
  }
  else
  {
     ESP_LOGE("IOT-SDK", "Failed to create meeting");
  }

init()​

The init function initializes a meeting using the provided configuration in init_config_t. It must be called exactly once, before any other meeting method. A return value of RESULT_OK signifies success, while any other value indicates an error.

Parameters​

  • cfg
    • type: init_config_t*
    • REQUIRED
    • A pointer to the configuration below.
init_config_t init_cfg = {
      .meetingID = "Your meeting id",
      .token = "your authentication token",
      .displayName = "ESP32-Device",    // user configurable 
      .participantId = deviceid,
      .audioCodec = AUDIO_CODEC_PCMA,   // Options: AUDIO_CODEC_PCMA, AUDIO_CODEC_PCMU, AUDIO_CODEC_OPUS      
      .videoCodec = VIDEO_CODEC_JPEG,   // or VIDEO_CODEC_NONE for no video
};
  • Only meetingID and token are mandatory; passing NULL for either returns NULL_PARAMETER.
  • displayName and participantId may be "" or NULL, in which case the SDK generates a random value for you.
note

The strings you pass in init_config_t are copied by the SDK, so you are free to release your own buffers as soon as init() returns.

Returns​

result_t enum.

Example​

result_t init_result = init(&init_cfg);

startPublishAudio()​

The startPublishAudio function captures audio from the IoT device and publishes it into the active meeting session. A return value of RESULT_OK means the audio stream has started successfully, while any non-zero result code indicates an error and the audio will not be published.

Parameters​

  • void

Returns​

result_t enum.

Example​

result_t publish_result = startPublishAudio();

startSubscribeAudio()​

The startSubscribeAudio function subscribes to an audio stream from the meeting and plays it through the device speaker. Playback needs a board with a speaker; without one it returns DEVICE_NOT_SUPPORTED. See Supported Microcontrollers.

The function returns a result_t code, where RESULT_OK indicates successful subscription and playback, while any non-zero value signals an error.

Parameters​

  • void

Returns​

result_t enum.

Example​

#include "videosdk.h"
#include "esp_log.h"
void app_main(){
  // Subscribe to remote audio and play it on the device.
  result_t subscribe_result = startSubscribeAudio();
  ESP_LOGI("IOT-SDK", "Subscribe Result: %d", subscribe_result);
}

startPublishVideo()​

The startPublishVideo function captures video from the IoT device camera and publishes it into the active meeting session. A return value of RESULT_OK means the video stream has started successfully, while any non-zero result code indicates an error and the video will not be published.

Parameters​

  • void

Returns​

result_t enum.

Example​

result_t publish_video_result = startPublishVideo();

startSubscribeVideo()​

The startSubscribeVideo function subscribes to a video stream from the meeting and renders it on the device display. Rendering needs a board with a display; without one it returns DEVICE_NOT_SUPPORTED. See Supported Microcontrollers.

The function returns a result_t code, where RESULT_OK indicates successful subscription and playback, while any non-zero value signals an error.

Parameters​

  • void

Returns​

result_t enum.

Example​

#include "videosdk.h"
#include "esp_log.h"
void app_main(){
  // Subscribe to remote video and render it on the device.
  result_t subscribe_video_result = startSubscribeVideo();
  ESP_LOGI("IOT-SDK", "Subscribe Video Result: %d", subscribe_video_result);
}

startMessageChannel()​

The startMessageChannel function opens the data channel used for sending and receiving application messages. Call it once after init() and before the first sendMessage(). It is idempotent and works on any supported board.

Parameters​

  • void

Returns​

result_t enum.

Example​

result_t message_channel_result = startMessageChannel();

sendMessage()​

The sendMessage function sends a text or binary application message to the other participants over the data channel. The data buffer is copied, so it can be reused immediately after the call.

Parameters​

  • data
    • type: const uint8_t*
    • REQUIRED
    • Pointer to the message bytes.
  • len
    • type: size_t
    • REQUIRED
    • Message length in bytes. Maximum is 24000.
  • is_binary
    • type: int
    • REQUIRED
    • 1 for a WebRTC binary message, 0 for a UTF-8 text message.

Returns​

result_t enum. Returns DATA_CHANNEL_NOT_STARTED if startMessageChannel() was not called, DATA_CHANNEL_QUEUE_FULL if the send queue is momentarily full, NULL_PARAMETER if data is NULL or len is 0 or greater than 24000, or MEMORY_ALLOC_FAILED if the message could not be copied.

Example​

const char *text = "hello from esp32";
result_t send_result = sendMessage((const uint8_t *)text, strlen(text), 0);

stopMessageChannel()​

The stopMessageChannel function stops the local message channel, dropping any queued messages and disabling further sends. Call it whenever you want to close the channel; leaving the meeting also releases it automatically.

Parameters​

  • void

Returns​

result_t enum. Returns DATA_CHANNEL_NOT_STARTED if the channel was never started.

Example​

result_t stop_message_result = stopMessageChannel();

setDataMessageHandler()​

The setDataMessageHandler function registers (or clears, with NULL) the callback invoked for each application message received from another participant. Register it after init() and before the start* calls.

Parameters​

  • cb
    • type: data_message_cb_t
    • REQUIRED
    • Callback of the form void cb(const uint8_t* data, size_t len, int is_binary, uint16_t sid), or NULL to clear.

Returns​

  • void

Example​

static void on_data_message(const uint8_t *data, size_t len, int is_binary, uint16_t sid) {
  // handle the message (buffer valid only for this call)
}

setDataMessageHandler(on_data_message);

setConnectionStateHandler()​

The setConnectionStateHandler function registers (or clears, with NULL) a callback that fires when the signaling connection state changes. A connected == false event means the session dropped and the app should leave and rejoin. Register it after init().

Parameters​

  • cb
    • type: connection_state_cb_t
    • REQUIRED
    • Callback of the form void cb(bool connected, void* user), or NULL to clear.
  • user
    • type: void*
    • REQUIRED
    • Opaque pointer passed back to the callback verbatim (may be NULL).

Returns​

  • void

Example​

static void on_connection_state(bool connected, void *user) {
  ESP_LOGI("IOT-SDK", "signaling connected = %d", connected);
}

setConnectionStateHandler(on_connection_state, NULL);

setSpeakerVolume()​

The setSpeakerVolume function sets the speaker playback volume at runtime, from 0 to 100 (out-of-range values are clamped). Available on boards with a speaker (ESP32-S3-Korvo-2).

Parameters​

  • volume
    • type: int
    • REQUIRED
    • Volume level from 0 to 100.

Returns​

  • void

Example​

setSpeakerVolume(80);

leave()​

The leave() method removes the peer from the active meeting session and stops all ongoing tasks, including publishing and subscribing, if they are running. It blocks until both have finished, so you can rejoin immediately after it returns RESULT_OK.

Parameters​

  • void

Returns​

result_t enum. The two failure cases need opposite responses:

  • STOP_PUBLISH_TASK_CREATE_FAILED / STOP_SUBSCRIBE_TASK_CREATE_FAILED: teardown never started (out of memory), so nothing was torn down and the session is still active. Call leave() again.
  • LEAVE_FAILED: teardown started but did not finish within 6 seconds, so something is stuck. The session is not left intact; do not treat it as a clean exit.

Example​

result_t leave_result = leave();

Got a Question? Ask us on discord

Last updated on by karan07080
Previous
Result Code
Next

Was this helpful?