From 7d1fbed9a767ca6c61be91196476a5d79ea1228c Mon Sep 17 00:00:00 2001
From: JessamyT <75634662+JessamyT@users.noreply.github.com>
Date: Thu, 14 Sep 2023 11:26:46 -0400
Subject: [PATCH 01/10] DOCS-1088: Document more of the cloud API (#1814)
---
docs/program/apis/cloud.md | 290 +++++++++++++++++++++++++-
static/include/services/apis/cloud.md | 11 +-
2 files changed, 295 insertions(+), 6 deletions(-)
diff --git a/docs/program/apis/cloud.md b/docs/program/apis/cloud.md
index 459edc7203..9c4d0990ed 100644
--- a/docs/program/apis/cloud.md
+++ b/docs/program/apis/cloud.md
@@ -67,7 +67,7 @@ The cloud API supports the following methods (among [others](https://python.viam
### ListOrganizations
-List the organizations the user is an authorized user of.
+List the {{< glossary_tooltip term_id="organization" text="organizations" >}} the user is an authorized user of.
{{< tabs >}}
{{% tab name="Python" %}}
@@ -91,7 +91,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
### ListOrganizationMembers
-List the members and invites of the organization that you are currently authenticated to.
+List the members and invites of the {{< glossary_tooltip term_id="organization" text="organizations" >}} that you are currently authenticated to.
{{< tabs >}}
{{% tab name="Python" %}}
@@ -117,7 +117,7 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
### GetOrganizationNamespaceAvailability
-Check the availability of an organization namespace.
+Check the availability of an {{< glossary_tooltip term_id="organization" text="organization" >}} namespace.
{{< tabs >}}
{{% tab name="Python" %}}
@@ -188,9 +188,289 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/
{{% /tab %}}
{{< /tabs >}}
+### CreateLocation
+
+Create and name a {{< glossary_tooltip term_id="location" text="location" >}} under the organization you are currently authenticated to.
+Optionally, put the new location under a specified parent location.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `name` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Name of the new location.
+- `parent_location_id` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Optional parent location to put the location under.
+Defaults to creating a location in your organization at root level if you do not provide a location ID.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid name (such as "") or invalid parent location ID is passed.
+
+**Returns:**
+
+- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The newly created location.
+
+```python {class="line-numbers linkable-line-numbers"}
+my_new_location = await cloud.create_location(name="Robotville", parent_location_id="111ab12345")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.create_location).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### GetLocation
+
+Get a {{< glossary_tooltip term_id="location" text="location" >}} by its location ID.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to get.
+Defaults to the location ID provided at `AppClient` instantiation.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid location ID is passed, or if one isn't passed and no location ID was provided at `AppClient` instantiation.
+
+**Returns:**
+
+- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The location corresponding to the provided ID.
+
+```python {class="line-numbers linkable-line-numbers"}
+location = await cloud.get_location(location_id="123ab12345")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_location).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### UpdateLocation
+
+Change the name of a {{< glossary_tooltip term_id="location" text="parent location" >}} and/or assign it a new location.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to update.
+- `name` [Optional(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Optional new name to update the location name to.
+If nothing is passed, the name is not changed.
+- `parent_location_id` [Optional(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): Optional ID of the new location to move the location to.
+If nothing is passed, the location does not move.
+If an empty string is passed, the location moves up to the top level.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid location ID is passed, or if one isn't passed and no location ID was provided at `AppClient` instantiation.
+
+**Returns:**
+
+- [(viam.proto.app.Location)](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location): The newly updated location.
+
+```python {class="line-numbers linkable-line-numbers"}
+# The following line takes the location with ID "abc12abcde" and moves it
+# to be a sub-location of the location with ID "xyz34xxxxx"
+my_updated_location = await cloud.update_location(
+ location_id="abc12abcde",
+ name="",
+ parent_location_id="xyz34xxxxx",
+)
+
+# The following line changes the name of the location without changing its parent location
+my_updated_location = await cloud.update_location(
+ location_id="abc12abcde",
+ name="Land Before Robots"
+)
+
+# The following line moves the location back up to be a top level location without changing its name
+my_updated_location = await cloud.update_location(
+ location_id="abc12abcde",
+ name="",
+ parent_location_id=""
+)
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.update_location).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### DeleteLocation
+
+Delete a {{< glossary_tooltip term_id="location" text="location" >}}.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to delete.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid location ID is passed.
+
+**Returns:**
+
+- None
+
+```python {class="line-numbers linkable-line-numbers"}
+await cloud.delete_location(location_id="abc12abcde")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.delete_location).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### ListLocations
+
+Get a list of all {{< glossary_tooltip term_id="location" text="locations" >}} under the organization you are currently authenticated to.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- None
+
+**Returns:**
+
+- (List[[viam.proto.app.Location](https://python.viam.dev/autoapi/viam/proto/app/index.html#viam.proto.app.Location)]): The list of locations.
+
+```python {class="line-numbers linkable-line-numbers"}
+locations = await cloud.list_locations()
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.list_locations).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### LocationAuth
+
+Get a location’s `LocationAuth` (location secret or secrets).
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to retrieve `LocationAuth` from.
+Defaults to the location ID provided at `AppClient` instantiation.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid location ID is passed, or if one isn't passed and no location ID was provided at `AppClient` instantiation.
+
+**Returns:**
+
+- [(viam.proto.app.LocationAuth)](https://python.viam.dev/autoapi/viam/gen/app/v1/app_pb2/index.html#viam.gen.app.v1.app_pb2.LocationAuth): The `LocationAuth` containing location secrets and secret IDs.
+
+```python {class="line-numbers linkable-line-numbers"}
+loc_auth = await cloud.location_auth(location_id="123xy12345")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.location_auth).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### CreateLocationSecret
+
+Create a new location secret.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(Optional[string])](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to generate a new secret for.
+ Defaults to the location ID provided at `AppClient` instantiation.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid location ID is passed, or if one isn't passed and no location ID was provided at `AppClient` instantiation.
+
+**Returns:**
+
+- [(viam.proto.app.LocationAuth)](https://python.viam.dev/autoapi/viam/gen/app/v1/app_pb2/index.html#viam.gen.app.v1.app_pb2.LocationAuth): The specified location's `LocationAuth` containing the newly created secret.
+
+```python {class="line-numbers linkable-line-numbers"}
+new_loc_auth = await cloud.create_location_secret()
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.create_location_secret).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### DeleteLocationSecret
+
+Delete a location secret.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `location_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the location to delete the secret from.
+ Defaults to the location ID provided at `AppClient` instantiation.
+- `secret_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The `id` of the secret to delete (not the secret string itself).
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid location ID is passed, or if one isn't passed and no location ID was provided at `AppClient` instantiation.
+
+**Returns:**
+
+- [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str):
+
+```python {class="line-numbers linkable-line-numbers"}
+await cloud.delete_location_secret(secret_id="abcd123-456-7890ab-cxyz98-989898xyzxyz")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.delete_location_secret).
+
+{{% /tab %}}
+{{< /tabs >}}
+
+### GetRobot
+
+Get a robot by its ID.
+
+{{< tabs >}}
+{{% tab name="Python" %}}
+
+**Parameters:**
+
+- `robot_id` [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): ID of the robot to get.
+
+**Raises:**
+
+- `GRPCError`: This error is raised if an invalid location ID is passed, or if one isn't passed and no location ID was provided at `AppClient` instantiation.
+
+**Returns:**
+
+- [(string)](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str): The robot.
+
+```python {class="line-numbers linkable-line-numbers"}
+robot = await cloud.get_robot(robot_id="1a123456-x1yz-0ab0-a12xyzabc")
+```
+
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_robot).
+
+{{% /tab %}}
+{{< /tabs >}}
+
### NewRobot
-Create a new robot.
+Create a new {{< glossary_tooltip term_id="robot" text="robot" >}}.
{{< tabs >}}
{{% tab name="Python" %}}
@@ -213,7 +493,7 @@ Create a new robot.
new_robot_id = await cloud.new_robot(name="beepboop")
```
-For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.get_organization_namespace_availability).
+For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/app/app_client/index.html#viam.app.app_client.AppClient.new_robot).
{{% /tab %}}
{{< /tabs >}}
diff --git a/static/include/services/apis/cloud.md b/static/include/services/apis/cloud.md
index 11c1df13e4..3d8ec8fa80 100644
--- a/static/include/services/apis/cloud.md
+++ b/static/include/services/apis/cloud.md
@@ -4,4 +4,13 @@ Method Name | Description
[`GetOrganizationNamespaceAvailability`](/program/apis/cloud/#getorganizationnamespaceavailability) | Check the availability of an organization namespace.
[`ListOrganizationMembers`](/program/apis/cloud/#listorganizationmembers) | List the members and invites of the current organization.
[`UpdateOrganizationInviteAuthorizations`](/program/apis/cloud/#updateorganizationinviteauthorizations) | Update the authorizations attached to an organization invite that has already been created.
-[`NewRobot`](/program/apis/cloud/# ) | Create a new robot.
+[`CreateLocation`](/program/apis/cloud/#createlocation) | Create and name a location.
+[`GetLocation`](/program/apis/cloud/#getlocation) | Get a location by its ID.
+[`UpdateLocation`](/program/apis/cloud/#updatelocation ) | Change the name of and/or assign a parent location to a location.
+[`DeleteLocation`](/program/apis/cloud/#deletelocation ) | Delete a location.
+[`ListLocations`](/program/apis/cloud/#listlocations ) | List locations.
+[`LocationAuth`](/program/apis/cloud/#locationauth ) | Get a location's authorization (location secrets).
+[`CreateLocationSecret`](/program/apis/cloud/#createlocationsecret ) | Create a new location secret.
+[`DeleteLocationSecret`](/program/apis/cloud/#deletelocationsecret ) | Delete a location secret.
+[`GetRobot`](/program/apis/cloud/#getrobot ) | Get a robot by robot ID.
+[`NewRobot`](/program/apis/cloud/#newrobot ) | Create a new robot.
From 29765a96d22c68091eadc3cfa29a31390a36c889 Mon Sep 17 00:00:00 2001
From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Date: Thu, 14 Sep 2023 12:56:56 -0400
Subject: [PATCH 02/10] DOCS-792: Persist tab selection to local storage
(#1825)
---
layouts/shortcodes/tabs.html | 4 +-
static/js/tabpane-persist.js | 109 +++++++++++++++++++++++++++++++++++
2 files changed, 111 insertions(+), 2 deletions(-)
create mode 100644 static/js/tabpane-persist.js
diff --git a/layouts/shortcodes/tabs.html b/layouts/shortcodes/tabs.html
index 4882c4b608..e2505add5c 100644
--- a/layouts/shortcodes/tabs.html
+++ b/layouts/shortcodes/tabs.html
@@ -7,9 +7,9 @@
{{- range $i, $e := $tabs -}}
{{- $id := printf "%s-%d" $tab_set_id $i -}}
{{- if (eq $i 0) -}}
-{{- trim .name " " -}}
+{{- trim .name " " -}}
{{ else }}
-{{- trim .name " " -}}
+{{- trim .name " " -}}
{{- end -}}
{{- end -}}
diff --git a/static/js/tabpane-persist.js b/static/js/tabpane-persist.js
new file mode 100644
index 0000000000..6256ffe90c
--- /dev/null
+++ b/static/js/tabpane-persist.js
@@ -0,0 +1,109 @@
+// Utilities
+const _tdStoragePersistKey = (tabKey) =>
+ 'td-tp-persist:' + (tabKey || '');
+
+const _tdSupportsLocalStorage = () => typeof Storage !== 'undefined';
+
+// Helpers
+function tdPersistKey(key, value) {
+ // @requires: tdSupportsLocalStorage();
+ console.log("key", key, "value", value);
+ try {
+ if (value) {
+ localStorage.setItem(key, value);
+ } else {
+ localStorage.removeItem(key);
+ }
+ } catch (error) {
+ const action = value ? 'add' : 'remove';
+ console.error(
+ `Docsy tabpane: unable to ${action} localStorage key '${key}': `,
+ error
+ );
+ }
+}
+
+// Retrieve, increment, and store tab-select event count, then returns it.
+function tdGetTabSelectEventCountAndInc() {
+ // @requires: tdSupportsLocalStorage();
+
+ const storedCount = localStorage.getItem('td-tp-persist-count');
+ let numTabSelectEvents = parseInt(storedCount) || 0;
+ numTabSelectEvents++;
+ tdPersistKey('td-tp-persist-count', numTabSelectEvents.toString());
+ return numTabSelectEvents;
+}
+
+// Main functions
+
+function tdActivateTabsWithKey(key) {
+ console.log(key)
+
+ if (!key) return;
+
+ document.querySelectorAll(`.nav-tabs > .nav-item > a[data-td-tp-persist='${key}']`).forEach((element) => {
+ console.log(element)
+ new bootstrap.Tab(element).show();
+ });
+}
+
+function tdPersistActiveTab(activeTabKey) {
+ if (!_tdSupportsLocalStorage()) return;
+
+ tdPersistKey(
+ _tdStoragePersistKey(activeTabKey),
+ tdGetTabSelectEventCountAndInc()
+ );
+ tdActivateTabsWithKey(activeTabKey);
+}
+
+// Handlers
+
+function tdGetAndActivatePersistedTabs(tabs) {
+ // Get unique persistence keys of tabs in this page
+ var keyOfTabsInThisPage = [
+ ...new Set(
+ Array.from(tabs).map((el) => el.getAttribute("data-td-tp-persist"))
+ ),
+ ];
+
+ // Create a list of active tabs with their age:
+ let key_ageList = keyOfTabsInThisPage
+ // Map to [tab-key, last-activated-age]
+ .map((k) => [
+ k,
+ parseInt(localStorage.getItem(_tdStoragePersistKey(k))) || 0,
+ ])
+ // Exclude tabs that have never been activated
+ .filter(([k, v]) => v)
+ // Sort from oldest selected to most recently selected
+ .sort((a, b) => a[1] - b[1]);
+
+ // Activate tabs from the oldest to the newest
+ key_ageList.forEach(([key]) => {
+ tdActivateTabsWithKey(key);
+ });
+
+ return key_ageList;
+}
+
+function tdRegisterTabClickHandler(tabs) {
+ tabs.forEach((tab) => {
+ tab.addEventListener('click', () => {
+ const activeTabKey = tab.getAttribute("data-td-tp-persist");
+ console.log("!!", activeTabKey)
+ tdPersistActiveTab(activeTabKey);
+ tdActivateTabsWithKey(activeTabKey)
+ });
+ });
+}
+
+// Register listeners and activate tabs
+window.addEventListener('DOMContentLoaded', () => {
+ if (!_tdSupportsLocalStorage()) return;
+
+ var allTabsInThisPage = document.querySelectorAll(".nav-tabs > .nav-item > a");
+ console.log(allTabsInThisPage);
+ tdRegisterTabClickHandler(allTabsInThisPage);
+ tdGetAndActivatePersistedTabs(allTabsInThisPage);
+});
\ No newline at end of file
From ff5fddcd596b065c9e8ddaf431aef798b5359571 Mon Sep 17 00:00:00 2001
From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Date: Thu, 14 Sep 2023 13:25:37 -0400
Subject: [PATCH 03/10] Remove console log statements (#1828)
---
static/js/tabpane-persist.js | 5 -----
1 file changed, 5 deletions(-)
diff --git a/static/js/tabpane-persist.js b/static/js/tabpane-persist.js
index 6256ffe90c..4ebbac78bb 100644
--- a/static/js/tabpane-persist.js
+++ b/static/js/tabpane-persist.js
@@ -37,12 +37,9 @@ function tdGetTabSelectEventCountAndInc() {
// Main functions
function tdActivateTabsWithKey(key) {
- console.log(key)
-
if (!key) return;
document.querySelectorAll(`.nav-tabs > .nav-item > a[data-td-tp-persist='${key}']`).forEach((element) => {
- console.log(element)
new bootstrap.Tab(element).show();
});
}
@@ -91,7 +88,6 @@ function tdRegisterTabClickHandler(tabs) {
tabs.forEach((tab) => {
tab.addEventListener('click', () => {
const activeTabKey = tab.getAttribute("data-td-tp-persist");
- console.log("!!", activeTabKey)
tdPersistActiveTab(activeTabKey);
tdActivateTabsWithKey(activeTabKey)
});
@@ -103,7 +99,6 @@ window.addEventListener('DOMContentLoaded', () => {
if (!_tdSupportsLocalStorage()) return;
var allTabsInThisPage = document.querySelectorAll(".nav-tabs > .nav-item > a");
- console.log(allTabsInThisPage);
tdRegisterTabClickHandler(allTabsInThisPage);
tdGetAndActivatePersistedTabs(allTabsInThisPage);
});
\ No newline at end of file
From 2bbaa92b3ad9a6e5ccf7b1684310c6e48f8765c7 Mon Sep 17 00:00:00 2001
From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com>
Date: Thu, 14 Sep 2023 13:35:05 -0400
Subject: [PATCH 04/10] Improve Session Management docs (#1735)
---
docs/program/apis/sessions.md | 90 ++++++++++++++++-------------------
1 file changed, 42 insertions(+), 48 deletions(-)
diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md
index cf48370682..8fc3e73e24 100644
--- a/docs/program/apis/sessions.md
+++ b/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).
From 3ad57769c645c2af8adca02de414a63ecab0f687 Mon Sep 17 00:00:00 2001
From: andf-viam <132301587+andf-viam@users.noreply.github.com>
Date: Thu, 14 Sep 2023 13:58:32 -0400
Subject: [PATCH 05/10] DOCS-1080: Add a local module (#1815)
---
.../add-local-module-config-builder.png | Bin 0 -> 35730 bytes
.../configure/add-local-module-create.png | Bin 0 -> 89069 bytes
.../configure/add-local-module-csi-cam.png | Bin 0 -> 39767 bytes
.../configure/add-local-module-list.png | Bin 0 -> 66100 bytes
docs/extend/modular-resources/_index.md | 2 +-
docs/extend/modular-resources/configure.md | 86 +++++++++++++-----
.../extend/modular-resources/create/_index.md | 4 +-
docs/extend/modular-resources/examples/csi.md | 4 +
.../modular-resources/examples/custom-arm.md | 2 +-
9 files changed, 73 insertions(+), 25 deletions(-)
create mode 100644 assets/extend/modular-resources/configure/add-local-module-config-builder.png
create mode 100644 assets/extend/modular-resources/configure/add-local-module-create.png
create mode 100644 assets/extend/modular-resources/configure/add-local-module-csi-cam.png
create mode 100644 assets/extend/modular-resources/configure/add-local-module-list.png
diff --git a/assets/extend/modular-resources/configure/add-local-module-config-builder.png b/assets/extend/modular-resources/configure/add-local-module-config-builder.png
new file mode 100644
index 0000000000000000000000000000000000000000..8c601b831d7cffb6edb617af33cbda58859e5083
GIT binary patch
literal 35730
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