diff --git a/assets/build/configure/network.png b/assets/build/configure/network.png deleted file mode 100644 index 4d7246a27d..0000000000 Binary files a/assets/build/configure/network.png and /dev/null differ diff --git a/assets/build/program/sessions/heartbeatwindow.png b/assets/build/program/sessions/heartbeatwindow.png deleted file mode 100644 index 9b83cec6d8..0000000000 Binary files a/assets/build/program/sessions/heartbeatwindow.png and /dev/null differ diff --git a/docs/appendix/apis/sessions.md b/docs/appendix/apis/sessions.md index ba964ae522..c6cb319e5e 100644 --- a/docs/appendix/apis/sessions.md +++ b/docs/appendix/apis/sessions.md @@ -59,59 +59,13 @@ If a resource was used by client A and then by client B, and client A disconnect 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 machine connectivity. -Essentially, heartbeats are a client's way of letting a machine know that they are still connected. - -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 in the configuration of your machine: - -{{< tabs >}} -{{% tab name="Builder UI" %}} - -Navigate to your machine's **CONFIGURE** tab in the [Viam app](https://app.viam.com). -Find the card belonging to the appropriate {{< glossary_tooltip term_id="part" text="part" >}} of your machine in the nested resource tree. -Click the card to expand it, then click **Set heartbeat window** to adjust the **Heartbeat window**: - -{{}} - -{{% /tab %}} -{{% tab name="JSON" %}} - -Add the following `heartbeat_window` configuration to your `network.sessions` object: - -```json - ... // components {...}, services {...}, - "network": { - "sessions": { - "heartbeat_window": "30s" // Changes heartbeat window to 30 seconds - } - }, - ... -``` - -{{% /tab %}} -{{< /tabs >}} - -{{< alert title="Note" color="note" >}} -You must restart your machine for the new `heartbeat_window` to take effect. -{{< /alert >}} - -The default heartbeat window is 2 seconds if this configuration is omitted. - -If you manually manage sessions, each client must send at least one heartbeat within the window you set. - ## Manage sessions with the session management API 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. {{< alert title="Tip" color="tip" >}} -If you are looking to implement session management yourself only to increase the session window, you can increase the session window instead, by [increasing the `heartbeat_window`](#heartbeats). +If you are looking to implement session management yourself only to increase the session window, you can increase the session window instead, by [increasing the `heartbeat_window`](/configure/#network). {{< /alert >}} To manage your session with the session management API: diff --git a/docs/configure/_index.md b/docs/configure/_index.md index 85dbe25f76..2fbe574f6b 100644 --- a/docs/configure/_index.md +++ b/docs/configure/_index.md @@ -318,13 +318,37 @@ See [Configure a Trigger](/configure/triggers/) for more information on triggers ### Network -Expand a part's configuration card to open its network configuration interface: +You can configure your machine's bind address and heartbeat window. -{{}} +On your machine's **CONFIGURE** tab, click the **+** button and select **Network**. -You can configure the address `viam-server` binds to for accepting connections. -By default, `viam-server` binds to `0.0.0.0:8080` when managed by the Viam app or when authentication and TLS are enabled. -You can also set the [heartbeat](/appendix/apis/sessions/#heartbeats) window. +{{< tabs >}} +{{% tab name="Builder UI" %}} + +In the **network** panel, configure your **Bind address** and your **Heartbeat window**. + +{{% /tab %}} +{{% tab name="JSON" %}} + +```json + ... // components {...}, services {...}, + "network": { + "bind_address": "0.0.0.0:8080", + "sessions": { + "heartbeat_window": "30s" // Changes heartbeat window to 30 seconds + } + }, + ... +``` + +{{% /tab %}} +{{< /tabs >}} + + +| Attribute | Type | Required? | Description | +| --------- | ---- | --------- | ----------- | +| `bind_address` | string | Optional | The address `viam-server` binds to for accepting connections. Default: `"0.0.0.0:8080"` when managed by the Viam app or when authentication and TLS are enabled. | +| `sessions.heartbeat_window` | string | Optional | A _heartbeat_ is a signal that indicates machine connectivity. 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. Default: `"2s"`. Use a higher value in high-latency networks. Requires a restart to take effect. | ## Configuration History diff --git a/docs/sdks/connectivity.md b/docs/sdks/connectivity.md index c902f4c06d..5ebedc6cd1 100644 --- a/docs/sdks/connectivity.md +++ b/docs/sdks/connectivity.md @@ -25,7 +25,7 @@ When a machine loses its connection to LAN or WAN, all client sessions will time ## Client session timeout and end -When your client cannot connect to your machine's `viam-server` instance, `viam-server` will end any current client [_sessions_](/appendix/apis/sessions/) on this machine and all client operations will [timeout automatically](/appendix/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 machine until the connection is restored. +When your client cannot connect to your machine's `viam-server` instance, `viam-server` will end any current client [_sessions_](/appendix/apis/sessions/) on this machine and all client operations will [timeout automatically](/appendix/apis/sessions/) and halt: any active commands will be cancelled, stopping any moving parts, and no new commands will be able to reach the machine until the connection is restored. To disable the default behavior and manage resource timeout and reconfiguration over a networking session yourself, you can [disable the default behavior](/appendix/apis/sessions/#disable-default-session-management) of session management, then use [Viam's SDKs](/sdks/) in your code to make calls to [the session management API](https://pkg.go.dev/go.viam.com/rdk/session#hdr-API).