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

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

<Steps>
  <Step title="Locate the sample file">
    Navigate to the `src` directory in your Spotify MacroBoard source code and find `SampleCredentials.h`.
  </Step>

  <Step title="Create your credentials file">
    Make a copy of `SampleCredentials.h` and rename it to `SMBCredentials.h`.

    <Warning>
      The main code expects the file to be named `SMBCredentials.h`. Using a different name will cause compilation errors.
    </Warning>
  </Step>

  <Step title="Open for editing">
    Open `SMBCredentials.h` in Arduino IDE or your preferred text editor.
  </Step>
</Steps>

## Configure WiFi settings

The ESP32 needs WiFi credentials to connect to your network and communicate with the Spotify API server.

<CodeGroup>
  ```cpp WiFi configuration theme={null}
  const char SSID[] = "YourNetworkName";
  const char SSID_PASS[] = "YourNetworkPassword";
  ```

  ```cpp Example theme={null}
  const char SSID[] = "HomeNetwork";
  const char SSID_PASS[] = "MySecurePassword123";
  ```
</CodeGroup>

### Configuration parameters

| Parameter | Description | Example |
| - | - | - |
| `SSID` | Your WiFi network name | "HomeNetwork" |
| `SSID_PASS` | Your WiFi password | "MySecurePassword123" |

<Warning>
  **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.
</Warning>

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

## Set API password

The API password authenticates your MacroBoard with the Spotify control server.

<CodeGroup>
  ```cpp Password configuration theme={null}
  const String PASSWORD = "YourSecureAPIPassword";
  ```

  ```cpp Example theme={null}
  const String PASSWORD = "MySpotifyMacroBoard2024";
  ```
</CodeGroup>

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

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

<Steps>
  <Step title="Connect to your server">
    Use OpenSSL or your browser to retrieve the SSL certificate from your server:

    <CodeGroup>
      ```bash OpenSSL theme={null}
      openssl s_client -connect benzhou.tech:443 -showcerts
      ```

      ```bash Browser method theme={null}
      # In Chrome/Edge:
      # 1. Visit https://yourserver.com
      # 2. Click the padlock icon
      # 3. Click "Certificate"
      # 4. Go to "Details" tab
      # 5. Click "Export"
      ```
    </CodeGroup>
  </Step>

  <Step title="Copy the certificate">
    Copy the entire certificate including the `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----` lines.
  </Step>

  <Step title="Format for C++">
    Format the certificate as a C++ string with line breaks escaped as `\n`.
  </Step>
</Steps>

### Certificate configuration

<CodeGroup>
  ```cpp Certificate structure theme={null}
  const char *benzServerCert =
      "-----BEGIN CERTIFICATE-----\n"
      "MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQGEwJJ\n"
      "RTESMBAGA1UEChMJQmFsdGltb3JlMRMwEQYDVQQLEwpDeWJlclRydXN0MSIwIAYD\n"
      "VQQDExlCYWx0aW1vcmUgQ3liZXJUcnVzdCBSb290MB4XDTAwMDUxMjE4NDYwMFoX\n"
      // ... more certificate lines ...
      "-----END CERTIFICATE-----";
  ```
</CodeGroup>

<Accordion title="Example certificate configuration">
  ```cpp theme={null}
  const char *benzServerCert =
      "-----BEGIN CERTIFICATE-----\n"
      "MIIGEzCCA/ugAwIBAgIQfVtRJrR2uhHbdBYLvFMNpzANBgkqhkiG9w0BAQwFADCB\n"
      "iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl\n"
      "cnNleSBDaXR5MR4wHAYDVQQKExVUaGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNV\n"
      "BAMTJVVTRVJUcnVzdCBSU0EgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMTgx\n"
      "MTAyMDAwMDAwWhcNMzAxMjMxMjM1OTU5WjCBjzELMAkGA1UEBhMCR0IxGzAZBgNV\n"
      "BAgTEkdyZWF0ZXIgTWFuY2hlc3RlcjEQMA4GA1UEBxMHU2FsZm9yZDEYMBYGA1UE\n"
      // ... additional lines ...
      "-----END CERTIFICATE-----";
  ```
</Accordion>

<Note>
  The certificate is set using `wifiClient.setCACert(benzServerCert)` during setup. This ensures all HTTPS connections are verified against this certificate.
</Note>

## Pin configuration

The pin assignments are defined in the credentials file. Verify these match your hardware connections:

<CodeGroup>
  ```cpp Pin definitions theme={null}
  // 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
  ```
</CodeGroup>

### Pin reference

<Accordion title="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 |
</Accordion>

<Accordion title="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 |
</Accordion>

<Accordion title="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 |
</Accordion>

<Warning>
  Do not modify pin definitions unless your hardware uses different connections. Incorrect pin assignments can damage your ESP32 or components.
</Warning>

## Verify configuration

Before uploading, verify your configuration:

<Steps>
  <Step title="Check file inclusion">
    Ensure the main sketch (`src.ino`) includes your credentials file:

    ```cpp theme={null}
    #include <SMBCredentials.h>
    ```
  </Step>

  <Step title="Verify compilation">
    Click the **Verify** button in Arduino IDE to compile the code and check for errors.
  </Step>

  <Step title="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
  </Step>
</Steps>

## Upload to ESP32

Once your configuration is complete:

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

  <Step title="Select port">
    Verify the correct port is selected in **Tools > Port**.
  </Step>

  <Step title="Upload">
    Click the **Upload** button (right arrow icon) to compile and upload the code.

    The upload process typically takes 30-60 seconds.
  </Step>

  <Step title="Monitor connection">
    After upload, watch the RGB LEDs for connection status:

    * **Pulsing white**: Connecting to WiFi
    * **Fade to green**: Successfully connected
    * **Red**: Connection error
  </Step>
</Steps>

<Tip>
  If the upload fails, try holding the BOOT button on your ESP32 when you see "Connecting..." in the Arduino IDE console.
</Tip>

## Troubleshooting

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

<Accordion title="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
</Accordion>

## Next steps

<Card title="Code overview" icon="code" href="/software/code-overview">
  Learn about the code structure and how the MacroBoard works
</Card>