From 28c7426dcf1a4cc75fcc98dff7d9b388bdd41bc2 Mon Sep 17 00:00:00 2001 From: cpu Date: Sun, 29 Jun 2025 22:51:40 +0200 Subject: [PATCH] updated readme for remote control --- docs/remote-control.md | 68 ++++++++++++++++++++++++------------------ 1 file changed, 39 insertions(+), 29 deletions(-) diff --git a/docs/remote-control.md b/docs/remote-control.md index 2d12c8f..7fd8152 100644 --- a/docs/remote-control.md +++ b/docs/remote-control.md @@ -5,10 +5,13 @@ 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) + - [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. +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:** @@ -24,9 +27,7 @@ Players can use their smartphones to send commands to Nexus Timer via MQTT. This ### Mosquitto Installation Guide -**On Android (using Termux):** - -1. **Install Termux** from the Play Store and run. +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 @@ -34,45 +35,54 @@ Players can use their smartphones to send commands to Nexus Timer via MQTT. This ``` 3. **Configure the MQTT Broker:** ```bash - nano ~/.termux/etc/mosquitto/mosquitto.conf + nano $PREFIX/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 + listener 9001 0.0.0.0 protocol websockets allow_anonymous true ``` 4. **Run Mosquitto with the configuration:** ```bash - mosquitto -c ~/.termux/etc/mosquitto/mosquitto.conf + mosquitto -c $PREFIX/etc/mosquitto/mosquitto.conf ``` - -* **MQTT Broker:** Needs to be accessible on the local network and configured with a WebSocket listener (e.g., `ws://:`). Nexus Timer defaults to `ws://localhost:9001`. - ### Android Shortcut Setup -* Install the "HTTP Shortcuts" app from the Play Store. +* 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. -* **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://:`). - * 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 -p -t game -m "X"` - * Replace `` with your Mosquitto broker's IP. - * Replace `` 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. +* 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 -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 Setup -* Enter the MQTT Broker URL in the Setup screen and connect. +### 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". \ No newline at end of file