Skip to content

Commit b3c71ac

Browse files
authored
DOCS-3993: Add unlisted module config instructions (#4314)
1 parent 011c7f2 commit b3c71ac

File tree

1 file changed

+71
-4
lines changed

1 file changed

+71
-4
lines changed

docs/operate/reference/module-configuration.md

Lines changed: 71 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ description: "Configure module versions and module environment variables."
1313
This page contains reference material.
1414
For quick instructions on configuring a module on your machine, see [Configure hardware on your machine](/operate/get-started/supported-hardware/#configure-hardware-on-your-machine).
1515

16-
### Modular resource configuration details
16+
## Modular resource configuration details
1717

1818
The modular resource card allows you to configure attributes for the resource.
1919

@@ -79,7 +79,7 @@ The following properties are available for modular resources:
7979
| `model` | string | **Required** | The full {{< glossary_tooltip term_id="model-namespace-triplet" text="model namespace triplet">}} of the modular resource's {{< glossary_tooltip term_id="model" text="model" >}}. |
8080
| `depends_on` | array | Optional | The `name` of components you want to confirm are available on your machine alongside your modular resource. Often a [board](/operate/reference/components/board/). Unnecessary if you coded [implicit dependencies](/operate/get-started/other-hardware/dependencies/). |
8181

82-
### Module configuration details
82+
## Module configuration details
8383

8484
{{< tabs >}}
8585
{{% tab name="Config Builder" %}}
@@ -196,7 +196,7 @@ You can add and edit `env` by switching from **Builder** to **JSON** mode in the
196196
| `name` | string | **Required** | A name for this instance of the module. |
197197
| `env` | object | Optional | Environment variables available to the module. For example `{ "API_KEY": "${environment.API_KEY}" }`. Some modules require that you set environment variables as part of configuration. Check the module's readme for more information. See [environment variables](#environment-variables). |
198198

199-
#### Module versioning
199+
### Module versioning
200200

201201
You can configure how each module on your machine updates itself when a newer version becomes available from the Viam Registry.
202202
By default, a newly-added module is set to pin to the latest release (**Latest**) of the version you added.
@@ -227,7 +227,7 @@ For any version type other than **Patch (X.Y.Z)**, the module will upgrade as so
227227
If, for example, the module provides a motor component, and the motor is running, it will stop while the module upgrades.
228228
{{% /alert %}}
229229

230-
#### Environment variables
230+
### Environment variables
231231

232232
Each module has access to the following default environment variables.
233233
Not all of these variables are automatically available on [local modules](/operate/get-started/other-hardware/#test-your-module-locally); you can manually set variables your module requires if necessary.
@@ -291,3 +291,70 @@ To set the path to a program or library on a machine, you can set a system varia
291291
```
292292

293293
{{% /expand%}}
294+
295+
## Configure an unlisted module
296+
297+
To configure a module that is uploaded to the Viam Registry but has [visibility](/operate/get-started/other-hardware/manage-modules/#change-module-visibility) set to **Unlisted**, you need to manually add the module to your configuration:
298+
299+
1. Navigate to the module's page in the Viam Registry, using the link to the module.
300+
301+
1. Find the **Unlisted module usage** section.
302+
303+
1. Copy the module configuration JSON snippet.
304+
305+
1. In the Viam app, navigate to the **CONFIGURE** tab of the machine you want to configure.
306+
307+
1. Switch to **JSON** mode.
308+
309+
1. Paste the copied module configuration into your `modules` array.
310+
311+
1. Copy the model configuration snippet for the model you want to use, and add it to your `components` or `services` array (as appropriate).
312+
For example:
313+
314+
{{< tabs >}}
315+
{{% tab name="Example" %}}
316+
317+
```json {class="line-numbers linkable-line-numbers"}
318+
"components": [
319+
{
320+
"name": "sensor-1",
321+
"api": "rdk:component:sensor",
322+
"model": "jessamy:hello-world:hello-camera",
323+
"attributes": {}
324+
},
325+
...
326+
],
327+
"modules": [
328+
{
329+
"type": "registry",
330+
"name": "jessamyhello-world",
331+
"module_id": "jessamy:hello-world",
332+
"version": "latest"
333+
}
334+
]
335+
```
336+
337+
{{% /tab %}}
338+
{{% tab name="Template" %}}
339+
340+
```json {class="line-numbers linkable-line-numbers"}
341+
"<components|services>": [
342+
{
343+
"name": "<resource-name>",
344+
"api": "<model-API-namespace>:<component|service>:<model-name>",
345+
"model": "<module-namespace>:<module-name>:<model-name>",
346+
"attributes": {}
347+
}
348+
],
349+
"modules": [
350+
{
351+
"type": "registry",
352+
"name": "<module-namespace><module-name>",
353+
"module_id": "<module-namespace>:<module-name>",
354+
"version": "latest"
355+
}
356+
]
357+
```
358+
359+
{{% /tab %}}
360+
{{< /tabs >}}

0 commit comments

Comments
 (0)