# 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)
    - [Nexus Timer Setup](#nexus-timer-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.

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

**On Android (using Termux):**

1. **Install Termux** from the Play Store 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 ~/.termux/etc/mosquitto/mosquitto.conf
    ```
    Add the following configuration, then save and exit:
    ```
    listener 1883 0.0.0.0
    protocol mqtt

    listener 8080 0.0.0.0
    protocol websockets

    allow_anonymous true
    ```
4. **Run Mosquitto with the configuration:**
    ```bash
    mosquitto -c ~/.termux/etc/mosquitto/mosquitto.conf
    ```

*   **MQTT Broker:** Needs to be accessible on the local network and configured with a WebSocket listener (e.g., `ws://<broker_ip>:<ws_port>`). Nexus Timer defaults to `ws://localhost:9001`.

### Android Shortcut Setup
*   Install the "HTTP Shortcuts" app from the Play Store.
*   Create a new shortcut.
*   **Shortcut Type:** Choose "Execute Script" or a type that allows MQTT publishing (some versions might have direct MQTT support, or you can use Termux with `mosquitto_pub` called by the script).
*   **If HTTP Shortcuts has direct MQTT publish action:**
    *   Configure Broker URL (e.g., `tcp://<BROKER_IP>:<TCP_PORT>`).
    *   Set Topic to: `game`
    *   Set Payload to: The single character (e.g., `a`).
    *   Set QoS, Retain as needed (usually 0 and false are fine).
*   **If using scripting with `mosquitto_pub` (via Termux):**
    *   Install Termux and `mosquitto-clients` package (`pkg install mosquitto`).
    *   In HTTP Shortcuts, create a shortcut that executes a script.
    *   The script would be something like: `mosquitto_pub -h <BROKER_IP> -p <TCP_PORT> -t game -m "X"`
        *   Replace `<BROKER_IP>` with your Mosquitto broker's IP.
        *   Replace `<TCP_PORT>` with Mosquitto's TCP port (e.g., 1883). Note: `mosquitto_pub` uses TCP, while the PWA uses WebSockets to connect to the *same* broker.
        *   `-t game`: The topic Nexus Timer 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.
*   **Customize Shortcut:** Give the shortcut a name (e.g., "Pass My Turn") and an icon on the Android home screen.

### Nexus Timer Setup
*   Enter the MQTT Broker URL 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".