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

# PCB design

> Detailed information about the Spotify MacroBoard PCB design, specifications, and manufacturing files

The Spotify MacroBoard uses a custom PCB to connect all components together. This page provides detailed information about the PCB design, how to order it, and technical specifications.

## PCB files

All PCB design files are included in the source repository under the `PCB/` directory.

### Available files

<Accordion title="Design files">
  **SpotifyMacroBoardDesign.json**

  The complete PCB design file in JSON format. This file can be imported into compatible PCB design software for viewing or modification.

  Location: `PCB/SpotifyMacroBoardDesign.json`
</Accordion>

<Accordion title="Schematic files">
  **Schematic.json and Schematic.png**

  The circuit schematic shows how all components are connected electrically. Available in both JSON format (for editing) and PNG format (for viewing).

  * View: `PCB/Schematic.png`
  * Edit: `PCB/Schematic.json`

  The schematic includes:

  * ESP32 pin assignments
  * OLED display I2C connections (SDA/SCL)
  * WS2812B LED data line connection
  * 7 switch connections with pull-up resistors
  * Power distribution network
</Accordion>

<Accordion title="Manufacturing files (Gerber)">
  **Gerber.zip**

  Production-ready Gerber files for PCB manufacturing. This ZIP file contains all the layers needed to fabricate the PCB.

  Location: `PCB/Gerber.zip`

  The Gerber file package includes:

  * Top copper layer
  * Bottom copper layer
  * Top silkscreen
  * Bottom silkscreen
  * Top soldermask
  * Bottom soldermask
  * Drill file
  * Board outline
</Accordion>

<Accordion title="PCB preview">
  **PCBDesign.png**

  A rendered preview image of the PCB layout showing component placement and routing.

  Location: `PCB/PCBDesign.png`
</Accordion>

## PCB specifications

When ordering the PCB, use these specifications:

### Physical specifications

| Parameter | Specification |
| - | - |
| Layers | 2-layer board (recommended) |
| Material | FR-4 |
| Thickness | 1.6mm (standard) |
| Finish | HASL, ENIG, or LeadFree HASL |
| Copper weight | 1 oz (35µm) |
| Minimum trace width | Check design files |
| Minimum drill size | Check design files |

### Design specifications

| Parameter | Value |
| - | - |
| GPIO pins used | 12 (pins 4, 5, 12, 13, 14, 18, 19, 21, 25, 26) |
| I2C bus | SDA (GPIO 21), SCL (GPIO 19) |
| LED data pin | GPIO 18 |
| Switch pins | GPIO 4, 5, 12, 13, 14, 25, 26 |
| I2C speed | 400 kHz (Fast Mode) |
| Pull-up resistors | Internal pull-ups enabled on all switch pins |

## Pin connections

The PCB routes the following connections:

