{"id":24324577,"url":"https://github.com/abe-winter/module-example-cpp","last_synced_at":"2025-08-22T08:11:17.835Z","repository":{"id":193122018,"uuid":"685158762","full_name":"abe-winter/module-example-cpp","owner":"abe-winter","description":"Example repo for building a Viam module with C++","archived":false,"fork":false,"pushed_at":"2024-01-19T17:27:10.000Z","size":82,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-11T04:23:50.880Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abe-winter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-30T16:31:05.000Z","updated_at":"2025-01-29T11:26:14.000Z","dependencies_parsed_at":null,"dependency_job_id":"43b84da5-fd29-4c14-9553-e79c2bc52ceb","html_url":"https://github.com/abe-winter/module-example-cpp","commit_stats":null,"previous_names":["viamrobotics/module-example-cpp","abe-winter/module-example-cpp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/abe-winter/module-example-cpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abe-winter%2Fmodule-example-cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abe-winter%2Fmodule-example-cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abe-winter%2Fmodule-example-cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abe-winter%2Fmodule-example-cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abe-winter","download_url":"https://codeload.github.com/abe-winter/module-example-cpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abe-winter%2Fmodule-example-cpp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271606595,"owners_count":24788979,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-22T02:00:08.480Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-17T19:41:02.146Z","updated_at":"2025-08-22T08:11:17.777Z","avatar_url":"https://github.com/abe-winter.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# C++ example module\n\nThis example module demonstrates the use of the [C++ SDK](https://github.com/viamrobotics/viam-cpp-sdk) to build a minimal Viam module.\nIt is [available for use on the registry](https://app.viam.com/module/viam/module-example-cpp) and shows how to include CI (Continuous Integration) builds for both x86 and ARM architectures.\n\nYou can use this as a reference along with the C++ instructions for [coding your own modules](https://docs.viam.com/registry/create/).\n\n\n## Requirements\n\nBefore building this module, verify your operating system's development environment is compatible.\nThe tested ideal environment for building this module is Debian Bullseye (used in our CI).\n\nYou can also use Ubuntu 22.04 for testing, but the resulting C++ builds will not be binary compatible with Bullseye.\n\n\nTo setup for building this module:\n\n1. Install the apt packages in [apt-setup.sh](apt-setup.sh).\n2. Install the latest version of CMake to ensure compatibility with this module's CI.\n\u003cbr/\u003e\u003cbr/\u003eTo install CMake on **Ubuntu 22.04**, run the following command:\u003cbr/\u003e\u003cbr/\u003e\n\t```sh\n\tsnap install cmake\n\t```\n            \n\u003e [!WARNING]\n\u003e Avoid using `apt-get` as it may install an older version of CMake.\n\n* See [CMake's download instructions](https://cmake.org/download/) for more information.\u003cbr/\u003e\n  \t\n3. [Install rust](https://www.rust-lang.org/tools/install) (needed for `viam_rust_utils`).\n\n\n## Build and Run\n\nYou can build this example module by either the following steps to build it directly from the registry or by opting for the local build instructions.\n\n### Build from the Registry\n\nTo build this module and it's executable sourced from the registry, follow this set of instructions.\nThese instructions assume a target system similar to Debian Bullseye.\nFirst, install the required libraries on your target system:\n\n```sh\nsudo apt install -qqy libgrpc++1 libboost-log1.74.0\n```\n\nThen follow the C++ instructions to [add a module from the Viam Registry](https://docs.viam.com/registry/configure/#add-a-modular-resource-from-the-viam-registry) and select the `wifi:cpp` model from the `module-example-cpp` module.\n\n### Build Locally\n\nThese instructions assume a target system similar to Debian Bullseye.\n\nBefore you can build this module's executable, you must follow the steps to [prepare a module for execution](https://docs.viam.com/registry/create/#prepare-the-module-for-execution).\n\nYou can use the sections linked in the [Module Contents](#module-contents) section as a reference when creating and building your own C++ module.\n\n## Configure your Example C++ Module\n\n\u003e [!NOTE]\n\u003e Before configuring your example module, you must [add a machine](https://docs.viam.com/fleet/machines/#add-a-new-machine).\n\nNavigate to the **Config** tab of your machine’s page in [the Viam app](https://app.viam.com/).\nClick on the **Components** subtab and click **Create component**.\nSelect **Sensor**, then search for the `wifi:cpp` model. Give your resource a name of your choice, click **Create** and then click **Save config**.\n\nNext, change the **Mode:** selector from **Builder** to **Raw JSON**, and verify that `\"components\"` array now includes the `viam:wifi:cpp` model and that `\"modules\"` array includes the `module-example-cpp` module. \n\nYour `Raw JSON` configuration should now include both: \n\n```json {class=\"line-numbers linkable-line-numbers\"}\n{\n  \"modules\": [\n    {\n      \"type\": \"registry\",\n      \"name\": \"viam_module-example-cpp\",\n      \"module_id\": \"viam:module-example-cpp\",\n      \"version\": \"0.0.3\"\n    }\n  ],\n  \"components\": [\n    {\n      \"name\": \"my-wifi-cpp\",\n      \"model\": \"viam:wifi:cpp\",\n      \"type\": \"sensor\",\n      \"namespace\": \"rdk\",\n      \"attributes\": {},\n      \"depends_on\": []\n    }\n  ]\n}\n```\n\nIf you upload your version to the Viam registry after building it, remember to update `model` and `module_id` with your values.\nIf you aren't using the registry, you can also use `scp` to transfer the build to your machine and run it in \n[executable_path / local exec mode](https://docs.viam.com/extend/modular-resources/configure/#configure-your-module).\n\n\u003e [!NOTE]  \n\u003e For more information, see [Configure a Machine](https://docs.viam.com/manage/configuration/).\n\n\n## Module Contents\n\nYou can use this repository's files as a reference when building your C++ module:\n\n| Name  | Content | Location |\n| ------------- | ------------- | ------------- |\n| `CMakeLists.txt` | The configuration for compiling the binary and managing dependencies. | `-` |\n| `Makefile` | The command to create the module tarball dependencies. | `-` |\n| `.github/workflows/` | The CI build and deployment logic for the registry. | `-` |\n| `run.sh` and `apt-setup.sh` | The entrypoint and dependency installation for running the module on a machine. | `-` |\n| `meta.json` | The Viam module configuration. | `-` |\n| `main.cpp`  | The module's entry point file.\u003c/br\u003eSee [Code a main entry point program](https://docs.viam.com/registry/create/#code-a-main-entry-point-program) for more information. | `src`|\n| `wifi.cpp` | The resource model which implements all the methods that the Viam RDK require.\u003c/br\u003eSee [Code a new resource model](https://docs.viam.com/registry/create/#code-a-new-resource-model) for more information. | `src` |\n| `wifi.hpp` | The defined implementation of the derivative `WifiSensor` class in `wifi.cpp`.\u003c/br\u003eSee [Find your reference files](https://docs.viam.com/registry/create/#find-your-reference-files) for more information. | `src` |\n\n\n## Setting Up CI\n\nThis module uses [Buildjet runners](https://buildjet.com/for-github-actions) to build natively for ARM.\nIf you fork this repository and don't have Buildjet connected to GitHub, your CI jobs won't start.\n\nYou can choose one option for CI setup:\n- Exlusively targetting x86\n- Building on an ARM emulator using [QEMU](https://www.qemu.org/download/) with [docker/build-push-action](https://github.com/docker/build-push-action)\n- Setting up cross-compilation\n\nRefer to the [fork instructions](https://github.com/viam-labs/python-example-module#forking-this-repo) in the Python example module for more details on deploying your fork. \n\n\n## Troubleshooting\n\n\u003e [!NOTE]\n\u003e Ensure you have `viam-server` installed your machine.\n\n\n### Library Paths\n\nUse `ldd` to identify library path issues.\ns\nFor example:\n\n- If you are unable to find one of the `libviam` packages (for example: `libviamsdk.so.noabi`), ensure `libvimapi` and `libviamsdk` are bundled in your `module.tar.gz`.\n- Confirm that `LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$PWD` (handled by the `run.sh` wrapper) is set.\n- If any other libraries are missing, use `apt-get install` to install them.\n\n\n### Connecting a Debugger\n\nFor unexplained issues, you can use a debugger to investigate crashes or disconnects.\nThe debugger referenced in this case is [GDB](https://www.onlinegdb.com/).\n\n1. Configure your machine to use the module and ensure it's running.\n2. Find the PID of your running module with `ps aux | grep module-example-cpp`.\n3. Run `sudo gdb --pid $PID` with the obtained PID (use `sudo` as `viam-server` is likely running in sudo).\n4. Type `continue` in gdb to restart the process.\n5. Trigger the action causing the issue, and gdb should catch it.\n\nFor a more involved C++ module example, which defines both a component and service API, see the [C++ complex module example](https://github.com/viamrobotics/viam-cpp-sdk/tree/main/src/viam/examples/modules/complex).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabe-winter%2Fmodule-example-cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabe-winter%2Fmodule-example-cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabe-winter%2Fmodule-example-cpp/lists"}