Skip to main content

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.

Before uploading the code to your ESP32, you need to configure credentials and network settings. This includes WiFi credentials, API authentication, and SSL certificate configuration.

​
Create credentials file

The Spotify MacroBoard uses a separate header file for credentials to keep sensitive information organized and secure.
1

Locate the sample file

Navigate to the src directory in your Spotify MacroBoard source code and find SampleCredentials.h.
2

Create your credentials file

Make a copy of SampleCredentials.h and rename it to SMBCredentials.h.
The main code expects the file to be named SMBCredentials.h. Using a different name will cause compilation errors.
3

Open for editing

Open SMBCredentials.h in Arduino IDE or your preferred text editor.

​
Configure WiFi settings

The ESP32 needs WiFi credentials to connect to your network and communicate with the Spotify API server. 
const char SSID[] = "YourNetworkName";
const char SSID_PASS[] = "YourNetworkPassword";

​
Configuration parameters

ParameterDescriptionExample
SSIDYour WiFi network name”HomeNetwork”
SSID_PASSYour WiFi password”MySecurePassword123”
2.4 GHz network required: The ESP32 WiFi radio only supports 2.4 GHz networks. Make sure you’re connecting to a 2.4 GHz network, not 5 GHz.If your router uses a combined SSID for both bands, you may need to create a separate 2.4 GHz network or ensure the ESP32 connects to the correct band.
Avoid using special characters in your WiFi password that might require escaping in C++ strings (such as backslashes or quotes). If you must use them, escape them properly with a backslash.

​
Set API password

The API password authenticates your MacroBoard with the Spotify control server. 
const String PASSWORD = "YourSecureAPIPassword";
This password is used in API requests to /api/manageState/ and /api/getCurrent/ endpoints. You’ll need to configure the same password on your server.

​
Configure server certificate

The MacroBoard uses HTTPS for secure communication with the API server. You need to provide the server’s SSL certificate.

​
Get your server certificate

1

Connect to your server

Use OpenSSL or your browser to retrieve the SSL certificate from your server:
openssl s_client -connect benzhou.tech:443 -showcerts
2

Copy the certificate

Copy the entire certificate including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.
3

Format for C++

Format the certificate as a C++ string with line breaks escaped as \n.

​
Certificate configuration

const char *benzServerCert =
    "-----BEGIN CERTIFICATE-----\n"
    "MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQGEwJJ\n"
    "RTESMBAGA1UEChMJQmFsdGltb3JlMRMwEQYDVQQLEwpDeWJlclRydXN0MSIwIAYD\n"
    "VQQDExlCYWx0aW1vcmUgQ3liZXJUcnVzdCBSb290MB4XDTAwMDUxMjE4NDYwMFoX\n"
    // ... more certificate lines ...
    "-----END CERTIFICATE-----";

const char *benzServerCert =
    "-----BEGIN CERTIFICATE-----\n"
    "MIIGEzCCA/ugAwIBAgIQfVtRJrR2uhHbdBYLvFMNpzANBgkqhkiG9w0BAQwFADCB\n"
    "iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl\n"
    "cnNleSBDaXR5MR4wHAYDVQQKExVUaGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNV\n"
    "BAMTJVVTRVJUcnVzdCBSU0EgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMTgx\n"
    "MTAyMDAwMDAwWhcNMzAxMjMxMjM1OTU5WjCBjzELMAkGA1UEBhMCR0IxGzAZBgNV\n"
    "BAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4GA1UEBxMHU2FsZm9yZDEYMBYGA1UE\n"
    // ... additional lines ...
    "-----END CERTIFICATE-----";
The certificate is set using wifiClient.setCACert(benzServerCert) during setup. This ensures all HTTPS connections are verified against this certificate.

​
Pin configuration

The pin assignments are defined in the credentials file. Verify these match your hardware connections: 
// LED configuration
#define RGB_PIN 18
#define RGB_LED_NUM 20
#define BRIGHTNESS 230
#define CHIP_SET WS2812B
#define COLOR_CODE GRB

// Button pins
#define SHUFFLE 4
#define VOLUME_DEC 5
#define VOLUME_INC 12
#define LOOP 13
#define BACK 14
#define PAUSE_PLAY 25
#define SKIP 26

// Display pins
#define LED 18
#define SCL 19
#define SDA 21
#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1

​
Pin reference

SettingValueDescription
RGB_PIN18Data pin for LED strip
RGB_LED_NUM20Number of LEDs in strip
BRIGHTNESS230LED brightness (0-255)
CHIP_SETWS2812BLED chip type
COLOR_CODEGRBColor order for LEDs
ButtonGPIO PinFunction
SHUFFLE4Toggle shuffle mode
VOLUME_DEC5Decrease volume
VOLUME_INC12Increase volume
LOOP13Toggle repeat mode
BACK14Previous track
PAUSE_PLAY25Play/pause toggle
SKIP26Next track
SettingValueDescription
SDA21I2C data pin
SCL19I2C clock pin
SCREEN_WIDTH128Display width in pixels
SCREEN_HEIGHT64Display height in pixels
OLED_RESET-1No reset pin used
Do not modify pin definitions unless your hardware uses different connections. Incorrect pin assignments can damage your ESP32 or components.

​
Verify configuration

Before uploading, verify your configuration:
1

Check file inclusion

Ensure the main sketch (src.ino) includes your credentials file:
#include <SMBCredentials.h>
2

Verify compilation

Click the Verify button in Arduino IDE to compile the code and check for errors.
3

Review credentials

Double-check that:
  • WiFi SSID and password are correct
  • Network is 2.4 GHz
  • API password matches your server configuration
  • Server certificate is properly formatted

​
Upload to ESP32

Once your configuration is complete:
1

Connect ESP32

Connect your ESP32 to your computer via USB.
2

Select port

Verify the correct port is selected in Tools > Port.
3

Upload

Click the Upload button (right arrow icon) to compile and upload the code.The upload process typically takes 30-60 seconds.
4

Monitor connection

After upload, watch the RGB LEDs for connection status:
  • Pulsing white: Connecting to WiFi
  • Fade to green: Successfully connected
  • Red: Connection error
If the upload fails, try holding the BOOT button on your ESP32 when you see “Connecting…” in the Arduino IDE console.

​
Troubleshooting

Cause: Cannot connect to WiFi or API server.Solutions:
  • Verify WiFi credentials are correct
  • Ensure you’re using a 2.4 GHz network
  • Check that your router is broadcasting the SSID
  • Move the ESP32 closer to your router
  • Verify the server certificate is correct
Cause: API request timeout.Solutions:
  • Check that your server is running and accessible
  • Verify the API password is correct
  • Ensure your firewall allows connections on port 443
  • Check server logs for errors
Cause: Invalid response from server.Solutions:
  • Verify the server is returning proper JSON responses
  • Check that the API endpoints are implemented correctly
  • Review server logs for errors
Cause: Missing or incorrect configuration.Solutions:
  • Ensure SMBCredentials.h exists in the src directory
  • Verify all required libraries are installed
  • Check that pin definitions don’t conflict
  • Ensure certificate string is properly formatted

​
Next steps

Code overview

Learn about the code structure and how the MacroBoard works

Build docs developers (and LLMs) love

Get started for freeTalk to us