Remote Control System

The remote control module allows administrators to control Android TV devices remotely via WebSocket commands. This is critical for troubleshooting screens without physical access.

Architecture

1. Session: A "Session" is established between a controllerId (admin's browser) and a deviceId.
2. WebSocket: Commands are sent via HTTP/WebSocket to the server, which forwards them to the device via MQTT or direct socket connection.
3. Gestures: The system supports complex gestures (Tap, Swipe, Pinch, Rotate).

API Commands

Session Management

• Start Session: POST /remote-control/:deviceId/session/start

  • Requires controllerId.
  • Used to lock the device control to a specific admin.

• End Session: POST /remote-control/:deviceId/session/end

  • Releases the lock.

Command Execution

The controller supports sending specific gestures:

• tap: Click at x/y coordinates.
• swipe: Drag from startX/Y to endX/Y with duration.
• keypress: Send Android key codes (Home, Back, D-Pad).
• input: Send text input to focused field.

Usage Examples

Tap Button

POST /remote-control/device123/command
{
  "action": "tap",
  "x": 500,
  "y": 300
}

Scroll Down

POST /remote-control/device123/command
{
  "action": "swipe",
  "startX": 500,
  "startY": 800,
  "endX": 500,
  "endY": 200,
  "duration": 300
}

Home Button

POST /remote-control/device123/command
{
  "action": "keypress",
  "keyCode": "KEYCODE_HOME"
}

Troubleshooting

• Status Check: GET /remote-control/:deviceId/status
  • Verifies if the device is online and listening for commands.
• Latency: Commands should be nearly instantaneous (less than 200ms). High latency indicates network issues on the device side.

Security

Requires MANAGE_REMOTE_CONTROL permission. Only online devices can be controlled.

Limitations

• One Session at a Time: Only one admin can control a device simultaneously.
• Timeout: Sessions expire after 5 minutes of inactivity.
• Logging: All commands are logged in CommandHistory for auditing.