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.

This guide will walk you through assembling your Spotify MacroBoard. Follow each step carefully to ensure a successful build.
Safety firstSoldering involves high temperatures and toxic fumes. Always:
  • Work in a well-ventilated area
  • Wear safety glasses
  • Keep soldering iron away from flammable materials
  • Use a soldering iron stand
  • Wash hands after soldering
  • Never touch the soldering iron tip

​
Before you begin

​
Required tools

  • Soldering iron (temperature controlled, 300-350°C)
  • Solder (60/40, 63/37, or lead-free)
  • Wire strippers
  • Flush cutters
  • Multimeter
  • Helping hands or PCB holder
  • Isopropyl alcohol (for cleaning flux)
  • Cotton swabs or brush

​
Required components

Ensure you have all components from the component list:
  • Custom PCB
  • ESP32 development board
  • SSD1306 OLED display (128x64, I2C)
  • WS2812B LED strip (20 LEDs)
  • 7 mechanical switches
  • 7 keycaps (optional)
  • Pin headers
  • Resistors and capacitors (per schematic)
  • Wire (22-24 AWG)
  • USB cable
Read through the entire guide before starting assembly. This will help you understand the process and avoid mistakes.

​
Assembly overview

The assembly process follows this order:
  1. PCB preparation and inspection
  2. Solder surface-mount components (if any)
  3. Solder through-hole components (resistors, capacitors)
  4. Install pin headers
  5. Mount mechanical switches
  6. Connect ESP32
  7. Connect OLED display
  8. Install WS2812B LED strip
  9. Testing and verification
  10. Final assembly

​
Step-by-step assembly

1

Prepare the PCB

Inspect the PCB:
  • Check for manufacturing defects
  • Verify all holes are properly drilled
  • Look for any shorts or broken traces
Clean the PCB:
  • Wipe with isopropyl alcohol to remove any oils
  • Dry completely before soldering
Test continuity:
  • Use a multimeter to verify ground connections
  • Check that there are no shorts between power rails
  • Verify critical traces are continuous
2

Solder passive components

Start with the smallest components first (resistors, then capacitors).For each component:
  1. Identify its position on the PCB using the schematic
  2. Insert the component leads through the holes
  3. Bend the leads slightly to hold the component in place
  4. Flip the board over
  5. Solder each lead
  6. Trim excess leads with flush cutters
  • Heat both the pad and component lead simultaneously
  • Apply solder to the joint, not the iron
  • Use just enough solder to form a shiny, cone-shaped joint
  • Avoid cold solder joints (dull, grainy appearance)
  • Don’t overheat components (3-5 seconds per joint)
Critical components:
  • Decoupling capacitors near the ESP32 power pins (100nF)
  • Power supply capacitors (10µF electrolytic)
  • Any resistors specified in the schematic
If your design uses internal pull-ups (as in the default firmware), you don’t need external pull-up resistors for the switches.
3

Install pin headers

Pin headers allow you to mount the ESP32 and OLED display without direct soldering.For the ESP32:
  1. Place female pin headers where the ESP32 will mount
  2. Use the ESP32 itself to align the headers properly
  3. Tack solder one pin on each header
  4. Check alignment before soldering all pins
  5. Solder all remaining pins
For the OLED display:
  1. Use 4-pin female or male headers (depending on your display module)
  2. Align with the I2C connection points (VCC, GND, SDA, SCL)
  3. Tack solder one pin
  4. Check alignment
  5. Solder remaining pins
Using pin headers makes it easy to replace components if needed. For a more permanent installation, you can solder directly to the PCB.
4

Mount mechanical switches

The 7 mechanical switches are the main input method for the MacroBoard.Installation:
  1. Insert each switch into its designated position on the PCB
  2. Ensure the pins align with the holes
  3. Press firmly until the switch sits flush with the PCB
  4. The switch should click into place
  5. Flip the board over
  6. Solder the switch pins (usually 2 pins per switch)
  7. Trim any excess pin length
Switch positions (from left to right):
  • Position 1: Shuffle (GPIO 4)
  • Position 2: Volume Down (GPIO 5)
  • Position 3: Volume Up (GPIO 12)
  • Position 4: Loop/Repeat (GPIO 13)
  • Position 5: Previous Track (GPIO 14)
  • Position 6: Play/Pause (GPIO 25)
  • Position 7: Next Track (GPIO 26)
If your switches have PCB mount pins (5 pins total), solder all pins for maximum stability.
5

Connect the ESP32