<Tabs>
  <Tab title="ESP32 connections">
    **Power:**

    * 5V input from USB
    * 3.3V regulation (if not using board's built-in regulator)
    * Ground plane

    **Digital pins:**

    * GPIO 4: Shuffle button
    * GPIO 5: Volume down button
    * GPIO 12: Volume up button
    * GPIO 13: Loop/Repeat button
    * GPIO 14: Previous track button
    * GPIO 18: WS2812B LED data + LED indicator
    * GPIO 19: I2C SCL (OLED display)
    * GPIO 21: I2C SDA (OLED display)
    * GPIO 25: Play/Pause button
    * GPIO 26: Next track button
  </Tab>

  <Tab title="OLED display">
    **I2C connection:**

    * VCC: 3.3V or 5V (depending on display module)
    * GND: Ground
    * SDA: GPIO 21
    * SCL: GPIO 19

    **I2C address:** 0x3C

    <Note>
      The I2C bus operates at 400 kHz (Fast Mode) as configured in the firmware:

      ```cpp theme={null}
      I2C.begin(SDA, SCL, 400000);
      ```
    </Note>
  </Tab>

  <Tab title="LED strip">
    **WS2812B connection:**

    * VCC: 5V (direct from power supply)
    * GND: Ground
    * DIN: GPIO 18

    **Configuration:**

    * Number of LEDs: 20
    * Chipset: WS2812B
    * Color order: GRB
    * Brightness: 230/255
    * Max power: 5V @ 500mA

    <Warning>
      Ensure the power supply can provide sufficient current for 20 LEDs. The firmware limits power to 500mA, but use a supply rated for at least 1A total.
    </Warning>
  </Tab>

  <Tab title="Switches">
    **Button connections:**

    Each switch connects between its GPIO pin and ground:

    * Switch 1 (Shuffle): GPIO 4 ↔ GND
    * Switch 2 (Vol -): GPIO 5 ↔ GND
    * Switch 3 (Vol +): GPIO 12 ↔ GND
    * Switch 4 (Loop): GPIO 13 ↔ GND
    * Switch 5 (Previous): GPIO 14 ↔ GND
    * Switch 6 (Play/Pause): GPIO 25 ↔ GND
    * Switch 7 (Next): GPIO 26 ↔ GND

    All pins use internal pull-up resistors (configured via `INPUT_PULLUP`), so no external resistors are required.
  </Tab>
</Tabs>

## Ordering the PCB

You can order the PCB from any PCB manufacturer using the provided Gerber files.

<Steps>
  <Step title="Download the Gerber files">
    Download `Gerber.zip` from the `PCB/` directory in the repository.

    <Info>
      Do not unzip the file. Most PCB manufacturers accept the ZIP file directly.
    </Info>
  </Step>

  <Step title="Choose a PCB manufacturer">
    Popular PCB manufacturers that accept Gerber files:

    * JLCPCB (jlcpcb.com)
    * PCBWay (pcbway.com)
    * OSH Park (oshpark.com)
    * ALLPCB (allpcb.com)
    * Seeed Studio (seeedstudio.com)

    Most manufacturers offer very affordable prices for small quantities (often under \$5 for 5 boards).
  </Step>

  <Step title="Upload Gerber files">
    On the manufacturer's website:

    1. Create an account or log in
    2. Click "Quote Now" or "Instant Quote"
    3. Upload the `Gerber.zip` file
    4. Wait for the files to be analyzed
  </Step>

  <Step title="Configure PCB options">
    Select the following options (or use defaults):

    * **Layers:** 2
    * **Thickness:** 1.6mm
    * **Color:** Your choice (green is cheapest)
    * **Surface finish:** HASL (cheapest) or ENIG (better)
    * **Copper weight:** 1 oz
    * **Quantity:** 5 minimum (most manufacturers)

    <Note>
      The dimensions and other technical specs will be automatically detected from the Gerber files.
    </Note>
  </Step>

  <Step title="Review and order">
    1. Review the PCB preview (most sites show a 3D render)
    2. Verify the dimensions and hole placements
    3. Add to cart and complete checkout
    4. Wait for manufacturing (typically 1-2 weeks including shipping)
  </Step>
</Steps>

## PCB modifications

If you want to modify the PCB design:

### Importing design files

The `SpotifyMacroBoardDesign.json` and `Schematic.json` files can be imported into compatible EDA (Electronic Design Automation) software.

<Warning>
  Before modifying the PCB, ensure you understand the circuit design and have experience with PCB layout. Incorrect modifications can result in a non-functional board.
</Warning>

### Common modifications

<Accordion title="Adding more switches">
  To add additional switches:

  1. Choose available GPIO pins on the ESP32
  2. Add new switch footprints to the PCB
  3. Route traces from the GPIO pin to one switch terminal
  4. Connect the other terminal to ground
  5. Update the firmware to handle additional switches

  Available GPIO pins (not currently used): 2, 15, 16, 17, 22, 23, 27, 32, 33
</Accordion>

<Accordion title="Using fewer LEDs">
  The firmware is configured for 20 LEDs, but you can use fewer:

  1. Modify the PCB to include fewer LED positions
  2. Update the firmware constant:
     ```cpp theme={null}
     #define RGB_LED_NUM 20  // Change to your number
     ```
  3. Ensure proper power calculations (fewer LEDs = less current)
</Accordion>

<Accordion title="Different display size">
  To use a different OLED display:

  1. Check if it uses I2C with the same address (0x3C)
  2. Ensure it's compatible with the SSD1306 driver
  3. Update the firmware screen dimensions:
     ```cpp theme={null}
     #define SCREEN_WIDTH 128
     #define SCREEN_HEIGHT 64
     ```
  4. Adjust the display layout code if necessary
</Accordion>

## Design considerations

### Power distribution

The PCB includes power distribution for:

* 5V rail for ESP32 and LED strip
* 3.3V rail for OLED display (if required)
* Separate ground plane for noise reduction

### Signal integrity

* I2C traces (SDA/SCL) should be kept as short as possible
* LED data line should have a direct path to minimize signal degradation
* Ground plane provides return path for all signals

### Mechanical design

* Switch spacing compatible with standard keyboard layouts
* Mounting holes for case attachment (if using enclosure)
* Component placement optimized for hand assembly

## Testing the PCB

After receiving your PCB, test it before assembly:

<Steps>
  <Step title="Visual inspection">
    * Check for manufacturing defects
    * Verify all traces are intact
    * Ensure holes are properly drilled
    * Look for shorts or breaks
  </Step>

  <Step title="Continuity testing">
    Use a multimeter to verify:

    * Ground connections are continuous
    * No shorts between power rails
    * Switch pad connections
    * Trace continuity between pads
  </Step>

  <Step title="Power testing">
    Before soldering components:

    * Test 5V and 3.3V rails with a power supply
    * Verify no excessive current draw
    * Check for shorts or unexpected connections
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Component list" icon="list-check" href="/hardware/components">
    Review all required components before assembly
  </Card>

  <Card title="Assembly guide" icon="screwdriver-wrench" href="/hardware/assembly">
    Follow step-by-step assembly instructions
  </Card>
</CardGroup>