Skip to content

Help

Jump to bottom Edit New page
Stavros Ntentos edited this page Apr 12, 2024 · 60 revisions

Connecting an Android device

If you have not already installed GSConnect and the KDE Connect Android app, please see the Installation page instead.

  1. Open the Android App and GSConnect Preferences

    GSConnect & KDE Connect Android

  2. Click Refresh in GSConnect preferences or the Android app

    Service Preferences

  3. Connect to GSConnect by IP

  4. Connect to Android by IP

    Connect to...

  5. Check your Firewall, Route and VPN Settings

    The KDE Connect protocol requires ports 1716-1764 for TCP and UDP to be open. Auto-discovery requires UDP broadcasts.

    The KDE Connect wiki has further information about using OpenVPN and configuring firewalls.

  6. Open a New Issue

    If you are still having trouble connecting, please feel free to open a New Issue.

Generate Support Log

When a problem requires detailed information to debug, you may use the built-in function for generating a support log. The log will contain information about your desktop, GSConnect and detailed debugging messages.

Generate Support Log

  1. Select Generate Support Log in the menu

    A dialog will open and debug information will start being logged. Do not close the dialog yet.

  2. Take any steps necessary to reproduce the problem

    This is the most important step. You must use the functionality which is not working. For example, if you are having trouble connecting devices you must activate the Refresh action for both devices or errors will not be logged.

    Any errors or debug messages will be recorded during this period. You must leave the dialog open as long as necessary to reproduce the problem.

  3. Select Review Log in the dialog

    The default text editor will now open, allowing you to review the log. You should remove or censor any information you consider private before submitting this log.

File and Settings

WARNING: Clearing the settings in GSConnect or the KDE Connect Android App will rarely solve problems. It is far more likely that you will cause problems by doing so.

Where are the files and settings?

Cached data is stored in the user cache directory under gsconnect; usually ~/.cache/gsconnect/.

~/.cache/gsconnect/contacts.json
~/.cache/gsconnect/7b2c8d552e9043232d1466e28af55367

Cached data specific to a device is stored in a sub-directory. Plugin data is also stored in memory when in use, so you must disable a plugin before deleting its cache.

~/.cache/gsconnect/<device-id>/<plugin-name>.json
~/.cache/gsconnect/<device-id>/8ae5f579bd08e1167274e88aa79b37ea

Most settings are stored using GSettings and you can access it with dconf-editor at the path:

/org/gnome/shell/extensions/gsconnect/

The service certificate and private key are stored at the path

~/.config/gsconnect

How can I reset the settings?

To completely remove a device and all its settings, open the device preferences for that device and select Unpair from the menu. The device's stored data will be deleted, either immediately or (in the case of a connected device) when the connection is closed.

To completely remove GSConnect, all files and settings run following commands in order from the command-line:

gnome-extensions uninstall gsconnect@andyholmes.github.io
rm -rf ~/.local/share/gnome-shell/extensions/gsconnect@andyholmes.github.io
rm -rf ~/.cache/gsconnect
rm -rf ~/.config/gsconnect
dconf reset -f /org/gnome/shell/extensions/gsconnect/

Firewall Configuration

ufw

This firewall is commonly used on Ubuntu based distributions, including Pop!_OS and Linux Mint).

You can enable and use ufw(Uncomplicated Firewall):

sudo ufw enable
sudo ufw allow 1716:1764/tcp
sudo ufw allow 1716:1764/udp

reboot if ufw wasnt enabled previously.

nftables

If you are using nftables, the modern replacement for iptables, some configuration is needed to allow communication over the ports used by KDE Connect.

Edit /etc/nftables.conf and add the following rules to the beginning of the input chain:

tcp dport 1714-1764 accept comment "allow KDE Connect"
udp dport 1714-1764 accept comment "allow KDE Connect"

If you are filtering outgoing packets (not applicable to most users), add the following rules to the end of the output chain:

tcp sport 1714-1764 accept comment "allow KDE Connect"
udp sport 1714-1764 accept comment "allow KDE Connect"

Then restart to apply the changes.

For more information, see the nftables wiki or the Arch wiki on nftables.

iptables

