KDEConnect: Difference between revisions

From KDE Community Wiki
m (→‎Installing Using prefix.sh: Change title casing)
(Some formatting fixes and preparation for proper Usage section)
Line 1: Line 1:
<languages />
<languages />
<translate>
<translate>
This is the community page for KDE Connect. Feel free to edit it! It should contain useful and up to date resources for both users and developers.
This is the community page for '''KDE Connect'''. Feel free to edit it! It should contain useful and up-to-date resources for both users and developers.


== What is KDE Connect? ==
== What is KDE Connect? ==


KDE Connect is a project that enables all your devices to communicate with each other. Here are a few things KDE Connect can do:
'''KDE Connect''' is a project that enables all your devices to communicate with each other. Here are a few things '''KDE Connect''' can do:
* Receive your phone notifications on your desktop computer and reply to messages
* Receive your phone notifications on your desktop computer and reply to messages
* Control music playing on your desktop from your phone
* Control music playing on your desktop from your phone
Line 17: Line 17:




To achieve this, KDE Connect:
To achieve this, '''KDE Connect''':
* implements a secure communication protocol over the network, and allows any developer to create plugins on top of it.
* implements a secure communication protocol over the network, and allows any developer to create plugins on top of it.
* Has a component that you install on your desktop.
* Has a component that you install on your desktop.
Line 29: Line 29:
== Installation ==
== Installation ==


You will most likely find the KDE Connect desktop component as a package in your distribution's repos. If not you can ask them to package it.
You will most likely find the '''KDE Connect''' desktop component as a package in your distribution's repos. If not, you can ask them to package it.


