KDEConnect: Difference between revisions

From KDE Community Wiki
(Fix minor typo)
(36 intermediate revisions by 9 users not shown)
Line 1: Line 1:
This is the comunity page for KDE Connect. 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 aims to communicate all your devices. For example, with KDE Connect you can receive your phone notifications on your computer, or just use your phone as a remote control for your desktop. To achieve this, KDE Connect implements a secure communication protocol over the network, and allows any developer to create plugins on top of it. Currently there are KDE Connect clients on KDE, Android and Blackberry, and soon we will support iPhone as well.
KDE Connect is a project that enables all your devices to communicate with each other. Here's 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 [https://userbase.kde.org/KDE_Connect/Tutorials/Useful_commands 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


Some other cool features in video: https://www.youtube.com/watch?v=KkCFngNmsh0


More info at: http://albertvaka.wordpress.com
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 [http://albertvaka.wordpress.com Albert Vaka's] or [http://nicolasfella.wordpress.com Nico's] blog.


== Installation ==
== Installation ==


You will most likely find KDE Connect as a package in your distribution's repos. If you use desktop environment other than KDE's Plasma, you might also want to install indicator-kdeconnect, that provides a system tray as a GUI for other desktops.
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.
 
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.
 
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.)
 
== 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.
 
An alternative native extension for [https://chrome.google.com/webstore/detail/kde-connect/ofmplbbfigookafjahpeepbggpofdhbo Chrome/Chromium] (or compatible) and [https://addons.mozilla.org/en-US/firefox/addon/kde_connect/ Firefox] users, lets you "send pages and content from your browser to connected KDE Connect devices, via browser action or context menu." See its [https://github.com/pdf/kdeconnect-chrome-extension Github] page for installation instructions.
 
== 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 ===
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
 
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 I find that 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


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 store [https://f-droid.org/repository/browse/?fdid=org.kde.kdeconnect_tp F-Droid].
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 you are a Firefox user, this cool [http://kamikazow.wordpress.com/2014/11/22/send-firefox-tabs-to-your-phone-via-kde-connect/ extension] might be of your interest.
== Building KDE Connect (Desktop) ==
If you want to build KDE Connect yourself, you'll first need to grab the code from git. 
<syntaxhighlight lang="bash">
git clone git://anongit.kde.org/kdeconnect-kde.git
</syntaxhighlight>
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. On Ubuntu you can use <code>sudo apt-get build-dep kdeconnect</code> to install all build dependencies. On openSUSE you can use <code>sudo zypper si -d kdeconnect-kde</code>.
 
To configure use
<syntaxhighlight lang="bash">
cd kdeconnect-kde
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
</syntaxhighlight>
To build use
<syntaxhighlight lang="bash">
make
sudo make install
</syntaxhighlight>
 
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:
<syntaxhighlight lang="bash">
cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug ..
</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 are a Chrome/Chromium (or compatible) user, this [https://chrome.google.com/webstore/detail/kde-connect/ofmplbbfigookafjahpeepbggpofdhbo extension] might be of interest, see the [https://github.com/pdf/kdeconnect-chrome-extension Github] page for installation instructions.
For instruction on how to integrate it in KDevelop check out this [https://nicolasfella.wordpress.com/2018/03/30/building-kde-connect/ blog post]
 
== Building KDE Connect (Android) ==
You can find the code at git://anongit.kde.org/kdeconnect-android.git. It's easiest to use Android Studio to build the app and install it to your phone. Using the emulator is possible, but need an advanced networking setup (the emulator needs to be on the same subnet as the PC, or you won't be able to connect to your desktop.


== Troubleshooting ==
== Troubleshooting ==


=== I have two devices running KDE Connnect 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 ====


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


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
Line 32: Line 106:
sudo ufw allow 1714:1764/tcp
sudo ufw allow 1714:1764/tcp
sudo ufw reload
sudo ufw reload
</syntaxhighlight>
==== firewalld ====
If your firewall is '''firewalld''', you can open the necessary ports with:
<syntaxhighlight lang="bash">
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
</syntaxhighlight>
</syntaxhighlight>


Line 38: Line 122:


===  My KDE Connect crashes or restarts when trying to pair with another device ===
===  My KDE Connect crashes or restarts when trying to pair with another device ===
Some times, 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? ===  
Line 44: Line 128:


===  My problem is not in this list :( ===  
===  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 bugtracker: http://bugs.kde.org
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 ==


If you are interested in contributing to KDE Connect, please join the [https://mail.kde.org/mailman/listinfo/kdeconnect mailing list] of the project. You might also want to read [//albertvaka.wordpress.com Albert Vaca's development blog].
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].
 
You can submit patches on our [https://phabricator.kde.org/project/view/159/ Phabricator]. [https://community.kde.org/Infrastructure/Phabricator This wiki page] has more details on how this process works. 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).


You can find the sources in the following repositories:
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.
* https://projects.kde.org/projects/extragear/network/kdeconnect-android/repository
* https://projects.kde.org/projects/extragear/network/kdeconnect-kde/repository

Revision as of 17:45, 9 September 2018

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's 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 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 bug. 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.)

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.

An alternative native extension for Chrome/Chromium (or compatible) and Firefox users, lets you "send pages and content from your browser to connected KDE Connect devices, via browser action or context menu." See its Github page for installation instructions.

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

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

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 I find that 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 (Desktop)

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

git clone git://anongit.kde.org/kdeconnect-kde.git

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. On Ubuntu you can use sudo apt-get build-dep kdeconnect to install all build dependencies. On openSUSE you can use sudo zypper si -d kdeconnect-kde.

To configure use

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

To build use

make
sudo make install

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:

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 instruction on how to integrate it in KDevelop check out this blog post

Building KDE Connect (Android)

You can find the code at git://anongit.kde.org/kdeconnect-android.git. It's easiest to use Android Studio to build the app and install it to your phone. Using the emulator is possible, but need an advanced networking setup (the emulator needs to be on the same subnet as the PC, or you won't be able to connect to your desktop.

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 a program to configure the firewall. Open Firewall Configuration (the program's filename is firewall-config), and in Zones > Services check the kde-connect service.

My 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`)

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.

You can submit patches on our Phabricator. This wiki page has more details on how this process works. 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.