From 20f83004f06eebbda82555cb8e7b1e9932dfc01c Mon Sep 17 00:00:00 2001 From: Jeremy Rose Date: Fri, 23 Oct 2026 17:13:12 -0400 Subject: [PATCH 1/2] Document machine-wide resource name uniqueness (DOCS-4939) Co-Authored-By: Claude Sonnet 5.5 --- docs/hardware/configure-hardware.md | 8 +++++++- docs/hardware/machine-configuration.md | 2 +- docs/hardware/multi-machine/add-a-remote-part.md | 5 ++++- docs/hardware/multi-machine/overview.md | 2 +- docs/monitor/troubleshoot.md | 2 ++ 5 files changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/hardware/configure-hardware.md b/docs/hardware/configure-hardware.md index 5b78d1a9dd..4d38127622 100644 --- a/docs/hardware/configure-hardware.md +++ b/docs/hardware/configure-hardware.md @@ -111,7 +111,13 @@ If it shows as offline, verify that `viam-server` is running on your machine. motor", "xArm6"). The search covers all available models and fragments. 4. Give your component a **name** and click **Add to machine**. The name is how you reference it in code and configuration, so keep it short, - descriptive, and unique on this machine. + descriptive, and unique on this machine. See [Resource names](#resource-names). + +#### Resource names + +Every component and service on a machine needs a name that is unique across the whole machine, even when two resources use different APIs. For example, you can't name both a camera and a sensor `billing`. This includes resources from [remote parts](/hardware/multi-machine/add-a-remote-part/) and fragments. The name `builtin` is reserved for the default services. + +If names collide, `viam-server` logs an error and doesn't build the conflicting local resources. Anything that depends on them is also unavailable until you rename one. If a local resource collides with a remote one, the local resource wins and the remote resource is hidden. To avoid collisions with remote resources, [set a prefix](/hardware/multi-machine/add-a-remote-part/#3-optional-set-a-prefix) on the remote. ### 3. Configure attributes diff --git a/docs/hardware/machine-configuration.md b/docs/hardware/machine-configuration.md index e40dff08a5..c24fc94a18 100644 --- a/docs/hardware/machine-configuration.md +++ b/docs/hardware/machine-configuration.md @@ -26,7 +26,7 @@ fields: | Field | What it does | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `name` | A unique name for this component on this machine. Your code references the component by this name. | +| `name` | A name for this component, unique across the machine ([details](/hardware/configure-hardware/#resource-names)). Your code references the component by this name. | | `api` | The component type, in the form `rdk:component:` (for example, `rdk:component:arm`). | | `model` | The specific implementation, in the form `namespace:family:name` (for example, `viam:ufactory:xArm6`). Built-in models use `rdk:builtin:name` (for example, `rdk:builtin:gpio`). | | `attributes` | Model-specific settings that control how to connect to the hardware and how it should behave. | diff --git a/docs/hardware/multi-machine/add-a-remote-part.md b/docs/hardware/multi-machine/add-a-remote-part.md index d6a2ec87ba..8023b7ad95 100644 --- a/docs/hardware/multi-machine/add-a-remote-part.md +++ b/docs/hardware/multi-machine/add-a-remote-part.md @@ -62,8 +62,11 @@ The remote part is now part of your machine's configuration. ## 3. Optional: set a prefix -If you connect multiple remotes and some export components with the same names, add a `prefix` to the remote config. +Resource names must be unique across the whole machine, including resources from remotes. +If a remote exports a resource with the same name as a local resource or another remote's resource, `viam-server` hides the remote resource (a local resource wins its name). +Add a `prefix` to the remote config to prevent this. The prefix is prepended to every resource name coming from that remote. +See [Resource names](/hardware/configure-hardware/#resource-names). Prefixes are concatenated directly, with no separator. To keep names readable, end your prefix with `-` or `_`: diff --git a/docs/hardware/multi-machine/overview.md b/docs/hardware/multi-machine/overview.md index 653d4198fb..4b3616a4d1 100644 --- a/docs/hardware/multi-machine/overview.md +++ b/docs/hardware/multi-machine/overview.md @@ -85,7 +85,7 @@ If you configured a prefix on the remote, it is prepended to every remote resour gripper = Gripper.from_robot(machine, "end-effectorgripper") ``` -When two connected parts export resources with the same name, a prefix disambiguates them. +Resource names must be unique across the whole machine. When a remote exports a resource with the same name as a local one, or as another remote's, `viam-server` hides the remote resource unless a prefix disambiguates them. See [Resource names](/hardware/configure-hardware/#resource-names). ## What happens on disconnect diff --git a/docs/monitor/troubleshoot.md b/docs/monitor/troubleshoot.md index 1f354c6ab6..dd6eb8d8de 100644 --- a/docs/monitor/troubleshoot.md +++ b/docs/monitor/troubleshoot.md @@ -131,6 +131,8 @@ You can filter logs by: The default log level is `Info`. If you are not seeing helpful logs, enable debug logging. +If a resource you configured is missing or unavailable, search the logs for `name collision`. Two resources sharing a name can stop both from building. See [Resource names](/hardware/configure-hardware/#resource-names). + #### Enable debug logging **For all resources on the machine**, add `"debug": true` to the JSON configuration: From 517a0cb4fc8a141dc444a870ab5e18fa0d93437c Mon Sep 17 00:00:00 2001 From: Jeremy Rose Date: Mon, 26 Oct 2026 10:38:12 -0400 Subject: [PATCH 2/2] Address review: both remotes hidden, v1.6.0 note, search Resource name Co-Authored-By: Claude Sonnet 5.5 --- docs/hardware/configure-hardware.md | 4 ++-- docs/hardware/multi-machine/add-a-remote-part.md | 2 +- docs/hardware/multi-machine/overview.md | 2 +- docs/monitor/troubleshoot.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/hardware/configure-hardware.md b/docs/hardware/configure-hardware.md index 4d38127622..f2982e6488 100644 --- a/docs/hardware/configure-hardware.md +++ b/docs/hardware/configure-hardware.md @@ -115,9 +115,9 @@ If it shows as offline, verify that `viam-server` is running on your machine. #### Resource names -Every component and service on a machine needs a name that is unique across the whole machine, even when two resources use different APIs. For example, you can't name both a camera and a sensor `billing`. This includes resources from [remote parts](/hardware/multi-machine/add-a-remote-part/) and fragments. The name `builtin` is reserved for the default services. +Starting with `viam-server` v1.6.0, every component and service on a machine needs a name that is unique across the whole machine, even when two resources use different APIs. For example, you can't name both a camera and a sensor `billing`. This includes resources from [remote parts](/hardware/multi-machine/add-a-remote-part/) and fragments. The name `builtin` is reserved for the default services. -If names collide, `viam-server` logs an error and doesn't build the conflicting local resources. Anything that depends on them is also unavailable until you rename one. If a local resource collides with a remote one, the local resource wins and the remote resource is hidden. To avoid collisions with remote resources, [set a prefix](/hardware/multi-machine/add-a-remote-part/#3-optional-set-a-prefix) on the remote. +If names collide, `viam-server` logs an error and doesn't build the conflicting local resources. Anything that depends on them is also unavailable until you rename one. If a remote resource has the same name as a local resource, the local resource wins and the remote one is hidden from the machine's resource list. If two remotes export the same name, both are hidden. To avoid collisions with remote resources, [set a prefix](/hardware/multi-machine/add-a-remote-part/#3-optional-set-a-prefix) on the remote. ### 3. Configure attributes diff --git a/docs/hardware/multi-machine/add-a-remote-part.md b/docs/hardware/multi-machine/add-a-remote-part.md index 8023b7ad95..126cb8fcc4 100644 --- a/docs/hardware/multi-machine/add-a-remote-part.md +++ b/docs/hardware/multi-machine/add-a-remote-part.md @@ -63,7 +63,7 @@ The remote part is now part of your machine's configuration. ## 3. Optional: set a prefix Resource names must be unique across the whole machine, including resources from remotes. -If a remote exports a resource with the same name as a local resource or another remote's resource, `viam-server` hides the remote resource (a local resource wins its name). +If a remote resource has the same name as a local resource, the local one wins and the remote one is hidden. If two remotes export the same name, both are hidden. Add a `prefix` to the remote config to prevent this. The prefix is prepended to every resource name coming from that remote. See [Resource names](/hardware/configure-hardware/#resource-names). diff --git a/docs/hardware/multi-machine/overview.md b/docs/hardware/multi-machine/overview.md index 4b3616a4d1..b193cde726 100644 --- a/docs/hardware/multi-machine/overview.md +++ b/docs/hardware/multi-machine/overview.md @@ -85,7 +85,7 @@ If you configured a prefix on the remote, it is prepended to every remote resour gripper = Gripper.from_robot(machine, "end-effectorgripper") ``` -Resource names must be unique across the whole machine. When a remote exports a resource with the same name as a local one, or as another remote's, `viam-server` hides the remote resource unless a prefix disambiguates them. See [Resource names](/hardware/configure-hardware/#resource-names). +Resource names must be unique across the whole machine. When a remote resource has the same name as a local one, the local resource wins and the remote one is hidden. When two remotes export the same name, both are hidden. A prefix prevents this. See [Resource names](/hardware/configure-hardware/#resource-names). ## What happens on disconnect diff --git a/docs/monitor/troubleshoot.md b/docs/monitor/troubleshoot.md index 134b17cfb4..a239aa88d4 100644 --- a/docs/monitor/troubleshoot.md +++ b/docs/monitor/troubleshoot.md @@ -140,7 +140,7 @@ If you set your own start and end times, the button copies a link to that range The default log level is `Info`. If you are not seeing helpful logs, enable debug logging. -If a resource you configured is missing or unavailable, search the logs for `name collision`. Two resources sharing a name can stop both from building. See [Resource names](/hardware/configure-hardware/#resource-names). +If a resource you configured is missing or unavailable, search the logs for `Resource name`. Two resources sharing a name can stop both from building. See [Resource names](/hardware/configure-hardware/#resource-names). #### Enable debug logging