Despite a common misconception you can use KDE Connect on all desktop environments. Since most of the developers are using Plasma it may occur that a feature is broken or inaccessible on other desktop environments. In this case, please report it as a [https://bugs.kde.org/enter_bug.cgi?product=kdeconnect bug]. There are multiple ways to enhance the KDE Connect experience on non-Plasma desktops. If you are a GNOME user you might prefer [https://extensions.gnome.org/extension/1319/gsconnect/ GSConnect], a GNOME shell extension. For desktops with AppIndicator support (Budgie, Cinnamon, LXDE, Pantheon, Unity) [https://github.com/Bajoja/indicator-kdeconnect indicator-kdeconnect] is available.
Despite common misconception, you can use '''KDE Connect''' on all desktop environments. Since most the developers are using Plasma, it may occur that a feature is broken or inaccessible on other desktop environments. In this case, please file a [https://bugs.kde.org/enter_bug.cgi?product=kdeconnect bug report]. There are multiple ways to enhance the '''KDE Connect''' experience on non-Plasma desktops. If you are a GNOME user you might prefer [https://extensions.gnome.org/extension/1319/gsconnect/ GSConnect], a GNOME shell extension. For desktops with AppIndicator support (Budgie, Cinnamon, LXDE, Pantheon, Unity) [https://github.com/Bajoja/indicator-kdeconnect indicator-kdeconnect] is available.


The app for Android can be found in both the [https://play.google.com/store/apps/details?id=org.kde.kdeconnect_tp Google Play Store] and the free and open store [https://f-droid.org/repository/browse/?fdid=org.kde.kdeconnect_tp F-Droid].
The app for Android can be found in both the [https://play.google.com/store/apps/details?id=org.kde.kdeconnect_tp Google Play Store] and the free and open store [https://f-droid.org/repository/browse/?fdid=org.kde.kdeconnect_tp F-Droid].


There was some development of a KDE Connect client app for iOS in 2014 (see [https://cgit.kde.org/scratch/yangqiao/kdeconnect-ios.git/ source code]) but due to our experience and various technical and organizational factors it's unlikely that we will have official iOS support anytime soon.
There was some development of a '''KDE Connect''' client app for iOS in 2014 (see [https://cgit.kde.org/scratch/yangqiao/kdeconnect-ios.git/ source code]) but due to our experience and various technical and organizational factors it's unlikely that we will have official iOS support anytime soon.


KDE Connect is also available on [https://openrepos.net/content/piggz/kde-connect SailfishOS] and we are working on bringing it to other Linux-based phones (Plasma Mobile, PostmarketOS etc.)
'''KDE Connect''' is also available on [https://openrepos.net/content/piggz/kde-connect SailfishOS] and we are working on bringing it to other Linux-based phones (Plasma Mobile, PostmarketOS etc.)
 
== Usage ==
 
Please see the '''KDE Connect''' [https://userbase.kde.org/KDEConnect Userbase page] for detailed information on the different ways '''KDE Connect''' can be used.


== Browser Integration ==
== Browser Integration ==


[https://community.kde.org/Plasma/Browser_Integration Plasma Browser Integration] makes KDE Connect even more powerful. It allows you to control content from e.g. Youtube or Netflix from your phone and send browser tabs to your phone. Despite the name, it can also be used on non-Plasma desktops.
[https://community.kde.org/Plasma/Browser_Integration Plasma Browser Integration] makes '''KDE Connect''' even more powerful. It allows you to control content from e.g. Youtube or Netflix from your phone and send browser tabs to your phone. Despite the name, it can also be used on non-Plasma desktops.


== Running KDE Connect over OpenVPN ==
== Running KDE Connect over OpenVPN ==
There may be a variety of reasons for using KDE Connect with a VPN. Maybe you have left home and want to run a command or maybe you’re on a public wifi network where your devices aren’t allowed to communicate and you want to use remote control to give a presentation.


=== Set up Open VPN ===
There may be a variety of reasons for using '''KDE Connect''' with a VPN. Maybe you have left home and want to run a command, or maybe you’re on a public wifi network where your devices aren’t allowed to communicate and you want to use remote control to give a presentation.
If you have your own server with a public-facing IP address, you can set up OpenVPN yourself. OpenVPN is not the easiest piece of software to set up, but by following a setup tutorial such as this one, you should be able to manage: https://openvpn.net/howto.html
 
=== Set up OpenVPN ===


In order to allow UDP broadcast packets, which are what KDE Connect uses to automatically discover two devices, OpenVPN needs to be set up for bridging (TAP device). If you use a tun device, you can still manually connect by IP address.
If you have your own server with a public-facing IP address, you can set up '''OpenVPN''' yourself. It is not the easiest piece of software to set up, but by following a setup tutorial such as this one, you should be able to manage: https://openvpn.net/howto.html


If you want to rent a pre-configured OpenVPN service rather than set up your own it should work, but the same considerations about the server settings need to be taken into account.
In order to allow UDP broadcast packets, which are what '''KDE Connect''' uses to automatically discover two devices, '''OpenVPN''' needs to be set up for bridging (TAP device). If you use a tun device, you can still manually connect by IP address.


Once the server is running, you can use the official OpenVPN client to connect the desktop to the server. There is no official OpenVPN client for Android, but I find that the OpenVPN for Android client works well: https://play.google.com/store/apps/details?id=de.blinkt.openvpn
If you want to rent a pre-configured '''OpenVPN''' service rather than set up your own, it should work, but the same considerations about the server settings need to be taken into account.
 
Once the server is running, you can use the official '''OpenVPN''' client to connect the desktop to the server. There is no official '''OpenVPN''' client for Android, but the '''OpenVPN for Android''' client works well: https://play.google.com/store/apps/details?id=de.blinkt.openvpn


Once both devices are connected, test that they are able to communicate over the VPN by trying to do a network ping between them.
Once both devices are connected, test that they are able to communicate over the VPN by trying to do a network ping between them.


=== Configure KDE Connect ===
=== Configure KDE Connect ===
If your OpenVPN instance is set up for bridging, KDE Connect should work just like on a local network


If you are using OpenVPN with a tun device, you will have to manually add your devices by IP. Then, once you connect to the VPN, KDE Connect should automatically detect your device and either connect or be ready for pairing!
If your '''OpenVPN''' instance is set up for bridging, '''KDE Connect''' should work just like on a local network.
 
If you are using '''OpenVPN''' with a tun device, you will have to manually add your devices by IP. Then, once you connect to the VPN, '''KDE Connect''' should automatically detect your device and either connect or be ready for pairing!


== Building KDE Connect ==
== Building KDE Connect ==
If you want to build KDE Connect yourself, you'll first need to grab the code from git.   
If you want to build KDE Connect yourself, you'll first need to grab the code from git.   
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
Line 68: Line 76:
</syntaxhighlight>
</syntaxhighlight>


Note: if you plan to contribute code to KDE Connect, please follow the steps in [[KDEConnect#Setting_up_KDE_Connect_Repository_for_Development]]
Note: if you plan to contribute code to '''KDE Connect''', please follow the steps in [[KDEConnect#Setting_up_KDE_Connect_Repository_for_Development]]


=== Linux Desktop ===
=== Linux Desktop ===
KDE Connect uses cmake as a build system, which will tell you if you are missing any dependencies. On some distros you will need to install some development packages. Sometimes you will need to get the dependencies by yourself because the development branch of KDE Connect often uses new libraries not included in distro repositories, in which case you can build those yourself or use kdesrc-build. Helpfully, some package managers have a command which will automatically fetch the dependencies for you:
 
'''KDE Connect''' uses cmake as a build system, which will tell you if you are missing any dependencies. On some distros you will need to install some development packages. Sometimes you will need to get the dependencies by yourself because the development branch of '''KDE Connect''' often uses new libraries not included in distro repositories, in which case you can build those yourself or use kdesrc-build. Helpfully, some package managers have a command which will automatically fetch the dependencies for you:


<b> For Ubuntu </b>
<b> For Ubuntu </b>
Line 94: Line 103:


==== Installing using prefix.sh ====
==== Installing using prefix.sh ====
For development, it is recommended to install to your home directory using prefix.sh. This gives a faster development cycle and avoids clobbering your system-installed version with a potentially unstable WIP version.
For development, it is recommended to install to your home directory using prefix.sh. This gives a faster development cycle and avoids clobbering your system-installed version with a potentially unstable WIP version.


Line 120: Line 130:


==== Installing to the System ====
==== Installing to the System ====
If you want to use the new version of KDE Connect daily, you can install it to the system. This is not recommended for day-to-day development since it requires <code>sudo</code> access.
 
If you want to use the new version of '''KDE Connect daily''', you can install it to the system. This is not recommended for day-to-day development since it requires <code>sudo</code> access.


To configure use
To configure use
Line 134: Line 145:
sudo make install
sudo make install
</syntaxhighlight>
</syntaxhighlight>
Note that this will override the KDE Connect provided by your distro
Note that this will override the '''KDE Connect''' provided by your distro


If you are intending to develop KDE Connect or experience a crash and are asked to give a backtrace, build KDE Connect with debugging symbols:
If you intend to develop '''KDE Connect''' or experience a crash and are asked to give a backtrace, build '''KDE Connect''' with debugging symbols:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug ..
cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug ..
</syntaxhighlight>
</syntaxhighlight>


If you install KDE Connect in a custom location you'll need to run <code>kdeconnectd</code> manually, since DBus doesn't know about it.
If you install '''KDE Connect''' in a custom location, you'll need to run <code>kdeconnectd</code> manually, since DBus doesn't know about it.


For instruction on how to integrate the build with KDevelop check out this [https://nicolasfella.wordpress.com/2018/03/30/building-kde-connect/ blog post]
For instructions on how to integrate the build with '''KDevelop''', check out this [https://nicolasfella.wordpress.com/2018/03/30/building-kde-connect/ blog post].


=== Android ===
=== Android ===
You can find the code on [https://invent.kde.org/kde/kdeconnect-android Invent]. It's easiest to use Android Studio to build the app and install it to your phone, although it can be done on the command line using gradle.


Running KDE Connect in the emulator is possible, but needs an advanced networking setup. See the guide posted for the [[/Android_Emulator/]]
You can find the code on [https://invent.kde.org/kde/kdeconnect-android Invent]. It's easiest to use '''Android Studio''' to build the app and install it to your phone, although it can be done on the command line using gradle.
 
Running '''KDE Connect''' in the emulator is possible, but needs an advanced networking setup. See the guide posted for the [[/Android_Emulator/]]


=== Windows ===
=== Windows ===
KDE Connect works quite well on Windows, with many features ported.
 
'''KDE Connect''' works quite well on Windows, with many features ported.
See [https://community.kde.org/KDEConnect/Build_Windows here] for build instructions
See [https://community.kde.org/KDEConnect/Build_Windows here] for build instructions


=== MacOS ===
=== MacOS ===
KDE Connect works fairly well on macOS. But there is not yet an official release for it. See [https://community.kde.org/KDEConnect/Build_MacOS here] for build instructions.


You can get the Nightly Build from [https://binary-factory.kde.org/view/MacOS/job/kdeconnect-kde_Nightly_macos/ Binary Factory]
'''KDE Connect''' works fairly well on macOS. But there is no official release for it yet. See [https://community.kde.org/KDEConnect/Build_MacOS here] for build instructions.
 
You can get the Nightly Build from the [https://binary-factory.kde.org/view/MacOS/job/kdeconnect-kde_Nightly_macos/ Binary Factory]


=== Mobile-Friendly QML App ===
=== Mobile-Friendly QML App ===
KDE Connect provides an alternative mobile-friendly interface, targeted at mobile Linux platforms such as Plasma Mobile. The app is usable on the desktop as well. It is built from the same sources as the desktop component. The build steps are mostly the same, just one additional step is needed to enable building the app.
 
'''KDE Connect''' provides an alternative mobile-friendly interface, targeted at mobile Linux platforms such as Plasma Mobile. The app is usable on the desktop as well. It is built from the same sources as the desktop component. The build steps are mostly the same, just one additional step is needed to enable building the app.


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
Line 170: Line 185:


=== Desktop SMS Messaging App ===
=== Desktop SMS Messaging App ===
KDE Connect has an SMS Messaging app which lets you type and view SMS messages from your computer. It supports basic features and works correctly most of the time. If you are interested in trying it or developing it, you can build it from source. It is automatically built as part of the rest of KDE Connect and is output as 'kdeconnect-sms'.
 
'''KDE Connect''' has an SMS messaging app which lets you type and view SMS messages from your computer. It supports basic features and works correctly most of the time. If you are interested in trying or developing it, you can build it from source. It is automatically built as part of the rest of '''KDE Connect''' and is output as 'kdeconnect-sms'.


== Troubleshooting ==
== Troubleshooting ==


=== I have two devices running KDE Connect on the same network, but they can't see each other ===  
=== I have two devices running KDE Connect on the same network, but they can't see each other ===
KDE Connect uses dynamic ports in the range 1714-1764 for UDP and TCP. So if you are behind a firewall, make sure to open this port range for both TCP and UDP. Otherwise, make sure your network is not blocking UDP broadcast packets.
 
'''KDE Connect''' uses dynamic ports in the range 1714-1764 for UDP and TCP. So if you are behind a firewall, make sure to open this port range for both TCP and UDP. Otherwise, make sure your network is not blocking UDP broadcast packets.


==== ufw ====
==== ufw ====
Line 198: Line 215:


==== Fedora firewall ====
==== Fedora firewall ====
In Fedora there is a program to configure the firewall. Open Firewall Configuration (the program's filename is <code>firewall-config</code>), and in '''Zones''' ➔ '''Services''' check the kde-connect service.
 
In Fedora, there is an utility for configuring the firewall. Open Firewall Configuration (the program's filename is <code>firewall-config</code>), and in '''Zones''' ➔ '''Services''' check the kde-connect service.


Make sure you have chosen the '''Permanent''' Configuration in the drop-down at the top, otherwise these settings will be reset upon reboot.
Make sure you have chosen the '''Permanent''' Configuration in the drop-down at the top, otherwise these settings will be reset upon reboot.


==== iptables ====
==== iptables ====
 
If your firewall is '''iptables''', you can open the necessary ports with:
If your firewall is '''iptables''', you can open the necessary ports with:
   
   
Line 215: Line 232:
</syntaxhighlight>
</syntaxhighlight>


===  My KDE Connect crashes or restarts when trying to pair with another device ===
===  KDE Connect crashes or restarts when trying to pair with another device ===
Sometimes, a corrupt config file may cause KDE Connect to crash when trying to pair with a device. In that case, deleting the config  ~/.config/kdeconnect might help.
 
Sometimes, a corrupt config file may cause '''KDE Connect''' to crash when trying to pair with a device. In that case, deleting the config  ~/.config/kdeconnect might help.
 
===  Can I run KDE Connect without a display server? ===


===  Can I run KDE Connect without a display server? ===
Yes, you can pass the command line argument `-platform offscreen` to the daemon (eg: `killall -9 kdeconnectd; /usr/lib/libexec/kdeconnectd -platform offscreen`)
Yes, you can pass the command line argument `-platform offscreen` to the daemon (eg: `killall -9 kdeconnectd; /usr/lib/libexec/kdeconnectd -platform offscreen`)


=== Running kdeconnect on an emulator ===
=== Running KDE Connect on an emulator ===
How to setup running kdeconnect on an emulator is described here [[/Android_Emulator/]]
 
How to setup running '''KDE Connect''' on an emulator is described here [[/Android_Emulator/]]


=== GSConnect ===
=== GSConnect ===
GSConnect is an independent project which implements the KDE Connect protocol and uses the same Android app. If you are running GSConnect, please visit that project's [https://github.com/andyholmes/gnome-shell-extension-gsconnect/wiki GitHub page] first for support. If you and the GSConnect team determine the issue is the Android app or protocol, feel free to report those in the KDE Connect bug tracker.


===  My problem is not in this list :( ===  
'''GSConnect''' is an independent project which implements the '''KDE Connect''' protocol into GNOME and uses the same Android app. If you are running '''GSConnect''', please visit that project's [https://github.com/andyholmes/gnome-shell-extension-gsconnect/wiki GitHub page] first for support. If you and the '''GSConnect''' team determine the issue is the Android app or protocol, feel free to report those in the '''KDE Connect''' bug tracker.
 
===  My problem is not in this list :( ===
 
In case you find a bug and want to report it, you can do so in the [https://bugs.kde.org/enter_bug.cgi?product=kdeconnect KDE bug tracker].
In case you find a bug and want to report it, you can do so in the [https://bugs.kde.org/enter_bug.cgi?product=kdeconnect KDE bug tracker].


== Development ==
== Development ==
KDE Connect is a perfect project to start contributing to KDE. You'll need a basic understanding of programming concepts, the rest can be learned by doing. Experience with Android or Qt is beneficial, but not needed.
 
'''KDE Connect''' is a perfect project to start contributing to KDE. You'll need a basic understanding of programming concepts, the rest can be learned by doing. Experience with Android or Qt is beneficial, but not needed.


We have a group to discuss development. You can access it from [https://t.me/joinchat/BRUUN0bwMhNfn8FIejA-nw Telegram], IRC (#kdeconnect) or matrix.org (#freenode_#kdeconnect:matrix.org). Feel free to ask any development-related questions there. We also have a  [https://mail.kde.org/mailman/listinfo/kdeconnect mailing list].
We have a group to discuss development. You can access it from [https://t.me/joinchat/BRUUN0bwMhNfn8FIejA-nw Telegram], IRC (#kdeconnect) or matrix.org (#freenode_#kdeconnect:matrix.org). Feel free to ask any development-related questions there. We also have a  [https://mail.kde.org/mailman/listinfo/kdeconnect mailing list].


All patches are submitted on Gitlab. The Android repository is [https://invent.kde.org/kde/kdeconnect-android here] and the C++ Desktop repository is [https://invent.kde.org/kde/kdeconnect-kde here]. Be sure to select the most relevant template. You don't need to assign any reviewers, the developers are subscribed to notifications. Should this be your first patch, it's good to know that it might take some time before your patch is reviewed (we all work on KDE Connect in our free time), and you'll probably have to make some changes a couple of times. That's not because you're new, that's what happens for all reviews (even for long-time contributors).
All patches are submitted on Gitlab. The Android repository is [https://invent.kde.org/kde/kdeconnect-android here] and the C++ Desktop repository is [https://invent.kde.org/kde/kdeconnect-kde here]. Be sure to select the most relevant template. You don't need to assign any reviewers, the developers are subscribed to notifications. Should this be your first patch, it's good to know that it might take some time before your patch is reviewed (we all work on '''KDE Connect''' in our free time), and you'll probably have to make some changes a couple of times. That's not because you're new, that's what happens for all reviews (even for long-time contributors).


There are a couple of tasks marked as Junior Jobs on our [https://phabricator.kde.org/project/board/159/ workboard]. Those have some extra information on how to approach them that help you get started.
There are a couple of tasks marked as Junior Jobs on our [https://phabricator.kde.org/project/board/159/ workboard]. Those have some extra information on how to approach them that help you get started.
Line 241: Line 264:
=== Setting up KDE Connect Repository for Development ===
=== Setting up KDE Connect Repository for Development ===


KDE Connect is actually composed of two repositories; one for the Android implementation and one for the C++ (Desktop) implementation. You can have a local clone of both on your computer and the steps to set them up are the same. For these directions, I will use the C++ repository, but if you want the Android repository, just replace every instance of 'kdeconnect-kde' with 'kdeconnect-android'
'''KDE Connect''' is actually composed of two repositories; one for the Android implementation and one for the C++ (Desktop) implementation. You can have a local clone of both on your computer and the steps to set them up are the same. For these directions, I will use the C++ repository, but if you want the Android repository, just replace every instance of 'kdeconnect-kde' with 'kdeconnect-android'


# Fork the repository
# Fork the repository
Line 259: Line 282:


==== Set up second remote (Optional) ====
==== Set up second remote (Optional) ====
Having a second remote allows you to have your local 'master' branch track the upstream kdeconnect-kde master branch, so you can easily get all the latest changes.
Having a second remote allows you to have your local 'master' branch track the upstream kdeconnect-kde master branch, so you can easily get all the latest changes.


Line 276: Line 300:


====Restarting the daemon====
====Restarting the daemon====
Whenever you do a change to KDE Connect you need to restart the daemon for the change to take effect.  
Whenever you do a change to KDE Connect you need to restart the daemon for the change to take effect.  
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
Line 283: Line 308:


====DBus inspection====
====DBus inspection====
The daemon communicates with various UI components (Plasmoid, CLI, Indicator etc.) over DBus. QDbusViewer allows inspecting the DBus interface provided by the daemon which can be incredibly useful for debugging.
The daemon communicates with various UI components (Plasmoid, CLI, Indicator etc.) over DBus. QDbusViewer allows inspecting the DBus interface provided by the daemon which can be incredibly useful for debugging.
   
   
</translate>
</translate>

Revision as of 20:18, 10 September 2019

<languages /> <translate> This is the community page for KDE Connect. Feel free to edit it! It should contain useful and up-to-date resources for both users and developers.

What is KDE Connect?

KDE Connect is a project that enables all your devices to communicate with each other. Here are a few things KDE Connect can do:

  • Receive your phone notifications on your desktop computer and reply to messages
  • Control music playing on your desktop from your phone
  • Use your phone as a remote control for your desktop
  • Run predefined commands on your PC from connected devices. See the list of example commands for more details.
  • Check your phones battery level from the desktop
  • Ring your phone to help finding it
  • Share files and links between devices
  • Browse your phone from the desktop
  • Control the desktop's volume from the phone


To achieve this, KDE Connect:

  • implements a secure communication protocol over the network, and allows any developer to create plugins on top of it.
  • Has a component that you install on your desktop.
  • Has a KDE Connect client app you run on your phone.


This video from 2013 demonstrates some other cool features: https://www.youtube.com/watch?v=KkCFngNmsh0

More info at Albert Vaka's or Nico's blog.

Installation

You will most likely find the KDE Connect desktop component as a package in your distribution's repos. If not, you can ask them to package it.

Despite common misconception, you can use KDE Connect on all desktop environments. Since most the developers are using Plasma, it may occur that a feature is broken or inaccessible on other desktop environments. In this case, please file a bug report. There are multiple ways to enhance the KDE Connect experience on non-Plasma desktops. If you are a GNOME user you might prefer GSConnect, a GNOME shell extension. For desktops with AppIndicator support (Budgie, Cinnamon, LXDE, Pantheon, Unity) indicator-kdeconnect is available.

The app for Android can be found in both the Google Play Store and the free and open store F-Droid.

There was some development of a KDE Connect client app for iOS in 2014 (see source code) but due to our experience and various technical and organizational factors it's unlikely that we will have official iOS support anytime soon.

KDE Connect is also available on SailfishOS and we are working on bringing it to other Linux-based phones (Plasma Mobile, PostmarketOS etc.)

Usage

Please see the KDE Connect Userbase page for detailed information on the different ways KDE Connect can be used.

Browser Integration

Plasma Browser Integration makes KDE Connect even more powerful. It allows you to control content from e.g. Youtube or Netflix from your phone and send browser tabs to your phone. Despite the name, it can also be used on non-Plasma desktops.

Running KDE Connect over OpenVPN

There may be a variety of reasons for using KDE Connect with a VPN. Maybe you have left home and want to run a command, or maybe you’re on a public wifi network where your devices aren’t allowed to communicate and you want to use remote control to give a presentation.

Set up OpenVPN

If you have your own server with a public-facing IP address, you can set up OpenVPN yourself. It is not the easiest piece of software to set up, but by following a setup tutorial such as this one, you should be able to manage: https://openvpn.net/howto.html

In order to allow UDP broadcast packets, which are what KDE Connect uses to automatically discover two devices, OpenVPN needs to be set up for bridging (TAP device). If you use a tun device, you can still manually connect by IP address.

If you want to rent a pre-configured OpenVPN service rather than set up your own, it should work, but the same considerations about the server settings need to be taken into account.

Once the server is running, you can use the official OpenVPN client to connect the desktop to the server. There is no official OpenVPN client for Android, but the OpenVPN for Android client works well: https://play.google.com/store/apps/details?id=de.blinkt.openvpn

Once both devices are connected, test that they are able to communicate over the VPN by trying to do a network ping between them.

Configure KDE Connect

If your OpenVPN instance is set up for bridging, KDE Connect should work just like on a local network.

If you are using OpenVPN with a tun device, you will have to manually add your devices by IP. Then, once you connect to the VPN, KDE Connect should automatically detect your device and either connect or be ready for pairing!

Building KDE Connect

If you want to build KDE Connect yourself, you'll first need to grab the code from git.

git clone https://invent.kde.org/kde/kdeconnect-kde.git

Note: if you plan to contribute code to KDE Connect, please follow the steps in KDEConnect#Setting_up_KDE_Connect_Repository_for_Development

Linux Desktop

KDE Connect uses cmake as a build system, which will tell you if you are missing any dependencies. On some distros you will need to install some development packages. Sometimes you will need to get the dependencies by yourself because the development branch of KDE Connect often uses new libraries not included in distro repositories, in which case you can build those yourself or use kdesrc-build. Helpfully, some package managers have a command which will automatically fetch the dependencies for you:

For Ubuntu

you can go in to /etc/apt/source.list and enable the source repositories to install all build-dependencies.

# apt update
# apt-get build-dep kdeconnect

For openSUSE

you can use

# zypper si -d kdeconnect-kde

Be sure to uninstall the package-provided version of kdeconnect before continuing, otherwise, you will end up in a confusing situation where some plugins are being provided by the system-installed version and others are coming from your new build.

Installing using prefix.sh

For development, it is recommended to install to your home directory using prefix.sh. This gives a faster development cycle and avoids clobbering your system-installed version with a potentially unstable WIP version.

These steps are roughly the same for any KDE project:

To configure use

cd kdeconnect-kde
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=~/kde-prefix ..

To build use

make -j8 install

To run the daemon, do

source build/prefix.sh
killall kdeconnectd; ~/kde-prefix/lib64/libexec/kdeconnectd

Other executables, such as the SMS app or the settings app, are on the path provided by prefix.sh, and can be found in ~/kde-prefix/bin

Installing to the System

If you want to use the new version of KDE Connect daily, you can install it to the system. This is not recommended for day-to-day development since it requires sudo access.

To configure use

cd kdeconnect-kde
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr ..

To build use

make
sudo make install

Note that this will override the KDE Connect provided by your distro

If you intend to develop KDE Connect or experience a crash and are asked to give a backtrace, build KDE Connect with debugging symbols:

cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug ..

If you install KDE Connect in a custom location, you'll need to run kdeconnectd manually, since DBus doesn't know about it.

For instructions on how to integrate the build with KDevelop, check out this blog post.

Android

You can find the code on Invent. It's easiest to use Android Studio to build the app and install it to your phone, although it can be done on the command line using gradle.

Running KDE Connect in the emulator is possible, but needs an advanced networking setup. See the guide posted for the Android_Emulator

Windows

KDE Connect works quite well on Windows, with many features ported. See here for build instructions

MacOS

KDE Connect works fairly well on macOS. But there is no official release for it yet. See here for build instructions.

You can get the Nightly Build from the Binary Factory

Mobile-Friendly QML App

KDE Connect provides an alternative mobile-friendly interface, targeted at mobile Linux platforms such as Plasma Mobile. The app is usable on the desktop as well. It is built from the same sources as the desktop component. The build steps are mostly the same, just one additional step is needed to enable building the app.

cd build
cmake -DEXPERIMENTALAPP_ENABLED=True .

This will result in an additional 'kcapp' executable being built

Desktop SMS Messaging App

KDE Connect has an SMS messaging app which lets you type and view SMS messages from your computer. It supports basic features and works correctly most of the time. If you are interested in trying or developing it, you can build it from source. It is automatically built as part of the rest of KDE Connect and is output as 'kdeconnect-sms'.

Troubleshooting

I have two devices running KDE Connect on the same network, but they can't see each other

KDE Connect uses dynamic ports in the range 1714-1764 for UDP and TCP. So if you are behind a firewall, make sure to open this port range for both TCP and UDP. Otherwise, make sure your network is not blocking UDP broadcast packets.

ufw

If your firewall is ufw, you can open the necessary ports with:

sudo ufw allow 1714:1764/udp
sudo ufw allow 1714:1764/tcp
sudo ufw reload

firewalld

If your firewall is firewalld, you can open the necessary ports with:

sudo firewall-cmd --zone=public --permanent --add-port=1714-1764/tcp
sudo firewall-cmd --zone=public --permanent --add-port=1714-1764/udp
sudo systemctl restart firewalld.service

Fedora firewall

In Fedora, there is an utility for configuring the firewall. Open Firewall Configuration (the program's filename is firewall-config), and in ZonesServices check the kde-connect service.

Make sure you have chosen the Permanent Configuration in the drop-down at the top, otherwise these settings will be reset upon reboot.

iptables

If your firewall is iptables, you can open the necessary ports with:

sudo iptables -I INPUT -i <yourinterface> -p udp --dport 1714:1764 -m state --state NEW,ESTABLISHED -j ACCEPT
sudo iptables -I INPUT -i <yourinterface> -p tcp --dport 1714:1764 -m state --state NEW,ESTABLISHED -j ACCEPT

sudo iptables -A OUTPUT -o <yourinterface> -p udp --sport 1714:1764 -m state --state NEW,ESTABLISHED -j ACCEPT
sudo iptables -A OUTPUT -o <yourinterface> -p tcp --sport 1714:1764 -m state --state NEW,ESTABLISHED -j ACCEPT

KDE Connect crashes or restarts when trying to pair with another device

Sometimes, a corrupt config file may cause KDE Connect to crash when trying to pair with a device. In that case, deleting the config ~/.config/kdeconnect might help.

Can I run KDE Connect without a display server?

Yes, you can pass the command line argument `-platform offscreen` to the daemon (eg: `killall -9 kdeconnectd; /usr/lib/libexec/kdeconnectd -platform offscreen`)

Running KDE Connect on an emulator

How to setup running KDE Connect on an emulator is described here Android_Emulator

GSConnect

GSConnect is an independent project which implements the KDE Connect protocol into GNOME and uses the same Android app. If you are running GSConnect, please visit that project's GitHub page first for support. If you and the GSConnect team determine the issue is the Android app or protocol, feel free to report those in the KDE Connect bug tracker.

My problem is not in this list :(

In case you find a bug and want to report it, you can do so in the KDE bug tracker.

Development

KDE Connect is a perfect project to start contributing to KDE. You'll need a basic understanding of programming concepts, the rest can be learned by doing. Experience with Android or Qt is beneficial, but not needed.

We have a group to discuss development. You can access it from Telegram, IRC (#kdeconnect) or matrix.org (#freenode_#kdeconnect:matrix.org). Feel free to ask any development-related questions there. We also have a mailing list.

All patches are submitted on Gitlab. The Android repository is here and the C++ Desktop repository is here. Be sure to select the most relevant template. You don't need to assign any reviewers, the developers are subscribed to notifications. Should this be your first patch, it's good to know that it might take some time before your patch is reviewed (we all work on KDE Connect in our free time), and you'll probably have to make some changes a couple of times. That's not because you're new, that's what happens for all reviews (even for long-time contributors).

There are a couple of tasks marked as Junior Jobs on our workboard. Those have some extra information on how to approach them that help you get started.

Setting up KDE Connect Repository for Development

KDE Connect is actually composed of two repositories; one for the Android implementation and one for the C++ (Desktop) implementation. You can have a local clone of both on your computer and the steps to set them up are the same. For these directions, I will use the C++ repository, but if you want the Android repository, just replace every instance of 'kdeconnect-kde' with 'kdeconnect-android'

  1. Fork the repository
    • With your web browser, open the Web GUI to KDE Connect's GitLab: https://invent.kde.org/kde/kdeconnect-kde
    • If you are not already, sign in with your KDE identity by clicking the "Sign In" button in the top left
    • Click the "Fork" button, near the top right
    • Wait for the forking to complete
  2. Clone your fork
    • Open your new fork in the GitLab web GUI
    • Click the "Clone" button in the top right
    • Select the method of cloning
      • I recommend SSH. This will require you add an SSH public key to your KDE GitLab account.
      • An HTTPS clone will require you to log in with your KDE Identity credentials to push changes.
    • In the folder you want to clone, do 'git clone <cloning path from above>'

You are all set up! See the optional steps for ways to make life easier.

Set up second remote (Optional)

Having a second remote allows you to have your local 'master' branch track the upstream kdeconnect-kde master branch, so you can easily get all the latest changes.

These steps assume you are using command-line git. If you are using a GUI tool, the steps will be different, but the ideas will be the same.

  1. On the command line, change to your local repository clone
  2. Execute:
# Note that we use HTTPS cloning here so that you don't need a verified account to pull changes!
git remote add upstream https://invent.kde.org/kde/kdeconnect-kde.git
git fetch upstream
git checkout -b upstream-master --track upstream/master
  1. Now whenever there are new changes upstream, simply pull the upstream-master branch, then merge or rebase your local branches onto those changes!

Development tips

Restarting the daemon

Whenever you do a change to KDE Connect you need to restart the daemon for the change to take effect.

killall kdeconnectd
build/bin/kdeconnectd

DBus inspection

The daemon communicates with various UI components (Plasmoid, CLI, Indicator etc.) over DBus. QDbusViewer allows inspecting the DBus interface provided by the daemon which can be incredibly useful for debugging.

</translate>