RSDK-4648: Document namespace nomenclature better (#417)

Co-authored-by: hexbabe <[email protected]>
Co-authored-by: andf-viam <[email protected]>

Author: 3 people

docs/examples/example.ipynb

@@ -321,7 +321,7 @@
     "\n",
     "class MySensor(Sensor):\n",
     "    # Subclass the Viam Sensor component and implement the required functions\n",
-    "    MODEL: ClassVar[Model] = Model(ModelFamily(\"acme\",\"wifi_sensor\"), \"linux\")\n",
+    "    MODEL: ClassVar[Model] = Model(ModelFamily(\"viam\",\"sensor\"), \"linux-wifi\")\n",
     "\n",
     "    @classmethod\n",
     "    def new(cls, config: ComponentConfig, dependencies: Mapping[ResourceName, ResourceBase]) -> Self:\n",
@@ -511,15 +511,15 @@
     "### 5. Configure a modular resource\n",
     "**NOTE:** *If you are adding your module to the registry, follow [these instructions](https://docs.viam.com/extend/modular-resources/configure/) instead. Otherwise, continue with these instructions, which will show you how to configure the module locally.*\n",
     "\n",
-    "[Configure your new module](https://docs.viam.com/extend/modular-resources/#configure-your-module) on your robot by navigating to the **Config** tab of the robot's page on the Viam app, then click on the **Modules** subtab. Add the name of your module and the executable path. For our example, the path would be `<path-on-your-filesystem>/wifi-sensor/run.sh`.\n",
+    "[Configure your new module](https://docs.viam.com/extend/modular-resources/#configure-your-module) on your robot by navigating to the **Config** tab of the robot's page on the Viam app, then click on the **Modules** subtab. Add the name of your module and the executable path. For our example, the path would be `<path-on-your-filesystem>/linux-wifi/run.sh`.\n",
     "\n",
     "Once you have configured a module as part of your robot configuration, [configure your modular resource](https://docs.viam.com/extend/modular-resources/#configure-your-modular-resource) made available by that module by adding new components or services configured with your modular resources' new type or model. To instantiate a new resource from your module, specify the `type`, `model`, and `name` of your modular resource. The aforementioned `type`, `model`, and `name` should be the same as those in the `MODEL` class attribute defined in your [component class](#2-register-the-custom-component). This is a JSON example:\n",
     "\n",
     "```json\n",
     "{\n",
     "  \"components\": [\n",
     "    {\n",
-    "      \"model\": \"acme:wifi_sensor:linux\",\n",
+    "      \"model\": \"viam:sensor:linux-wifi\",\n",
     "      \"attributes\": {},\n",
     "      \"depends_on\": [],\n",
     "      \"name\": \"my-sensor\",\n",
@@ -528,12 +528,18 @@
     "  ],\n",
     "  \"modules\": [\n",
     "    {\n",
-    "      \"executable_path\": \"<path-on-your-filesystem>/wifi-sensor/run.sh\",\n",
+    "      \"executable_path\": \"<path-on-your-filesystem>/linux-wifi/run.sh\",\n",
     "      \"name\": \"wifi_sensor\"\n",
     "    }\n",
     "  ]\n",
     "}\n",
-    "```\n"
+    "```\n",
+    "\n",
+    "Note the nomenclature of the above `model` field, `viam:sensor:linux-wifi`. Models are uniquely namespaced as colon-delimited-triplets in the form `namespace:family:name`, and are named according to the Viam API that your model implements. A model with the `viam` namespace is always Viam-provided. Read more about making custom namespaces [here](https://docs.viam.com/extend/modular-resources/key-concepts/#models).\n",
+    "\n",
+    "Viam also provides many built-in models that implement API capabilities, each using `rdk` as the `namespace`, and `builtin` as the `family`:\n",
+    "- The `rdk:builtin:gpio` model of the `rdk:component:motor` API provides RDK support for [GPIO-controlled DC motors](https://docs.viam.com/components/motor/gpio/).\n",
+    "- The `rdk:builtin:DMC4000` model of the same `rdk:component:motor` API provides RDK support for the [DMC4000](https://docs.viam.com/components/motor/dmc4000/) motor."
    ]
   },
   {
@@ -566,7 +572,7 @@
     "\n",
     "class MyModularArm(Arm):\n",
     "    # Subclass the Viam Arm component and implement the required functions\n",
-    "    MODEL: ClassVar[Model] = Model(ModelFamily(\"acme\", \"demo\"), \"myarm\")\n",
+    "    MODEL: ClassVar[Model] = Model(ModelFamily(\"viam\", \"arm\"), \"my-arm\")\n",
     "\n",
     "    def __init__(self, name: str):\n",
     "        # Starting joint positions\n",

examples/complex_module/README.md

@@ -34,7 +34,9 @@ These steps assume that you have a robot available at [app.viam.com](app.viam.co
 
 The `run.sh` script is the entrypoint for this module. To connect this module with your robot, you must add this module's entrypoint to the robot's config. For example, the entrypoint file may be at `/home/viam-python-sdk/examples/complex_module/run.sh` and you must add this file path to your configuration. See the [documentation](https://docs.viam.com/program/extend/modular-resources/#use-a-modular-resource-with-your-robot) for more details.
 
-Once the module has been added to your robot, add a `Gizmo` component that uses the `MyGizmo` model. See the [documentation](https://docs.viam.com/program/extend/modular-resources/#configure-a-component-instance-for-a-modular-resource) for more details. You can also add an `Arm` component that uses the `MyArm` model and a `Summation` service that uses the `MySum` model in a similar manner.
+Once the module has been added to your robot, add a `Gizmo` component that uses the `MyGizmo` model. See the [documentation](https://docs.viam.com/extend/modular-resources/configure/) for more details. You can also add an `Arm` component that uses the `MyArm` model and a `Summation` service that uses the `MySum` model in a similar manner.
+
+Models are uniquely namespaced as colon-delimited-triplets in the form `namespace:family:name`, and are named according to the Viam API that your model implements. A model with the `viam` namespace is always Viam-provided. Read more about making custom namespaces [here](https://docs.viam.com/extend/modular-resources/key-concepts/#models).
 
 An example configuration for an Arm component, a Gizmo component, and a Summation service could look like this:
 
@@ -44,7 +46,7 @@ An example configuration for an Arm component, a Gizmo component, and a Summatio
     {
       "name": "arm1",
       "type": "arm",
-      "model": "acme:demo:myarm",
+      "model": "viam:arm:myarm",
       "attributes": {},
       "depends_on": []
     },
@@ -92,7 +94,7 @@ An example configuration for an Arm component, a Gizmo component, and a Summatio
         "left": "motor1",
         "right": "motor2"
       },
-      "model": "acme:demo:mybase",
+      "model": "viam:base:mybase",
       "depends_on": []
     }
   ],

examples/complex_module/src/arm/my_arm.py

@@ -14,7 +14,7 @@
 
 class MyArm(Arm):
     # Subclass the Viam Arm component and implement the required functions
-    MODEL: ClassVar[Model] = Model(ModelFamily("acme", "demo"), "myarm")
+    MODEL: ClassVar[Model] = Model(ModelFamily("viam", "arm"), "myarm")
 
     def __init__(self, name: str):
         # Starting position

examples/complex_module/src/base/my_base.py

@@ -24,7 +24,7 @@ class MyBase(Base, Reconfigurable):
     """
 
     # Subclass the Viam Base component and implement the required functions
-    MODEL: ClassVar[Model] = Model(ModelFamily("acme", "demo"), "mybase")
+    MODEL: ClassVar[Model] = Model(ModelFamily("viam", "base"), "mybase")
 
     def __init__(self, name: str):
         super().__init__(name)

examples/simple_module/README.md

@@ -26,14 +26,16 @@ The `run.sh` script is the entrypoint for this module. To connect this module wi
 
 Once the module has been added to your robot, add a new component that uses the `MySensor` model. See the [documentation](https://docs.viam.com/program/extend/modular-resources/#configure-a-component-instance-for-a-modular-resource) for more details.
 
+Models are uniquely namespaced as colon-delimited-triplets in the form `namespace:family:name`, and are named according to the Viam API that your model implements. A model with the `viam` namespace is always Viam-provided. Read more about making custom namespaces [here](https://docs.viam.com/extend/modular-resources/key-concepts/#models).
+
 An example configuration for a Sensor component could look like this:
 ```json
 {
   "components": [
     {
       "name": "sensor1",
       "type": "sensor",
-      "model": "acme:demo:mysensor",
+      "model": "viam:sensor:mysensor",
       "attributes": {},
       "depends_on": []
     }

examples/simple_module/src/main.py

@@ -15,7 +15,7 @@
 
 class MySensor(Sensor):
     # Subclass the Viam Sensor component and implement the required functions
-    MODEL: ClassVar[Model] = Model(ModelFamily("acme", "demo"), "mysensor")
+    MODEL: ClassVar[Model] = Model(ModelFamily("viam", "sensor"), "mysensor")
     multiplier: float
 
     def __init__(self, name: str):