# 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)
    - [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.

## MQTT Remote Control
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

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:
    ```
    listener 1883 0.0.0.0
    protocol mqtt

    listener 9001 0.0.0.0
    protocol websockets

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