Add install.sh, setup.sh, and update README

install.sh: install ESP-IDF v5.2 + ESP-ADF v2.7, detect existing env, write .env file with IDF_PATH/ADF_PATH setup.sh: prompt for WiFi creds, write sdkconfig.defaults, build, optionally flash and prepare SD card README: rewrite to reflect current architecture (NFC URL streaming, web UI, no arduino-esp32), add roadmap and quick start https://claude.ai/code/session_01MhAnh68DPNnTjcKqjNYDmk
2026-10-28 06:52:57 +01:00 · 2026-06-13 07:10:28 +00:00
1 parent afbc0e5e23
commit 76b02b840c
@@ -1,76 +1,124 @@
 # Kidsbox

-This is a battery-powered rfid-tag-controlled audio player meant to be used by kids.
-You can bundle audio-files to rfid tags and let your kids choose the music or audiobook of their favour by placing the corresponding tag atop of the box.
+A battery-powered, RFID/NFC-tag-controlled audio player for kids.
+Place an NFC tag on the box — the mapped audio file or stream plays automatically.
+Tags are programmed from a smartphone using any NFC writing app (e.g. NFC Tools).
+The box streams from the URL written to the tag, caches it locally for offline play,
+and exposes a web interface for playback control and storage management.

 |Front|Side|
 |-|-|
 |![Frontal View](docs/img/front.jpeg)|![Side View](docs/img/side.jpeg)|

-## Todo
+---

- Volume buttons
- Playlists
- Pausing
- ... I have a lot of ideas :)
+## Quick Start

-## Setup
+### 1. Install the development environment

-1. Install ESP-ADF and ESP-IDF according to the [install guide](https://docs.espressif.com/projects/esp-adf/en/latest/get-started/index.html#installation-step-by-step).
-2. Clone this repository and `cd` into the repository directory.
-3. `git submodule init --recursive`
-3. `cd device`
-4. Make sure that you have `idf.py` available in your environment. This is described in the install guide.
-5. Execute `idf.py build` to compile, `idf.py build flash monitor` to flash it to your board.
+```bash
+./install.sh
+```
+
+This installs **ESP-IDF v5.2** and **ESP-ADF v2.7** into `~/esp/` and writes a `.env` file.
+Existing installations are detected automatically (via `$IDF_PATH` / `$ADF_PATH`).
+
+### 2. Configure and build
+
+```bash
+source .env && source $IDF_PATH/export.sh
+./setup.sh
+```
+
+`setup.sh` will:
+- Prompt for your WiFi SSID and password
+- Build the firmware (`idf.py build`)
+- Optionally flash to the device
+- Optionally prepare an SD card (create directories, copy web UI)
+
+---
+
+## How It Works
+
+1. Write an audio URL to an NFC tag with a smartphone app (e.g. **NFC Tools**).
+2. Place the tag on the box → the box reads the URL, streams the audio, and caches it.
+3. Subsequent plays of the same tag use the local cache (no internet needed).
+4. Removing the tag pauses playback; replacing it resumes.
+
+Without an NDEF URL on a tag, the box falls back to a local mapping file at
+`/sdcard/internal/<tag-id>` (plain text, one URL or file path per file).
+
+---
+
+## Web Interface
+
+Once connected to WiFi, open `http://<device-ip>` in a browser.
+
+| Section | What it does |
+|---|---|
+| Now Playing | Track URI, play/pause/stop, volume slider |
+| Device Info | IP address, playback status, cache size, free heap |
+| Storage | List and delete cached files |
+| Bluetooth | Toggle BT speaker mode (stub — in progress) |
+
+---

 ## Hardware

 ### Parts

-_TBD_
+| Part | Links |
+|---|---|
+| ESP32-LyraT 4.3 | [Mouser](https://www.mouser.de/ProductDetail/Espressif-Systems/ESP32-LyraT?qs=MLItCLRbWsxPzPCja546ZA%3D%3D) |
+| RC522 RFID/NFC module | — |
+| SD card (FAT32, any size) | — |

-|Part|Links|
-|-|-|
-|ESP32-LyraT 4.3|[Mouser](https://www.mouser.de/ProductDetail/Espressif-Systems/ESP32-LyraT?qs=MLItCLRbWsxPzPCja546ZA%3D%3D)|
+### DIP-Switch (LyraT 4.3)

+| Switch | Position | Purpose |
+|---|---|---|
+| 1 | OFF | Disconnects GPIO 12 from SD-D2 |
+| 2 | OFF | Disconnects GPIO 13 from SD-D3 |
+| 3 | OFF | Connects GPIO 15 to SD CMD |
+| 4 | ON | Connects GPIO 13 to JTAG header |
+| 5 | ON | Connects GPIO 12 to JTAG header |
+| 6 | OFF | Connects GPIO 13 to SD CLK |
+| 7 | OFF | Disconnects GPIO 12 from AUX-in detection |
+| 8 | OFF | — |

-### Hardware Setup
+### RC522 Wiring

-The peripherals must be configured for:
+> MISO/MOSI pin names are **not** inverted between host and chip on this board.

- SD Card
- RFID-module
- Vol+/- buttons 
+| RC522 Pin | LyraT v4.3 Pin | GPIO |
+|---|---|---|
+| 3.3V | 3.3V | — |
+| RST | 3.3V | — |
+| GND | GND | — |
+| SDA | I2C SDA | 18 |
+| SCK | I2C SCL | 23 |
+| MOSI | JTAG MTCK | 13 |
+| MISO | JTAG MTDI | 12 |

-The ESP32-LyraT board has only a few exposed GPIO pins. To save pins, the SD-Card reader runs only in 1-Wire mode. I have actually no idea what the limitations and differences are, but I didn't encounter any problems yet.
+### SD Card Layout

-#### DIP-Switch
+```
+/sdcard/
+  www/          ← web interface files (copied by setup.sh)
+  internal/     ← tag-id → URL/path mapping files (manual)
+  cache/        ← downloaded audio files (managed automatically)
+```

-The switches must be exatly in the positions outlined in the table.
+---

-|Number|Setting|Purpose|
-|-|-|-|
-|1|OFF|Disconnects GPIO 12 from SD-D2|
-|2|OFF|Disconnects GPIO 13 from SD-D3|
-|3|OFF|Connects GPIO 15 to SD CMD|
-|4|ON|Connects GPIO 13 to the JTAG header|
-|5|ON|Connects GPIO 12 to the JTAG header|
-|6|OFF|Connects GPIO 13 to SD CLK|
-|7|OFF|Disconnects GPIO 12 from the AUX-in-detection|
-|8|OFF| - |
+## Roadmap

-#### RFID
-
-_The MISO/MOSI pins are not inverted on host/chip_
-
-Connection Table:
-
-|RC522 Pin|ESP32 Lyrat v4.3 Pin|GPIO Number|
-|-|-|-|
-|3.3v|3.3v|-|
-|RST|3.3v|-|
-|GND|GND|-|
-|SDA|I2C SDA|18|
-|SCK|I2C SCL|23|
-|MOSI|JTAG MTCK|13|
-|MISO|JTAG MTDI|12|
+- [x] RFID/NFC tag detection
+- [x] NDEF URL reading from NFC tags
+- [x] HTTP audio streaming
+- [x] Local file cache
+- [x] WiFi (native ESP-IDF, no Arduino dependency)
+- [x] Web interface — playback controls, storage, device info
+- [ ] Volume buttons (hardware)
+- [ ] Playlists
+- [ ] Bluetooth speaker mode (A2DP sink)