Connection State - IoT SDK

A device on Wi-Fi loses its connection sooner or later: the access point reboots, the device drifts out of range, or the network drops long enough for the session to die. The SDK reports this through a callback so your application can react instead of sitting in a silent, half-dead call.

Two layers are involved, and they recover differently:

• The network link. Handled by whatever you use to bring up Wi-Fi, such as ESP-IDF's example_connect(). It reconnects on its own.
• The VideoSDK session. Reported by setConnectionStateHandler(). It does not come back on its own. Once the session drops, the device has to leave and join again.

setConnectionStateHandler()

• The setConnectionStateHandler() function registers a callback that fires whenever the signaling connection state changes. Register it after init() and before your start* calls, so it is in place before media begins.
• Pass NULL as the callback to clear it.

This function takes two parameters:

• cb: a callback of the form void cb(bool connected, void *user). A connected == false event means the session dropped.
• user: an opaque pointer handed back to the callback untouched. Use it to reach your own state, or pass NULL.

caution

The callback runs on an SDK task. Keep it short, and do not call leave() from inside it, because leave() blocks until teardown finishes. Record the event and let your own task do the work.

Example

#include "videosdk.h"
#include "esp_log.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

static volatile bool s_session_dropped = false;

static void on_connection_state(bool connected, void *user) {
  ESP_LOGI("IOT-SDK", "signaling connected = %d", connected);
  if (!connected) {
    s_session_dropped = true;   // flag it, handle it outside the callback
  }
}

// Register right after init(), before startPublishAudio() / startPublishVideo().
setConnectionStateHandler(on_connection_state, NULL);

Rejoining after a drop

Once the flag is set, the recovery sequence is always the same: leave, then start a fresh session with init() and restart the streams you were running.

static init_config_t s_init_cfg;   // keep the config you joined with

static bool rejoin_room(void) {
  result_t r = leave();
  if (r != RESULT_OK) {
    // STOP_PUBLISH_TASK_CREATE_FAILED / STOP_SUBSCRIBE_TASK_CREATE_FAILED:
    // teardown never started, the session is still up, so call leave() again.
    // LEAVE_FAILED: teardown is stuck. Do not rejoin on top of it.
    ESP_LOGE("IOT-SDK", "leave failed: %d", r);
    return false;
  }

  r = init(&s_init_cfg);
  if (r != RESULT_OK) {
    ESP_LOGE("IOT-SDK", "re-init failed: %d", r);
    return false;
  }

  setConnectionStateHandler(on_connection_state, NULL);
  startPublishAudio();
  // ...and any other direction this device was running.
  return true;
}

void app_task(void *arg) {
  int backoff_ms = 1000;
  while (1) {
    if (s_session_dropped) {
      s_session_dropped = false;
      if (rejoin_room()) {
        backoff_ms = 1000;                              // recovered
      } else {
        s_session_dropped = true;                       // try again later
        vTaskDelay(pdMS_TO_TICKS(backoff_ms));
        if (backoff_ms < 30000) backoff_ms *= 2;        // back off, do not hammer
      }
    }
    vTaskDelay(pdMS_TO_TICKS(100));
  }
}

note

Back off between attempts. A device that retries in a tight loop while the network is still down burns power, floods your logs, and reconnects no faster.

caution

If leave() returns LEAVE_FAILED, teardown started but did not finish, so the session is not left cleanly. Do not immediately rejoin on top of it. Log it, and let the device restart with esp_restart() if it keeps happening. See Result Code.

What to watch for

• The token is checked when the session is created. A token that expired while the device was running will make the rejoin fail rather than the original join, so long-lived devices need a way to obtain a fresh token. See Authentication and Tokens.
• Turn on debug logs while you are testing recovery, so you can see the drop and the rejoin in the monitor. See Logging and Debugging.

API Reference

The API references for all the methods utilized in this guide are provided below.

• setConnectionStateHandler
• init
• leave