Merge pull request #84 from chrizzo-hb/main

ADB Guide, About Knulli page, improved navigation

Author: chrizzo-hb

docs/_inc/images/play/add-games/add-games-adb-001.png

@@ -0,0 +1,56 @@
+# About KNULLI :material-gamepad:
+
+Hi there! Welcome to KNULLI!
+
+KNULLI is a custom firmware (CFW) for retro-gaming devices. It is developed as a fork of the very well-known [Batocera](https://batocera.org/) adapted to handheld devices which are incompatible with the mainline Linux kernel or need other types of device-specific special attention.
+
+If you are new to retro-gaming: Don't be scared! The initial setup might look a little intimidating at first, but you'll get the gist of it pretty fast, our wiki will guide you through it! Just head to the [Quick Start Guide](../play/quick-start) and follow it step by step and you'll have your KNULLI installation up and running in no time!
+
+However, if you already have some experience with other CFWs, we'd like to give you a brief introduction, since KNULLI might do some things a little differently from other CFWs. So, if you want to make sure KNULLI is the right fit for you, check out the following sections:
+
+* ["You've GOT to try KNULLI!"](#youve-got-to-try-knulli)
+* [Built-in features](#built-in-features)
+* [Set up your emulators via EmulationStation](#set-up-your-emulators-via-emulationstation)
+* [Strict folder structure](#strict-folder-structure)
+* [Default file system](#default-file-system)
+
+## "You've GOT to try KNULLI!"
+
+Our friend [TechDweeb](https://www.youtube.com/@TechDweeb) made a very comprehensive video guide to get you started with KNULLI. (Thanks, TechDweeb!) If you want to get to know KNULLI, learn about its features, and see it in action, this video might just be what you are looking for.
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/GJQnhkNd9kU?si=bSP_jlUffjkhP4H1" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+
+## Built-in features
+
+KNULLI comes with a lot of built-in features:
+
+* KNULLI comes with a ton of different emulators and ports (including PortMaster) and supports the addition of [native Pico-8](../systems/pico-8).
+* You can [scrape](../play/scraping) the metadata and media (screenshots, boxarts, videos, descriptions, etc.) directly from ScreenScraper, TheGamesDB and ArcadeDB.
+* You can collect and review your [RetroAchievements](../play/retro-achievements).
+* You can connect [Bluetooth](../configure/bluetooth) controllers and headphones if your handheld supports Bluetooth.
+* KNULLI supports using the HDMI output of your device (if it has one) to play your games on the big screen.
+* KNULLI allows to [add files wirelessly](../play/add-games/network-transfer) by making your userdata available via SMB (the default built-in Windows file sharing protocol).
+* KNULLI comes with a set of default [bezel decorations](../configure/customization/bezel-decorations) that you can simply switch on.
+* You can switch between a lot of different [themes](../configure/customization/themes).
+* You can organize your games in [dynamic collections](../configure/collections) which group your games automatically by certain keywords or attributes.
+* You can create [custom collections](../configure/collections) of hand-picked games, too!
+* KNULLI comes with syncthing to synchronize your savegames and states among different KNULLI/Batocera devices.
+* If your device comes with [RGB LEDs](../configure/rgb-leds), KNULLI enables you to set them up and even use them as battery indicators.
+* Expert users can access KNULLI via [SSH](../configure/SSH).
+* KNULLI allows to either go on standby or shutdown gracefully when [closing the lid](../configure/power-management) of a clamshell device.
+
+## Set up your emulators via EmulationStation
+
+The frontend of KNULLI is called EmulationStation. It is a very comprehensive GUI that comes with a lot of different themes. One of the core features of KNULLI is that you will be able to set up your emulators directly in EmulationStation either **per system** or **per game**.
+
+Other CFWs expect you to set up the emulators via each emulator's own GUI (which is **RetroArch** in most cases). However, KNULLI encourages you **not** to rely on the RetroArch GUI **at all**. KNULLI will **generate** the emulator configuration for each game individually on launch, based on the settings you set up in EmulationStation.
+
+Expert users will still be able to access the RetroArch GUI while running a game. [**Overrides**](../configure/retroarch/shaders) and [**remap**](../configure/retroarch/controls) files can be used either **per game** or **per system** to make manual adjustments directly in the RetroArch GUI. However, one of the core features of KNULLI is to aggregate emulation settings into EmulationStation to make messing around with individual emulator GUIs obsolete.
+
+## Strict folder structure
+
+KNULLI comes with a lot of built-in features you won't find in many other CFWs. However, to make all these features work, KNULLI relies on a very **strict folder structure**. Games, BIOS files, saves, themes, etc., need to be in the exact place KNULLI needs them to be. If you want to migrate your existing library to KNULLI, you need to adapt said library to the KNULLI folder structure - there is no way around. You should be aware that KNULLI is **case sensitive**.
+
+## Default file system
+
+Unlike many other CFWs, KNULLI defaults to the **ext4** file system. **ext4** has a lot of advantages, it is more sturdy and reliable than the **exFAT** file system, however, it has one big drawback: **ext4** cannot be accessed from Windows/MacOS. Thankfully, KNULLI provides other means to [add games](../play/add-games) either by network access or via ADB. Don't worry though: It is easily possible to simply [format your storage](../play/add-games/formatting) to exFAT instead if you prefer. However, you should be aware about the [PortMaster/exFAT situation](../guides/portmaster-and-exfat) before doing so.

docs/_inc/images/play/add-games/add-games-adb-002.png

@@ -0,0 +1,80 @@
+# :material-usb: Accessing via USB
+
+If [network transfer](../network-transfer) is not an option for you, but you still want to rely on the ext4 file system, you can set up Android Debug Bridge (ADB) to access your KNULLI device via USB connection.
+
+## Install ADB
+
+To access your device via USB, you will need two download and install
+
+* the [ADB SDK Platform tools](https://developer.android.com/tools/releases/platform-tools?hl=de#downloads) (**Memorize** the location where you installed it!)
+* an ADB browser, e.g. [ADB Explorer for Windows](https://apps.microsoft.com/detail/9ppgn2wm50qb)
+
+### Configure ADB Explorer
+
+After installing *ADB SDK Platform tools* and *ADB Explorer*, you need to point *ADB Explorer* to the `adb.exe` file inside the folder where you installed the *ADB SDK Platform tools*. Next, make sure to select *Disk Usage Only* as your *Progress Method*.
+
+<table>
+  <tr>
+    <td>
+      <img src="/_inc/images/play/add-games/add-games-adb-001.png">
+      <p><strong>Step 1: </strong>Open <em>ADB Explorer</em> and click the <em>Change</em> button to select the path to your ADB installation. Point to the <code>adb.exe</code> file of your <em>ADB SDK Platform tools</em> installation.<p>
+    </td>
+    <td>
+      <img src="/_inc/images/play/add-games/add-games-adb-002.png">
+        <p><strong>Step 2: </strong>Select <em>Disk Usage Only</em> as your <em>Progress Method</em>.</p>
+    </td>
+  </tr>
+</table>
+
+## Transfer your data
+
+Now that you have set up your *ADB Explorer*, you may use it to
+
+* add files to your device (**push**).
+* get files from your device (**pull**).
+* delete files from your device.
+
+### Browsing your device with ADB Explorer
+
+Before you start adding or removing files, take a moment to understand how to navigate. In your *ADB Explorer*, your KNULLI device will present itself as *Nexus 4* at the top-left of the *ADB Explorer* window.
+
+* Click *Nexus 4* to expand and then *Browse*.
+* In the next menu, make sure to double-click *Root*, which will take you to the root folder of your KNULLI device.
+* From here, scroll down and double-click `userdata` to enter your [userdata folder](../game-storage).
+* You can use the *Up* symbol or the *Back* arrow in the address bar to return to the previous folder.
+
+<table>
+  <tr>
+    <td>
+      <img src="/_inc/images/play/add-games/add-games-adb-003.png">
+      <p><strong>Step 1: </strong>Click <em>Nexus 4</em> to expand the device and click <em>Browse</em> to start browsing.<p>
+    </td>
+    <td>
+      <img src="/_inc/images/play/add-games/add-games-adb-004.png">
+        <p><strong>Step 2: </strong>Double-click <em>Root</em> to enter the root folder of your KNULLI device.</p>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <img src="/_inc/images/play/add-games/add-games-adb-005.png">
+      <p><strong>Step 3: </strong>Scroll down and double-click <code>userdata</code> to enter the <code>userdata</code> folder.<p>
+    </td>
+    <td>
+      <img src="/_inc/images/play/add-games/add-games-adb-006.png">
+        <p><strong>Step 4: </strong>You have reached the <code>userdata</code> folder.</p>
+    </td>
+  </tr>
+</table>
+
+
+### Adding/retrieving/deleting files to/from your device
+
+In ADB, **adding** something to a device is called **push** while **retrieving** something from a device is called **pull**.
+
+If you want to push or pull a device to/from a folder, navigate to said folder and right-click it to bring up the context menu. Here, you will find options to push, pull, and even delete files.
+
+<img src="/_inc/images/play/add-games/add-games-adb-007.png">
+
+### After transferring your data
+
+Once your data is completely transferred, make sure to update your gamelists to make the data available. You can do so by pressing ++"Start"++ to open the main menu, then open *Game settings* and select *Update gamelists*. KNULLI will rescan all game folders and identify all the games you added to make them available in EmulationStation.

docs/_inc/images/play/add-games/add-games-adb-003.png

@@ -1,9 +1,21 @@
 # :material-layers-plus: Spiele zu KNULLI hinzufügen
 
-Es gibt verschiedene Möglichkeiten, um Spiele auf dein KNULLI-Gerät zu laden. Welche Möglichkeiten für dich geeignet sind, hängt davon ab, welche Funktionen auf deinem Gerät zur Verfügung stehen. Wenn dein Gerät beispielsweise keine geeignete Hardware hat, um einem Netzwerk beizutreten, kannst du natürlich keine Daten via Netzwerk übertragen. Außerdem spielt es natürlich eine Rolle, welches Gerät dir als Datenquelle zur Verfügung steht.
+Es gibt verschiedene Möglichkeiten, um Spiele auf dein KNULLI-Gerät zu laden. Welche Möglichkeiten für dich geeignet sind, hängt davon ab, welche Funktionen auf deinem Gerät zur Verfügung stehen. Bevor du anfängst, deine Spiele hinzuzufügen, solltest du dich aber erst mit der Ordnerstruktur von KNULLI vertraut machen.
 
 !!! danger "Wichtig: Unbedingt lesen bevor du loslegst!"
 
     Im Gegensatz zu vielen anderen CFWs verwendet KNULLI standardmäßig das **ext4**-Dateisystem für deine Spiele, Speicherstände, Konfigurationen etc. ext4 ist ein Dateisystem, das **nicht** von **Windows/MacOS** gelesen oder beschrieben werden kann. Keine Panik: Du kannst deine Spiele trotzdem ganz einfach via [Netzwerkübertragung](../add-games/network-transfer) auf die SD-Karte laden. Wir haben diese Entscheidung **bewusst** gefällt um einen Workaround zu schaffen, weil es derzeit Probleme mit der Kompatibilität von **PortMaster**-Spielen gibt.
 
     Diverse PortMaster-Spiele können derzeit nicht fehlerfrei ausgeführt werden, wenn KNULLI sie von einer mit **exFAT** formatierten SD-Karte starten muss. (**exFAT** ist das Standarddateisystem für SD-Karten und USB-Sticks.) Das PortMaster-Team arbeitet allerdings bereits an einer Lösung für das Problem. Wir **empfehlen dringend**, den Abschnitt [PortMaster und exFAT](../../guides/portmaster-and-exfat) zu lesen **bevor** du die Einrichtung fortsetzt, damit du in Ruhe entscheiden kannst, wie du den Datenspeicher deines KNULLI-Gerätes handhaben möchtest.
+
+## Bevor du anfängst Spiele hinzuzufügen
+
+* [Speicherort für Spiele](game-storage) - Lerne die Ordnerstruktur von KNULLI kennen.
+* [SD-Karte(n) formatieren](formatting) - Lerne die Formatierungsoptionen kennen.
+* [Zweite SD-Karte einrichten](second-sd-card) - Lerne, wie man eine zweite SD-Karte in Betrieb nimmt.
+
+## Nachdem dein Datenspeicher eingerichtet ist
+
+* [Netzwerkübertragung](network-transfer) - Lerne die Netzwerkübertragung von KNULLI kennen.
+* [Zugriff via USB](accessing-via-usb) - Lerne wie du via USB auf dein Gerät zugreifen kannst.
+* [Direktzugriff auf die SD-Karte](accessing-sd-card) - Lerne wie du direkt von Windows auf deine SD-Karte zugreifen kannst (falls möglich).

docs/_inc/images/play/add-games/add-games-adb-004.png

@@ -1,9 +1,21 @@
 # :material-layers-plus: Adding Games to KNULLI
 
-KNULLI has a few options for adding games. Depending on the capabilites of your device, you will have to determine which option to choose. For example, some devices do not have networking capabilites, so with those devices you will not be able to use the network transfer options. Additionally, you might have to consider the computer you will use as a data source, since some options are restricted to specific operating systems.
+KNULLI has a few options for adding games. Depending on the capabilities of your device, you will have to determine which option to choose. Before you start adding your games, we suggest that you accommodate yourself with the storage for games and other userdata.
 
 !!! danger "Important: Read this before you start!"
 
     Unlike many other CFWs, KNULLI currently uses **ext4** as the default file system for your games, saves, configs, etc. ext4 is a **Linux** file system which **cannot** be accessed from **Windows/MacOS**. Don't worry: You will still be able to add your games via [network transfer](../add-games/network-transfer). We made this decision **purposely** to create a workaround for an ongoing issue with **PortMaster** compatibility.
 
     Several PortMaster games are currently not working properly on KNULLI when running from **exFAT**-formatted SD cards. (**exFAT** is the default file system of SD cards and thumb drives.) However, the PortMaster team is aware of the situation and a fix is already on its way. We **strongly recommend** that you read the [PortMaster and exFAT section](../../guides/portmaster-and-exfat) **before you proceed** and make a decision on how to handle data storage on your KNULLI device.
+
+## Before you start adding your games
+
+* [Game Storage](game-storage) - Learn about the folder structure of KNULLI.
+* [Formatting your SD Card(s)](formatting) - Learn about formatting options.
+* [Set up a secondary SD Card](second-sd-card) - Learn about single- and dual SD card setups.
+
+## After your game storage is set up
+
+* [Network Transfer](network-transfer) - Learn how to add your games via Wi-Fi.
+* [Accessing your device via USB](accessing-via-usb) - Learn how to access your device via USB.
+* [Accessing your SD Card directly](accessing-sd-card) - Learn how to access your SD card directly from Windows (if applicable).

docs/_inc/images/play/add-games/add-games-adb-005.png

@@ -158,6 +158,8 @@ plugins:
             PortMaster and exFAT: PortMaster und exFAT
             Power Management: Energieeinstellungen
             Major Updates: Umfangreiche Updates
+            Questions about KNULLI: Fragen zu KNULLI
+            Accessing via USB: Zugriff via USB
         - locale: pl
           name: Polski
           build: true
@@ -251,20 +253,22 @@ plugins:
             Unbranded: Senza Marchio
 nav:
     - Home: index.md
+    - About KNULLI: about-knulli.md
     - FAQs:
       - FAQs: faq/index.md
-      - About KNULLI: faq/knulli.md
+      - Questions about KNULLI: faq/knulli.md
       - Troubleshooting: faq/troubleshooting.md
     - Play:
       - Quick Start Guide: play/quick-start.md
       - Install: play/install.md
       - Add Games:
         - Add Games: play/add-games/index.md
         - Game Storage: play/add-games/game-storage.md
-        - Accessing SD Card: play/add-games/accessing-sd-card.md
+        - Formatting: play/add-games/formatting.md
         - Second SD Card: play/add-games/second-sd-card.md
         - Network Transfer: play/add-games/network-transfer.md
-        - Formatting: play/add-games/formatting.md
+        - Accessing via USB: play/add-games/accessing-via-usb.md
+        - Accessing SD Card: play/add-games/accessing-sd-card.md
       - BIOSes: play/bioses.md
       - Scraping: play/scraping.md
       - Basic Inputs: play/basic-inputs.md