Run a Sample IoT SDK Project

The IoT SDK ships two ready-to-run sample projects inside the published component on the ESP Component Registry:

Example	What it does
audio_call	Joins a room and streams audio.
video_call	Joins a room and streams video.

idf.py create-project-from-example downloads the component and scaffolds the whole project for you: source, CMakeLists.txt, partitions.csv and a tuned sdkconfig.defaults. There is nothing to wire up by hand.

The same samples are also available on GitHub: videosdk-rtc-iot-sdk-example.

tip

If you would rather build a project from scratch and add the SDK to it yourself, follow the Quick Start instead.

Prerequisites

Before you get started, ensure you have the following:

• ESP-IDF: ESP-IDF v5.4.2, v5.4.3, or v5.4.4
• Python: Python version >= 3.11
• A supported ESP32-S3 board. For a list of supported boards, see Supported Microcontrollers.
• A valid Video SDK Account

Generate Token

To manage secured communication, every participant that connects to a room needs an access token. You can easily generate this token from the VideoSDK Dashboard.

For development purpose, you can generate a temporary token from VideoSDK Dashboard's API section.

Run the Sample Project

Step 1: Configure the ESP-IDF environment

1

Configure the ESP-IDF environment

tip

For setting up ESP-IDF, follow only Step 1 of the Quick Start. Inside that step, you do not need to run the project creation commands; the next step here creates the project for you.

Once the toolchain is installed, activate it in your shell:

source ~/esp/esp-idf/export.sh

Step 2: Create the sample project

2

Create the sample project

Pick the example you want and run one command. It fetches the component from the registry and generates a complete project in the current directory.

# Audio call
idf.py create-project-from-example "videosdk/iot-sdk=0.4.0:audio_call"

# ...or video call
idf.py create-project-from-example "videosdk/iot-sdk=0.4.0:video_call"

Then move into the generated folder:

cd audio_call     # or: cd video_call

note

The generated project already contains everything the SDK needs: main/idf_component.yml, main/CMakeLists.txt, partitions.csv and a tuned sdkconfig.defaults. The board, token, room ID and log-verbosity menus come from the component itself, so there is no Kconfig.projbuild to write.

Step 3: Configure your board and credentials

3

Configure your board and credentials

Set the target, then set your Wi-Fi, token and room ID in menuconfig.

idf.py set-target esp32s3
idf.py menuconfig

Inside menuconfig, set the following. Press S to save and Enter to confirm, then Esc or q to exit.

a. Example Connection Configuration
       |-> WIFI SSID              <!-- your WiFi name -->
       |-> WIFI Password          <!-- your WiFi password -->

b. VideoSDK Configuration
       |-> Auth token (JWT)       <!-- paste your VideoSDK token -->
       |-> Room ID                <!-- the room you want to join -->

c. SET Microcontroller
       |-> Audio hardware board
             |-> ESP32-S3-XIAO      (default)
             |-> ESP32-S3-Korvo-2
       |-> Speaker output volume (0-100)   <!-- board-dependent; see Supported Microcontrollers -->

d. VideoSDK Logging
       |-> Log verbosity
             |-> Normal (default)
             |-> Debug

The token and room ID live in sdkconfig, not in source, so you never have to paste a real token into a .c file.

Sending vs receiving

All boards can send audio and video. Receiving needs a speaker and a display; on boards without them, startSubscribeAudio() and startSubscribeVideo() return DEVICE_NOT_SUPPORTED (expected, not a failure). See Supported Microcontrollers.

Step 4: Build & Flash Project

4

Build & Flash Project

Build the firmware and flash it onto your board.

idf.py build
idf.py flash monitor

idf.py flash monitor auto-detects the serial port when a single board is connected, so you usually do not need to specify one. Exit the monitor with Ctrl+]. On Linux, add yourself to the dialout group first (sudo usermod -a -G dialout $USER, then log out and back in) or flashing fails with a permission error.

More than one device connected?

If you have several USB-serial devices plugged in, auto-detect cannot tell which is your board. Pass the port explicitly with idf.py -p <PORT> flash monitor, where <PORT> is /dev/cu.usbmodem* or /dev/cu.usbserial-* on macOS (ls /dev/cu.*), /dev/ttyUSB* or /dev/ttyACM* on Linux, or COMx on Windows (Device Manager -> Ports). List the ports before and after plugging the board in; the entry that appears is your port.

• You can checkout the complete quick start example here.

• Join the same room ID from a browser or a phone using any VideoSDK client SDK, and the device will appear as another participant.

Next steps

• Audio: Publish Audio · Subscribe Audio
• Video: Publish Video · Subscribe Video
• Data Channel: Send Message · Receive Message
• API reference: Methods · Result Codes