nexus-timer/docs/remote-control.md

Remote Control Options

Table of Contents

1. HID Smart Buttons
2. MQTT Remote Control
   • Mosquitto Installation Guide
     • Mosquitto MQTT Broker using Termux app
     • Mosquitto MQTT Broker with VPN on Android 16's Native Linux VM
   • Android Shortcut Setup
   • Configure Quick Tap gesture to trigger the shortcut
   • Testing with mosquitto_pub (via Termux)
   • 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 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 and run.
2. Update packages and install Mosquitto in Termux:

   pkg update && pkg upgrade
   pkg install mosquitto
   

3. Configure the MQTT Broker:

   nano $PREFIX/etc/mosquitto/mosquitto.conf
   

   Add the following configuration, then save and exit:

   # 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:

   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.

  sudo apt update && sudo apt upgrade
  

• Next, use the apt package manager to install the Mosquitto broker and the command-line clients.

  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.

  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.

  # 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:

  sudo systemctl restart mosquitto
  

• You can verify that the service is running correctly by checking its status:

  systemctl status mosquitto
  

• (Optional) To have the service not start automatically every time you boot up your Linux VM, you can disable it:

  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.
• 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".