DOCS-3174: Update machine settings (#3930)

Co-authored-by: Ale Paredes <[email protected]>
Co-authored-by: Sierra Guequierre <[email protected]>

Author: 3 people

docs/manage/fleet/provision/end-user-setup.md

@@ -139,7 +139,7 @@ Note that any features that require internet access will not function if the con
 
 You can now use your machine.
 
-If your machine needs to be able to connect to more than one WiFi network, you can add additional networks in the [`viam-agent` network configuration](/manage/reference/viam-agent/#networks).
+If your machine needs to be able to connect to more than one WiFi network, you can add additional networks in the [`viam-agent` network configuration](/manage/reference/viam-agent/#network_configuration).
 You can also override other configuration details in the [`viam-agent` configuration](/manage/reference/viam-agent/#configuration).
 
 To control your machine, you can navigate to its **CONTROL** tab in the [Viam app](https://app.viam.com).

docs/manage/fleet/provision/setup.md

@@ -187,7 +187,7 @@ Create a file called <FILE>viam-provisioning.json</FILE> with the following form
   "model": "<NAME>", # the machine's model
   "fragment_id": "<ID>", # the fragment id, required for mobile app
   "hotspot_prefix": "<PREFIX>", # machine creates a hotspot during setup
-  "disable_dns_redirect": true, # disable if using a mobile app
+  "disable_captive_portal_redirect": false, # set to true if using a mobile app
   "hotspot_password": "<PASSWORD>", # password for the hotspot
   "networks" : []
 }
@@ -202,12 +202,12 @@ Create a file called <FILE>viam-provisioning.json</FILE> with the following form
   "model": "C-3PO",
   "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663",
   "hotspot_prefix": "skywalker-setup",
-  "disable_dns_redirect": true,
+  "disable_captive_portal_redirect": false,
   "hotspot_password": "skywalker123",
-  "roaming_mode": false,
-  "offline_timeout": "3m30s",
-  "user_timeout": "2m30s",
-  "fallback_timeout": "15m"
+  "turn_on_hotspot_if_wifi_has_no_internet": false,
+  "offline_before_starting_hotspot_minutes": "3m30s",
+  "user_idle_minutes": "2m30s",
+  "retry_connection_timeout_minutes": "15m"
 }
 ```
 
@@ -228,14 +228,14 @@ It also configures timeouts to control how long `viam-agent` waits for a valid l
 | `hotspot_interface` | string | Optional | The interface to use for hotspot/provisioning/wifi management. Default: first discovered 802.11 device. |
 | `hotspot_prefix` | string | Optional | `viam-agent` will prepend this to the hostname of the device and use the resulting string for the provisioning hotspot SSID. Default: `"viam-setup"`. |
 | `hotspot_password` | string | Optional | The Wifi password for the provisioning hotspot. Default: `"viamsetup"`. |
-| `disable_dns_redirect` | boolean | Optional | By default, ALL DNS lookups using the provisioning hotspot will redirect to the device. This causes most phones/mobile devices to automatically redirect the user to the captive portal as a "sign in" screen. When disabled, only domains ending in .setup (ex: viam.setup) will be redirected. This generally avoids displaying the portal to users and is mainly used in conjunction with a mobile provisioning application workflow. Default: `false`. |
-| `roaming_mode` | boolean | Optional | By default, the device will only attempt to connect to a single wifi network (the one with the highest priority), provided during initial provisioning/setup using the provisioning mobile app or captive web portal. Wifi connection alone is enough to consider the device as "online" even if the global internet is not reachable. If the primary network configured during provisioning cannot be connected to and roaming mode is enabled, the device will attempt connections to all configured networks in `networks`, and only consider the device online if the internet is reachable. Default: `false`. |
-| `offline_timeout` | boolean | Optional | Will only enter provisioning mode (hotspot) after being disconnected longer than this time. Useful on flaky connections, or when part of a system where the device may start quickly, but the wifi/router may take longer to be available. Default: `"2m"` (2 minutes). |
-| `user_timeout` | boolean | Optional | Amount of time before considering a user (using the captive web portal or provisioning app) idle, and resuming normal behavior. Used to avoid interrupting provisioning mode (for example for network tests/retries) when a user might be busy entering details. Default: `"5m"` (5 minutes). |
-| `fallback_timeout` | boolean | Optional | Provisioning mode will exit after this time, to allow other unmanaged (for example wired) or manually configured connections to be tried. Provisioning mode will restart if the connection/online status doesn't change. Default: `"10m"` (10 minutes). |
-| `networks` | array | Optional | Add additional networks the machine can connect to for provisioning. We recommend that you add WiFi settings in the operating system (for example, directly in NetworkManager) rather than in this file, or in the corresponding machine config in the Viam app, if networks aren't needed until after initial provisioning. See [Networks](/manage/reference/viam-agent/#networks). Default: `[]`. |
-| `wifi_power_save` | boolean | Optional | If set, will explicitly enable or disable power save for all WiFi connections managed by NetworkManager.  |
-| `device_reboot_after_offline_minutes` | integer | Optional | If set, `viam-agent` will reboot the device after it has been offline for the specified duration. Default: `0` (disabled). |
+| `disable_captive_portal_redirect` | boolean | Optional | By default, all DNS lookups are redirected to the "sign in" portal, which can cause mobile devices to automatically display the portal. When set to true, only DNS requests for domains ending in .setup, like `viam.setup` are redirected, preventing the portal from appearing unexpectedly, especially convenient when using a mobile app for provisioning. Default: `false`. |
+| `turn_on_hotspot_if_wifi_has_no_internet` | boolean | Optional | By default, the device connects to a single prioritized WiFi network (provided during provisioning) and is considered online even if the global internet is not reachable. When `turn_on_hotspot_if_wifi_has_no_internet` is true and the primary network lacks internet connectivity, the device will try all configured networks and only mark itself as online if it successfully connects to the internet. Default: `false`. |
+| `offline_before_starting_hotspot_minutes` | integer | Optional | Will only enter provisioning mode (hotspot) after being disconnected longer than this time. Useful on flaky connections, or when part of a system where the device may start quickly, but the wifi/router may take longer to be available. Default: `2` (2 minutes). |
+| `user_idle_minutes` | integer | Optional | Amount of time before considering a user (using the captive web portal or provisioning app) idle, and resuming normal behavior. Used to avoid interrupting provisioning mode (for example for network tests/retries) when a user might be busy entering details. Default: `5` (5 minutes). |
+| `retry_connection_timeout_minutes` | integer | Optional | Provisioning mode will exit after this time, to allow other unmanaged (for example wired) or manually configured connections to be tried. Provisioning mode will restart if the connection/online status doesn't change. Default: `10` (10 minutes). |
+| `networks` | array | Optional | Add additional networks the machine can connect to for provisioning. We recommend that you add WiFi settings in the operating system (for example, directly in NetworkManager) rather than in this file, or in the corresponding machine config in the Viam app, if networks aren't needed until after initial provisioning. See [Networks](/manage/reference/viam-agent/#network_configuration). Default: `[]`. |
+| `wifi_power_save` | boolean | Optional | Boolean, which, if set, will explicitly enable or disable power save for all WiFi connections managed by NetworkManager. If not set, the system default applies. Default: `NULL`.  |
+| `device_reboot_after_offline_minutes` | integer | Optional | If set, `viam-agent` will reboot the device after it has been offline (and in hotspot mode) for the specified duration. Default: `0` (disabled). |
 
 {{% /expand%}}
 
@@ -251,10 +251,10 @@ If you know in advance which other networks a machine should be able to connect
 However, if you want to add additional networks to the provisioning configuration you can add them to the `networks` field value.
 
 {{< alert title="Important" color="note" >}}
-You must enable `roaming_mode` in the [`agent-provisioning` configuration](/manage/fleet/provision/setup/#configure-agent-provisioning) of the machine to allow the machine to connect to the specified networks after provisioning.
+You must enable `turn_on_hotspot_if_wifi_has_no_internet` in the [`agent-provisioning` configuration](/manage/fleet/provision/setup/#configure-agent-provisioning) of the machine to allow the machine to connect to the specified networks after provisioning.
 {{< /alert >}}
 
-If `roaming_mode` is enabled, `agent-provisioning` will try to connect to each specified network in order of `priority` from highest to lowest.
+If `turn_on_hotspot_if_wifi_has_no_internet` is enabled, `agent-provisioning` will try to connect to each specified network in order of `priority` from highest to lowest.
 
 <!-- prettier-ignore -->
 | Name       | Type   | Description |
@@ -272,13 +272,13 @@ The following configuration defines the connection information and credentials f
   "model": "C-3PO",
   "fragment_id": "2567c87d-7aef-41bc-b82c-d363f9874663",
   "hotspot_prefix": "skywalker-setup",
-  "disable_dns_redirect": true,
+  "disable_captive_portal_redirect": false,
   "hotspot_password": "skywalker123",
-  "roaming_mode": false,
-  "offline_timeout": "3m30s",
-  "user_timeout": "2m30s",
-  "fallback_timeout": "15m",
-  "roaming_mode": true,
+  "turn_on_hotspot_if_wifi_has_no_internet": false,
+  "offline_before_starting_hotspot_minutes": "3m30s",
+  "user_idle_minutes": "2m30s",
+  "retry_connection_timeout_minutes": "15m",
+  "turn_on_hotspot_if_wifi_has_no_internet": true,
   "networks": [
     {
       "type": "wifi",
@@ -449,9 +449,9 @@ sudo ./preinstall.sh /path/to/rootfs
 
 ### Device not detecting networks
 
-Some systems can't scan for WiFi networks while in hotspot mode, meaning they won't automatically detect networks coming online or into range until the `fallback_timeout` expires.
-The `fallback_timeout` causes your device to exit hotspot mode, at which point your device will be able to detect newly available networks.
-If your device does not connect to your network, adjust the `fallback_timeout` value in the [`agent-provisioning` configuration](/manage/fleet/provision/setup/#configure-agent-provisioning).
+Some systems can't scan for WiFi networks while in hotspot mode, meaning they won't automatically detect networks coming online or into range until the `retry_connection_timeout_minutes` expires.
+The `retry_connection_timeout_minutes` causes your device to exit hotspot mode, at which point your device will be able to detect newly available networks.
+If your device does not connect to your network, adjust the `retry_connection_timeout_minutes` value in the [`agent-provisioning` configuration](/manage/fleet/provision/setup/#configure-agent-provisioning).
 
 ### Test GRPC components of the provisioning service
 
@@ -496,7 +496,7 @@ For a guide you can give to end users for setting up their machine, see [Setup m
 
    - `agent-provisioning` will use the provided network if it can connect, even if that network does not have internet access.
      Note that any features that require internet access will not function if the connected WiFi network is not connected to the internet.
-     If you want `agent-provisioning` to require that a WiFi network be connected to the internet in order to connect to it, enable roaming mode.
+     If you want `agent-provisioning` to require that a WiFi network be connected to the internet in order to connect to it, enable `turn_on_hotspot_if_wifi_has_no_internet`.
 
 1. `viam-agent` then starts `viam-server` with the provided configuration and the machine becomes **live**.
 
@@ -536,7 +536,7 @@ For a guide you can give to end users for setting up their machine, see [Setup m
 
    - `agent-provisioning` will use the provided network if it can connect, even if that network does not have internet access.
      Note that any features that require internet access will not function if the connected WiFi network is not connected to the internet.
-     If you want `agent-provisioning` to require that a WiFi network be connected to the internet in order to connect to it, enable roaming mode.
+     If you want `agent-provisioning` to require that a WiFi network be connected to the internet in order to connect to it, enable `turn_on_hotspot_if_wifi_has_no_internet`.
 
 1. `viam-agent` then starts `viam-server` with the provided configuration and the machine becomes **live**.