Some users have reported that even when port 1714 to 1764 are open on firewall, iptables still need to be configured to allow connection. If that is the case, execute following commands in terminal

sudo iptables -I INPUT -i <your-interface> -p udp --dport 1714:1764 -m state --state NEW,ESTABLISHED -j ACCEPT
sudo iptables -I INPUT -i <your-interface> -p tcp --dport 1714:1764 -m state --state NEW,ESTABLISHED -j ACCEPT
sudo iptables -A OUTPUT -o <your-interface> -p tcp --sport 1714:1764 -m state --state NEW,ESTABLISHED -j ACCEPT
sudo iptables -A OUTPUT -o <your-interface> -p udp --sport 1714:1764 -m state --state NEW,ESTABLISHED -j ACCEPT

Where <your-interface> is your interface name without brackets, It is first name on nmcli or can be found using ifconfig -a or with inet addr or your network settings in GUI. Note: iptables is not persistent by itself, use iptables-save and iptables-restore (or iptables-persistent on debian/ubuntu based os) to save your rules between reboots.

Further information regarding similar issues can be found on KDEConnect community wiki

Firewalld

This firewall is commonly used in Fedora and other Red Hat distributions.

GUI:

Open Firewall Configuration (firewall-config). In Zones ➔ Services, check the kde-connect service. Turn in on if it's not.

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

CLI:

sudo firewall-cmd --permanent --zone=public --add-service=kdeconnect 
sudo firewall-cmd --reload

In the above command --zone=public, replace public with your current zone.

Troubleshooting the firewall

If you are experiencing errors and it is unclear whether the firewall is at fault, install adb on your computer. Then, enable USB debugging on your Android phone. With the phone connected to the computer via USB, run:

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

This will print error messages from the KDE Connect app itself. If you see java.net.NoRouteToHostException, then there is most likely an issue with the firewall.

Common Problems

Contacts Don't Sync

Some phone models or apps seem to have trouble exporting contacts. Please see Issue #277 for more information.

There are two ways to sync your contacts, but neither are required. If you would like to sync your contacts from Gnome Online Accounts or Evolution, please see Desktop Contacts in the Optional Dependencies section. You should disable the Contacts plugin for any devices that you want to fallback to desktop contacts.

If either of these methods fail, GSConnect will try to gather contact information from incoming phone calls and messages.

SMS Messages Don't Sync

Some phone models (especially Samsung) and SMS apps (especially Signal) either don't use the standard Android database, encrypt messages or use proprietary methods for storage and access. Please see Issue #320 and KDE Connect Bug #401677 for more information.

Phones Reported

  • Samsung Galaxy S6, S7, S8
  • Motorola G6
  • Nokia 7 Plus
  • Huawei P10 Lite

Apps Reported

  • Samsung Messages
  • Signal

Mount Doesn't Work

  1. First see Generate Support Log

    If there are errors in the log related to mounting you should open a New Issue

  2. Set a location in the Android App

    You must configure at least on storage location in the Filesystem expose settings.

  3. Force Quit the Android App

    Sometimes the SFTP server in the Android App gets stuck after a number of connections. Force quitting the App from the App Info screen and re-opening it has been know to fix this. Rebooting the Android device will have the same effect.

  4. Debug the Android App

    If there are no mounting errors in the log, you have configured a storage location in the app and restarted the Android App there may be a bug in the App. Assuming you have adb setup you can run the following command in a terminal:

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

    If there is an error in the Android logcat, you should open a bug at bugs.kde.org in the android-application component.

Remote Input Doesn't Work

As of v28, Remote Input is only supported on X11 and Wayland with Mutter's RemoteDesktop interface.

The following distributions DO NOT support Remote Input on Wayland:

  • Debian (with GNOME 3.36)
  • Ubuntu (all versions)

This is not a bug in GSConnect.

Remote Keyboard Not Active

