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

1. Download Arduino IDE

   Download the latest version of Arduino IDE from the official Arduino website. Version 2.0 or higher is recommended for the best experience.

2. Install the IDE

   Run the installer and follow the on-screen instructions for your operating system.

3. Launch Arduino IDE

   Open Arduino IDE after installation completes.

Configure ESP32 board support

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

1. Open board manager URL preferences

   Navigate to File > Preferences (or Arduino IDE > Settings on macOS).

2. 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
   

   If you already have other board URLs, separate them with commas or use the button next to the field to add a new line.
3. Open board manager

   Go to Tools > Board > Board Manager.

4. Install ESP32 boards

   Search for “esp32” and install the esp32 by Espressif Systems package. This may take a few minutes.

5. Select your ESP32 board

   After installation, go to Tools > Board > esp32 and select ESP32 Dev Module (or the specific ESP32 variant you’re using).

Board configuration

Configure the board settings to match the Spotify MacroBoard specifications:

Arduino configuration

{
  "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"
}

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

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

Install required libraries

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

1. Open library manager

   Navigate to Tools > Manage Libraries or click the library icon in the left sidebar.

2. Install Adafruit GFX Library

   Search for “Adafruit GFX” and install Adafruit GFX Library by Adafruit.

   This library provides graphics primitives for displays.

3. Install Adafruit SSD1306

   Search for “Adafruit SSD1306” and install Adafruit SSD1306 by Adafruit.

   This library drives the OLED display used in the MacroBoard.

4. Install FastLED

   Search for “FastLED” and install FastLED by Daniel Garcia.

   FastLED controls the WS2812B RGB LED strip.

The WiFi, WiFiClientSecure, and Wire libraries are built into the ESP32 board package and don’t need separate installation.

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

1. Connect via USB

   Connect your ESP32 board to your computer using a USB cable.

2. 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.

3. 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).

4. Verify connection

   Click the Verify button (checkmark icon) to compile a blank sketch and ensure your setup is working correctly.

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

Open the Spotify MacroBoard code

1. Download the source code

   Clone or download the Spotify MacroBoard source code repository to your computer.

2. Open the sketch

   In Arduino IDE, go to File > Open and navigate to the src/src.ino file in the source code directory.

3. Verify compilation

   Click the Verify button to compile the code. This will check for any missing dependencies.

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

Next steps

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

Configuration

Configure WiFi credentials, API password, and server certificate