README.md 4.65 KB
Newer Older
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
1 2 3 4 5 6
# KDE Connect - desktop app

KDE Connect is a multi-platform app that allows your devices to communicate (eg: your phone and your computer).

## (Some) Features
- **Shared clipboard**: copy and paste between your phone and your computer (or any other device).
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
7
- **Notification sync**: Read and reply to your Android notifications from the desktop.
Varun Patel's avatar
Varun Patel committed
8
- **Share files and URLs** instantly from one device to another including some filesystem integration.
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
9
- **Multimedia remote control**: Use your phone as a remote for Linux media players.
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
10
- **Virtual touchpad**: Use your phone screen as your computer's touchpad and keyboard.
Varun Patel's avatar
Varun Patel committed
11
- **Presentation remote**: Advance your presentation slides straight from your phone.
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
12

Varun Patel's avatar
Varun Patel committed
13
All this is done completely wirelessly, utilising TLS encryption.
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
14 15

## Supported platforms
Varun Patel's avatar
Varun Patel committed
16 17
- Computers running Linux with Plasma 5, Gnome 3, Elementary OS... any distro with Qt5 support given a little work :)
- Android, by installing the KDE Connect app from the [Play Store](https://play.google.com/store/apps/details?id=org.kde.kdeconnect_tp) or [F-Droid](https://f-droid.org/repository/browse/?fdid=org.kde.kdeconnect_tp).
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
18 19

## How to install
Varun Patel's avatar
Varun Patel committed
20
These instructions explain how to install KDE Connect on your computer. You will also need to install it on your Andriod device and pair them together in the app before using this application. The Android app repository can be found [here](https://cgit.kde.org/kdeconnect-android.git/)
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
21 22

### On Linux
Varun Patel's avatar
Varun Patel committed
23
Look in your distribution repo for a package called `kdeconnect-kde`, `kdeconnect-plasma`, or just `kdeconnect`. If it's not there and you know how to build software from sources, you just found the repo :), instructions are [here](https://community.kde.org/KDEConnect#Building_KDE_Connect_.28Desktop.29)
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
24 25

### On Mac or Windows
Varun Patel's avatar
Varun Patel committed
26
Platforms other than Linux are not officially supported, as there has yet to be an official release of KDE Connect for MacOS or Windows. However, most of the features have already been ported to windows so you can compile KDE Connect for Windows using [Craft](https://community.kde.org/Craft). It hasn't yet been completely tested on MacOS, contributions and feedback are welcome!
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
27 28

### On BSD
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
29
It should work, but no promises :)
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
30 31 32 33 34 35 36 37 38

## How does it work?
KDE Connect consists of an UI-agnostic "core" library which exposes a series of DBus interfaces, and several UI components that consume these DBus interfaces. This way, new UI components can be added to integrate better with specific platforms or desktops, without having to reimplement the protocol or any of the internals. The core KDE Connect library is also divided in 4 big blocks:

- **LinkProviders**: Are in charge of discovering other KDE Connect-enabled devices in the network and establishing a Link to them.
- **Devices**: Represent a remote device, abstracting the specific Link that is being used to reach it.
- **NetworkPackets**: JSON-serializable and self-contained pieces of information to be sent by the plugins between devices.
- **Plugins**: Independent pieces of code which implement a specific feature. Plugins will use NetworkPackets to exchange information through the network with other Plugins on a remote Device.

Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
39
The basic structure of a NetworkPacket is the following:
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
40 41 42 43 44 45 46 47 48 49

```
{
  "id": 123456789,
  "type": "com.example.myplugin",
  "body": {  },
  "version": 5
}
```

50
The content of the `"body"` section is defined by each Plugin. Hence, only the emisor and receiver plugins of a given packet type need agree on the contents of the body.
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
51 52 53 54 55 56

NetworkPackets can also have binary data attached that can't be serialized to JSON. In this case, two new fields will be added:

`"payloadSize"`: The size of the file, or -1 if it is a stream without known size.  
`"payloadTransferInfo"`: Another JSON object where the specific Link can add information so the Link in the remote end can establish a connection and receive the payload (eg: IP and port in a local network). It's up to the Link implementation to decide how to use this field.

Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
57 58
## Contributing

59
To contribute patches, use [KDE Connect's GitLab](https://invent.kde.org/kde/kdeconnect-kde). There you can also find a task list with stuff to do, and links to other relevant resources. It is a good idea to also subscribe to the [KDE Connect mailing list](https://mail.kde.org/mailman/listinfo/kdeconnect). We can also be reached on IRC at #kdeconnect on freenode or on [telegram](https://t.me/joinchat/AOS6gA37orb2dZCLhqbZjg), contributions and feedback are warmly welcomed.
Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
60

Albert Vaca Cintora's avatar
Albert Vaca Cintora committed
61 62 63
## License
[GNU GPL v2](https://www.gnu.org/licenses/gpl-2.0.html) and [GNU GPL v3](https://www.gnu.org/licenses/gpl-3.0.html)

64
If you are reading this from Github, you should know that this is just a mirror of the [KDE Project repo](https://cgit.kde.org/kdeconnect-kde.git).