> For the complete documentation index, see [llms.txt](https://docs.skypaybd.top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skypaybd.top/system-and-devices/devices-telemetry.md). # Device Health & Telemetry SkyPay relies on a distributed cluster of dedicated Android relay smartphones running the `SkyPay.apk` synchronization service. These devices interface directly with telecommunication networks to capture real-time Mobile Financial Services (MFS) SMS transactions, monitor device connectivity, and report hardware vitals. The **Device Status API** (`/api/v2/device/status`) allows merchants and platform administrators to inspect connection health, operational state, battery level, and last active intervals across single or multiple devices in real time. *** ## 1. Endpoint Details & Authentication * **URL**: `https://core.skypaybd.top/api/v2/device/status` * **Method**: `GET` | `POST` * **Headers**: * `DEVICE-KEYS` (Required): Comma-separated list of active device keys (e.g., `dev_key_01,dev_key_02`). * `Content-Type`: `application/json` *** ## 2. Device State Machine & Lifecycle Logic Every device connected to the SkyPay network transitions through an event-driven state machine based on ping acknowledgments, periodic heartbeat signals, and network availability. ``` ┌──────────────────────────────────────────────┐ │ Device Registered │ └──────────────────────┬───────────────────────┘ │ ┌────────────┴────────────┐ │ IP Assigned? │ ├────────────┬────────────┤ │ No │ Yes │ ▼ ▼ │ [6: Not Connected] [5: Never Active] ▲ │ Valid Heartbeat │ ▼ │ [1: Active (online)] ◄─────────────┐ │ │ │ │ │ Age > 3m (180s) │ │ ▼ │ │ [3: Maybe Active (maybe_online)] │ Pulse │ │ │ Received │ │ Age > 7m (420s) │ (≤180s) │ ▼ │ │ [4: Maybe Inactive (degraded)] │ │ │ │ │ │ Age > 10m (600s) │ │ ▼ │ │ [2: Inactive (offline)] ───────────┘ │ └─────── [0: On Queue (in_queue)] (Ping dispatched, age ≤ 60s) ``` ### Comprehensive Status Code Reference | Status Code | Enum Label | Internal State | Description & Criteria | | ----------- | ------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | **On Queue** | `in_queue` | A telemetry query/ping was recently dispatched to the device and is awaiting acknowledgment (age ≤ 60 seconds). | | `1` | **Active** | `online` | Device is operational, connected, and has transmitted a valid heartbeat within the last **3 minutes** (≤ 180 seconds). | | `2` | **Inactive** | `offline` | Device is completely offline. No valid heartbeat received for over **10 minutes** (> 600 seconds). SMS verifications routed to this device will fail. | | `3` | **Maybe Active** | `maybe_online` | Heartbeat pulse is slightly delayed (last seen between **3 to 7 minutes** ago / 180s–420s). May indicate intermittent network connectivity. | | `4` | **Maybe Inactive** | `degraded` | Heartbeat interrupted. Device has not reported in **7 to 10 minutes** (420s–600s). Device requires inspection. | | `5` | **Never Active** | `never_active` | Device has an IP address assigned in the database but has never successfully transmitted a verified telemetry payload. | | `6` | **Not Connected** | `failed` | Application is not linked to the device hardware (device IP address is absent from registry). | *** ## 3. Thresholds & Operational SLAs | Threshold Metric | Duration Window | Evaluation Interval | Action Triggered | | -------------------------- | ------------------ | ------------------- | ----------------------------------------------------------------------------- | | **Heartbeat Frequency** | 30 seconds | Continuous | Android relay pushes ping to Firestore / Core Engine. | | **Ping Queue Window** | 60 seconds | On Status Query | Marks device as `in_queue` (`0`) while awaiting response. | | **Healthy Online Window** | 0 to 180 seconds | Real-Time | State evaluates as `online` (`1`). Active payment routing enabled. | | **Slight Delay Warning** | 180 to 420 seconds | Real-Time | State evaluates as `maybe_online` (`3`). Warning alert logged. | | **Critical Delay Warning** | 420 to 600 seconds | Real-Time | State evaluates as `degraded` (`4`). Administrator alert pushed. | | **Offline Failover** | > 600 seconds | Real-Time | State evaluates as `offline` (`2`). Transactions routed to backup SIM device. | *** ## 4. Downtime Calculation Algorithm SkyPay computes elapsed hardware downtime and human-readable `last_active` strings using high-precision timestamp subtraction: $$\Delta t = t\_{ ext{current}} - t\_{ ext{last\_heartbeat}}$$ ### Elapsed Interval Formatting Algorithm ``` IF last_heartbeat IS NULL THEN RETURN "never" ELSE IF Δt < 60 seconds THEN RETURN "now" ELSE IF Δt < 3,600 seconds (1 hour) THEN RETURN floor(Δt / 60) + "m" ELSE IF Δt < 86,400 seconds (24 hours) THEN RETURN floor(Δt / 3600) + "h" ELSE IF Δt < 604,800 seconds (7 days) THEN RETURN floor(Δt / 86400) + "d" ELSE IF Δt < 2,592,000 seconds (30 days) THEN RETURN floor(Δt / 604800) + "w" ELSE IF Δt < 31,536,000 seconds (365 days) THEN RETURN floor(Δt / 2592000) + "mo" ELSE RETURN floor(Δt / 31536000) + "y" END IF ``` *** ## 5. Telemetry Payload & Vitals Metadata In addition to connectivity states, modern SkyPay relay devices transmit deep hardware vitals: ### Telemetry Vitals Schema | Attribute | Type | Example | Description | | --------------- | ------- | ------------------ | ------------------------------------------------------------------- | | `name` | String | `"POS Terminal 1"` | Configured label of the Android relay device. | | `status` | Integer | `1` | Operational state integer (`0` to `6`). | | `last_active` | String | `"now"` | Formatted time interval since last pulse. | | `battery_level` | Integer | `92` | Current battery percentage (`0` to `100`). | | `is_charging` | Boolean | `true` | AC charger connection status. | | `temperature_c` | Float | `34.2` | Internal hardware temperature in Celsius. | | `network_type` | String | `"WiFi"` | Connection channel (`WiFi`, `LTE`, `3G`). | | `signal_dbm` | Integer | `-68` | Cellular signal strength in dBm (-50 dBm excellent, -110 dBm poor). | | `app_version` | String | `"2.4.1"` | Installed version of `SkyPay.apk`. | ### Example Query & Response #### Request (cURL) ```bash curl -X GET "https://core.skypaybd.top/api/v2/device/status" \ -H "DEVICE-KEYS: dev_key_pos_01,dev_key_pos_02,dev_key_backup" ``` #### Success Response (HTTP 200 OK) ```json { "status": true, "results": [ { "name": "POS Terminal 1 (Main bKash)", "last_active": "now", "status": 1, "battery_level": 98, "is_charging": true, "network_type": "WiFi", "signal_dbm": -62, "app_version": "2.4.1" }, { "name": "POS Terminal 2 (Nagad Relay)", "last_active": "4m", "status": 3, "battery_level": 84, "is_charging": true, "network_type": "LTE", "signal_dbm": -88, "app_version": "2.4.1" }, { "name": "Backup SIM Device", "last_active": "15m", "status": 2, "battery_level": 12, "is_charging": false, "network_type": "None", "signal_dbm": 0, "app_version": "2.3.9" } ] } ``` *** ## 6. Device Error Responses ### Missing Header (HTTP 400 Bad Request) ```json { "status": false, "message": "DEVICE-KEYS header is required." } ``` ### No Matching Devices (HTTP 404 Not Found) Triggered when none of the supplied keys correspond to an existing or active device in your merchant portfolio: ```json { "status": false, "message": "No matching valid devices found for the provided keys." } ``` ### Method Not Allowed (HTTP 405) ```json { "status": false, "message": "Method not allowed. Only GET or POST requests are accepted." } ``` *** ## 7. Hardware Watchdog & Operational Best Practices To guarantee uninterrupted transaction processing and prevent device dropouts: 1. **Disable Battery Optimization**: On Android, navigate to `Settings > Apps > SkyPay > Battery` and select **Unrestricted**. 2. **Prevent Doze Mode**: Ensure the SkyPay app has permission to ignore battery optimizations and maintain foreground wake-locks. 3. **Smart Plug Power Cycling**: Constant 100% battery float charge can cause lithium battery swelling. Use a smart plug or hardware timer to cycle power between 20% and 80% state of charge. 4. **Dual SIM Redundancy**: Pair phones equipped with dual physical SIMs to maintain both bKash and Nagad reception on a single hardware chassis. *** ## 8. Next Steps Review standard error handling across all platform endpoints: * [← Previous: Webhooks (IPN)](/integration-and-api/webhooks.md) * [Next: Error Reference →](/system-and-devices/error-codes.md)