2HoursProject/nexus-timer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
e8ebb23678c6fe657530fccadca01aa8933c3352
nexus-timer/docs/remote-control.md

188 lines
8.1 KiB
Markdown
Raw Blame History

# 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)
- [Mosquitto MQTT Broker on Android 16's Native Linux VM](#mosquitto-mqtt-broker-on-android-16s-native-linux-vm)
- [Mosquitto MQTT Broker on older versions of Android then 16](#mosquitto-mqtt-broker-on-older-versions-of-android-then-16)
- [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
#### Mosquitto MQTT Broker 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. For older versions proceed to [Mosquitto MQTT Broker on older versions of Android then 16](#mosquitto-mqtt-broker-on-older-versions-of-android-then-16).
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.
```bash
sudo apt update && sudo apt upgrade
```
* Next, use the `apt` package manager to install the Mosquitto broker and the command-line clients.
```bash
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.
```bash
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.
```ini
# 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:
```bash
sudo systemctl restart mosquitto
```
* You can verify that the service is running correctly by checking its status:
```bash
systemctl status mosquitto
```
* (Optional) To have the service not start automatically every time you boot up your Linux VM, you can disable it:
```bash
sudo systemctl disable mosquitto
```
Your Mosquitto MQTT broker is now successfully configured and running on your Android 16 device.
---
#### Mosquitto MQTT Broker on older versions of Android then 16
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:
```ini
# 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:**
```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 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".
Reference in New Issue View Git Blame Copy Permalink