Loading 3D model… large boards can take a moment.
zBox is an offline-first ESP32 NFC audio box: tap a card to play an MP3 from microSD, use four physical buttons for playback and modes, and manage music and mappings from a small FastAPI web portal. Wi-Fi is needed only for provisioning, synchronization, and maintenance.
[!CAUTION] The manufactured PCB and Gerbers are legacy v2.0 (April 2026). They predate the current schematic's July load-switch changes and are not a turnkey version of that schematic. A build from these Gerbers needs manual off-board wiring; read Hardware status before ordering boards.
See the complete BOM for values, footprints, quantities, and revision notes.
git clone --recursive https://github.com/dkej123/zBox.git
cd zBox
If you already cloned without submodules, run git submodule update --init --recursive.
Print the STL enclosure parts and follow the . Wire the modules using the , accounting for the . Check polarity and shorts before power-up.
Format a microSD card as FAT32, insert it into the Lolin D32 Pro, connect USB, then run:
cd esp32
pio run -e lolin_d32_pro -t upload
cd ..
There is no compile-time server address. The device exposes its own sync service over Wi-Fi.
docker compose up -d --build
curl http://localhost:8000/api/health
Open http://<server-host>:8000. The optional ZBOX_IP environment value is only a fallback;
the preferred setup is saving the device address in the portal.
Hold buttons A+B for about two seconds to enter Sync Mode. On first use, join the
zBox-Sync Wi-Fi network from a phone or laptop and complete its captive portal with the
credentials for the same network as the server. Note the device IP shown by your router or
serial monitor.
In the admin portal:
zbox.local, and save it.When sync finishes, hold A+B to return to normal operation. Present the registered card;
playback should start locally from microSD through the NS4168 speaker.
| Input | Action |
|---|---|
A or B, click | Play/pause |
A, double-click | Previous track |
B, double-click | Next track |
A, hold ~2 s | Toggle optional Bluetooth output |
B, hold ~2 s | Toggle NFC Card/Music playback mode |
C / D, click | Volume down / up |
C, hold ~2 s | Show battery level |
D, hold ~1 s | Enter deep sleep |
A+B, hold ~2 s | Enter or leave Sync Mode |
Sleeping: hold D ≥400 ms | Wake normally |
Sleeping: hold C+D ≥400 ms | Wake into night-light mode |
The device currently powers down with ESP32 deep sleep. The proposed zero-standby-current soft latch and mechanical travel switch are design work only; they have not been built or bench-validated. See Hardware status.
| Path | Contents |
|---|---|
esp32/ | PlatformIO firmware and native tests |
server/ / web/ | FastAPI server and browser admin |
hardware/pcb/kicad/ | Current schematic plus legacy v2.0 PCB layout |
hardware/pcb/gerbers/ | Legacy v2.0 manufacturing outputs |
hardware/stl/ | Printable enclosure parts |
hardware/cad/fusion360/step/ | Editable mechanical STEP export |
karty.pdf and cards_images/ are optional printable card assets. The project
owner holds the rights needed to publish the owner-created card graphics and other media here.
The MIT license covers the repository's code, hardware design files, documentation, and owner-created media unless a file states otherwise. Third-party submodules and dependencies retain their own licenses. This is a DIY design: independently review electrical and battery safety before manufacturing or giving a completed device to a child.
No comments yet. Be the first to ask about this board.