From 8f621bf88b5c4f682cb5aaef9fcae644763843ed Mon Sep 17 00:00:00 2001 From: vshnosngh Date: Wed, 18 Nov 2026 13:06:56 +0530 Subject: [PATCH] docs: add comprehensive README with setup instructions and APK details --- README.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++ local.properties | 1 + 2 files changed, 143 insertions(+) create mode 100644 README.md create mode 100644 local.properties diff --git a/README.md b/README.md new file mode 100644 index 0000000..89a372c --- /dev/null +++ b/README.md @@ -0,0 +1,142 @@ +# Device Trigger — Android Remote Device Control App + +A clean, native Android mobile application designed to remotely control the power states of multiple machines (e.g. servers, Debian/Pop!_OS nodes, lab rigs). + +The app features a **horizontal swipe interface** where each device is represented by a dedicated screen with **three massive, high-contrast, tactile buttons**: +1. 🟢 **POWER ON** — Sends remote power on / wake trigger +2. 🟠 **REBOOT** — Gracefully restarts the remote machine (confirmation protected) +3. 🔴 **POWER OFF** — Shuts down the machine (confirmation protected) + +Endpoints for each machine are loaded dynamically by fetching a lightweight JSON configuration hosted in a **Cloudflare R2** bucket. Critical actions (`poweroff` and `reboot`) authenticate using a device-specific `secretKey`. + +--- + +## 📱 Pre-built Ready-to-Install APK + +The application has been compiled into a ready-to-install debug APK: +``` +app/build/outputs/apk/debug/app-debug.apk +``` + +### Installing on your Android phone via ADB: +```bash +adb install -r app/build/outputs/apk/debug/app-debug.apk +``` +*Or transfer `app-debug.apk` directly to your phone and tap to install.* + +--- + +## 🚀 Key Features + +- **Massive Tactile Buttons**: High-contrast, large touch targets designed to prevent accidental mis-taps while remaining effortless to press. +- **Horizontal Swipe Navigation**: Seamlessly swipe left and right between configured machines with an animated bottom page indicator. +- **Dynamic Cloudflare R2 Configuration**: Simply supply your Cloudflare R2 JSON URL when adding a device; the app fetches and validates endpoint URLs automatically. +- **Multi-Device Support**: Manage any number of remote machines. The last swipe tab is always an **"+ Add Device"** configuration screen. +- **Persistent Local Storage**: Configured machines are safely saved to Android persistent storage (`SharedPreferences`) so they remain available whenever the app is reopened. +- **Mistake-Proof Safety Prompts**: Reboot and Power Off actions trigger a quick confirmation dialog before sending the request. +- **Instant Visual Feedback**: On-screen status banners, in-button loading indicators, and Android Toast notifications display HTTP status codes (e.g., `200 OK`) and server responses. + +--- + +## ⚙️ Cloudflare R2 JSON Specification + +When adding a device, the application downloads and parses a JSON file hosted in your Cloudflare R2 bucket. + +### Example JSON file: +```json +{ + "poweron": "https://cosmos.linuxguy.space/poweron", + "poweroff": "https://cosmos.linuxguy.space/poweroff", + "reboot": "https://cosmos.linuxguy.space/reboot" +} +``` + +*Note: The built-in parser is resilient and automatically accepts key variants such as `power_on`, `powerOn`, `power_off`, `powerOff`, `restart`, and `shutdown`.* + +--- + +## 📡 API Request Specification + +When an action is triggered, the app dispatches an asynchronous HTTP `POST` request using `OkHttp`: + +| Field | Value / Description | +|---|---| +| **HTTP Method** | `POST` | +| **Header 1** | `Content-Type: application/json` | +| **Header 2** | `X-Secret-Key: ` (e.g., `Carbon@12`) | +| **JSON Body** | `{"node": ""}` (e.g., `{"node": "debian"}`) | +| **Timeout** | 15 seconds connect / read / write | + +--- + +## 🛠️ Project Structure + +``` +exp-app/ +├── app/ +│ ├── src/ +│ │ ├── main/ +│ │ │ ├── AndroidManifest.xml +│ │ │ ├── java/com/expapp/trigger/ +│ │ │ │ ├── MainActivity.kt +│ │ │ │ ├── data/ +│ │ │ │ │ ├── model/DeviceConfig.kt +│ │ │ │ │ ├── parser/R2ConfigParser.kt +│ │ │ │ │ └── repository/DeviceRepository.kt +│ │ │ │ ├── network/ +│ │ │ │ │ ├── TriggerClient.kt +│ │ │ │ │ └── TriggerResult.kt +│ │ │ │ └── ui/ +│ │ │ │ ├── components/ +│ │ │ │ │ ├── ActionConfirmDialog.kt +│ │ │ │ │ ├── HugeActionButton.kt +│ │ │ │ │ └── StatusBanner.kt +│ │ │ │ ├── screens/ +│ │ │ │ │ ├── AddDevicePage.kt +│ │ │ │ │ ├── DevicePage.kt +│ │ │ │ │ └── MainScreen.kt +│ │ │ │ └── theme/ +│ │ │ │ ├── Color.kt +│ │ │ │ └── Theme.kt +│ │ │ └── res/ +│ │ │ └── values/ +│ │ │ ├── strings.xml +│ │ │ └── themes.xml +│ │ └── test/java/com/expapp/trigger/ +│ │ ├── data/parser/R2ConfigParserTest.kt +│ │ ├── data/repository/DeviceRepositoryTest.kt +│ │ └── network/TriggerClientTest.kt +│ └── build.gradle.kts +├── docs/superpowers/ +│ ├── specs/2026-11-18-remote-device-trigger-app-design.md +│ └── plans/2026-11-18-remote-device-trigger-app.md +├── build.gradle.kts +├── settings.gradle.kts +├── gradle.properties +├── gradlew +└── gradlew.bat +``` + +--- + +## 💻 Building from Source + +### Prerequisites: +- Java JDK 17 or 21 +- Android SDK (API 34) + +### Run Unit Tests: +```bash +./gradlew testDebugUnitTest +``` + +### Build Debug APK: +```bash +./gradlew assembleDebug +``` +The generated APK will be at `app/build/outputs/apk/debug/app-debug.apk`. + +### Open in Android Studio: +1. Open Android Studio. +2. Select **File -> Open...** and navigate to `/home/creserver/Desktop/Vaishno_workspace/experiments/exp-app`. +3. Allow Gradle sync to complete and click **Run** (Shift+F10) on a connected device or emulator. diff --git a/local.properties b/local.properties new file mode 100644 index 0000000..6a084c0 --- /dev/null +++ b/local.properties @@ -0,0 +1 @@ +sdk.dir=/home/creserver/Android/Sdk