# Remote Control Options

## Table of Contents
1. [HID Smart Buttons](#hid-smart-buttons)
2. [MQTT Remote Control](#mqtt-remote-control)
    - [Mosquitto Installation Guide](#mosquitto-installation-guide)
        - [Mosquitto MQTT Broker using `Termux` app](#mosquitto-mqtt-broker-using-termux-app)
        - [Mosquitto MQTT Broker with VPN on Android 16's Native Linux VM](#mosquitto-mqtt-broker-with-vpn-on-android-16s-native-linux-vm)
    - [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)
    - [Nexus Timer (PWA) Setup](#nexus-timer-pwa-setup)


## HID Smart Buttons
For an enhanced tactile experience, Nexus Timer supports Smart Buttons based on Bluetooth-connected microcontroller (e.g., XIAO nRF52840) implementing HID (Human Interface Device) protocol emulating a keyboard.

*   **Buttons:** Connect 3 physical buttons, potentially extended e.g., via 1.5m wires for easy player access.
*   **Configuration:**
    *   **Player 1's Button:** Single Click: Emulates a key press (e.g., 'a'). Configure this as Player 1's "Pass Turn / My Pause" hotkey in the app.
    *   **Player 2's Button:** Single Click: Emulates a key press (e.g., 'b'). Configure as Player 2's "Pass Turn / My Pause" hotkey.
    *   **Player 3's Button:** Single Click: Emulates a key press (e.g., 'c'). Configure as Player 3's "Pass Turn / My Pause" hotkey.
    *   **If Player 3 is Game Admin:**
        *   **Player 3's Button:** Long Press: Emulates a key press (e.g., 's'). Configure as the "Global Stop/Pause All" hotkey in the app.
        *   **Player 3's Button:** Double Click: Emulates a key press (e.g., 'x'). Configure as the "Global Run All Timers" hotkey in the app.
    
The code for the XIAO nRF52840 module with a 3D printing files can be found in the [arduino](../arduino) subdirectory.

## MQTT Remote Control
Alternatively to a dedicated smart buttons, players can use their smartphones to send commands to Nexus Timer via MQTT. This requires an MQTT broker (like Mosquitto) on the same network.

### Mosquitto Installation Guide

#### Mosquitto MQTT Broker using `Termux` app

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
    pkg update && pkg upgrade
    pkg install mosquitto
    ```
3. **Configure the MQTT Broker:**
    ```bash
    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
    ```
---

#### Mosquitto MQTT Broker with VPN 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. Note that ports exposed by the Mosquitto cannot be reached from LAN. The workarround is using a VPN (wireguard).

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.

---

### 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.
*   Advanced Types -> MQTT Shortcut.
*   Shortcut name: `Pass Turn/My Pause`
*   Basic Settings: Set the MQTT server's address to `tcp://localhost:1883`. *(Note: `HTTP Shortcuts` app uses TCP, while the PWA (Web app) uses WebSockets to connect to the same broker.)*
*   Messages:
    *   Set Topic to: `game`. *(Note: The topic name is hardcoded in the PWA.)*
    *   Set Payload to a single character (e.g. `a`). Each player will set a unique character (i.e. `a-z, A-Z, 0-10`). 
*   Go back and save the configuration.
*   Create homescreen icon for the `Pass Turn/My Pause` shortcut:
    *   Tap and hold on an empty space on the homscreen. 
    *   Select widgets.
    *   Search for HTTP and select the `HTTP Shortcuts` app.
    *   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`.
*   Select `Open app` and click the configure icon.
*   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 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.
*   Assign unique single characters as **MQTT Triggers** for each player's "Pass Turn / My Pause" action.
*   Assign unique single characters as **MQTT Triggers** for "Global Stop/Pause All" and "Global Run All Timers".