DOCS-1174: Clarify model triplet (#1938)

docs/appendix/glossary/api-namespace-triplet.md

@@ -6,14 +6,14 @@ short_description: namespace:type:subtype
 aka:
 ---
 
-Every Viam {{< glossary_tooltip term_id="resource" text="resource" >}} subtype exposes an [application programming interface (API)](https://en.wikipedia.org/wiki/API) to describe how you can interact with that resource.
+Every Viam {{< glossary_tooltip term_id="resource" text="resource" >}} {{< glossary_tooltip term_id="subtype" text="subtype" >}} exposes an [application programming interface (API)](https://en.wikipedia.org/wiki/API) to describe how you can interact with that resource.
 
 These APIs are organized by colon-delimited-triplet identifiers, in the form of `namespace:type:subtype`.
 
 The `namespace` for built-in Viam resources is `rdk`, while the `type` is `component` or `service`.
 `subtype` refers to a specific component or service, like a `camera` or `vision`.
 
-One subtype can have various models, custom or built-in, but they all must conform to the subtype's API definition.
+One subtype can have various {{< glossary_tooltip term_id="model" text="models" >}}, custom or built-in, but they all must conform to the subtype's API definition.
 This requirement ensures that when a resource of that model is deployed, you can [interface with it](/program/) using the same [client API methods](/program/apis/) you would when programming resources of the same subtype with a different model.
 
 For example:

docs/appendix/glossary/model-namespace-triplet.md

@@ -1,14 +1,12 @@
 ---
 title: Model Namespace Triplet
 id: model-namespace-triplet
-full_link:
-short_description: namespace:family:name
+full_link: /modular-resources/key-concepts/#naming-your-model-namespacerepo-namename
+short_description: namespace:repo-name:name or rdk:builtin:name
 aka:
 ---
 
-{{< glossary_tooltip term_id="model" text="Models" >}} are uniquely namespaced as colon-delimited-triplets in the form of `namespace:family:name`.
-
-For example:
-
-- The `rdk:builtin:gpio` model implements the `rdk:component:motor` API to support [GPIO-controlled DC motors](/components/motor/gpio/).
-- The `rdk:builtin:DMC4000` model implements the `rdk:component:motor` API to support [DMC4000](/components/motor/dmc4000/) motor controllers.
+{{< glossary_tooltip term_id="model" text="Models" >}} are uniquely namespaced as colon-delimited-triplets.
+Modular resource model names have the form `namespace:repo-name:name`.
+Built-in model names have the form `rdk:builtin:name`.
+See [Naming your model](/modular-resources/key-concepts/#naming-your-model-namespacerepo-namename) for more information.

docs/manage/CLI.md

@@ -523,7 +523,7 @@ For example, the following represents the configuration of an example `my-module
 ```
 
 {{% alert title="Important" color="note" %}}
-If you are publishing a public module (`"visibility": "public"`), the [namespace of your model](/modular-resources/key-concepts/#naming-your-model) must match the [namespace of your organization](/manage/fleet/organizations/#create-a-namespace-for-your-organization).
+If you are publishing a public module (`"visibility": "public"`), the [namespace of your model](/modular-resources/key-concepts/#naming-your-model-namespacerepo-namename) must match the [namespace of your organization](/manage/fleet/organizations/#create-a-namespace-for-your-organization).
 In the example above, the model namespace is set to `acme` to match the owning organization's namespace.
 If the two namespaces do not match, the command will return an error.
 {{% /alert %}}

docs/modular-resources/configure.md

@@ -160,7 +160,7 @@ If the module requires you to configure specific **Attributes**, click the **URL
   "components": [
     {
       "name": "<your-model-instance-name>",
-      "model": "<model-namespace>:<model-family>:<model-name>",
+      "model": "<namespace>:<repo-name>:<name>",
       "type": "<your-resource-subtype>",
       "namespace": "<your-module-namespace>",
       "attributes": {},
@@ -344,7 +344,7 @@ The `attributes` available vary depending on your implementation.
     {
       "namespace": "<your-module-namespace>",
       "type": "<your-resource-subtype>",
-      "model": "<model-namespace>:<model-family>:<model-name>",
+      "model": "<namespace>:<repo-name>:<name>",
       "name": "<your-model-instance-name>",
       "attributes": {},
       "depends_on": []

docs/modular-resources/create/_index.md

@@ -49,7 +49,7 @@ A custom module can implement one or more [models](/modular-resources/key-concep
     - For example, the base client is defined in [<file>rdk/components/base/client.go</file>](https://github.com/viamrobotics/rdk/blob/main/components/base/client.go).
     - Base your edits to <file>my_modular_resource.go</file> or <file>my_modular_resource.py</file> on this first file.
     - Name your model according to the namespace of the built-in API you are implementing.
-      For more information see [Naming your model](/modular-resources/key-concepts/#naming-your-model).
+      For more information see [Naming your model](/modular-resources/key-concepts/#naming-your-model-namespacerepo-namename).
 
       <br> **To prepare to import your custom model and your chosen resource subtype's API into your main program and register them with your chosen SDK:**
 
@@ -65,8 +65,8 @@ A custom module can implement one or more [models](/modular-resources/key-concep
 
 ### Code a new resource model
 
-The following example module registers a modular resource implementing Viam's built-in [Base API](/components/base/#api) [(rdk:service:base)](/modular-resources/key-concepts/#models) as a new model, `"mybase"`, using the model family `acme:demo:mybase`.
-For more information see [Naming your model](/modular-resources/key-concepts/#naming-your-model).
+The following example module registers a modular resource implementing Viam's built-in [Base API](/components/base/#api) [(rdk:service:base)](/modular-resources/key-concepts/#models) as a new model, `"mybase"`, using the model `acme:demo:mybase`.
+For more information see [Naming your model](/modular-resources/key-concepts/#naming-your-model-namespacerepo-namename).
 
 The Go code for the custom model (<file>mybase.go</file>) and module entry point file (<file>main.go</file>) is adapted from the full demo modules available on the [Viam GitHub](https://github.com/viamrobotics/rdk/blob/main/examples/customresources).
 
@@ -119,7 +119,8 @@ class MyBase(Base, Reconfigurable):
     """
 
     # Here is where we define our new model's colon-delimited-triplet
-    # (acme:demo:mybase) acme = namespace, demo = family, mybase = model name.
+    # (acme:demo:mybase) acme = namespace, demo = repo-name,
+    # mybase = model name.
     MODEL: ClassVar[Model] = Model(ModelFamily("acme", "demo"), "mybase")
 
     def __init__(self, name: str, left: str, right: str):
@@ -280,7 +281,7 @@ import (
 )
 
 // Here is where we define your new model's colon-delimited-triplet (acme:demo:mybase)
-// acme = namespace, demo = family, mybase = model name.
+// acme = namespace, demo = repo-name, mybase = model name.
 var (
     Model            = resource.NewModel("acme", "demo", "mybase")
     errUnimplemented = errors.New("unimplemented")

docs/modular-resources/examples/custom-arm.md

@@ -21,7 +21,7 @@ aliases:
 # SMEs: Nicole Jung
 ---
 
-The {{< glossary_tooltip term_id="rdk" text="RDK" >}} provides a number of built-in arm {{< glossary_tooltip term_id="model" text="models" >}} that implement the API protocol of the [arm](/components/arm/) subtype of component, such as the `ur5e`, `xArm6`, and `xArm7`.
+The {{< glossary_tooltip term_id="rdk" text="RDK" >}} provides a number of built-in arm {{< glossary_tooltip term_id="model" text="models" >}} that implement the API protocol of the [arm](/components/arm/) {{< glossary_tooltip term_id="subtype" text="subtype" >}} of component, such as the `ur5e`, `xArm6`, and `xArm7`.
 
 {{% alert title="Info" color="info" %}}
 

docs/modular-resources/key-concepts.md

@@ -58,8 +58,10 @@ Models allow you to control different instances of a resource with a consistent
 For example, some DC motors communicate using [GPIO](/components/board/), while other DC motors use serial protocols like the [SPI bus](/components/board/#spis).
 Regardless, you can power any motor model that implements the `rdk:component:motor` API with the `SetPower()` method.
 
-Models are uniquely namespaced as colon-delimited-triplets in the form `namespace:family:name`.
-See [Naming your model](/modular-resources/key-concepts/#naming-your-model) for more information.
+Models are uniquely namespaced as colon-delimited-triplets.
+Modular resource model names have the form `namespace:repo-name:name`.
+Built-in model names have the form `rdk:builtin:name`.
+See [Naming your model](#naming-your-model-namespacerepo-namename) for more information.
 
 Models are either:
 
@@ -95,7 +97,7 @@ When implementing a custom [model](#models) of an existing [service](/services/)
 - `type`: `service`
 - `subtype`: any one of [these service proto files](https://github.com/viamrobotics/api/tree/main/proto/viam/service).
 
-#### Naming your model
+#### Naming your model: namespace:repo-name:name
 
 If you are [creating a custom module](/modular-resources/create/) and [uploading that module](/modular-resources/upload/) to the Viam registry, ensure your model name meets the following requirements:
 
@@ -104,31 +106,15 @@ If you are [creating a custom module](/modular-resources/create/) and [uploading
 - Your model triplet must be all-lowercase.
 - Your model triplet may only use alphanumeric (`a-z` and `0-9`), hyphen (`-`), and underscore (`_`) characters.
 
-In addition, you should chose a name for the `family` of your model based on the whether your module implements a single model, or multiple models:
-
-- If your module provides a single model, the `family` should match the `subtype` of whichever API your model implements.
-  For example, the Intel Realsense module `realsense`, available from the [Viam registry](https://app.viam.com/module/viam/realsense), implements the `camera` component API, so it is named as follows:
-
-  ```json {class="line-numbers linkable-line-numbers"}
-  {
-    "api": "rdk:component:camera",
-    "model": "viam:camera:realsense"
-  }
-  ```
-
-- If your module provides multiple models, the `family` should describe the common functionality provided across all the models of that module.
-  For example, the ODrive module `odrive`, available from the [Viam registry](https://app.viam.com/module/viam/odrive), implements several `motor` component APIs, so it is named as follows:
-
-  ```json {class="line-numbers linkable-line-numbers"}
-  {
-    "api": "rdk:component:motor",
-    "model": "viam:odrive:serial"
-  },
-  {
-    "api": "rdk:component:motor",
-    "model": "viam:odrive:canbus"
-  }
-  ```
+For the middle segment of your model triplet `repo-name`, use the name of the git repository where you store your module's code.
+The `repo-name` should describe the common functionality provided across the model or models of that module.
+
+For example:
+
+- The `rand:yahboom:arm` model and the `rand:yahboom:gripper` model uses the repository name [yahboom](https://github.com/viam-labs/yahboom).
+  The models implement the `rdk:component:arm` and the `rdk:component:gripper` API to support the Yahboom DOFBOT arm and gripper, respectively.
+- The `viam-labs:audioout:pygame` model uses the repository name [audioout](https://github.com/viam-labs/audioout)
+  It implements the custom API `viam-labs:service:audioout`.
 
 A model with the `viam` namespace is always Viam-provided.
 

docs/modular-resources/upload/_index.md

@@ -111,7 +111,7 @@ If you mark your module as public, you cannot change it back to private.
         <td><code>models</code></td>
         <td>object</td>
         <td><strong>Required</strong></td>
-        <td>A list of one or more <a href="/modular-resources/key-concepts/#models">models</a> provided by your custom module. You must provide at least one model, which consists of an <code>api</code> and <code>model</code> key pair. If you are publishing a public module (<code>"visibility": "public"</code>), the <a href="/modular-resources/key-concepts/#naming-your-model">namespace of your model</a> must match the <a href="/manage/fleet/organizations/#create-a-namespace-for-your-organization">namespace of your organization</a>.</td>
+        <td>A list of one or more <a href="/modular-resources/key-concepts/#models">models</a> provided by your custom module. You must provide at least one model, which consists of an <code>api</code> and <code>model</code> key pair. If you are publishing a public module (<code>"visibility": "public"</code>), the <a href="/modular-resources/key-concepts/#naming-your-model-namespacerepo-namename">namespace of your model</a> must match the <a href="/manage/fleet/organizations/#create-a-namespace-for-your-organization">namespace of your organization</a>.</td>
       </tr>
       <tr>
         <td><code>entrypoint</code></td>

docs/tutorials/custom/controlling-an-intermode-rover-canbus.md

@@ -121,15 +121,15 @@ Since you will conform to an existing Viam API for [base](/components/base/), th
 **rdk:component:base**
 
 This base model is being created for tutorial purposes only, and will implement only partial functionality for demonstration purposes.
-Therefore, use the namespace "viamlabs", an (arbitrary) model family called "tutorial" and lastly, a model name of "intermode".
+Therefore, use the namespace "viamlabs", an (arbitrary) repo-name called "tutorial" and lastly, a model name of "intermode".
 The complete triplet is:
 **viamlabs:tutorial:intermode**
 
 The [module.go code](https://github.com/viam-labs/tutorial-intermode) creates this model and registers the component instance.
 The _Subtype_ of a resource contains its API triplet, so using `base.Subtype` (see line 30 below) registers our new model with the _API_ from the RDK's built-in base component (rdk:component:base).
 
 ```go {class="line-numbers linkable-line-numbers"}
-// namespace, model family, model
+// namespace, repo-name, model
 var model = resource.NewModel("viamlabs", "tutorial", "intermode")
 
 func main() {

docs/tutorials/custom/custom-base-dog.md

@@ -225,14 +225,14 @@ As you follow the prompts, it's a good idea to use the same names we used so tha
 
 - Model name: `robotdog`
 - Module namespace: `viamlabs`
-- Module family: `base`
+- Module repo-name: `base`
 - Language: `python`
 - API triplet: `rdk:components:base`
 - Existing API? `Yes`
 
 {{% alert title="Important" color="note" %}}
 
-You can use a different model name, module namespace, and family, but you need to use the existing API triplet `rdk:components:base` in order for your custom base to work properly as a base with `viam-server` and the [Viam app](https://app.viam.com/).
+You can use a different model name, module namespace, and repo-name, but you need to use the existing API triplet `rdk:components:base` in order for your custom base to work properly as a base with `viam-server` and the [Viam app](https://app.viam.com/).
 
 {{% /alert %}}