The ESP32 is the microcontroller that runs the firmware.If using pin headers:
  1. Insert the ESP32 into the female headers
  2. Ensure proper orientation (check pin labels)
  3. Press firmly until seated
If soldering directly:
  1. Place the ESP32 on the PCB
  2. Align all pins with their pads
  3. Tack solder opposite corners
  4. Check alignment
  5. Solder all remaining pins
Verify orientation before soldering!Double-check that the ESP32 is oriented correctly. The USB port should be accessible for programming. Soldering it backwards will prevent the board from working.
Pin verification: After mounting, verify these critical connections with a multimeter:
  • GPIO 18 → LED data pad
  • GPIO 19 → SCL pad (OLED)
  • GPIO 21 → SDA pad (OLED)
  • All switch GPIO pins → their respective switch pads
6

Connect the OLED display

The SSD1306 OLED display shows track information and status.Wiring:
  • Display VCC → PCB VCC (3.3V or 5V depending on display)
  • Display GND → PCB GND
  • Display SDA → PCB SDA (GPIO 21)
  • Display SCL → PCB SCL (GPIO 19)
Connection methods:
  1. Insert the OLED display into the 4-pin header
  2. Ensure pins are properly aligned (VCC, GND, SDA, SCL)
  3. Press firmly until seated
This method allows easy removal for repairs or upgrades.
The firmware configures the I2C bus at 400 kHz. Most SSD1306 displays support this speed, but if you experience issues, you can modify the firmware to use 100 kHz (Standard Mode).
7

Install the LED strip

The WS2812B LED strip provides visual feedback with colors matching the album art.Preparation:
  1. If you have a longer LED strip, cut it to exactly 20 LEDs
  2. Cut along the designated cut lines (usually marked on the strip)
  3. Note the direction: there’s a data input (DIN) and data output (DOUT) end
  4. The data flows in one direction only
Wiring:
  • LED Strip 5V → PCB 5V
  • LED Strip GND → PCB GND
  • LED Strip DIN → PCB LED Data (GPIO 18)
Power considerations20 LEDs can draw up to 1200mA at full brightness (60mA per LED). The firmware limits this to 500mA, but ensure your power supply is rated for at least 1A total.
Connection methods:
If your LED strip has solder pads at the beginning:
  1. Tin the pads on both the LED strip and PCB
  2. Cut 3 pieces of wire (5-10cm each)
  3. Solder one end to the LED strip pads (5V, GND, DIN)
  4. Solder the other end to the corresponding PCB pads
  5. Use heat shrink tubing for insulation
Mounting the LED strip:
  • LED strips often have adhesive backing
  • Plan the LED placement around the PCB perimeter or beneath keycaps
  • Clean the mounting surface before applying
  • Press firmly for 30 seconds
  • Additional support with hot glue or zip ties is recommended
8

Initial testing

Before final assembly, test all components to ensure everything works.Power test:
  1. Connect USB cable to the ESP32
  2. Do NOT plug into computer yet
  3. Use a multimeter to check:
    • 5V rail is present
    • 3.3V rail is present (if applicable)
    • No shorts between power and ground
Component test:
  1. Plug USB cable into computer
  2. ESP32 power LED should illuminate
  3. Upload a test sketch or the final firmware
LED test:
  • All 20 LEDs should turn white on startup
  • If connecting to WiFi, LEDs pulse white
  • After WiFi connection, LEDs turn green
  • If any LED doesn’t work, check connections and data line continuity
OLED test:
  • Display should initialize (may flash briefly)
  • If display shows “OrangeRed” on LEDs and freezes, the display failed to initialize
  • Check I2C connections (SDA, SCL)
  • Verify I2C address is 0x3C
Switch test:
  • Press each switch and verify the corresponding action
  • If a switch doesn’t work:
    • Check solder joints
    • Verify GPIO pin connection
    • Ensure switch is properly seated
If the OLED fails to initialize, the firmware will display OrangeRed on all LEDs and halt:
if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    for (int i = 0; i < RGB_LED_NUM; i++) {
        LEDs[i] = CRGB::OrangeRed;
    }
    FastLED.show();
    for (;;);
}
This indicates an I2C communication problem.
9

Install keycaps

Once testing is complete, install the keycaps on the switches.Installation:
  1. Align the keycap stem with the switch stem
  2. Press down firmly until you hear/feel a click
  3. The keycap should be secure and not wobble
