Define a New Resource Subtype

You can define a new 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.

  Tip

  If you want to use most of an existing API but need just a few other functions, try using the DoCommand endpoint and extra parameters to add custom functionality to an existing subtype. For example, if you have a sensor and you want to define a Calibrate method, you can use DoCommand.

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

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 boilerplate 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