Skip to content

Commit

Permalink
DOCS-3138: Add bind address reference docs
Browse files Browse the repository at this point in the history
  • Loading branch information
npentrel committed Nov 26, 2024
1 parent 647c0bc commit ced3e47
Show file tree
Hide file tree
Showing 4 changed files with 29 additions and 51 deletions.
Binary file removed assets/build/configure/network.png
Binary file not shown.
Binary file removed assets/build/program/sessions/heartbeatwindow.png
Binary file not shown.
46 changes: 0 additions & 46 deletions docs/appendix/apis/sessions.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,52 +59,6 @@ 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**:

{{<imgproc src="/build/program/sessions/heartbeatwindow.png" alt="Heartbeat window configuration pane in Viam app" resize="400x" declaredimensions=true >}}

{{% /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.
Expand Down
34 changes: 29 additions & 5 deletions docs/configure/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

{{<imgproc src="/build/configure/network.png" resize="x400" style="width: 300px" declaredimensions=true alt="The network configuration interface on a part card of a machine.">}}
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 >}}

<!-- prettier-ignore -->
| 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

Expand Down

0 comments on commit ced3e47

Please sign in to comment.