Keycap labeling (optional):
  • Use a label maker for professional-looking labels
  • Use vinyl stickers or decals
  • 3D print custom keycaps with legends
  • Leave blank for a minimalist look
Suggested labels:
  1. Shuffle (🔀)
  2. Vol - (🔉)
  3. Vol + (🔊)
  4. Loop (🔁)
  5. Previous (⏮)
  6. Play/Pause (⏯)
  7. Next (⏭)
10

Final assembly and cleanup

Complete the assembly and prepare for use.Cleaning:
  1. Power off the device
  2. Clean flux residue with isopropyl alcohol
  3. Use a brush or cotton swab
  4. Let dry completely
Inspection:
  • Check all solder joints for quality
  • Verify no loose wires or components
  • Ensure no shorts or exposed conductors
  • Test mechanical stability of all parts
Optional enclosure:
  • Design and 3D print a case
  • Use standoffs to mount the PCB
  • Add rubber feet for stability
  • Ensure access to USB port for programming
Cable management:
  • Use cable clips or adhesive mounts
  • Route USB cable neatly
  • Secure loose wires with zip ties or hot glue

​
Troubleshooting

Common issues and solutions:
Possible causes:
  • No power to LED strip (check 5V connection)
  • Data line not connected (check GPIO 18)
  • Wrong data direction (LED strips are directional)
  • Faulty LED strip
Solutions:
  1. Verify 5V and GND connections with multimeter
  2. Check continuity of data line from ESP32 GPIO 18 to LED strip DIN
  3. Ensure LED strip DIN is connected (not DOUT)
  4. Test with a simple LED test sketch
Possible causes:
  • I2C connections (SDA/SCL) swapped or disconnected
  • Wrong I2C address
  • Insufficient power
  • Faulty display module
Solutions:
  1. Verify SDA (GPIO 21) and SCL (GPIO 19) connections
  2. Scan for I2C devices using an I2C scanner sketch
  3. Check display receives proper voltage (3.3V or 5V)
  4. Try reducing I2C speed in firmware (400 kHz → 100 kHz)
  5. Test display with a separate sketch
Possible causes:
  • Poor solder joints
  • Switch not fully seated
  • GPIO pin not connected
  • Wrong pin mapping in firmware
Solutions:
  1. Reflow solder joints on the non-working switch
  2. Verify switch is fully inserted into PCB
  3. Check continuity from switch pin to ESP32 GPIO
  4. Verify pin mapping in firmware matches hardware: 
    #define SHUFFLE 4
#define VOLUME_DEC 5
#define VOLUME_INC 12
#define LOOP 13
#define BACK 14
#define PAUSE_PLAY 25
#define SKIP 26
  5. Test switch with multimeter (continuity mode)
Possible causes:
  • Wrong WiFi credentials
  • 5 GHz network (ESP32 only supports 2.4 GHz)
  • Network security settings
  • Weak signal
Solutions:
  1. Verify SSID and password in credentials file
  2. Ensure using a 2.4 GHz network (ESP32 doesn’t support 5 GHz)
  3. Try a network with WPA2 security
  4. Move closer to WiFi router
  5. LEDs will pulse white while attempting connection
Possible causes:
  • Wrong COM port selected
  • Driver not installed
  • USB cable is power-only (no data)
  • Faulty ESP32
Solutions:
  1. Try a different USB cable (must support data)
  2. Install ESP32 USB drivers (CP210x or CH340)
  3. Hold BOOT button while programming
  4. Select correct board in Arduino IDE (ESP32 Dev Module)
  5. Try different USB port on computer

​
Power consumption

Understanding power consumption helps ensure reliable operation:
ComponentCurrent Draw
ESP32 (active, WiFi on)~160-260mA
ESP32 (idle, WiFi on)~80-120mA
SSD1306 OLED display~20mA
WS2812B LEDs (20, full white)~1200mA
WS2812B LEDs (20, limited)~500mA (firmware limit)
Total (typical)~700mA
Total (maximum)~1500mA
The firmware configures FastLED to limit power consumption:
FastLED.setMaxPowerInVoltsAndMilliamps(5, 500);
This prevents overdrawing current from USB ports, which are typically limited to 500mA.

​
Next steps

With your MacroBoard assembled, you’re ready to program it:

Software setup

Install the Arduino IDE and upload the firmware

Configuration

Configure WiFi credentials and API settings

​
Additional resources

Component list

Review required components and specifications

PCB design

Learn about the PCB design and files

Build docs developers (and LLMs) love

Get started for freeTalk to us