added native Linux VM on Android 16 in to readme

2025-07-20 02:15:58 +02:00
parent 28c7426dcf
commit e8ebb23678
1 changed files with 102 additions and 2 deletions
--- a/docs/remote-control.md
+++ b/docs/remote-control.md
@@ -4,6 +4,8 @@
 1. [HID Smart Buttons](#hid-smart-buttons)
 2. [MQTT Remote Control](#mqtt-remote-control)
    - [Mosquitto Installation Guide](#mosquitto-installation-guide)
+        - [Mosquitto MQTT Broker on Android 16's Native Linux VM](#mosquitto-mqtt-broker-on-android-16s-native-linux-vm)
+        - [Mosquitto MQTT Broker on older versions of Android then 16](#mosquitto-mqtt-broker-on-older-versions-of-android-then-16)
    - [Android Shortcut Setup](#android-shortcut-setup)
    - [Configure `Quick Tap` gesture to trigger the shortcut](#configure-quick-tap-gesture-to-trigger-the-shortcut)
    - [Testing with `mosquitto_pub` (via Termux)](#testing-with-mosquitto_pub-via-termux)
@@ -27,6 +29,92 @@ Players can use their smartphones to send commands to Nexus Timer via MQTT. This

 ### Mosquitto Installation Guide

+#### Mosquitto MQTT Broker on Android 16's Native Linux VM
+
+This guide details how to install and configure the Mosquitto MQTT broker within the native `Linux Virtual Machine environment` introduced in Android 16. For older versions proceed to [Mosquitto MQTT Broker on older versions of Android then 16](#mosquitto-mqtt-broker-on-older-versions-of-android-then-16).
+
+1. **Enable the Linux Development Environment**
+
+First, you must activate the Linux VM on your Android 16 device.
+
+*   Navigate to **Settings > About Phone**.
+*   Tap on the **Build Number** seven (7) times to unlock **Developer options**.
+*   Go back and navigate to **Settings > System > Developer options**.
+*   Find and enable the **Linux development environment** toggle.
+*   Once enabled, a new **Terminal** application will be added to your app drawer.
+
+2. **Install Mosquitto**
+
+Open the **Terminal** app to access your Debian-based Linux environment.
+
+*   First, update and upgrade your system's package lists to ensure all sources are current.
+
+    ```bash
+    sudo apt update && sudo apt upgrade
+    ```
+
+*   Next, use the `apt` package manager to install the Mosquitto broker and the command-line clients.
+
+    ```bash
+    sudo apt install mosquitto mosquitto-clients
+    ```
+
+3. **Configure the MQTT Broker**
+
+Create a custom configuration file to control the broker's behavior. The recommended practice on Debian is to place new configurations in the `/etc/mosquitto/conf.d/` directory.
+
+*   Use a command-line text editor like `nano` to create a new configuration file.
+
+    ```bash
+    sudo nano /etc/mosquitto/conf.d/local.conf
+    ```
+
+*   Add the following lines to the file. This configuration sets up listeners for both standard MQTT and WebSockets traffic and permits connections without authentication.
+
+    ```ini
+    # MQTT listener on port 1883
+    # MQTT connection from the HTTP Shortcut app
+    listener 1883 0.0.0.0
+    protocol mqtt
+
+    # WebSocket listener on port 9001
+    # MQTT over WebSocket connection from the PWA (Web App)
+    listener 9001 0.0.0.0
+    protocol websockets
+
+    # Allow clients to connect without username/password
+    allow_anonymous true
+    ```
+
+*   Save the file and exit the text editor (in `nano`, press `Ctrl+X`, then `Y`, then `Enter`).
+
+4. **Run and Manage the Mosquitto Service**
+
+The Mosquitto broker runs as a system service. After installation, it should start automatically.
+
+*   To apply your new configuration, restart the Mosquitto service:
+
+    ```bash
+    sudo systemctl restart mosquitto
+    ```
+
+*   You can verify that the service is running correctly by checking its status:
+
+    ```bash
+    systemctl status mosquitto
+    ```
+
+*   (Optional) To have the service not start automatically every time you boot up your Linux VM, you can disable it:
+    ```bash
+    sudo systemctl disable mosquitto
+    ```
+
+Your Mosquitto MQTT broker is now successfully configured and running on your Android 16 device.
+
+---
+
+#### Mosquitto MQTT Broker on older versions of Android then 16
+
 1. **Install Termux** from the [Play Store](https://play.google.com/store/apps/details?id=com.termux) and run.
 2. **Update packages and install Mosquitto in Termux:**
    ```bash
@@ -38,19 +126,26 @@ Players can use their smartphones to send commands to Nexus Timer via MQTT. This
    nano $PREFIX/etc/mosquitto/mosquitto.conf
    ```
    Add the following configuration, then save and exit:
-    ```
+    ```ini
+    # MQTT listener on port 1883
+    # MQTT connection from the HTTP Shortcut app
    listener 1883 0.0.0.0
    protocol mqtt

+    # WebSocket listener on port 9001
+    # MQTT over WebSocket connection from the PWA (Web App)
    listener 9001 0.0.0.0
    protocol websockets

+    # Allow clients to connect without username/password
    allow_anonymous true
    ```
 4. **Run Mosquitto with the configuration:**
    ```bash
    mosquitto -c $PREFIX/etc/mosquitto/mosquitto.conf
    ```
+---
+
 ### Android Shortcut Setup
 *   Install the `HTTP Shortcuts` app from the [Play Store](https://play.google.com/store/apps/details?id=ch.rmy.android.http_shortcuts).
 *   Create a new shortcut.
@@ -68,6 +163,8 @@ Players can use their smartphones to send commands to Nexus Timer via MQTT. This
    *   Select the icon and assign the `Pass Turn/My Pause` shortcut.
    *   An icon will appear on the homescreen.
    *   Tap the icon to trigger the game action.
+---
+
 ### Configure `Quick Tap` gesture to trigger the shortcut:
 *   Go to Android `settings`.
 *   Navigate to `System -> Gestures -> Quick Tap to start actions`.
@@ -75,12 +172,15 @@ Players can use their smartphones to send commands to Nexus Timer via MQTT. This
 *   Select `HTTP Shortcuts` app and click the configure icon.
 *   Select `Pass Turn/My Pause` shortcut.
 *   Double-Tap on the back of the phone to trigger the game action.
-### Testing with `mosquitto_pub` (via Termux):
+---
+
+### Testing with `mosquitto_pub` (via Terminal/Termux):
 *   Run: `mosquitto_pub -h <BROKER_IP> -p <TCP_PORT> -t game -m "X"`
    *   Replace `<BROKER_IP>` with your Mosquitto broker's IP (e.g. `localhost`).
    *   Replace `<TCP_PORT>` with Mosquitto's TCP port (e.g., 1883). 
    *   `-t game`: The topic the PWA listens on.
    *   `-m "X"`: The single character message (e.g., "a", "b", "s"). This "X" should match the MQTT char configured in Nexus Timer for the desired action.
+---

 ### Nexus Timer (PWA) Setup
 *   Enter the MQTT Broker URL `ws://localhost:9001` in the Setup screen and connect.