Configuration

Configure WiFi credentials, API password, and server certificate for the Spotify MacroBoard

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.

WiFi configuration

const char SSID[] = "YourNetworkName";
const char SSID_PASS[] = "YourNetworkPassword";

Configuration parameters

Parameter	Description	Example
SSID	Your WiFi network name	”HomeNetwork”
SSID_PASS	Your 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.

Password configuration

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

   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

Certificate structure

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

Example certificate configuration

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:

Pin definitions

// 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

RGB LED settings

Setting	Value	Description
RGB_PIN	18	Data pin for LED strip
RGB_LED_NUM	20	Number of LEDs in strip
BRIGHTNESS	230	LED brightness (0-255)
CHIP_SET	WS2812B	LED chip type
COLOR_CODE	GRB	Color order for LEDs

Button assignments

Button	GPIO Pin	Function
SHUFFLE	4	Toggle shuffle mode
VOLUME_DEC	5	Decrease volume
VOLUME_INC	12	Increase volume
LOOP	13	Toggle repeat mode
BACK	14	Previous track
PAUSE_PLAY	25	Play/pause toggle
SKIP	26	Next track

Display configuration

Setting	Value	Description
SDA	21	I2C data pin
SCL	19	I2C clock pin
SCREEN_WIDTH	128	Display width in pixels
SCREEN_HEIGHT	64	Display height in pixels
OLED_RESET	-1	No 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

LEDs show red after upload

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

LEDs show yellow after connection

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

LEDs show orange

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

Compilation 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