2HoursProject/nexus-timer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

updated readme for remote control

Browse Source
This commit is contained in:
cpu
2025-06-29 22:51:40 +02:00
parent ca3ba141a7
commit 28c7426dcf
1 changed files with 39 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/remote-control.md
View File

@@ -5,10 +5,13 @@
2. [MQTT Remote Control](#mqtt-remote-control) 2. [MQTT Remote Control](#mqtt-remote-control)
- [Mosquitto Installation Guide](#mosquitto-installation-guide) - [Mosquitto Installation Guide](#mosquitto-installation-guide)
- [Android Shortcut Setup](#android-shortcut-setup) - [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 ## 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. * **Buttons:** Connect 3 physical buttons, potentially extended (e.g., via 1.5m wires) for easy player access.
* **Configuration:** * **Configuration:**
@@ -24,9 +27,7 @@ Players can use their smartphones to send commands to Nexus Timer via MQTT. This
### Mosquitto Installation Guide ### Mosquitto Installation Guide
**On Android (using Termux):** 1. **Install Termux** from the [Play Store](https://play.google.com/store/apps/details?id=com.termux) and run.
1. **Install Termux** from the Play Store and run.
2. **Update packages and install Mosquitto in Termux:** 2. **Update packages and install Mosquitto in Termux:**
```bash ```bash
pkg update && pkg upgrade 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:** 3. **Configure the MQTT Broker:**
```bash ```bash
nano ~/.termux/etc/mosquitto/mosquitto.conf nano $PREFIX/etc/mosquitto/mosquitto.conf
``` ```
Add the following configuration, then save and exit: Add the following configuration, then save and exit:
``` ```
listener 1883 0.0.0.0 listener 1883 0.0.0.0
protocol mqtt protocol mqtt
listener 8080 0.0.0.0 listener 9001 0.0.0.0
protocol websockets protocol websockets
allow_anonymous true allow_anonymous true
``` ```
4. **Run Mosquitto with the configuration:** 4. **Run Mosquitto with the configuration:**
```bash ```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://<broker_ip>:<ws_port>`). Nexus Timer defaults to `ws://localhost:9001`.
### Android Shortcut Setup ### 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. * 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). * Advanced Types -> MQTT Shortcut.
* **If HTTP Shortcuts has direct MQTT publish action:** * Shortcut name: `Pass Turn/My Pause`
* Configure Broker URL (e.g., `tcp://<BROKER_IP>:<TCP_PORT>`). * 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.)*
* Set Topic to: `game` * Messages:
* Set Payload to: The single character (e.g., `a`). * Set Topic to: `game`. *(Note: The topic name is hardcoded in the PWA.)*
* Set QoS, Retain as needed (usually 0 and false are fine). * Set Payload to a single character (e.g. `a`). Each player will set a unique character (i.e. `a-z, A-Z, 0-10`).
* **If using scripting with `mosquitto_pub` (via Termux):** * Go back and save the configuration.
* Install Termux and `mosquitto-clients` package (`pkg install mosquitto`). * Create homescreen icon for the `Pass Turn/My Pause` shortcut:
* In HTTP Shortcuts, create a shortcut that executes a script. * Tap and hold on an empty space on the homscreen.
* The script would be something like: `mosquitto_pub -h <BROKER_IP> -p <TCP_PORT> -t game -m "X"` * Select widgets.
* Replace `<BROKER_IP>` with your Mosquitto broker's IP. * Search for HTTP and select the `HTTP Shortcuts` app.
* 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. * Select the icon and assign the `Pass Turn/My Pause` shortcut.
* `-t game`: The topic Nexus Timer listens on. * An icon will appear on the homescreen.
* `-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. * Tap the icon to trigger the game action.
* **Customize Shortcut:** Give the shortcut a name (e.g., "Pass My Turn") and an icon on the Android home screen. ### 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 Setup ### Nexus Timer (PWA) Setup
* Enter the MQTT Broker URL in the Setup screen and connect. * 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 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". * Assign unique single characters as **MQTT Triggers** for "Global Stop/Pause All" and "Global Run All Timers".