-
Program your robots
+ Program your machine
- Program and control your robots in the languages you already know like Python, Go, TypeScript, C++, or Flutter. + Program and control your machines in the languages you already know like Python, Go, TypeScript, C++, or Flutter.
@@ -162,7 +162,7 @@ sitemap:
{{}}
diff --git a/docs/appendix/glossary/component.md b/docs/appendix/glossary/component.md
index 93112452f4..c65e2e32fc 100644
--- a/docs/appendix/glossary/component.md
+++ b/docs/appendix/glossary/component.md
@@ -7,3 +7,5 @@ aka:
---
A resource that represents a physical component in a robot which a computer controls; for example, a servo, a camera, or an arm.
+
+For more information, see [Components](/components/).
diff --git a/docs/appendix/glossary/fragment.md b/docs/appendix/glossary/fragment.md
index 83b930d06f..4ffea1e973 100644
--- a/docs/appendix/glossary/fragment.md
+++ b/docs/appendix/glossary/fragment.md
@@ -9,4 +9,4 @@ aka:
A reusable configuration block that you can share across multiple robots.
For example, if you are deploying a specific mobile robot that is always physically connected the same way, you can create a fragment to make managing your fleet easy.
-For more information see [Fragments](../../manage/configuration/#fragments).
+For more information, see [Fragments](../../manage/configuration/#fragments).
diff --git a/docs/appendix/glossary/location.md b/docs/appendix/glossary/location.md
index 634598766c..40d4baf451 100644
--- a/docs/appendix/glossary/location.md
+++ b/docs/appendix/glossary/location.md
@@ -1,11 +1,11 @@
---
title: Location
id: location
-full_link:
+full_link: /manage/fleet/locations/
short_description: A location is a virtual grouping of robots that allows you to organize robots and manage access to your fleet.
aka:
---
A location is a virtual grouping of robots that allows you to organize robots and manage access to your fleet.
-For more information, see [Fleet Management](/manage/fleet/).
+For more information, see [Manage Locations and Sub-Locations](/manage/fleet/locations/).
diff --git a/docs/appendix/glossary/organization.md b/docs/appendix/glossary/organization.md
index 016887e806..7d29c685c2 100644
--- a/docs/appendix/glossary/organization.md
+++ b/docs/appendix/glossary/organization.md
@@ -1,7 +1,7 @@
---
title: Organization
id: organization
-full_link:
+full_link: /manage/fleet/organizations/
short_description: An organization is a group of one or more locations that helps you organize your fleet and manage who has access to your fleet.
aka:
---
@@ -10,4 +10,4 @@ An organization is the highest level grouping in the Viam platform, which genera
Every {{< glossary_tooltip term_id="location" text="location" >}} is grouped into an organization.
You can also have organizations for departments or other entities, or for personal use.
-For more information, see [Fleet Management](/manage/fleet/).
+For more information, see [Manage Organizations](/manage/fleet/organizations/).
diff --git a/docs/appendix/glossary/process.md b/docs/appendix/glossary/process.md
index eca60e735f..b9a3d7b78e 100644
--- a/docs/appendix/glossary/process.md
+++ b/docs/appendix/glossary/process.md
@@ -11,3 +11,5 @@ Processes are binaries or scripts that run on a {{< glossary_tooltip term_id="pa
You can use processes to create a new local instance of `viam-server` to implement drivers for custom {{< glossary_tooltip term_id="component" text="components" >}}, or to run a client application, for example.
They provide an OS-specific process managed by `viam-server` to either run once or indefinitely.
For example, you could use a process to run a camera server.
+
+For information on how to configure a process, see [Configure a Robot](/manage/configuration/#processes).
diff --git a/docs/appendix/glossary/remote.md b/docs/appendix/glossary/remote.md
index 1ae4ca28e6..439c4dcd55 100644
--- a/docs/appendix/glossary/remote.md
+++ b/docs/appendix/glossary/remote.md
@@ -8,4 +8,4 @@ aka:
A robot part which is controlled by another robot part.
-For more information see [Robot Architecture: Parts, Sub-Parts and Remotes](../../manage/parts-and-remotes/).
+For more information, see [Robot Architecture: Parts, Sub-Parts and Remotes](../../manage/parts-and-remotes/).
diff --git a/docs/appendix/glossary/robot-config.md b/docs/appendix/glossary/robot-config.md
index 56e714b2f0..94a4cb0662 100644
--- a/docs/appendix/glossary/robot-config.md
+++ b/docs/appendix/glossary/robot-config.md
@@ -1,11 +1,11 @@
---
title: Robot Config
id: robot-config
-full_link:
+full_link: /manage/configuration/
short_description: The complete configuration of a single robot part.
aka:
---
The complete configuration of a single robot {{< glossary_tooltip term_id="part" text="part" >}}.
-For more information see [Configuration](../../manage/configuration/).
+For more information, see [Configuration](../../manage/configuration/).
diff --git a/docs/appendix/glossary/robot.md b/docs/appendix/glossary/robot.md
index 588494e4b5..6e49494c00 100644
--- a/docs/appendix/glossary/robot.md
+++ b/docs/appendix/glossary/robot.md
@@ -1,11 +1,11 @@
---
title: Robot
id: robot
-full_link: /manage/fleet/#robots
+full_link: /manage/fleet/robots/
short_description: An organizational concept, consisting of either one part, or multiple parts working closely together to complete tasks.
aka:
---
An organizational concept, consisting of either one *{{< glossary_tooltip term_id="part" text="part" >}}*, or multiple *parts* working closely together to complete tasks.
-For more information, see [Robots](../../manage/fleet/#robots).
+For more information, see [Robots](../../manage/fleet/robots/).
diff --git a/docs/appendix/glossary/service.md b/docs/appendix/glossary/service.md
index 9c35d17410..e8f1cd4835 100644
--- a/docs/appendix/glossary/service.md
+++ b/docs/appendix/glossary/service.md
@@ -6,4 +6,6 @@ short_description: Built-in software packages for complex capabilities such as S
aka:
---
-Services are built-in software packages for complex capabilities such as SLAM, Computer Vision, Motion Planning, and Data Collection.
+Services are built-in software packages for complex capabilities such as SLAM, computer vision, motion planning, and data collection.
+
+For more information, see [Services](/services/).
diff --git a/docs/appendix/glossary/slam.md b/docs/appendix/glossary/slam.md
index d5f3ea0db6..d7bec0a92d 100644
--- a/docs/appendix/glossary/slam.md
+++ b/docs/appendix/glossary/slam.md
@@ -7,3 +7,5 @@ aka:
---
Simultaneous Localization and Mapping (SLAM) is an algorithm that allows your robot to create a map of its surroundings and find its location within that map.
+
+For more information, see [SLAM](/services/slam/).
diff --git a/docs/appendix/glossary/smart-machine.md b/docs/appendix/glossary/smart-machine.md
new file mode 100644
index 0000000000..669df49af7
--- /dev/null
+++ b/docs/appendix/glossary/smart-machine.md
@@ -0,0 +1,10 @@
+---
+title: Smart Machine
+id: smart-machine
+full_link:
+short_description: A machine or device that lives in the real world and has some ability to perceive the world (with a sensor, for example) and perform actions like operating a motor.
+aka:
+---
+
+A machine or device that lives in the real world and has some ability to perceive the world (with a sensor, for example) and perform actions like operating a motor.
+The machine might also interact with other systems, with the cloud, or with users.
diff --git a/docs/components/arm/_index.md b/docs/components/arm/_index.md
index 1760640a83..21d3d7659c 100644
--- a/docs/components/arm/_index.md
+++ b/docs/components/arm/_index.md
@@ -60,6 +60,8 @@ Supported arm models include:
| [`yahboom-dofbot`](yahboom-dofbot/) | [Yahboom DOFBOT](https://category.yahboom.net/collections/r-robotics-arm) |
| [`ur5e`](ur5e/) | [Universal Robots UR5e](https://www.universal-robots.com/products/ur5-robot) |
+Follow [this guide](/extend/modular-resources/examples/custom-arm/) to implement your custom arm as a [modular resource](/extend/modular-resources/).
+
## Control your arm with Viam's client SDK libraries
To get started using Viam's SDKs to connect to and control your robot, go to your robot's page on [the Viam app](https://app.viam.com), navigate to the **Code sample** tab, select your preferred programming language, and copy the sample code generated.
diff --git a/docs/components/board/upboard.md b/docs/components/board/upboard.md
index 86100d6d00..81338878b5 100644
--- a/docs/components/board/upboard.md
+++ b/docs/components/board/upboard.md
@@ -13,7 +13,7 @@ Configure an `upboard` board to integrate an Intel-based board like the [UP4000]
Complete the following setup requirements, then move on to configuring your board in [the Viam app](https://app.viam.com):
-## Set up requirements
+## Setup requirements
Flash your Intel-based board with:
@@ -38,10 +38,6 @@ Edit and fill in the attributes as applicable.
{{% /tab %}}
{{% tab name="JSON Template" %}}
-Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
-Click on the **Components** subtab and navigate to the **Create component** menu.
-Select **Raw JSON** mode and copy and paste the following:
-
```json {class="line-numbers linkable-line-numbers"}
{
"components": [
@@ -82,9 +78,6 @@ Select **Raw JSON** mode and copy and paste the following:
{{% /tab %}}
{{< /tabs >}}
-Save the config.
-Edit and fill in the attributes as applicable.
-
The following attributes are available for `upboard` boards:
| Name | Type | Inclusion | Description |
diff --git a/docs/components/camera/_index.md b/docs/components/camera/_index.md
index 90dafc6e33..add028230e 100644
--- a/docs/components/camera/_index.md
+++ b/docs/components/camera/_index.md
@@ -118,7 +118,7 @@ If the server does not know how to return the specified MIME type, the server re
```python {class="line-numbers linkable-line-numbers"}
my_camera = Camera.from_robot(robot=robot, name="my_camera")
-frame = await my_cam.get_image()
+frame = await my_camera.get_image()
```
@@ -200,7 +200,7 @@ The multiple images returned from GetImages do not represent a time series of im ```python {class="line-numbers linkable-line-numbers"} my_camera = Camera.from_robot(robot=robot, name="my_camera") -images, metadata = await my_cam.get_images() +images, metadata = await my_camera.get_images() img0 = images[0].image timestamp = metadata.captured_at ``` @@ -342,7 +342,7 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/c Execute model-specific commands that are not otherwise defined by the component API. For native models, model-specific commands are covered with each model's documentation. -If you are implementing your own camera and add features that have no native API method, you can access them with `DoCommand`. +If you are implementing your own camera and adding features that have no native API method, you can access them with `DoCommand`. {{< tabs >}} {{% tab name="Python" %}} diff --git a/docs/components/component/model1.md b/docs/components/component/model1.md index 5dd335d92a..14cd280dd3 100644 --- a/docs/components/component/model1.md +++ b/docs/components/component/model1.md @@ -17,10 +17,6 @@ Optional additional description/information. {{% tab name="Config Builder" %}} Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). -Click on the **Components** subtab and navigate to the **Create component** menu. - -Enter a name for your arm, select the `arm` type, and select the `model1` model. - Click on the **Components** subtab and click **Create component**. Select the `arm` type, then select the `model1` model. Enter a name for your arm and click **Create**. diff --git a/docs/components/motor/_index.md b/docs/components/motor/_index.md index 6df96e8b11..495333b7a0 100644 --- a/docs/components/motor/_index.md +++ b/docs/components/motor/_index.md @@ -41,6 +41,15 @@ Model | Description [`roboclaw`](./roboclaw/) | [Standard brushed DC motor](https://en.wikipedia.org/wiki/DC_motor) driven by [Basicmicro's](https://www.basicmicro.com/) [RoboClaw](https://www.basicmicro.com/RoboClaw-2x30A-Motor-Controller_p_9.html) motor controller [`fake`](./fake/) | Used to test code without hardware +Viam also provides the following motor models as [modular resources](/extend/modular-resources/): + + Model | Description + ----- | ----------- + [`viam:odrive:canbus`](/extend/modular-resources/examples/odrive/) | An [ODrive S1](https://odriverobotics.com/shop/odrive-s1) motor driver with CANbus communication + [`viam:odrive:serial`](/extend/modular-resources/examples/odrive/) | An [ODrive S1](https://odriverobotics.com/shop/odrive-s1) motor driver with serial communication + +These modules can be [added to your robot from the Viam registry](/extend/modular-resources/configure/#add-a-module-from-the-viam-registry). + ## Control your motor with Viam's client SDK libraries To get started using Viam's SDKs to connect to and control your robot, go to your robot's page on [the Viam app](https://app.viam.com), navigate to the **Code sample** tab, select your preferred programming language, and copy the sample code generated. diff --git a/docs/components/movement-sensor/adxl345.md b/docs/components/movement-sensor/adxl345.md index 8f01de4f43..3d0483a19a 100644 --- a/docs/components/movement-sensor/adxl345.md +++ b/docs/components/movement-sensor/adxl345.md @@ -17,10 +17,9 @@ If you are using a [Viam Rover](https://docs.viam.com/try-viam/), this is the ac {{% tab name="Config Builder" %}} Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). -Click on the **Components** subtab and navigate to the **Create component** menu. -Enter a name for your movement sensor, select the `movement-sensor` type, and select the `accel-adxl345` model. - -Click **Create Component** +Click on the **Components** subtab and click **Create component**. +Select the `movement-sensor` type, then select the `accel-adxl345` model. +Enter a name for your movement sensor and click **Create**. {{< imgproc src="/components/movement-sensor/adxl345-builder.png" alt="Creation of an `accel-adxl345` movement sensor in the Viam app config builder." resize="600x" >}} diff --git a/docs/components/movement-sensor/viam-visual-odometry.md b/docs/components/movement-sensor/viam-visual-odometry.md index 13295a7a29..7e9af1c94e 100644 --- a/docs/components/movement-sensor/viam-visual-odometry.md +++ b/docs/components/movement-sensor/viam-visual-odometry.md @@ -27,8 +27,8 @@ Therefore, you should not consider returned unit measurements trustworthy: inste While `viam-visual-odometry` enables you to add movement sensing abilities to your robot without needing specialized hardware, a dedicated [movement sensor](/components/movement-sensor/) will generally provide more accurate readings. If your robot requires precise awareness of its location and its movement, you should consider using a dedicated movement sensor in addition to the `viam-visual-odometry` module. -The `viam-visual-odometry` module is available [from the Viam Registry](https://app.viam.com/module/viam/monocular-visual-odometry). -See [Modular resources](/extend/modular-resources/#the-viam-registry) for instructions on using a module from the Viam Registry on your robot. +The `viam-visual-odometry` module is available [from the Viam registry](https://app.viam.com/module/viam/monocular-visual-odometry). +See [Modular resources](/extend/modular-resources/#the-viam-registry) for instructions on using a module from the Viam registry on your robot. The source code for this module is available on the [`viam-visual-odometry` GitHub repository](https://github.com/viamrobotics/viam-visual-odometry). diff --git a/docs/components/movement-sensor/wheeled-odometry.md b/docs/components/movement-sensor/wheeled-odometry.md index 0e7d40f571..b26ef4dced 100644 --- a/docs/components/movement-sensor/wheeled-odometry.md +++ b/docs/components/movement-sensor/wheeled-odometry.md @@ -34,7 +34,6 @@ Make sure to configure the base width and circumference, as these measurements a ## Configuration Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). -Click on the **Components** subtab and navigate to the **Create component** menu. Select **Raw JSON** mode. Copy and paste the following: diff --git a/docs/components/sensor/_index.md b/docs/components/sensor/_index.md index 3242130b95..ea75ff27bd 100644 --- a/docs/components/sensor/_index.md +++ b/docs/components/sensor/_index.md @@ -46,6 +46,14 @@ This allows you to have the same access and control of the sensor through Viam a For an example of creating a custom component, see a [WiFi strength sensor built with the Viam Go SDK](https://github.com/viam-labs/wifi-sensor/blob/main/linuxwifi/linuxwifi.go) or [custom resource types implemented with the Viam Python SDK](https://github.com/viamrobotics/viam-python-sdk/tree/main/examples/). +Viam also provides the following sensor model as a [modular resource](/extend/modular-resources/): + + Model | Description + ----- | ----------- + [`viam:visual_odometry:opencv_orb`](/extend/modular-resources/examples/odrive/) | A resource which uses monocular [visual odometry](https://en.wikipedia.org/wiki/Visual_odometry) to enable any [calibrated cameras](/components/camera/calibrate/) to function as a movement sensor + +This module can be [added to your robot from the Viam registry](/extend/modular-resources/configure/#add-a-module-from-the-viam-registry). + ## Control your sensor with Viam's client SDK libraries To get started using Viam's SDKs to connect to and control your robot, go to your robot's page on [the Viam app](https://app.viam.com), navigate to the **Code sample** tab, select your preferred programming language, and copy the sample code generated. diff --git a/docs/components/servo/pi.md b/docs/components/servo/pi.md index 6e15b6d8c1..5868d6caf6 100644 --- a/docs/components/servo/pi.md +++ b/docs/components/servo/pi.md @@ -86,11 +86,11 @@ The following attributes are available for `pi` servos: | ---- | ---- | --------- | ----------- | | `pin` | string | **Required** | The {{< glossary_tooltip term_id="pin-number" text="pin number" >}} of the pin the servo's control wire is wired to on the [board](/components/board/). | | `board` | string | **Required** | `name` of the [board](/components/board/) the servo is wired to. | -| `min` | float | Optional | The minimum angle in degrees that the servo can reach.
Default = `0.0`
Range = [`0.0`, `180.0`] | -| `max` | float | Optional | The maximum angle in degrees that the servo can reach.
Default = `180.0`
Range = [`0.0`, `180.0`] | +| `min` | float | Optional | Sets a software limit on the minimum angle in degrees your servo can rotate to.
Default = `0.0`
Range = [`0.0`, `180.0`] | +| `max` | float | Optional | Sets a software limit on the maximum angle in degrees your servo can rotate to.
Default = `180.0`
Range = [`0.0`, `180.0`] | | `starting_position_degs` | float | Optional | Starting position of the servo in degrees.
Default = `0.0`
Range = [`0.0`, `180.0`] | | `hold_position` | boolean | Optional | If `false`, power down a servo if it has tried and failed to go to a position for a duration of 500 milliseconds.
Default = `true` | -| `max_rotation_deg` | int | Optional | The maximum angle the servo can rotate. Must be in between `min` and `max`.
Default = `180` | +| `max_rotation_deg` | int | Optional | The maximum angle that you know your servo can possibly rotate to, according to its hardware. Refer to your servo's data sheet for clarification. Must be greater than or equal to the value you set for `max`.
Default = `180` | {{% alert title="Tip" color="tip" %}} diff --git a/docs/extend/_index.md b/docs/extend/_index.md index d5c618c8ab..c597873ead 100644 --- a/docs/extend/_index.md +++ b/docs/extend/_index.md @@ -6,7 +6,7 @@ simple_list: true no_list: true type: docs tags: ["server", "rdk", "extending viam", "modular resources", "components", "services"] -description: "Extend Viam with modular resources from the Viam Registry." +description: "Extend Viam with modular resources from the Viam registry." aliases: - "/program/extend/" --- diff --git a/docs/extend/custom-components-remotes.md b/docs/extend/custom-components-remotes.md index 70bcbd8332..8aea4324f5 100644 --- a/docs/extend/custom-components-remotes.md +++ b/docs/extend/custom-components-remotes.md @@ -12,10 +12,10 @@ description: "Implement custom components and register them on a server configur --- {{% alert title="Caution" color="caution" %}} -{{< glossary_tooltip term_id="module" text="Modular resources" >}} are the preferred method of creating custom resource implementations for SDKs with module support unless you are hosting `viam-server` on a non-Linux system or have another issue with compilation. +[Modular resources](/extend/modular-resources/key-concepts/) are the preferred method of creating custom resource implementations for SDKs with module support unless you are hosting `viam-server` on a non-Linux system or have another issue with compilation. {{% /alert %}} -If a type or model of [component](/components/) you are working with is not built-in to the [Viam RDK](/internals/rdk/), you can use a [Viam SDK](/program/apis/) to code a custom resource implementation, host it on a server, and add it as a [remote](/manage/parts-and-remotes/) of your robot. +If a type or model of [component](/components/) you are working with is not [built-in to the Viam RDK](/internals/rdk/), or [available from the Viam Registry as a module](/extend/modular-resources/key-concepts/), you can use a [Viam SDK](/program/apis/) to code a custom resource implementation, host it on a server, and add it as a [remote](/manage/parts-and-remotes/) of your robot. Once you have coded your custom component and configured the remote servers, you can control and monitor your component with the Viam SDKs, like any other component. diff --git a/docs/extend/modular-resources/_index.md b/docs/extend/modular-resources/_index.md index 97e28d9249..bbb60e6a2c 100644 --- a/docs/extend/modular-resources/_index.md +++ b/docs/extend/modular-resources/_index.md @@ -22,30 +22,30 @@ For example, you can: - **Implement fully custom logic:** If your robot runs specialty or proprietary logic, and you want to use Viam to manage and control that logic, such as when managing a software development lifecyle, you can implement your own custom logic by wrapping the generic API. These custom implementations are called {{< glossary_tooltip term_id="module" text="modular resources" >}}, and are made available for use on a robot through [modules](/extend/modular-resources/key-concepts/#modules). -A module can provide one or more modular resources, and can be added to your robot from the Viam Registry. +A module can provide one or more modular resources, and can be added to your robot from the Viam registry. ## The Viam Registry -The [Viam Registry](https://app.viam.com/registry) allows hardware and software engineers to collaborate on their robotics projects by writing and sharing custom modules with each other. -You can add a module from the Viam Registry directly from your robot's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **+ Create component** button. +The [Viam registry](https://app.viam.com/registry) allows hardware and software engineers to collaborate on their robotics projects by writing and sharing custom modules with each other. +You can add a module from the Viam registry directly from your robot's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **+ Create component** button. -The code behind any modular resource can be packaged as a [module](/extend/modular-resources/key-concepts/#modules) and uploaded to the Viam Registry. +The code behind any modular resource can be packaged as a [module](/extend/modular-resources/key-concepts/#modules) and uploaded to the Viam registry. Once the module has been uploaded to the Registry, you can [deploy the module](/extend/modular-resources/configure/) to any robot in your organization from [the Viam app](https://app.viam.com/). ### Uploading to Viam Registry -After you finish programming your module, you can [upload your module to the Viam Registry](/extend/modular-resources/upload/) to make it available for deployment to robots. +After you finish programming your module, you can [upload your module to the Viam registry](/extend/modular-resources/upload/) to make it available for deployment to robots. As part of the upload process, you decide whether your module is *public* (visible to all users) or *private* (visible only to other members of your [organization](/manage/fleet/organizations/)). -You can see details about each module in [the Viam Registry](https://app.viam.com/registry) on its module details page. +You can see details about each module in the [Viam registry](https://app.viam.com/registry) on its module details page. See the [Odrive module](https://app.viam.com/module/viam/odrive) for an example. Public modules also display the number of times a module has been deployed to a robot. -When you make changes to your module, you can [uploaded the newer version](/extend/modular-resources/upload/#update-an-existing-module) with a new version number, and the Viam Registry will track each version that you upload. +When you make changes to your module, you can [uploaded the newer version](/extend/modular-resources/upload/#update-an-existing-module) with a new version number, and the Viam registry will track each version that you upload. ### Deploying to a Robot -Once you [upload a module to the Viam Registry](/extend/modular-resources/upload/), you can [deploy the module](/extend/modular-resources/configure/) to any robot in your organization from [the Viam app](https://app.viam.com/). +Once you [upload a module to the Viam registry](/extend/modular-resources/upload/), you can [deploy the module](/extend/modular-resources/configure/) to any robot in your organization from [the Viam app](https://app.viam.com/). Navigate to your robot's **Configuration** tab, click the **+ Create component** button, then start typing the name of the module you would like to deploy. If you uploaded your module and set its visibility to private, the module will only appear for users within your [organization](/manage/fleet/organizations/). @@ -59,9 +59,9 @@ To get started working with modular resources: - [Create your own module](/extend/modular-resources/create/) implementing at least one modular resource. -- [Upload your module to the Viam Registry](/extend/modular-resources/upload/) to share with the community, or just to your own organization. +- [Upload your module to the Viam registry](/extend/modular-resources/upload/) to share with the community, or just to your own organization. -- Browse [the Viam Registry](https://app.viam.com/registry) to see modules uploaded by other users. +- Browse the [Viam registry](https://app.viam.com/registry) to see modules uploaded by other users. - [Deploy a module](/extend/modular-resources/configure/) to your robot from the Registry. diff --git a/docs/extend/modular-resources/configure.md b/docs/extend/modular-resources/configure.md index 4ead43ea07..1d7a73dc4d 100644 --- a/docs/extend/modular-resources/configure.md +++ b/docs/extend/modular-resources/configure.md @@ -4,87 +4,121 @@ linkTitle: "Configure" weight: 30 type: "docs" tags: ["server", "rdk", "extending viam", "modular resources", "components", "services"] -description: "Add and configure a module from the Viam Registry on your robot." +description: "Add and configure a module from the Viam registry on your robot." no_list: true --- -You can extend Viam by adding a module on your robot to make one or more modular resources available for configuration. -You can [add a module from the Viam Registry](#add-a-module-from-the-viam-registry), or you can [code your own module and add it to your robot locally](#add-a-local-module-to-your-robot). +You can extend Viam by adding a module on your robot that provides one or more {{< glossary_tooltip term_id="resource" text="modular resources" >}} ([components](/components/) or [services](/services/)). +You can [add a module from the Viam registry](#add-a-module-from-the-viam-registry), or you can [code your own module and add it to your robot locally](#add-a-local-module-to-your-robot). -A *module* makes one or more *modular resources* available for configuration. See [Key Concepts of Modular Resource APIs](/extend/modular-resources/key-concepts/) for more information. -## Add a module from the Viam Registry +## Add a module from the Viam registry -The Viam Registry is a central repository of modules from both Viam and the robotics community that allows you to easily extend Viam's capabilities on your robot. +The [Viam registry](https://app.viam.com/registry) is a central repository of modules from both Viam and the robotics community that allows you to easily extend Viam's capabilities on your robot. -To add a module from the Viam Registry to your robot: +A module provides one or more {{< glossary_tooltip term_id="resource" text="modular resources" >}} (either a [component](/components/) or [service](/services/)). + +Follow the instructions below depending on the type of modular resource you would like to add to your robot: + +- [Add a modular component](#add-a-modular-component-from-the-viam-registry) +- [Add a modular service](#add-a-modular-service-from-the-viam-registry) + +### Add a modular component from the Viam registry + +To add a modular [component](/components/) from the Viam registry to your robot: 1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). 1. Click on the **Components** subtab and click the **Create component** button. -1. Enter the name of the module you would like to add to your robot. - To find the name of a module you're interested in, you can: +1. Browse the list of available component types, and select the specific modular component you'd like to add. + + {{}}
+
+ You can also start typing to search for a module by name or to narrow down your search results.
- - Start typing to search for modules by name.
- Modules available from the Viam Registry will be listed under the `From Registry` section of the search results.
- - [Browse the Viam Registry](https://app.viam.com/modules) directly to search available modules.
+ {{}}
- {{}}
+1. After selecting the modular component, click the **Add module** button, enter a name for your modular component, and click **Create** to add it to your robot.
-1. After entering the name of the module that you would like to add to your robot, select the matching module in the search results and click the **Add module** button.
+ {{}}
-When you add a module from the Viam Registry, the custom modular component it provides appears under the **Components** subtab like any other component.
+When you add a module from the Viam registry, the custom modular component it provides appears under the **Components** subtab like any other component.
You can also find [the module itself](#configure-a-module-from-the-viam-registry) listed as **Deployed** under the **Modules** subtab.
-{{}}
+If the module requires you to configure specific **Attributes**, click the **URL** link in the [module's configuration pane](#configure-a-module-from-the-viam-registry) to view the specific attribute requirements on the module's GitHub page.
+
+To delete a module added from the Viam registry, click the trash can icon in the upper-right corner of the module configuration pane in the **Components** tab.
+Deleting a module *does not* delete any configured modular resources it provides.
+
+### Add a modular service from the Viam registry
+
+To add a modular [service](/services/) from the Viam registry to your robot:
+
+1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
+1. Click on the **Services** subtab and click the **Create service** button.
+1. Browse the list of available service types and select the specific modular service you'd like to add.
+
+ {{}}
+
+ You can also start typing to search for a module by name or to narrow down your search results.
+
+ {{}}
-If the module requires you to configure specific **Atrributes**, click the **URL** link in the module's configuration pane to view the specific documentation on the module's GitHub page.
+1. After selecting the modular service, click the **Add module** button, enter a name for your modular service, and click **Create** to add it to your robot.
+
+ {{}}
+
+When you add a module from the Viam registry, the custom modular service it provides appears under the **Services** subtab like any other service.
+You can also find [the module itself](#configure-a-module-from-the-viam-registry) listed as **Deployed** under the **Modules** subtab.
-To delete a module added from the Viam Registry, click the trash can icon in the upper-right corner of the module configuration pane in the **Components** tab.
+If the module requires you to configure specific **Attributes**, click the **URL** link in the [module's configuration pane](#configure-a-module-from-the-viam-registry) to view the specific attribute requirements on the module's GitHub page.
-### Configure a module from the Viam Registry
+To delete a module added from the Viam registry, click the trash can icon in the upper-right corner of the module configuration pane in the **Services** tab.
+Deleting a module *does not* delete any configured modular resources it provides.
-Once you have added a module from the Viam Registry, you can view and configure the module from the **Modules** subtab:
+## Configure a module from the Viam registry
+
+Once you have added a modular resource to your robot, you can view and configure the module itself from the **Modules** subtab:
1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
1. Click on the **Modules** subtab.
All modules you have added to your robot appear under the **Deployed** section.
-This pane lists the models provided by the module, any [components](/components/) on your robot that are currently using those models, and allows you to configure [how the module updates](#configure-version-update-management-for-a-registry-module) when a new version is available from the Viam Registry.
+This pane lists the models provided by the module, any [components](/components/) or [services](/services/) on your robot that are currently using the module, and allows you to configure [how the module updates](#configure-version-update-management-for-a-registry-module) when a new version is available from the Viam registry.
-{{}}
+{{}}
-#### Configure version update management for a Registry module
+### Configure version update management for a Registry module
-When you add a module to your robot, you can also configure how that module updates itself when a newer version becomes available from the Viam Registry.
+When you add a module to your robot, you can also configure how that module updates itself when a newer version becomes available from the Viam registry.
By default, a newly-added module is set to pin to the specific patch release (**Patch (X.Y.Z)**) of the version you added, meaning that the module will *never automatically update itself*.
-If you wish to allow automatic module updates when a new version of the module becomes available in the Viam Registry, you can set the **Version type** for your module in the **Modules** subtab.
+If you wish to allow automatic module updates when a new version of the module becomes available in the Viam registry, you can set the **Version type** for your module in the **Modules** subtab.
Updating to a newer version of a module brings new functionality and bug fixes, but requires restarting the module to apply the update.
The following update options are available:
- **Patch (X.Y.Z)**: Do not update to any other version.
This is the default.
- **Minor (X.Y.*)**: Only update to newer patch releases of the same minor release branch.
- The module will automatically restart and update itself whenever new updates within the same minor release are available in the Viam Registry.
+ The module will automatically restart and update itself whenever new updates within the same minor release are available in the Viam registry.
For example, use this option to permit a module with version `1.2.3` to update to version `1.2.4` or `1.2.5` but not `1.3.0` or `2.0.0`.
- **Major (X.*)**: Only update to newer minor releases of the same major release branch.
- The module will automatically restart and update itself whenever new updates within the same major release are available in the Viam Registry.
+ The module will automatically restart and update itself whenever new updates within the same major release are available in the Viam registry.
For example, use this option to permit a module with version `1.2.3` to update to version `1.2.4` or `1.3.0` but not `2.0.0` or `3.0.0`.
-- **Latest**: Always update to the latest version of this module available from the Viam Registry as soon as a new version becomes available.
+- **Latest**: Always update to the latest version of this module available from the Viam registry as soon as a new version becomes available.
When using the **Patch (X.Y.Z)** version type, you may select any patch version of the module from the **Version** drop down menu, including past versions if desired.
-The current deployed version of your module and the latest version of that module available from the Viam Registry are shown on this pane for your reference.
+The current deployed version of your module and the latest version of that module available from the Viam registry are shown on this pane for your reference.
{{% alert title="Caution" color="caution" %}}
For any version type other than **Patch (X.Y.Z)**, the module will upgrade as soon as an update that matches that specified version type is available, which will **restart the module**.
If, for example, the module provides a motor component, and the motor is running, it will stop while the module upgrades.
{{% /alert %}}
-### Configure a modular resource from a Registry module
+### Create a new modular resource from a Registry module
-Once you have configured a module from the Viam Registry, you can add any number of the resources that the module makes available to your robot by adding new components or services configured with your modular resources' [model](/extend/modular-resources/key-concepts/#models).
+Once you have [added a module](#add-a-module-from-the-viam-registry) from the Viam registry, you can add any number of the modular resources it provides to your robot by adding new components or services configured with your modular resources' [model](/extend/modular-resources/key-concepts/#models).
The following properties are available for modular resources:
@@ -98,6 +132,7 @@ The following properties are available for modular resources:
All standard properties for configuration, such as `attributes` and `depends_on`, are also supported for modular resources.
The `attributes` available vary depending on your implementation.
+If the module requires you to configure specific **Attributes**, click the **URL** link in the module's configuration pane to view the specific attribute requirements on the module's GitHub page.
{{< tabs >}}
{{% tab name="JSON Template" %}}
@@ -106,47 +141,51 @@ The `attributes` available vary depending on your implementation.
{
"components": [
{
- "namespace": "",
- "type": "",
- "model": "::",
"name": "",
- "depends_on": [],
+ "model": "::",
+ "type": "",
+ "namespace": "",
+ "attributes": {},
+ "depends_on": []
}
],
- "modules": [ ... ] // < INSERT YOUR MODULE CONFIGURATION >
+ "modules": [
+ {
+ "type": "registry",
+ "name": "",
+ "module_id": ":",
+ "version": ""
+ }
+ ]
}
```
{{% /tab %}}
{{% tab name="JSON Example" %}}
-The following is an example configuration for a base modular resource implementation.
-The configuration adds `acme:demo:mybase` as a modular resource from the module `my_base`.
-The custom model is configured as a component with the name "my-custom-base-1".
-You can send commands to the base according to the Viam [base API](/components/base/#api):
+The following is an example configuration for for the [Intel Realsense module](https://app.viam.com/module/viam/realsense).
+The configuration adds `viam:camera:realsense` as a modular resource from the module `viam:realsense`.
+The custom model is configured as a component with the name "my-realsense".
```json {class="line-numbers linkable-line-numbers"}
{
"components": [
- {
- "type": "board",
- "name": "main-board",
- "model": "pi"
- },
- {
- "type": "base",
- "name": "my-custom-base-1",
- "model": "acme:demo:mybase",
- "namespace": "rdk",
- "attributes": {},
- "depends_on": [ "main-board" ]
- }
- ],
- "modules": [
- {
- "name": "my-custom-base",
- "executable_path": "/home/my_username/my_base/run.sh"
- }
+ {
+ "name": "my-realsense",
+ "model": "viam:camera:realsense",
+ "type": "camera",
+ "namespace": "rdk",
+ "attributes": {},
+ "depends_on": []
+ }
+ ],
+ "modules": [
+ {
+ "type": "registry",
+ "name": "viam_realsense",
+ "module_id": "viam:realsense",
+ "version": "0.0.3"
+ }
]
}
```
@@ -240,7 +279,8 @@ The `attributes` available vary depending on your implementation.
"type": "",
"model": "::",
"name": "",
- "depends_on": [],
+ "attributes": {},
+ "depends_on": []
}
],
"modules": [ ... ] // < INSERT YOUR MODULE CONFIGURATION >
diff --git a/docs/extend/modular-resources/create/_index.md b/docs/extend/modular-resources/create/_index.md
index cebdbf2d43..21c314a38a 100644
--- a/docs/extend/modular-resources/create/_index.md
+++ b/docs/extend/modular-resources/create/_index.md
@@ -12,9 +12,9 @@ You can extend Viam by creating a custom [module](/extend/modular-resources/key-
A common use case for modular resources is to create a new model that implements an existing Viam API.
-Once you have created your modular resource, you can use the [Viam CLI](/manage/cli/) to [upload your modular resource](/extend/modular-resources/upload/) to the Viam Registry, to share it with other Viam users or just to other users in your organization.
+Once you have created your modular resource, you can use the [Viam CLI](/manage/cli/) to [upload your modular resource](/extend/modular-resources/upload/) to the Viam registry, to share it with other Viam users or just to other users in your organization.
-Alternatively, you can add your module locally to your robot without uploading to the Viam Registry.
+Alternatively, you can add your module locally to your robot without uploading to the Viam registry.
## Create a custom module
@@ -533,6 +533,6 @@ Your executable will be run by `viam-server` as root, so dependencies need to be
## Next steps
-Once you have created your custom resource, you can use the [Viam CLI](/manage/cli/) to [upload your custom resource](/extend/modular-resources/upload/) to the Viam Registry, to share it with other Viam users or just to other users in your organization.
+Once you have created your custom resource, you can use the [Viam CLI](/manage/cli/) to [upload your custom resource](/extend/modular-resources/upload/) to the Viam registry, to share it with other Viam users or just to other users in your organization.
-Alternatively, you can [add your module locally](/extend/modular-resources/configure/) to your robot without uploading to the Viam Registry.
+Alternatively, you can [add your module locally](/extend/modular-resources/configure/) to your robot without uploading to the Viam registry.
diff --git a/docs/extend/modular-resources/examples/csi.md b/docs/extend/modular-resources/examples/csi.md
index c0e15f8cec..78fe6d6042 100644
--- a/docs/extend/modular-resources/examples/csi.md
+++ b/docs/extend/modular-resources/examples/csi.md
@@ -8,7 +8,6 @@ tags: ["board", "csi", "jetson", "serial", "module", "modular resources", "Pytho
# SMEs: Sean
---
-
Many boards, like the Jetson Orin Nano, come with the option to use Camera Serial Interface (CSI) cameras, like [these cameras from E-con Systems](https://www.e-consystems.com/nvidia-jetson-agx-orin-cameras.asp) or [this camera from Seed Technologies](https://www.digikey.com/en/products/detail/seeed-technology-co.,-ltd/114992263/12396924).
These cameras are excellent for utilizing embedded vision systems like Viam's [vision service](/services/vision/).
Not all CSI cameras are supported by the [webcam camera model](/components/camera/webcam/).
@@ -22,7 +21,7 @@ To use the CSI camera module, follow the [installation](#installation) and [conf
## Installation
-On your robot's computer, download [the `viam:camera:csi` appimage](https://github.com/viamrobotics/odrive) and make it executable:
+On your robot's computer, download [the `viam:camera:csi` appimage](https://github.com/seanavery/viam-csi) and make it executable:
``` {class="command-line" data-prompt="$"}
sudo wget https://github.com/seanavery/viam-csi/releases/download/v0.0.2/viam-csi-0.0.2-aarch64.AppImage -O /usr/local/bin/viam-csi
@@ -32,6 +31,32 @@ sudo chmod 755 /usr/local/bin/viam-csi
## Configuration
{{< tabs name="Connect your CSI Module and Modular Resource">}}
+{{% tab name="Config Builder" %}}
+
+Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
+
+Click on the **Modules** subtab and navigate to the **Local** section.
+Enter a name, for example `my_csi_cam_module_name`, then enter the executable path.
+If you used the above install command, the executable path should be: `/usr/local/bin/viam-csi`.
+Then click **Add module**.
+
+Click on the **Components** subtab and click **Create component**.
+Select the `local modular resource` type.
+Then select `camera` as the type, enter the triplet `viam:camera:csi`, and give your resource a name, for example `my_test_csi_cam`.
+Click **Create**.
+
+On the new component panel, copy and paste the following JSON object into the attributes field:
+
+```json
+{
+ "width_px": ,
+ "height_px": ,
+ "frame_rate": ,
+ "debug": ""
+}
+```
+
+{{% /tab %}}
{{% tab name="JSON Template" %}}
Go to your robot's page on the [Viam app](https://app.viam.com/).
@@ -39,33 +64,30 @@ Navigate to the **Config** tab on your robot's page and select **Raw JSON** mode
Copy and paste the JSON object for the module into the modules array to add Viam's `csi-mr` module:
-```json {class="line-numbers linkable-line-numbers"}
+```json
{
- "modules": [
- {
- "executable_path": "",
- "name": ""
- }
- ]
+ "executable_path": "",
+ "name": "",
+ "type": "local"
}
```
Next, add the following JSON object to your components array to configure a `csi` [camera](/components/camera/) component with the name `my_test_csi_cam`:
```json {class="line-numbers linkable-line-numbers"}
- {
- "model": "viam:camera:csi",
- "attributes": {
- "width_px": ,
- "height_px": ,
- "frame_rate": ,
- "debug": ""
- },
- "depends_on": [],
- "name": "",
- "namespace": "rdk",
- "type": "camera"
- }
+{
+ "model": "viam:camera:csi",
+ "attributes": {
+ "width_px": ,
+ "height_px": ,
+ "frame_rate": ,
+ "debug": ""
+ },
+ "depends_on": [],
+ "name": "",
+ "namespace": "rdk",
+ "type": "camera"
+}
```
{{% /tab %}}
@@ -76,7 +98,8 @@ Next, add the following JSON object to your components array to configure a `csi
"modules": [
{
"executable_path": "/usr/bin/csi-mr",
- "name": "csi_cam_module"
+ "name": "csi_cam_module",
+ "type": "local"
}
],
"components": [
@@ -100,10 +123,7 @@ Next, add the following JSON object to your components array to configure a `csi
{{% /tab %}}
{{< /tabs >}}
-Save the config.
-Edit and fill in the attributes as applicable.
-
-Check the [**Logs** tab](/program/debug/) of your robot in the Viam app to make sure your camera has connected and no errors are being raised.
+Edit and fill in the attributes to configure your component.
The following attributes are available for the `viam:camera:csi` model:
@@ -114,3 +134,7 @@ The following attributes are available for the `viam:camera:csi` model:
| `frame_rate` | int | Optional | The image capture frame rate this camera should use.
Default: `30` | | `video_path` | string | Optional | The filepath to the input sensor of this camera on your board. If none is given, your robot will attempt to detect the video path automatically.
Default: `"0"` | | `debug` | boolean | Optional | Whether or not you want debug input from this camera in your robot's logs.
Default: `false` | + +Then, save the config. + +Check the [**Logs** tab](/program/debug/) of your robot in the Viam app to make sure your camera has connected and no errors are being raised. diff --git a/docs/extend/modular-resources/examples/odrive.md b/docs/extend/modular-resources/examples/odrive.md index 7528327be6..4675a5ea90 100644 --- a/docs/extend/modular-resources/examples/odrive.md +++ b/docs/extend/modular-resources/examples/odrive.md @@ -3,7 +3,7 @@ title: "Add an ODrive motor as a Modular Resource" linkTitle: "ODrive" weight: 40 type: "docs" -description: "How to add an ODrive motor with serial or CANbus communication as a modular resource of your robot." +description: "Configure an ODrive motor with serial or CANbus communication as a modular resource of your robot." tags: ["motor", "odrive", "canbus", "serial", "module", "modular resources", "Python", "python SDK", "CAN"] # SMEs: Kim, Martha, Rand --- @@ -35,7 +35,7 @@ pip3 install python-can cantools viam-sdk Follow [these instructions](https://docs.odriverobotics.com/v/latest/odrivetool.html) to install `odrivetool`. -Find and copy the path (either absolute, or relative to the working directory) to the executable module file `run.sh` on your robot's computer to provide when [configuring the module](#module). +Find and copy the path (either absolute, or relative to the working directory) to the executable module file `run.sh` on your robot's computer to provide when [configuring the module](#configuration). {{% alert title="Tip" color="tip" %}} @@ -52,7 +52,7 @@ pwd 1. Read through the [ODrive documentation](https://docs.odriverobotics.com/v/latest/getting-started.html) to wire, calibrate, and configure your ODrive natively. -{{% alert title="Tip" color="tip" %}} + {{% alert title="Tip" color="tip" %}} This configuration remains on the same ODrive motor controller across reboots, and only changes when you go through the configuration of the ODrive again. @@ -62,26 +62,26 @@ See [add an `odrive_config_file`](#add-an-odrive_config_file) for more informati This option is not recommend for the `canbus` model. -{{% /alert %}} + {{% /alert %}} -Note that `iq_msg_rate_ms` in the `odrive_config_file` defaults to `0`, and you must set this to or around `100` to use the [motor API's `SetPower` method](https://docs.viam.com/components/motor/#setpower). + Note that `iq_msg_rate_ms` in the `odrive_config_file` defaults to `0`, and you must set this to or around `100` to use the [motor API's `SetPower` method](https://docs.viam.com/components/motor/#setpower). 2. Follow [this guide](https://docs.odriverobotics.com/v/latest/control.html#control-doc) to tune your ODrive motor. 3. See the [ODrive CAN documentation](https://docs.odriverobotics.com/v/latest/can-guide.html) for detailed information on how to set up CAN on your ODrive. -{{% alert title="Tip" color="tip" %}} + {{% alert title="Tip" color="tip" %}} If you are using a Raspberry Pi as your [board](/components/board/), you must run `sudo ip link set can0 up type can bitrate` in your terminal to receive CAN messages.
See "[Troubleshooting](#troubleshooting): [CAN Link Issues](https://github.com/viamrobotics/odrive#can-link-issues)" for more information.
Additionally, make sure you have [enabled SPI communication on your Pi](/installation/prepare/rpi-setup/) to use several common CANHats.
-{{% /alert %}}
+ {{% /alert %}}
4. Make sure your ODrive is connected to your [board](/components/board/) as follows, depending on your preferred connection method:
-{{< tabs name="Connect your ODrive">}}
+ {{< tabs name="Connect your ODrive">}}
{{% tab name="serial" %}}
Plug the [USB Isolator for Odrive](https://odriverobotics.com/shop/usb-c-to-usb-a-cable-and-usb-isolator) into a USB port on your board.
@@ -93,62 +93,69 @@ Plug a USB-C to USB-A cable from the isolator to the ODrive.
Wire the CANH and CANL pins from your board to your ODrive.
Refer to your board and the [ODrive's pinout](https://docs.odriverobotics.com/v/latest/pinout.html) diagrams for the location of these pins.
-You must make a serial connection to set up your ODrive. If CAN chains together multiple ODrives, only one at a time must have this serial connection for reconfiguration
+You must make a serial connection to set up your ODrive.
+If CAN chains together multiple ODrives, only one at a time must have this serial connection for reconfiguration
After setting up the ODrive, if you wish to use the `canbus` model, you can either leave the serial connection plugged in or remove it and leave only the CANH and CANL pins wired.
Note that if you want to only use the CAN pins, you cannot specify an `"odrive_config_file"` in your Viam configuration.
The ODrive would not be able to make the serial connection it needs to perform reconfiguration.
{{% /tab %}}
-{{< /tabs >}}
+ {{< /tabs >}}
-After preparing your ODrive, configure the module to configure `serial` or `canbus` model motors on your robot.
+ After preparing your ODrive, configure the module to configure `serial` or `canbus` model motors on your robot.
## Configuration
-### Module
-
-{{< tabs name="Add the ODrive module">}}
+{{< tabs name="Connect your Odrive Module and Modular Resource">}}
{{% tab name="Config Builder" %}}
-Go to your robot's page on the [Viam app](https://app.viam.com/).
-Navigate to the **Config** tab on your robot's page, and click on the **Modules** subtab.
+Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
-Add the ODrive module with a name of your choice and an `"executable_path"` that points to the location where your ODrive module’s run script, run.sh , is stored on your robot’s computer.
+Click on the **Modules** subtab and navigate to the **Local** section.
+Enter a name, for example `my_odrive_motor`, and the executable path, that points to the location where your ODrive module’s run script, run.sh , is stored on your robot’s computer.
+Then click **Add module**.
-{{% /tab %}}
-{{% tab name="JSON Template" %}}
+Click on the **Components** subtab and click **Create component**.
+Select the `local modular resource` type.
+Then select `motor` as the type, enter the triplet `viam:odrive:serial`, and give your resource a name, for example `my_test_odrive`.
+Click **Create**.
+
+On the new component panel, copy and paste the following JSON object into the attributes field:
```json {class="line-numbers linkable-line-numbers"}
-"modules": [
- {
- "name": "odrive",
- "executable_path": ""
- }
-]
+{
+ "width_px": ,
+ "height_px": ,
+ "frame_rate": ,
+ "debug": ""
+}
```
{{% /tab %}}
-{{< /tabs >}}
+{{% tab name="JSON Template" %}}
-### Modular Resource
+ Navigate to the **Config** tab.
+ Select the **Raw JSON** mode.
-Go to your robot's page on the [Viam app](https://app.viam.com/).
-Navigate to the **Config** tab on your robot's page, and click on the **Components** subtab.
-Select **Raw JSON** mode.
+ To add the module, copy and paste the JSON object into the `"modules"` array:
-Copy and paste the following JSON along with your module JSON depending on your preferred communication type:
+ ```json {class="line-numbers linkable-line-numbers"}
+ {
+ "name": "odrive",
+ "executable_path": ""
+ }
+ ```
-{{< tabs name="Add an ODrive motor">}}
-{{% tab name="serial" %}}
+ To add the modular resource from the module, copy and paste the JSON object into the `"components"` array:
-```json {class="line-numbers linkable-line-numbers"}
-{
- // "modules": [ {"name": "odrive" ... } ] MODULE JSON
- "components": [
- {
+ {{< tabs name="Add an ODrive motor">}}
+ {{% tab name="serial" %}}
+
+ ```json {class="line-numbers linkable-line-numbers"}
+ {
"model": "viam:odrive:serial",
"namespace": "rdk",
"attributes": {
@@ -156,19 +163,14 @@ Copy and paste the following JSON along with your module JSON depending on your
"depends_on": [],
"type": "motor",
"name": ""
- }
- ]
-}
-```
+ }
+ ```
-{{% /tab %}}
-{{% tab name="canbus" %}}
+ {{% /tab %}}
+ {{% tab name="canbus" %}}
-```json {class="line-numbers linkable-line-numbers"}
-{
- // "modules": [ {"name": "odrive" ... } ] MODULE JSON
- "components": [
- {
+ ```json {class="line-numbers linkable-line-numbers"}
+ {
"model": "viam:odrive:canbus",
"namespace": "rdk",
"attributes": {
@@ -177,10 +179,11 @@ Copy and paste the following JSON along with your module JSON depending on your
"depends_on": [],
"type": "motor",
"name": ""
- }
- ]
-}
-```
+ }
+ ```
+
+ {{% /tab %}}
+ {{< /tabs >}}
{{% /tab %}}
{{% tab name="JSON Example" %}}
@@ -222,11 +225,11 @@ Copy and paste the following JSON along with your module JSON depending on your
}
```
-Edit and fill in the attributes as applicable to your model of ODrive.
-
{{% /tab %}}
{{< /tabs >}}
+Edit and fill in the attributes as applicable to your model of ODrive.
+
The following attributes are available for the motor resources available in the Viam ODrive module:
| Name | Type | Inclusion | Description |
@@ -245,7 +248,7 @@ The `"canbus"` type allows you to connect multiple ODrives without providing a `
{{% /alert %}}
-#### Add an `odrive_config_file`
+### Add an `odrive_config_file`
To add an `odrive_config_file` and reconfigure your ODrive natively each time the motor is initialized on the robot, use [`odrivetool`](https://docs.odriverobotics.com/v/latest/odrivetool.html) to extract your configuration from your ODrive:
diff --git a/docs/extend/modular-resources/examples/rplidar.md b/docs/extend/modular-resources/examples/rplidar.md
index e8962623ea..df119760d7 100644
--- a/docs/extend/modular-resources/examples/rplidar.md
+++ b/docs/extend/modular-resources/examples/rplidar.md
@@ -3,11 +3,12 @@ title: "Add an RPlidar as a Modular Resource"
linkTitle: "RPlidar"
weight: 40
type: "docs"
-description: "How to add an RPlidar as a modular resource of your robot."
+description: "Configure an RPlidar camera as a modular resource of your robot."
image: "/program/modular-resources/rplidar-on-robot.png"
imageAlt: "An R-P-lidar mounted to a Viam rover."
images: ["/program/modular-resources/rplidar-on-robot.png"]
tags: ["slam", "services", "modular resources", "lidar", "rplidar"]
+no_list: true
aliases:
- "/program/extend/modular-resources/add-rplidar-module/"
- "/program/extend/modular-resources/examples/add-rplidar-module/"
@@ -55,101 +56,176 @@ For example, if you are using the [RPlidar A1](https://www.slamtec.com/en/Lidar/
Then, go to your robot's page on the [Viam app](https://app.viam.com/).
{{< tabs name="Add the RPlidar component">}}
+{{% tab name="Config Builder" %}}
+
+Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
+
+ {{< tabs name="Add the RPlidar component - configs" >}}
+ {{% tab name="Linux" %}}
+
+Click on the **Modules** subtab and navigate to the **Local** section.
+Enter a name, for example `my_rplidar_module_name`, and the executable path `/usr/bin/csi-mr`.
+Then click **Add module**.
+
+Click on the **Components** subtab and click **Create component**.
+Select the `local modular resources` type.
+Then select the `camera` as the type, enter the triplet `viam:lidar:rplidar` and give your resource a name, for example `rplidar`.
+Click **Create**.
+
+ {{% /tab %}}
+ {{% tab name="macOS x86_64" %}}
+
+Click on the **Modules** subtab and navigate to the **Local** section.
+Enter a name, for example `my_rplidar_module_name`, and the executable path `/usr/bin/csi-mr`.
+Then click **Add module**.
+
+Click on the **Components** subtab and click **Create component**.
+Select the `local modular resources` type.
+Then select the `camera` as the type, enter the triplet `viam:lidar:rplidar` and give your resource a name, for example `rplidar`.
+Click **Create**.
+
+On the new component panel, copy and paste the following JSON object into the attributes field:
+
+```json
+{
+ "device_path": "/dev/tty.SLAB_USBtoUART"
+}
+```
+
+ {{% /tab %}}
+ {{% tab name="macOS ARM64 (M1 & M2)" %}}
+
+Click on the **Modules** subtab and navigate to the **Local** section.
+Enter a name, for example `my_rplidar_module_name`, and the executable path `/opt/homebrew/bin/rplidar-module`.
+Then click **Add module**.
+
+Click on the **Components** subtab and click **Create component**.
+Select the `local modular resources` type.
+Then select the `camera` as the type, enter the triplet `viam:lidar:rplidar` and give your resource a name, for example `rplidar`.
+Click **Create**.
+
+On the new component panel, copy and paste the following JSON object into the attributes field:
+
+```json
+{
+ "device_path": "/dev/tty.usbserial-XXX"
+}
+```
+
+If you are on an M1 or M2 Macbook, determine the device path by running the following command:
+
+```sh {class="command-line" data-prompt="$"}
+ls /dev/ | grep tty.usbserial
+```
+
+For example, you may see `tty.usbserial-130`, in which case your device path would be `/dev/tty.usbserial-130`.
+Replace the `XXX` at the end of the `device_path` value in the attributes configuration with the number at the end of your device path.
+
+ {{% /tab %}}
+ {{< /tabs >}}
+
+{{% /tab %}}
{{% tab name="JSON Template" %}}
Navigate to the **Config** tab.
-Select the **Raw JSON** mode, then copy/paste the following `"components"` and `"modules"` JSON:
+
+Select the **Raw JSON** mode.
{{< tabs name="Add the RPlidar component - configs" >}}
{{% tab name="Linux" %}}
+ Copy and paste the JSON object for the module into the modules array to add the module:
+
+ ```json
+ {
+ "executable_path": "/usr/local/bin/rplidar-module",
+ "name": "my_rplidar_module_name"
+ }
+ ```
+
+ Next, add the following JSON object to your components array to configure a `rplidar` [camera](/components/camera/) component with the name `rplidar`:
+
```json
{
- "modules": [
- {
- "executable_path": "/usr/local/bin/rplidar-module",
- "name": "rplidar-module"
- }
- ],
- "components": [
- {
- "namespace": "rdk",
- "type": "camera",
- "depends_on": [],
- "model": "viam:lidar:rplidar",
- "name": "rplidar"
- }
- ]
+ "namespace": "rdk",
+ "type": "camera",
+ "depends_on": [],
+ "model": "viam:lidar:rplidar",
+ "name": "rplidar"
}
```
{{% /tab %}}
{{% tab name="macOS x86_64" %}}
+ Copy and paste the JSON object for the module into the modules array to add the module:
+
+ ```json
+ {
+ "executable_path": "/usr/local/bin/rplidar-module",
+ "name": "my_rplidar_module_name"
+ }
+ ```
+
+ Next, add the following JSON object to your components array to configure a `rplidar` [camera](/components/camera/) component with the name `rplidar`:
+
```json
{
- "modules": [
- {
- "executable_path": "/usr/local/bin/rplidar-module",
- "name": "rplidar-module"
- }
- ],
- "components": [
- {
- "namespace": "rdk",
- "type": "camera",
- "depends_on": [],
- "model": "viam:lidar:rplidar",
- "attributes": {
- "device_path": "/dev/tty.SLAB_USBtoUART"
- },
- "name": "rplidar"
- }
- ]
+ "namespace": "rdk",
+ "type": "camera",
+ "depends_on": [],
+ "model": "viam:lidar:rplidar",
+ "attributes": {
+ "device_path": "/dev/tty.SLAB_USBtoUART"
+ },
+ "name": "rplidar"
}
```
{{% /tab %}}
{{% tab name="macOS ARM64 (M1 & M2)" %}}
-If you are on an M1 or M2 Macbook, determine the device path by running the following command:
+ Copy and paste the JSON object for the module into the modules array to add the module:
-```sh {class="command-line" data-prompt="$"}
-ls /dev/ | grep tty.usbserial
-```
+ ```json
+ {
+ "executable_path": "/usr/local/bin/rplidar-module",
+ "name": "my_rplidar_module_name"
+ }
+ ```
-For example, you may see `tty.usbserial-130`, in which case your device path would be `/dev/tty.usbserial-130`.
-Use the device path in your configuration:
+ Next, add the following JSON object to your components array to configure a `rplidar` [camera](/components/camera/) component with the name `rplidar`:
```json
{
- "modules": [
- {
- "executable_path": "/opt/homebrew/bin/rplidar-module",
- "name": "rplidar-module"
- }
- ],
- "components": [
- {
- "namespace": "rdk",
- "type": "camera",
- "depends_on": [],
- "model": "viam:lidar:rplidar",
- "attributes": {
- "device_path": "/dev/tty.usbserial-XXX"
- },
- "name": "rplidar"
- }
- ]
+ "namespace": "rdk",
+ "type": "camera",
+ "depends_on": [],
+ "model": "viam:lidar:rplidar",
+ "attributes": {
+ "device_path": "/dev/tty.usbserial-XXX"
+ },
+ "name": "rplidar"
}
```
+ If you are on an M1 or M2 Macbook, determine the device path by running the following command:
+
+ ```sh {class="command-line" data-prompt="$"}
+ ls /dev/ | grep tty.usbserial
+ ```
+
+ For example, you may see `tty.usbserial-130`, in which case your device path would be `/dev/tty.usbserial-130`.
+ Replace the `XXX` at the end of the `device_path` value in the attributes configuration with the number at the end of your device path.
+
{{% /tab %}}
{{< /tabs >}}
{{% /tab %}}
{{< /tabs >}}
+Then, save the config.
+
Check the **Logs** tab of your robot in the Viam app to make sure your RPlidar has connected and no errors are being raised.
## Troubleshooting
diff --git a/docs/extend/modular-resources/examples/tflite-module.md b/docs/extend/modular-resources/examples/tflite-module.md
index d2b97dbb4d..4163fe4022 100644
--- a/docs/extend/modular-resources/examples/tflite-module.md
+++ b/docs/extend/modular-resources/examples/tflite-module.md
@@ -228,7 +228,12 @@ To generate your robot's configuration using `example_audio_classification_clien
```
1. Copy the contents of this file.
- Then return to your robot's page on [the Viam app](https://app.viam.com), select the **Config** tab, select **Raw JSON**, and paste the configuration into the text area.
+ Then return to your robot's page on [the Viam app](https://app.viam.com), select the **Config** tab, select **Raw JSON**, and add the configuration into the text area.
+
+ {{< alert title="Important" color="note" >}}
+ If you already have other configured components, you will need to add each generated JSON object to the respective `modules` or `services` array.
+ If you do not already have configured components, you can replace the contents in **Raw JSON** with the generated contents.
+ {{< /alert >}}
1. Click the **Save config** button at the bottom of the page.
Now, when you switch back to **Builder** mode, you can see the new configuration settings under the **Services** and **Modules** subtabs.
diff --git a/docs/extend/modular-resources/key-concepts.md b/docs/extend/modular-resources/key-concepts.md
index 375b4c162f..c7e3911486 100644
--- a/docs/extend/modular-resources/key-concepts.md
+++ b/docs/extend/modular-resources/key-concepts.md
@@ -19,7 +19,7 @@ A module provides definitions for one or more pairs of [APIs](#valid-apis-to-imp
When the module initializes, it registers those pairs on your robot, making the functionality defined by that pair available for use.
-You can [upload your own modules to the Viam Registry](/extend/modular-resources/upload/) or can [add existing modules from the Registry](/extend/modular-resources/configure/).
+You can [upload your own modules to the Viam registry](/extend/modular-resources/upload/) or can [add existing modules from the Registry](/extend/modular-resources/configure/).
See [Creating a custom module](/extend/modular-resources/create/) for more information.
@@ -47,7 +47,7 @@ See [Naming your model](/extend/modular-resources/key-concepts/#naming-your-mode
Models are either:
- Built into the RDK, and included when you [install `viam-server`](/installation/) or when you use one of the [Viam SDKs](/program/apis/).
-- Provided in custom modules available for download from [the Viam Registry](https://app.viam.com/module), and are written by either Viam or community users.
+- Provided in custom modules available for download from the [Viam registry](https://app.viam.com/registry), and are written by either Viam or community users.
### Built-in models
@@ -61,7 +61,7 @@ For example:
### Custom models
-The [Viam Registry](https://app.viam.com/registry) makes available both Viam-provided and community-written modules for download and use on your robot.
+The [Viam registry](https://app.viam.com/registry) makes available both Viam-provided and community-written modules for download and use on your robot.
These models run outside `viam-server` as a separate process.
#### Valid APIs to implement in your model
@@ -80,7 +80,7 @@ When implementing a custom model of an existing [service](/services/), valid [AP
#### Naming your model
-If you are [creating a custom module](/extend/modular-resources/create/) and [uploading that module](/extend/modular-resources/upload/) to the Viam Registry, ensure your model name meets the following requirements:
+If you are [creating a custom module](/extend/modular-resources/create/) and [uploading that module](/extend/modular-resources/upload/) to the Viam registry, ensure your model name meets the following requirements:
- The namespace of your model **must** match the [namespace of your organization](/manage/fleet/organizations/#create-a-namespace-for-your-organization).
For example, if your organization uses the `acme` namespace, your models must all begin with `acme`, like `acme:demo:mybase`.
@@ -90,7 +90,7 @@ If you are [creating a custom module](/extend/modular-resources/create/) and [up
In addition, you should chose a name for the `family` of your model based on the whether your module implements a single model, or multiple models:
- If your module provides a single model, the `family` should match the `subtype` of whichever API your model implements.
- For example, the Intel Realsense module `realsense`, available from [the Viam Registry](https://app.viam.com/module/viam/realsense), implements the `camera` component API, so it is named as follows:
+ For example, the Intel Realsense module `realsense`, available from the [Viam registry](https://app.viam.com/module/viam/realsense), implements the `camera` component API, so it is named as follows:
```json {class="line-numbers linkable-line-numbers"}
{
@@ -100,7 +100,7 @@ In addition, you should chose a name for the `family` of your model based on the
```
- If your module provides multiple models, the `family` should describe the common functionality provided across all the models of that module.
- For example, the ODrive module `odrive`, available from [the Viam Registry](https://app.viam.com/module/viam/odrive), implements several `motor` component APIs, so it is named as follows:
+ For example, the ODrive module `odrive`, available from the [Viam registry](https://app.viam.com/module/viam/odrive), implements several `motor` component APIs, so it is named as follows:
```json {class="line-numbers linkable-line-numbers"}
{
diff --git a/docs/extend/modular-resources/upload/_index.md b/docs/extend/modular-resources/upload/_index.md
index e885205da0..363f1719b0 100644
--- a/docs/extend/modular-resources/upload/_index.md
+++ b/docs/extend/modular-resources/upload/_index.md
@@ -1,26 +1,22 @@
---
-title: "Upload your own modules to the Viam Registry"
+title: "Upload your own modules to the Viam registry"
linkTitle: "Upload"
weight: 20
type: "docs"
tags: ["server", "rdk", "extending viam", "modular resources", "components", "services"]
-description: "Use the Viam CLI to upload a custom module to the Viam Registry."
+description: "Use the Viam CLI to upload a custom module to the Viam registry."
no_list: true
---
-{{% alert title="Beta Notice" color="note" %}}
-This feature is in beta, and may not be suitable for production use.
-{{% /alert %}}
+Once you have [created a custom module](/extend/modular-resources/create/), you can use the [Viam CLI](/manage/cli/) to upload it to the Viam registry.
-Once you have [created a custom module](/extend/modular-resources/create/), you can use the [Viam CLI](/manage/cli/) to upload it to the Viam Registry.
-
-With the CLI, you can register your module with the Viam Registry to share it with other Viam users, or upload it as a private module that is shared only within your [organization](/manage/fleet/organizations/).
+With the CLI, you can register your module with the [Viam registry](https://app.viam.com/registry) to share it with other Viam users, or upload it as a private module that is shared only within your [organization](/manage/fleet/organizations/).
For more information, see the [`viam module` command](/manage/cli/#module).
## Upload a custom module
-To upload your custom module to the Viam Registry, either as a public or private module, use the Viam CLI commands `create`, `upload`, and `update` following the instructions below:
+To upload your custom module to the [Viam registry](https://app.viam.com/registry), either as a public or private module, use the Viam CLI commands `create`, `upload`, and `update` following the instructions below:
1. First, [install the Viam CLI](/manage/cli/#install) and [authenticate](/manage/cli/#authenticate) to Viam, from the same machine that you intend to upload your module from.
@@ -113,16 +109,16 @@ To upload your custom module to the Viam Registry, either as a public or private
See [The `meta.json` file](/manage/cli/#the-metajson-file) for more information.
-1. Run `viam module update` to register the configuration changes you just made to `meta.json` with the Viam Registry.
+1. Run `viam module update` to register the configuration changes you just made to `meta.json` with the Viam registry.
Run this command from within the same directory as your `meta.json` file:
``` sh {id="terminal-prompt" class="command-line" data-prompt="$"}
viam module update
```
- On a successful update, the command will return a link to the updated module in the Viam Registry.
+ On a successful update, the command will return a link to the updated module in the Viam registry.
-1. Package your custom module to get it ready to upload to the Viam Registry.
+1. Package your custom module to get it ready to upload to the Viam registry.
Currently, the Registry only supports `tar.gz` or `tar.xz` format.
Use the command below specific for the language of your module:
@@ -143,7 +139,7 @@ To upload your custom module to the Viam Registry, either as a public or private
Where `run.sh` is your [entrypoint file](/extend/modular-resources/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/extend/modular-resources/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module.
-1. Run `viam module upload` to upload the updated custom module to the Viam Registry:
+1. Run `viam module upload` to upload the updated custom module to the Viam registry:
``` sh {id="terminal-prompt" class="command-line" data-prompt="$"}
viam module upload --version --platform module.tar.gz
@@ -165,37 +161,48 @@ To upload your custom module to the Viam Registry, either as a public or private
The `viam module upload` command only supports one `platform` argument at a time.
If you would like to upload your module with support for multiple platforms, you must run a separate `viam module upload` command for each platform.
Use the *same version number* when running multiple `upload` commands of the same module code if only the `platform` support differs.
+ The Viam registry page for your module displays the platforms your module supports for each version you have uploaded.
{{% /alert %}}
- For example, the following command uploads the compressed `module.tar.gz` archive to the Viam Registry when run in the same directory as the corresponding `meta.json` file:
+ For example, the following command uploads the compressed `module.tar.gz` archive to the Viam registry when run in the same directory as the corresponding `meta.json` file:
``` sh {id="terminal-prompt" class="command-line" data-prompt="$"}
viam module upload --version 1.0.0 --platform darwin/arm64 module.tar.gz
```
- When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam Registry.
+ When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam registry.
For more information, see the [`viam module` command](/manage/cli/#module)
## Update an existing module
-You can also use the [Viam CLI](/manage/cli/) to update an existing custom module in the Viam Registry.
+You can update an existing module in the [Viam registry](https://app.viam.com/registry) in one of two ways:
+
+- [Upload new versions of your module manually](#update-an-existing-module-using-the-viam-cli) using the [Viam CLI](/manage/cli/).
+- [Automatically upload new versions of your module on release](#update-an-existing-module-using-a-github-action) as part of a continuous integration (CI) workflow, using a GitHub Action.
+
+Updating your module manually is appropriate for smaller projects, especially those with only one contributor.
+Updating your module automatically using CI is better suited for larger, ongoing projects, especially those with multiple contributors.
+
+### Update an existing module using the Viam CLI
+
+To update an existing module in the [Viam registry](https://app.viam.com/registry) manually, use the [Viam CLI](/manage/cli/):
1. Edit your custom module with the changes you'd like to make.
1. Update your custom module's `meta.json` file with the changes, if any.
For example, if you have altered your model's name, or adjusted the endpoint name, you'll need to update `meta.json` with these changes.
-1. Run `viam module update` to register the configuration changes you just made to `meta.json` with the Viam Registry.
+1. Run `viam module update` to register the configuration changes you just made to `meta.json` with the Viam registry.
Run this command from within the same directory as your `meta.json` file:
``` sh {id="terminal-prompt" class="command-line" data-prompt="$"}
viam module update
```
- On a successful update, the command will return a link to the updated module in the Viam Registry.
+ On a successful update, the command will return a link to the updated module in the Viam registry.
-1. Package your custom module to get it ready to upload to the Viam Registry.
+1. Package your custom module to get it ready to upload to the Viam registry.
Currently, the Registry only supports `tar.gz` or `tar.xz` format.
Use the command below specific for the language of your module:
@@ -216,18 +223,91 @@ You can also use the [Viam CLI](/manage/cli/) to update an existing custom modul
Where `run.sh` is your [entrypoint file](/extend/modular-resources/create/#compile-the-module-into-an-executable), `requirements.txt` is your [pip dependency list file](/extend/modular-resources/create/#compile-the-module-into-an-executable), and `src` is the source directory of your module.
-1. Run `viam module upload` to upload the updated custom module to the Viam Registry:
+1. Run `viam module upload` to upload the updated custom module to the Viam registry:
``` sh {id="terminal-prompt" class="command-line" data-prompt="$"}
viam module upload --version --platform
```
- For example, the following command uploads the compressed `my-module.tar.gz` archive to the Viam Registry when run in the same directory, and increments the [`version`](/manage/cli/#using-the---version-argument) of the module to version `1.0.1`:
+ For example, the following command uploads the compressed `my-module.tar.gz` archive to the Viam registry when run in the same directory, and increments the [`version`](/manage/cli/#using-the---version-argument) of the module to version `1.0.1`:
``` sh {id="terminal-prompt" class="command-line" data-prompt="$"}
viam module upload --version 1.0.1 --platform darwin/arm64 my-module.tar.gz
```
- When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam Registry.
+ When you `upload` a module, the command performs basic [validation](/manage/cli/#upload-validation) of your packaged module to ensure it is compatible with the Viam registry.
For more information, see the [`viam module` command](/manage/cli/#module)
+
+### Update an existing module using a GitHub action
+
+To update an existing module in the [Viam registry](https://app.viam.com/registry) using CI, use the [`upload-module` GitHub action](https://github.com/viamrobotics/upload-module).
+
+1. Edit your custom module with the changes you'd like to make.
+
+1. Navigate to the **Actions** tab of the GitHub repository you are using for your module code.
+ If you have already created GitHub actions for this repository, click the **New workflow** button to create a new one.
+ If you have not yet created any GitHub actions, click the **Set up a workflow yourself** link.
+ See the [GitHub actions documentation](https://docs.github.com/en/actions/creating-actions) for more information.
+
+1. Paste the following action template YAML into the edit window.
+
+ ```yaml {class="line-numbers linkable-line-numbers"}
+ on:
+ push:
+ release:
+ types: [released]
+
+ jobs:
+ publish:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ - name: build
+ run: echo "your build command goes here" && false # <-- replace this with the command that builds your module's tar.gz
+ - uses: viamrobotics/upload-module@main
+ # if: github.event_name == 'release' # <-- once the action is working, uncomment this so you only upload on release
+ with:
+ module-path: module.tar.gz
+ org-id: your-org-id-uuid # <-- replace with your org ID. not required for public modules
+ platform: linux/amd64 # <-- replace with your target architecture, or your module will not deploy
+ version: ${{ github.event_name == 'release' && github.ref_name || format('0.0.0-{0}.{1}', github.ref_name, github.run_number) }} # <-- see 'Versioning' section below for explanation
+ key-id: ${{ secrets.viam_key_id }}
+ key-value: ${{ secrets.viam_key_value }}
+ ```
+
+1. Edit the copied code to include the configuration specific to your module.
+ Each item marked with a `<--` comment requires that you edit the configuration values accordingly.
+
+ Set `run` to the command you use to build and package your module.
+ When ready to test the action, uncomment `if: github.event_name == 'release'` to enable the action to trigger a run when you [issue a release](https://docs.github.com/en/repositories/releasing-projects-on-github).
+
+ For guidance on configuring the other parameters, see the documentation for each:
+ - [`org-id`](/manage/cli/#using-the---org-id-and---public-namespace-arguments) - Not required if your module is public.
+ - [`platform`](/manage/cli/#using-the---platform-argument) - You can only upload one platform at a time.
+ - [`version`](https://github.com/viamrobotics/upload-module/blob/main/README.md#versioning) - Also see [Using the --version argument](/manage/cli/#using-the---version-argument) for more details on the types of versioning supported.
+
+1. Create an organization API key and configure your GitHub repository to use it to authenticate during GitHub action runs, following the steps below:
+
+ 1. Follow the instructions to [Create an organization API key](/manage/cli/#create-an-organization-api-key).
+ These steps will return a `key id` and a `key value` which together comprise your organization API key.
+ If you have already created an organization API key, you can skip this step.
+
+ 1. In the GitHub repository for your project, select **Settings**, then **Secrets and variables**, then **Actions**.
+
+ 1. Click the green **New repository secret** button, enter `viam_key_id` as the **NAME**, paste the value for `key id` from above into the **Secret** text field, then click **Add secret**.
+
+ 1. Then, click the green **New repository secret** button, enter `viam_key_value` as the **NAME**, paste the value for `key value` from above into the **Secret** text field, then click **Add secret**.
+
+ For more information on GitHub secrets, see the GitHub documentation for [Creating secrets for a repository](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).
+
+1. Push a commit to your module or [create a new release](https://docs.github.com/en/repositories/releasing-projects-on-github).
+ The specific step to take to release your software depends on your CI workflow, your GitHub configuration, and the `run` step you defined earlier.
+ Once complete, your module should upload to the [Viam registry](https://app.viam.com/registry) with the appropriate version automatically.
+
+For more details, see the [`upload-module` GitHub action documentation](https://github.com/viamrobotics/upload-module), or take a look through one of the following example repositories that show how to package and deploy modules using the Viam SDKs:
+
+- [Python with virtualenv](https://github.com/viam-labs/python-example-module)
+- [Python with docker](https://github.com/viamrobotics/python-container-module)
+- [Golang](https://github.com/viam-labs/wifi-sensor)
+- [C++](https://github.com/viamrobotics/module-example-cpp)
diff --git a/docs/installation/_index.md b/docs/installation/_index.md
index 6cdbc4ad51..d85f4b8c3a 100644
--- a/docs/installation/_index.md
+++ b/docs/installation/_index.md
@@ -40,11 +40,17 @@ If you are using one of the following boards, you can follow our guide for that
{{% card link="/installation/prepare/sk-tda4vm/" class="small" %}}
{{% card link="/installation/prepare/jetson-nano-setup/" class="small" %}}
{{% card link="/installation/prepare/jetson-agx-orin-setup/" class="small" %}}
-{{% card link="/installation/prepare/microcontrollers" class="small" %}}
{{< /cards >}}
+Viam also provides a lightweight version of `viam-server` which can run on resource-limited embedded systems that cannot run the fully-featured Robot Development Kit (RDK). +If you are using a microcontroller, prepare your board using the following guide: + +{{< cards >}} +{{% card link="/installation/prepare/microcontrollers" class="small" %}} +{{< /cards >}} + Other SBCs such as the [RockPi S](https://wiki.radxa.com/RockpiS) and [Orange Pi Zero 2](https://orangepi.com/index.php?route=product/product&path=237&product_id=849) can run Viam with an experimental [periph.io](https://periph.io/) based [modular component](https://github.com/viam-labs/periph_board). ### Install `viam-server` diff --git a/docs/installation/prepare/jetson-agx-orin-setup.md b/docs/installation/prepare/jetson-agx-orin-setup.md index dae5d93ac6..cc8644cf25 100644 --- a/docs/installation/prepare/jetson-agx-orin-setup.md +++ b/docs/installation/prepare/jetson-agx-orin-setup.md @@ -33,7 +33,7 @@ You need the following hardware, tools, and software to install `viam-server` on **Initial Setup with Display Attached:** -1. A [Jetson AGX Orin Developer Kit](https://www.arrow.com/en/products/945-13730-0000-000/nvidia) +1. A [Jetson AGX Orin Developer Kit](https://developer.nvidia.com/embedded/learn/get-started-jetson-agx-orin-devkit) 2. A PC monitor (HDMI or DisplayPort) 3. USB keyboard and mouse 4. A DisplayPort to HDMI adapter/cable, to connect the Orin to the monitor @@ -42,7 +42,7 @@ You need the following hardware, tools, and software to install `viam-server` on **Initial Setup in Headless Mode:** -1. A [Jetson AGX Orin Developer Kit](https://www.arrow.com/en/products/945-13730-0000-000/nvidia) +1. A [Jetson AGX Orin Developer Kit](https://developer.nvidia.com/embedded/learn/get-started-jetson-agx-orin-devkit) 2. An internet-connected Windows, Linux, or macOS computer 3. A way to connect the computer to the Orin (for example, the USB Type-A to USB Type-C Cable included with the AGX Orin Developer Kit) diff --git a/docs/manage/CLI.md b/docs/manage/CLI.md index a19dcf4ffd..f9cf21b787 100644 --- a/docs/manage/CLI.md +++ b/docs/manage/CLI.md @@ -15,7 +15,7 @@ The CLI lets you: * Retrieve [organization](/manage/fleet/organizations/) and location information * Manage [robot fleet](/manage/fleet/) data and logs * Control robots by issuing component and service commands -* Upload and manage [modular resources](/extend/modular-resources/) in the Viam Registry +* Upload and manage [modular resources](/extend/modular-resources/) in the Viam registry For example, this CLI command moves a servo to the 75 degree position: @@ -29,48 +29,35 @@ viam.component.servo.v1.ServoService.MoveRequest You can download the Viam CLI executable using one of the options below. Select the tab for your platform and architecture. - -{{% alert title="Tip" color="tip" %}} -You can use the `uname -m` command to determine your system architecture. -{{% /alert %}} +If you are on Linux, you can use the `uname -m` command to determine your system architecture. {{< tabs >}} -{{% tab name="Linux aarch64" %}} - -To download the Viam CLI on a Linux computer with the `aarch64` architecture, run the following commands: - -```{class="command-line" data-prompt="$"} -sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64 -sudo chmod a+rx /usr/local/bin/viam -``` - -{{% /tab %}} -{{% tab name="Linux x86_64" %}} +{{% tab name="macOS" %}} -To download the Viam CLI on a Linux computer with the `amd64` (Intel `x86_64`) architecture, run the following commands: +To download the Viam CLI on a macOS computer, run the following commands: ```{class="command-line" data-prompt="$"} -sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64 -sudo chmod a+rx /usr/local/bin/viam +brew tap viamrobotics/brews +brew install viam ``` {{% /tab %}} -{{% tab name="macOS arm64" %}} +{{% tab name="Linux aarch64" %}} -To download the Viam CLI on a macOS computer with the `arm64` (Apple Silicon) architecture, run the following commands: +To download the Viam CLI on a Linux computer with the `aarch64` architecture, run the following commands: ```{class="command-line" data-prompt="$"} -sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-darwin-arm64 +sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64 sudo chmod a+rx /usr/local/bin/viam ``` {{% /tab %}} -{{% tab name="macOS x86_64" %}} +{{% tab name="Linux x86_64" %}} -To download the Viam CLI on a macOS computer with the `amd64` (Intel `x86_64`) architecture, run the following commands: +To download the Viam CLI on a Linux computer with the `amd64` (Intel `x86_64`) architecture, run the following commands: ```{class="command-line" data-prompt="$"} -sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-darwin-amd64 +sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64 sudo chmod a+rx /usr/local/bin/viam ``` @@ -95,7 +82,8 @@ echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc {{% /tab %}} {{< /tabs >}} -To later update the Viam CLI tool, you can use the steps above to reinstall the latest version. +To later update the Viam CLI tool on Linux, use the steps above to reinstall the latest version. +to later update the Viam CLI tool on macOS, run `brew upgrade viam`. ## Authenticate @@ -304,8 +292,8 @@ This includes: * Creating a new custom modular resource * Updating an existing module with new changes -* Uploading a new module to the Viam Registry -* Updating an existing module in the Viam Registry +* Uploading a new module to the Viam registry +* Updating an existing module in the Viam registry ```sh {class="command-line" data-prompt="$"} viam module create --name [--org-id | --public-namespace ]
@@ -325,19 +313,22 @@ viam module create --name 'my-module' --org-id 'abc'
# update an existing module:
viam module update
-# upload a new or updated custom module to the Viam Registry:
+# upload a new or updated custom module to the Viam registry:
viam module upload --version "1.0.0" --platform "darwin/arm64" packaged-module.tar.gz
```
See [Upload a custom module](/extend/modular-resources/upload/#upload-a-custom-module) and [Update an existing module](/extend/modular-resources/upload/#update-an-existing-module) for a detailed walkthrough of the `viam module` commands.
+If you update and release your module as part of a continuous integration (CI) workflow, you can also
+[automatically upload new versions of your module on release](/extend/modular-resources/upload/#update-an-existing-module-using-a-github-action) using a GitHub Action.
+
#### Command options
| command option | description | positional arguments
| ----------- | ----------- | ----------- |
| `create` | generate new metadata for a custom module on your local filesystem | - |
| `update` | update an existing custom module on your local filesystem with recent changes to the [`meta.json` file](#the-metajson-file) | - |
-| `upload` | validate and upload a new or existing custom module on your local filesystem to the Viam Registry. See [Upload validation](#upload-validation) for more information |
+| `upload` | validate and upload a new or existing custom module on your local filesystem to the Viam registry. See [Upload validation](#upload-validation) for more information |
| `--help` | return help | - |
##### Named arguments
@@ -356,10 +347,10 @@ See [Upload a custom module](/extend/modular-resources/upload/#upload-a-custom-m
All of the `module` commands accept either the `--org-id` or `--public-namespace` argument.
-* Use the `--public-namespace` argument to supply the [namespace](/manage/fleet/organizations/#create-a-namespace-for-your-organization) of your organization, suitable for uploading your module to the Viam Registry and sharing with other users.
+* Use the `--public-namespace` argument to supply the [namespace](/manage/fleet/organizations/#create-a-namespace-for-your-organization) of your organization, suitable for uploading your module to the Viam registry and sharing with other users.
* Use the `--org-id` to provide your organization ID instead, suitable for sharing your module privately within your organization.
-You may use either argument for the `viam module create` command, but must use `--public-namespace` for the `update` and `upload` commands when uploading as a public module (`visibility: "public"`) to the Viam Registry.
+You may use either argument for the `viam module create` command, but must use `--public-namespace` for the `update` and `upload` commands when uploading as a public module (`visibility: "public"`) to the Viam registry.
##### Using the `--platform` argument
@@ -374,12 +365,14 @@ The `viam module upload` command only supports one `platform` argument at a time
If you would like to upload your module with support for multiple platforms, you must run a separate `viam module upload` command for each platform.
Use the *same version number* when running multiple `upload` commands of the same module code if only the `platform` support differs.
+The Viam registry page for your module displays the platforms your module supports for each version you have uploaded.
+
##### Using the `--version` argument
The `--version` argument accepts a valid [semver 2.0](https://semver.org/) version (example: `1.0.0`).
You set an initial version for your custom module with your first `viam module upload` command for that module, and can later increment the version with subsequent `viam module upload` commands.
-Once your module is uploaded, users can select which version of your module to use on their robot from your module's page on the Viam Registry.
+Once your module is uploaded, users can select which version of your module to use on their robot from your module's page on the Viam registry.
Users can choose to pin to a specific patch version, permit upgrades within major release families or only within minor releases, or permit continuous updates.
When you `update` a module configuration and then `upload` it, the `entrypoint` for that module defined in the [`meta.json` file](#the-metajson-file) is associated with the specific `--version` for that `upload`.
@@ -387,7 +380,7 @@ Therefore, you are able to change the `entrypoint` file from version to version,
##### Upload validation
-When you `upload` a module, the command validates your local packaged module to ensure that it meets the requirements to successfully upload to the Viam Registry.
+When you `upload` a module, the command validates your local packaged module to ensure that it meets the requirements to successfully upload to the Viam registry.
The following criteria are checked for every `upload`:
* The packaged module must exist on the filesystem at the path provided to the `upload` command.
@@ -397,9 +390,9 @@ The following criteria are checked for every `upload`:
##### The `meta.json` file
-When uploading a custom module, the Viam Registry tracks your module's metadata in a `meta.json` file.
+When uploading a custom module, the Viam registry tracks your module's metadata in a `meta.json` file.
This file is created for you when you run the `viam module create` command, with the `module_id` field pre-populated based on the `--name` you provided to `create`.
-If you later make changes to this file, you can register those changes with the Viam Registry by using the `viam module update` command.
+If you later make changes to this file, you can register those changes with the Viam registry by using the `viam module update` command.
The `meta.json` file includes the following configuration options:
diff --git a/docs/manage/configuration.md b/docs/manage/configuration.md
index f303b69660..654fcb4c33 100644
--- a/docs/manage/configuration.md
+++ b/docs/manage/configuration.md
@@ -149,10 +149,7 @@ Depending on your robot, you may not need to configure any modules, remotes, pro
Components represent the pieces of hardware on your robot that you want to control with Viam.
-You must configure each component with a name, a model, a type, attributes, and dependencies:
-
-- `name`: Serves as an identifier when accessing the resource from your code, as well as when configuring other resources that are dependent on that resource.
-You can choose any unique name for a component.
+You must configure each component with a type, a model, a name, attributes, and dependencies:
- `type`: The broad component category, such as `motor`, `arm` or `camera`.
Components of a given type have a common API.
@@ -160,6 +157,9 @@ You can choose any unique name for a component.
- `model`: Indicates the more specific category of hardware.
Components of the same model are supported using the same low-level code.
+- `name`: Serves as an identifier when accessing the resource from your code, as well as when configuring other resources that are dependent on that resource.
+You can choose any unique name for a component.
+
- `attributes`: A struct to define things like how the component is wired to the robot, its dimensions, and other specifications; attributes vary widely between models.
See the [component documentation](/components/) for a given component type and model for more details.
diff --git a/docs/manage/fleet/organizations.md b/docs/manage/fleet/organizations.md
index f16937de0e..2743c2ec5d 100644
--- a/docs/manage/fleet/organizations.md
+++ b/docs/manage/fleet/organizations.md
@@ -48,7 +48,7 @@ In the members section of the page enter their email address, select a role, and
### Create a namespace for your organization
-When uploading [custom modules](/extend/modular-resources/) to the Viam Registry, you must set a namespace for your organization to associate your module with.
+When uploading [custom modules](/extend/modular-resources/) to the Viam registry, you must set a namespace for your organization to associate your module with.
To create a new namespace for your organization, click on the Org's **Settings** in the top right of the navigation bar, then click the **Set a public namespace** button.
Enter a name for your namespace, and then click **Set namespace**.
diff --git a/docs/manage/fleet/robots.md b/docs/manage/fleet/robots.md
index 219737deb9..88d923296e 100644
--- a/docs/manage/fleet/robots.md
+++ b/docs/manage/fleet/robots.md
@@ -111,6 +111,6 @@ Click on the **Generate Key** button to generate a new key.
## Delete a robot
-You can delete a robot by checking the **Sure?** box in the lower left of the robot page and clicking **Delete robot**.
+You can delete a robot by navigating to its page in [the Viam app](https://app.viam.com) and selecting **Sure?** and **Delete robot** in the lower left corner of the page.
{{< imgproc alt="The DELETE ROBOT button and the confirmation checkbox (Sure?) next to it." src="/manage/app-usage/delete.png" resize="300x" >}}
diff --git a/docs/note.md b/docs/note.md
index d988f7d757..0705ec64bf 100644
--- a/docs/note.md
+++ b/docs/note.md
@@ -214,6 +214,8 @@ await arm.move_to_position(pose=pos, world_state=worldstate)
They both use the same color.
**Note/Important/Stability Notice**: These call attention to something important.
+ When creating alerts about important messages, set the title attribute as `title="Important"`.
+ If you want to include a more detailed title or message, use `title="Important: $message"` to provide additional context.
**Caution**: Provide notice that a certain action or event could damage hardware or cause data loss.
diff --git a/docs/program/_index.md b/docs/program/_index.md
index c1ff586094..3fb1f90fe1 100644
--- a/docs/program/_index.md
+++ b/docs/program/_index.md
@@ -1,13 +1,13 @@
---
-title: "Program a Robot"
-linkTitle: "Program Robots"
-childTitleEndOverwrite: "Program Robots"
-description: "Use the SDK of your preferred language to write code to control your robots."
+title: "Program a Smart Machine"
+linkTitle: "Program Machines"
+childTitleEndOverwrite: "Program Machines"
+description: "Use the SDK of your preferred language to write code to control your smart machines."
weight: 45
no_list: true
type: docs
image: "/general/code.png"
-imageAlt: "Program a Robot"
+imageAlt: "Program a smart machine"
images: ["/general/code.png"]
aliases:
- "product-overviews/sdk-as-client"
@@ -17,12 +17,12 @@ aliases:
Viam offers software development kits (SDKs) in popular languages which
-- Broker connection, authentication, and encryption for communication with robots running `viam-server` using {{< glossary_tooltip term_id="webrtc" >}}
+- Broker connection, authentication, and encryption for communication with {{< glossary_tooltip term_id="smart-machine" text="smart machines">}} running `viam-server` using {{< glossary_tooltip term_id="webrtc" >}}
- Enable you to interface with robot [gRPC APIs](https://github.com/viamrobotics/api) in a way that is idiomatic to that programming language
-Use the SDK of your preferred language to write code to control your robots.
+Use the SDK of your preferred language to write code to control your smart machine.
Viam currently offers SDKs for the following languages:
diff --git a/docs/program/apis/robot.md b/docs/program/apis/robot.md
index a64332015b..193d873266 100644
--- a/docs/program/apis/robot.md
+++ b/docs/program/apis/robot.md
@@ -1,5 +1,5 @@
---
-title: "Manage Robots with Viam's Client SDKs"
+title: "Manage Robots with Viam's Robot API"
linkTitle: "Robot Management"
weight: 20
type: "docs"
@@ -115,7 +115,7 @@ Get the configuration of the frame system of a given robot.
```python {class="line-numbers linkable-line-numbers"}
# Get a list of each of the reference frames configured on the robot.
frame_system = await robot.get_frame_system_config()
-print(f"frame system donfiguration: {frame_system}")
+print(f"frame system configuration: {frame_system}")
```
For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/robot/client/index.html#viam.robot.client.RobotClient.get_frame_system_config).
diff --git a/docs/program/apis/sessions.md b/docs/program/apis/sessions.md
index a652200508..cf48370682 100644
--- a/docs/program/apis/sessions.md
+++ b/docs/program/apis/sessions.md
@@ -1,6 +1,6 @@
---
title: "Session Management with Viam's Client SDKs"
-linkTitle: "Session Management API"
+linkTitle: "Session Management"
weight: 20
type: "docs"
description: "How to use the session management API with Viam's Client SDKs."
diff --git a/docs/program/apis/connectivity.md b/docs/program/connectivity.md
similarity index 100%
rename from docs/program/apis/connectivity.md
rename to docs/program/connectivity.md
diff --git a/docs/services/navigation/_index.md b/docs/services/navigation/_index.md
index 5e0d686a81..8b4a9dc427 100644
--- a/docs/services/navigation/_index.md
+++ b/docs/services/navigation/_index.md
@@ -554,3 +554,145 @@ obstacles = await my_nav.get_obstacles()
{{% /tab %}}
{{< /tabs >}}
+
+## Concepts
+
+The following concepts are important to understand when utilizing the navigation service.
+Each concept is a type of relative or absolute measurement, taken by a [movement sensor](/components/movement-sensor/), which can then be utilized by your robot to navigate across space.
+
+Here's how to make use of the following types of measurements:
+
+- [Compass Heading](/services/navigation/#compass-heading)
+- [Orientation](/services/navigation/#orientation)
+- [Angular Velocity](/services/navigation/#angular-velocity)
+- [Position](/services/navigation/#position)
+- [Linear Acceleration](/services/navigation/#linear-acceleration)
+- [Linear Velocity](/services/navigation/#linear-velocity)
+
+### Compass Heading
+
+The following {{< glossary_tooltip term_id="model" text="models" >}} of [movement sensor](/components/movement-sensor/) take compass heading measurements:
+
+- [gps-nmea](/components/movement-sensor/gps/gps-nmea/) - some GPS hardware only report heading while moving.
+- [gps-nmea-rtk-pmtk](/components/movement-sensor/gps/gps-nmea-rtk-pmtk/) - some GPS hardware only report heading while moving.
+- [gps-nmea-rtk-serial](/components/movement-sensor/gps/gps-nmea-rtk-serial/) - some GPS hardware only report heading while moving.
+- [imu-wit](/components/movement-sensor/imu/imu-wit/)
+
+An example of a `Compass Heading` reading:
+
+``` go
+// heading is a float64 between 0-360
+heading, err := gps.CompassHeading(context.Background, nil)
+```
+
+Use compass heading readings to determine the *bearing* of your robot, or, the [cardinal direction](https://en.wikipedia.org/wiki/Cardinal_direction) that your robot is facing.
+
+To read compass headings, [configure a capable movement sensor](/components/movement-sensor/#configuration) on your robot.
+Then use the movement sensor API's [`GetCompassHeading()`](/components/movement-sensor/#getcompassheading) method to get readings from the sensor.
+
+### Orientation
+
+The following {{< glossary_tooltip term_id="model" text="models" >}} of [movement sensor](/components/movement-sensor/) take orientation measurements:
+
+- [imu-wit](/components/movement-sensor/imu/imu-wit/)
+- [imu-vectornav](/components/movement-sensor/imu/imu-vectornav/)
+
+An example of an `Orientation` reading:
+
+``` go
+// orientation is a OrientationVector struct with OX, OY, OZ denoting the coordinates of the vector and rotation about z-axis, Theta
+orientation, err := imuwit.Orientation(context.Background, nil)
+```
+
+Use orientation readings to determine the orientation of an object in 3D space as an [*orientation vector*](/internals/orientation-vector/).
+An orientation vector indicates how it is rotated relative to an origin coordinate system around the x, y, and z axes.
+You can choose the origin reference frame by configuring it using Viam's [frame system](/services/frame-system/).
+The `GetOrientation` readings will report orientations relative to that initial frame.
+
+To read orientation, first [configure a capable movement sensor](/components/movement-sensor/#configuration) on your robot.
+Additionally, follow [these instructions](/services/frame-system/#configuration) to configure the geometries of each component of your robot within the [frame system](/services/frame-system/).
+Then use the movement sensor API's [`GetOrientation()`](/components/movement-sensor/#getorientation) method to get orientation readings.
+
+### Angular Velocity
+
+The following {{< glossary_tooltip term_id="model" text="models" >}} of the [movement sensor](/components/movement-sensor/) component take angular velocity measurements:
+
+- [imu-wit](/components/movement-sensor/imu/imu-wit/)
+- [imu-vectornav](/components/movement-sensor/imu/imu-vectornav/)
+- [wheeled-odometry](/components/movement-sensor/wheeled-odometry/)
+- [gyro-mpu6050](/components/movement-sensor/mpu6050/)
+
+An example of an `AngularVelocity` reading:
+
+``` go
+// angularVelocity is an AngularVelocity r3 Vector with X, Y, and Z magnitudes
+angularVelocity, err := imu.AngularVelocity(context.Background, nil)
+```
+
+Use angular velocity readings to determine the speed and direction at which your robot is rotating.
+
+To get an angular velocity reading, first [configure a capable movement sensor](/components/movement-sensor/#configuration) on your robot.
+Then use the movement sensor API's [`GetAngularVelocity()`](/components/movement-sensor/#getangularvelocity) method to get angular velocity readings from the sensor.
+
+### Position
+
+The following {{< glossary_tooltip term_id="model" text="models" >}} of the [movement sensor](/components/movement-sensor/) component take position measurements:
+
+- [gps-nmea](/components/movement-sensor/gps/gps-nmea/)
+- [gps-nmea-rtk-pmtk](/components/movement-sensor/gps/gps-nmea-rtk-pmtk/)
+- [gps-nmea-rtk-serial](/components/movement-sensor/gps/gps-nmea-rtk-serial/)
+
+An example of a `Position` reading:
+
+``` go
+// position is a geo.Point consisting of Lat and Long: -73.98 and an altitude in float64
+position, altitude, err:= imu.Position(context.Background, nil)
+```
+
+Use position readings to determine the GPS coordinates of an object in 3D space or its position in the geographic coordinate system [(GCS)](https://en.wikipedia.org/wiki/Geographic_coordinate_system).
+These position readings reflect the *absolute* position of components.
+
+To get a position, [configure a capable movement sensor](/components/movement-sensor/#configuration) on your robot.
+Then use the movement sensor API's [`GetPosition()`](/components/movement-sensor/#getposition) method to get position readings from the sensor.
+
+### Linear Velocity
+
+The following {{< glossary_tooltip term_id="model" text="models" >}} of [movement sensor](/components/movement-sensor/) take linear velocity measurements:
+
+- [gps-nmea](/components/movement-sensor/gps/gps-nmea/)
+- [gps-nmea-rtk-pmtk](/components/movement-sensor/gps/gps-nmea-rtk-pmtk/)
+- [gps-nmea-rtk-serial](/components/movement-sensor/gps/gps-nmea-rtk-serial/)
+- [wheeled-odometry](/components/movement-sensor/wheeled-odometry/) (provides a relative estimate only based on where the base component has started)
+
+An example of a `Linear Velocity` reading:
+
+``` go
+// linearVelocity is an r3.Vector with X, Y, and Z magnitudes
+linearVelocity, err := imu.LinearVelocity(context.Background, nil)
+```
+
+Use linear velocity readings to determine the speed at which your robot is moving through space.
+
+To get linear velocity, [configure a capable movement sensor](/components/movement-sensor/#configuration) on your robot.
+Then use the movement sensor API's [`GetLinearVelocity()`](/components/movement-sensor/#getlinearvelocity) method to get linear velocity readings from the sensor.
+
+### Linear Acceleration
+
+The following {{< glossary_tooltip term_id="model" text="models" >}} of [movement sensor](/components/movement-sensor/) take linear acceleration measurements:
+
+- [accel-adxl345](/components/movement-sensor/adxl345/)
+- [imu-wit](/components/movement-sensor/imu/imu-wit/)
+- [imu-vectornav](/components/movement-sensor/imu/imu-vectornav/)
+- [gyro-mpu6050](/components/movement-sensor/mpu6050/)
+
+An example of a `Linear Acceleration` reading:
+
+``` go
+// linearAcceleration is an r3.Vector with X, Y, and Z magnitudes
+linearAcceleration, err := imu.LinearAcceleration(context.Background, nil)
+```
+
+You can use linear acceleration readings to determine the rate of change of the [linear velocity](/services/navigation/#linear-velocity) of your robot, or, the acceleration at which your robot is moving through space.
+
+To get linear acceleration, [configure a capable movement sensor](/components/movement-sensor/#configuration) on your robot.
+Then use the movement sensor API's [`GetLinearAcceleration()`](/components/movement-sensor/#getlinearacceleration) method to get linear acceleration readings from the sensor.
diff --git a/docs/try-viam/_index.md b/docs/try-viam/_index.md
index 6be7fe96cc..30cf5f1ad0 100644
--- a/docs/try-viam/_index.md
+++ b/docs/try-viam/_index.md
@@ -14,7 +14,7 @@ aliases:
- "/getting-started/try-viam/"
---
-Viam is a general robotics platform that can run on any hardware.
+Viam is a general {{< glossary_tooltip term_id="smart-machine" text="smart machine">}} platform that can run on any hardware.
The easiest way to try Viam is to [rent and remotely configure and control a Viam Rover](https://app.viam.com/try) located on-site at Viam in New York:
@@ -35,7 +35,7 @@ See detailed instructions.
diff --git a/docs/tutorials/custom/custom-base-dog.md b/docs/tutorials/custom/custom-base-dog.md
index 1567f3328a..1883a1ff09 100644
--- a/docs/tutorials/custom/custom-base-dog.md
+++ b/docs/tutorials/custom/custom-base-dog.md
@@ -345,42 +345,59 @@ Name your module `my-custom-base`.
Enter the path (for example, `/home/fido/robotdog/run.sh`) to your module's executable file in the **Executable path** field.
Click **Save Config** at the bottom of the page.
-
+
## Configure the components
Now that the custom base code is set up, you need to configure all your hardware components.
-Navigate to the **Components** subtab of the **Config** tab.
+Navigate to the **Components** subtab of your robot's **Config** tab.
-### Configure the base
+### Configure the camera
-In the **Create Component** field, give your base a name.
-We called ours "quadruped".
-In the **Type** drop-down select `base`.
-In the **Model** field, type in `viamlabs:base:robotdog`.
-Click **Create Component**.
+Configure the ribbon camera on the dog as a `webcam` following our [webcam documentation](/components/camera/webcam/).
-
+Click **Save config**.
-You need to add the `ip_address` and `port` attributes to your base config.
-In the attributes field, paste the following, replacing `` with your Pi's hostname (for example, `"ip_address": "robotdog.local"`):
+### Configure the base
+
+Because your custom base relies on a local module, you need to use raw JSON to configure your modular resource.
+Use the **Mode** selector in the upper-left corner of the **Config** tab to switch to **Raw JSON** mode.
+
+Locate the `"components": []` portion of the config file.
+At the end of your camera configuration, add a comma and then add the following base configuration:
```json
-{
- "ip_address": ".local",
- "port": 5001
-}
+ {
+ "namespace": "rdk",
+ "name": "quadruped",
+ "type": "base",
+ "model": "viamlabs:base:robotdog",
+ "attributes": {
+ "ip_address": ".local",
+
+ "port": 5001
+ },
+ "depends_on": []
+ }
```
+Edit the `ip_address` attribute to match your robot's hostname, replacing `` with your Pi's hostname (for example, `"ip_address": "robotdog.local"`).
If this doesn't work, you can instead try using the IP address of the machine where the module is running, for example, `"ip_address": "10.0.0.123"`.
+If you are using a port other than `5001`, edit the `port` attribute.
`5001` is the default port for sending and receiving instructions to and from the Freenove server.
-Click **Save Config**.
+Click **Save config**.
-### Configure the camera
+Your raw JSON configuration should look similar to the following:
-Configure the ribbon camera on the dog as a `webcam` following our [webcam documentation](/components/camera/webcam/).
+
+
+Toggle back to **Builder** mode and make sure a configuration panel has been generated:
+
+
+
+If yours doesn't resemble the following, go back to the raw JSON and double-check your JSON formatting.
## Start the Freenove server
diff --git a/docs/tutorials/get-started/blink-an-led.md b/docs/tutorials/get-started/blink-an-led.md
index 356c785055..4e356c3026 100644
--- a/docs/tutorials/get-started/blink-an-led.md
+++ b/docs/tutorials/get-started/blink-an-led.md
@@ -130,7 +130,7 @@ First, go to the [Viam app](https://app.viam.com/) on your web browser and navig
{{% tab name="Config Builder" %}}
Add a [*board component*](/components/board/) to represent your single-board computer, which in this case is the Raspberry Pi.
-To create the new component, click **Create component** in the lower left corner of the **Config** tab.
+To create the new component, click **Create component** in the lower-left corner of the **Config** tab.
- Select `board` as the component type.
- Select `pi` as the model.
diff --git a/docs/tutorials/projects/claw-game.md b/docs/tutorials/projects/claw-game.md
index 8d5659b9a4..7993b14988 100644
--- a/docs/tutorials/projects/claw-game.md
+++ b/docs/tutorials/projects/claw-game.md
@@ -164,10 +164,11 @@ Navigate to the **Config** tab of your robot's page and select your main part fr
{{< tabs >}}
{{% tab name="Builder UI" %}}
-Click on the **Components** subtab and navigate to the **Create component** menu.
+Click the **Components** subtab.
+Click the **Create component** button in the lower-left corner.
-Add your [board](https://docs.viam.com/components/board/) with the name `myBoard`, type `board`, and model `pi`.
-Click **Create Component**.
+Add your [board](https://docs.viam.com/components/board/) with type `board` and model `pi`.
+Name your board `myBoard` and click **Create**.
@@ -175,7 +176,7 @@ You can name your board whatever you want as long as you use the same name to re
We named it `myBoard` for simplicity.
This is the only component in the main robot.
-Click **Save config** in the bottom left corner of the screen.
+Click **Save config** in the lower-left corner of the screen.
{{% /tab %}}
{{% tab name="Raw JSON" %}}
@@ -196,7 +197,7 @@ On the [`Raw JSON` tab](/manage/configuration/#the-config-tab), replace the conf
}
```
-Click **Save config** in the bottom left corner of the screen.
+Click **Save config** in the lower-left corner of the screen.
{{% /tab %}}
{{< /tabs >}}
@@ -210,10 +211,11 @@ Use the parts drop-down menu to navigate to the `planning` sub-part.
{{< tabs >}}
{{% tab name="Builder UI" %}}
-Click on the **Components** subtab and navigate to the **Create component** menu.
+Click the **Components** subtab.
+Click the **Create component** button in the lower-left corner.
-Add your [arm](/components/arm/) with the name `myArm`, type `arm`, and model `xArm6`.
-Click **Create Component**.
+Add your [arm](/components/arm/) with type `arm`, and model `xArm6`.
+Name it `myArm` and click **Create**.
@@ -222,7 +224,7 @@ Our arm's address was `10.1.1.26`, but you should use the IP address for your ar
For more information on xArm6 configuration, see [Configure an xArm6 Arm](/components/arm/xarm6/).
-Click **Save config** in the bottom left corner of the screen.
+Click **Save config** in the lower-left corner of the screen.
{{% /tab %}}
{{% tab name="Raw JSON" %}}
@@ -274,8 +276,9 @@ Click **Save config** in the bottom left corner of the screen.
{{< tabs >}}
{{% tab name="Builder UI" %}}
-Add your [gripper](/components/gripper/) with the name `gripper`, type `gripper`, and model `fake`.
-Click **Create Component**.
+Click **Create component** and add your [gripper](/components/gripper/).
+Choose type `gripper` and model `fake`.
+Name it `gripper` and click **Create**.
@@ -285,7 +288,7 @@ You will only use this as a placeholder for the size of the gripper to use with
Measure the claw's height and width, and enter these values for the `fake` model.
Ours was 120mm for the width and 180mm for the height.
-Click **Save config** in the bottom left corner of the screen.
+Click **Save config** in the lower-left corner of the screen.
{{% /tab %}}
{{% tab name="Raw JSON" %}}
diff --git a/docs/tutorials/projects/foam-dart-launcher.md b/docs/tutorials/projects/foam-dart-launcher.md
index 6d3e6d439a..5b4cdde8fe 100644
--- a/docs/tutorials/projects/foam-dart-launcher.md
+++ b/docs/tutorials/projects/foam-dart-launcher.md
@@ -171,11 +171,13 @@ Try activating the solenoid manually to ensure that it hits the foam dart launch
## Configure Your Foam Dart Launcher Robot with the Viam App
Create a new robot in the Viam app and give it a name.
+Navigate to your new robot's **Config** tab and click the **Components** subtab.
### Board Configuration (Raspberry Pi)
-Add your board with the **Name** `local`, **Type** `board`, and **Model** `pi`.
-Click **Create Component**.
+Click **Create component** and add your [board](/components/board/).
+Choose type `board` and model `pi`.
+Name it `local` and click **Create**.
{{}}
@@ -186,8 +188,8 @@ Just remember to use that name consistently in the following steps.
#### Left Motor
-Add the left [motor](/components/motor/) with the **Name** `left`, **Type** `motor`, and **Model** `gpio`.
-Click **Create Component**.
+Click **Create component** and add the left [motor](/components/motor/) with type `motor` and model `gpio`.
+Name it `left` and click **Create**.
Select the name of the board the motor controller is wired to (for example, "local") from the **Board** drop-down.
@@ -203,8 +205,8 @@ Click **Save config** at the bottom of the screen.
#### Right Motor
-Add the right motor with the **Name** `right`, **Type** `motor` and **Model** `gpio`.
-Click **Create Component**.
+Click **Create component** and add the right [motor](/components/motor/) with type `motor` and model `gpio`.
+Name it `right` and click **Create**.
Select the name of the board the motor controller is wired to (for example, "local") from the **Board** drop-down.
@@ -228,7 +230,8 @@ Let’s add a base to be able to control them together.
Configure a [base component](/components/base/) to coordinate your motors so you can move the base around with your keyboard.
-Give it a **Name** (you can just call it "base"), set **Type** to `base`, set **Model** to `wheeled`, and click **Create Component**.
+Click **Create component** and add the base with type `base` and model `wheeled`.
+Give it a name (you can call it `base`) and click **Create**.
From the **Right Motors** and **Left Motors** drop downs, select `right` and `left`, respectively (the motors you configured in the previous step).
diff --git a/docs/tutorials/projects/guardian.md b/docs/tutorials/projects/guardian.md
index 62701cdaa9..1263dc61b3 100644
--- a/docs/tutorials/projects/guardian.md
+++ b/docs/tutorials/projects/guardian.md
@@ -126,24 +126,27 @@ Go to the **Setup** tab of your new robot's page and follow the steps [to instal
{{% tab name="Builder UI" %}}
Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
-Click on the **Components** subtab and navigate to the **Create component** menu.
+Click on the **Components** subtab.
1. **Add the board.**
- Enter `local` for the name for your [board component](/components/board/), select the type `board`, and select the `pi` model.
- Then click **Create component**.
+ Click **Create component** in the lower-left corner of the page.
+ Select `board` for the type, then select `pi` for the model.
+ Enter `local` as the name for your [board component](/components/board/), then click **Create**.
2. **Add the camera.**
- Create a [camera component](/components/camera/) with the name `cam`, the type `camera` and the model `webcam`.
- Click **Create Component** to add the camera.
+ Click **Create Component** to add the [camera](/components/camera/).
+ Select `camera` for the type, then select `webcam` for the model.
+ Enter `cam` as the name for the camera, then click **Create**.
In the new camera panel, click the **Video Path** field to reveal a drop-down populated with camera paths that have been identified on your machine.
Select `mmal service 16.1 (platform:bcm2835_v4l2-0)`.
3. **Add the servo.**
- Create a [servo component](/components/servo/) with the name `servo`, the type `servo` and the model `pi`.
- Click **Create Component** to add the servo.
+ Click **Create component** in the lower-left corner of the page.
+ Select `servo` for the type, then select `pi` for the model.
+ Enter `servo` as the name for your [servo component](/components/servo/), then click **Create**.
Configure the attributes by adding the name of your board, `local`, and the {{< glossary_tooltip term_id="pin-number" text="pin number" >}} of the pin on `local` that you connected your servo PWM wire to, `12`:
```json
diff --git a/docs/tutorials/projects/light-up.md b/docs/tutorials/projects/light-up.md
index a4f47070a7..f7137b7db6 100644
--- a/docs/tutorials/projects/light-up.md
+++ b/docs/tutorials/projects/light-up.md
@@ -122,8 +122,9 @@ Click on the **Services** subtab and navigate to the **Create service** menu.
To be able to test that the vision service is working, add a `transform` camera which will add bounding boxes and labels around the objects the service detects.
-Click on the **Components** subtab and navigate to the **Create component** menu.
-Create a [transform camera](/components/camera/transform/) with the name `detectionCam`, the type `camera` and the model `transform`.
+Click the **Components** subtab and click the **Create component** button in the lower-left corner.
+Create a [transform camera](/components/camera/transform/) with type `camera` and model `transform`.
+Name it `detectionCam` and click **Create**.
diff --git a/docs/tutorials/projects/modernize-retro-robot.md b/docs/tutorials/projects/modernize-retro-robot.md
index e59d04d9ef..379cb21d44 100644
--- a/docs/tutorials/projects/modernize-retro-robot.md
+++ b/docs/tutorials/projects/modernize-retro-robot.md
@@ -271,17 +271,19 @@ Go to the **Setup** tab of your new robot's page and follow the steps [to instal
{{% tab name="Builder UI" %}}
Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
-Click on the **Components** subtab and navigate to the **Create component** menu.
+Click on the **Components** subtab.
-1. **Add the board**
+1. **Add the board**.
- Enter `local` for the name for your [board component](/components/board/), select the type `board`, and select the `pi` model.
- Then click **Create component**.
+ Click the **Create component** button in the lower-left corner of the page.
+ Select the type `board`, then select the `pi` model.
+ Enter `local` as the name for your [board component](/components/board/), then click **Create**.
-2. **Add the left base motor.**
+2. **Add the left motor.**
- Enter `base-l` for the name for your left base [motor component](/components/motor/), select the type `motor`, and select the `gpio` model.
- Then click **Create component**.
+ Click **Create component** to add the [motor component](/components/motor/) on the left side of the robot base.
+ Select the type `motor`, and select the `gpio` model.
+ Enter `base-l` for the name, then click **Create**.
Next, select `local` for the board attribute.
Set `Max RPM` to 200.
@@ -294,10 +296,11 @@ Click on the **Components** subtab and navigate to the **Create component** menu
Finally, add `local` to `Depends on` - this ensures that the `local` board component is fully initialize prior to this motor.
-3. **Add the right base motor**
+3. **Add the right motor**
- Enter `base-r` for the name for your right base [motor component](/components/motor/), select the type `motor`, and select the `gpio` model.
- Then click **Create component**.
+ Click **Create component**.
+ For your right base [motor component](/components/motor/), select the type `motor`, and select the `gpio` model.
+ Enter `base-r` for the name, then click **Create**.
Next, select `local` for the board attribute.
Set `Max RPM` to 200.
@@ -314,8 +317,9 @@ Click on the **Components** subtab and navigate to the **Create component** menu
Configuring a [base component](/components/base/) allows you to create an interface to control the movement of MAIV withing needing to send individual motor commands.
- Enter `base` for the name for your base, select the type `base`, and select the `wheeled` model.
- Then click **Create component**.
+ Click **Create component**.
+ Select the type `base`, and select the `wheeled` model.
+ Enter `base` for the name for your base, then click **Create**.
Next, add `base-r` to `Right Motors` and add `base-l` to `Left Motors`.
@@ -481,10 +485,10 @@ You can use any free GPIO pins, but we connected pin 16 to `IN1`, pin 37 to `IN2
{{< tabs >}}
{{% tab name="Builder UI" %}}
To add the neck motor, navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
-Click on the **Components** subtab and navigate to the **Create component** menu.
+Navigate to the **Components** subtab and click **Create component** in the lower-left corner.
-Enter `neck` for the name for your neck [motor component](/components/motor/), select the type `motor`, and select the `gpio` model.
-Then click **Create component**.
+To create your [motor component](/components/motor/), select the type `motor`, and select the `gpio` model.
+Enter `neck` as the name for your neck motor, then click **Create**.
Next, select `local` for the board attribute.
Set `Max RPM` to 200.
@@ -563,11 +567,11 @@ Fit MAIV's neck into the torso, and re-assemble the torso.
{{< tabs >}}
{{% tab name="Builder UI" %}}
-Add the camera to your robot by navigating to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
-Click on the **Components** subtab and navigate to the **Create component** menu.
+Add the [camera component](/components/camera/) to your robot by navigating to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
+Click on the **Components** subtab and click the **Create component** button in the lower-left corner.
-Enter `face-cam` for the name for your [camera component](/components/camera/), select the type `camera`, and select the `webcam` model.
-Then click **Create component**.
+Select the type `camera`, and select the `webcam` model.
+Enter `face-cam` for the name, then click **Create**.
Being that this is the only camera currently configured for MAIV, keep 'video path' blank, and viam-server will auto-detect the path on startup or reconfiguration.
diff --git a/docs/tutorials/projects/send-security-photo.md b/docs/tutorials/projects/send-security-photo.md
index 1a64059e24..8a588eec3f 100644
--- a/docs/tutorials/projects/send-security-photo.md
+++ b/docs/tutorials/projects/send-security-photo.md
@@ -134,12 +134,13 @@ Click on the **Services** subtab and navigate to the **Create service** menu.
To be able to test that the vision service is working, add a `transform` camera which will add bounding boxes and labels around the objects the service detects.
-Click on the **Components** subtab and navigate to the **Create component** menu.
-Create a [transform camera](/components/camera/transform/) with the name `detectionCam`, the type `camera`, and the model `transform`.
+Click on the **Components** subtab and click **Create component** in the lower-left corner.
+Create a [transform camera](/components/camera/transform/) with type `camera` and model `transform`.
+Name it `detectionCam` and click **Create**.
-In the new transform camera panel, replace the attributes JSON object with the following object which specifies the camera source that the `transform` camera will be using and defines a pipeline that adds the defined `myPeopleDetector`:
+In the new transform camera panel, replace the attributes JSON object with the following object which specifies the camera source that the `transform` camera will use, and defines a pipeline that adds the defined `myPeopleDetector`:
```json
{
@@ -156,7 +157,7 @@ In the new transform camera panel, replace the attributes JSON object with the f
}
```
-Click **Save config** in the bottom left corner of the screen.
+Click **Save config** in the lower-left corner of the screen.
diff --git a/docs/tutorials/services/webcam-line-follower-robot.md b/docs/tutorials/services/webcam-line-follower-robot.md
index d79bc7228d..af52fe8a1e 100644
--- a/docs/tutorials/services/webcam-line-follower-robot.md
+++ b/docs/tutorials/services/webcam-line-follower-robot.md
@@ -66,28 +66,31 @@ Follow the instructions until the Viam app shows that your robot has successfull
{{% tab name="Builder UI" %}}
Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com).
-Click on the **Components** subtab and navigate to the **Create component** menu.
+Click on the **Components** subtab.
1. **Add the board.**
- Enter `local` for the name for your [board component](/components/board/), select the type `board`, and select the `pi` model.
- Then click **Create component**.
+ Click **Create component**.
+ Select the type `board`, and select the `pi` model.
+ Enter `local` as the name of your [board component](/components/board/), then click **Create**.
2. **Add the motors.**
- Enter `leftm` for the name for your left [motor component](/components/base/), select the type `motor`, and select the `gpio` model.
- Then click **Create component** and fill in the appropriate properties for your motor.
+ Click **Create component**.
+ Select the type `motor`, and select the `gpio` model.
+ Enter `leftm` as the name of your [motor component](/components/motor/), then click **Create** and fill in the appropriate properties for your motor.
Repeat the same for the right motor and call it `rightm`.
3. **Add the base.**
- Enter `scuttlebase` for the name for your [base component](/components/base/), select the type `base`, and select the `wheeled` model.
- Then click **Create component** and select the motors.
+ Click **Create component**.
+ Select the type `base`, and select the `wheeled` model.
+ Enter `scuttlebase` as the name for your [base component](/components/base/), then click **Create** and select the motors.
4. **Add the camera.**
Create a [camera component](/components/camera/) with the name `my_camera`, the type `camera` and the model `webcam`.
- Click **Create Component** to add the camera.
+ Click **Create component** to add the camera.
If your robot is connected, you can click the **Video Path** field in the new camera panel to reveal a drop-down populated with camera paths that have been identified on your machine.
Select the path to the camera you want to use.
@@ -240,8 +243,9 @@ Click on the **Services** subtab and navigate to the **Create service** menu.
If you'd like to see the bounding boxes that the color detector identifies, you'll need to configure a [transform camera](/components/camera/transform/).
This isn't another piece of hardware, but rather a virtual "camera" that takes in the stream from the webcam we just configured and outputs a stream overlaid with bounding boxes representing the color detections.
- Click on the **Components** subtab and navigate to the **Create component** menu.
- Create a [transform camera](/components/camera/transform/) with the name `transform_cam`, the type `camera` and the model `transform`.
+ Click on the **Components** subtab and click **Create component**.
+ Add a [transform camera](/components/camera/transform/) with type `camera` and model `transform`.
+ Name it `transform_cam` and click **Create**.
Replace the attributes JSON object with the following object which specifies the camera source that the `transform` camera will be using and defines a pipeline that adds the defined `detector`:
diff --git a/docs/viam/_index.md b/docs/viam/_index.md
index 230059ffd1..51a2acc5e6 100644
--- a/docs/viam/_index.md
+++ b/docs/viam/_index.md
@@ -1,7 +1,7 @@
---
title: "Viam in 3 minutes"
linkTitle: "Viam in 3 minutes"
-description: "Viam is a complete software platform for robots which provides modular robot components and services for vision, motion, SLAM, ML, and data management."
+description: "Viam is a complete software platform for smart machines which provides modular components and services for vision, motion, SLAM, ML, and data management."
weight: 10
no_list: true
type: docs
@@ -14,54 +14,54 @@ imageAlt: "/general/understand.png"
images: ["/general/understand.png"]
---
-Viam is a complete software platform that supports every step of your robot development lifecycle.
+Viam is a complete software platform that supports every step of your {{< glossary_tooltip term_id="smart-machine" text="smart machine">}} development lifecycle.
-## Plan your robot
+## Plan your smart machine
-When using Viam, this is what you'll need to know to plan your robot:
+When using Viam, this is what you'll need to know to plan your smart machine:
-
+
- **Hardware**:
-Many {{< glossary_tooltip term_id="component" text="robotic components">}} are natively supported by the Viam platform.
+Many {{< glossary_tooltip term_id="component" text="components">}} are natively supported by the Viam platform.
You will not need to write a single line of code to integrate them, and swapping out component models will not require code changes.
- **Functionality**:
You can make use of computer vision, motion planning, SLAM, data management, machine learning, and more by configuring Viam's built-in {{< glossary_tooltip term_id="service" text="services">}}.
- **Architecture**:
-You can build simple robots or multi-part robots that use secure communication channels across local networks and the cloud, all of which can be managed with a uniform API.
-- **Extensibility**: If you need additional functionality, you can leverage community contributed and modular resources to [extend](/extend/) Viam from [the Viam Registry](/extend/modular-resources/).
+You can build simple smart machines or multi-part smart machines that use secure communication channels across local networks and the cloud, all of which can be managed with a uniform API.
+- **Extensibility**: If you need additional functionality, you can leverage community contributed and modular resources to [extend](/extend/) Viam from [the Viam registry](/extend/modular-resources/).
Join the [**Viam community**](https://discord.gg/viam) to collaborate during planning and beyond.
## Get started
-A *robot* in Viam consists of at least one computer, typically a [single-board computer](/installation/), running `viam-server` and communicating with any hardware connected to it by signaling through digital data pins.
+A *smart machine* in Viam consists of at least one computer, typically a [single-board computer](/installation/), running `viam-server` and communicating with any hardware connected to it by signaling through digital data pins.
Viam supports devices running **any** 64-bit Linux OS or macOS.
{{< imgproc src="/viam/board-viam-server.png" alt="A diagram of a single-board computer running viam-server." resize="270x" class="alignleft" style="max-width:270px" >}}
-The Viam platform provides a user interface for connecting to and managing robots, the [Viam app](https://app.viam.com/).
+The Viam platform provides a user interface for connecting to and managing smart machines, the [Viam app](https://app.viam.com/).
-To use the Viam platform with your robot, log in to [the app](https://app.viam.com/), create a new robot, and [install](/installation/) the [`viam-server`](https://github.com/viamrobotics/rdk) binary which:
+To use the Viam platform with your smart machine, log in to [the app](https://app.viam.com/), create a new robot, and [install](/installation/) the [`viam-server`](https://github.com/viamrobotics/rdk) binary which:
-- Creates, configures, and maintains the robot.
+- Creates, configures, and maintains the smart machine.
- Securely handles all communications.
- Runs drivers, custom code, and any other software.
- Accepts API requests.
- Runs services like computer vision, data synchronization, and motion planning.
{{% alert title="Info" color="info" %}}
-Everything Viam runs on your robot is [open-source](https://github.com/viamrobotics).
+Everything Viam runs on your smart machine is [open-source](https://github.com/viamrobotics).
{{% /alert %}}
-## Configure your robot
+## Configure your smart machine
Robots can be small and simple or very complex.
-A robot can be a single-board computer with a single sensor or LED wired to it, or a robot can consist of multiple computers with many physical components connected, acting as one unit.
+A smart machine can be a single-board computer with a single sensor or LED wired to it, or a smart machine can consist of multiple computers with many physical components connected, acting as one unit.
The term {{% glossary_tooltip term_id="component" text="*component*" %}} describes a piece of hardware that a computer controls, like an arm or a motor.
-For each component that makes up your robot:
+For each component that makes up your smart machine:
+
-The Viam platform provides a consistent programming interface for all robots, allowing you to [control your robots](/program/apis/) with code in the **language of your choice**.
+The Viam platform provides a consistent programming interface for all smart machines, allowing you to [control your smart machines](/program/apis/) with code in the **language of your choice**.
Viam currently has SDKs for [Go](https://pkg.go.dev/go.viam.com/rdk), [Python](https://python.viam.dev/), and [TypeScript](https://ts.viam.dev/).
Additional SDKs are coming soon, including Rust, Java, C++, and Flutter.
TLS certificates provided by [app.viam.com](https://app.viam.com) ensure that all communication is authenticated and encrypted.
-Viam uses {{< glossary_tooltip term_id="webrtc" >}} to create secure peer-to-peer paths between robots and clients for fast, low-latency communication.
-The Viam cloud does not receive any command or control information regarding your robots, ensuring low latency, robustness, and privacy.
-With WebRTC established, Viam uses {{< glossary_tooltip term_id="grpc" text="gRPC" >}} so you can program your robot in many common programming languages.
+Viam uses {{< glossary_tooltip term_id="webrtc" >}} to create secure peer-to-peer paths between smart machines and clients for fast, low-latency communication.
+The Viam cloud does not receive any command or control information regarding your smart machines, ensuring low latency, robustness, and privacy.
+With WebRTC established, Viam uses {{< glossary_tooltip term_id="grpc" text="gRPC" >}} so you can program your smart machines in many common programming languages.
-This provides flexibility and security whether you are building tight control loops for autonomous mobile robots, event-based triggers for IoT devices, or custom web-based robot management interfaces.
+This provides flexibility and security whether you are building tight control loops for autonomous mobile smart machines, event-based triggers for IoT devices, or custom web-based smart machine management interfaces.
There are four categories of APIs:
@@ -109,44 +109,44 @@ You can see the Viam API specification on [GitHub](https://github.com/viamroboti
### Network flexibility
-Your robot does not need to be connected to the cloud.
+Your smart machine does not need to be connected to the cloud.
-The `viam-server` software resides on your robot alongside your configurations, your code, and appropriate services.
-In scenarios without cloud connectivity, you can still connect your robot to a local area network (LAN), or to any relevant devices (such as a gamepad).
+The `viam-server` software resides on your smart machine alongside your configurations, your code, and appropriate services.
+In scenarios without cloud connectivity, you can still connect your smart machine to a local area network (LAN), or to any relevant devices (such as a gamepad).
It all depends on your use case and configuration.
- All APIs work locally or in the cloud
- Data is cached locally and synced when possible
- Configuration is cached
-When your robot is connected (to either LAN or WAN), `viam-server` can act as both a client and a server.
+When your smart machine is connected (to either LAN or WAN), `viam-server` can act as both a client and a server.
In other words, each instance can request resources, as well as provide them.
This allows for tremendous flexibility in terms of your architecture design.
## Scale
-With robots in production, Viam provides [fleet management capabilities](/manage/fleet/) to help you scale.
+With smart machines in production, Viam provides [fleet management capabilities](/manage/fleet/) to help you scale.
With it you can:
- Manage permissions within your organization and locations.
- Manage software across your fleet, including deployment of code and machine learning models.
-- Keep your robot configuration and capabilities up-to-date.
+- Keep your smart machine configuration and capabilities up-to-date.
## Extensibility
-You can also extend Viam to support additional hardware components or software services by deploying a module from the [Viam Registry](https://app.viam.com/registry) to your robot.
+You can also extend Viam to support additional hardware components or software services by deploying a module from the [Viam registry](https://app.viam.com/registry) to your smart machine.
-The Viam Registry allows hardware and software engineers to collaborate on their robotics projects by writing and sharing custom modules with each other.
-You can add a module from the Viam Registry directly from your robot's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **+ Create component** button.
-You can also [upload your own module to the Viam Registry](/extend/modular-resources/upload/).
+The Viam registry allows hardware and software engineers to collaborate on their smart machine projects by writing and sharing custom modules with each other.
+You can add a module from the Viam registry directly from your smart machine's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **+ Create component** button.
+You can also [upload your own module to the Viam registry](/extend/modular-resources/upload/).
See [Modular resources](/extend/modular-resources/) for more information.
## Next steps
-Start by borrowing one of our robots.
+Start by borrowing one of our rovers.
Use [Try Viam](/try-viam/).
-If you already have your own robot, [set up `viam-server`](/installation/) and learn how Viam helps you prototype and scale.
+If you already have your own smart machine, [set up `viam-server`](/installation/) and learn how Viam helps you prototype and scale.
For more inspiration, check out our [tutorials](/tutorials/) or visit our community on [Discord](https://discord.gg/viam) to get help or workshop ideas with others!
Community
- Have questions, or want to meet other people working on robots? Join us in the Community Discord!
+Have questions, or want to meet other people working on smart machines? Join us in the Community Discord!
@@ -200,7 +200,7 @@ The multiple images returned from GetImages do not represent a time series of im ```python {class="line-numbers linkable-line-numbers"} my_camera = Camera.from_robot(robot=robot, name="my_camera") -images, metadata = await my_cam.get_images() +images, metadata = await my_camera.get_images() img0 = images[0].image timestamp = metadata.captured_at ``` @@ -342,7 +342,7 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/c Execute model-specific commands that are not otherwise defined by the component API. For native models, model-specific commands are covered with each model's documentation. -If you are implementing your own camera and add features that have no native API method, you can access them with `DoCommand`. +If you are implementing your own camera and adding features that have no native API method, you can access them with `DoCommand`. {{< tabs >}} {{% tab name="Python" %}} diff --git a/docs/components/component/model1.md b/docs/components/component/model1.md index 5dd335d92a..14cd280dd3 100644 --- a/docs/components/component/model1.md +++ b/docs/components/component/model1.md @@ -17,10 +17,6 @@ Optional additional description/information. {{% tab name="Config Builder" %}} Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). -Click on the **Components** subtab and navigate to the **Create component** menu. - -Enter a name for your arm, select the `arm` type, and select the `model1` model. - Click on the **Components** subtab and click **Create component**. Select the `arm` type, then select the `model1` model. Enter a name for your arm and click **Create**. diff --git a/docs/components/motor/_index.md b/docs/components/motor/_index.md index 6df96e8b11..495333b7a0 100644 --- a/docs/components/motor/_index.md +++ b/docs/components/motor/_index.md @@ -41,6 +41,15 @@ Model | Description [`roboclaw`](./roboclaw/) | [Standard brushed DC motor](https://en.wikipedia.org/wiki/DC_motor) driven by [Basicmicro's](https://www.basicmicro.com/) [RoboClaw](https://www.basicmicro.com/RoboClaw-2x30A-Motor-Controller_p_9.html) motor controller [`fake`](./fake/) | Used to test code without hardware +Viam also provides the following motor models as [modular resources](/extend/modular-resources/): + + Model | Description + ----- | ----------- + [`viam:odrive:canbus`](/extend/modular-resources/examples/odrive/) | An [ODrive S1](https://odriverobotics.com/shop/odrive-s1) motor driver with CANbus communication + [`viam:odrive:serial`](/extend/modular-resources/examples/odrive/) | An [ODrive S1](https://odriverobotics.com/shop/odrive-s1) motor driver with serial communication + +These modules can be [added to your robot from the Viam registry](/extend/modular-resources/configure/#add-a-module-from-the-viam-registry). + ## Control your motor with Viam's client SDK libraries To get started using Viam's SDKs to connect to and control your robot, go to your robot's page on [the Viam app](https://app.viam.com), navigate to the **Code sample** tab, select your preferred programming language, and copy the sample code generated. diff --git a/docs/components/movement-sensor/adxl345.md b/docs/components/movement-sensor/adxl345.md index 8f01de4f43..3d0483a19a 100644 --- a/docs/components/movement-sensor/adxl345.md +++ b/docs/components/movement-sensor/adxl345.md @@ -17,10 +17,9 @@ If you are using a [Viam Rover](https://docs.viam.com/try-viam/), this is the ac {{% tab name="Config Builder" %}} Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). -Click on the **Components** subtab and navigate to the **Create component** menu. -Enter a name for your movement sensor, select the `movement-sensor` type, and select the `accel-adxl345` model. - -Click **Create Component** +Click on the **Components** subtab and click **Create component**. +Select the `movement-sensor` type, then select the `accel-adxl345` model. +Enter a name for your movement sensor and click **Create**. {{< imgproc src="/components/movement-sensor/adxl345-builder.png" alt="Creation of an `accel-adxl345` movement sensor in the Viam app config builder." resize="600x" >}} diff --git a/docs/components/movement-sensor/viam-visual-odometry.md b/docs/components/movement-sensor/viam-visual-odometry.md index 13295a7a29..7e9af1c94e 100644 --- a/docs/components/movement-sensor/viam-visual-odometry.md +++ b/docs/components/movement-sensor/viam-visual-odometry.md @@ -27,8 +27,8 @@ Therefore, you should not consider returned unit measurements trustworthy: inste While `viam-visual-odometry` enables you to add movement sensing abilities to your robot without needing specialized hardware, a dedicated [movement sensor](/components/movement-sensor/) will generally provide more accurate readings. If your robot requires precise awareness of its location and its movement, you should consider using a dedicated movement sensor in addition to the `viam-visual-odometry` module. -The `viam-visual-odometry` module is available [from the Viam Registry](https://app.viam.com/module/viam/monocular-visual-odometry). -See [Modular resources](/extend/modular-resources/#the-viam-registry) for instructions on using a module from the Viam Registry on your robot. +The `viam-visual-odometry` module is available [from the Viam registry](https://app.viam.com/module/viam/monocular-visual-odometry). +See [Modular resources](/extend/modular-resources/#the-viam-registry) for instructions on using a module from the Viam registry on your robot. The source code for this module is available on the [`viam-visual-odometry` GitHub repository](https://github.com/viamrobotics/viam-visual-odometry). diff --git a/docs/components/movement-sensor/wheeled-odometry.md b/docs/components/movement-sensor/wheeled-odometry.md index 0e7d40f571..b26ef4dced 100644 --- a/docs/components/movement-sensor/wheeled-odometry.md +++ b/docs/components/movement-sensor/wheeled-odometry.md @@ -34,7 +34,6 @@ Make sure to configure the base width and circumference, as these measurements a ## Configuration Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). -Click on the **Components** subtab and navigate to the **Create component** menu. Select **Raw JSON** mode. Copy and paste the following: diff --git a/docs/components/sensor/_index.md b/docs/components/sensor/_index.md index 3242130b95..ea75ff27bd 100644 --- a/docs/components/sensor/_index.md +++ b/docs/components/sensor/_index.md @@ -46,6 +46,14 @@ This allows you to have the same access and control of the sensor through Viam a For an example of creating a custom component, see a [WiFi strength sensor built with the Viam Go SDK](https://github.com/viam-labs/wifi-sensor/blob/main/linuxwifi/linuxwifi.go) or [custom resource types implemented with the Viam Python SDK](https://github.com/viamrobotics/viam-python-sdk/tree/main/examples/). +Viam also provides the following sensor model as a [modular resource](/extend/modular-resources/): + + Model | Description + ----- | ----------- + [`viam:visual_odometry:opencv_orb`](/extend/modular-resources/examples/odrive/) | A resource which uses monocular [visual odometry](https://en.wikipedia.org/wiki/Visual_odometry) to enable any [calibrated cameras](/components/camera/calibrate/) to function as a movement sensor + +This module can be [added to your robot from the Viam registry](/extend/modular-resources/configure/#add-a-module-from-the-viam-registry). + ## Control your sensor with Viam's client SDK libraries To get started using Viam's SDKs to connect to and control your robot, go to your robot's page on [the Viam app](https://app.viam.com), navigate to the **Code sample** tab, select your preferred programming language, and copy the sample code generated. diff --git a/docs/components/servo/pi.md b/docs/components/servo/pi.md index 6e15b6d8c1..5868d6caf6 100644 --- a/docs/components/servo/pi.md +++ b/docs/components/servo/pi.md @@ -86,11 +86,11 @@ The following attributes are available for `pi` servos: | ---- | ---- | --------- | ----------- | | `pin` | string | **Required** | The {{< glossary_tooltip term_id="pin-number" text="pin number" >}} of the pin the servo's control wire is wired to on the [board](/components/board/). | | `board` | string | **Required** | `name` of the [board](/components/board/) the servo is wired to. | -| `min` | float | Optional | The minimum angle in degrees that the servo can reach.
Default = `0.0`
Range = [`0.0`, `180.0`] | -| `max` | float | Optional | The maximum angle in degrees that the servo can reach.
Default = `180.0`
Range = [`0.0`, `180.0`] | +| `min` | float | Optional | Sets a software limit on the minimum angle in degrees your servo can rotate to.
Default = `0.0`
Range = [`0.0`, `180.0`] | +| `max` | float | Optional | Sets a software limit on the maximum angle in degrees your servo can rotate to.
Default = `180.0`
Range = [`0.0`, `180.0`] | | `starting_position_degs` | float | Optional | Starting position of the servo in degrees.
Default = `0.0`
Range = [`0.0`, `180.0`] | | `hold_position` | boolean | Optional | If `false`, power down a servo if it has tried and failed to go to a position for a duration of 500 milliseconds.
Default = `true` | -| `max_rotation_deg` | int | Optional | The maximum angle the servo can rotate. Must be in between `min` and `max`.
Default = `180` | +| `max_rotation_deg` | int | Optional | The maximum angle that you know your servo can possibly rotate to, according to its hardware. Refer to your servo's data sheet for clarification. Must be greater than or equal to the value you set for `max`.
Default = `180` | {{% alert title="Tip" color="tip" %}} diff --git a/docs/extend/_index.md b/docs/extend/_index.md index d5c618c8ab..c597873ead 100644 --- a/docs/extend/_index.md +++ b/docs/extend/_index.md @@ -6,7 +6,7 @@ simple_list: true no_list: true type: docs tags: ["server", "rdk", "extending viam", "modular resources", "components", "services"] -description: "Extend Viam with modular resources from the Viam Registry." +description: "Extend Viam with modular resources from the Viam registry." aliases: - "/program/extend/" --- diff --git a/docs/extend/custom-components-remotes.md b/docs/extend/custom-components-remotes.md index 70bcbd8332..8aea4324f5 100644 --- a/docs/extend/custom-components-remotes.md +++ b/docs/extend/custom-components-remotes.md @@ -12,10 +12,10 @@ description: "Implement custom components and register them on a server configur --- {{% alert title="Caution" color="caution" %}} -{{< glossary_tooltip term_id="module" text="Modular resources" >}} are the preferred method of creating custom resource implementations for SDKs with module support unless you are hosting `viam-server` on a non-Linux system or have another issue with compilation. +[Modular resources](/extend/modular-resources/key-concepts/) are the preferred method of creating custom resource implementations for SDKs with module support unless you are hosting `viam-server` on a non-Linux system or have another issue with compilation. {{% /alert %}} -If a type or model of [component](/components/) you are working with is not built-in to the [Viam RDK](/internals/rdk/), you can use a [Viam SDK](/program/apis/) to code a custom resource implementation, host it on a server, and add it as a [remote](/manage/parts-and-remotes/) of your robot. +If a type or model of [component](/components/) you are working with is not [built-in to the Viam RDK](/internals/rdk/), or [available from the Viam Registry as a module](/extend/modular-resources/key-concepts/), you can use a [Viam SDK](/program/apis/) to code a custom resource implementation, host it on a server, and add it as a [remote](/manage/parts-and-remotes/) of your robot. Once you have coded your custom component and configured the remote servers, you can control and monitor your component with the Viam SDKs, like any other component. diff --git a/docs/extend/modular-resources/_index.md b/docs/extend/modular-resources/_index.md index 97e28d9249..bbb60e6a2c 100644 --- a/docs/extend/modular-resources/_index.md +++ b/docs/extend/modular-resources/_index.md @@ -22,30 +22,30 @@ For example, you can: - **Implement fully custom logic:** If your robot runs specialty or proprietary logic, and you want to use Viam to manage and control that logic, such as when managing a software development lifecyle, you can implement your own custom logic by wrapping the generic API. These custom implementations are called {{< glossary_tooltip term_id="module" text="modular resources" >}}, and are made available for use on a robot through [modules](/extend/modular-resources/key-concepts/#modules). -A module can provide one or more modular resources, and can be added to your robot from the Viam Registry. +A module can provide one or more modular resources, and can be added to your robot from the Viam registry. ## The Viam Registry -The [Viam Registry](https://app.viam.com/registry) allows hardware and software engineers to collaborate on their robotics projects by writing and sharing custom modules with each other. -You can add a module from the Viam Registry directly from your robot's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **+ Create component** button. +The [Viam registry](https://app.viam.com/registry) allows hardware and software engineers to collaborate on their robotics projects by writing and sharing custom modules with each other. +You can add a module from the Viam registry directly from your robot's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **+ Create component** button. -The code behind any modular resource can be packaged as a [module](/extend/modular-resources/key-concepts/#modules) and uploaded to the Viam Registry. +The code behind any modular resource can be packaged as a [module](/extend/modular-resources/key-concepts/#modules) and uploaded to the Viam registry. Once the module has been uploaded to the Registry, you can [deploy the module](/extend/modular-resources/configure/) to any robot in your organization from [the Viam app](https://app.viam.com/). ### Uploading to Viam Registry -After you finish programming your module, you can [upload your module to the Viam Registry](/extend/modular-resources/upload/) to make it available for deployment to robots. +After you finish programming your module, you can [upload your module to the Viam registry](/extend/modular-resources/upload/) to make it available for deployment to robots. As part of the upload process, you decide whether your module is *public* (visible to all users) or *private* (visible only to other members of your [organization](/manage/fleet/organizations/)). -You can see details about each module in [the Viam Registry](https://app.viam.com/registry) on its module details page. +You can see details about each module in the [Viam registry](https://app.viam.com/registry) on its module details page. See the [Odrive module](https://app.viam.com/module/viam/odrive) for an example. Public modules also display the number of times a module has been deployed to a robot. -When you make changes to your module, you can [uploaded the newer version](/extend/modular-resources/upload/#update-an-existing-module) with a new version number, and the Viam Registry will track each version that you upload. +When you make changes to your module, you can [uploaded the newer version](/extend/modular-resources/upload/#update-an-existing-module) with a new version number, and the Viam registry will track each version that you upload. ### Deploying to a Robot -Once you [upload a module to the Viam Registry](/extend/modular-resources/upload/), you can [deploy the module](/extend/modular-resources/configure/) to any robot in your organization from [the Viam app](https://app.viam.com/). +Once you [upload a module to the Viam registry](/extend/modular-resources/upload/), you can [deploy the module](/extend/modular-resources/configure/) to any robot in your organization from [the Viam app](https://app.viam.com/). Navigate to your robot's **Configuration** tab, click the **+ Create component** button, then start typing the name of the module you would like to deploy. If you uploaded your module and set its visibility to private, the module will only appear for users within your [organization](/manage/fleet/organizations/). @@ -59,9 +59,9 @@ To get started working with modular resources: - [Create your own module](/extend/modular-resources/create/) implementing at least one modular resource. -- [Upload your module to the Viam Registry](/extend/modular-resources/upload/) to share with the community, or just to your own organization. +- [Upload your module to the Viam registry](/extend/modular-resources/upload/) to share with the community, or just to your own organization. -- Browse [the Viam Registry](https://app.viam.com/registry) to see modules uploaded by other users. +- Browse the [Viam registry](https://app.viam.com/registry) to see modules uploaded by other users. - [Deploy a module](/extend/modular-resources/configure/) to your robot from the Registry. diff --git a/docs/extend/modular-resources/configure.md b/docs/extend/modular-resources/configure.md index 4ead43ea07..1d7a73dc4d 100644 --- a/docs/extend/modular-resources/configure.md +++ b/docs/extend/modular-resources/configure.md @@ -4,87 +4,121 @@ linkTitle: "Configure" weight: 30 type: "docs" tags: ["server", "rdk", "extending viam", "modular resources", "components", "services"] -description: "Add and configure a module from the Viam Registry on your robot." +description: "Add and configure a module from the Viam registry on your robot." no_list: true --- -You can extend Viam by adding a module on your robot to make one or more modular resources available for configuration. -You can [add a module from the Viam Registry](#add-a-module-from-the-viam-registry), or you can [code your own module and add it to your robot locally](#add-a-local-module-to-your-robot). +You can extend Viam by adding a module on your robot that provides one or more {{< glossary_tooltip term_id="resource" text="modular resources" >}} ([components](/components/) or [services](/services/)). +You can [add a module from the Viam registry](#add-a-module-from-the-viam-registry), or you can [code your own module and add it to your robot locally](#add-a-local-module-to-your-robot). -A *module* makes one or more *modular resources* available for configuration. See [Key Concepts of Modular Resource APIs](/extend/modular-resources/key-concepts/) for more information. -## Add a module from the Viam Registry +## Add a module from the Viam registry -The Viam Registry is a central repository of modules from both Viam and the robotics community that allows you to easily extend Viam's capabilities on your robot. +The [Viam registry](https://app.viam.com/registry) is a central repository of modules from both Viam and the robotics community that allows you to easily extend Viam's capabilities on your robot. -To add a module from the Viam Registry to your robot: +A module provides one or more {{< glossary_tooltip term_id="resource" text="modular resources" >}} (either a [component](/components/) or [service](/services/)). + +Follow the instructions below depending on the type of modular resource you would like to add to your robot: + +- [Add a modular component](#add-a-modular-component-from-the-viam-registry) +- [Add a modular service](#add-a-modular-service-from-the-viam-registry) + +### Add a modular component from the Viam registry + +To add a modular [component](/components/) from the Viam registry to your robot: 1. Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). 1. Click on the **Components** subtab and click the **Create component** button. -1. Enter the name of the module you would like to add to your robot. - To find the name of a module you're interested in, you can: +1. Browse the list of available component types, and select the specific modular component you'd like to add. + + {{
Default: `30` | | `video_path` | string | Optional | The filepath to the input sensor of this camera on your board. If none is given, your robot will attempt to detect the video path automatically.
Default: `"0"` | | `debug` | boolean | Optional | Whether or not you want debug input from this camera in your robot's logs.
Default: `false` | + +Then, save the config. + +Check the [**Logs** tab](/program/debug/) of your robot in the Viam app to make sure your camera has connected and no errors are being raised. diff --git a/docs/extend/modular-resources/examples/odrive.md b/docs/extend/modular-resources/examples/odrive.md index 7528327be6..4675a5ea90 100644 --- a/docs/extend/modular-resources/examples/odrive.md +++ b/docs/extend/modular-resources/examples/odrive.md @@ -3,7 +3,7 @@ title: "Add an ODrive motor as a Modular Resource" linkTitle: "ODrive" weight: 40 type: "docs" -description: "How to add an ODrive motor with serial or CANbus communication as a modular resource of your robot." +description: "Configure an ODrive motor with serial or CANbus communication as a modular resource of your robot." tags: ["motor", "odrive", "canbus", "serial", "module", "modular resources", "Python", "python SDK", "CAN"] # SMEs: Kim, Martha, Rand --- @@ -35,7 +35,7 @@ pip3 install python-can cantools viam-sdk Follow [these instructions](https://docs.odriverobotics.com/v/latest/odrivetool.html) to install `odrivetool`. -Find and copy the path (either absolute, or relative to the working directory) to the executable module file `run.sh` on your robot's computer to provide when [configuring the module](#module). +Find and copy the path (either absolute, or relative to the working directory) to the executable module file `run.sh` on your robot's computer to provide when [configuring the module](#configuration). {{% alert title="Tip" color="tip" %}} @@ -52,7 +52,7 @@ pwd 1. Read through the [ODrive documentation](https://docs.odriverobotics.com/v/latest/getting-started.html) to wire, calibrate, and configure your ODrive natively. -{{% alert title="Tip" color="tip" %}} + {{% alert title="Tip" color="tip" %}} This configuration remains on the same ODrive motor controller across reboots, and only changes when you go through the configuration of the ODrive again. @@ -62,26 +62,26 @@ See [add an `odrive_config_file`](#add-an-odrive_config_file) for more informati This option is not recommend for the `canbus` model. -{{% /alert %}} + {{% /alert %}} -Note that `iq_msg_rate_ms` in the `odrive_config_file` defaults to `0`, and you must set this to or around `100` to use the [motor API's `SetPower` method](https://docs.viam.com/components/motor/#setpower). + Note that `iq_msg_rate_ms` in the `odrive_config_file` defaults to `0`, and you must set this to or around `100` to use the [motor API's `SetPower` method](https://docs.viam.com/components/motor/#setpower). 2. Follow [this guide](https://docs.odriverobotics.com/v/latest/control.html#control-doc) to tune your ODrive motor. 3. See the [ODrive CAN documentation](https://docs.odriverobotics.com/v/latest/can-guide.html) for detailed information on how to set up CAN on your ODrive. -{{% alert title="Tip" color="tip" %}} + {{% alert title="Tip" color="tip" %}} If you are using a Raspberry Pi as your [board](/components/board/), you must run `sudo ip link set can0 up type can bitrate
+Viam also provides a lightweight version of `viam-server` which can run on resource-limited embedded systems that cannot run the fully-featured Robot Development Kit (RDK). +If you are using a microcontroller, prepare your board using the following guide: + +{{< cards >}} +{{% card link="/installation/prepare/microcontrollers" class="small" %}} +{{< /cards >}} + Other SBCs such as the [RockPi S](https://wiki.radxa.com/RockpiS) and [Orange Pi Zero 2](https://orangepi.com/index.php?route=product/product&path=237&product_id=849) can run Viam with an experimental [periph.io](https://periph.io/) based [modular component](https://github.com/viam-labs/periph_board). ### Install `viam-server` diff --git a/docs/installation/prepare/jetson-agx-orin-setup.md b/docs/installation/prepare/jetson-agx-orin-setup.md index dae5d93ac6..cc8644cf25 100644 --- a/docs/installation/prepare/jetson-agx-orin-setup.md +++ b/docs/installation/prepare/jetson-agx-orin-setup.md @@ -33,7 +33,7 @@ You need the following hardware, tools, and software to install `viam-server` on **Initial Setup with Display Attached:** -1. A [Jetson AGX Orin Developer Kit](https://www.arrow.com/en/products/945-13730-0000-000/nvidia) +1. A [Jetson AGX Orin Developer Kit](https://developer.nvidia.com/embedded/learn/get-started-jetson-agx-orin-devkit) 2. A PC monitor (HDMI or DisplayPort) 3. USB keyboard and mouse 4. A DisplayPort to HDMI adapter/cable, to connect the Orin to the monitor @@ -42,7 +42,7 @@ You need the following hardware, tools, and software to install `viam-server` on **Initial Setup in Headless Mode:** -1. A [Jetson AGX Orin Developer Kit](https://www.arrow.com/en/products/945-13730-0000-000/nvidia) +1. A [Jetson AGX Orin Developer Kit](https://developer.nvidia.com/embedded/learn/get-started-jetson-agx-orin-devkit) 2. An internet-connected Windows, Linux, or macOS computer 3. A way to connect the computer to the Orin (for example, the USB Type-A to USB Type-C Cable included with the AGX Orin Developer Kit) diff --git a/docs/manage/CLI.md b/docs/manage/CLI.md index a19dcf4ffd..f9cf21b787 100644 --- a/docs/manage/CLI.md +++ b/docs/manage/CLI.md @@ -15,7 +15,7 @@ The CLI lets you: * Retrieve [organization](/manage/fleet/organizations/) and location information * Manage [robot fleet](/manage/fleet/) data and logs * Control robots by issuing component and service commands -* Upload and manage [modular resources](/extend/modular-resources/) in the Viam Registry +* Upload and manage [modular resources](/extend/modular-resources/) in the Viam registry For example, this CLI command moves a servo to the 75 degree position: @@ -29,48 +29,35 @@ viam.component.servo.v1.ServoService.MoveRequest You can download the Viam CLI executable using one of the options below. Select the tab for your platform and architecture. - -{{% alert title="Tip" color="tip" %}} -You can use the `uname -m` command to determine your system architecture. -{{% /alert %}} +If you are on Linux, you can use the `uname -m` command to determine your system architecture. {{< tabs >}} -{{% tab name="Linux aarch64" %}} - -To download the Viam CLI on a Linux computer with the `aarch64` architecture, run the following commands: - -```{class="command-line" data-prompt="$"} -sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64 -sudo chmod a+rx /usr/local/bin/viam -``` - -{{% /tab %}} -{{% tab name="Linux x86_64" %}} +{{% tab name="macOS" %}} -To download the Viam CLI on a Linux computer with the `amd64` (Intel `x86_64`) architecture, run the following commands: +To download the Viam CLI on a macOS computer, run the following commands: ```{class="command-line" data-prompt="$"} -sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64 -sudo chmod a+rx /usr/local/bin/viam +brew tap viamrobotics/brews +brew install viam ``` {{% /tab %}} -{{% tab name="macOS arm64" %}} +{{% tab name="Linux aarch64" %}} -To download the Viam CLI on a macOS computer with the `arm64` (Apple Silicon) architecture, run the following commands: +To download the Viam CLI on a Linux computer with the `aarch64` architecture, run the following commands: ```{class="command-line" data-prompt="$"} -sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-darwin-arm64 +sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64 sudo chmod a+rx /usr/local/bin/viam ``` {{% /tab %}} -{{% tab name="macOS x86_64" %}} +{{% tab name="Linux x86_64" %}} -To download the Viam CLI on a macOS computer with the `amd64` (Intel `x86_64`) architecture, run the following commands: +To download the Viam CLI on a Linux computer with the `amd64` (Intel `x86_64`) architecture, run the following commands: ```{class="command-line" data-prompt="$"} -sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-darwin-amd64 +sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64 sudo chmod a+rx /usr/local/bin/viam ``` @@ -95,7 +82,8 @@ echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc {{% /tab %}} {{< /tabs >}} -To later update the Viam CLI tool, you can use the steps above to reinstall the latest version. +To later update the Viam CLI tool on Linux, use the steps above to reinstall the latest version. +to later update the Viam CLI tool on macOS, run `brew upgrade viam`. ## Authenticate @@ -304,8 +292,8 @@ This includes: * Creating a new custom modular resource * Updating an existing module with new changes -* Uploading a new module to the Viam Registry -* Updating an existing module in the Viam Registry +* Uploading a new module to the Viam registry +* Updating an existing module in the Viam registry ```sh {class="command-line" data-prompt="$"} viam module create --name
| {{ Try a Viam Rover in our robotics lab. Control, drive, or program the rover to see how you can build a robot with Viam. You can also try services like computer vision. +Try a Viam Rover in our robotics lab. Control, drive, or program the rover to see how you can build a smart machine with Viam. You can also try services like computer vision. |
+
- **Hardware**:
-Many {{< glossary_tooltip term_id="component" text="robotic components">}} are natively supported by the Viam platform.
+Many {{< glossary_tooltip term_id="component" text="components">}} are natively supported by the Viam platform.
You will not need to write a single line of code to integrate them, and swapping out component models will not require code changes.
- **Functionality**:
You can make use of computer vision, motion planning, SLAM, data management, machine learning, and more by configuring Viam's built-in {{< glossary_tooltip term_id="service" text="services">}}.
- **Architecture**:
-You can build simple robots or multi-part robots that use secure communication channels across local networks and the cloud, all of which can be managed with a uniform API.
-- **Extensibility**: If you need additional functionality, you can leverage community contributed and modular resources to [extend](/extend/) Viam from [the Viam Registry](/extend/modular-resources/).
+You can build simple smart machines or multi-part smart machines that use secure communication channels across local networks and the cloud, all of which can be managed with a uniform API.
+- **Extensibility**: If you need additional functionality, you can leverage community contributed and modular resources to [extend](/extend/) Viam from [the Viam registry](/extend/modular-resources/).
Join the [**Viam community**](https://discord.gg/viam) to collaborate during planning and beyond.
## Get started
-A *robot* in Viam consists of at least one computer, typically a [single-board computer](/installation/), running `viam-server` and communicating with any hardware connected to it by signaling through digital data pins.
+A *smart machine* in Viam consists of at least one computer, typically a [single-board computer](/installation/), running `viam-server` and communicating with any hardware connected to it by signaling through digital data pins.
Viam supports devices running **any** 64-bit Linux OS or macOS.
{{< imgproc src="/viam/board-viam-server.png" alt="A diagram of a single-board computer running viam-server." resize="270x" class="alignleft" style="max-width:270px" >}}
-The Viam platform provides a user interface for connecting to and managing robots, the [Viam app](https://app.viam.com/).
+The Viam platform provides a user interface for connecting to and managing smart machines, the [Viam app](https://app.viam.com/).
-To use the Viam platform with your robot, log in to [the app](https://app.viam.com/), create a new robot, and [install](/installation/) the [`viam-server`](https://github.com/viamrobotics/rdk) binary which:
+To use the Viam platform with your smart machine, log in to [the app](https://app.viam.com/), create a new robot, and [install](/installation/) the [`viam-server`](https://github.com/viamrobotics/rdk) binary which:
-- Creates, configures, and maintains the robot.
+- Creates, configures, and maintains the smart machine.
- Securely handles all communications.
- Runs drivers, custom code, and any other software.
- Accepts API requests.
- Runs services like computer vision, data synchronization, and motion planning.
{{% alert title="Info" color="info" %}}
-Everything Viam runs on your robot is [open-source](https://github.com/viamrobotics).
+Everything Viam runs on your smart machine is [open-source](https://github.com/viamrobotics).
{{% /alert %}}
-## Configure your robot
+## Configure your smart machine
Robots can be small and simple or very complex.
-A robot can be a single-board computer with a single sensor or LED wired to it, or a robot can consist of multiple computers with many physical components connected, acting as one unit.
+A smart machine can be a single-board computer with a single sensor or LED wired to it, or a smart machine can consist of multiple computers with many physical components connected, acting as one unit.
The term {{% glossary_tooltip term_id="component" text="*component*" %}} describes a piece of hardware that a computer controls, like an arm or a motor.
-For each component that makes up your robot:
+For each component that makes up your smart machine:
{{< imgproc src="/viam/test_components.png" alt="Multiple components being tested in the Viam app." resize="320x" style="max-width:320px" class="alignright" >}} @@ -71,32 +71,32 @@ For each component that makes up your robot: 2. Test it with the visual [control tab](/manage/fleet/robots/#control). 3. See any problems with in-app [logs](/manage/fleet/robots/#logs), review or roll back configuration [history](/manage/fleet/robots/#history). -After configuring your robot's hardware, you can configure [high level functionality](/services/) the same way: +After configuring your smart machine's hardware, you can configure [high level functionality](/services/) the same way: -- **Data Management** enables you to capture and sync data from one or more robots, and use that data for machine learning and beyond. -- **Fleet management** enables you to configure, control, debug, and manage entire fleets of robots. -- **Motion planning** enables your robot to plan and move itself. -- **Vision** enables your robot to intelligently see and interpret the world around it. -- **Simultaneous Localization And Mapping (SLAM)** enables your robot to map its surroundings and find its position on a map. +- **Data Management** enables you to capture and sync data from one or more smart machine, and use that data for machine learning and beyond. +- **Fleet management** enables you to configure, control, debug, and manage entire fleets of smart machines. +- **Motion planning** enables your smart machine to plan and move itself. +- **Vision** enables your smart machine to intelligently see and interpret the world around it. +- **Simultaneous Localization And Mapping (SLAM)** enables your smart machine to map its surroundings and find its position on a map.
{{< imgproc src="/viam/robot-components.png" alt="Robot components" resize="600x" class="aligncenter" >}}
-## Control your robot
+## Control your smart machine
-
+
-The Viam platform provides a consistent programming interface for all robots, allowing you to [control your robots](/program/apis/) with code in the **language of your choice**.
+The Viam platform provides a consistent programming interface for all smart machines, allowing you to [control your smart machines](/program/apis/) with code in the **language of your choice**.
Viam currently has SDKs for [Go](https://pkg.go.dev/go.viam.com/rdk), [Python](https://python.viam.dev/), and [TypeScript](https://ts.viam.dev/).
Additional SDKs are coming soon, including Rust, Java, C++, and Flutter.
TLS certificates provided by [app.viam.com](https://app.viam.com) ensure that all communication is authenticated and encrypted.
-Viam uses {{< glossary_tooltip term_id="webrtc" >}} to create secure peer-to-peer paths between robots and clients for fast, low-latency communication.
-The Viam cloud does not receive any command or control information regarding your robots, ensuring low latency, robustness, and privacy.
-With WebRTC established, Viam uses {{< glossary_tooltip term_id="grpc" text="gRPC" >}} so you can program your robot in many common programming languages.
+Viam uses {{< glossary_tooltip term_id="webrtc" >}} to create secure peer-to-peer paths between smart machines and clients for fast, low-latency communication.
+The Viam cloud does not receive any command or control information regarding your smart machines, ensuring low latency, robustness, and privacy.
+With WebRTC established, Viam uses {{< glossary_tooltip term_id="grpc" text="gRPC" >}} so you can program your smart machines in many common programming languages.
-This provides flexibility and security whether you are building tight control loops for autonomous mobile robots, event-based triggers for IoT devices, or custom web-based robot management interfaces.
+This provides flexibility and security whether you are building tight control loops for autonomous mobile smart machines, event-based triggers for IoT devices, or custom web-based smart machine management interfaces.
There are four categories of APIs:
@@ -109,44 +109,44 @@ You can see the Viam API specification on [GitHub](https://github.com/viamroboti
### Network flexibility
-Your robot does not need to be connected to the cloud.
+Your smart machine does not need to be connected to the cloud.
-The `viam-server` software resides on your robot alongside your configurations, your code, and appropriate services.
-In scenarios without cloud connectivity, you can still connect your robot to a local area network (LAN), or to any relevant devices (such as a gamepad).
+The `viam-server` software resides on your smart machine alongside your configurations, your code, and appropriate services.
+In scenarios without cloud connectivity, you can still connect your smart machine to a local area network (LAN), or to any relevant devices (such as a gamepad).
It all depends on your use case and configuration.
- All APIs work locally or in the cloud
- Data is cached locally and synced when possible
- Configuration is cached
-When your robot is connected (to either LAN or WAN), `viam-server` can act as both a client and a server.
+When your smart machine is connected (to either LAN or WAN), `viam-server` can act as both a client and a server.
In other words, each instance can request resources, as well as provide them.
This allows for tremendous flexibility in terms of your architecture design.
## Scale
-With robots in production, Viam provides [fleet management capabilities](/manage/fleet/) to help you scale.
+With smart machines in production, Viam provides [fleet management capabilities](/manage/fleet/) to help you scale.
With it you can:
- Manage permissions within your organization and locations.
- Manage software across your fleet, including deployment of code and machine learning models.
-- Keep your robot configuration and capabilities up-to-date.
+- Keep your smart machine configuration and capabilities up-to-date.
## Extensibility
-You can also extend Viam to support additional hardware components or software services by deploying a module from the [Viam Registry](https://app.viam.com/registry) to your robot.
+You can also extend Viam to support additional hardware components or software services by deploying a module from the [Viam registry](https://app.viam.com/registry) to your smart machine.
-The Viam Registry allows hardware and software engineers to collaborate on their robotics projects by writing and sharing custom modules with each other.
-You can add a module from the Viam Registry directly from your robot's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **+ Create component** button.
-You can also [upload your own module to the Viam Registry](/extend/modular-resources/upload/).
+The Viam registry allows hardware and software engineers to collaborate on their smart machine projects by writing and sharing custom modules with each other.
+You can add a module from the Viam registry directly from your smart machine's **Configuration** tab in [the Viam app](https://app.viam.com/), using the **+ Create component** button.
+You can also [upload your own module to the Viam registry](/extend/modular-resources/upload/).
See [Modular resources](/extend/modular-resources/) for more information.
## Next steps
-Start by borrowing one of our robots.
+Start by borrowing one of our rovers.
Use [Try Viam](/try-viam/).
-If you already have your own robot, [set up `viam-server`](/installation/) and learn how Viam helps you prototype and scale.
+If you already have your own smart machine, [set up `viam-server`](/installation/) and learn how Viam helps you prototype and scale.
For more inspiration, check out our [tutorials](/tutorials/) or visit our community on [Discord](https://discord.gg/viam) to get help or workshop ideas with others!