|
1 | 1 | # Viam Agent
|
2 | 2 | A self-updating service manager that maintains the lifecycle for viam-server (as built from RDK) and other Viam provided system services.
|
3 | 3 |
|
4 |
| -## Requirements |
5 |
| -Currently, viam-agent is only supported on Linux, for amd64 (x86_64) and arm64 (aarch64) CPUs. |
6 |
| - |
7 |
| -## Installation |
8 |
| -Your system will need to have `curl` available. |
9 |
| - |
10 |
| -### Automatic |
11 |
| -The smart machine config `/etc/viam.json` can be installed automatically if you have an API key and part ID available. Modify the following command by inserting your actual details. (Be sure to remove the surrounding < > characters of the placeholders.) |
12 |
| -``` |
13 |
| -sudo /bin/sh -c "VIAM_API_KEY_ID=<KEYID> VIAM_API_KEY=<KEY> VIAM_PART_ID=<PARTID>; $(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" |
14 |
| -``` |
15 |
| -### Manual configuration |
16 |
| -Make sure you've already installed your robot's configuration file to `/etc/viam.json` then run the following: |
17 |
| -``` |
18 |
| -sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/install.sh)" |
19 |
| -``` |
20 |
| - |
21 |
| -## Provisioning and Networking |
22 |
| -The current version of viam-agent includes a device provisioning subsystem that can help set up wifi and smart machine configs. For more info, see the [Provisioning Subsystem](https://github.com/viamrobotics/agent-provisioning) |
23 |
| - |
24 |
| -## Management |
25 |
| -Viam Agent will install itself as a systemd service named `viam-agent`. Start/stop/restart it with `systemctl` |
26 |
| -Ex: `sudo systemctl restart viam-agent` |
27 |
| - |
28 |
| -### Notes |
29 |
| -The agent will automatically update both itself and viam-server. However, it is up to the user to restart the service to use the new version. |
30 |
| -For the agent itself restart the service (per the management command above) or reboot. Note this will restart viam-server as well. |
31 |
| -viam-server may be restarted via the normal "restart" button in the cloud App, or as part of the full agent restart per above. |
32 |
| - |
33 |
| -### Uninstall |
34 |
| -To remove the agent and all viam configuration completely, run the following script. |
35 |
| -``` |
36 |
| -sudo /bin/sh -c "$(curl -fsSL https://storage.googleapis.com/packages.viam.com/apps/viam-agent/uninstall.sh)" |
37 |
| -``` |
38 |
| - |
39 |
| -## Configuration |
40 |
| -Configuration is maintained via the "agent" section of the device's config in the viam App. Below is an example config section: |
41 |
| -``` |
42 |
| -{ |
43 |
| - "agent": { |
44 |
| - "viam-agent": { |
45 |
| - "release_channel": "stable", |
46 |
| - "pin_version": "1.2.3", |
47 |
| - "pin_url": "http://example/test.binary", |
48 |
| - "disable_subsystem": false |
49 |
| - }, |
50 |
| - "viam-server": { |
51 |
| - "attributes": { |
52 |
| - "fast_start": true |
53 |
| - } |
54 |
| - }, |
55 |
| - "agent-provisioning": { |
56 |
| - "release_channel": "stable" |
57 |
| - }, |
58 |
| - "agent-syscfg": { |
59 |
| - "release_channel": "stable" |
60 |
| - } |
61 |
| - } |
62 |
| -} |
63 |
| -``` |
64 |
| -Above there are (currently) four subsystems, `viam-agent` (the main agent program itself), `viam-server` (the core of the robot/device), `agent-provisioning` (provides early setup and network management. [Provisioning Details](https://github.com/viamrobotics/agent-provisioning) ), and `agent-syscfg` (provides various OS/system configuration tweaks [Syscfg Details](https://github.com/viamrobotics/agent-syscfg)) |
65 |
| - |
66 |
| -Each section primarily controls updates for that subsystem, using one of three settings, `pin_url` (highest priority), `pin_version` (checked/used only if pin_url is unset or empty), and `release_channel` (used by default, and defaults to stable, but only if `pin_url` and `pin_version` are both unset.) The example above gives all three for visual clarity, but is not actually needed. In this case, only `pin_url` would be used. |
67 |
| - |
68 |
| -For release channel, "stable" generally means semantically versioned releases that are tested before release, and are relatively infrequent, but will automatically upgrade when a new version is released. Using `pin_version` allows one to "lock" the subsystem to an explcit version (as provided by the release channel) no automatic upgrades will be performed until the setting is updated to a new version (or removed to revert to the release channel.) Lastly, `pin_url` can be used to point to a specific binary. Typically this is only used for testing/troubleshooting. |
69 |
| - |
70 |
| -The `disable_subsystem` setting can be set to true if you don't wish to use/start a particular subsystem. |
71 |
| - |
72 |
| -Note that only sections/settings you explicitly want to modify need to be included in the config. By default, all subsystems will use the `stable` release channel, so no configuration at all is needed to get that behavior. E.g. in the example above, viam-server will still get stable releases, as none of the update-related values are being modified, but it will ALSO use the fast_start behavior detailed below. For another example, the `agent-provisioning` or `agent-syscfg` sections could be left out entirely, and the device will use a default config for those subsystems anyway. To actually disable one, the section can be added, and `disable_subsystem` to to `true` |
73 |
| - |
74 |
| - |
75 |
| -## FastStart Mode |
76 |
| -This bypasses the normal network/online wait and update checks during inital startup, and executes viam-server as quickly as possible. Useful if you have a device that often starts when offline or on a slow connection, and having the latest version immediately after start isn't required. Note that normal, periodic update checks will continue to run afterwards. This only affects initial startup sequencing. |
77 |
| - |
78 |
| -To use it, set `"fast_start": true` in the attributes for the viam-server subsystem. Alternately, set `VIAM_AGENT_FAST_START=1` in your environment. |
| 4 | +For more information, see the [Viam Agent documentation](https://docs.viam.com/configure/agent/). |
79 | 5 |
|
80 | 6 | ## Development
|
81 | 7 |
|
|
0 commit comments