DOCSEARCHbyAlgolia
Submit Docs

VK DeviceHub

repository·master·Indexed 42 days ago

https://github.com/vkcom/devicehub

A device management platform and smartphone test farm (fork of DeviceFarmer/stf) for remotely controlling, monitoring, and managing Android and iOS devices via a web browser. Version 1.5.2 includes features for real-time screen viewing via minicap, device booking, group inventory management, and an OAuth 2.0 protected API for device and user management.

Tokens
78.5K
Snippets
179
Records
238
Agent score
54%

What's inside VK DeviceHub

  1. Overview of VK DeviceHub features

    master

    VK DeviceHub is a fork of DeviceFarmer/stf developed by VK. It provides remote control and management for mobile devices.

    Key Capabilities

    • Database: Uses MongoDB for improved performance and flexibility over RethinkDB.
    • Android Support: Supports SDK levels 10 (Android 2.3.3) through 34 (Android 14), including Wear 5.1, Fire OS, and CyanogenMod. No root access is required.
    • iOS Support: Supports all iOS versions and devices compatible with Appium's WebDriverAgent. Features include simple taps, gestures, physical button simulation, and app installation.
    • Remote Control: Real-time screen viewing (30-40 FPS), rotation support, keyboard input, copy/paste, multi-touch gestures, and drag-and-drop .apk installation.
    • Device Management: Inventory monitoring (battery, hardware specs), device searching, and user identification.
    • Organization: Systems for Partitioning (allocating devices to projects/orgs) and Booking (reserving devices for specific periods), along with group management.
    • User Management: Create/search/delete users, manage permissions, and set group quotas.
    • API: Provides a REST API for programmatic access.

  2. Overview of minicap

    master

    minicap is a tool that provides a socket interface for streaming real-time screen capture data from Android devices. It is designed to be used as a component within larger programs (like STF) for remote control.

    Key Characteristics:

    • Performance: Can achieve 10-20 FPS on older devices and 30-40 FPS on newer devices. For maximum FPS, it is recommended to run minicap at half the real vertical and horizontal resolution.
    • Latency: Features non-zero latency; frames may be one or a few frames behind the physical screen.
    • Frame Delivery: On Android 4.2+, frames are only sent when the screen changes. On older versions, frames are sent as a constant stream.
    • Compatibility: Works without root on SDK 28 (Android 9.0) and lower. Supports Android 2.3 (SDK 9) up to recent versions. Works on Android Wear. Does not support emulators or Android 3.x.

  3. Overview of DeviceHub system components

    master

    DeviceHub is composed of several specialized units that work together to manage device fleets:

    • app: The main UI service. Serves the React frontend, handles authentication redirection, and exposes API endpoints for the frontend.
    • device: Manages device connections, screen streaming, and user interactions.
    • groups-engine: Manages the lifecycle of device groups, membership (users/devices), and consistency.
    • log: Subscribes to log events from connected devices and stores them in the database.
    • prooxy: An HTTP reverse proxy that routes incoming requests to the appropriate backend services (api, app, auth, storage) based on URL paths.
    • reaper: Monitors device worker heartbeats to ensure the present/absent flag in the database remains accurate during unexpected failures or provider shutdowns.

  4. UI Permission Controls and Validation

    master

    VK DeviceHub implements permission enforcement at both the API and UI layers:

    • API Layer: A centralized permission check function evaluates roles hierarchically. API controllers use an allowModerator parameter to determine if specific actions are permitted for moderators.
    • UI Layer: The frontend dynamically renders controls based on the user's permissions. Users with edit permissions (System Admins, Group Owners, or Group Moderators) will see additional controls for managing group membership and moderator assignments.

  5. Communication Flow: Device Lifecycle and Presence

    master

    Device presence is managed through a combination of the Provider, Reaper, and Triproxy units:

    1. Discovery: The Provider (via ADB/Tracker) detects a device and triggers registration, emitting wire.DeviceIntroductionMessage or wire.ProviderMessage through the Triproxy-device layer.
    2. Heartbeat: The Reaper unit listens for wire.DeviceHeartbeatMessage and wire.DeviceIntroductionMessage via ZMQ.
    3. Presence Tracking: The Reaper maintains a TTL (Time-To-Live) state.
      • When a device is detected/bumped, it triggers wire.DevicePresentMessage.
      • When the TTL expires (on on.drop), it triggers wire.DeviceAbsentMessage.
    4. Database Sync: The Reaper uses dbapi.loadPresentDevices to sync the current state with MongoDB.

  6. Understand the VK DeviceHub authorization flow

    master

    VK DeviceHub uses a JWT-based authorization flow. When a user attempts to access an API endpoint (e.g., GET /api/v1/*) without a valid token, the API returns a 401 Unauthorized status. The Single Page Application (SPA) then redirects the browser to an authentication endpoint: /auth/<selected_auth_type>. During this process, the authentication provider issues a JWT, which the browser stores in localStorage. Once the token is stored, the user is redirected back to the application root (GET /), and subsequent requests will include the stored JWT for authorized access.

    sequenceDiagram
browser ->> app: GET /
app -->> browser: Returns SPA
browser ->> api: GET /api/v1/(anything)
api -->> browser: 401 Unauthorized
browser ->> auth: GET /auth/%selected_auth_type%
Note over auth,browser: Authorization flow happens here
browser ->> browser: Stores the jwt in localStorage while on /auth
browser ->> app: GET /

  7. Understand DeviceHub authentication mechanisms

    master

    DeviceHub supports several authentication modules that can be started independently. These modules handle user authentication and generate JWT tokens, which are required for subsequent API requests and WebSocket connections.

    Supported mechanisms:

    • LDAP Authentication: Enterprise directory integration.
    • Mock Authentication: Simple name/email based authentication (ideal for testing).
    • SAML2 Authentication: Single sign-on integration.
    • OAuth2 Authentication: Third-party authentication providers.
    • OpenID Authentication: OpenID Connect authentication.

  8. Configure the device market name in the UI

    master

    The market name displayed in the User Interface is pulled from the device's settings. By default, it attempts to fetch the value from the command settings get global device_name via the vendor's market name.

    To use a different market name in the UI, you must change the device's global settings directly.

  9. How the provider unit manages physical devices

    master

    The provider module tracks and manages physical devices connected to the system via an ADB server. It is responsible for device discovery, worker process management, and system registration.

    Workflow for new device detection:

    1. Discovery: The provider connects to the ADB server and tracks devices.
    2. Filtering: It filters out unwanted devices (e.g., remote devices if disallowed).
    3. Introduction: It sends a DeviceIntroductionMessage to the processor.
    4. Registration: It sets the device type in the database.
    5. Worker Spawning: It spawns a dedicated device worker process to manage the device, allocates ports, and monitors status.

    Communication Pattern:

    • Uses a push socket to send messages to the processor.
    • Uses a sub socket to receive messages from other components.
    • If a worker crashes, the provider can restart it to maintain availability.

  10. How idb architecture works

    master

    idb is a tool for interacting with iOS devices and simulators, consisting of two main components that work in tandem:

    1. idb_cli: A Python 3-based command-line interface that acts as a thin client. It communicates with idb_companion via gRPC using either TCP or Unix Domain Sockets. It does not need to run on the same Mac that the iPhone or iOS Simulator is connected to.
    2. idb_companion: A gRPC server running on macOS (built with Objective-C++). It provides access to native iOS automation APIs by managing the FBSimulatorControl and FBDeviceControl frameworks. It manages a single iOS target (device or simulator) in its gRPC server mode.

    Key capabilities used by the project include log reading, application installation/uninstallation, and file system management.

  11. Understand the role of the processor and websocket units

    master

    DeviceHub relies on two key components for real-time communication:

    • processor: Acts as the communication bridge between the device side and the application side. It routes messages using ZeroMQ sockets and processes messages defined in the system's wire protocol.
    • websocket: Provides real-time communication between the client-side JavaScript (browser) and the server-side ZeroMQ+Protobuf system. It enables UI actions to flow directly to the device management system.

  12. How DeviceHub units communicate

    master

    DeviceHub is a distributed system where different functional processes (referred to as "units") operate independently. These units interact with each other using:

    • ZeroMQ: For high-performance asynchronous messaging.
    • Protocol Buffers: For structured data serialization.

    Each process is treated as a discrete "unit" in the context of deployment and system management.