Reorganize READMEs

Author: ladvoc

README.md

@@ -34,18 +34,97 @@ dependencies:
 
 In the future, this SDK will be added to the [ESP component registry](https://components.espressif.com).
 
-## Examples
+## Documentation
 
-This repository contains several examples you can use as a starting point for your project:
-- [Voice agent](./examples/voice_agent/)
-- *More examples coming soon*
+Please refer to the [LiveKit Docs](https://docs.livekit.io/home/) for an introduction to the platform and its features, or to the API reference (*TODO: Not published yet*) for specifics about this SDK.
 
-See the README located in each example directory for setup information and build instructions.
+## Example: Voice Agent
 
-## Documentation
+This repository contains an example application built with this SDK and [LiveKit Agents](https://docs.livekit.io/agents/), enabling bidirectional voice communication with an AI agent. The agent can interact with hardware in response to user requests. Below is an example of a conversation between a user and the agent:
 
-Please refer to the [LiveKit Docs](https://docs.livekit.io/home/) for an introduction to the platform and its features, or to the API reference (*TODO: Not published yet*) for specifics about this SDK.
+> **User:** What is the current CPU temperature? \
+> **Agent:** The CPU temperature is currently 33°C.
+
+> **User:** Turn on the blue LED. \
+> **Agent:** *[turns blue LED on]*
+
+> **User:** Turn on the yellow LED. \
+> **Agent:** I'm sorry, the board does not have a yellow LED.
+
+### Requirements
+
+- Software:
+    - [IDF](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/index.html) release v5.4 or later
+    - Python 3.9 or later
+    - LiveKit Cloud Project
+    - Sandbox Token Server (created from your cloud project)
+    - API keys for OpenAI, Deepgram, and Cartesia.
+- Hardware
+    - Dev board: [ESP32-S3-Korvo-2](https://docs.espressif.com/projects/esp-adf/en/latest/design-guide/dev-boards/user-guide-esp32-s3-korvo-2.html)
+    - Two micro USB cables: one for power, one for flashing
+    - Mono enclosed speaker (example from [Adafruit](https://www.adafruit.com/product/3351))
+
+### Run example
+
+To run the example on your board, begin in your terminal by navigating to the example's root directory: *[examples/voice_agent](./examples/voice_agent/)*.
+
+#### 1. Configuration
+
+The example requires a network connection and Sandbox ID from your [LiveKit Cloud Project](https://cloud.livekit.io/projects/p_/sandbox/templates/token-server). To configure these settings from your terminal, launch *menuconfig*:
+```sh
+idf.py menuconfig
+```
+
+With *menuconfig* open, navigate to the *LiveKit Example* menu and configure the following settings:
+
+- Network → Wi-Fi SSID
+- Network → Wi-Fi password
+- Room connection → Sandbox ID
+
+For more information about available options, please refer to [this guide](./examples/README.md#configuration).
+
+#### 2. Build & flash
+
+Begin by connecting your dev board via USB. With the board connected, use the following command
+to build the example, flash it to your board, and monitor serial output:
+
+```sh
+idf.py flash monitor
+```
+
+Once running on device, the example will establish a network connection and then connect to a
+LiveKit room. Once connected, you will see the following log message:
+
+```sh
+I (17208) livekit_example: Connected to room
+```
+
+If you encounter any issues during this process, please refer to the example [troubleshooting guide](./examples/README.md/#troubleshooting).
+
+### Run agent
+
+With the example running on your board, the next step is to run the agent so it can join the room.
+Begin by navigating to the agent's source directory in your terminal: *[examples/voice_agent/agent](./examples/voice_agent/agent)*.
+
+In this directory, create a *.env* file containing the required API keys:
+
+```sh
+DEEPGRAM_API_KEY=<your Deepgram API Key>
+OPENAI_API_KEY=<your OpenAI API Key>
+CARTESIA_API_KEY=<your Cartesia API Key>
+LIVEKIT_API_KEY=<your API Key>
+LIVEKIT_API_SECRET=<your API Secret>
+LIVEKIT_URL=<your server URL>
+```
+
+With the API keys in place, download the required files and run the agent in development mode as follows:
+
+```sh
+python agent.py download-files
+python agent.py dev
+```
 
+With the agent running, it will discover and join the room, and you will now be able to engage in two-way conversation. Try asking some of the questions shown above.
 
 ## Getting Help & Contributing
 

examples/README.md

@@ -0,0 +1,95 @@
+# Examples
+
+This directory contains example applications using the LiveKit ESP-32 SDK, demonstrating various features and
+use cases. For setup instructions specific to each example, see the example's README.
+
+## Configuration
+
+This guide lists the settings available for all examples. From within the example's root directory, you can set these options in two ways:
+
+1. **Using *menuconfig***: run `idf.py menuconfig`, navigate to the *LiveKit Example* submenu, and configure the
+list of available settings.
+
+2. **In an *sdkconfig* file**: place setting key-value pairs in an *sdkconfig* file in the format shown below.
+
+### Codec board type
+
+For examples that support multiple development boards, you can set the model of the board you are using as follows:
+
+```ini
+CONFIG_CODEC_BOARD_TYPE="S3_Korvo_V2"
+```
+
+See the README for each example for information about supported boards.
+
+### Network
+
+All examples require a network connection in order to connect to a LiveKit server. Choose one of the following connection options:
+
+#### Wi-Fi
+
+Connect using Wi-Fi by specifying your network SSID and password as follows:
+
+```ini
+CONFIG_NETWORK_MODE_WIFI=y
+CONFIG_WIFI_SSID="<your SSID>"
+CONFIG_WIFI_PASSWORD="<your password>"
+```
+
+#### Ethernet
+
+You can choose to connect using Ethernet on supported boards such as the [ESP32-P4-Function-EV-Board](https://docs.espressif.com/projects/esp-dev-kits/en/latest/esp32p4/esp32-p4-function-ev-board/user_guide.html).
+
+TODO:
+
+### Room connection
+
+In production, your backend server is responsible for [generating tokens](https://docs.livekit.io/home/server/generating-tokens/) for users to connect to a room.
+
+However, for the purposes of demonstration, each example supports two methods to supply the required tokens without
+creating a custom backend. Choose one of the following methods:
+
+#### Option A: Sandbox token server (recommended)
+
+A Sandbox Token Server is simple hosted component that exposes an HTTP endpoint to generate tokens—much like your own
+server would in production. To use this option, create a [Sandbox Token Server](https://cloud.livekit.io/projects/p_/sandbox/templates/token-server) for your LiveKit Cloud project, and set its ID in _sdkconfig_:
+
+```ini
+CONFIG_LK_USE_SANDBOX=y
+CONFIG_LK_SANDBOX_ID="<your sandbox id>"
+```
+
+(Optional) If you would like the token to be generated with a specific room or participant name, you can also add the following keys:
+
+```ini
+CONFIG_LK_SANDBOX_ROOM_NAME="robot-control"
+CONFIG_LK_SANDBOX_PARTICIPANT_NAME="esp-32"
+```
+
+#### Option B: Pre-generated token
+
+Connect to a room by proving a manually generated token and custom LiveKit server URL:
+
+```ini
+CONFIG_LK_USE_PREGENERATED=y
+CONFIG_LK_TOKEN="your-jwt-token"
+CONFIG_LK_SERVER_URL="ws://localhost:7880"
+```
+
+This option can be useful for local development or troubleshooting. Tokens can be generated using the *token* subcommand on the [LiveKit CLI](https://docs.livekit.io/home/cli/cli-setup/#generate-access-token), and you can follow [this guide](https://docs.livekit.io/home/self-hosting/local/) to install LiveKit server to run from your local machine.
+
+## Troubleshooting
+
+### No serial ports found
+
+If your board's serial port cannot be detected, check to see if it is recognized by your operating system:
+
+- macOS: Run `ls /dev/cu.*` and look for `/dev/cu.usbserial-*` or similar.
+- Linux: Run `ls /dev/ttyUSB*` or `ls /dev/ttyACM*`.
+- Windows: Check Device Manager under "Ports (COM & LPT)" for the COM port (e.g. _COM3_).
+
+If you see your board listed, you can manually specify its port to *idf.py* as follows:
+
+```
+idf.py -P /dev/cu.usbserial-xyz flash monitor
+```