DOCSEARCHbyAlgolia
Submit Docs

KDE Connect Documentation

repository·master·Indexed 26 days ago

https://github.com/kde/kdeconnect-kde

A multi-platform application for seamless communication and feature synchronization between computers (Linux, Windows, macOS, BSD) and mobile devices (Android, iOS). This documentation covers installation, the kdeconnect-cli tool for device management and remote operations, the UI-agnostic core architecture, the Bluetooth multiplexing protocol, and plugin implementations for battery and clipboard synchronization.

Tokens
6.2K
Snippets
6
Records
60
Agent score
84%

What's inside KDE Connect

  1. KDE Connect Architecture Overview

    master

    KDE Connect is built on a UI-agnostic core library that exposes DBus interfaces. This allows different UI components to consume the same core functionality. The core is divided into four main blocks:

    • LinkProviders: Responsible for discovering devices on the network and establishing a Link.
    • Devices: Abstract representations of a remote device, regardless of the underlying Link type.
    • NetworkPackets: Self-contained, JSON-serializable pieces of information used for communication.
    • Plugins: Independent modules that implement specific features by exchanging NetworkPackets.

  2. Understand the Bluetooth Multiplexing Protocol

    master

    The KDE Connect Bluetooth backend uses a multiplexing protocol to allow multiple independent data channels over a single Bluetooth connection. This avoids the limitations of Bluetooth connection counts and allows for simultaneous operations (like file transfers) without blocking other communications.

    Key characteristics:

    • Protocol Agnostic: Works regardless of whether the device is a server or client.
    • Channel-based: Every channel is identified by a unique 16-byte UUID.
    • Default Channel: A single main channel is available immediately with UUID a0d0aaf4-1072-4d81-aa35-902a954b1266 and requires no setup.

  3. Create a new plugin for the KDE Connect Android client

    master

    To implement a new plugin for the Android client (in the kdeconnect-android repository), use the PingPlugin as a template:

    1. Directory Setup:
      • Navigate to src/org/kde/kdeconnect/Plugins.
      • Copy PingPlugin to a new directory name (e.g., FindMyPhonePlugin).
    2. File Renaming and Refactoring:
      • Rename PingPlugin.java to FindMyPhonePlugin.java.
      • Perform case-sensitive replacements: replace Ping with FindMyPhone, ping with findmyphone, PING with FINDMYPHONE, and plugin_ping with plugin_findmyphone.
    3. Resource Configuration:
      • Open res/values/strings.xml.
      • Copy the lines for pref_plugin_ping_desc and pref_plugin_ping.
      • Replace ping with findmyphone in the keys and update the text between the <string> tags to reflect your plugin's name and description.

  5. Install KDE Connect on Linux

    master

    To install KDE Connect on a Linux distribution, search your package manager for one of the following package names:

    • kdeconnect-kde
    • kdeconnect-plasma
    • kdeconnect
    • kde-connect

    Note: You must also install the KDE Connect app on your mobile device (Android or iOS) and pair them within the application to enable communication.

  6. Create a new plugin for the KDE Connect desktop client

    master

    To implement a new plugin for the desktop client, use the existing ping plugin as a template. Follow these steps to set up the project structure and configuration:

    1. Directory Setup:
      • Navigate to the plugins directory.
      • Copy the ping directory to a new name (e.g., findmyphone).
      • Add add_subdirectory(findmyphone) to the main CMakeLists.txt after the existing add_subdirectory calls.
    2. File Renaming:
      • Enter the new plugin directory.
      • Update the local CMakeLists.txt by replacing ping with your new plugin name.
      • Rename all other files in the directory by replacing ping with your new plugin name.
    3. Code Implementation:
      • Edit the README with a description of your plugin.
      • Edit the .cpp and .h files (e.g., findmyphoneplugin.cpp and findmyphoneplugin.h).
      • Update the license header.
      • Perform case-sensitive replacements: replace ping with findmyphone, PingPlugin with FindMyPhonePlugin, and PING with FINDMYPHONE.
    4. Metadata Configuration:
      • Edit the kdeconnect_findmyphone.json file:
        • Replace ping with findmyphone.
        • Update name, description, icon, author, email, version, website, and license info.
        • Remove all translations.
        • Set X-KDEConnect-SupportedPacketType and X-KDEConnect-OutgoingPacketType to your specific packet type (e.g., kdeconnect.findmyphone).
        • Note: Ensure the packet type matches the #define PACKET_TYPE_... in your .h file and the corresponding definition in the Android client.

  7. Install KDE Connect on Windows or macOS

    master
    Official releases for Windows and macOS are not currently available. However, you can compile KDE Connect for Windows using Craft. For macOS, the software is not yet fully tested, but users are encouraged to contribute and provide feedback.

  8. Use the Mousepad plugin for remote cursor control

    master

    The Mousepad plugin allows a user to control a computer's mouse cursor using a mobile device.

    • Cursor Movement: As the user moves the phone, the plugin receives dx and dy values (the relative difference between the last movement and the current movement of the X and Y axes) inside a NetworkPackage. The desktop application uses QCursor to move the mouse cursor according to this relative position.
    • Clicking: Taps or double-taps on the phone simulate mouse button presses using XTestFakeButtonEvent.

  11. Access device contacts via the Contacts plugin

    master

    The Contacts plugin enables communication with a paired device to access its contact list. It supports two primary modes of operation:

    1. Downloading the entire contact list: Retrieves all contacts from the paired device.
    2. Requesting a specific contact: Retrieves details for a single, specific contact.

  12. Use the Pause Music plugin to control media via telephony events

    master

    The Pause Music plugin automatically manages media playback by listening to kdeconnect.telephony events.

    • Pausing: When the plugin detects a ringing or talking event in the event field, it pauses all music and video players reachable via the MPRIS (Media Player Remote Interfacing Specification) interface.
    • Resuming: When a matching package is received with the boolean isCancel set to true, the plugin resumes playback for all previously paused MPRIS sources.