Merge pull request #55 from chrizzo-hb/main

Improved SSH and ScummVM doc

Author: chrizzo-hb

docs/configure/ssh.de.md

@@ -1,15 +1,36 @@
 # :material-console: SSH
 
-Als fortgeschrittener Nutzer möchtest du möglicherweise auf die Kommandozeile (oder Shell) deines KNULLI-Gerätes zugreifen, um Linux-Befehle direkt eingeben zu können. KNULLI stellt dafür einen SSH-Zugang bereit. Es gibt viele verschiedene SSH-Clients, die du nutzen kannst, um Zugriff auf die Shell deines KNULLI-Gerätes zu erhalten. Für Windows-Nutzer empfehlen wir [SmarTTY](https://sysprogs.com/SmarTTY) oder [PuTTY](https://www.putty.org).
+Als fortgeschrittener Nutzer möchtest du möglicherweise auf die Kommandozeile (oder Shell) deines KNULLI-Gerätes zugreifen, um Linux-Befehle direkt eingeben zu können. KNULLI stellt dafür einen SSH-Zugang bereit. Es gibt viele verschiedene SSH-Clients, die du nutzen kannst, um Zugriff auf die Shell deines KNULLI-Gerätes zu erhalten. Für Windows-Nutzer empfehlen wir [SmarTTY](https://sysprogs.com/SmarTTY) (das sogar Dateiübertragungen möglich macht) oder [PuTTY](https://www.putty.org).
 
-Um mit deinem KNULLI-Gerät eine SSH-Verbindung aufzubauen, musst du das Gerät zuerst mit deinem lokalen Netzwerk verbinden, wie im Abschnitt [Netzwerkverbindungen](../networking) beschrieben.
+Es ist allerdings auch möglich, den SSH-Client zu verwenden, der bereits in dein Betriebssystem integriert ist: Die meisten Linux-Distributionen und modernen Windows-Versionen enthalten bereits ein SSH-Programm, das auf der Kommandozeile ausgeführt werden kann.
 
-Um die SSH-Verbindung aufzubauen benötigst du dann die folgenden Informationen:
+Um auf dein KNULLI-Gerät via SSH zuzugreifen, musst du das Gerät zuerst mit deinem lokalen Netzwerk verbinden, wie im Abschnitt [Netzwerkverbindungen](../networking) beschrieben und anschließend eine SSH-Verbindung aufbauen, wie in den folgenden Abschnitten beschrieben.
+
+## Benötigte Informationen
+
+Um die SSH-Verbindung aufzubauen benötigst du die folgenden Informationen:
 
 * Host: Entweder der Hostname deines KNULLI-Gerätes (der Standard-Hostname lautet `KNULLI`) oder die aktuelle IP-Adresse (drücke ++"Start"++ und wähle *Network settings* um deine aktuelle IP-Adresse einzusehen)
 * Username: `root`
 * Passwort: Dein aktuelles Root-Passwort (drücke ++"Start"++ und wähle *System settings* und dann *Security* um dein aktuelles Root-Passwort einzusehen, das Standardpasswort lautet `linux`)
 
+## Option 1: Den integrierten SSH-Kommandozeilenbefehl verwenden
+
+* Öffne ein Terminal bzw. eine Konsole auf deinem Computer.
+     * Windows-Nutzer können sowohl das neue Windows Terminal als auch die klassische Eingabeaufforderung (CMD) oder die PowerShell nutzen.
+     * Linux-Nutzer wissen normalerweise eh, wie man die Kommandozeile auf ihrem Gerät benutzt.
+* Tippe
+  ```
+  ssh root@knulli
+  ```
+  und bestätigte mit ++"Enter"++. (Falls du den Hostnamen deines KNULLI-Gerätes geändert hast, musst du `knulli` mit deinem Hostnamen oder der IP-Adresse deines KNULLI-Geräts ersetzen.)
+* Falls du nach Fingerabdrücken gefragt wirst, kannst du das einfach bestätigen.
+* Sobald du danach gefragt wirst, gib dein Passwort ein und bestätige.
+* Nachdem das Passwort überprüft wurde, solltest du mit deinem Gerät via SSH verbunden sein.
+* Wenn du mit deinen SSH-Arbeiten fertig bist, kannst du die Verbindung trennen, indem du `exit` eintippst und bestätigst.
+
+## Option 2: Ein eigenständiges SSH-Programm verwenden
+
 Um eine SSH-Verbindung via SmarTTY aufzubauen, installiere das Programm, starte es und folge diesen Schritten:
 
 <table>

docs/configure/ssh.md

@@ -1,15 +1,36 @@
 # :material-console: SSH
 
-As an advanced user, you might want to access the command line (or shell) of your KNULLI device to enter Linux commands directly. You may do so by connecting to KNULLI via SSH. There are several SSH clients available. For Windows users, we recommmend [SmarTTY](https://sysprogs.com/SmarTTY) or [PuTTY](https://www.putty.org).
+As an advanced user, you might want to access the command line (or shell) of your KNULLI device to enter Linux commands directly. You may do so by connecting to KNULLI via SSH. There are several SSH clients available. For Windows users, we recommmend [SmarTTY](https://sysprogs.com/SmarTTY) (which is also able to do file transfers) or [PuTTY](https://www.putty.org).
 
-To connect to your KNULLI device via SSH, simply connect the device to your local network as described in the [Networking](../networking) section.
+However, it is also possible to simply use the SSH client which is already integrated in your operating system: Most Linux distributions and modern Windows versions come with a SSH command line tool.
+
+To connect to your KNULLI device via SSH, simply connect the device to your local network as described in the [Networking](../networking) section and establish the SSH connection as explained below.
+
+## Required information
 
 When establishing your SSH connection, you will need the following information:
 
 * Host: Either the hostname of your KNULLI device (default is `KNULLI`) or the current IP address (press ++"Start"++ and go to *Network settings* to find your current IP address)
 * Username: `root`
 * Password: Your current root password (press ++"Start"++ and go to *System settings* and *Security* to find your current root password, default is `linux`)
 
+## Option 1: Using SSH from the command line
+
+* Open a command line/terminal on your computer.
+    * Windows users can use the new Windows Terminal, classic CMD, or PowerShell.
+    * Linux users probably know their way around the command line anyway.
+* Type
+  ```
+  ssh root@knulli
+  ```
+  and confirm by pressing ++"Enter"++. (If you changed the hostname of your KNULLI device, you might need to replace `knulli` with the hostname you chose or the IP address of your KNULLI device.)
+* If asked, you may confirm fingerprinting.
+* When asked, type your password and confirm.
+* After the password was verified, you should be connected to your device via SSH.
+* Once you are done with SSH, you can quit the SSH client by typing `exit` and confirming.
+
+## Option 2: Using a standalone SSH client tool
+
 To establish a SSH connection via SmarTTY, install and launch the program, then follow these steps:
 
 <table>

docs/systems/scummvm.md

@@ -8,30 +8,78 @@ ScummVM is a collection of virtual machines and re-implementations of game engin
 
     However, KNULLI also supports connecting a mouse via Bluetooth, as explained in the [Controls](../../configure/controls) section.
 
+## Standalone and RetroArch ScummVM
+
+KNULLI comes with two different ScummVM emulators: The RetroArch-integrated ScummVM core (`libretro:scummvm`) and the standalone ScummVM (`scummvm`). Both work fine on most KNULLI-driven handhelds, however, some of the more demanding games might run a little better on the **standalone** version.
+
+Both versions come with the ScummVM launcher which relies on a `scummvm.ini` file to keep all the game-specific settings, however, both versions work slightly different:
+
+* **Standalone** ScummVM
+    * keeps its `scummvm.ini` in `system/.config/scummvm`.
+    * will **only** launch games from EmulationStation which have been added to `scummvm.ini`
+        * either by manually editing the file or
+        * by adding the games from the **standalone** launcher.
+* **Libretro** ScummVM
+    * keeps its `scummvm.ini` in `bios`.
+    * will launch games from EmulationStation **without** adding them to the `scummvm.ini`.
+    * will **not** memorize game-specific settings for games which are launched from EmulationStation.
+
+!!! info "Updated version coming soon"
+    We already adopted a recent update to Batocera, which improved the behavior of the **libretro** ScummVM emulator. With every KNULLI build **after** August 19th 2024, **libretro** ScummVM will memorize game specific settings if the game was added to `scummvm.ini`, either by manually editing the file or by adding the games from the **standalone** launcher. To call the came as configured in the `scummvm.ini`, the `.scummvm` file needs to **contain** the **exact launcher ID**.
+
 ## Adding ScummVM games
 
-Unlike most other systems, your ScummVM games need a little adjustment to be run on your KNULLI device.
+Unlike most other systems, your ScummVM games need a little adjustment to be run on your KNULLI device. This guide will help you to set up your ScummVM games properly. To do so, it is required that you understand the difference between the **game ID** and the **launcher ID** of ScummVM.
+
+### Game IDs
+
+Within ScummVM, each game has a dedicated **game ID** that consists of two parts: The ID of the **engine** (or developer) and the ID of the **game** within that engine. Those two values are combined, separated by the `:` character. For example, classic LucasArts adventures run in the SCUMM engine, which has the ID `scumm`. Within that engine, "Indiana Jones And The Fate Of Atlantis" by LucasArts has the ID `atlantis`. Consequently, the **game ID** of "Indiana Jones And The Fate Of Atlantis" is `scumm:atlantis`.
+
+The game "Atlantis: The Lost Tales" by Cryo also goes by `atlantis`, however, the engine for that game has the ID `cryomni3d`, so the **game ID** of "Atlantis: The Lost Tales" is `cryomni3d:atlantis`.
+
+### Launcher IDs
 
-### Step 1: Find out the game ID
+When adding a game to the ScummVM launcher (e.g., on your computer or on your emulation device), the game receives another ID - the **launcher ID**. By default, the launcher ID **usually** corresponds to the game-part (the part after the `:`) of the **game ID**, sometimes **followed** by a set of **modifiers** that indicates a language or other version information.
 
-Within ScummVM, every supported game has an **ID**. You will need to find out the ScummVM ID of your game in order to run it on KNULLI. You can do so by opening *ScummVM* on your local PC and have a look at the *Game* tab in the *Game Settings* of each game. Alternatively, you can check out the [compatibility chart at the ScummVM website](https://www.scummvm.org/compatibility/). You will find the game ID in the *ScummVM ID* column. (You only want the part after the colon (`:`), e.g., `comi` from `scumm:comi` for "The Curse Of Monkey Island".)
+For example, "Broken Sword" has the **game ID** `sword1:sword1`, the german Windows version of the game gets the **launcher ID** `sword1-win-de` by default. However, it is also possible to add **the same game** multiple times to the ScummVM launcher. In this case, the launcher ID receives a numerical suffix, for example, a second instance of "Broken Sword" would receive the **launcher ID** `sword1-win-de-1`.
 
-!!! info "Some games exist in different versions"
+### Step 1: Find out the (default) launcher ID
 
-    Be aware that some games have different IDs for different versions, e.g., localized versions, usually indicated by a suffix to the original game ID. For example, the main (US) version of "Day Of The Tentacle" has the ID `tentacle`, the German version has the ID `tentacle-de`.
+To run your ScummVM game on KNULLI, you will need to find out the (default) **launcher ID** of the ScummVM game. You can do this by adding the game to the ScummVM launcher on your computer or on your handheld device. Afterwards, go to the *Game Options*, find the *Game* tab and take a look at the *ID* field.
+
+!!! info "Open ScummVM launcher on your device"
+    The launcher will pop up automatically if you try to launch a game that does not exist. For the **standalone** ScummVM launcher, you need to make sure that *Emulator* is set to `scummvm` in the *Game Settings* (or *System Settings*). Likewise, you will need to set *Emulator* to `libretro:scummvm` if you want to configure the **RetroArch-integrated** ScummVM.
+    In both cases, create a `.scummvm` file for a game you know not to exist (e.g., `scummvm-launcher.scummvm`) and launch it from EmulationStation to bring up the launcher.
 
 ### Step 2: Add your game files
 
-In the [`userdata` folder](../../play/add-games/game-storage), go to `roms`, then go to `scummvm`. Inside this folder, create a subfolder for every game you want to add. Even though you can name the folder however you want, we suggest to name the folder like the game ID, e.g. `roms/scummvm/comi`.
+In the [`userdata` folder](../../play/add-games/game-storage), go to `roms`, then go to `scummvm`. Inside this folder, create a subfolder for every game you want to add. You can name the folder however you want.
 
 Depending on the game, you will need some files from your original copy of the game to run it with ScummVM. Have a look at the [Supported Games section of the ScummVM wiki](https://wiki.scummvm.org/index.php?title=Category:Supported_Games) to figure out, which files you will need to run your game and add them to the folder you just created, just as explained in the ScummVM wiki.
 
-Additionally, create an empty text file in the folder of each game and name it `[ScummVM game ID].scummvm`, e.g., `comi.scummvm` for "The Curse Of Monkey Island" or `tentacle-de.scummvm` for the German version of "Day Of The Tentacle".
+### Step 3: Create the ScummVM file
+
+After you have added all the game files for a game, create an new text file in the folder of each game. Now, you need to rename this file **exactly** like the **default launcher ID** of this game. So, for example, for the German version of "Broken Sword" for Windows, the file should be named `sword1-win-de.scummvm`. This will allow the **RetroArch-integrated** ScummVM to launch the game from EmulationStation.
+
+However, if you also want to be able to use **standalone** ScummVM **or** if you want to be able to save game-specific settings in the **RetroArch-integrated** ScummVM, you need to take an additional step and **edit** the text file, so that it **contains** the same **default launcher ID** the file is named after.
+
+So, for the German version of Broken Sword, you will have a file `sword1-win-de.scummvm` which contains the following text:
 
-### Step 3: Update gamelists
+```
+sword1-win-de
+```
+
+!!! info "Saving game-specific settings in RetroArch-integrated ScummVM"
+    Saving game-specific settings is only supported in KNULLI builds which have been released **after** August 19th 2024.
+
+### Step 4: Update gamelists
 
 Press ++"Start"++ to bring up the main menu, go to *Game Settings* and pick *Update Gamelists* to scan for your newly added games. Afterwards, you should find your ScummVM games in the *ScummVM* category.
 
-### Step 4: Scrape media
+### Step 5: Add the game to the ScummVM launcher
+
+Depending on your previous steps and the emulator you chose, you might be led directly to the ScummVM launcher when you try to lauch your game for the first time, because it could not be found within the respective `scummvm.ini`. If so, pick *Add Game* in the ScummVM launcher and add the game by browsing to its folder and following on-screen instructions. Afterwards, *Quit* the launcher and try to launch your game again. If it still does not work, go to the *Game Options* within ScummVM, take a look at the *ID* in the *Game* tab and make sure to have the very same ID in your `.scummvm` file and its name.
+
+### Step 6: Scrape media
 
-By default, each ScummVM game will be named after its `.scummvm` file. Since this is not very user-friendly, we recommend scraping for artworks and media. Since the scraper will most likely not be able to identify games based on their sometimes pretty cryptic ScummVM IDs, you may need to do scrape **manually** as explained in the [Scraping](../../play/scraping) section.
+By default, each ScummVM game will be named after its `.scummvm` file in your EmulationStation GUI. Since this is not very user-friendly, we recommend scraping for artworks and media. Since the scraper will most likely not be able to identify games based on their sometimes pretty cryptic ScummVM IDs, you may need to do scrape **manually** as explained in the [Scraping](../../play/scraping) section.