Documentation
Guides pour construire et utiliser votre Music Box
Guides détaillés
Suivez le chemin, étape par étape
Des tutoriels clairs et illustrés pour vous accompagner tout au long du projet.
- Guide de démarrage rapide
Tout ce qu'il faut savoir pour commencer votre projet en 30 minutes.
Temps estimé : 30 min
- Liste des composants
La liste complète des pièces à acheter avec les liens et références.
Temps estimé : 5 min
- Impression 3D
Guide pour imprimer le boîtier : paramètres, matériaux et astuces.
Temps estimé : 10 min
- Installation du logiciel
Comment flasher la carte SD et configurer le système.
Temps estimé : 20 min
- Assemblage
Guide illustré pas-à-pas pour assembler tous les composants.
Temps estimé : 1 heure
- Configuration initiale
Connecter l'application mobile et ajouter votre première musique.
Temps estimé : 15 min
- Utilisation quotidienne
Comment gérer les playlists, associer des cartes NFC et entretenir le système.
Temps estimé : 10 min
- Dépannage
Solutions aux problèmes courants et FAQ.
Temps estimé : 5 min
Guide de démarrage rapide
Voici un aperçu des étapes principales. La documentation complète sera disponible prochainement.
1. Préparer le matériel
Commandez tous les composants nécessaires (voir la liste complète ci-dessous). Pendant ce temps, téléchargez et imprimez le boîtier 3D.
2. Flasher la carte SD
Utilisez Raspberry Pi Imager pour flasher l'image système sur votre carte microSD. L'image contient tout le logiciel pré-configuré.
3. Assembler le boîtier
Placez le Raspberry Pi, le lecteur NFC et les boutons dans le boîtier imprimé. Connectez tous les câbles selon le schéma fourni.
4. Première configuration
Branchez votre Music Box, téléchargez l'application mobile et connectez-vous au même réseau Wi-Fi. L'application détectera automatiquement votre Music Box.
5. Ajouter de la musique
Depuis l'application, uploadez vos fichiers audio, créez vos premières playlists et associez-les à des cartes NFC.
6. Profiter ! 🎉
Votre Music Box est prête ! Donnez les cartes à vos enfants et regardez-les découvrir la magie de l'interaction physique.
Liste des composants
Voici tous les composants dont vous aurez besoin, avec des estimations de prix et des liens de référence.
Raspberry Pi 4 Model B (4GB RAM)
Le cerveau de votre Music Box. La version 4GB est recommandée.
Où acheter : Kubii, Raspberry Pi Official, Amazon
Module NFC RC522 RFID
Le lecteur qui détecte les cartes NFC. Compatible 13.56MHz.
Où acheter : Amazon, AliExpress, eBay
Carte microSD 32GB (Classe 10)
Pour installer le système d'exploitation et stocker la musique.
Marques recommandées : SanDisk, Samsung
Alimentation USB-C 5V 3A
Pour alimenter le Raspberry Pi 4 de manière stable.
Utilisez l'alimentation officielle Raspberry Pi si possible
Haut-parleur (USB ou Bluetooth)
N'importe quel haut-parleur USB ou Bluetooth fera l'affaire.
Alternative : utiliser la sortie jack 3.5mm avec des enceintes classiques
Cartes NFC NTAG215 (pack de 10)
Pour associer à vos playlists. Les stickers fonctionnent aussi !
Assurez-vous qu'elles sont compatibles 13.56MHz (NTAG215 recommandé)
Boutons poussoirs tactiles (x5)
Pour les contrôles : play/pause, volume +/-, suivant/précédent.
Boutons arcade ou tactiles selon vos préférences
Câbles et connecteurs
Câbles Dupont femelle-femelle, câbles GPIO pour connecter les composants.
Un kit de démarrage Raspberry Pi contient souvent tout le nécessaire
Total estimé
Prix indicatifs, peuvent varier selon les fournisseurs et promotions
Conseil : Les kits complets seront bientôt disponibles dans la boutique ! Tout sera pré-emballé avec les bons composants pour vous faciliter la vie.
Schémas de câblage
Guide détaillé pour connecter tous les composants au Raspberry Pi.
Connexion lecteur NFC RC522
Connectez le module NFC aux pins GPIO du Raspberry Pi via I2C
| De (Module) | Vers (Raspberry Pi) | Couleur câble |
|---|---|---|
| RC522 SDA | GPIO 8 (Pin 24) | Bleu |
| RC522 SCK | GPIO 11 (Pin 23) | Jaune |
| RC522 MOSI | GPIO 10 (Pin 19) | Orange |
| RC522 MISO | GPIO 9 (Pin 21) | Vert |
| RC522 GND | GND (Pin 6) | Noir |
| RC522 RST | GPIO 25 (Pin 22) | Rouge |
| RC522 3.3V | 3.3V (Pin 1) | Rouge |
Boutons de contrôle
Connectez les 5 boutons aux pins GPIO avec résistances pull-up internes
| De (Module) | Vers (Raspberry Pi) | Couleur câble |
|---|---|---|
| Bouton Play/Pause | GPIO 17 (Pin 11) + GND | Gris |
| Bouton Volume + | GPIO 27 (Pin 13) + GND | Violet |
| Bouton Volume - | GPIO 22 (Pin 15) + GND | Bleu |
| Bouton Suivant | GPIO 23 (Pin 16) + GND | Vert |
| Bouton Précédent | GPIO 24 (Pin 18) + GND | Jaune |
Important : Débranchez toujours le Raspberry Pi avant de connecter ou déconnecter des composants GPIO. Une mauvaise connexion peut endommager définitivement votre Pi !
Dépannage
Solutions détaillées aux problèmes les plus courants rencontrés lors de l'assemblage et de l'utilisation.
Lecteur NFC
❌ Le lecteur NFC ne détecte pas les cartes
✅ Solutions :
- 1.Vérifiez que le module RC522 est bien alimenté (LED rouge allumée)
- 2.Vérifiez les connexions GPIO (en particulier SDA, SCK, MOSI, MISO)
- 3.Activez SPI dans raspi-config : sudo raspi-config > Interface Options > SPI > Enable
- 4.Testez avec la commande : python3 -m mfrc522 (doit afficher "Waiting for card...")
- 5.Assurez-vous que les cartes sont bien NTAG215 ou compatibles 13.56MHz
❌ Les cartes sont détectées mais rien ne se joue
✅ Solutions :
- 1.Vérifiez que la carte est bien associée à une playlist dans l'app
- 2.Consultez les logs : sudo journalctl -u musicbox -f
- 3.Vérifiez que des fichiers audio sont bien présents dans /home/pi/music
- 4.Redémarrez le service : sudo systemctl restart musicbox
Audio
❌ Pas de son / Audio ne fonctionne pas
✅ Solutions :
- 1.Vérifiez le volume système : alsamixer (appuyez sur M pour unmute)
- 2.Testez la sortie audio : speaker-test -t wav -c 2
- 3.Changez la sortie audio par défaut : sudo raspi-config > System Options > Audio
- 4.Si utilisation Bluetooth : sudo bluetoothctl puis connect [MAC]
- 5.Vérifiez que pygame est installé : pip3 list | grep pygame
❌ Son haché ou crachotements
✅ Solutions :
- 1.Augmentez le buffer audio dans /etc/asound.conf
- 2.Utilisez une alimentation 3A officielle (pas de sous-alimentation)
- 3.Désactivez le Wi-Fi si possible (sudo rfkill block wifi)
- 4.Réduisez la qualité des fichiers audio (MP3 192kbps max recommandé)
Réseau et Application
❌ L'application mobile ne trouve pas la Music Box
✅ Solutions :
- 1.Vérifiez que les deux sont sur le même réseau Wi-Fi
- 2.Désactivez le mode avion et le VPN sur le smartphone
- 3.Vérifiez que le service API est actif : sudo systemctl status musicbox-api
- 4.Testez l'accès direct : http://[IP-du-Pi]:8000 dans un navigateur
- 5.Vérifiez le pare-feu : sudo ufw allow 8000
❌ Impossible de se connecter en Wi-Fi
✅ Solutions :
- 1.Vérifiez le fichier /etc/wpa_supplicant/wpa_supplicant.conf
- 2.Redémarrez le Wi-Fi : sudo systemctl restart dhcpcd
- 3.Testez avec un câble Ethernet pour diagnostiquer
- 4.Vérifiez que le pays Wi-Fi est bien configuré : sudo raspi-config
Système
❌ Le Raspberry Pi ne démarre pas
✅ Solutions :
- 1.Vérifiez l'alimentation (LED rouge fixe = OK, clignotante = problème)
- 2.Reflashez la carte SD avec une image neuve
- 3.Testez la carte SD sur un autre appareil (peut être corrompue)
- 4.Vérifiez que le fichier config.txt est présent dans /boot
❌ Système très lent ou freezes
✅ Solutions :
- 1.Vérifiez l'espace disque : df -h (minimum 2GB libres)
- 2.Vérifiez la RAM : free -h
- 3.Désactivez les services inutiles : sudo systemctl disable bluetooth
- 4.Overclock léger possible dans /boot/config.txt (attention à la température)
Fichiers et Playlists
❌ Les fichiers audio ne se chargent pas
✅ Solutions :
- 1.Vérifiez les permissions : sudo chown -R pi:pi /home/pi/music
- 2.Vérifiez le format de fichier : file [fichier.mp3]
- 3.Évitez les caractères spéciaux dans les noms de fichiers
- 4.Limite de taille : 200MB par fichier recommandé
❌ Une playlist ne joue pas tous les morceaux
✅ Solutions :
- 1.Vérifiez le fichier playlist.json dans /home/pi/playlists
- 2.Supprimez le cache : rm -rf /home/pi/.cache/musicbox
- 3.Recréez la playlist depuis l'application
Toujours bloqué ?
La communauté est là pour vous aider ! Rejoignez-nous sur GitHub Discussions pour poser vos questions.
Demander de l'aide sur GitHubQuestions fréquentes
Les réponses aux questions les plus courantes.
Quels formats audio sont supportés ?
MP3, FLAC, WAV, OGG, AAC et la plupart des formats audio courants. Le système utilise pygame pour la lecture audio.
Puis-je utiliser des stickers NFC sur mes figurines ?
Absolument ! Les stickers NFC fonctionnent parfaitement. Collez-les sur n'importe quel objet : figurines, blocs de construction, cartes à jouer, etc.
Combien de cartes NFC puis-je associer ?
Il n'y a pas de limite théorique. Vous pouvez associer autant de cartes que vous voulez à différentes playlists.
L'application mobile fonctionne-t-elle hors ligne ?
Oui, une fois la musique téléchargée sur le Raspberry Pi, tout fonctionne en local sans connexion internet.
Puis-je utiliser plusieurs Music Box avec la même application ?
Oui ! L'application peut détecter et gérer plusieurs Music Box sur le même réseau.
Le système fonctionne-t-il avec Spotify/YouTube Music ?
Le système actuel fonctionne avec vos fichiers audio locaux. L'intégration YouTube est en développement.
Quelle est l'autonomie sur batterie ?
Avec une power bank 10000mAh, comptez environ 6-8 heures d'utilisation continue. Privilégiez les batteries USB-C PD.
Puis-je utiliser un Raspberry Pi 3 ou Zero ?
Oui, mais le Pi 4 (4GB) est fortement recommandé pour de meilleures performances. Le Zero 2W fonctionne mais avec des limitations.
Comment ajouter de la musique sans l'application ?
Via SSH, copiez vos MP3 dans /home/pi/music et exécutez : python3 /home/pi/musicbox/scan_library.py
Peut-on programmer des horaires de lecture ?
Oui ! Via l'interface web à http://[IP]:8000/admin ou en éditant /etc/cron.d/musicbox
Combien de temps prend l'assemblage complet ?
Environ 2-3 heures pour un débutant, incluant l'impression 3D (6-12h), l'installation logicielle (30 min) et le câblage (1h). Avec de l'expérience, comptez 1h.
Ai-je besoin de compétences en programmation ?
Non ! L'image système est pré-configurée. Vous flashez la carte SD, assemblez les composants et c'est prêt. Aucun code à écrire, sauf si vous voulez personnaliser.
Où puis-je acheter les composants ?
Raspberry Pi chez Kubii ou Amazon, RC522 sur AliExpress/Amazon, carte SD chez SanDisk, cartes NFC sur eBay. Un kit complet sera bientôt disponible dans notre boutique.
Le boîtier imprimé en 3D est-il obligatoire ?
Non, vous pouvez utiliser n'importe quel boîtier ou même laisser les composants à l'air libre. Le STL est fourni pour ceux qui ont une imprimante 3D.
Quelle est la portée de lecture NFC ?
Environ 2-4 cm maximum. L'enfant doit poser la carte directement sur le lecteur RC522. C'est volontaire pour éviter les détections accidentelles.
Puis-je utiliser des cartes Amiibo ou cartes de transport ?
Les cartes Amiibo fonctionnent ! Les cartes de transport (Navigo, Oyster) ne marchent pas car elles utilisent un autre protocole (Mifare Classic vs NTAG215).
Comment gérer plusieurs enfants avec une seule Music Box ?
Chaque enfant peut avoir ses propres cartes avec ses playlists. L'app permet de créer des profils et d'organiser les cartes par couleur ou symbole.
Le volume est-il limité pour protéger les oreilles ?
Oui, vous pouvez configurer un volume maximum dans les paramètres. Recommandation : 70% max pour les enfants de moins de 6 ans.
Que se passe-t-il si j'enlève la carte pendant la lecture ?
Par défaut, la musique s'arrête immédiatement. Vous pouvez configurer un mode "continue" qui laisse jouer jusqu'à la fin du morceau.
Puis-je mettre à jour le logiciel facilement ?
Oui, via SSH avec "git pull && sudo systemctl restart musicbox" ou via l'interface web (bientôt). Les mises à jour OTA automatiques sont prévues pour Q3 2025.
La Music Box fonctionne-t-elle sans Wi-Fi ?
Absolument ! Une fois configurée, elle fonctionne 100% offline. Le Wi-Fi n'est nécessaire que pour ajouter de la musique via l'app mobile.
Combien de musique puis-je stocker ?
Avec une carte SD 32GB, environ 8000 chansons MP3 (320kbps). Une 64GB double cette capacité. Prévoyez 2GB pour le système.
Puis-je contrôler plusieurs Music Box depuis une seule app ?
Oui ! L'app détecte automatiquement toutes les Music Box sur le réseau. Parfait pour gérer la chambre des enfants + le salon.
Y a-t-il un mode silencieux pour la nuit ?
Oui, configurez un mode "nuit" qui réduit automatiquement le volume après une certaine heure et joue uniquement des berceuses.
Les mises à jour cassent-elles la configuration ?
Non, les playlists et associations de cartes sont sauvegardées dans /home/pi/data et survivent aux mises à jour. Backup automatique quotidien recommandé.
Vous ne trouvez pas votre réponse ?
Rejoignez la communauté sur GitHub Discussions ou consultez le dépannage complet dans la documentation.
Documentation technique
Pour les développeurs et les curieux qui veulent comprendre comment tout fonctionne.