Jump to content

Konversation/Scripts/Scripting guide and KDEConnect: Difference between pages

From KDE UserBase Wiki
(Difference between pages)
Argonel (talk | contribs)
KDEDevelopers, trusted
6 edits
Removed apparently unnecessary syntaxhighlight tags
 
m Fixing Sensitive Notification Content (Android 15+)
 
Line 1: Line 1:
<languages />
<languages />
<translate>
<translate>
== Overview == <!--T:31-->


== Introduction == <!--T:1-->
<!--T:32-->
This is the documentation page for '''KDE Connect'''. If you are developing, debugging, or building a release of '''KDE Connect''', please refer to the [https://community.kde.org/KDEConnect community page].
 
<!--T:33-->
'''KDE Connect''' has two parts: the desktop program and the phone app.
 
== What is KDE Connect? == <!--T:1-->


<!--T:2-->
<!--T:2-->
'''Konversation''' has built-in support for running external scripts which, partnered with D-Bus and '''Konversation's''' own D-Bus methods, cover the most common scripting use cases, such as displaying information in the current chat window or controlling another application or even '''Konversation''' itself. This guide introduces the basics of writing a '''Konversation''' script. It covers only the essential concepts necessary to get started. Language- and system-specific nuances will be left to the user as a learning exercise.
'''KDE Connect''' is a project that enables all your devices to communicate with each other. Here's a few things '''KDE Connect''' can do:


== Requirements == <!--T:3-->


<!--T:3-->
* Receive your phone notifications on your desktop computer and reply to messages</translate>
<translate>
<!--T:4-->
<!--T:4-->
All you need is a text editor and a programming/scripting language. '''Konversation''' supports any programming language that:
* Control music playing on your desktop from your phone</translate>
 
<translate>
<!--T:5-->
<!--T:5-->
# Can accept and process command-line arguments (argv's).
* Use your phone as a remote control for your desktop</translate>
# Can connect to and call D-Bus, or at least make external system calls (such as executing the program "<code>qdbus</code>"). It is probably better and more secure to use the language's native D-Bus bindings if available, rather than executing a system call to run <code>qdbus</code>.
<translate>
<!--T:6-->
* Run predefined commands on your PC from connected devices. See the list of example commands for more details.</translate>
<translate>
<!--T:7-->
* Check your phone's battery level from the desktop</translate>
<translate>
<!--T:8-->
* Ring your phone to help find it</translate>
<translate>
<!--T:9-->
* Share files and links between devices</translate>
<translate>
<!--T:10-->
* Browse your phone from your desktop</translate>
<translate>
<!--T:11-->
* Control the desktop's volume using your phone</translate>
<translate>
<!--T:87-->
* Send SMS from your desktop


<!--T:6-->
== Installation== <!--T:14-->
At the moment, Python, BASH (or Shell), and Perl are known to work and have examples shipped with '''Konversation'''. But any language fulfilling the two requirements above would probably also work. This guide will give examples in Python.


== Case 1: Display Information into the Current Chat Window == <!--T:7-->
<!--T:88-->
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.


<!--T:8-->
<!--T:12-->
Probably the most common scripting scenario is getting some text to display in the current '''Konversation''' tab (channel or private message), with the data usually coming from an external source. This source could be the script itself, another application (such as the <code>media</code> script included with '''Konversation'''), or the Internet (like getting weather information and displaying it in '''Konversation'''). Whatever the source, there are 3 steps to perform:
Despite 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 file a [https://bugs.kde.org/enter_bug.cgi?product=kdeconnect bug report].


<!--T:9-->
<!--T:178-->
# Getting the input - catching and parsing the command sent by the user from '''Konversation'''.
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), KDE Connect already comes with the '''kdeconnect-indicator''' binary, which can be set to autostart in each environment.
# Processing the data - gathering data from sources and manipulating it based on the input.
# Sending the output - throwing the information back to '''Konversation''' through D-Bus.


<!--T:10-->
<!--T:89-->
The following is a nonsensical example of a '''Konversation''' script that roughly follows that pattern.
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].


<!--T:164-->
The app for iOS can be found in [https://apps.apple.com/app/kde-connect/id1580245991 Apple's proprietary App Store]. Additionally, a pre-release, testing version of KDE Connect can be downloaded from [https://testflight.apple.com/join/vxCluwBF TestFlight]. Please see the [https://invent.kde.org/network/kdeconnect-ios/-/blob/master/README.md iOS README] for important data disclosure information, known limitations, and bug reporting information.


<!--T:11-->
<!--T:91-->
<!--}}-->{{Input|lang=python|1=
'''KDE Connect''' is also available for SailfishOS via [https://openrepos.net/content/r1tschy/sailfish-connect sailfish-connect] and we are working on bringing it to other Linux-based phones (Plasma Mobile, PostmarketOS etc.)
#!/usr/bin/env python
# mood - a Konversation script to display a witty remark based on the user's mood.
# Usage: /exec mood [mood_string]


<!--T:12-->
<!--T:92-->
import sys
[https://kdeconnect.kde.org/download.html See KDE Connect download page] for installation links for other platforms (including Windows and macOS).
import subprocess


<!--T:13-->
==Pairing two devices together== <!--T:24-->
command = ['qdbus', 'org.kde.konversation', '/irc']


<!--T:14-->
<!--T:25-->
argc = len(sys.argv)
First, you need to open '''KDE Connect''' on your computer ''and'' phone. You should now be able to see in each screen the name of the device you wish to pair with. If it's not working, make sure that the two devices are connected to the same network and that there isn't any firewall blocking the two devices from seeing each other. See the [[Special:myLanguage/KDEConnect#I_have_two_devices_running_KDE_Connect_on_the_same_network.2C_but_they_can.27t_see_each_other|troubleshooting section]].


<!--T:15-->
<!--T:26-->
if argc < 2:
[[File:kde_connect_desktop.png|700px|center]]
    command.append("error")
    text = "Server required"
elif argc < 3:
    command.append("error")
    text = "Target required"
elif argc < 4:
    command.append("error")
    text = "No mood given"
else:
    server = sys.argv[1]
    target = sys.argv[2]
    mood  = sys.argv[3]


    <!--T:16-->
<!--T:27-->
if mood == "hungry":
[[File:kde_connect_on_android_phone_devices.png|300px|center]]
        text = "Hungry! Anyone got a horse?"
    elif mood == "sleepy":
        text = "I yawn, therefore I am."
    elif mood == "gloomy":
        text = "Roses are red. Violets are blue, and so am I ..."
    elif mood == "happy":
        text = "Thinking happy thoughts (with a dash of pixie dust)."
    elif mood == "hyper":
        text = "Just a spoonful of sugar? I think I took a whole jar! *cartwheels*"
    elif mood == "excited":
        text = "Are we there yet? Are we there yet? Are we there yet?"
    else:
        text = "What were we talking about again?"


        <!--T:17-->
<!--T:28-->
command.append("say")
You can now request pairing in one of the two devices. The other device will show a prompt asking to accept the pairing request. Confirm it and that's it! Your devices are now paired.
        command.append(server)
        command.append(target)


<!--T:18-->
<!--T:29-->
command.append(text)
While a typical configuration might include one computer and one phone, it's also possible to pair two computers instead.


<!--T:19-->
== Bluetooth Connectivity == <!--T:182-->  
subprocess.Popen(command).communicate()
}}<!--{{-->


=== Getting the Input === <!--T:20-->
<!--T:183-->
In recent versions (for example v24.08.1) bluetooth connectivity has been enabled by default. To use this, you must first bluetooth pair your computer and phone.


<!--T:21-->
<!--T:184-->
When '''Konversation''' calls an external script, it runs it with some predefined arguments, like this:
[[File:KDEConnect-Bluetooth-1.png|300px|center]]


<!--T:22-->
<!--T:185-->
<code>script_name server target [additional arguments ...]</code>
Click Add device:


<!--T:23-->
<!--T:186-->
Arguments are usually stored in a collection (a list or an array, depending on the language) called "argv" indexed from 0 to N, with N being the number of arguments.
[[File:KDEConnect-Bluetooth-2.png|300px|center]]


<!--T:24-->
<!--T:187-->
* ''argv[0]'' is always the script name itself. In most cases, it's safe to ignore this.
Make sure your phone is visible to pairing and it will appear, once appeared click pair:


<!--T:60-->
<!--T:188-->
* ''argv[1]'' is the address of the server the user is currently connected to. In case of multiple connected servers, this will always be the server to which the channel or query window is connected to.
[[File:KDEConnect-Bluetooth-3.png|300px|center]]
[[File:KDEConnect-Bluetooth-4.png|300px|center]]


<!--T:61-->
<!--T:189-->
* ''argv[2]'' is the target, the name of the chat window where the command to run the script came from which, more often than not, would be the same window where output would be displayed. Of course, you can always change this.
It will pop up with a PIN to be confirmed on both the computer and the phone:


<!--T:62-->
<!--T:190-->
* ''argv[3]'' to ''argv[N]'' will be any additional arguments that would be sent by the user calling the script through '''Konversation'''. This can be anything from flags to enable/disable options in the script or data or text that can be displayed in the output of the script. Not all scripts have additional arguments, like the <code>uptime</code> and <code>sysinfo</code> scripts.
[[File:KDEConnect-Bluetooth-5.png|300px|center]]
<br><!-- br added due to lack of top margin on Remember template -->
[[File:KDEConnect-Bluetooth-A1.png|300px|center]]


<!--T:25-->
<!--T:191-->
{{Remember|1= Even if your script doesn't require additional arguments or even if the user didn't supply them, '''Konversation''' will always send the system and target arguments. Meaning, ''argv[1]'' and ''argv[2]'' will always be set. The minimum argument count will always be 3 (remember, indexing starts at 0).}}
Click matches on the desktop and pair on Android


=== Processing the Data === <!--T:26-->
<!--T:192-->
It will then be connected correctly:


<!--T:27-->
<!--T:193-->
In the example script, the ''mood'' variable, supplied by the user in ''argv[3]'' of the script, is compared to predefined values and the appropriate remark is assigned to the ''text'' variable. This is a simple example of data processing. You can also fetch data from a predefined data source, like the <code>fortune</code> script. Or assemble information coming from the operating system, such as done in the <code>sysinfo</code> script. Whatever information or text you need to be displayed in '''Konversation''', you create that here.
[[File:KDEConnect-Bluetooth-6.png|300px|center]]
[[File:KDEConnect-Bluetooth-7.png|300px|center]]
[[File:KDEConnect-Bluetooth-A2.png|300px|center]]


<!--T:28-->
<!--T:194-->
{{Warning|1=A word of caution: Be careful when creating multi-line text output, as your server or the channel you're sending to may have anti-flooding policies. When dealing with a potentially large, it might be best to have it displayed in another way (like in a text editor).}}
Once this has been achieved open the KDE Connect on Android and enable bluetooth


<!--T:29-->
<!--T:195-->
Now that the needed information is processed and assembled, it's time to prepare it for sending back into '''Konversation''', which is discussed in the next section.
[[File:KDEConnect-Bluetooth-A-KDEBluetoothEnable.png|300px|center]]


=== Sending the Output === <!--T:30-->
<!--T:196-->
On the "Add new devices" page, the computer should appear and the pairing process can be followed as usual. Refreshing this view can force the phone to attempt to rediscover.
''This may take some time to appear, both Android and Bluez seem to implement quite a lot of caching and this can delay how long it takes to be detected''.


<!--T:31-->
<!--T:197-->
Controlling '''Konversation''' externally, like through a script or the command-line, involves using its D-Bus methods. '''Konversation''' has several of them, including a group whose purpose is to display messages. Sending D-Bus messages can be tedious. Fortunately, Qt provides a much easier way of doing that, using the helper program "<code>qdbus</code>". Without going into much detail, all the D-Bus commands we will be sending to make '''Konversation''' display messages starts with this string:
[[File:KDEConnect-Bluetooth-A3.png|300px|center]]
<code> qdbus org.kde.konversation /irc</code>


<!--T:32-->
== Browser Integration == <!--T:93-->
Depending on what kind of message the script will be sending, additional options will be added to that command. Here are but a few examples:
{{Input|lang=bash|1=
qdbus org.kde.konversation /irc say server target message}}
This is probably the command that will be most commonly used. It sends message to the chat window target connected to server. If you want the message to be sent to the same chat window where the script was called from, use ''argv[1]'' and ''argv[2]'' for server and target, respectively. Of course you can always change the target to any channel or nick you want in that server.


<!--T:33-->
<!--T:94-->
{{Input|lang="bash"|
[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.
qdbus org.kde.konversation /irc error message
}}
This displays the message in the same chat window where the script was invoked. The difference is that the message isn't actually sent to the IRC server and is only visible to the user. The message is also formatted as something like ''"[D-Bus] Error: message"''. Useful for informing the user about errors in using the script or if something fails in the script. It doesn't need a server or a target.


<!--T:34-->
== Changing Device Names == <!--T:34-->
{{Input|lang=bash|1=
qdbus org.kde.konversation /irc sayToAll message
}}
Sends the message to all channels and query windows in all servers. Please use sparingly and observe proper netiquette. It doesn't require a server and a target.


<!--T:35-->
<!--T:35-->
{{Input|lang="bash"|1=
You can only change the name of your device on the device itself. So if you want to change the name of your computer then you must use the desktop program and if you want to change the name of your phone or tablet you must make the change in the '''KDE Connect''' app. Once a device is renamed, it will automatically sync with all other connected devices.
qdbus org.kde.konversation /irc actionToAll message
 
}}
<!--T:73-->
sayToAll's action sibling. Sends the message to all channels and query windows in all servers BUT prepends "/me" to the actual message, resulting in displaying something like ''"*YourNick message*"''. Again, netiquette applies.
[[File:kde_connect_renaming_device.png|800px|center]]
 
== Running KDE Connect over OpenVPN == <!--T:95-->
 
<!--T:96-->
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 the remote control to give a presentation.
 
=== Set up OpenVPN === <!--T:97-->
 
<!--T:98-->
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 [https://openvpn.net/howto.html this one], you should be able to manage.
 
<!--T:99-->
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.
 
<!--T:100-->
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.


<!--T:36-->
<!--T:101-->
{{Note|To send an action ("/me") message only to the current chat window (where the script was called from), compose the actual message as "/me message" and use the say variant of the command (first one in this list if you got lost {{smiley}}).}}
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 openvpn]


<!--T:37-->
<!--T:102-->
There are other /irc related qdbus commands, some of which change the user's status instead of displaying the command. Feel free to explore other possibilities. Another Qt helper program, "<code>qdbusviewer</code>", provides a graphical interface for browsing through the available commands for '''Konversation''' and other "D-Bus aware" programs. You will probably need it a lot especially for the second scripting scenario discussed later.
Once both devices are connected, test that they are able to communicate over the VPN by trying to do a network ping between them.


=== Getting the Script to Run === <!--T:38-->
=== Configure KDE Connect === <!--T:103-->


<!--T:39-->
<!--T:104-->
Now it's time to actually make the script run in '''Konversation'''. Here are the steps:
If your '''OpenVPN''' instance is set up for bridging, '''KDE Connect''' should work just like on a local network.
 
<!--T:105-->
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!
 
==Available Plugins == <!--T:36-->
 
===Battery Monitor=== <!--T:37-->
 
<!--T:38-->
''"Show your phone battery next to your computer battery."''
 
<!--T:74-->
By enabling this, the '''KDE Connect''' widget on your panel tray will display your phone's battery.
 
<!--T:75-->
[[File:KDEConnectBattery.png|500px|center]]
 
===Clipboard=== <!--T:39-->


<!--T:40-->
<!--T:40-->
* Make your script executable. <code> chmod +x script_name</code> does it all. It would be better to not include extensions (.sh, .py, .pl, etc.) in your filename, to make it easier to call the script.
''"Share the clipboard between devices."''


<!--T:63-->
<!--T:76-->
* Place the script in either one of two folders:
With this, you can simply copy text from your computer and it will be immediately available to paste on your phone, and vice-versa. This does not work with images though.
** If you want your script to be available all users in your system, put the script together with the other scripts installed with '''Konversation'''. This may vary from distro to distro (or your own personal tinkering), but common a location is ''/usr/share/apps/konversation/scripts/''. In case it's not there, get the output of the command <code>kde4-config --install data</code> and append <code>/konversation/scripts/</code> to it. Consult your distribution's support channel if it's still not there.
 
** If you want the script just for yourself, simply place the script in ''~/.kde/share/apps/konversation/scripts/''. Some distros might still be using ~/.kde4/ instead so adjust accordingly.
<!--T:134-->
** Post version 1.3.1 note: another way to find out where the installed scripts are is to run this command in '''Konversation's''' input line (using the <code>media</code> script as an example, since it comes with any '''Konversation''' installation): <code>/exec --showpath media</code>. Note that if there are two scripts with the same name in the user's home and in the system locations, the one in the user's home will take precedence and be the one shown here.
====Auto-sync on Android 10+====
Android 10 prevents apps from accessing the clipboard to prevent malicious apps from accessing your data. This makes the clipboard plugin in KDE Connect uncomfortable to use.
 
<!--T:222-->
On Android 10+, there's an action button labeled "Send Clipboard" in the persistent indicator notification.
 
<!--T:181-->
On Android 14+, there's a tile in the pull-down menu called "Send clipboard", that can be moved to a convenient slot (e.g. in the partial pull-down section).
 
<!--T:135-->
=====Magisk Module (root only)=====
If you are rooted, you can use a Magisk module to remove this restriction.
 
<!--T:136-->
=====Log Reading=====
If you have a build containing commit [https://invent.kde.org/network/kdeconnect-android/commit/edc655da5ac1eb5c3027c8556cc62037a1d4c5ac edc655da5ac1eb5c3027c8556cc62037a1d4c5ac], you can enable the READ_LOGS permission in order to enable a workaround to clipboard sync.
 
<!--T:214-->
Enable [https://developer.android.com/studio/debug/dev-options USB debugging] on your phone.
 
<!--T:137-->
Run these commands:
 
<!--T:138-->
<syntaxhighlight lang="bash">
adb -d shell pm grant org.kde.kdeconnect_tp android.permission.READ_LOGS;
adb -d shell appops set org.kde.kdeconnect_tp SYSTEM_ALERT_WINDOW allow;
adb -d shell am force-stop org.kde.kdeconnect_tp;
</syntaxhighlight>
 
<!--T:139-->
''How does it work?''
 
<!--T:140-->
With log reading enabled, KDE Connect watches its own log. If it sees a line indicating that it has been denied access to read the clipboard, it pops up an invisible window to the foreground, grabs the clipboard, and closes the window.
 
===Contacts=== <!--T:141-->
 
<!--T:142-->
''"Synchronize contacts between devices"''
 
<!--T:143-->
This plugin silently synchronizes contacts, in vcard format, from your phone to your desktop.
 
<!--T:144-->
As of this writing, the synchronization is one-way, with data being sent from the Android implementation to the desktop, to be consumed by any application which uses the KPeople library with the KPeopleVCard plugin, such as the KDE Connect SMS app.


<!--T:64-->
====VCard Location==== <!--T:145-->
* To actually run the script, you need to invoke it by running this command in '''Konversation's''' input line: <code> /exec script_name [additional arguments]</code>


<!--T:41-->
<!--T:146-->
This will call your script and pass the arguments to it. Remember that your script_name is always ''argv[0]'', and that the current server and chat window are passed as ''argv[1]'' and ''argv[2]'', even if you didn't include them in your command. Therefore, any additional arguments would be ''argv[3]'' and so on.
On non-Windows platforms, contact cards are written to ''QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) + "/kpeoplevcard"''. This might be configured differently by your system, but normally resolves to ''~/.local/share/kpeoplevcard''.


<!--T:65-->
<!--T:147-->
* For convenience, you can create a command alias in '''Konversation''' so that you can invoke your script simply using /script_name instead of the actual syntax given above. To manually do this, go to <menuchoice>Settings -> Configure Konversation -> Command Aliases</menuchoice> page. Click on the <menuchoice>New</menuchoice> button and enter "script_name" in the <menuchoice>Alias<m/enuchoice> field and "/exec script_name" in the <menuchoice>Replacement</menuchoice> field. So next time you need to run your script, you can simply do use <code>/script_name [arguments]</code>
On Windows, the path resolves to ''%LocalAppData%''.


<!--T:66-->
===Inhibit Screensaver=== <!--T:41-->
* Alternately, whenever '''Konversation''' is started, it automatically creates a command alias of "/script_name" for "/exec script_name" for every script it finds in the scripts/ directories mentioned earlier.


<!--T:42-->
<!--T:42-->
For the previous example, the script is named "mood" and can be invoked either using <code>/mood [mood]</code> or <code>/exec mood [mood]</code>, like:
''"Inhibit the screensaver when the device is connected."''


<!--T:43-->
<!--T:43-->
/mood gloomy
This makes sure that your screensaver will not run while your device is connected.


<!--T:44-->
<!--T:44-->
That's basically all you need to know to make a '''Konversation''' script. To make it a bit more interesting, let's have an example of another common scripting scenario.
===Multimedia Control Receiver===
''"Remote control your music and videos."''


== Case 2: Controlling an External Program from Konversation == <!--T:45-->
<!--T:45-->
With this feature, you can control your music and videos remotely, with pause/play, previous/next, 5 s before/later. You can also change which media player to control, in addition to application and system volume.


<!--T:46-->
<!--T:46-->
Thanks to D-Bus, and the fact that a lot of KDE applications have D-Bus methods, you can control any KDE application right from within '''Konversation'''. Even without D-Bus, you can let your script start, stop, or possibly even control other applications simply with a command in '''Konversation'''. This lets you do a lot of things, like sending a command to a terminal emulator, opening a bug report in a browser providing only the report number (like the <code>bug</code> script), or simply running a system command (and probably displaying the results of that command, as the <code>cmd</code> script does).
[[File:Kde connect media player on android phone.jpg|300px|center|Multimedia control receiver with KDE Connect in Android]]


<!--T:47-->
<!--T:47-->
The following script performs the first example. It first makes [[Special:mylanguage/Yakuake|Yakuake]] visible and then runs the command supplied by the user. The script is rather simple and doesn't involve displaying anything back to the user, except in the case of an error when calling the script itself.
===Pause Media During Calls===
''"Pause music/videos during a phone call."''


<!--T:48-->
<!--T:48-->
<!--}}-->{{Input|lang=python|1=
Pause music/videos during a call. This feature can be powerful when combined with  [[Special:myLanguage/Plasma-browser-integration|Plasma Browser Integration]]. For example, when you are listening to some music on Peertube or Youtube, the video will be paused whenever you receive a call.
#!/usr/bin/env python
# yakrun - Konversation script that runs the command supplied by the user in Yakuake and toggles Yakuake's state
# Usage: /exec yakrun [command]


<!--T:49-->
<!--T:49-->
import sys
You can configure this option to pause only when you pick up your phone or directly when your phone starts to ring. You can also decide if you want to only pause the media player or/and mute the system sound.
import subprocess


<!--T:50-->
===Ping=== <!--T:50-->
errorCommand  = ['qdbus', 'org.kde.konversation', '/irc', 'error']
toggleCommand = ['qdbus', 'org.kde.yakuake', '/yakuake/window', 'toggleWindowState']
runCommand    = ['qdbus', 'org.kde.yakuake', '/yakuake/sessions', 'runCommand']


<!--T:51-->
<!--T:51-->
argc = len(sys.argv)
''"Send and receive pings."''


<!--T:52-->
<!--T:52-->
if argc < 4:
This serves to test your connection to a given device. Once selected, a "Ping!" will appear as a notification on your receiving device.
    text = "No command to run."


    <!--T:53-->
<!--T:53-->
errorCommand.append(text)
On your desktop, you can send a ping through the KDE Connect settings or through the widget on the tray.


    <!--T:54-->
<!--T:54-->
subprocess.Popen(errorCommand).communicate()
On your phone, you can send a ping through the upper right hamburger menu on the '''KDE Connect''' app.
else:
    command = " ".join(sys.argv[3:])


    <!--T:55-->
<!--T:55-->
runCommand.append(command)
[[File:Kde connect on android phone overview.png|center|300px|Send a ping to your computer with android]]


    <!--T:56-->
===Receive Notifications=== <!--T:56-->
subprocess.Popen(toggleCommand).communicate()
    subprocess.Popen(runCommand).communicate()
}}<!--{{-->


== Language-specific Notes == <!--T:57-->
<!--T:57-->
''"Show your phone notifications on your computer and keep them in sync."''


<!--T:58-->
<!--T:58-->
* Be careful when processing arguments and assembling them into a single string with spaces, which might be more error-prone in some languages, such as BASH.
This keeps you in touch with what happens on your phone! Any notifications you receive on your phone will be shown in your computer. Some notifications, such as those of Instant Messengers (IM) like Telegram can be replied on the fly through the computer notification itself.


<!--T:59-->
<!--T:59-->
[[Category:Internet]]
===Remote File System Browser===
[[Category:Advanced Users]]
''"Browse the remote device filesystem using SFTP."''
 
<!--T:60-->
This allows you to access your phone storage! When enabled, a device will appear in Dolphin with which you can navigate your external storage.
 
<!--T:77-->
[[File:KDEConnectBrowse.png|800px|center]]
 
<!--T:78-->
[[File:KDEConnectViewBrowser.png|500px|center]]
 
<!--T:61-->
===Ring My Phone===
''"Find your lost phone by making it play an alarm sound."''
 
<!--T:62-->
This also serves to test your connection to a given device, and by ringing your phone remotely, you can quickly find its location!
 
<!--T:79-->
[[File:KDEConnectRing.png|500px|center]]
 
<!--T:63-->
===Run Commands===
''"Execute console commands directly."''
 
<!--T:64-->
With '''KDE Connect''', you can run predefined commands on your computer by pressing buttons on your phone!
Instructions on how to add a command are shown in [[Special:myLanguage/KDE_Connect/Tutorials/Adding_commands|userbase]]. A set of useful commands can also be found [[Special:myLanguage/KDE_Connect/Tutorials/Useful_commands|here]].
Some sample commands, such as suspend and lock screen, are also available.
 
<!--T:179-->
If your device supports Device Controls (Android 11+), KDE Connect will display configured commands there. You can then quickly control your remote device, such as locking the screen. See Google's documentation for more description of device controls: https://developer.android.com/develop/ui/views/device-control
 
<!--T:180-->
[[File:20231023-KDE Connect Device Controls Screenshot Samsung.jpg|thumb|alt=Screenshot of the device controls pane on a Samsung device, showing two configured commands, "Suspend" and "Lock Screen". In each device control tool is the command it will execute, and a prompt which says "Tap to execute".|Screenshot of the device controls pane on a Samsung device|center]]
 
<!--T:65-->
===Send Notifications===
''"Broadcast this computer's notifications, so they can be shown on other devices."''
 
<!--T:80-->
This is pretty self-explanatory: notifications from your computer will show up on your phone.
 
<!--T:66-->
You can configure if you want to send the notification description, the icons pertaining to the application and persistent or very important notifications.
This keeps you in touch with what happens on your computer! Any notifications you receive on your computer will be shown in your phone.
 
====Sensitive Notification Content (Android 15+)==== <!--T:207-->
 
<!--T:208-->
On Android 15+, "sensitive" notification content is hidden by the system when passed to applications. Due to this limitation, KDE Connect will show something like "Sensitive notification content hidden" instead of the real content.
 
=====(Recommended) Grant RECEIVE_SENSITIVE_NOTIFICATIONS===== <!--T:211-->
 
<!--T:212-->
KDE Connect can be granted the RECEIVE_SENSITIVE_NOTIFICATIONS permission, at which point sensitive notification content will be delivered normally. This may not work on all manufacturer's devices.
 
<!--T:213-->
# Set up ADB (https://developer.android.com/tools/adb).
# Connect the phone over ADB, either with USB or wireless ADB.
# Run <syntaxhighlight lang="bash">adb shell cmd appops set --user 0 org.kde.kdeconnect_tp RECEIVE_SENSITIVE_NOTIFICATIONS allow</syntaxhighlight>
# If you're facing a permission related exception: <syntaxhighlight lang=""bash>java.lang.SecurityException: uid 2000 does not have android.permission.MANAGE_APP_OPS_MODES.
</syntaxhighlight> upon running above command, enable '''Disable permission monitoring''' in '''Developer Options''', reboot the phone and then run above command.
# Reboot the phone.
 
=====Disable Enhanced Notifications===== <!--T:209-->
 
<!--T:210-->
In the notification settings for the app you want to send unrestricted notifications, disable "Enhanced notifications" which will remove this restriction.
 
<!--T:215-->
Note that this will disable ''all'' enhanced notification functionality, such as being able to reply to messages from notifications, etc.
 
<!--T:216-->
===Share and Receive===
''"Receive and send files, URLs or plain text easily."''
 
<!--T:81-->
This integrates your desktop and your browser so that you can right-click on files or links and send it immediately to your phone!
 
<!--T:82-->
Files show the right-click option "Send to phone via KDEConnect" and will send the file directly, showing it among your notifications.
 
<!--T:83-->
Links show the right-click option "Open on phone" and will automatically open your phone's default browser on the chosen website. Really handy!
 
<!--T:68-->
When receiving files from your phone into your computer, they will go to your Downloads folder by default. If you wish, you can change that too.
 
<!--T:69-->
===Telephone Integration===
''"Show notifications for incoming calls."''
 
<!--T:70-->
Whenever you get a call on your phone, a notification telling you which number is calling appears. Paired with "Pause media during calls", you'll surely be able to answer readily and never lose a call!
 
<!--T:71-->
===Virtual Input===
''"Use your phone as a touchpad and keyboard."''
 
<!--T:84-->
With this enabled, by going to your phone app and selecting Remote input, a touch screen will immediately be available for you to control your computer mouse, similarly to a touchpad. One touch equals one click.
 
<!--T:85-->
The keyboard icon in the upper right allows you to type on your phone and see the result on your computer too.
 
<!--T:72-->
If you press the hamburger menu right by its side, you'll be able to send right and middle clicks.
 
<!--T:86-->
===Presentation control===
It is possible to control presentations using the previous/next slide button. When the device is locked, you can use the volume up/down button to do that. You can also highlight something using the laserpointer. Just move your phone and the blue circle will follow! Using the hamburger menu, you can toggle fullscreen (F5) or quit the presentation (Esc).
 
== Permissions Explanations and Tutorial Videos == <!--T:155-->
 
<!--T:156-->
From time to time, Google will require video submissions to prove that we use permissions in ways which are allowed by Play Store policies. Those videos are gathered here for future reference, but also because they provide nice tutorials of how to use certain features, and are also useful to demonstrate permissions usage to a wider audience.
 
=== Android Mouse Receiver (Accessibility Permission) === <!--T:157-->
 
<!--T:158-->
In order to be a fake input device, Android requires that we take the Accessibility permission. The mouse receiver plugin is demonstrated in the following video.
https://www.youtube.com/watch?v=PQ-Oubt4Rks
 
=== Other Permissions === <!--T:159-->
 
<!--T:160-->
This video demonstrates several KDE Connect features, in particular it demonstrates how KDE Connect uses certain privacy-impacting permissions, such as the SMS permissions.
https://www.youtube.com/watch?v=QGHzXpX0vtk
 
== Missing or limited features on some platforms == <!--T:163-->
 
<!--T:165-->
Some platforms are missing some features due to technical limitations or other reasons.
 
=== iOS === <!--T:166-->
 
==== Missing ==== <!--T:167-->
 
<!--T:168-->
* Notification sync
* SMS
* Keeping connection alive when app is not on-screen
* Virtual Display
 
==== One way - only from iOS to desktop ==== <!--T:169-->
 
<!--T:170-->
* Remote Input
* Run Command
* Slideshow Remote
* Shared clipboard (limited, need to tap "push clipboard" on the app to push clipboard to the PC)
 
=== Android === <!--T:171-->
 
==== Missing ==== <!--T:172-->
 
<!--T:173-->
* Virtual Display
 
==== One way - only from Android to desktop ==== <!--T:174-->
 
<!--T:175-->
* Run Command
* Slideshow Remote
* SMS (transfer messages to desktop and handle sending)
* Contacts
 
==== One way - only from desktop to Android ==== <!--T:176-->
 
<!--T:177-->
* SMS (retrieve from phone and dispatch send requests to phone)
 
== Troubleshooting == <!--T:106-->
 
</translate><span id="I have two devices running KDE Connect on the same network, but they can't see each other"></span><translate>
 
=== I have two devices running KDE Connect on the same network, but they can't see each other === <!--T:107-->
 
<!--T:108-->
'''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.
 
<!--T:148-->
Check that the process is listening on the network:
 
</translate>
<syntaxhighlight lang="bash">
sudo netstat -tunelp | grep -i kdeconnect
</syntaxhighlight>
<translate>
 
<!--T:150-->
Are the ports open/blocked?
 
</translate>
<syntaxhighlight lang="bash">
netcat -z -v <your-phones-ip> 1714-1764
</syntaxhighlight>
<translate>
 
<!--T:152-->
Example output:
 
<!--T:153-->
Connection to <your -phones-ip> 1716 port [tcp/*] succeeded!
 
<!--T:154-->
You also get lots of Connection refused, but you need 1 “succeeded”
 
<!--T:161-->
If the network connection is not the problem, you might try starting from a clean configuration again:
 
</translate>
<syntaxhighlight lang="bash">
killall kdeconnectd
mv ~/.config/kdeconnect ~/.config/kdeconnect.bak
</syntaxhighlight>
<translate>
 
==== ufw ==== <!--T:109-->
 
<!--T:110-->
If your firewall is '''ufw''', you can open the necessary ports with:
 
</translate>
<syntaxhighlight lang="bash">
sudo ufw allow 1714:1764/udp
sudo ufw allow 1714:1764/tcp
sudo ufw reload
</syntaxhighlight>
<translate>
 
==== firewalld ==== <!--T:112-->
 
<!--T:113-->
If your firewall is '''firewalld''', you can open the necessary ports with:
 
</translate>
<syntaxhighlight lang="bash">
sudo firewall-cmd --permanent --zone=public --add-service=kdeconnect
sudo firewall-cmd --reload
</syntaxhighlight>
<translate>
 
==== Firewall Configuration (firewall-config) ==== <!--T:115-->
 
<!--T:116-->
Open Firewall Configuration (<code>firewall-config</code>). In '''Zones''' ➔ '''Services''', check the kde-connect service.
 
<!--T:117-->
Make sure you choose the "Permanent" '''Configuration:''' option in the drop-down menu at the top, otherwise rebooting will discard your settings changes.
 
==== iptables ==== <!--T:118-->
 
<!--T:119-->
If your firewall is '''iptables''', you can open the necessary ports with:
</translate>
<syntaxhighlight lang="bash">
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
</syntaxhighlight>
<translate>
 
===  KDE Connect crashes or restarts when trying to pair with another device === <!--T:121-->
 
<!--T:122-->
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.
 
=== KDE Connect Android app crashes === <!--T:129-->
 
<!--T:130-->
If the KDE Connect Android app crashes, you might be able to get more information about the crash by using '''adb logcat'''.
 
<!--T:131-->
Set up ADB using the [https://developer.android.com/studio/command-line/adb official instructions]
 
<!--T:132-->
The following command should list all information relevant to your crash. Run '''adb logcat''' *before* triggering the crash.
 
</translate>
<syntaxhighlight lang="bash">
adb logcat --pid=$(adb shell pidof -s org.kde.kdeconnect_tp)
</syntaxhighlight>
<translate>
 
===  Can I run KDE Connect without a display server? === <!--T:123-->
 
<!--T:124-->
Yes, you can pass the command line argument <code>-platform offscreen</code> to the daemon (eg: <code>killall -9 kdeconnectd; /usr/lib/libexec/kdeconnectd -platform offscreen</code>)
 
=== GSConnect === <!--T:125-->
 
<!--T:126-->
'''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.
 
=== Bluetooth === <!--T:198-->
 
<!--T:199-->
Check the logs for KDE Connect; a normal set of logs looks like:
[[File:KDEConnect-Bluetooth-Screenshot 20241004 092657.png|centre|700px]]
The logs can usually be read with journalctl:
 
<!--T:200-->
{{Input|1=journalctl --user [email protected]}}
 
<!--T:201-->
and should contain several mentions of bluetooth. If there is a log like:
 
<!--T:202-->
{{Output|1=qt.bluetooth.bluez: Bluetooth device is powered off}}
 
<!--T:203-->
then the daemon was started when bluetooth was disabled and will need to be restarted until a release including https://invent.kde.org/mintsoft/kdeconnect-kde/-/commit/251ea971c5f3639a84f56bfb22237f93b4f817d2 is released.
 
<!--T:204-->
If everything looks correct from the logging perspective then it is worth confirming that the bluetooth interface has had the service uuid added to it (this is what the client application will connect to). If you run <code>bluetoothctl show</code> there will be a list of UUIDs on the interface, and it should include
 
<!--T:205-->
{{Output|1=UUID: Vendor specific          (185f3df4-3268-4e3f-9fca-d4d5059915bd)}}
 
<!--T:206-->
If it does not, then there is a problem registering the UUID on the interface and you should restart kdeconnectd and check the logs etc for information.
 
=== Debug logging === <!--T:217-->
 
<!--T:218-->
On many systems (including Debian/Ubuntu and Arch) kdeconnect is autostarted as a systemd user unit, you can enable debug logging by doing the following as the user (not root, do not use sudo):
<syntaxhighlight lang="bash">
systemctl edit --user [email protected]
</syntaxhighlight>
 
<!--T:219-->
Add the following content:
<pre>
[Service]
Environment=QT_LOGGING_RULES="*.debug=true; qt.debug=false;"
</pre>
then save and exit the file.
 
<!--T:220-->
Restart the unit:
<syntaxhighlight lang="bash">
systemctl restart --user [email protected]
</syntaxhighlight>
 
<!--T:221-->
Logs can then be seen with journalctl:
<syntaxhighlight lang="bash">
journalctl --user -u [email protected]
</syntaxhighlight>
 
===  My problem is not in this list :( === <!--T:127-->
 
<!--T:128-->
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].
</translate>
</translate>

Latest revision as of 09:17, 30 September 2025

Other languages:

Overview

This is the documentation page for KDE Connect. If you are developing, debugging, or building a release of KDE Connect, please refer to the community page.

KDE Connect has two parts: the desktop program and the phone app.

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 phone's battery level from the desktop
  • Ring your phone to help find it
  • Share files and links between devices
  • Browse your phone from your desktop
  • Control the desktop's volume using your phone
  • Send SMS from your desktop

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 of 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), KDE Connect already comes with the kdeconnect-indicator binary, which can be set to autostart in each environment.

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

The app for iOS can be found in Apple's proprietary App Store. Additionally, a pre-release, testing version of KDE Connect can be downloaded from TestFlight. Please see the iOS README for important data disclosure information, known limitations, and bug reporting information.

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

See KDE Connect download page for installation links for other platforms (including Windows and macOS).

Pairing two devices together

First, you need to open KDE Connect on your computer and phone. You should now be able to see in each screen the name of the device you wish to pair with. If it's not working, make sure that the two devices are connected to the same network and that there isn't any firewall blocking the two devices from seeing each other. See the troubleshooting section.

You can now request pairing in one of the two devices. The other device will show a prompt asking to accept the pairing request. Confirm it and that's it! Your devices are now paired.

While a typical configuration might include one computer and one phone, it's also possible to pair two computers instead.

Bluetooth Connectivity

In recent versions (for example v24.08.1) bluetooth connectivity has been enabled by default. To use this, you must first bluetooth pair your computer and phone.

Click Add device:

Make sure your phone is visible to pairing and it will appear, once appeared click pair:

It will pop up with a PIN to be confirmed on both the computer and the phone:

Click matches on the desktop and pair on Android

It will then be connected correctly:

Once this has been achieved open the KDE Connect on Android and enable bluetooth

On the "Add new devices" page, the computer should appear and the pairing process can be followed as usual. Refreshing this view can force the phone to attempt to rediscover. This may take some time to appear, both Android and Bluez seem to implement quite a lot of caching and this can delay how long it takes to be detected.

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.

Changing Device Names

You can only change the name of your device on the device itself. So if you want to change the name of your computer then you must use the desktop program and if you want to change the name of your phone or tablet you must make the change in the KDE Connect app. Once a device is renamed, it will automatically sync with all other connected devices.

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 the 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.

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: 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!

Available Plugins

Battery Monitor

"Show your phone battery next to your computer battery."

By enabling this, the KDE Connect widget on your panel tray will display your phone's battery.

Clipboard

"Share the clipboard between devices."

With this, you can simply copy text from your computer and it will be immediately available to paste on your phone, and vice-versa. This does not work with images though.

Auto-sync on Android 10+

Android 10 prevents apps from accessing the clipboard to prevent malicious apps from accessing your data. This makes the clipboard plugin in KDE Connect uncomfortable to use.

On Android 10+, there's an action button labeled "Send Clipboard" in the persistent indicator notification.

On Android 14+, there's a tile in the pull-down menu called "Send clipboard", that can be moved to a convenient slot (e.g. in the partial pull-down section).

Magisk Module (root only)

If you are rooted, you can use a Magisk module to remove this restriction.

Log Reading

If you have a build containing commit edc655da5ac1eb5c3027c8556cc62037a1d4c5ac, you can enable the READ_LOGS permission in order to enable a workaround to clipboard sync.

Enable USB debugging on your phone.

Run these commands: 

adb -d shell pm grant org.kde.kdeconnect_tp android.permission.READ_LOGS;
adb -d shell appops set org.kde.kdeconnect_tp SYSTEM_ALERT_WINDOW allow;
adb -d shell am force-stop org.kde.kdeconnect_tp;

How does it work?

With log reading enabled, KDE Connect watches its own log. If it sees a line indicating that it has been denied access to read the clipboard, it pops up an invisible window to the foreground, grabs the clipboard, and closes the window.

Contacts

"Synchronize contacts between devices"

This plugin silently synchronizes contacts, in vcard format, from your phone to your desktop.

As of this writing, the synchronization is one-way, with data being sent from the Android implementation to the desktop, to be consumed by any application which uses the KPeople library with the KPeopleVCard plugin, such as the KDE Connect SMS app.

VCard Location

On non-Windows platforms, contact cards are written to QStandardPaths::writableLocation(QStandardPaths::GenericDataLocation) + "/kpeoplevcard". This might be configured differently by your system, but normally resolves to ~/.local/share/kpeoplevcard.

On Windows, the path resolves to %LocalAppData%.

Inhibit Screensaver

"Inhibit the screensaver when the device is connected."

This makes sure that your screensaver will not run while your device is connected.

Multimedia Control Receiver

"Remote control your music and videos."

With this feature, you can control your music and videos remotely, with pause/play, previous/next, 5 s before/later. You can also change which media player to control, in addition to application and system volume.

Multimedia control receiver with KDE Connect in Android
Multimedia control receiver with KDE Connect in Android

Pause Media During Calls

"Pause music/videos during a phone call."

Pause music/videos during a call. This feature can be powerful when combined with Plasma Browser Integration. For example, when you are listening to some music on Peertube or Youtube, the video will be paused whenever you receive a call.

You can configure this option to pause only when you pick up your phone or directly when your phone starts to ring. You can also decide if you want to only pause the media player or/and mute the system sound.

Ping

"Send and receive pings."

This serves to test your connection to a given device. Once selected, a "Ping!" will appear as a notification on your receiving device.

On your desktop, you can send a ping through the KDE Connect settings or through the widget on the tray.

On your phone, you can send a ping through the upper right hamburger menu on the KDE Connect app.

Send a ping to your computer with android
Send a ping to your computer with android

Receive Notifications

"Show your phone notifications on your computer and keep them in sync."

This keeps you in touch with what happens on your phone! Any notifications you receive on your phone will be shown in your computer. Some notifications, such as those of Instant Messengers (IM) like Telegram can be replied on the fly through the computer notification itself.

Remote File System Browser

"Browse the remote device filesystem using SFTP."

This allows you to access your phone storage! When enabled, a device will appear in Dolphin with which you can navigate your external storage.

Ring My Phone

"Find your lost phone by making it play an alarm sound."

This also serves to test your connection to a given device, and by ringing your phone remotely, you can quickly find its location!

Run Commands

"Execute console commands directly."

With KDE Connect, you can run predefined commands on your computer by pressing buttons on your phone! Instructions on how to add a command are shown in userbase. A set of useful commands can also be found here. Some sample commands, such as suspend and lock screen, are also available.

If your device supports Device Controls (Android 11+), KDE Connect will display configured commands there. You can then quickly control your remote device, such as locking the screen. See Google's documentation for more description of device controls: https://developer.android.com/develop/ui/views/device-control

Screenshot of the device controls pane on a Samsung device, showing two configured commands, "Suspend" and "Lock Screen". In each device control tool is the command it will execute, and a prompt which says "Tap to execute".
Screenshot of the device controls pane on a Samsung device

Send Notifications

"Broadcast this computer's notifications, so they can be shown on other devices."

This is pretty self-explanatory: notifications from your computer will show up on your phone.

You can configure if you want to send the notification description, the icons pertaining to the application and persistent or very important notifications. This keeps you in touch with what happens on your computer! Any notifications you receive on your computer will be shown in your phone.

Sensitive Notification Content (Android 15+)

On Android 15+, "sensitive" notification content is hidden by the system when passed to applications. Due to this limitation, KDE Connect will show something like "Sensitive notification content hidden" instead of the real content.

(Recommended) Grant RECEIVE_SENSITIVE_NOTIFICATIONS

KDE Connect can be granted the RECEIVE_SENSITIVE_NOTIFICATIONS permission, at which point sensitive notification content will be delivered normally. This may not work on all manufacturer's devices.

  1. Set up ADB (https://developer.android.com/tools/adb).
  2. Connect the phone over ADB, either with USB or wireless ADB.
  3. Run 
    adb shell cmd appops set --user 0 org.kde.kdeconnect_tp RECEIVE_SENSITIVE_NOTIFICATIONS allow
  4. If you're facing a permission related exception: 
    java.lang.SecurityException: uid 2000 does not have android.permission.MANAGE_APP_OPS_MODES.
    upon running above command, enable Disable permission monitoring in Developer Options, reboot the phone and then run above command.
  5. Reboot the phone.
Disable Enhanced Notifications

In the notification settings for the app you want to send unrestricted notifications, disable "Enhanced notifications" which will remove this restriction.

Note that this will disable all enhanced notification functionality, such as being able to reply to messages from notifications, etc.

Share and Receive

"Receive and send files, URLs or plain text easily."

This integrates your desktop and your browser so that you can right-click on files or links and send it immediately to your phone!

Files show the right-click option "Send to phone via KDEConnect" and will send the file directly, showing it among your notifications.

Links show the right-click option "Open on phone" and will automatically open your phone's default browser on the chosen website. Really handy!

When receiving files from your phone into your computer, they will go to your Downloads folder by default. If you wish, you can change that too.

Telephone Integration

"Show notifications for incoming calls."

Whenever you get a call on your phone, a notification telling you which number is calling appears. Paired with "Pause media during calls", you'll surely be able to answer readily and never lose a call!

Virtual Input

"Use your phone as a touchpad and keyboard."

With this enabled, by going to your phone app and selecting Remote input, a touch screen will immediately be available for you to control your computer mouse, similarly to a touchpad. One touch equals one click.

The keyboard icon in the upper right allows you to type on your phone and see the result on your computer too.

If you press the hamburger menu right by its side, you'll be able to send right and middle clicks.

Presentation control

It is possible to control presentations using the previous/next slide button. When the device is locked, you can use the volume up/down button to do that. You can also highlight something using the laserpointer. Just move your phone and the blue circle will follow! Using the hamburger menu, you can toggle fullscreen (F5) or quit the presentation (Esc).

Permissions Explanations and Tutorial Videos

From time to time, Google will require video submissions to prove that we use permissions in ways which are allowed by Play Store policies. Those videos are gathered here for future reference, but also because they provide nice tutorials of how to use certain features, and are also useful to demonstrate permissions usage to a wider audience.

Android Mouse Receiver (Accessibility Permission)

In order to be a fake input device, Android requires that we take the Accessibility permission. The mouse receiver plugin is demonstrated in the following video. https://www.youtube.com/watch?v=PQ-Oubt4Rks

Other Permissions

This video demonstrates several KDE Connect features, in particular it demonstrates how KDE Connect uses certain privacy-impacting permissions, such as the SMS permissions. https://www.youtube.com/watch?v=QGHzXpX0vtk

Missing or limited features on some platforms

Some platforms are missing some features due to technical limitations or other reasons.

iOS

Missing

  • Notification sync
  • SMS
  • Keeping connection alive when app is not on-screen
  • Virtual Display

One way - only from iOS to desktop

  • Remote Input
  • Run Command
  • Slideshow Remote
  • Shared clipboard (limited, need to tap "push clipboard" on the app to push clipboard to the PC)

Android

Missing

  • Virtual Display

One way - only from Android to desktop

  • Run Command
  • Slideshow Remote
  • SMS (transfer messages to desktop and handle sending)
  • Contacts

One way - only from desktop to Android

  • SMS (retrieve from phone and dispatch send requests to phone)

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.

Check that the process is listening on the network: 

sudo netstat -tunelp | grep -i kdeconnect

Are the ports open/blocked? 

netcat -z -v <your-phones-ip> 1714-1764

Example output:

Connection to <your -phones-ip> 1716 port [tcp/*] succeeded!

You also get lots of Connection refused, but you need 1 “succeeded”

If the network connection is not the problem, you might try starting from a clean configuration again: 

killall kdeconnectd
mv ~/.config/kdeconnect ~/.config/kdeconnect.bak

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 --permanent --zone=public --add-service=kdeconnect
sudo firewall-cmd --reload

Firewall Configuration (firewall-config)

Open Firewall Configuration (firewall-config). In Zones ➔ Services, check the kde-connect service.

Make sure you choose the "Permanent" Configuration: option in the drop-down menu at the top, otherwise rebooting will discard your settings changes.

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.

KDE Connect Android app crashes

If the KDE Connect Android app crashes, you might be able to get more information about the crash by using adb logcat.

Set up ADB using the official instructions

The following command should list all information relevant to your crash. Run adb logcat *before* triggering the crash. 

adb logcat --pid=$(adb shell pidof -s org.kde.kdeconnect_tp)

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)

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.

Bluetooth

Check the logs for KDE Connect; a normal set of logs looks like:

The logs can usually be read with journalctl: 

journalctl --user [email protected]

and should contain several mentions of bluetooth. If there is a log like: 

qt.bluetooth.bluez: Bluetooth device is powered off

then the daemon was started when bluetooth was disabled and will need to be restarted until a release including https://invent.kde.org/mintsoft/kdeconnect-kde/-/commit/251ea971c5f3639a84f56bfb22237f93b4f817d2 is released.

If everything looks correct from the logging perspective then it is worth confirming that the bluetooth interface has had the service uuid added to it (this is what the client application will connect to). If you run bluetoothctl show there will be a list of UUIDs on the interface, and it should include 

UUID: Vendor specific           (185f3df4-3268-4e3f-9fca-d4d5059915bd)

If it does not, then there is a problem registering the UUID on the interface and you should restart kdeconnectd and check the logs etc for information.

Debug logging

On many systems (including Debian/Ubuntu and Arch) kdeconnect is autostarted as a systemd user unit, you can enable debug logging by doing the following as the user (not root, do not use sudo): 

systemctl edit --user [email protected]

Add the following content: 

[Service]
Environment=QT_LOGGING_RULES="*.debug=true; qt.debug=false;"

then save and exit the file.

Restart the unit: 

systemctl restart --user [email protected]

Logs can then be seen with journalctl: 

journalctl --user -u [email protected]

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.

Retrieved from "https://userbase.kde.org/index.php?title=Konversation/Scripts/Scripting_guide&oldid=498247"