> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketbyte.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Setup

> Everything you need to go from a fresh machine to building Pocketbyte apps.

This guide walks you through setting up your Pocketbyte development environment, adding the library component, and running your first application on the device in a few steps.

## Prerequisites

Before you begin, make sure you have the following:

* A Pocketbyte DevKit
* A USB-C cable
* A Windows, macOS, or Linux computer

## Steps

<Steps>
  <Step title="Install ESP-IDF">
    If you haven't already, install ESP-IDF v5.x by following the [official Espressif get-started guide](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/get-started/index.html) for your operating system. After installation, source the environment script so that `idf.py` is available in your shell:

    ```bash theme={null}
    . $HOME/esp/esp-idf/export.sh
    ```

    Verify the installation by checking the version:

    ```bash theme={null}
    idf.py --version
    ```

    You should see output similar to `ESP-IDF v5.x.x`. If you see an error, make sure the environment is sourced correctly before continuing.

    <Tip>
      VSCode has an official ESP-IDF extension that will install everything you need automatically. If the install process above is too complicated for you, just install this extension instead! After installing the extension, can use the ESP-IDF even without VSCode.
    </Tip>

    <Note>
      If you are on Windows, you can directly proceed with this step using WSL 2. If you do not want to use WSL2, your best option is to use the VSCode extension.
    </Note>
  </Step>

  <Step title="Create a new ESP-IDF project">
    Create a new ESP-IDF project using the `idf.py create-project` command. This sets up the standard directory structure including `main/`, `CMakeLists.txt`, and the required `idf_component.yml` manifest.

    ```bash theme={null}
    idf.py create-project my-pocketbyte-app
    cd my-pocketbyte-app
    ```

    Set the build target to the ESP32-S3 so that the toolchain and configuration defaults match your Pocketbyte hardware:

    ```bash theme={null}
    idf.py set-target esp32s3
    ```
  </Step>

  <Step title="Add the Pocketbyte component">
    From inside your project directory, add the Pocketbyte library as a managed component. The ESP-IDF component manager will fetch the latest compatible version and add it to your project's dependency manifest automatically.

    ```bash theme={null}
    idf.py add-dependency "omrawaley/pocketbyte"
    ```

    You'll see the component listed in `main/idf_component.yml` after this command completes. The library source is downloaded automatically during the next build.
  </Step>

  <Step title="Write a minimal main.c">
    Open `main/main.c` and replace its contents with the following minimal program. This tests to see if the library can be linked properly and if the code can execute without any runtime errors.

    ```c theme={null}
    #include <pocketbyte.h>

    void app_main(void)
    {
        return 0;
    }
    ```
  </Step>

  <Step title="Build and flash to your device">
    Connect your Pocketbyte to your computer via USB. Build the project and flash it to the device.

    ```bash theme={null}
    idf.py build && idf.py flash
    ```

    The device will reset after flashing and your app will start running immediately.

    <Tip>
      If the flash command times out waiting for the device to enter download mode, hold the **BOOT** button on Pocketbyte, then press and release the **RESET** button while keeping BOOT held, then release BOOT. The device will enter flash mode and the command will proceed.
    </Tip>
  </Step>

  <Step title="Build and flash to your device">
    Connect your Pocketbyte to your computer via USB. Build the project and flash it to the device.

    ```bash theme={null}
    idf.py build && idf.py flash
    ```

    The device will reset after flashing and your app will start running immediately.

    <Tip>
      If the flash command times out waiting for the device to enter download mode, hold the **BOOT** button on Pocketbyte, then press and release the **RESET** button while keeping BOOT held, then release BOOT. The device will enter flash mode and the command will proceed.
    </Tip>

    <Tip>
      Use `idf.py monitor` at any time to reconnect to the serial output of an already-flashed device. This is useful for reading debug output from `printf` statements in your app without reflashing. Press `Ctrl+]` to exit the monitor.
    </Tip>
  </Step>
</Steps>