oster
/
hannabox
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
hannabox/USER_MANUAL.md

11 KiB
Raw Permalink Blame History

HannaBox – User Manual

HannaBox is a child‑friendly music player powered by an ESP32. It plays audio files from a microSD card and can start playlists by tapping an RFID figurine. It has three robust buttons for everyday use and an optional web app for managing music and tags over Wi‑Fi.

This guide explains how to set it up, use it daily, map figurines, and troubleshoot common issues.

What you need

  • HannaBox device (with speaker and RFID reader)
  • microSD card (FAT32, 8–32 GB recommended)
  • Power source (USB power supply or internal battery charged)
  • Optional: Home Wi‑Fi (for the web app)
  • Optional: RFID figurines/cards (13.56 MHz)

Safety: Keep volume at safe levels for children. Supervise charging. Avoid liquids and drops.

Quick start (first‑time setup)

  1. Prepare the SD card (FAT32)
  • Format your microSD card as FAT32 on your computer.
  1. Create required folders and copy files
  • On the SD card, create a folder named system.
  • Copy the web files from this project into that folder:
    • web/index.html → system/index.html
    • web/style.css → system/style.css
    • web/script.js → system/script.js
  • Copy the optional system sounds:
    • sounds/start.mp3 → system/start.mp3 (plays after successful startup)
    • sounds/sleep.mp3 → system/sleep.mp3 (plays before going to sleep)

Resulting SD layout (example):

SD Card Root/
├── system/
│   ├── index.html
│   ├── style.css
│   ├── script.js
│   ├── start.mp3
│   └── sleep.mp3
├── Music/                (your folders – optional names)
│   ├── AlbumA/
│   │   ├── 01.mp3
│   │   └── 02.mp3
│   └── AlbumB/
│       └── story.mp3
└── loose_song.mp3
  1. Insert the SD card and power on the HannaBox
  • On first start, the device initializes the SD card and loads defaults.
  • You’ll hear start.mp3 if present.
  1. Connect to Wi‑Fi (optional, for the web app)
  • If the HannaBox isn’t already on your Wi‑Fi, it opens a temporary hotspot named “HannaBox”.
  • Connect your phone or laptop to the “HannaBox” Wi‑Fi and follow the captive portal to select your home network and enter its password.
  • After it connects, note the device’s IP address (shown in the portal or in your router’s device list).

Tip: The HannaBox works without Wi‑Fi for basic playback and figurines. Wi‑Fi is only needed for the web app (playlist view, uploads, tag mapping from a browser).

Daily use

The three buttons

  • Start/Stop (Play/Pause)
    • Short press: Toggle play/pause.
    • Hold to adjust volume with the other buttons (see below).
  • Next
    • Short press while playing: Skip to the next track.
    • If stopped: increases volume by one step and plays the start sound as feedback.
    • While holding Start/Stop: increases volume (no feedback sound).
  • Previous
    • Short press while playing: Go to the previous track. If the current track played for more than ~2 seconds, it restarts the current track first.
    • If stopped: decreases volume by one step and plays the start sound as feedback.
    • While holding Start/Stop: decreases volume (no feedback sound).

Volume range is 0–15 by default (configurable). Changes made with buttons and the web app are kept in sync.

Using RFID figurines

  • Put a figurine on top
  • If the figurine has a mapping, the associated song or folder will play according to its mode (see “Mapping figurines” below).
  • If nothing happens, the figurine may not be mapped yet. Use the web app’s Manager to map it (see next section).

Auto‑sleep and resume

  • After inactivity (defaults to 30 minutes), HannaBox plays system/sleep.mp3 and then goes into deep sleep to save battery.
  • Press Start/Stop to wake it.
  • By default it resumes the last track and position where you left off (can be changed in config).

Battery behavior

  • The device monitors battery voltage. If it’s too low, it will prepare to sleep and then go to deep sleep to protect the battery. Charge before use.

The web app (local control & management)

