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.
If your use case uses only DoCommand and no other API methods, you can define a new model of generic component or generic service.
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:
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.
Choose a name for your subtype. For example,
gizmo.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.
Define your new API:
- Write the proto methods in a
<subtype name>.protofile inside yoursrc/proto directory. For reference: - And define the proto methods in a protobuf-supported language such as Python or Go in a file called
api.pyorapi.go, respectively.
- Write the proto methods in a
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.
In the
/src/ directory of your module, use the protobuf compiler to generate all other necessary protocol buffer code, based on the<subtype name>.protofile you wrote.- Example generated files for a Python-based service.
The
buf.files were generated. Thespeech.proto was manually written.
- Example generated files for a Python-based service.
The
Next steps
Was this page helpful?
Glad to hear it! If you have any other feedback please let us know:
We're sorry about that. To help us improve, please tell us what we can do better:
Thank you!