Improve Session Management docs (#1735)

docs/program/apis/sessions.md

@@ -3,47 +3,55 @@ title: "Session Management with Viam's Client SDKs"
 linkTitle: "Session Management"
 weight: 20
 type: "docs"
-description: "How to use the session management API with Viam's Client SDKs."
+description: "Manage sessions between your robot and clients connected through Viam's SDKs."
 tags: ["client", "sdk", "viam-server", "networking", "apis", "robot api", "session", "sessions", "session management"]
 ---
 
-When controlling a robot or fleet with Viam, you want a way to understand the presence of the clients that are communicating with and authenticated to each robot's `viam-server`.
-The period of time during which these clients are present is called a *session*.
+When you connect to a robot using an SDK, the SDK connects to the robot's `viam-server` instance as a _client_.
+The period of time during which a client is connected to a robot is called a _session_.
 
-Session management:
+_Session management_ is a presence mechanism that allows you to manage the clients that are authenticated and communicating with a robot's `viam-server` instance.
 
-- allows a client to express that it is actively connected or authenticated to `viam-server` on your robot
-- supports stopping moving components when the connection is no longer active.
-
-*Session management* is a presence mechanism between a client and `viam-server`.
-Session management allows for safer operation of robots that physically move.
+As a safety precaution, the default session management configuration ensures that a robot only moves when a client is actively connected.
+This is especially important for robots that physically move.
 For example, imagine a wheeled rover gets a [`SetPower()`](/components/base/#setpower) command as the last input from a client before the connection to the robot is interrupted.
-Without session management, the API request from the client sets the flow of electricity to the motors of the robot and then does not time out, causing the robot to continue driving forever, colliding with objects and people.
+Without session management, the API request from the client would cause the rover's motors to move, causing the robot to continue driving forever and potentially colliding with objects and people.
+
+If you want to manage operations differently, you can manage your robot's client sessions yourself.
+The Session Management API provides functionality for
 
-With default configuration, sessions are automatically managed for you with Viam's `SessionsClient`.
-If you want to manage sessions yourself, use Viam's sessions management API.
+- clients to notify to the robot that the client is actively authenticated and connected
+- the robot to stop moving components when a session ends
 
 ### The `SessionsClient`
 
-A Viam robot has many clients because a client is anything that is receiving the information served by `viam-server` running on the robot, which includes the primary part, sub-parts, client SDKs, and more.
-A *client* of a Viam robot could be an SDK script controlling the robot, an input controller, or just the different resources on the robot talking amongst themselves.
-For example, if you use Viam's module registry to [add modular resources to your robot](/extend/modular-resources/), the clients of your robot will include the "model servers" you instantiate on your robot for individual resources.
+A _client_ of a Viam robot can be a program using an SDK to control the robot, or all the different resources on the robot,  including all {{< glossary_tooltip term_id="part" text="parts" >}} and sub-parts, like an input controller and a base, communicating.
+
+For example, if you use Viam's module registry to [add modular resources to your robot](/extend/modular-resources/), the clients of your robot will include the model servers you instantiate on your robot for individual resources, as well as the SDKs you are using to program the modular resources.
 
 Viam's session management API's `SessionsClient` is a built-in solution that manages the connection between your robot's clients and your robot.
-With the `SessionsClient`, if the robot does not receive a signal from the client at regular intervals, it safely stops until the connection is reestablished.
-Your client of the session management API maintains the session, telling the `viam-server` instance that it is still present every so often; in other words, staying within the *heartbeat* window.
+If you connect to your robot using one of Viam's SDKs, the resulting client will automatically maintain the session by sending a _heartbeat_ notifying the robot's `viam-server` instance of its continued presence.
+The `SessionsClient` on the robot maintains an overview of all sessions based on the clients' heartbeat messages.
+
+If the robot does not receive a signal from the client in the expected interval, the robot ends the session and stop all resources that are marked for safety monitoring and have been last used by that session.
+That means if a client sends a command to a robot to move the motors and then loses the connection, the robot will stop moving.
+
+{{< alert title="Caution" color="caution" >}}
+If a resource was used by client A and then by client B, and client A disconnects, the resource will not be stopped, regardless of possibly ongoing commands initiated by client A.
+{{< /alert >}}
+
+A disconnected client will attempt to establish a new session immediately prior to the next operation it performs.
 
 #### Heartbeats
 
-A *heartbeat* is a signal that indicates robot connectivity.
-Essentially, "heartbeats" are a Viam robot's way of letting a user reading data from it know the different parts of it are "alive."
+A _heartbeat_ is a signal that indicates robot connectivity.
+Essentially, heartbeats are a client's way of letting a robot know that they are still connected.
 
-Heartbeats are sent automatically from Viam's Go, Python, and TypeScript client SDKs unless you disable this with the session management API, or session management is not implemented by the server in question.
+Heartbeats are sent automatically from Viam's SDKs unless you disable them with the session management API or session management is not implemented by the server in question.
 Heartbeats are automatically sent at an interval that is one fifth of the heartbeat window.
 For example, if the heartbeat window is 5 seconds, clients will each send a heartbeat every 1 second.
 
-You can adjust the heartbeat window through the configuration of your robot.
-To do so, add Raw JSON to the configuration of your robot in this format:
+You can adjust the heartbeat window in the configuration of your robot by adding the following to your robot's Raw JSON configuration:
 
 ``` json
   ... // components {...}, services {...}, 
@@ -57,37 +65,17 @@ To do so, add Raw JSON to the configuration of your robot in this format:
 
 The default heartbeat window is 2 seconds if this configuration is omitted.
 
-If you choose to use the session management API to manage sessions, your client must send at least one session heartbeat within the window you set.
-As soon as your window lapses or expires, the server will safely stop all resources that are marked for safety monitoring that have been last used by that session, and no others.
-A lapsed client will attempt to establish a new session immediately prior to the next operation it performs.
-
-## Usage
-
-Usage of the session management API differs across [Viam's SDKS](/program/).
-
-### Access the session management API
-
-To manage sessions on-robot manually, you can use the following client SDKs:
-
-{{< tabs >}}
-{{% tab name="Go" %}}
-
-To enable the [Session Management API](https://pkg.go.dev/go.viam.com/rdk/session) the Go Client SDK provides, [disable the default behavior of sessions](#disable-default-session-management).
+If you manually manage sessions, each client must send at least one heartbeat within the window you set.
 
-{{% /tab %}}
-{{% tab name="Other SDKs" %}}
+## Manage sessions with the session management API
 
-The session management API is not currently provided in the Python or TypeScript SDKs.
+The [Session Management API](https://pkg.go.dev/go.viam.com/rdk/session) is not currently provided in the Python or TypeScript SDKs.
 Use the Go Client SDK instead.
 
-{{% /tab %}}
-{{% /tabs %}}
-
-### Use the session management API to manually manage sessions
+To manage your session with the session management API:
 
-First, use your [`RobotClient()`](/program/apis/#robot-api) instance to access the [`SessionsClient`](https://pkg.go.dev/go.viam.com/rdk/session) within your client SDK program.
-This is a [gRPC](https://grpc.io/) client that `viam-server` instantiates at robot runtime.
-Find `SessionsClient` defined on [GitHub](https://github.com/viamrobotics/rdk/blob/main/robot/client/client.go).
+1. [Disable the default session management](#disable-default-session-management)
+1. [Use the session management API to manually manage sessions](#use-the-session-management-api-to-manually-manage-sessions)
 
 ### Disable default session management
 
@@ -129,3 +117,9 @@ disableSessions: true
 This option allows you to have full control over sessions management.
 After disabling the client, you must now manage each of your sessions manually with the session management API.
 You can do this with Viam's [client SDKs](https://pkg.go.dev/go.viam.com/rdk/session).
+
+### Use the session management API to manually manage sessions
+
+Use your [`RobotClient()`](/program/apis/#robot-api) instance to access the [`SessionsClient`](https://pkg.go.dev/go.viam.com/rdk/session) within your client SDK program.
+This is a [gRPC](https://grpc.io/) client that `viam-server` instantiates at robot runtime.
+Then, define your own [`SessionsClient`](https://github.com/viamrobotics/rdk/blob/main/robot/client/client.go).