Define a New Resource Subtype

You can define a new, custom resource subtype API if:

• You have a resource that does not fit into any of the existing component or service subtypes.
• You have a resource that could fit into an existing subtype, but you want to define an API with different methods and messages than the ones in the existing APIs for that subtype.

Define your new resource API

Viam uses protocol buffers for API definition.

To define a new subtype, you need to define the methods and messages of the new API in protobuf, write code in Python or Go to implement the higher level server and client functions required, and generate all necessary protobuf module files. The following steps guide you through this process in more detail:

1. Decide whether your custom subtype is a component or a service. If it provides an interface to control hardware, it is a component. If it provides higher-level functionality, it is a service.

2. Choose a name for your subtype. For example, gizmo.

   Determine a valid API namespace triplet based on your subtype name. You can figure out the model namespace triplet later when you create a model that implements your custom API.

   API namespace triplet and model namespace triplet example

   The viam-labs:audioout:pygame model uses the repository name audioout. It implements the custom API viam-labs:service:audioout:

   {
     "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.

3. Create a directory for your module. Within that, create a directory called src.

   Tip

   If you are writing your module using Python, you can use this module generator tool to generate stub files for the new API as well as a new module that implements the new API.

4. Define your new API:

   • Write the proto methods in a <subtype name>.proto file inside your src/proto directory. For reference:
     • Example modular component proto file
     • Example modular service proto file
     • Built-in Viam resource proto files
   • And define the proto methods in a protobuf-supported language such as Python or Go in a file called api.py or api.go, respectively.
     • Example component in Python
     • Example service in Python

5. In the root directory of your module, you need to generate some configuration files. You will typically need the following three files for most modules, though different files are required for some advanced use cases. See the Buf documentation for instructions.

   • buf.yaml
   • buf.gen.yaml
   • buf.lock

6. In the /src/ directory of your module, use the protobuf compiler to generate all other necessary protocol buffer code, based on the <subtype name>.proto file you wrote.

   • Example generated files for a Python-based service. The buf. files were generated. The speech.proto was manually written.

Next steps