Apps installeren op muOS: .muxapp- en .muxzip-bestanden met Archive Manager

Apps voor muOS komen als één bestand dat eindigt op .muxapp. Je hoeft het niet uit te pakken of mappen te kopiëren: muOS heeft een ingebouwd installatieprogramma, Archive Manager, dat het voor je doet. Deze handleiding laat het hele proces zien, wat er achter de schermen gebeurt, en de twee dingen waar mensen over struikelen: updates die je instellingen terugzetten, en hoe je een app verwijdert.

Getest op: Anbernic RG40XXH · muOS 2601.0 Jacaranda. Andere muOS-handhelds werken hetzelfde.

Wat een .muxapp-bestand is

Een .muxapp-bestand is een gewoon ZIP-archief met een andere extensie. Erin zit één map met de naam van de app, bijvoorbeeld:

WiFiTransfer.muxapp
└── WiFiTransfer/
    ├── mux_launch.sh    ← hiermee start muOS de app
    ├── config.ini
    └── …

Installeren betekent die map uitpakken naar MUOS/application/ op je SD-kaart. Elke app in die map verschijnt in het menu Applications.

Stap 1: kopieer het bestand naar de map ARCHIVE

Archive Manager toont de bestanden in de map ARCHIVE bovenaan op SD-kaart 1 (de kaart waar muOS vanaf draait). Bestaat de map niet, maak hem dan aan, in hoofdletters.

Er zijn drie eenvoudige manieren om het bestand daar te krijgen:

Kaartlezer: zet de handheld uit, stop SD-kaart 1 in je computer en kopieer het .muxapp-bestand naar ARCHIVE. Werp de kaart netjes uit voordat je hem eruit haalt.
Via wifi met Wi-Fi Transfer: open de app op de handheld, open het getoonde adres in de browser van je telefoon of pc en tik in het tabblad SD-kaart 1 op Games toevoegen en kies de .muxapp. Hij gaat automatisch naar ARCHIVE.
SFTP: muOS kan een SFTP-server draaien: zet SFTP + Filebrowser aan onder Configuration → Connectivity → Web Services. Daarna kan elke SFTP-app (FileZilla, Cyberduck, WinSCP) het bestand naar ARCHIVE op SD-kaart 1 kopiëren.

Houd de bestandsnaam zoals hij is: Archive Manager bepaalt aan de extensie (.muxapp) wat hij doet.

Stap 2: installeer het met Archive Manager

Open op de handheld Applications → Archive Manager.
Selecteer het .muxapp-bestand en druk op A.
muOS sluit zijn menu’s en toont tijdens het werk een tekstscherm: Inspecting Archive…, de bestanden die worden uitgepakt, Sync Filesystem en tot slot All Done!
Na een paar seconden ben je terug in Archive Manager. Het bestand staat nu gemarkeerd als INSTALLED.

Open Applications: de nieuwe app staat in de lijst. Sommige apps hebben ook wifi nodig (Configuration → Connectivity → Wi-Fi Network) voordat je ze start.

Het .muxapp-bestand blijft na de installatie in ARCHIVE staan. Je kunt het als back-up bewaren of verwijderen; de geïnstalleerde app heeft het niet nodig.

Wat Archive Manager echt doet

Voordat hij iets uitpakt, controleert Archive Manager het archief en weigert hij het als een pad erin buiten de doelmap wijst (een absoluut pad of ..). Zo kan een kapot of kwaadaardig pakket op die manier geen systeembestanden van muOS overschrijven.

Die controle gaat over waar bestanden terechtkomen, niet over wat de app doet als hij draait. Apps op muOS hebben volledige toegang tot het systeem, dus installeer alleen .muxapp-bestanden van bronnen die je vertrouwt: de eigen website van de ontwikkelaar of zijn releasepagina op GitHub.

Archive Manager is niet alleen voor apps. Hij kiest de installatiemethode op basis van de extensie:

