From ea14fec79dc02677bf1c0607d6f7362021a1bd29 Mon Sep 17 00:00:00 2001 From: lia <167905060+lia-viam@users.noreply.github.com> Date: Wed, 29 Jan 2025 10:07:13 -0500 Subject: [PATCH 1/3] Update README.md for sensor module --- src/viam/examples/modules/simple/README.md | 48 +++++++++++----------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/src/viam/examples/modules/simple/README.md b/src/viam/examples/modules/simple/README.md index c6f592b2c..a7337ac62 100644 --- a/src/viam/examples/modules/simple/README.md +++ b/src/viam/examples/modules/simple/README.md @@ -11,9 +11,9 @@ For more information, see the [documentation](https://docs.viam.com/registry/). For a list of example modules in different Viam SDKs, take a look [here](https://github.com/viamrobotics/upload-module/#example-repos). ## Project structure -The `main.cpp` file contains the definition of a new generic model and code to register it. It also has the optional validator function and implements reconfigure. The validator function is defined upon resource registration, and the reconfigure method is implemented on the resource class. +The `main.cpp` file contains the definition of a new sensor component and code to register it. It also has the optional validator function and implements reconfigure. The validator function is defined upon resource registration, and the reconfigure method is implemented on the resource class. -The validator function can throw errors that are triggered due to errors in the configuration. It also returns a vector of strings representing the implicit dependencies of the resource. Note that printers have no implicit dependencies; see the [complex module example](https://github.com/viamrobotics/viam-cpp-sdk/tree/main/src/viam/examples/modules/complex) for examples of modular resources with implicit dependencies. +The validator function can throw errors that are triggered due to errors in the configuration. It also returns a vector of strings representing the implicit dependencies of the resource. Note that this sensor has no implicit dependencies; see the [complex module example](https://github.com/viamrobotics/viam-cpp-sdk/tree/main/src/viam/examples/modules/complex) for examples of modular resources with implicit dependencies. The reconfiguration method reconfigures the resource based on the new configuration passed in. @@ -22,28 +22,28 @@ When simple_module is run, the main function creates and starts the module. Read ## Configuring and using the module The `simple_module` binary generated after building is the entrypoint for this module. To connect this module with your robot, you must add this module's entrypoint to the robot's config. For example, this could be `/home/viam-cpp-sdk/build/install/bin/simple_module`. See the [documentation](https://docs.viam.com/registry/configure/#add-a-local-module) for more details. -Once the module has been added to your robot, you will then need to add a component that uses the `viam:generic:printer` model. See the [documentation](https://docs.viam.com/registry/configure/#add-a-local-modular-resource) for more details. - -An example configuration for a printer could look like this: -```json -{ - "modules": [ - { - "name": "MyModule", - "executable_path": "/home/viam-cpp-sdk/build/install/bin/simple_module" - } - ], - "components": [ - { - "namespace": "rdk", - "type": "generic", - "name": "printer1", - "model": "viam:generic:printer", - "attributes": { - "to_print": "foo" - } - } - ] +Once the module has been added to your robot, you will then need to add a component that uses the `viam:sensor:mysensor` model. See the [documentation](https://docs.viam.com/registry/configure/#add-a-local-modular-resource) for more details. + +An example configuration for our sensor could look like this: +```json{ + "components": [ + { + "name": "mysensor", + "api": "rdk:component:sensor", + "model": "viam:sensor:mysensor", + "attributes": { + "multiplier": 2 + } + } + ], + "modules": [ + { + "type": "local", + "name": "my-module", + "executable_path": "/home/viam-cpp-sdk/build/src/viam/examples/modules/simple/simple_module" + } + ] } ``` +Note in particular that our sensor has a `multiplier` attribute whose presence is checked in the `validate` and `reconfigure` methods, defaulting to 1.0 if not present. From db37912d97d9a6e93f0b7112d77b9592674eaffd Mon Sep 17 00:00:00 2001 From: lia <167905060+lia-viam@users.noreply.github.com> Date: Wed, 29 Jan 2025 10:10:22 -0500 Subject: [PATCH 2/3] change exe path --- src/viam/examples/modules/simple/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/viam/examples/modules/simple/README.md b/src/viam/examples/modules/simple/README.md index a7337ac62..e06705678 100644 --- a/src/viam/examples/modules/simple/README.md +++ b/src/viam/examples/modules/simple/README.md @@ -40,7 +40,7 @@ An example configuration for our sensor could look like this: { "type": "local", "name": "my-module", - "executable_path": "/home/viam-cpp-sdk/build/src/viam/examples/modules/simple/simple_module" + "executable_path": "/home/viam-cpp-sdk/build/install/bin/simple_module" } ] } From f7d593bbacd0267d376c0c492096393301c6fdc5 Mon Sep 17 00:00:00 2001 From: lia <167905060+lia-viam@users.noreply.github.com> Date: Wed, 29 Jan 2025 14:04:24 -0500 Subject: [PATCH 3/3] Clarify structure of example directory --- src/viam/examples/README.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/src/viam/examples/README.md b/src/viam/examples/README.md index 5307189a4..b80ee7781 100644 --- a/src/viam/examples/README.md +++ b/src/viam/examples/README.md @@ -1,3 +1,11 @@ +# Viam C++ SDK Examples + +This directory contains some examples for working with the Viam SDK, ranging from component and service examples to module examples which show how to create modular resources. + +Note that with the exception of examples in the [`project`](./project) directory, all these examples are _part of the C++ SDK build tree_, which means that their build files only work if you are using them within an existing SDK build. For learning about SDK features and concepts this is fine, but it is **not** what you should use for starter code if you want, for example, to develop and deploy a standalone C++ module which lives outside of the SDK build tree. For that look in the [`project`](./project) directory, where you will find CMake and Makefile code which adapts the source code from the simple module example to work as a standalone project which consumes the Viam C++ SDK as a dependency. + + + # Component & Service Examples Examples: - camera @@ -16,9 +24,15 @@ This will setup a server running on `localhost:8080` that has a mock setup of th Download and build the C++ SDK by following the instructions [here](https://github.com/viamrobotics/viam-cpp-sdk#getting-started). -Then run: +Then run the executable for whichever component you chose to build above. This will be ``` shell -viam-cpp-sdk/build/viam/examples/[component name]/example_[component name] +# Camera +viam-cpp-sdk/build/viam/examples/camera/example_camera +``` +or +```shell +# Motor +viam-cpp-sdk/build/viam/examples/motor/example_motor ``` # Module examples @@ -27,14 +41,9 @@ Examples: - complex - tflite -These examples go through how to create custom modular resources using Viam's C++ SDK, and how to connect them to a Robot. Refer to each directory's README file for more information. - -# Generic Examples - -## Project example -This example shows how to setup a simple CMake-based project that uses Viam's C++ SDK. +These examples go through how to create custom modular resources using Viam's C++ SDK, and how to connect them to a Robot. Refer to each directory's README file for more information. As mentioned above, these can either be built as part of the SDK build tree, or you can use some of the build code in [`project`](./project) to build the simple module example as a standalone project which consumes the SDK as a dependency. -## Dial Example +# Dial Example If you are connecting to a robot with authentication you will need to add credentials. Update path code :