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,16 @@ 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:
+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, if the Connect plugin is running in your menu bar, you can choose "Turn On Raspberry Pi Connect" from the dropdown menu:
+
+image::images/turn-on-connect.png[width="80%"]
 
 === Connect Lite
 
@@ -36,19 +38,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
 
-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.
+To start Connect from the command line, run the following command:
+
+[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,28 +10,74 @@
 
 * 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.
 
+=== Common issues
+
+==== Screen sharing not available
+
+If Connect states that screen sharing is "unavailable" that means it cannot connect to its dedicated WayVNC service.
+
+The first step is to check the status of the WayVNC service:
+
+[source,console]
+----
+$ systemctl --user status rpi-connect-wayvnc.service
+$ journalctl --user --follow --unit rpi-connect-wayvnc.service
+----
+
+If it is failing to start or that service isn't found at all, please ensure the following:
+
+. You're using rpi-connect version 1.1.0 or later (and not rpi-connect-lite which lacks screen sharing support)
+. You're using a Wayland compositor such as Wayfire (enabled via raspi-config's Advanced Options and on by default for Raspberry Pi 4 and 5 with Raspberry Pi OS Bookworm) and not X11
+. You're using a desktop environment supported by WayVNC, e.g. Raspberry Pi Desktop. (Note that using KDE will switch 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 having any other login session running, 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: therefore, there must already be a desktop session in progress. To start such a session automatically on boot, you'll need to enable Desktop Autologin via raspi-config's System Options.
+
+==== Networking and firewall issues
+
+Connect is designed to avoid having to make changes to your network and firewall in order to establish a connection but if you have a restrictive network and are having trouble connecting, please check the following:
+
+. You can access the Connect API (required for authentication and negotiating the connection between your Raspberry Pi device and your browser), e.g. can you load https://api.connect.raspberrypi.com/up?
+. You can access our STUN server (used to obtain a peer-to-peer connection through local or public networks) on stun.raspberrypi.com and UDP port 3478
+. You can access our TURN servers (used to relay sessions if a peer-to-peer connection through local or public networks can't be made) on 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:
 
 [source,console]
 ----
 $ rpi-connect status
+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 the following, you need to run `rpi-connect on` to start Connect:
+
+[source,console]
+----
+$ rpi-connect status
+✗ Raspberry Pi Connect is not running, run rpi-connect on
+----
+
 === 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 +91,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 (note the addition of the `-Ldebug` flag):
 
 [source,bash]
 ----
@@ -72,11 +118,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 +131,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
 ----