Skip to content

Commit

Permalink
DOCS-3171: Add more custom API versus custom model distinction (#3709)
Browse files Browse the repository at this point in the history
  • Loading branch information
JessamyT authored Nov 26, 2024
1 parent 3027910 commit 5c58eff
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 13 deletions.
16 changes: 3 additions & 13 deletions docs/how-tos/create-module.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ The three pieces of the API namespace triplet are as follows:

In addition to determining which existing API namespace triplet to use when creating your module, you need to decide on a separate triplet unique to your model.

{{< expand "API namespace triplet and model namespace triplet examples" >}}
{{< expand "API namespace triplet and model namespace triplet example" >}}

The `rand:yahboom:arm` model and the `rand:yahboom:gripper` model use 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:
Expand All @@ -136,16 +136,6 @@ The models implement the `rdk:component:arm` and the `rdk:component:gripper` API
}
```

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`:

```json
{
"api": "viam-labs:service:audioout",
"model": "viam-labs:audioout:pygame"
}
```

{{< /expand >}}

A resource model is identified by a unique name, called the {{< glossary_tooltip term_id="model-namespace-triplet" text="model namespace triplet" >}}, using the format: `namespace:repo-name:model-name`, where:
Expand Down Expand Up @@ -1224,7 +1214,7 @@ When packaged in this fashion, you can run the resulting executable on your desi
To create a packaged executable:

1. First, [create a Python virtual environment](/sdks/python/python-venv/) in your module's directory to ensure your module has access to any required libraries.
Be sure you are within your Python virtual environment for the rest of these steps: your terminal prompt should include the name of your virtual environment in parenthesis.
Be sure you are within your Python virtual environment for the rest of these steps: your terminal prompt should include the name of your virtual environment in parentheses.

1. Create a `requirements.txt` file containing a list of all the dependencies your module requires.
For example, a `requirements.txt` file with the following contents ensures that the Viam Python SDK (`viam-sdk`), PyInstaller (`pyinstaller`), and the Google API Python client (`google-api-python-client`) are installed:
Expand Down Expand Up @@ -1343,7 +1333,7 @@ Use the [`nuitka` Python compiler](https://pypi.org/project/Nuitka/) to compile
1. In order to use Nuitka, you must install a [supported C compiler](https://github.com/Nuitka/Nuitka#c-compiler) on your machine.

1. Then, [create a Python virtual environment](/sdks/python/python-venv/) in your module's directory to ensure your module has access to any required libraries.
Be sure you are within your Python virtual environment for the rest of these steps: your terminal prompt should include the name of your virtual environment in parenthesis.
Be sure you are within your Python virtual environment for the rest of these steps: your terminal prompt should include the name of your virtual environment in parentheses.

1. Create a `requirements.txt` file containing a list of all the dependencies your module requires.
For example, a `requirements.txt` file with the following contents ensures that the Viam Python SDK (`viam-sdk`) and Nuitka (`nuitka`) are installed:
Expand Down
20 changes: 20 additions & 0 deletions docs/registry/advanced/create-subtype.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,26 @@ The following steps guide you through this process in more detail:
If it provides higher-level functionality, it is a service.
1. Choose a name for your subtype.
For example, `gizmo`.

Determine a valid {{< glossary_tooltip term_id="api-namespace-triplet" text="API namespace triplet" >}} based on your subtype name.
You can figure out the {{< glossary_tooltip term_id="model-namespace-triplet" text="model namespace triplet" >}} later when you [create a model that implements your custom API](/registry/advanced/create-subtype/#next-steps).

{{< expand "API namespace triplet and model namespace triplet example" >}}

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`:

```json
{
"api": "viam-labs:service:audioout",
"model": "viam-labs:audioout:pygame"
}
```

For your custom API, your API namespace triplet might be `your-org-namespace:component:gizmo` where `your-org-namespace` is your organization namespace, found in your org settings page in the Viam app.

{{< /expand >}}

1. Create a directory for your module.
Within that, create a directory called <file>src</file>.

Expand Down

0 comments on commit 5c58eff

Please sign in to comment.