Raspberry Pi auswählen
Auf der DietPi-Webseite das passende Raspberry-Pi-Modell auswählen und das 64-Bit-Image herunterladen.
MuPiBox-NG · Installation
MuPiBox NG installieren
DietPi auf microSD oder USB-Stick schreiben, unsere vorbereitete dietpi.txt kopieren und einschalten. Per LAN läuft die Einrichtung danach vollständig automatisch; für WLAN kommen nur Ländercode, SSID und Passwort dazu.
Aktueller Stand: MuPiBox NG wird vorerst ausschließlich als Development-Version veröffentlicht (
0.1.0-dev.N). Die Installation ist für Tester vorgesehen; Test-, Alpha- und Stable-Kanäle sind technisch vorbereitet, werden aktuell aber noch nicht öffentlich veröffentlicht.
Schritt 1
DietPi herunterladen.
MuPiBox NG setzt auf ein schlankes 64-Bit-DietPi. Aktuell ist Debian 13 „Trixie“ die bevorzugte stabile DietPi-Basis.
Speichermedium wählen
Du kannst eine microSD-Karte oder – wenn dein Raspberry Pi USB-Boot unterstützt – einen USB-Stick verwenden. Wenn du unsicher bist, nimm zunächst microSD.
Flash-Programm
Das heruntergeladene .img.xz-Image kann direkt mit Raspberry Pi Imager, balenaEtcher oder Rufus geschrieben werden.
Achtung: Beim Flashen wird das ausgewählte Speichermedium vollständig überschrieben. Vor dem Start unbedingt prüfen, dass wirklich die richtige microSD-Karte bzw. der richtige USB-Stick ausgewählt ist.
Schritt 2
DietPi auf microSD oder USB flashen.
Der Ablauf ist bei beiden Medien praktisch identisch.
DietPi-Image auswählen
Im Flash-Programm das heruntergeladene DietPi-Image als Betriebssystem bzw. Image auswählen.
microSD oder USB auswählen
Das gewünschte Zielmedium auswählen. Für eine Musikbox empfiehlt sich ausreichend Reserve für Updates, Cache und lokale Medien.
Schreiben und auswerfen
Image schreiben, die Prüfung des Flash-Programms abwarten und das Medium danach sauber auswerfen.
Schritt 3
Netzwerk und Display auswählen.
Nach dem Flashen die Boot-Partition noch einmal am PC öffnen und die passende MuPiBox-Vorlage herunterladen. Entscheidend sind dabei zwei Dinge: LAN oder WLAN – und ob du das Waveshare 5-inch 800×480 DSI verwendest. Die gewählte Datei anschließend auf der Boot-Partition als dietpi.txt speichern und die vorhandene Datei ersetzen.
Standard / HDMI / Raspberry-Pi-Display
Verwendest du HDMI, das offizielle Raspberry-Pi-Touchdisplay oder ein anderes bereits vom System unterstütztes Display, nimm die normale LAN- oder WLAN-Vorlage. MuPiBox erzwingt dann kein zusätzliches Panel-Overlay.
Waveshare 5" DSI 800×480
Für dieses Display musst du ausdrücklich die Waveshare-Vorlage verwenden. Sie trägt den benötigten DSI-Treiber bereits während der Installation ein, damit das Display nach dem ersten Reboot sofort wieder verfügbar ist.
Warum erkennt MuPiBox das Waveshare nicht einfach automatisch? Das Panel benötigt sein Device-Tree-Overlay, bevor Linux es zuverlässig als DSI-Display bereitstellen kann. Genau dieses Overlay muss also schon vor dem ersten MuPiBox-Reboot gesetzt werden. Die Waveshare-Vorlage ist deshalb nicht nur für den Installationsscreen wichtig, sondern für den normalen Betrieb des Displays. Mit der generischen Vorlage kann die Installation erfolgreich durchlaufen, das Waveshare aber nach dem Reboot schwarz bleiben.
Installation per LAN
Empfohlen, wenn ein Netzwerkkabel verfügbar ist. Ethernet ist bereits aktiviert, WLAN deaktiviert. Nach dem Kopieren sind keine weiteren Netzwerkeinstellungen nötig.
AUTO_SETUP_NET_ETHERNET_ENABLED=1
AUTO_SETUP_NET_WIFI_ENABLED=0Installation per WLAN
WLAN ist bereits aktiviert und Ethernet deaktiviert. Vor dem ersten Boot musst du nur noch den korrekten WLAN-Ländercode sowie SSID und Passwort eintragen.
AUTO_SETUP_NET_ETHERNET_ENABLED=0
AUTO_SETUP_NET_WIFI_ENABLED=1Nur bei WLAN: Land setzen
In der WLAN-dietpi.txt bei AUTO_SETUP_NET_WIFI_COUNTRY_CODE deinen echten zweistelligen ISO-Ländercode eintragen, zum Beispiel DE, AT, CH, US oder GB.
Nur bei WLAN: Zugangsdaten
In DietPis vorhandener dietpi-wifi.txt reichen für ein normales WPA/WPA2-Heimnetz in Entry 0 normalerweise aWIFI_SSID[0] und aWIFI_KEY[0]. aWIFI_KEYMGR[0]='WPA-PSK' bleibt unverändert.
Weltweit neutral: Alle MuPiBox-Vorlagen verwenden
C.UTF-8 und UTC. Nur der WLAN-Ländercode kann nicht weltweit sinnvoll vorbelegt werden und muss bei einer WLAN-Variante einmal passend zum Standort gesetzt werden.
Wichtig: Egal ob
dietpi-mupibox-lan.txt, dietpi-mupibox-wifi.txt oder eine der beiden waveshare-5-dsi-Varianten: Auf der Boot-Partition muss die gewählte Datei am Ende immer dietpi.txt heißen.
Schritt 4
Einschalten und warten.
DietPi führt den kompletten First-Run automatisch aus. Danach lädt DietPi unser Post-Install-Script von releases.mupibox.de, welches den signierten MuPiBox-NG-Installer startet.
DietPi richtet sich ein
Updates, Basissystem, Netzwerk und die vorgegebenen Systemoptionen werden ohne Menüs oder Rückfragen eingerichtet.
MuPiBox übernimmt
Nach Abschluss des DietPi-Setups startet automatisch der MuPiBox-NG-Installer. Sobald möglich, zeigt das Display den grafischen Installationsfortschritt.
Nur bei Problemen: SSH
Für die Diagnose ist Dropbear aktiv. Das vorbereitete Initial-Login lautet root mit Passwort mupibox. Dieses öffentliche Setup-Passwort solltest du nach erfolgreicher Installation ändern.
Nicht ausschalten: Der erste Start kann deutlich länger dauern als ein normaler Boot. Solange DietPi bzw. der MuPiBox-Installer arbeitet, die Stromversorgung nicht trennen.
Manueller Fallback
Normalerweise musst du nichts mehr eingeben.
Nur wenn du ohne unsere vorbereitete dietpi.txt installierst oder den automatischen Lauf erneut starten möchtest, kannst du den Development-Installer manuell als root ausführen:
Standard / HDMI / offizielles Raspberry-Pi-Display:
curl -fsSL https://releases.mupibox.de/installer/install.sh | bash -s -- development genericWaveshare 5" DSI 800×480:
curl -fsSL https://releases.mupibox.de/installer/install.sh | bash -s -- development waveshare-5-dsi
Displayprofil bleibt erhalten: Das Waveshare-Profil ist keine temporäre Installationsoption. Der Installer schreibt damit dauerhaft das benötigte DSI-Overlay in die Raspberry-Pi-Bootkonfiguration. Nach dem Reboot läuft die normale MuPiBox-Oberfläche über denselben Displaytreiber weiter.
Automatische Einrichtung
Der Installer richtet benötigte Systempakete, MuPiBox-Dienste, Player, Web-Administration und Update-Infrastruktur automatisch ein.
Fortschritt am Display
Sobald die grafischen Komponenten verfügbar sind, übernimmt der MuPiBox-Installationsscreen. Während der Installation die Stromversorgung nicht trennen.
Kein GitHub-Zugang nötig
Die Box lädt fertige Release-Artefakte von releases.mupibox.de. Das private Quellcode-Repository wird auf der Box nicht benötigt.
Sicherer Release-Weg: Der Installer prüft das MuPiBox-Release über eine Ed25519-Signatur und anschließend den SHA256-Prüfwert des heruntergeladenen Artefakts. Ein manipuliertes offizielles Manifest wird abgelehnt.
Schritt 5
Adminportal öffnen.
Am Ende der Installation zeigt der Installer die IP-Adresse der Box an. Das Adminportal erreichst du anschließend im Browser über Port 8090:
http://IP-DER-MUPIBOX:8090/Sicherheit zuerst
Zuerst ein Admin-Passwort setzen. Danach unter Box → Systemzugang das öffentliche DietPi-Setup-Passwort mupibox für root und dietpi durch ein eigenes Passwort ersetzen.
Grundlagen
Admin-Sprache, Boxname, Displaygröße, Lautstärke und weitere Grundeinstellungen setzen.
Medien, TTS & Hardware
Lokale Medien, Spotify, Radio, Text-to-Speech, MuPiHAT, RFID, Tasten und Netzwerk passend zur eigenen Box einrichten.
Updates
Danach läuft alles über MuPiBox.
Spätere NG-Versionen werden im Adminportal unter Wartung → Updates angezeigt. Dort siehst du auch die lokal installierte Version und den aktiven Development-Kanal. Im signierten Versionsverlauf kannst du bei Bedarf gezielt zu einer früheren veröffentlichten Development-Version wechseln. Download, Signatur-/Prüfsummenprüfung, Backup, Installation, Healthcheck und automatischer Rollback laufen dabei immer über denselben MuPiBox-Updater.
Wenn etwas nicht klappt
- Internetverbindung der Box prüfen.
- Bei USB-Boot prüfen, ob dein Raspberry Pi davon booten kann.
- Bleibt ein Waveshare 5" DSI nach dem Reboot schwarz, prüfen, ob wirklich die
waveshare-5-dsi-Vorlage verwendet wurde. - Adminportal über die IP-Adresse und
:8090öffnen. - Bei Installationsproblemen die genaue Fehlermeldung aus dem Terminal notieren.
Diagnose per SSH
Falls der Dienst nicht startet, helfen diese beiden Befehle bei der Fehlersuche:
systemctl status mupibox-ng
journalctl -u mupibox-ng -n 100 --no-pager