Merge pull request #3887 from raspberrypi/connect-2.0

Update Connect documentation for 2.0

documentation/asciidoc/services/connect/install.adoc

@@ -1,7 +1,7 @@
 [[install-connect]]
 == Install
 
-To begin installation, open a Terminal window. Run the following command to update your system and packages:
+If Connect isn't already installed in your version of Raspberry Pi OS, open a Terminal window. Run the following command to update your system and packages:
 
 [source,console]
 ----
@@ -16,14 +16,18 @@ Run the following command on your Raspberry Pi to install Connect:
 $ sudo apt install rpi-connect
 ----
 
-After installation, reboot your Raspberry Pi or xref:connect.adoc#manually-start-connect[manually start the Connect service] to use Connect:
+You can also install Connect from the Recommended Software application.
+
+After installation, use the `rpi-connect` command line interface to start Connect for your current user:
 
 [source,console]
 ----
-$ sudo reboot
+$ rpi-connect on
 ----
 
-Connect will automatically start the next time you log in to your Raspberry Pi.
+Alternatively, click the Connect icon in the menu bar to open a dropdown menu and select *Turn On Raspberry Pi Connect*:
+
+image::images/turn-on-connect.png[width="80%"]
 
 === Connect Lite
 
@@ -36,19 +40,29 @@ Run the following command on your Raspberry Pi to install Connect Lite:
 $ sudo apt install rpi-connect-lite
 ----
 
-Reboot your Raspberry Pi or xref:connect.adoc#manually-start-connect[manually start the Connect service] to use Connect.
+After installation, use the `rpi-connect` command line interface to start Connect for your current user:
+
+[source,console]
+----
+$ rpi-connect on
+----
 
-Consider xref:connect.adoc#enable-remote-shell-at-all-times[enabling user lingering] to make your device accessible even when your user account isn't logged in.
+xref:connect.adoc#enable-remote-shell-at-all-times[Enable user-lingering] to make your device accessible even when your user account isn't logged in.
 
 TIP: Lite commands use the same `rpi-connect` name as the full version of Connect. `rpi-connect-lite` is just a package name.
 
-=== Manually start Connect
+=== Manually start and stop Connect
+
+To start Connect from the command line, run the following command:
 
-NOTE: By default, Connect automatically starts at login. You don't need to manually start Connect after it starts for the first time unless you remove it from your login items.
+[source,console]
+----
+$ rpi-connect on
+----
 
-To start the service manually from the command line, run the following command:
+To stop Connect, run the following command:
 
 [source,console]
 ----
-$ systemctl --user start rpi-connect
+$ rpi-connect off
 ----

documentation/asciidoc/services/connect/introduction.adoc

@@ -4,7 +4,7 @@ Raspberry Pi Connect provides secure access to your Raspberry Pi from anywhere i
 
 image::images/hero.png[width="100%"]
 
-To use Connect, xref:connect.adoc#install-connect[install the Connect software] on your Raspberry Pi. Then visit https://connect.raspberrypi.com[connect.raspberrypi.com] to access the desktop or a shell running on your Raspberry Pi in a browser window.
+To use Connect, xref:connect.adoc#install-connect[install the Connect software] and xref:connect.adoc#link-connect[link your device with an account] on your Raspberry Pi. Then visit https://connect.raspberrypi.com[connect.raspberrypi.com] to access the desktop or a shell running on your Raspberry Pi in a browser window.
 
 Connect uses a secure, encrypted connection. By default, Connect communicates directly between your Raspberry Pi and your browser. However, when Connect can't establish a direct connection between your Raspberry Pi and your browser, we use a relay server. In such cases, Raspberry Pi only retains the metadata required to operate Connect.
 

documentation/asciidoc/services/connect/troubleshooting.adoc

@@ -10,6 +10,63 @@
 
 * Browsers intercept certain keys and key combinations. As a result, you can't type these keys into your Connect window. Screen sharing includes a toolbar to simulate some of the most popular intercepted keys.
 