Extensie	Wat het is	Waar het heen gaat
`.muxapp`	Applicatie	`MUOS/application/`
`.muxthm`	Thema	`MUOS/theme/<naam>/`
`.muxalt`	Alternatief uiterlijk voor het huidige thema	de map van het actieve thema
`.muxzip`	Inhoudspakket (bijvoorbeeld savegames, BIOS of collecties, afhankelijk van de inhoud)	de bijbehorende muOS-mappen
`.muxcat`	Cataloguspakket (hoesafbeeldingen en beschrijvingen)	`MUOS/package/catalogue/`
`.muxcfg`	RetroArch-configuratiepakket	`MUOS/package/config/`
`.muxupd`	muOS-systeemupdate	het systeem zelf

Een app updaten: bewaar eerst je instellingen

Om te updaten kopieer je de nieuwere .muxapp naar ARCHIVE en installeer je hem op dezelfde manier. Archive Manager pakt hem over de bestaande app-map heen uit:

bestanden die in het nieuwe pakket zitten, vervangen de oude, ook config.ini;
bestanden die niet in het pakket zitten, zoals de mappen data/ of logs/ van de app, blijven staan.

Alles wat je in de config.ini van de app hebt veranderd, staat na een update dus weer op de standaardwaarde. Kopieer vóór het updaten de config.ini van de app naar een veilige plek (of schrijf je instellingen op) en zet je wijzigingen daarna terug. Game Manager is een uitzondering: er zit geen config.ini in het pakket, dus je instellingen, ook je itch.io-API-sleutel, blijven bij een update bewaard. Je lijst met geïnstalleerde games staat in data/ en overleeft de update.

Heeft het nieuwe bestand dezelfde naam als het oude, verwijder of vervang dan eerst het oude in ARCHIVE, zodat je zeker weet welke je installeert.

Een app verwijderen

muOS 2601 heeft geen knop om apps te verwijderen. Om er een weg te halen, verwijder je de map:

SD-kaart 1 → MUOS/application/<AppNaam>

Doe dat met een kaartlezer, via SFTP of met Wi-Fi Transfer. Ga daarna terug naar het hoofdmenu en open Applications opnieuw; de app is weg. Door de map te verwijderen gaan ook de eigen instellingen en gegevens van de app weg, dus kopieer eerst wat je wilt bewaren.

Problemen oplossen

Archive Manager zegt “No Archives Found”: het bestand staat niet in ARCHIVE bovenaan SD-kaart 1, of de map heeft een verkeerde naam. Hij moet ARCHIVE heten, niet in ROMS of MUOS staan.
Het bestand staat in de lijst maar de installatie mislukt met “unsafe paths”: het pakket is verkeerd gemaakt. Neem contact op met de ontwikkelaar van de app; probeer het niet met de hand uit te pakken.
“Could not open archive… Corrupt?”: de download is niet afgemaakt of het kopiëren werd onderbroken. Download het opnieuw en vergelijk, als de ontwikkelaar een SHA-256-controlesom geeft, die (shasum -a 256 file.muxapp op een Mac of Linux).
De app is geïnstalleerd maar verschijnt niet: ga terug naar het hoofdmenu en open Applications opnieuw. Ontbreekt hij nog steeds, controleer dan of MUOS/application/<AppNaam>/mux_launch.sh bestaat.
De app start en sluit meteen weer: veel apps schrijven een logboek in hun eigen map, meestal logs/app.log. Kijk daarin, en zet wifi aan als de app internet nodig heeft.

Samenvatting

Zet het .muxapp-bestand in ARCHIVE op SD-kaart 1.
Applications → Archive Manager, selecteer het, druk op A, wacht op All Done!
Open de app via Applications.
Bewaar vóór een update de config.ini van de app. Om te verwijderen wis je de map in MUOS/application/.

Vragen? Mail naar feedback@pocketkode.com.

PocketKode is niet verbonden aan muOS of Anbernic.