Skip to content

Commit

Permalink
DOCS-1089: Update Modular resource examples to use new UI (#1806)
Browse files Browse the repository at this point in the history 
Co-authored-by: andf-viam <[email protected]>
  • Loading branch information
@npentrel @andf-viam
npentrel and andf-viam authored Sep 12, 2023
1 parent cf00f2f commit cc1a39a
Show file tree
Hide file tree
Showing 4 changed files with 249 additions and 141 deletions.
78 changes: 51 additions & 27 deletions docs/extend/modular-resources/examples/csi.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/).
Expand All @@ -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
Expand All @@ -32,40 +31,63 @@ 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": <int>,
"height_px": <int>,
"frame_rate": <int>,
"debug": "<boolean>"
}
```

{{% /tab %}}
{{% tab name="JSON Template" %}}

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 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": "</usr/bin/csi-mr>",
"name": "<your-csi-cam-module-name>"
}
]
"executable_path": "</usr/local/bin/viam-csi>",
"name": "<your-csi-cam-module-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": <int>,
"height_px": <int>,
"frame_rate": <int>,
"debug": "<boolean>"
},
"depends_on": [],
"name": "<your-csi-cam-name>",
"namespace": "rdk",
"type": "camera"
}
{
"model": "viam:camera:csi",
"attributes": {
"width_px": <int>,
"height_px": <int>,
"frame_rate": <int>,
"debug": "<boolean>"
},
"depends_on": [],
"name": "<your-csi-cam-name>",
"namespace": "rdk",
"type": "camera"
}
```

{{% /tab %}}
Expand All @@ -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": [
Expand All @@ -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:

Expand All @@ -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. <br> 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. <br> Default: `"0"` </br> |
| `debug` | boolean | Optional | Whether or not you want debug input from this camera in your robot's logs. <br> 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.
113 changes: 58 additions & 55 deletions docs/extend/modular-resources/examples/odrive.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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" %}}

Expand All @@ -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.

Expand All @@ -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 <baud_rate>` 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.
Expand All @@ -93,82 +93,84 @@ 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, <file>run.sh</file>, 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, <file>run.sh</file>, is stored on your robot’s computer.
Then click **Add module**.

![The ODrive module with the name 'odrive' and executable path '~/desktop/odrive/odrive-motor/run.sh' added to a robot in the Viam app config builder](/extend/modular-resources/add-odrive/add-odrive-module-ui.png)

{{% /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": "<your/path/to/odrive/odrive-motor/run.sh>"
}
]
{
"width_px": <int>,
"height_px": <int>,
"frame_rate": <int>,
"debug": "<boolean>"
}
```

{{% /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": "<your/path/to/odrive/odrive-motor/run.sh>"
}
```

{{< 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": {
},
"depends_on": [],
"type": "motor",
"name": "<your-odrive-motor>"
}
]
}
```
}
```

{{% /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": {
Expand All @@ -177,10 +179,11 @@ Copy and paste the following JSON along with your module JSON depending on your
"depends_on": [],
"type": "motor",
"name": "<your-odrive-motor>"
}
]
}
```
}
```

{{% /tab %}}
{{< /tabs >}}

{{% /tab %}}
{{% tab name="JSON Example" %}}
Expand Down Expand Up @@ -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 |
Expand All @@ -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:

Expand Down
Loading

0 comments on commit cc1a39a

Please sign in to comment.