From 625e0b8393221d1442f26921808355fd9bcd5ab3 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Mon, 25 Sep 2023 20:03:27 +0200 Subject: [PATCH] Update connectivity.md (#1870) --- docs/program/apis/sessions.md | 2 ++ docs/program/connectivity.md | 24 ++++++++++----------- docs/program/run.md | 40 ++++------------------------------- 3 files changed, 17 insertions(+), 49 deletions(-) diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md index cb7073193d..cb35185be6 100644 --- a/docs/program/apis/sessions.md +++ b/docs/program/apis/sessions.md @@ -28,6 +28,8 @@ 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 would cause the rover's motors to move, causing the robot to continue driving forever and potentially colliding with objects and people. +For more information, see [Client Sessions and Robot Network Connectivity](/program/connectivity/). + If you want to manage operations differently, you can manage your robot's client sessions yourself. The Session Management API provides functionality for: diff --git a/docs/program/connectivity.md b/docs/program/connectivity.md index d5bf1c5180..e82e16a198 100644 --- a/docs/program/connectivity.md +++ b/docs/program/connectivity.md @@ -3,26 +3,24 @@ title: "Client Sessions and Robot Network Connectivity" linkTitle: "Network Connectivity Issues" weight: 20 type: "docs" -description: "Whan a robot loses its connection to the internet, all client sessions will timeout and end by default." +description: "When a robot loses its connection to a LAN or WAN, all client sessions will timeout and end by default." tags: ["client", "sdk", "viam-server", "networking", "apis", "robot api", "session"] --- -What happens when your robot loses its connection to the internet over a LAN or WAN and can no longer communicate with clients through [the Viam app](https://app.viam.com). +When connecting to a robot using the connection code from the [code sample tab](/program/#hello-world-the-code-sample-tab), a [client session](/program/apis/sessions/) automatically uses the most efficient route to connect to your robot either through local LAN or WAN or the internet. -## How does `viam-server` work if your robot loses its network connection? +When a robot loses its connection to the internet but is still connected to a LAN or WAN: -When a robot loses its connection over LAN or WAN, it can no longer communicate with clients through [the Viam app](https://app.viam.com). -When no heartbeat has been received over a timeout period, `viam-server` will end any current client [_sessions_](/program/apis/sessions/) on this robot. +- Client sessions connected through the same LAN or WAN will function normally. +- Client sessions connected through the internet will timeout and end. + If the client is on the same LAN or WAN but the route it chose to connect is through the internet, the client will automatically disconnect and then reconnect over LAN. +- [Cloud Sync](/services/data/#cloud-sync) for Data Management will pause until the internet connection is re-established since the robot will be unable to connect to the [Viam app](https://app.viam.com). -## What happens to clients connected to the robot when your robot loses its network connection? +When a robot loses its connection to LAN or WAN, all client sessions will timeout and end by default. -When your client cannot connect to your robot's `viam-server` instance, all client operations will timeout automatically and halt. -Any active commands will be cancelled, stopping any moving parts, and no new commands will be able to reach the robot until the connection is restored. +## Client session timeout and end -### How do Viam's client SDKs work if your robot loses its network connection? +When your client cannot connect to your robot's `viam-server` instance, `viam-server` will end any current client [_sessions_](/program/apis/sessions/) on this robot and all client operations will [timeout automatically](/program/apis/sessions/#heartbeats) and halt: any active commands will be cancelled, stopping any moving parts, and no new commands will be able to reach the robot until the connection is restored. -As a client of your robot, Viam's SDKs will by default have their session ended when the robot loses its connection to the internet. - -To disable the default behavior here and manage resource timeout and reconfiguration over a networking session yourself, follow [these instructions](/program/apis/sessions/). -[Disable the default behavior](/program/apis/sessions/#disable-default-session-management) of session management, then utilize [Viam's SDKs](/program/) in your code to make calls to [the session management API](https://pkg.go.dev/go.viam.com/rdk/session#hdr-API). +To disable the default behavior and manage resource timeout and reconfiguration over a networking session yourself, you can [disable the default behavior](/program/apis/sessions/#disable-default-session-management) of session management, then use [Viam's SDKs](/program/) in your code to make calls to [the session management API](https://pkg.go.dev/go.viam.com/rdk/session#hdr-API). diff --git a/docs/program/run.md b/docs/program/run.md index 86a3102a36..e9b3701586 100644 --- a/docs/program/run.md +++ b/docs/program/run.md @@ -12,11 +12,11 @@ After saving your [code sample](/program/#hello-world-the-code-sample-tab) and a ### Authentication -You must reference a robot's location secret to authenticate yourself to the robot. +You must authenticate yourself to the robot using the robot's location secret. However, the app hides the robot location secret from the sample by default for your security. To copy the robot location secret, select **Include Secret** on the **Code sample** tab of your robot's page on the [Viam app](https://app.viam.com). -Paste it into your SDK code as directed by the code sample. +Paste it into your environment variables or directly into your code. You must also include the robot's remote address, like `12345.somerobot-main.viam.cloud`, as an external or public address to connect to your robot. The code sample includes this address at default. @@ -71,38 +71,6 @@ This is useful because as long as that computer is able to establish a network c ## Run Code On-Robot -{{< alert title="Info" color="info" >}} -This method of running code locally is only implemented on the Viam Python SDK. -{{< /alert >}} - -In case your robots have intermittent internet connectivity, you can ensure this does not interfere with the code's execution. -If you need to run [PID control loops](https://en.wikipedia.org/wiki/PID_controller) or other on-robot code, you can run control code on the same board that is running `viam-server`. - -In the `connect()` method of your control code, make the following changes: - -1. Set `disable_webrtc=True` to disable {{< glossary_tooltip term_id="webrtc" >}}. -2. Set `auth_entity` to your robot's [configured](/manage/configuration/) `name`. -3. Replace the remote address in `RobotClient.at_address` with `localhost:8080` - -Your SDK code should now look like: - -```python {class="line-numbers linkable-line-numbers"} -async def connect(): - creds = Credentials(type='robot-location-secret', - payload=YOUR_LOCATION_SECRET) - opts = RobotClient.Options( - refresh_interval=0, - dial_options=DialOptions( - credentials=creds, - disable_webrtc=True, - auth_entity="<YOUR_ROBOT_NAME>" - ) - ) - return await RobotClient.at_address('localhost:8080', opts) -``` - -Your localhost can now make a secure connection to `viam-server` locally. -SSL will check the server hostname against the `auth_entity` required by {{< glossary_tooltip term_id="grpc" >}} from the `auth_entity` `DialOptions`. +In case you run [PID control loops](https://en.wikipedia.org/wiki/PID_controller) or your robots have intermittent network connectivity, you can ensure this does not interfere with the code's execution, by running the the control code on the same board that is running `viam-server`. -This ensures that you can send commands to the robot through localhost without internet connectivity. -Note that all commands will be sent using {{< glossary_tooltip term_id="grpc" >}} only without {{< glossary_tooltip term_id="webrtc" >}}. +When connecting to a robot using the connection code from the [code sample tab](/program/#hello-world-the-code-sample-tab), a [client session](/program/apis/sessions/) automatically uses the [most efficient route](/program/connectivity/) to connect to your robot, which means the favored route for commands will be over localhost.