diff --git a/assets/components/camera/configure-ultrasonic.png b/assets/components/camera/configure-ultrasonic.png new file mode 100644 index 0000000000..ca22858076 Binary files /dev/null and b/assets/components/camera/configure-ultrasonic.png differ diff --git a/assets/components/sensor/ultrasonic-sensor-ui-config.png b/assets/components/sensor/ultrasonic-sensor-ui-config.png index beef85d8ee..84e0b8a6a0 100644 Binary files a/assets/components/sensor/ultrasonic-sensor-ui-config.png and b/assets/components/sensor/ultrasonic-sensor-ui-config.png differ diff --git a/docs/components/camera/_index.md b/docs/components/camera/_index.md index 96dae86a44..97edbe59e9 100644 --- a/docs/components/camera/_index.md +++ b/docs/components/camera/_index.md @@ -51,6 +51,7 @@ For configuration information, click on one of the supported camera models: | [`align_color_depth_homography`](align-color-depth-homography/) | Uses a homography matrix to align the color and depth images. | | [`join_pointclouds`](join-pointclouds/) | Combines the point clouds from multiple camera sources and projects them to be from the point of view of target_frame. | | [`transform`](transform/) | A pipeline for applying transformations to an input image source. | +| [`ultrasonic`](ultrasonic/) | An ultrasonic distance sensor like the [HC-S204](https://www.sparkfun.com/products/15569). | Viam also provides the following camera models as [modular resources](/extend/modular-resources/): diff --git a/docs/components/camera/ultrasonic.md b/docs/components/camera/ultrasonic.md new file mode 100644 index 0000000000..ce3cf92c76 --- /dev/null +++ b/docs/components/camera/ultrasonic.md @@ -0,0 +1,85 @@ +--- +title: "Configure an ultrasonic Camera" +linkTitle: "ultrasonic" +weight: 60 +type: "docs" +description: "Configure an ultrasonic model camera." +tags: ["camera", "components", "ultrasonic"] +icon: "/icons/components/camera.svg" +images: ["/icons/components/camera.svg"] +# SME: #team-bucket +--- + +{{< alert title="Usage" color="tip" >}} +An ultrasonic distance sensor can also be configured as a [sensor](/components/sensor/) resource. +When configured as a sensor, you can use the sensor method [`GetReadings()`](/components/sensor/#getreadings), rather than the camera method [`GetPointCloud()`](/components/camera/#getpointcloud). +{{< /alert >}} + +Configure an `ultrasonic` camera to integrate an ultrasonic distance sensor like the [HC-S204](https://www.sparkfun.com/products/15569) into your robot: + +{{< tabs >}} +{{% 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 click **Create component**. +Select the `camera` type, then select the `ultrasonic` model. +Enter a name for your camera and click **Create**. + +![Creation of a ultrasonic camera in the Viam app config builder.](/components/camera/configure-ultrasonic.png) + +Edit and fill in the attributes as applicable. + +{{% /tab %}} +{{% tab name="JSON Template" %}} + +```json {class="line-numbers linkable-line-numbers"} +{ + "components": [ + { + "name": "", + "type": "camera", + "model": "ultrasonic", + "attributes": { + "trigger_pin": "", + "echo_interrupt_pin": "", + "board": "", + "timeout_ms": + }, + "depends_on": [] + } + ] +} +``` + +{{% /tab %}} +{{% tab name="JSON Example" %}} + +```json {class="line-numbers linkable-line-numbers"} +{ + "components": [ + { + "name": "your-ultrasonic-sensor", + "type": "camera", + "model": "ultrasonic", + "attributes": { + "trigger_pin": "5", + "echo_interrupt_pin": "15", + "board": "your-board-name", + "timeout_ms": "1000" + }, + "depends_on": [] + } + ] +} +``` + +{{% /tab %}} +{{% /tabs %}} + +The following attributes are available for `ultrasonic` cameras: + +{{< readfile "/static/include/components/ultrasonic-attributes.md" >}} + +## Next Steps + +{{< readfile "/static/include/components/camera-model-next-steps.md" >}} diff --git a/docs/components/sensor/_index.md b/docs/components/sensor/_index.md index fd8a18b6d0..9441975318 100644 --- a/docs/components/sensor/_index.md +++ b/docs/components/sensor/_index.md @@ -37,7 +37,7 @@ For configuration information, click on one of the supported sensor models: | Model | Description | | ----- | ----------- | | [`fake`](fake/) | A model used for testing, with no physical hardware. | -| [`ultrasonic`](ultrasonic/) | [HC-S204 ultrasonic distance sensor](https://www.sparkfun.com/products/15569) | +| [`ultrasonic`](ultrasonic/) | An ultrasonic distance sensor like the [HC-S204](https://www.sparkfun.com/products/15569) | | [`bme280`](bme280/) | [BME280 environmental sensor](https://www.adafruit.com/product/2652) | | [`ds18b20`](ds18b20/) | [DallasTemperature DS18B20 digital temperature sensor](https://www.adafruit.com/product/381) | | [`sensirion-sht3xd`](sensirion-sht3xd/) | [Sensirion SHT3x-DIS temperature and humidity sensor](https://www.adafruit.com/product/2857) | diff --git a/docs/components/sensor/ultrasonic.md b/docs/components/sensor/ultrasonic.md index 967dd37d5d..c091330946 100644 --- a/docs/components/sensor/ultrasonic.md +++ b/docs/components/sensor/ultrasonic.md @@ -4,13 +4,20 @@ linkTitle: "ultrasonic" weight: 60 type: "docs" description: "Configure an ultrasonic model sensor." -tags: ["sensor", "components"] +tags: ["sensor", "components", "ultrasonic"] icon: "/icons/components/sensor.svg" images: ["/icons/components/sensor.svg"] # SME: #team-bucket --- -Configure an `ultrasonic` sensor to integrate an [HC-S204 ultrasonic distance sensor](https://www.sparkfun.com/products/15569) into your robot: +{{< alert title="Tip" color="tip" >}} +An ultrasonic distance sensor can also be configured as a [camera](/components/camera/) resource. + +When configured as a camera, you can use the camera method [`GetPointCloud()`](/components/camera/#getpointcloud), rather than the sensor method [`GetReadings()`](/components/sensor/#getreadings). +Additionally, you can use the camera component as an input to a [vision service](/services/vision/) model that returns obstacles. +{{< /alert >}} + +Configure an `ultrasonic` sensor to integrate an ultrasonic distance sensor like the [HC-S204](https://www.sparkfun.com/products/15569) into your robot: {{< tabs >}} {{% tab name="Config Builder" %}} @@ -73,12 +80,6 @@ Edit and fill in the attributes as applicable. The following attributes are available for `ultrasonic` sensors: - -| Attribute | Type | Inclusion | Description | -| --------- | ---- | --------- | ----------- | -| `board` | string | **Required** | The `name` of the [board](/components/board/) the sensor is wired to. | -| `trigger_pin` | string | **Required** | The {{< glossary_tooltip term_id="pin-number" text="pin number" >}} on the [board](/components/board/) that you have wired [the sensor's trigger pin](https://www.sparkfun.com/products/15569). | -| `echo_interrupt_pin` | string | **Required** | The {{< glossary_tooltip term_id="pin-number" text="pin number" >}} of the pin [the sensor's echo pin](https://www.sparkfun.com/products/15569) is wired to on the board. If you have already created a [digital interrupt](/components/board/#digital_interrupts) for this pin in the [board's configuration](/components/board/), use that digital interrupt's `name` instead. | -| `timeout_ms` | int | Optional | Time to wait in milliseconds before timing out of requesting to get readings from the sensor.
Default: `1000`. | +{{< readfile "/static/include/components/ultrasonic-attributes.md" >}} {{< readfile "/static/include/components/test-control/sensor-control.md" >}} diff --git a/static/include/components/ultrasonic-attributes.md b/static/include/components/ultrasonic-attributes.md new file mode 100644 index 0000000000..e1f8088ef1 --- /dev/null +++ b/static/include/components/ultrasonic-attributes.md @@ -0,0 +1,7 @@ + +| Attribute | Type | Inclusion | Description | +| --------- | ---- | --------- | ----------- | +| `board` | string | **Required** | The `name` of the [board](/components/board/) the ultrasonic is wired to. | +| `trigger_pin` | string | **Required** | The {{< glossary_tooltip term_id="pin-number" text="pin number" >}} of the [board's](/components/board/) GPIO pin that you have wired [the ultrasonic's trigger pin](https://www.sparkfun.com/products/15569) to. | +| `echo_interrupt_pin` | string | **Required** | The {{< glossary_tooltip term_id="pin-number" text="pin number" >}} of the pin [the ultrasonic's echo pin](https://www.sparkfun.com/products/15569) is wired to on the board. If you have already created a [digital interrupt](/components/board/#digital_interrupts) for this pin in the [board's configuration](/components/board/), use that digital interrupt's `name` instead. | +| `timeout_ms` | int | Optional | Time to wait in milliseconds before timing out of requesting to get ultrasonic distance readings.
Default: `1000`. |