> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/benz206/SpotifyMacroBoard/llms.txt
> Use this file to discover all available pages before exploring further.

# Software setup

> Install Arduino IDE, configure the ESP32 board, and install required libraries for the Spotify MacroBoard

This guide will walk you through setting up the development environment for the Spotify MacroBoard, including Arduino IDE installation, board configuration, and library dependencies.

## Prerequisites

Before you begin, ensure you have:

* A computer running Windows, macOS, or Linux
* USB cable (USB-C or Micro-USB depending on your ESP32 board)
* Internet connection for downloading libraries
* The Spotify MacroBoard source code

## Install Arduino IDE

<Steps>
  <Step title="Download Arduino IDE">
    Download the latest version of Arduino IDE from the [official Arduino website](https://www.arduino.cc/en/software). Version 2.0 or higher is recommended for the best experience.
  </Step>

  <Step title="Install the IDE">
    Run the installer and follow the on-screen instructions for your operating system.
  </Step>

  <Step title="Launch Arduino IDE">
    Open Arduino IDE after installation completes.
  </Step>
</Steps>

## Configure ESP32 board support

The Spotify MacroBoard uses an ESP32 microcontroller, which requires additional board definitions.

<Steps>
  <Step title="Open board manager URL preferences">
    Navigate to **File > Preferences** (or **Arduino IDE > Settings** on macOS).
  </Step>

  <Step title="Add ESP32 board manager URL">
    In the "Additional Board Manager URLs" field, add:

    ```
    https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
    ```

    <Info>If you already have other board URLs, separate them with commas or use the button next to the field to add a new line.</Info>
  </Step>

  <Step title="Open board manager">
    Go to **Tools > Board > Board Manager**.
  </Step>

  <Step title="Install ESP32 boards">
    Search for "esp32" and install the **esp32 by Espressif Systems** package. This may take a few minutes.
  </Step>

  <Step title="Select your ESP32 board">
    After installation, go to **Tools > Board > esp32** and select **ESP32 Dev Module** (or the specific ESP32 variant you're using).
  </Step>
</Steps>

## Board configuration

Configure the board settings to match the Spotify MacroBoard specifications:

<CodeGroup>
  ```json Arduino configuration theme={null}
  {
    "configuration": "JTAGAdapter=default,PSRAM=disabled,PartitionScheme=default,CPUFreq=240,FlashMode=qio,FlashFreq=80,FlashSize=4M,UploadSpeed=921600,LoopCore=1,EventsCore=1,DebugLevel=none,EraseFlash=none",
    "board": "esp32:esp32:esp32"
  }
  ```
</CodeGroup>

Set these parameters in the Arduino IDE:

| Parameter | Value | Location |
| - | - | - |
| Board | ESP32 Dev Module | Tools > Board |
| CPU Frequency | 240 MHz | Tools > CPU Frequency |
| Flash Frequency | 80 MHz | Tools > Flash Frequency |
| Flash Mode | QIO | Tools > Flash Mode |
| Flash Size | 4 MB | Tools > Flash Size |
| Upload Speed | 921600 | Tools > Upload Speed |
| Partition Scheme | Default | Tools > Partition Scheme |

<Warning>Using different flash or CPU frequencies may cause instability or prevent the device from functioning correctly.</Warning>

## Install required libraries

The Spotify MacroBoard requires several libraries for display, LED control, and network communication.

<Steps>
  <Step title="Open library manager">
    Navigate to **Tools > Manage Libraries** or click the library icon in the left sidebar.
  </Step>

  <Step title="Install Adafruit GFX Library">
    Search for "Adafruit GFX" and install **Adafruit GFX Library** by Adafruit.

    This library provides graphics primitives for displays.
  </Step>

  <Step title="Install Adafruit SSD1306">
    Search for "Adafruit SSD1306" and install **Adafruit SSD1306** by Adafruit.

    This library drives the OLED display used in the MacroBoard.
  </Step>

  <Step title="Install FastLED">
    Search for "FastLED" and install **FastLED** by Daniel Garcia.

    FastLED controls the WS2812B RGB LED strip.
  </Step>
</Steps>

<Note>
  The WiFi, WiFiClientSecure, and Wire libraries are built into the ESP32 board package and don't need separate installation.
</Note>

### Library summary

| Library | Purpose | Used For |
| - | - | - |
| Adafruit\_GFX | Graphics primitives | Drawing text and shapes on OLED |
| Adafruit\_SSD1306 | OLED display driver | 128x64 OLED display control |
| FastLED | LED control | WS2812B RGB LED strip |
| WiFi | Network connectivity | Connecting to WiFi network |
| WiFiClientSecure | HTTPS requests | Secure API communication |
| Wire | I2C communication | OLED display communication |

## Connect your ESP32

<Steps>
  <Step title="Connect via USB">
    Connect your ESP32 board to your computer using a USB cable.
  </Step>

  <Step title="Install drivers (if needed)">
    Windows users may need to install CP210x or CH340 USB drivers depending on your ESP32 board variant. Check your board documentation.
  </Step>

  <Step title="Select the port">
    In Arduino IDE, go to **Tools > Port** and select the port that corresponds to your ESP32 (usually labeled as "CP2102" or "CH340" on Windows, or "/dev/cu.usbserial" on macOS).
  </Step>

  <Step title="Verify connection">
    Click the **Verify** button (checkmark icon) to compile a blank sketch and ensure your setup is working correctly.
  </Step>
</Steps>

<Tip>
  If your ESP32 isn't detected, try a different USB cable. Some cables are charge-only and don't support data transfer.
</Tip>

## Open the Spotify MacroBoard code

<Steps>
  <Step title="Download the source code">
    Clone or download the Spotify MacroBoard source code repository to your computer.
  </Step>

  <Step title="Open the sketch">
    In Arduino IDE, go to **File > Open** and navigate to the `src/src.ino` file in the source code directory.
  </Step>

  <Step title="Verify compilation">
    Click the **Verify** button to compile the code. This will check for any missing dependencies.

    <Info>
      The compiled sketch uses approximately 886,189 bytes (67%) of program storage and 45,808 bytes (13%) of dynamic memory on a standard ESP32.
    </Info>
  </Step>
</Steps>

## Next steps

Now that your development environment is set up, proceed to configure your credentials and network settings:

<Card title="Configuration" icon="gear" href="/software/configuration">
  Configure WiFi credentials, API password, and server certificate
</Card>