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.

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.

  4. Define your new API:

  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.

  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.

Next steps