Improve ESP32 docs (#12)

* move examples up

* tweak name

* Add additional documentation

---------

Co-authored-by: Jacob Gelman <[email protected]>

Author: chenosaurus

README.md

@@ -20,10 +20,20 @@ Use this SDK to add realtime video, audio and data features to your ESP32 projec
 
 - **Supported chipsets**: ESP32-S3 and ESP32-P4
 - **Bidirectional audio**: Opus encoding, acoustic echo cancellation (AEC)
-- **Bidirectional video**: *coming soon*
+- **Bidirectional video**: *video support coming soon*
 - **Real-time data**: data packets, remote method calls (RPC)
 
-## Installation
+## Examples
+
+One of the best ways to get started with LiveKit is by reviewing the examples and choosing one as a starting point for your project:
+
+### [Voice AI Agent](./examples/voice_agent/README.md)
+
+Conversational AI voice agent that interacts with hardware based on user requests.
+
+## Basic usage
+
+### Installation
 
 In your application's IDF component manifest, add LiveKit as a Git dependency:
 
@@ -35,14 +45,139 @@ dependencies:
     version: <current version tag>
 ```
 
-Please be sure to pin to a specific version tag as subsequent 0.x.x releases may have breaking changes. In the future, this SDK will be added to the [ESP component registry](https://components.espressif.com).
+Please be sure to pin to a specific version tag, as subsequent 0.x.x releases may have breaking changes. In the future, this SDK will be added to the [ESP component registry](https://components.espressif.com).
 
-## Examples
+With LiveKit added as a dependency to your application, include the LiveKit header and invoke
+`livekit_system_init` early in your application's main function:
 
-One of the best ways to get started with LiveKit is by reviewing the examples and choosing one as a starting point for your project:
+```c
+#include "livekit.h"
+
+void app_main(void)
+{
+    livekit_system_init();
+    // Your application code...
+}
+```
+
+### Configure media pipeline
+
+LiveKit for ESP32 puts your application in control of the media pipeline; your application configures a capturer and/or renderer and provides their handles when creating a room.
+
+#### Capturer: input from camera/microphone
+
+- Required for rooms which will publish media tracks
+- Created using the Espressif [*esp_capture*](./components/third_party/esp-webrtc-solution/components/esp_capture/README.md) component
+- Capture audio capture over I2S, video from MIPI CSI or DVI cameras
+- After configuration, you will provide the `esp_capture_handle_t` when creating a room
+
+#### Renderer: output to display/speaker
+
+- Required for rooms which will subscribe to media tracks
+- Created using the Espressif [*av_render*](./components/third_party/esp-webrtc-solution/components/av_render/README.md) component
+- Playback audio over I2S, video on LCD displays supported by *esp_lcd*
+- After configuration, you will provide the `av_render_handle_t` when creating a room
+
+Please refer to the [examples](#examples) in this repository, which support many popular development boards via the Espressif [*codec_board*](./components/third_party/esp-webrtc-solution/components/codec_board/README.md) component.
+
+### Create room
+
+Create a room object, specifying your capturer, renderer, and handlers for room events:
+
+```c
+static livekit_room_handle_t room_handle = NULL;
+
+livekit_room_options_t room_options = {
+    .publish = {
+        .kind = LIVEKIT_MEDIA_TYPE_AUDIO,
+        .audio_encode = {
+            .codec = LIVEKIT_AUDIO_CODEC_OPUS,
+            .sample_rate = 16000,
+            .channel_count = 1
+        },
+        .capturer = my_capturer
+    },
+    .subscribe = {
+        .kind = LIVEKIT_MEDIA_TYPE_AUDIO,
+        .renderer = my_renderer
+    },
+    .on_state_changed = on_state_changed,
+    .on_participant_info = on_participant_info
+};
+if (livekit_room_create(&room_handle, &room_options) != LIVEKIT_ERR_NONE) {
+    ESP_LOGE(TAG, "Failed to create room object");
+}
+```
+
+This example does not show all available fields in room options—please refer to the [API reference](https://livekit.github.io/client-sdk-esp32/group__Lifecycle.html#structlivekit__room__options__t)
+for an extensive list.
+
+Typically, you will want to create the room object early in your application's lifecycle, and connect/disconnect as necessary based on user interaction.
+
+### Connect room
 
-- [Voice Agent](./examples/voice_agent/README.md): conversational AI voice agent that interacts with hardware based on user requests.
-- *More examples coming soon*
+With a room room handle, connect by providing a server URL and token:
+
+```c
+livekit_room_connect(room_handle, "<your server URL>", "<token>");
+```
+
+The connect method is asynchronous; use your `on_state_changed` handler provided in room options
+to get notified when the connection is established or fails (e.g. due to an expired token, etc.).
+
+Once connected, media exchange will begin:
+
+1. If a capturer was provided, video and/or audio tracks will be published.
+2. If a renderer was provided, the first video and/or audio tracks in the room will be subscribed to.
+
+### Real-time data
+
+In addition to real-time audio and video, LiveKit offers several methods for exchange real-time data between participants in a room.
+
+#### Remote method call (RPC)
+
+Define an RPC handler:
+
+```c
+static void get_cpu_temp(const livekit_rpc_invocation_t* invocation, void* ctx)
+{
+    float temp = board_get_temp();
+    char temp_string[16];
+    snprintf(temp_string, sizeof(temp_string), "%.2f", temp);
+    livekit_rpc_return_ok(temp_string);
+}
+```
+
+Register the handler on the room to allow it to be invoked by remote participants:
+
+```c
+livekit_room_rpc_register(room_handle, "get_cpu_temp", get_cpu_temp);
+```
+
+> [!TIP]
+> In the [*voice_agent*](./examples/voice_agent/) example, RPC is used to allow an AI agent to interact
+> with hardware by defining a series of methods for the agent to invoke.
+
+#### User packets
+
+Publish a user packet containing a raw data payload under a specific topic:
+
+```c
+const char* command = "G5 I0 J3 P0 Q-3 X2 Y3";
+
+livekit_payload_t payload = {
+     .bytes = (uint8_t*)command,
+     .size = strlen(command)
+};
+livekit_data_publish_options_t options = {
+    .payload = &payload,
+    .topic = "gcode",
+    .lossy = false,
+    .destination_identities = (char*[]){ "printer-1" },
+    .destination_identities_count = 1
+};
+livekit_room_publish_data(room_handle, &options);
+```
 
 ## Documentation
 

components/livekit/include/livekit.h

@@ -368,9 +368,7 @@ typedef struct {
 ///
 /// Example usage:
 /// @code
-/// const char* command = "G5 I0 J3 P0 Q-3 X2 Y3";
-///
-/// livekit_payload_t payload = {
+/// livekit_data_payload_t payload = {
 ///     .bytes = (uint8_t*)command,
 ///     .size = strlen(command)
 /// };

examples/voice_agent/main/example.c

@@ -154,6 +154,21 @@ void join_room()
     if (connect_res != LIVEKIT_ERR_NONE) {
         ESP_LOGE(TAG, "Failed to connect to room");
     }
+
+    const char* command = "G5 I0 J3 P0 Q-3 X2 Y3";
+
+    livekit_data_payload_t payload = {
+        .bytes = (uint8_t*)command,
+        .size = strlen(command)
+    };
+    livekit_data_publish_options_t options = {
+        .payload = &payload,
+        .topic = "gcode",
+        .lossy = false,
+        .destination_identities = (char*[]){ "printer-1" },
+        .destination_identities_count = 1
+    };
+    livekit_room_publish_data(room_handle, &options);
 }
 
 void leave_room()