NOTE: Due to an ambiguity in the protocol, the remote device will still report the keyboard as inactive when the "Handle remote keys only when editing" preference is disabled. This message can be ignored in that case (See #892).

In order to send keyboard events to a remote device it must report that the keyboard is active. If the remote device is an Android device you must follow these steps:

  • Enable the Receive remote keypresses plugin in the Android app
  • Enable the KDE Connect Remote Keyboard virtual keyboard in Android settings
  • Change the current keyboard to KDE Connect Remote Keyboard
  • Select a text entry or disable the option Handle remote keys only when editing in the plugin's settings

Update Error

Extensions Website Update Error

Whenever you update an extension from the Extensions Website, you must restart GNOME Shell. Even if you uninstall an extension then reinstall it, you must restart GNOME Shell between those steps.

This is a known issue with the website, with a pending fix. To avoid this error allow the Extensions App to update your extensions, which will notify you when you need to restart GNOME Shell.

Waiting for Service

If the Preferences window displays the message Waiting for service..., there are a few possible causes:

  1. The GSConnect service is turned off

    • Open the User Menu in the top-right of the screen
    • Open the Mobile Settings submenu
    • Select the Turn On item

  2. User Extensions are disabled in GNOME Shell

    Occasionally when an extension encounters a fatal error or causes GNOME Shell to crash, all User Extensions will be automatically disabled. You can re-enable them in GNOME Tweaks or with the command:

    $ dconf write /org/gnome/shell/disable-user-extensions false

  3. The DBus service is not launching

    • Try running the following command in a terminal: 
      $ gapplication launch org.gnome.Shell.Extensions.GSConnect
    • If that command returns an error message similar to the following:

      error sending Activate message to application: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name is not activatable

    • Restart the session DBus: 
      $ systemctl --user reload dbus-broker.service

If all else fails, try restarting Gnome Shell (e.g. logout then login)

Uncommon Problems

Interference with Other Equipment

Some users have reported that KDE Connect broadcasts (UDP Port 1716) can interfere with some equipment. The cause is unknown, but seems to only affect very few network connected devices such as PLCs and Wi-Fi repeaters.

Error Loading Extension

If GNOME Tweaks reports "Error loading extension", or executing the command gnome-extensions info gsconnect@andyholmes.github.io returns a state of ERROR, the GSConnect and GNOME Shell versions installed may not be compatible.

You should check if the version of GSConnect you have installed is compatible with your GNOME Shell.

If GSConnect was installed through a package manager such as apt, it's worth noting those distributions are not maintained by the maintainers of this project and may not be up-to-date. In these cases, consider switching to the recommended method of installation.

Updating Menu Actions on the Fly

Some changes (e.g., menu actions) require restarting the GSConnect service to apply. You can do so with the following command in the terminal:

touch ~/.local/share/gnome-shell/extensions/gsconnect@andyholmes.github.io/service/daemon.js

This action forces a reload of the daemon and can help apply the changes.

Detected Problems

These problems are automatically detected by GSConnect. Do not edit this section.

Network Error

GSConnect requires ports 1716-1764 for TCP and UDP. This error means another program is using those ports, usually KDE Connect (kdeconnectd).

  1. Check if KDE Connect is running

    If you have recently uninstalled KDE Connect the server may still be running.

    $ pidof kdeconnectd
18839
$ lsof -i UDP:1716
COMMAND     PID   USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
kdeconnec 18839 andrew   19u  IPv6 2394913      0t0  UDP *:1716

  2. Stop KDE Connect (kdeconnectd) if it is running

    You should also uninstall KDE Connect, since it will start each time you log into your session.

    $ killall -9 kdeconnectd

PulseAudio Error

GSConnect uses the PulseAudio bindings shipped with Gnome Shell for volume control features. This error means that GSConnect failed to find the required typelib (Gvc-1.0.typelib).

If you installed GSConnect from https://extensions.gnome.org or Zip file, please open a New Issue including your distribution and output of locate Gvc-1.0.typelib.

If you installed GSConnect from a distribution package, please file a bug with the package maintainer and reference the Packaging page.

OpenSSL not found

GSConnect uses the openssl command-line tool to generate TLS certificates and RSA keys. This error means GSConnect could not find OpenSSL, which usually happens for Fedora Silverblue users.

Fedora Silverblue users have reported this can be installed with the following commands:

$ rpm-ostree install openssl
$ systemctl reboot
Add a custom footer
Clone this wiki locally