Requirements: The HannaBox must be connected to your Wi‑Fi. Open a browser to the HannaBox’s IP address (e.g., http://192.168.x.x). The page and styling are served from the SD card’s system folder.

Main areas:

  • Player card: Big Play/Pause, Next, Previous, current title, time bar, and a volume slider.
  • Playlist: A clickable list of your folders and songs. Click any entry to start it.
  • Manager (toggle button): Tools for uploads, file management, and RFID mapping.

What you can do:

  • See what’s playing and control playback (Play/Pause/Next/Previous).
  • Seek within a track using the time slider.
  • Adjust volume (0–15) with the volume slider.
  • Browse and click items in the playlist to play them.
  • Toggle Manager for advanced actions.

Manager features:

  • Status indicators: Shows battery voltage (mV), last scanned NFC ID, and free memory (for info).
  • Upload audio: Upload .mp3 (up to ~50 MB). If a file with the same name exists, the box will automatically choose a new name. Ensure your SD card has free space.
  • Move/Rename files and Delete files.
  • Refresh playlist view.

Mapping figurines (RFID → what to play)

Option A: Map through the web app (recommended)

  1. Tap the figurine near the reader.
  2. Open the web app and toggle Manager.
  3. Copy “Last NFC ID” into the RFID field (it will autofill after tapping).
  4. In “Song”, enter:
    • A file name (e.g., story.mp3), or
    • A folder name (e.g., AlbumA), or
    • A full path (e.g., /Music/AlbumB/story.mp3) Tip: Using a folder name makes mappings more robust if you later move files.
  5. Choose Mode:
    • Single (s): Play just the selected song/file once.
    • Folder (f): Play all files in the selected folder once, then stop.
    • Random (r): Play all files in the selected folder in random order once, then stop.
    • Continuous (c): Loop through the selected folder continuously.
  6. Click “Update Mapping”.

Option B: Edit the mapping file on SD (advanced)

  • File: /system/mapping.txt
  • Lines look like: UID=target|mode Example: 12 34 56 78=AlbumA|f 90 87 65 43=/Music/AlbumB/story.mp3|s

Notes:

  • UID format is four bytes separated by spaces (copied from the web app’s “Last NFC ID”).
  • If you map to a folder, the player will progress inside that folder. With mode c it loops; with f it stops at the end.

Supported audio and playlist rules

  • The on‑device playlist is built from the SD card content (alphabetical).
  • The web app’s Playlist panel lets you click directories and files to play them.
  • Keep the system folder named exactly system. Do not put your music inside system.

Configuration (optional, for adults)

A configuration file is created automatically on first run:

  • Location: /system/config.txt
  • Format: key=value (with comments)

Common options:

  • initialVolume (0–21): Startup volume (UI uses 0–15 by default).
  • maxVolume (1–21): Maximum volume limit for buttons/web app.
  • sleepDelay (milliseconds): No‑interaction time before deep sleep (default 1800000 = 30 min).
  • sleepMessageDelay (milliseconds): When to play system/sleep.mp3 before sleep (default ~2 s earlier).
  • minVoltage (mV): Battery level that triggers a sleep to protect the battery (default 3200).
  • voltage100Percent (mV): Approximate voltage representing 100% (default 4200).
  • rfidLoopInterval (ms): How often to check the reader (default 25).
  • startAtStoredProgress (true/false): Resume from last position after wake/restart.
  • wifiSSID / wifiPassword: Usually left empty; Wi‑Fi setup is handled by the on‑device “HannaBox” hotspot.

Edit config.txt on your computer if needed (with the HannaBox powered off) or let the defaults work.

Power, sleep, and waking

  • Auto‑sleep: After the sleepDelay with no interaction, the box plays system/sleep.mp3 and then sleeps.
  • Waking: Press the Start/Stop button to wake.
  • On wake: You’ll hear system/start.mp3 (if present). If resume is enabled, playback continues where it stopped.

Troubleshooting

No sound

  • Turn volume up: hold Start/Stop and press Next, or use the web app slider.
  • Try playing a known good .mp3 file from the Playlist.
  • Ensure speaker is connected and the device is powered.
  • Confirm system/start.mp3 loads on startup (audible chime).

Web app looks unstyled or shows errors for style/script

  • Ensure the SD card has:
    • /system/index.html
    • /system/style.css
    • /system/script.js
  • Copy the files from this project’s web/ folder to the SD system/ folder (exact names, case sensitive).
  • Refresh the page.

Can’t find the device’s web page

  • Make sure you connected the HannaBox to your home Wi‑Fi using the “HannaBox” hotspot/captive portal.
  • Check your router’s device list for the IP address and enter it in the browser (e.g., http://192.168.0.25).
  • Reboot the HannaBox to retrigger the hotspot if it cannot connect to a remembered Wi‑Fi.

Figurine doesn’t start music

  • Tap the figurine again and hold it briefly over the reader.
  • In the web app (Manager), check “Last NFC ID”, then create or update a mapping.
  • Ensure the target song or folder actually exists on the SD card.

SD card not detected / empty playlist

  • SD card must be FAT32 and properly inserted.
  • Use the required system/ folder and keep music outside system/.
  • Power‑cycle the HannaBox after changing SD content.

Device sleeps too quickly

  • Battery may be low; charge it.
  • Increase sleepDelay in /system/config.txt if desired.

Resume didn’t work after wake

  • Ensure startAtStoredProgress=true in /system/config.txt.
  • The device writes /system/progress.txt just before sleep; verify the SD card isn’t full.

Uploads fail or are slow

  • Ensure there’s at least ~10 MB free on the SD card before uploading.
  • Keep individual uploads ≤ about 50 MB.
  • Supported upload types: .mp3

Tips

  • Use folder targets for figurines you want to “play this collection” (e.g., AlbumA with Folder mode).
  • Use Continuous mode for “bedtime loop” folders.
  • Keep file and folder names simple (letters, numbers, underscores) to make mapping easier.
  • Back up your SD card content occasionally.

Enjoy the HannaBox! If you ever need to rebuild the SD card layout, follow the “Quick start” steps above and remember to copy the three web files (index.html, style.css, script.js) into the system folder so the web app looks and works correctly.