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

# PlatformIO Setup and Configuration for Proton AI Core

> Configure PlatformIO to build and flash Proton AI Core projects. Set up platformio.ini with the ESP32-S3 board target and upload your first firmware.

PlatformIO is a professional, IDE-agnostic development platform that offers dependency management, multi-environment builds, and a rich library ecosystem — making it a powerful alternative to Arduino IDE for larger or more complex Proton AI Core projects. This guide walks you through creating a project, configuring `platformio.ini` for the ESP32-S3, and uploading your first firmware.

## Prerequisites

Before you begin, make sure you have the following ready:

* **Visual Studio Code** installed ([code.visualstudio.com](https://code.visualstudio.com))
* **PlatformIO IDE extension** installed in VS Code (search "PlatformIO IDE" in the Extensions panel)
* **USB driver** installed for your operating system — see the [Drivers](/setup/drivers) page if you haven't done this yet
* A **USB-C data cable** (charge-only cables will not work)

## Setup Steps

<Steps>
  <Step title="Create a New Project">
    Open the **PlatformIO Home** tab in VS Code (click the PlatformIO icon in the Activity Bar, then select **Home**).

    Click **New Project** and fill in the following fields:

    * **Name:** Your project name
    * **Board:** `Espressif ESP32-S3-DevKitC-1` (the closest compatible target — see the note below)
    * **Framework:** Arduino

    Click **Finish**. PlatformIO will scaffold the project and generate a `platformio.ini` file.

    <Note>
      A dedicated Proton AI Core board definition is planned. For now, use the ESP32-S3-DevKitC-1 board target as a compatible configuration.
    </Note>
  </Step>

  <Step title="Configure platformio.ini">
    Open the generated `platformio.ini` at the root of your project and replace its contents with the following:

    ```ini platformio.ini theme={null}
    [env:proton_ai_core]
    platform = espressif32
    board = esp32-s3-devkitc-1
    framework = arduino
    upload_speed = 921600
    monitor_speed = 115200
    build_flags =
        -DARDUINO_USB_MODE=1
        -DARDUINO_USB_CDC_ON_BOOT=1
    board_build.arduino.memory_type = qio_opi
    ```

    These flags enable USB CDC on boot so that `Serial.print()` output is routed over the USB-C connection, and configure the memory type for OPI PSRAM.
  </Step>

  <Step title="Write Your Code">
    Open `src/main.cpp` and replace its contents with the following:

    ```cpp src/main.cpp theme={null}
    #include <Arduino.h>

    void setup() {
      Serial.begin(115200);
      Serial.println("Proton AI Core — PlatformIO ready!");
    }

    void loop() {
      Serial.println("Running...");
      delay(1000);
    }
    ```
  </Step>

  <Step title="Build & Upload">
    Connect Proton AI Core to your computer with the USB-C data cable.

    To build and upload your firmware, use one of the following methods:

    * Click the **Upload** button (→) in the PlatformIO toolbar at the bottom of VS Code
    * Run the following command in a terminal at the project root:

      ```bash theme={null}
      pio run --target upload
      ```

    PlatformIO will compile the code and flash it to the board automatically.
  </Step>

  <Step title="Open Serial Monitor">
    To see output from `Serial.println()`, open the Serial Monitor using one of the following methods:

    * Click the **plug icon** in the PlatformIO toolbar at the bottom of VS Code
    * Run the following command in a terminal:

      ```bash theme={null}
      pio device monitor
      ```

    The monitor uses the `monitor_speed` value set in `platformio.ini` (115200 baud).
  </Step>
</Steps>

## Adding Libraries

PlatformIO manages library dependencies through the `lib_deps` key in `platformio.ini`. To add a library, specify it by its registry name and version — PlatformIO downloads and links it automatically at build time.

For example, to add the `esp32-camera` library for camera support:

```ini theme={null}
lib_deps =
    espressif/esp32-camera @ ^2.0.0
```

You can find additional libraries on the [PlatformIO Registry](https://registry.platformio.org) or specify a GitHub URL directly.

<Tip>
  PlatformIO handles library dependencies automatically — no manual downloads needed.
</Tip>