Skip to content

Commit 6ee8493

Browse files
npentrelnpentrel
committed
Updates
1 parent a32f026 commit 6ee8493

File tree

2 files changed

+145
-150
lines changed

2 files changed

+145
-150
lines changed

‎docs/manage/fleet/provision/setup.md

Lines changed: 108 additions & 149 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,10 @@ To parse the readings and provide tailored guidance to a ship's captain, the com
3434
By having the end customer set up the machine, the company:
3535

3636
- eliminates per-device setup and individualization at the factory
37-
- allows for tailored configurations per customer as needed
3837
- allows customer to provide their own WiFi credentials
38+
- allows for tailored configurations per customer as needed
3939

40-
This guide will show you how to install and configure `viam-agent`.
40+
This guide shows you how to install and configure `viam-agent`.
4141

4242
## Prerequisites
4343

@@ -62,49 +62,10 @@ For Bullseye, the installation of `viam-agent` changes the network configuration
6262

6363
## Choose provisioning methods
6464

65-
`viam-agent` supports two provisioning methods that can work independently or together:
66-
67-
- **WiFi Hotspot Provisioning**: Creates a WiFi hotspot that users connect to for setup via a captive web portal
68-
- **Bluetooth Provisioning**: Uses Bluetooth Low Energy (BLE) for setup via mobile apps
69-
70-
You can enable both methods simultaneously for maximum flexibility, or disable one method if it's not suitable for your environment.
71-
72-
### WiFi Hotspot Provisioning
73-
74-
WiFi hotspot provisioning creates a temporary WiFi network that users connect to for machine setup. This method works well with both captive web portals and mobile apps.
75-
76-
**Advantages:**
77-
- Works with any WiFi-enabled device
78-
- Supports both web portal and mobile app interfaces
79-
- Well-established and widely compatible
80-
81-
**Considerations:**
82-
- Requires creating an open WiFi hotspot
83-
- May be less reliable in environments with many WiFi networks
84-
- Some corporate environments may block hotspot connections
85-
86-
### Bluetooth Provisioning
87-
88-
Bluetooth provisioning uses Bluetooth Low Energy (BLE) for machine setup, allowing mobile devices to connect directly to the machine without joining a WiFi network.
89-
90-
**Advantages:**
91-
- More reliable in environments with many WiFi networks
92-
- No need for an open WiFi hotspot
93-
- Often easier for end-users on mobile devices
94-
- Uses encrypted communication for security
95-
96-
**Considerations:**
97-
- Requires Bluetooth Low Energy support on both device and mobile app
98-
- Currently optimized for mobile app workflows
99-
- Requires compatible mobile device with BLE support
100-
101-
{{< alert title="Note" color="note" >}}
102-
Bluetooth provisioning is designed primarily for mobile app workflows. While both provisioning methods can be enabled simultaneously, mobile apps will typically prefer Bluetooth when available.
103-
{{< /alert >}}
65+
You can let your end users complete machine setup over WiFi or Bluetooth:
10466

105-
## Decide on the user interface
106-
107-
You can choose to let your end users complete machine setup by using a captive web portal or a mobile app.
67+
- **WiFi Hotspot Provisioning**: When device boots, it creates a temporary WiFi hotspot that users connect to for setup either by using a captive web portal or a mobile app. Be aware that the WiFi hotspot is open to anyone.
68+
- **Bluetooth Low Energy (BLE) Provisioning**: When device boots, it searches for Bluetooth connections and a user connects to it using a mobile app.
10869

