Components & wiring
The Studio build adds a 320×240 colour TFT, an I²S speaker for audio cues, and a rotary encoder for volume. Base ESP32 + PN532 + NeoPixel ring is unchanged from the Classic.
jb-tft-v1). These instructions apply to this hardware variant only — other Jellybox SKUs use different displays, pinouts, and peripherals.Bill of materials
All components are available on Amazon, AliExpress, or Adafruit.
| Component | Notes | Qty |
|---|---|---|
| ESP32 dev board | Any 38-pin ESP32 DevKit. BOOT button (GPIO0) used for factory reset. | 1 |
| PN532 NFC/RFID module | I²C mode. Same as the Classic. | 1 |
| 2.4" ST7789 colour TFT (320×240, SPI) | Bare 8-pin module without a touch controller. Verify the pin order against your breakout — vendors vary. BLK/LED stays tied to 3.3 V; no GPIO backlight control in firmware. | 1 |
| MAX98357A I²S amplifier breakout | Adafruit #3006, AZ-Delivery, or any equivalent 5-pin breakout. Leave GAIN and SD floating for default 9 dB always-on operation. | 1 |
| Speaker — 4 Ω or 8 Ω, ≥ 1 W | Two leads into the speaker terminal on the PCB. The board routes them back to the amp's SPK+/SPK− pads — no flying wires. Pick something small enough to fit your enclosure. | 1 |
| KY-040 rotary encoder | 5-pin breakout with onboard pull-ups. ESP32 input-only pins (34/35/39) are used so no external resistors are required. | 1 |
| NeoPixel 16-LED ring (WS2812B) | Same as the Classic. | 1 |
| LiPo battery + TP4056 charger board | Same as the Classic — 1000–2000 mAh single-cell LiPo through a TP4056. | 1 |
| SPDT power switch | In line between TP4056 output and ESP32 VIN. | 1 |
| RFID/NFC tags (NTAG213 or NTAG215) | Same as the Classic. | 10+ |
Custom PCB
Skip the breadboard — a drop-in PCB that routes every connection above onto a single board.
Want to fabricate your own? The Download gerbers button above gives you the manufacturing files as a single ZIP. Upload it directly to a fab house like JLCPCB, PCBWay, or OSH Park.
Board dimensions & mounting holes
For anyone designing their own enclosure or 3D-printed shell around the PCB.
The Studio PCB carries the same ESP32, PN532, NeoPixel and charger headers as the Classic plus two extra connectors (I²S amp + rotary encoder) and an 8-pin TFT header in place of the eInk one. Exact dimensions and mounting-hole positions are taken from the current KiCad layout — update this entry once the board is finalised.
For the full, dimensioned reference — including every via and component hole — see the drill map:
jb-tft-v1) build only — other Jellybox SKUs use different displays and peripherals and will need their own boards.No PCB? See the hand-wired pinout below.
Wiring
All components run on 3.3 V logic and are directly compatible with the ESP32. The NeoPixel ring can be powered from 5 V for full brightness, or 3.3 V for dimmer but safer operation.
PN532 NFC reader (I²C)
IRQ and RST are not used by the firmware yet — leave those pins on the PN532 disconnected.
| Component pin | ESP32 pin | Notes |
|---|---|---|
| VCC | 3.3V | 3.3 V only — do not use 5 V |
| GND | GND | |
| SDA | GPIO 21 | I²C data — add 4.7 kΩ pull-up to 3.3 V if signal is unstable |
| SCL | GPIO 22 | I²C clock |
2.4″ ST7789 colour TFT (SPI)
Reuses the same SPI bus (MOSI=23, SCK=18) and chip-select / data-command / reset pins as the Classic eInk. BUSY (GPIO 4) is unused — the BLK / LED backlight pin sits on 3.3 V instead.
| Component pin | ESP32 pin | Notes |
|---|---|---|
| GND | GND | |
| VCC | 3.3V | Module accepts 3.3 V or 5 V — 3.3 V is plenty. |
| SCL (SCK) | GPIO 18 | SPI clock — shared VSPI bus |
| SDA (MOSI) | GPIO 23 | SPI MOSI — shared VSPI bus |
| RES (RST) | GPIO 16 | Reset |
| DC | GPIO 17 | Data / command select |
| CS | GPIO 5 | Chip select — active low |
| BLK / LED | 3.3V | Backlight always-on (no PWM control in firmware) |
NeoPixel 16-LED ring (WS2812B)
| Component pin | ESP32 pin | Notes |
|---|---|---|
| VCC / +5V | 5V (VIN) | Use 5 V from the ESP32 VIN pin for full brightness. 3.3 V also works at lower brightness. |
| GND | GND | |
| DIN | GPIO 27 | Data signal — a 300–500 Ω series resistor on this line is recommended to prevent ringing |
MAX98357A I²S amplifier
GAIN and SD inputs are left floating — default 9 dB gain, always-on. The amp's SPK+ / SPK− output pads are routed through the PCB straight to the speaker terminal, so no flying wires are needed at assembly — solder the amp module into its 7-pin header and the speaker into its 2-pin terminal.
| Component pin | ESP32 pin | Notes |
|---|---|---|
| VIN | 5V (VIN) | Run the amp off the 5 V rail (TP4056 output) — louder than 3.3 V. |
| GND | GND | |
| DIN | GPIO 32 | I²S data |
| BCLK | GPIO 14 | I²S bit clock |
| LRC | GPIO 33 | I²S left/right select (word clock) |
| SPK+ | Speaker terminal + | Routed on the PCB to the speaker connector — no wire needed |
| SPK− | Speaker terminal − | Routed on the PCB to the speaker connector — no wire needed |
Speaker terminal (2-pin)
The two pads on the PCB connect internally to the amp's SPK+/SPK− outputs. Polarity matters for stereo phasing but not for a single mono speaker — wire either way.
| Component pin | ESP32 pin | Notes |
|---|---|---|
| + | Amp SPK+ | PCB trace from the amp output |
| − | Amp SPK− | PCB trace from the amp output |
KY-040 rotary encoder
Encoder breakout has onboard pull-ups on CLK/DT, so the ESP32’s input-only pins (34/35/39) can be used without external resistors.
| Component pin | ESP32 pin | Notes |
|---|---|---|
| GND | GND | |
| + | 3.3V | |
| SW | GPIO 39 | Push-button — reserved; not used in v1 firmware |
| DT | GPIO 34 | Encoder data |
| CLK | GPIO 35 | Encoder clock |
Power
Jellybox is designed as a portable, battery-powered device — not a tethered USB gadget.
The assembly draws around 200–300 mA at 5 V when active (mostly the NeoPixel ring). A single-cell LiPo (1000–2000 mAh) wired through a TP4056 charger board gives a good balance of runtime and size, and lets you recharge over USB without removing the cell.
Battery wiring (TP4056 → ESP32)
Fit a power switch in line between the TP4056 output and the ESP32 so the device can be fully turned off when not in use.
| Component pin | ESP32 pin | Notes |
|---|---|---|
| LiPo + | TP4056 B+ | Battery positive into the charger board |
| LiPo − | TP4056 B− | Battery negative into the charger board |
| TP4056 OUT+ | Switch → ESP32 5V / VIN | Run the positive output through an SPDT switch, then into the ESP32 5 V rail |
| TP4056 OUT− | ESP32 GND | Common ground |
The firmware does not use the ESP32's deep-sleep mode yet, so the device stays active while switched on. Expect a few hours of runtime from a 2000 mAh cell — flip the switch off between uses to extend battery life.
Tag stickers
Credit-card-format NFC stickers are the easiest tag form factor — slim, cheap, and printable.
Jellybox is built around standard ISO 14443A tags, but the recommended form factor is a CR80 credit-card-sized PVC sticker (85.6 × 53.98 mm) with an embedded NTAG213 or NTAG215 chip. They're the same shape as a bank card, so they sit neatly in a wallet, a binder pocket, or a display rack next to the device — and the rigid white face takes printed artwork well.
The dashboard includes a built-in sticker sheet designer at Tags → Create sticker sheet. It:
- Pre-fills one sticker per registered RFID tag, pulling the poster or album artwork from the linked Jellyfin (or extension) item.
- Lays stickers out on A4 at exact CR80 dimensions, with cut marks and a safe-print border so they trim cleanly with a guillotine or scissors.
- Lets you tweak title text, swap artwork, choose landscape or portrait, and set text colour per card before printing.
Look for “NTAG213 PVC card” or “NTAG215 NFC card” on Amazon or AliExpress, sold in packs of 10–50. NTAG215 has more user memory (504 bytes) but Jellybox only stores the UID, so NTAG213 (144 bytes) is plenty.
Hardware assembled? Flash the firmware →