# 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 -p -t game -m "X"` * Replace `` with your Mosquitto broker's IP (e.g. `localhost`). * Replace `` 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".