+* To upgrade from version 1 to version 2, you must first upgrade the package you currently have installed before switching between `rpi-connect` and `rpi-connect-lite`. This ensures that Connect's services properly migrate to the version 2 format. If you currently have `rpi-connect` installed, run the following command:
++
+[source,console]
+----
+$ sudo apt install --only-upgrade rpi-connect
+----
++
+Alternatively, if you currently have `rpi-connect-lite` installed, run the following command:
++
+[source,console]
+----
+$ sudo apt install --only-upgrade rpi-connect-lite
+----
++
+You should see output similar to the following during the upgrade, indicating that Connect's services have migrated to the version 2 format:
++
+[source,console]
+----
+Replacing globally-enabled rpi-connect services with user-enabled ones...
+----
+
+=== Common issues
+
+==== Screen sharing not available
+
+If Connect states that screen sharing is unavailable, it cannot connect to the dedicated Connect WayVNC service.
+
+To find out more about the cause of the issue, run the following commands to check the status of the Connect WayVNC service:
+
+[source,console]
+----
+$ systemctl --user status rpi-connect-wayvnc.service
+$ journalctl --user --follow --unit rpi-connect-wayvnc.service
+----
+
+If the service fails to start or doesn't exist, ensure that your environment meets the following criteria:
+
+. You use `rpi-connect` version 1.1.0 or later.
+. You do not use `rpi-connect-lite`, which lacks screen sharing support.
+. You use a Wayland compositor such as wayfire or labwc, not X. You can control this setting via ``raspi-config``'s Advanced Options.
+. You use a desktop environment supported by WayVNC, e.g. Raspberry Pi Desktop. For instance, using KDE switches your Wayland compositor to kwin, which is unsupported.
+. You have an active graphical desktop session running as the same user as the one you signed into. For most, this means enabling "Desktop Autologin" via ``raspi-config``'s System Options.
+
+==== Can't connect after restarting or ending SSH session
+
+Connect runs as a user-level service and is therefore only available if there is an active session for the user signed into the service. If you want remote shell access without also running another login session, xref:connect.adoc#enable-remote-shell-at-all-times[enable user-lingering] for your user, which will keep Connect running at all times.
+
+For screen sharing, Connect can only share an existing graphical desktop session: it does not create entirely new sessions. There must already be a desktop session in progress. To start such a session automatically on boot, enable Desktop Autologin via ``raspi-config``'s System Options.
+
+==== Networking and firewall issues
+
+Connect avoids changing your network or firewall in order to establish a connection. However, if you have a restrictive network and experience trouble connecting, check the following:
+
+. Can you access the Connect API, which Connect uses for authentication and connection negotiation between your Raspberry Pi and your browser? To check, load https://api.connect.raspberrypi.com/up?[https://api.connect.raspberrypi.com/up?] on your Raspberry Pi.
+. Can you access the Connect STUN server, which Connect uses to obtain a peer-to-peer connection through local or public networks? To check, ping `stun.raspberrypi.com` on UDP port 3478.
+. Can you access our TURN servers, which Connect uses to relay sessions when a peer-to-peer connection fails? To check, ping `turn1.raspberrypi.com`, `turn2.raspberrypi.com` and `turn3.raspberrypi.com` on TCP ports 3478 or 443, or UDP ports 3478, 443 and 49152 -> 65535.
+
 === View Connect status
 
 To view the current status of the Connect service, run the following command:
@@ -19,19 +76,29 @@ To view the current status of the Connect service, run the following command:
 $ rpi-connect status
 ----
 
+You should see output similar to the following:
+
+----
+Signed in: yes
+Screen sharing: allowed (0 sessions active)
+Remote shell: allowed (0 sessions active)
+----
+
 The output of this command indicates whether or not you are currently signed in to Connect, as well as the remote services enabled on your Raspberry Pi.
 
+If you see output including "Raspberry Pi Connect is not running, run rpi-connect on", run `rpi-connect on` to start Connect.
+
 === Enable enhanced logging
 
 You can enable debug logging for both `rpi-connect` and its dedicated WayVNC server for a detailed account of local operations on your Raspberry Pi.
 
 ==== Enable enhanced logging in `rpi-connect`
 
-Open the `rpi-connect` configuration file for editing with the following command:
+Override the `rpi-connect` service definition with the following command:
 
 [source,console]
 ----
-$ systemctl --user edit rpi-connect
+$ systemctl --user edit rpi-connect.service
 ----
 
 Enter the following lines of configuration between the comments:
@@ -45,23 +112,23 @@ ExecStart=/usr/bin/rpi-connectd -socket %t/rpi-connect-wayvnc.sock -v
 
 NOTE: You need **both** lines that begin with `ExecStart=`.
 
-Finally, restart the service with the following command:
+Finally, restart Connect with the following command:
 
 [source,console]
 ----
-$ systemctl --user restart rpi-connect
+$ rpi-connect restart
 ----
 
 ==== Enable enhanced logging in the dedicated `wayvnc` server
 
-Open the configuration file for the dedicated WayVNC server associated with Connect:
+Override the `rpi-connect-wayvnc` service definition with the following command:
 
 [source,console]
 ----
 $ systemctl --user edit rpi-connect-wayvnc
 ----
 
-Enter the following lines of configuration between the comments:
+Enter the following lines of configuration between the comments (including the `-Ldebug` flag):
 
 [source,bash]
 ----
@@ -72,11 +139,11 @@ ExecStart=/usr/bin/rpi-connect-env /usr/bin/wayvnc --config /etc/rpi-connect/way
 
 NOTE: You need **both** lines that begin with `ExecStart=`.
 
-Finally, restart the service with the following command:
+Finally, restart Connect with the following command:
 
 [source,console]
 ----
-$ systemctl --user restart rpi-connect-wayvnc
+$ rpi-connect restart
 ----
 
 === View Connect logs
@@ -85,5 +152,5 @@ To view logs for the Connect service and its dedicated WayVNC server, run the fo
 
 [source,console]
 ----
-$ journalctl --user --follow --unit rpi-connect --unit rpi-connect-wayvnc
+$ journalctl --user --follow --unit rpi-connect.service --unit rpi-connect-wayvnc.service
 ----