10970
If you choose to have a mobile app experience, you can use the [Viam mobile app](/manage/troubleshoot/teleoperate/default-interface/#viam-mobile-app) or create your own custom mobile app using the [Flutter SDK](https://flutter.viam.dev/viam_protos.provisioning.provisioning/ProvisioningServiceClient-class.html) or the [TypeScript SDK](https://github.com/viamrobotics/viam-typescript-sdk/blob/main/src/app/provisioning-client.ts) to connect to `viam-agent` and provision your machines.
11071

@@ -116,100 +77,10 @@ If you do not yet have a fragment, follow the steps to [Create a configuration f
11677
If you are not using Flutter or TypeScript and would like to use provisioning, please [contact us](mailto:[email protected]).
11778
{{< /alert >}}
11879

119-
If you choose to use the captive web portal, you can optionally create a machine in advance and provide its machine cloud credentials file at <FILE>/etc/viam.json</FILE>.
120-
121-
You can get the machine cloud credentials by clicking the copy icon next to **Machine cloud credentials** in the part status dropdown to the right of your machine's name on the top of the page.
122-
123-
{{<imgproc src="configure/machine-part-info.png" resize="500x" declaredimensions=true alt="Machine part info dropdown" class="shadow" >}}
124-
125-
{{% expand "Want to create a machine and obtain its machine cloud credentials programmatically?" %}}
126-
127-
You can use the [Fleet Management API](/dev/reference/apis/fleet/) to create machines, and obtain their machine cloud credentials:
128-
129-
```python {class="line-numbers linkable-line-numbers"}
130-
import asyncio
131-
import requests
132-
133-
from viam.rpc.dial import DialOptions, Credentials
134-
from viam.app.viam_client import ViamClient
135-
from viam.app.app_client import APIKeyAuthorization
136-
137-
# Replace "<API-KEY>" (including brackets) with your API key
138-
API_KEY = "<API-KEY>"
139-
# Replace "<API-KEY-ID>" (including brackets) with your API key ID
140-
API_KEY_ID = "<API-KEY-ID>"
141-
# The id of the location to create the machine in
142-
LOCATION_ID = ""
143-
# The name for the machine to create
144-
MACHINE_NAME = ""
145-
146-
147-
async def connect() -> ViamClient:
148-
dial_options = DialOptions(
149-
credentials=Credentials(
150-
type="api-key",
151-
payload=API_KEY,
152-
),
153-
auth_entity=API_KEY_ID
154-
)
155-
return await ViamClient.create_from_dial_options(dial_options)
156-
157-
158-
async def main():
159-
160-
# Make a ViamClient
161-
viam_client = await connect()
162-
# Instantiate an AppClient called "cloud"
163-
# to run fleet management API methods on
164-
cloud = viam_client.app_client
165-
new_machine_id = await cloud.new_robot(
166-
name=MACHINE_NAME, location_id=LOCATION_ID)
167-
print("Machine created: " + new_machine_id)
168-
list_of_parts = await cloud.get_robot_parts(
169-
robot_id=new_machine_id)
170-
print("Part id: " + list_of_parts[0].id)
171-
172-
org_list = await cloud.list_organizations()
173-
print(org_list[0].id)
174-
175-
auth = APIKeyAuthorization(
176-
role="owner",
177-
resource_type="robot",
178-
resource_id=new_machine_id
179-
)
180-
api_key, api_key_id = await cloud.create_key(
181-
org_list[0].id, [auth], "test_provisioning_key")
182-
print(api_key, api_key_id)
183-
184-
headers = {
185-
'key_id': api_key_id,
186-
'key': api_key
187-
}
188-
params = {
189-
"client": 'true',
190-
"id": list_of_parts[0].id
191-
}
192-
res = requests.get(
193-
'https://app.viam.com/api/json1/config',
194-
params=params,
195-
headers=headers,
196-
timeout=10
197-
)
198-
print(res.text)
199-
200-
with open("viam.json", "w") as text_file:
201-
text_file.write(res.text)
202-
203-
viam_client.close()
204-
205-
if __name__ == '__main__':
206-
asyncio.run(main())
207-
```
208-
209-
{{% /expand%}}
210-
21180
## Configure defaults
21281

82+
The defaults file allows you to configure the provisioning experience for the users setting up their machines.
83+
21384
{{< table >}}
21485

21586
{{% tablestep number=1 %}}
@@ -356,6 +227,100 @@ The following configuration defines the connection information and credentials f
356227
{{% /tablestep %}}
357228
{{< /table >}}
358229

230+
## (Optional) Create a machine in advance
231+
232+
If you provision devices using a captive web portal, you can optionally create a machine in advance and provide its machine cloud credentials file at <FILE>/etc/viam.json</FILE>.
233+
234+
You can get the machine cloud credentials by clicking the copy icon next to **Machine cloud credentials** in the part status dropdown to the right of your machine's name on the top of the page.
235+
236+
{{<imgproc src="configure/machine-part-info.png" resize="500x" declaredimensions=true alt="Machine part info dropdown" class="shadow" >}}
237+
238+
{{% expand "Want to create a machine and obtain its machine cloud credentials programmatically?" %}}
239+
240+
You can use the [Fleet Management API](/dev/reference/apis/fleet/) to create machines, and obtain their machine cloud credentials:
241+
242+
```python {class="line-numbers linkable-line-numbers"}
243+
import asyncio
244+
import requests
245+
246+
from viam.rpc.dial import DialOptions, Credentials
247+
from viam.app.viam_client import ViamClient
248+
from viam.app.app_client import APIKeyAuthorization
249+
250+
# Replace "<API-KEY>" (including brackets) with your API key
251+
API_KEY = "<API-KEY>"
252+
# Replace "<API-KEY-ID>" (including brackets) with your API key ID
253+
API_KEY_ID = "<API-KEY-ID>"
254+
# The id of the location to create the machine in
255+
LOCATION_ID = ""
256+
# The name for the machine to create
257+
MACHINE_NAME = ""
258+
259+
260+
async def connect() -> ViamClient:
261+
dial_options = DialOptions(
262+
credentials=Credentials(
263+
type="api-key",
264+
payload=API_KEY,
265+
),
266+
auth_entity=API_KEY_ID
267+
)
268+
return await ViamClient.create_from_dial_options(dial_options)
269+
270+
271+
async def main():
272+
273+
# Make a ViamClient
274+
viam_client = await connect()
275+
# Instantiate an AppClient called "cloud"
276+
# to run fleet management API methods on
277+
cloud = viam_client.app_client
278+
new_machine_id = await cloud.new_robot(
279+
name=MACHINE_NAME, location_id=LOCATION_ID)
280+
print("Machine created: " + new_machine_id)
281+
list_of_parts = await cloud.get_robot_parts(
282+
robot_id=new_machine_id)
283+
print("Part id: " + list_of_parts[0].id)
284+
285+
org_list = await cloud.list_organizations()
286+
print(org_list[0].id)
287+
288+
auth = APIKeyAuthorization(
289+
role="owner",
290+
resource_type="robot",
291+
resource_id=new_machine_id
292+
)
293+
api_key, api_key_id = await cloud.create_key(
294+
org_list[0].id, [auth], "test_provisioning_key")
295+
print(api_key, api_key_id)
296+
297+
headers = {
298+
'key_id': api_key_id,
299+
'key': api_key
300+
}
301+
params = {
302+
"client": 'true',
303+
"id": list_of_parts[0].id
304+
}
305+
res = requests.get(
306+
'https://app.viam.com/api/json1/config',
307+
params=params,
308+
headers=headers,
309+
timeout=10
310+
)
311+
print(res.text)
312+
313+
with open("viam.json", "w") as text_file:
314+
text_file.write(res.text)
315+
316+
viam_client.close()
317+
318+
if __name__ == '__main__':
319+
asyncio.run(main())
320+
```
321+
322+
{{% /expand%}}
323+
359324
## Install `viam-agent`
360325

361326
`viam-agent` is a self-updating service manager that maintains the lifecycle for several Viam services and keeps them updated.
@@ -522,16 +487,23 @@ Some systems can't scan for WiFi networks while in hotspot mode, meaning they wo
522487
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.
523488
If your device does not connect to your network, adjust the `retry_connection_timeout_minutes` value in the [`defaults` file](/manage/fleet/provision/setup/#configure-defaults).
524489

490+
### WiFi provisioning not working
491+
492+
WiFi provisioning may be less reliable in environments with many WiFi networks.
493+
If possible, use Bluetooth provisioning or move to an area with fewer WiFi networks in range.
494+
525495
### Bluetooth provisioning not working
526496

527497
If Bluetooth provisioning is not working, check the following:
528498

529499
1. **Bluetooth adapter availability**: Ensure your device has a working Bluetooth adapter. You can check this with:
500+
530501
```sh {class="command-line" data-prompt="$"}
531502
bluetoothctl list
532503
```
533504

534505
1. **Bluetooth service status**: Verify the Bluetooth service is running:
506+
535507
```sh {class="command-line" data-prompt="$"}
536508
sudo systemctl status bluetooth
537509
```
@@ -547,19 +519,6 @@ If Bluetooth provisioning is not working, check the following:
547519
If you need to test the GRPC components of the provisioning service, there is a CLI client available.
548520
Get the code from the [`agent` repo](https://github.com/viamrobotics/agent/tree/main/cmd/provisioning-client) and run `go run ./cmd/provisioning-client/` for info.
549521

550-
The provisioning client supports both WiFi hotspot and Bluetooth modes:
551-
552-
```sh {class="command-line" data-prompt="$"}
553-
# Test WiFi hotspot provisioning
554-
go run ./cmd/provisioning-client/ --address localhost:4772 --status
555-
556-
# Test Bluetooth provisioning
557-
go run ./cmd/provisioning-client/ --bluetooth --status
558-
559-
# Scan for Bluetooth devices
560-
go run ./cmd/provisioning-client/ --scan
561-
```
562-
563522
## End user setup experience
564523

565524
End users receive a machine, and use either a captive web portal or mobile app to complete the machine setup.

‎docs/manage/reference/viam-agent/_index.md

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,10 @@ For information on managing the service, see [Manage `viam-agent`](/manage/refer
102102
"viam_server_start_timeout_minutes": 10,
103103
"disable_viam_server": false,
104104
"disable_network_configuration": false,
105-
"disable_system_configuration": false
105+
"disable_system_configuration": false,
106+
"viam_server_env": {
107+
"CUSTOM_VAR": "value"
108+
}
106109
},
107110
"network_configuration": {
108111
"manufacturer": "viam",
@@ -205,9 +208,42 @@ To update the version of `viam-server` (or the RDK) update the machine settings.
205208
| `disable_network_configuration` | boolean | Optional | Disables the network and hotspot configuration, as well as the configuration of additional networks. Default: `false`. |
206209
| `disable_system_configuration` | boolean | Optional | Disables the system configuration. Default: `false`. |
207210
| `disable_viam_server` | boolean | Optional | Disable `viam-server` remotely. This option is often used by developers working on Viam agent or when manually running `viam-server`. Default: `false`. |
211+
| `viam_server_env` | object | Optional | A map of environment variable names to values that `viam-agent` passes to `viam-server` and its child processes (including modules). Both keys and values must be strings. See [Environment Variables for viam-server](#environment-variables-for-viam-server). Default: `{}` (empty). |
208212
| `viam_server_start_timeout_minutes` | integer | Optional | Specify a time after which, if `viam-server` hasn't successfully started, Viam agent will kill it and restart. Default: `10`. |
209213
| `wait_for_update_check` | boolean | Optional | If set to `true`, `viam-agent` will wait for a network connection and check for updates before starting `viam-server`. See [Reduce startup time](#reduce-startup-time). Default: `false`. |
210214

215+
### Environment Variables for viam-server
216+
217+
You can configure environment variables for `viam-server` using the `viam_server_env` setting in `advanced_settings`.
218+
Environment variables set through `viam_server_env` are passed to `viam-server` and all child processes it launches, including modules.
219+
`viam-server` also inherits existing environment variables from `viam-agent`, such as `HOME`, `PWD`, `TERM`, `PATH`.
220+
221+
{{< alert title="Important" color="note" >}}
222+
When you change environment variables in `viam_server_env`, `viam-agent` will automatically restart `viam-server` to apply these and any other changes made before saving.
223+
This restart will occur immediately if `viam-server` is in a maintenance window and not currently processing configuration changes.
224+
{{< /alert >}}
225+
226+
Changes to `viam_server_env` are the only changes that automatically trigger a `viam-server` restart. Changing other configuration options requires a manual restart unless you've also changed `viam_server_env`.
227+
228+
#### Example configurations
229+
230+
```json
231+
{
232+
"agent": {
233+
"advanced_settings": {
234+
"viam_server_env": {
235+
"PION_LOG_TRACE": "all", # Debug logging for WebRTC
236+
"HTTPS_PROXY": "socks5://proxy.example.com:1080", # SOCKS proxy
237+
"HTTP_PROXY": "socks5://proxy.example.com:1080",
238+
"CUSTOM_VAR": "value"
239+
}
240+
}
241+
}
242+
}
243+
```
244+
245+
To remove an environment variable, remove it from the `viam_server_env` object and save your configuration.
246+
211247
### Reduce startup time
212248

213249
You can set `wait_for_update_check` to `false` to bypass `viam-agent` waiting for a network connection to be established and checking for updates during initial startup.

0 commit comments

Comments
 (0)