diff --git a/assets/services/navigation/configure-base-geometry.png b/assets/services/navigation/configure-base-geometry.png new file mode 100644 index 0000000000..c2adcd05b4 Binary files /dev/null and b/assets/services/navigation/configure-base-geometry.png differ diff --git a/assets/services/navigation/full-frame-movement-sensor-ui.png b/assets/services/navigation/full-frame-movement-sensor-ui.png new file mode 100644 index 0000000000..54cbfa5e70 Binary files /dev/null and b/assets/services/navigation/full-frame-movement-sensor-ui.png differ diff --git a/assets/services/navigation/navigation-control-card.png b/assets/services/navigation/navigation-control-card.png new file mode 100644 index 0000000000..651e99a699 Binary files /dev/null and b/assets/services/navigation/navigation-control-card.png differ diff --git a/assets/services/navigation/navigation-ui-config.png b/assets/services/navigation/navigation-ui-config.png new file mode 100644 index 0000000000..c0a8386b21 Binary files /dev/null and b/assets/services/navigation/navigation-ui-config.png differ diff --git a/assets/services/navigation/select-base-frame.png b/assets/services/navigation/select-base-frame.png new file mode 100644 index 0000000000..6625913f89 Binary files /dev/null and b/assets/services/navigation/select-base-frame.png differ diff --git a/docs/reference/apis/_index.md b/docs/reference/apis/_index.md index 8610f7f82e..89269c3663 100644 --- a/docs/reference/apis/_index.md +++ b/docs/reference/apis/_index.md @@ -11,11 +11,6 @@ aliases: - /program/apis/ - /build/program/apis/ - /appendix/apis/ - - /reference/apis/services/SLAM/ - - /reference/apis/services/slam/ - - /dev/reference/apis/services/SLAM/ - - /dev/reference/apis/services/slam/ - - /appendix/apis/services/slam/ no_list: true date: "2024-10-01" # updated: "" # When the content was last entirely checked @@ -111,7 +106,6 @@ See every service API and its methods at a glance in one compact grid. {{% card link="/reference/apis/services/vision/" customTitle="Vision service API" noimage="True" %}} {{% card link="/reference/apis/services/ml/" customTitle="ML model service API" noimage="True" %}} {{% card link="/reference/apis/services/motion/" customTitle="Motion service API" noimage="True" %}} -{{% card link="/reference/apis/services/navigation/" customTitle="Navigation service API" noimage="True" %}} {{% card link="/reference/apis/services/generic/" customTitle="Generic service API" noimage="True" %}} {{% card link="/reference/apis/services/base-rc/" customTitle="Base Remote Control service API" noimage="True" %}} {{% card link="/reference/apis/services/discovery/" customTitle="Discovery service API" noimage="True" %}} diff --git a/docs/reference/apis/services/navigation.md b/docs/reference/apis/services/navigation.md index 85f9ed27a4..c699e0661a 100644 --- a/docs/reference/apis/services/navigation.md +++ b/docs/reference/apis/services/navigation.md @@ -3,13 +3,29 @@ title: "Navigation service API" linkTitle: "Navigation" weight: 70 type: "docs" -description: "The navigation service API has been removed." -date: "2026-05-22" +tags: ["navigation", "services", "base", "rover"] +description: "Give commands to define waypoints and move your machine along those waypoints while avoiding obstacles." +date: "2022-01-01" aliases: - /dev/reference/apis/services/navigation/ - /appendix/apis/services/navigation/ +build: + render: always + list: never + publishResources: true --- -The navigation service API has been removed. +{{< alert title="Discontinued" color="caution" >}} +Support for the navigation service has been discontinued. +This page is retained for reference only. +{{< /alert >}} -For motion planning APIs, see [Motion service API](/reference/apis/services/motion/). +The navigation service API allows you to define waypoints and move your machine along those waypoints while avoiding obstacles. + +The [navigation service](/reference/services/navigation/) supports the following methods: + +{{< readfile "/static/include/services/apis/generated/navigation-table.md" >}} + +## API + +{{< readfile "/static/include/services/apis/generated/navigation.md" >}} diff --git a/docs/reference/apis/services/slam.md b/docs/reference/apis/services/slam.md new file mode 100644 index 0000000000..04c8fabd1d --- /dev/null +++ b/docs/reference/apis/services/slam.md @@ -0,0 +1,31 @@ +--- +title: "SLAM service API" +linkTitle: "SLAM" +weight: 60 +type: "docs" +tags: ["slam", "services"] +description: "Give commands to get a machine's position within a map." +date: "2022-01-01" +aliases: + - /dev/reference/apis/services/slam/ + - /appendix/apis/services/slam/ +build: + render: always + list: never + publishResources: true +--- + +{{< alert title="Discontinued" color="caution" >}} +Support for the SLAM service has been discontinued. +This page is retained for reference only. +{{< /alert >}} + +The SLAM service API allows you to get a machine's position within a map. + +The [SLAM service](/reference/services/slam/) supports the following methods: + +{{< readfile "/static/include/services/apis/generated/slam-table.md" >}} + +## API + +{{< readfile "/static/include/services/apis/generated/slam.md" >}} diff --git a/docs/reference/services/_index.md b/docs/reference/services/_index.md index d2d151365f..5cf21bc8be 100644 --- a/docs/reference/services/_index.md +++ b/docs/reference/services/_index.md @@ -19,7 +19,6 @@ Configuration reference for Viam built-in services. Each page covers available m {{% card link="/reference/services/frame-system/" %}} {{% card link="/reference/services/generic/" %}} {{% card link="/reference/services/motion/" %}} -{{% card link="/reference/services/navigation/" %}} {{% card link="/reference/services/vision/" %}} {{% card link="/reference/services/motion/" %}} {{< /cards >}} diff --git a/docs/reference/services/navigation/_index.md b/docs/reference/services/navigation/_index.md index 230ee56a5e..f85ba3742e 100644 --- a/docs/reference/services/navigation/_index.md +++ b/docs/reference/services/navigation/_index.md @@ -1,17 +1,383 @@ --- title: "Navigation service" linkTitle: "Navigation" -description: "The navigation service has been removed. Use the motion service for collision-free motion planning." -layout: "docs" -type: "docs" weight: 50 -date: "2026-05-22" +type: "docs" +description: "The navigation service uses GPS to autonomously navigate a rover to user-defined waypoints." +tags: ["navigation", "services", "base", "rover"] +date: "2022-01-01" aliases: - - "/operate/reference/services/navigation/" + - /operate/reference/services/navigation/ - /services/navigation/ - /mobility/navigation/ +build: + render: always + list: never + publishResources: true --- -The navigation service has been removed. +{{< alert title="Discontinued" color="caution" >}} +Support for the navigation service has been discontinued. +This page is retained for reference only. +{{< /alert >}} + +The navigation service is the stateful definition of Viam's [motion service](/reference/services/motion/). +It uses GPS to autonomously navigate a rover [base](/reference/components/base/) to user-defined waypoints. + +Configure your base with a navigation service, add waypoints, and set the mode of the service to [**Waypoint**](/reference/apis/services/navigation/#setmode) to move your rover along a defined path at your desired motion configuration. + +## Requirements + +You must configure a [base](/reference/components/base/) with [movement sensors](/reference/components/movement-sensor/) as part of your machine to configure a navigation service. + +To use the navigation service, configure a stack of movement sensors that implement the following methods in their {{< glossary_tooltip term_id="model" text="models'" >}} implementations of the [movement sensor API](/reference/apis/components/movement-sensor/#api): + +- [`GetPosition()`](/reference/apis/components/movement-sensor/#getposition) +- [`GetCompassHeading()`](/reference/apis/components/movement-sensor/#getcompassheading) +- [`GetProperties()`](/reference/apis/components/movement-sensor/#getproperties) + +The base should implement the following: + +- [`SetVelocity()`](/reference/apis/components/base/#setvelocity) +- [`GetGeometries()`](/reference/apis/components/base/#getgeometries) +- [`GetProperties()`](/reference/apis/components/base/#getproperties) + +See [navigation concepts](#navigation-concepts) for more info on how to implement and use movement sensors taking these measurements. + +## Configuration + +First, make sure your base is physically assembled and powered on. +Then, configure the service: + +{{< tabs >}} +{{% tab name="Config Builder" %}} + +Navigate to the **CONFIGURE** tab of your machine's page. +Click the **+** icon next to your machine part in the left-hand menu and select **Configuration block**. +Select the `navigation` type. +Enter a name or use the suggested name for your service and click **Create**. + +{{}} + +Edit the attributes as applicable to your machine, according to the table below. + +{{% /tab %}} +{{% tab name="JSON Template" %}} + +```json {class="line-numbers linkable-line-numbers"} +"services": [ +{ + "name": "your-navigation-service", + "api": "rdk:service:navigation", + "model": "rdk:builtin:builtin", + "attributes": { + "store": { + "type": "" + }, + "movement_sensor": "", + "base": "", + "obstacle_detectors": [ + { + "vision_service": "", + "camera": "" + } + ] + } +} + ... // Other services +] +``` + +{{% /tab %}} +{{% tab name="JSON Example" %}} + +```json {class="line-numbers linkable-line-numbers"} +{ + "name": "test_navigation", + "api": "rdk:service:navigation", + "model": "rdk:builtin:builtin", + "attributes": { + "store": { + "type": "mongodb", + // Remove "config": { ... } below if using "type": "memory" + "config": { + "uri": "mongodb://127.0.0.1:12345" + } + } + }, + "movement_sensor": "your-movement-sensor", + "obstacle_detectors": [ + { + "vision_service": "your-vision-service", + "camera": "your-camera" + }, + { + "vision_service": "your-vision-service-2", + "camera": "your-camera-2" + } + ] + "base": "your-base", + "obstacles": [ + { + "geometries": [ + { + "label": "your-label-for-this-obstacle", + "orientation": { + "type": "ov_degrees", + "value": { + "x": 1, + "y": 0, + "z": 0, + "th": 90 + } + }, + "x": 10, + "y": 10, + "z": 10 + } + ], + "location": { + "latitude": 1, + "longitude": 1 + } + } + ] +} +``` + +{{% /tab %}} +{{< /tabs >}} + +Edit and fill in the attributes as applicable. +The following attributes are available for `Navigation` services: + + +| Name | Type | Required? | Description | +| ---- | ---- | --------- | ----------- | +| `store` | obj | **Required** | The type and configuration of data storage to use. Either type `"memory"`, where no additional configuration is needed and the waypoints are stored in local memory while the navigation process is running, or `"mongodb"`, where data persists at the specified [MongoDB URI](https://www.mongodb.com/docs/manual/reference/connection-string) of your MongoDB deployment.
Default: `"memory"` | +| `base` | string | **Required** | The `name` you have configured for the [base](/reference/components/base/) you are operating with this service. | +| `movement_sensor` | string | **Required** | The `name` of the [movement sensor](/reference/components/movement-sensor/) you have configured for the base you are operating with this service. | +| `motion_service` | string | Optional | The `name` of the [motion service](/reference/services/motion/) you have configured for the base you are operating with this service. If you have not added a motion service to your machine, the default motion service will be used. Reference this default service in your code with the name `"builtin"`. | +| `obstacle_detectors` | array | Optional | An array containing objects with the `name` of each [`"camera"`](/reference/components/camera/) you have configured for the base you are navigating, along with the `name` of the [`"vision_service"`](/reference/services/motion/) you are using to detect obstacles. Note that any vision services on remote parts will only be able to access cameras on the same remote part. | +| `position_polling_frequency_hz` | float | Optional | The frequency in Hz to poll for the position of the machine.
Default: `1` | +| `obstacle_polling_frequency_hz` | float | Optional | The frequency in Hz to poll each vision service for new obstacles.
Default: `1` | +| `plan_deviation_m` | float | Optional | The distance in meters that a machine is allowed to deviate from the motion plan.
Default: `2.6`| +| `degs_per_sec` | float | Optional | The default angular velocity for the [base](/reference/components/base/) in degrees per second.
Default: `20` | +| `meters_per_sec` | float | Optional | The default linear velocity for the [base](/reference/components/base/) in meters per second.
Default: `0.3` | +| `obstacles` | obj | Optional | Any obstacles you wish to add to the machine's path. See the [motion service](/reference/services/motion/) for more information. | +| `bounding_regions` | obj | Optional | Set of bounds which the robot must remain within while navigating. See the [motion service](/reference/services/motion/) for more information. | + +### Configure and calibrate the frame system service for GPS navigation + +{{% alert title="Info" color="info" %}} + +The [frame system service](/reference/services/frame-system/) is an internally managed and mostly static system for storing the reference frame of each component of a machine within a coordinate system configured by the user. + +It stores the required contextual information for Viam's services like [Motion](/reference/services/motion/) and [Vision](/reference/services/vision/) to use the position and orientation readings returned by components like [movement sensors](/reference/components/movement-sensor/). + +{{% /alert %}} + +To make sure your rover base's autonomous GPS navigation with the navigation service is accurate, configure and calibrate the frame system service for the components of your machine. + +#### Configure + +Add [reference frames](/reference/services/frame-system/#configuration) to your rover [base](/reference/components/base/) and [movement sensor](/reference/components/movement-sensor/) configurations: + +- Navigate to the **CONFIGURE** tab of your machine's page. +- Find your base configuration card and click the **Frame** button. +- Since you haven't adjusted any parameters yet, the default reference frame will be shown for your base: + + {{}} + +- Keep the `parent` frame as `world`. +- Configure a `geometry` for the base that reflects its physical dimensions. + Measure the physical dimensions of your base and use them to configure the size of your geometry. + Units are in _mm_. + + For example, you would configure a box-shaped base with dimensions of 100mm x 100mm x 100mm (l x h x w) as follows: + + {{}} + +- Add a frame to your movement sensor configuration by clicking the **Frame** button. +- Set the `parent` within the frame card to the name of your base. +- Give the movement sensor a `translation` that reflects where it is mounted on your base, measuring the coordinates with respect to the origin of the base. + In other words, designate the base origin as `(0,0,0)` and measure the distance between that and the origin of the sensor to obtain the coordinates. + + For example, you would configure a movement sensor mounted 200mm on top of your base as follows: + + {{}} + +You can also adjust the `orientation` and `geometry` of your movement sensor or base, if necessary. +See [the frame system service](/reference/services/frame-system/) for instructions. + +#### Calibrate + +Then, to calibrate your frame system for the most accurate autonomous GPS navigation with the navigation service: + +- After configuring your machine, navigate to the **CONTROL** tab and select the card matching the name of your movement sensor. +- Monitor the readings displayed on the card, and verify that the compass or orientation readings from the movement sensor report `0` when the base is facing north. +- If you cannot verify this: + - Navigate back to your machine's **CONFIGURE** tab. + Scroll to the card with the name of your movement sensor. + Adjust the `orientation` of the frame to compensate for the mismatch. + - Navigate back to the movement sensor card on your **CONTROL** page, and confirm that the compass or orientation readings from the movement sensor now report `0` when the base is facing north, confirming that you've successfully calibrated your machine to be oriented accurately within the frame system. + - If you cannot verify this, repeat as necessary. + +## API + +The [navigation service API](/reference/apis/services/navigation/) supports the following methods: + +{{< readfile "/static/include/services/apis/generated/navigation-table.md" >}} + +## Control tab usage + +After configuring the navigation service for your machine, navigate to the **CONTROL** tab of the machine's page and expand the card matching the name of your service to use an interface for rover navigation. + +Here, you can add waypoints and obstacles and view the position of your rover base on a map: + +{{}} + +## Navigation 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](/reference/components/movement-sensor/), which can then be used by your machine to navigate across space. + +Here's how to use the following types of measurements: + +- [Compass Heading](#compass-heading) +- [Orientation](#orientation) +- [Angular Velocity](#angular-velocity) +- [Position](#position) +- [Linear Acceleration](#linear-acceleration) +- [Linear Velocity](#linear-velocity) + +### Compass heading + +The following {{< glossary_tooltip term_id="model" text="models" >}} of [movement sensor](/reference/components/movement-sensor/) take compass heading measurements: + +- [gps-nmea](https://github.com/viam-modules/gps/) - some GPS hardware only report heading while moving. +- [gps-nmea-rtk-pmtk](https://github.com/viam-modules/gps/) - some GPS hardware only report heading while moving. +- [gps-nmea-rtk-serial](https://github.com/viam-modules/gps/) - some GPS hardware only report heading while moving. +- [imu-wit](https://github.com/viam-modules/wit-motion/) +- [imu-wit-hwt905](https://github.com/viam-modules/wit-motion/) + +An example of a `CompassHeading` 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 machine, or, the [cardinal direction](https://en.wikipedia.org/wiki/Cardinal_direction) that your machine is facing. + +To read compass headings, [configure a capable movement sensor](/reference/components/movement-sensor/) on your machine. +Then use the movement sensor API's [`GetCompassHeading()`](/reference/apis/components/movement-sensor/#getcompassheading) method to get readings from the sensor. + +### Orientation + +The following {{< glossary_tooltip term_id="model" text="models" >}} of [movement sensor](/reference/components/movement-sensor/) take orientation measurements: + +- [imu-wit](https://github.com/viam-modules/wit-motion/) +- [imu-wit-hwt905](https://github.com/viam-modules/wit-motion/) +- [wheeled-odometry](/reference/components/movement-sensor/wheeled-odometry/) + +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_](/motion-planning/reference/orientation-vectors/). +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](/reference/services/frame-system/). +The `GetOrientation` readings will report orientations relative to that initial frame. + +To read orientation, first [configure a capable movement sensor](/reference/components/movement-sensor/) on your machine. +Additionally, follow [these instructions](/reference/services/frame-system/#configuration) to configure the geometries of each component of your machine within the frame system. +Then use the movement sensor API's [`GetOrientation()`](/reference/apis/components/movement-sensor/#getorientation) method to get orientation readings. + +### Angular velocity + +The following {{< glossary_tooltip term_id="model" text="models" >}} of the [movement sensor](/reference/components/movement-sensor/) component take angular velocity measurements: + +- [imu-wit](https://github.com/viam-modules/wit-motion/) +- [imu-wit-hwt905](https://github.com/viam-modules/wit-motion/) +- [wheeled-odometry](/reference/components/movement-sensor/wheeled-odometry/) +- [gyro-mpu6050](https://github.com/viam-modules/tdk-invensense/) + +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 machine is rotating. + +To get an angular velocity reading, first [configure a capable movement sensor](/reference/components/movement-sensor/) on your machine. +Then use the movement sensor API's [`GetAngularVelocity()`](/reference/apis/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](/reference/components/movement-sensor/) component take position measurements: + +- [gps-nmea](https://github.com/viam-modules/gps/) +- [gps-nmea-rtk-pmtk](https://github.com/viam-modules/gps/) +- [gps-nmea-rtk-serial](https://github.com/viam-modules/gps/) +- [wheeled-odometry](/reference/components/movement-sensor/wheeled-odometry/) + +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](/reference/components/movement-sensor/) on your machine. +Then use the movement sensor API's [`GetPosition()`](/reference/apis/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](/reference/components/movement-sensor/) take linear velocity measurements: + +- [gps-nmea](https://github.com/viam-modules/gps/) +- [gps-nmea-rtk-pmtk](https://github.com/viam-modules/gps/) +- [gps-nmea-rtk-serial](https://github.com/viam-modules/gps/) +- [wheeled-odometry](/reference/components/movement-sensor/wheeled-odometry/) (provides a relative estimate only based on where the base component has started) + +An example of a `LinearVelocity` 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 machine is moving through space. + +To get linear velocity, [configure a capable movement sensor](/reference/components/movement-sensor/) on your machine. +Then use the movement sensor API's [`GetLinearVelocity()`](/reference/apis/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](/reference/components/movement-sensor/) take linear acceleration measurements: + +- [accel-adxl345](https://github.com/viam-modules/analog-devices/) +- [imu-wit](https://github.com/viam-modules/wit-motion/) +- [imu-wit-hwt905](https://github.com/viam-modules/wit-motion/) +- [gyro-mpu6050](https://github.com/viam-modules/tdk-invensense/) + +An example of a `LinearAcceleration` 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](#linear-velocity) of your machine, or, the acceleration at which your machine is moving through space. -For collision-free motion planning, see [Motion planning](/motion-planning/). +To get linear acceleration, [configure a capable movement sensor](/reference/components/movement-sensor/) on your machine. +Then use the movement sensor API's [`GetLinearAcceleration()`](/reference/apis/components/movement-sensor/#getlinearacceleration) method to get linear acceleration readings from the sensor. diff --git a/docs/reference/services/slam/_index.md b/docs/reference/services/slam/_index.md new file mode 100644 index 0000000000..53ed0a4b0e --- /dev/null +++ b/docs/reference/services/slam/_index.md @@ -0,0 +1,22 @@ +--- +title: "SLAM service" +linkTitle: "SLAM" +weight: 60 +type: "docs" +tags: ["slam", "services"] +description: "Simultaneous localization and mapping (SLAM) allows your machine to create a map of its surroundings and find its location within that map." +date: "2022-01-01" +build: + render: always + list: never + publishResources: true +--- + +{{< alert title="Discontinued" color="caution" >}} +Support for the SLAM service has been discontinued. +This page is retained for reference only. +{{< /alert >}} + +Simultaneous localization and mapping (SLAM) allows your machine to create a map of its surroundings and find its location within that map. + +For the SLAM service API methods, see [SLAM service API](/reference/apis/services/slam/). diff --git a/netlify.toml b/netlify.toml index 98882fcb6b..33f44301f1 100644 --- a/netlify.toml +++ b/netlify.toml @@ -549,6 +549,21 @@ to = "/motion-planning/" status = 301 +# Capitalized SLAM API aliases consolidated to the lowercase canonical page. +# A Hugo alias here would create a /SLAM/ stub that shadows the real /slam/ +# page on case-insensitive serving, so redirect at the edge instead. +[[redirects]] + from = "/reference/apis/services/SLAM/" + to = "/reference/apis/services/slam/" + status = 301 + force = true + +[[redirects]] + from = "/dev/reference/apis/services/SLAM/" + to = "/reference/apis/services/slam/" + status = 301 + force = true + # Old IA paths from previous site versions [[redirects]] from = "/architecture/*" @@ -740,7 +755,7 @@ # (for development) turn true for extra diagnostic logging debug = true - skipPatterns = ["/tags/"] + skipPatterns = ["/tags/", "/reference/apis/services/SLAM/", "/dev/reference/apis/services/SLAM/"] [[context.deploy-preview.plugins]] package = "@eggnstone/netlify-plugin-no-more-404" @@ -749,7 +764,7 @@ failBuildOnError = true failPluginOnError = true - skipPatterns = ["/tags/"] + skipPatterns = ["/tags/", "/reference/apis/services/SLAM/", "/dev/reference/apis/services/SLAM/"] [[context.branch-deploy.plugins]] @@ -759,4 +774,4 @@ failBuildOnError = true failPluginOnError = true - skipPatterns = ["/tags/"] + skipPatterns = ["/tags/", "/reference/apis/services/SLAM/", "/dev/reference/apis/services/SLAM/"] diff --git a/static/include/services/apis/generated/navigation-table.md b/static/include/services/apis/generated/navigation-table.md new file mode 100644 index 0000000000..b206be35f7 --- /dev/null +++ b/static/include/services/apis/generated/navigation-table.md @@ -0,0 +1,16 @@ + +| Method Name | Description | +| ----------- | ----------- | +| [`GetMode`](/reference/apis/services/navigation/#getmode) | Get the `Mode` the service is operating in. | +| [`SetMode`](/reference/apis/services/navigation/#setmode) | Set the `Mode` the service is operating in. | +| [`GetLocation`](/reference/apis/services/navigation/#getlocation) | Get the current location of the robot in the navigation service. | +| [`GetWaypoints`](/reference/apis/services/navigation/#getwaypoints) | Get an array of waypoints currently in the service's data storage. | +| [`AddWaypoint`](/reference/apis/services/navigation/#addwaypoint) | Add a waypoint to the service's data storage. | +| [`RemoveWaypoint`](/reference/apis/services/navigation/#removewaypoint) | Remove a waypoint from the service's data storage. | +| [`GetObstacles`](/reference/apis/services/navigation/#getobstacles) | Get an array or list of the obstacles currently in the service's data storage. | +| [`GetPaths`](/reference/apis/services/navigation/#getpaths) | Get each path, the series of geo points the robot plans to travel through to get to a destination waypoint, in the machine's motion planning. | +| [`GetProperties`](/reference/apis/services/navigation/#getproperties) | Get information about the navigation service. | +| [`Reconfigure`](/reference/apis/services/navigation/#reconfigure) | Reconfigure this resource. | +| [`DoCommand`](/reference/apis/services/navigation/#docommand) | Execute model-specific commands that are not otherwise defined by the service API. | +| [`GetResourceName`](/reference/apis/services/navigation/#getresourcename) | Get the `ResourceName` for this instance of the navigation service. | +| [`Close`](/reference/apis/services/navigation/#close) | Safely shut down the resource and prevent further use. | diff --git a/static/include/services/apis/generated/navigation.md b/static/include/services/apis/generated/navigation.md new file mode 100644 index 0000000000..778157cf29 --- /dev/null +++ b/static/include/services/apis/generated/navigation.md @@ -0,0 +1,934 @@ +### GetMode + +Get the `Mode` the service is operating in. + +There are two options for modes: `MODE_MANUAL` or `MODE_WAYPOINT`. + +- `MODE_WAYPOINT`: Start to look for added waypoints and begin autonomous navigation. +- `MODE_MANUAL`: Stop autonomous navigation between waypoints and allow the base to be controlled manually. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- (viam.services.navigation.Mode.ValueType): : The Mode the service is operating in. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_nav = NavigationClient.from_robot(robot=machine, name="my_nav_service") + +# Get the Mode the service is operating in +await my_nav.get_mode() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.get_mode). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. + +**Returns:** + +- [(Mode)](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Mode): The `Mode` the service is operating in. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +// Get the Mode the service is operating in. +mode, err := myNav.Mode(context.Background(), nil) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Service). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `extra` (None) (optional) +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise<[navigationApi](https://ts.viam.dev/modules/navigationApi.html).[Mode](https://ts.viam.dev/enums/navigationApi.Mode.html)>) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +const navigation = new VIAM.NavigationClient(machine, "my_navigation"); + +const mode = await navigation.getMode(); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#getmode). + +{{% /tab %}} +{{< /tabs >}} + +### SetMode + +Set the `Mode` the service is operating in. + +There are two options for modes: `MODE_MANUAL` or `MODE_WAYPOINT`. + +- `MODE_WAYPOINT`: Start to look for added waypoints and begin autonomous navigation. +- `MODE_MANUAL`: Stop autonomous navigation between waypoints and allow the base to be controlled manually. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `mode` (viam.services.navigation.Mode.ValueType) (required): The Mode for the service to operate in. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- None. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_nav = NavigationClient.from_robot(robot=machine, name="my_nav_service") + +# Set the Mode the service is operating in to MODE_WAYPOINT and begin navigation +await my_nav.set_mode(Mode.ValueType.MODE_WAYPOINT) +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.set_mode). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `mode` [(Mode)](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Mode): The `Mode` for the service to operate in. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. + +**Returns:** + +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +// Set the Mode the service is operating in to ModeWaypoint and begin navigation. +err := myNav.SetMode(context.Background(), navigation.ModeWaypoint, nil) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Service). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `mode` ([navigationApi](https://ts.viam.dev/modules/navigationApi.html)) (required): The mode for the service to operate in. + + - 0: MODE_UNSPECIFIED + - 1: MODE_MANUAL + - 2: MODE_WAYPOINT + - 3: MODE_EXPLORE. + +- `extra` (None) (optional) +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +const navigation = new VIAM.NavigationClient(machine, "my_navigation"); + +// Set the mode to 2 which corresponds to WAYPOINT +await navigation.setMode(2); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#setmode). + +{{% /tab %}} +{{< /tabs >}} + +### GetLocation + +Get the current location of the robot in the navigation service. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- ([viam.services.navigation.GeoPoint](https://python.viam.dev/autoapi/viam/services/navigation/index.html#viam.services.navigation.GeoPoint)): : The current location of the robot in the navigation service, + represented in a GeoPoint with latitude and longitude values. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_nav = NavigationClient.from_robot(robot=machine, name="my_nav_service") + +# Get the current location of the robot in the navigation service +location = await my_nav.get_location() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.get_location). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. + +**Returns:** + +- [(\*spatialmath.GeoPose)](https://pkg.go.dev/go.viam.com/rdk/spatialmath#GeoPose): The current location of the robot in the navigation service, represented in a `Point` with latitude and longitude values. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +// Get the current location of the robot in the navigation service. +location, err := myNav.Location(context.Background(), nil) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Service). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `extra` (None) (optional) +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise<[navigationApi](https://ts.viam.dev/modules/navigationApi.html).[GetLocationResponse](https://ts.viam.dev/classes/navigationApi.GetLocationResponse.html)>) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +const navigation = new VIAM.NavigationClient(machine, "my_navigation"); + +const location = await navigation.getLocation(); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#getlocation). + +{{% /tab %}} +{{< /tabs >}} + +### GetWaypoints + +Get an array of waypoints currently in the service's data storage. +These are locations designated within a path for the robot to navigate to. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- ([List[viam.services.navigation.Waypoint]](https://python.viam.dev/autoapi/viam/services/navigation/index.html#viam.services.navigation.Waypoint)): : An array comprised of each Waypoint in the service’s data storage. + These are locations designated within a path for the robot to navigate to. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_nav = NavigationClient.from_robot(robot=machine, name="my_nav_service") + +# Get a list containing each waypoint stored by the navigation service +waypoints = await my_nav.get_waypoints() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.get_waypoints). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. + +**Returns:** + +- [([]Waypoint)](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Waypoint): An array comprised of each `Waypoint` in the service's data storage. These are locations designated within a path for the robot to navigate to. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +waypoints, err := myNav.Waypoints(context.Background(), nil) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Service). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `extra` (None) (optional) +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise<[navigationApi](https://ts.viam.dev/modules/navigationApi.html).[Waypoint](https://ts.viam.dev/classes/navigationApi.Waypoint.html)[]>) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +const navigation = new VIAM.NavigationClient(machine, "my_navigation"); + +const waypoints = await navigation.getWayPoints(); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#getwaypoints). + +{{% /tab %}} +{{< /tabs >}} + +### AddWaypoint + +Add a waypoint to the service's data storage. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `point` ([viam.services.navigation.GeoPoint](https://python.viam.dev/autoapi/viam/services/navigation/index.html#viam.services.navigation.GeoPoint)) (required): A waypoint represented in a GeoPoint with latitude and longitude values. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- None. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_nav = NavigationClient.from_robot(robot=machine, name="my_nav_service") + + # Create a new waypoint with latitude and longitude values of 0 degrees + location = GeoPoint(latitude=0, longitude=0) + + + # Add your waypoint to the service's data storage + await my_nav.add_waypoint(point=location) +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.add_waypoint). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `point` [(\*geo.Point)](https://pkg.go.dev/github.com/kellydunn/golang-geo#Point): A waypoint represented in a `Point` with latitude (lat) and longitude (lng) values. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. + +**Returns:** + +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +// Create a new waypoint with latitude and longitude values of 0 degrees. +// Assumes you have imported "github.com/kellydunn/golang-geo" as `geo`. +location := geo.NewPoint(0, 0) + +// Add your waypoint to the service's data storage. +err := myNav.AddWaypoint(context.Background(), location, nil) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Service). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `location` ([PlainMessage](https://ts.viam.dev/types/PlainMessage.html)) (required): A waypoint described by latitude and longitude values. +- `extra` (None) (optional) +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +const navigation = new VIAM.NavigationClient(machine, "my_navigation"); + +const location = { latitude: 40.7128, longitude: -74.006 }; +await navigation.addWayPoint(location); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#addwaypoint). + +{{% /tab %}} +{{< /tabs >}} + +### RemoveWaypoint + +Remove a waypoint from the service's data storage. +If the robot is currently navigating to this waypoint, the motion will be canceled, and the robot will proceed to the next waypoint. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `id` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The MongoDB ObjectID of the Waypoint to remove from the service’s data storage. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- None. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_nav = NavigationClient.from_robot(robot=machine, name="my_nav_service") + +# Remove the waypoint matching that ObjectID from the service's data storage +await my_nav.remove_waypoint(waypoint_id) +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.remove_waypoint). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `id` [(primitive.ObjectID)](https://pkg.go.dev/go.mongodb.org/mongo-driver/bson/primitive#ObjectID): The MongoDB ObjectID of the `Waypoint` to remove from the service's data storage. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. + +**Returns:** + +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +// Assumes you have already called AddWaypoint once and the waypoint has not yet been reached. +waypoints, err := myNav.Waypoints(context.Background(), nil) +if (err != nil || len(waypoints) == 0) { + return +} + +// Remove the first waypoint from the service's data storage. +err = myNav.RemoveWaypoint(context.Background(), waypoints[0].ID, nil) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Service). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `id` (string) (required): The MongoDB ObjectID of the waypoint to remove from the + service's data storage. +- `extra` (None) (optional) +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +const navigation = new VIAM.NavigationClient(machine, "my_navigation"); + +// Remove the first waypoint +if (waypoints.length > 0) { + await navigation.removeWayPoint(waypoints[0].id); +} +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#removewaypoint). + +{{% /tab %}} +{{< /tabs >}} + +### GetObstacles + +Get an array or list of the obstacles currently in the service's data storage. +These are objects designated for the robot to avoid when navigating. +These include all transient obstacles which are discovered by the vision services configured for the navigation service, in addition to the obstacles that are configured as a part of the service. +See the [motion service](/reference/services/motion/) for more information. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- ([List[viam.services.navigation.GeoGeometry]](https://python.viam.dev/autoapi/viam/services/navigation/index.html#viam.services.navigation.GeoGeometry)): : A list comprised of each GeoGeometry in the service’s data storage. + These are objects designated for the robot to avoid when navigating. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_nav = NavigationClient.from_robot(robot=machine, name="my_nav_service") + +# Get a list containing each obstacle stored by the navigation service +obstacles = await my_nav.get_obstacles() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.get_obstacles). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. + +**Returns:** + +- [([]\*spatialmath.GeoGeometry)](https://pkg.go.dev/go.viam.com/rdk/spatialmath#GeoGeometry): An array comprised of each `GeoObstacle` in the service's data storage. These are objects designated for the robot to avoid when navigating. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +// Get an array containing each obstacle stored by the navigation service. +obstacles, err := myNav.Obstacles(context.Background(), nil) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Service). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `extra` (None) (optional) +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise<[commonApi](https://ts.viam.dev/modules/commonApi.html).[GeoGeometry](https://ts.viam.dev/classes/commonApi.GeoGeometry.html)[]>) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +const navigation = new VIAM.NavigationClient(machine, "my_navigation"); + +const obstacles = await navigation.getObstacles(); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#getobstacles). + +{{% /tab %}} +{{< /tabs >}} + +### GetPaths + +Get each path, the series of geo points the robot plans to travel through to get to a destination waypoint, in the machine's motion planning. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- ([List[viam.proto.service.navigation.Path]](https://python.viam.dev/autoapi/viam/proto/service/navigation/index.html#viam.proto.service.navigation.Path)): : An array comprised of Paths, where each path is either a user-provided destination or + a Waypoint, along with the corresponding set of geopoints. This outlines the route the machine is expected to take to + reach the specified destination or Waypoint. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_nav = NavigationClient.from_robot(robot=machine, name="my_nav_service") + +# Get a list containing each path stored by the navigation service +paths = await my_nav.get_paths() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.get_paths). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `extra` [(map[string]interface{})](https://go.dev/blog/maps): Extra options to pass to the underlying RPC call. + +**Returns:** + +- [([]\*Path)](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Path): An array of paths, each path being a user-provided destination, or [`Waypoint`](#addwaypoint), and the set of [geo `Point`s](https://pkg.go.dev/github.com/kellydunn/golang-geo#Point) the robot plans to travel through to get there. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +// Get an array containing each path stored by the navigation service. +paths, err := myNav.Paths(context.Background(), nil) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Service). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `extra` (None) (optional) +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise<[navigationApi](https://ts.viam.dev/modules/navigationApi.html).[Path](https://ts.viam.dev/classes/navigationApi.Path.html)[]>) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +const navigation = new VIAM.NavigationClient(machine, "my_navigation"); + +const paths = await navigation.getPaths(); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#getpaths). + +{{% /tab %}} +{{< /tabs >}} + +### GetProperties + +Get information about the navigation service. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- (viam.services.navigation.MapType.ValueType): : Information about the type of map the service is using. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_nav = NavigationClient.from_robot(robot=machine, name="my_nav_service") + +# Get the properties of the current navigation service. +nav_properties = await my_nav.get_properties() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.get_properties). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. + +**Returns:** + +- [(Properties)](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Properties): Information about the type of map the service is using. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +// Get the properties of the current navigation service. +navProperties, err := myNav.Properties(context.Background()) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/services/navigation#Service). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise<[navigationApi](https://ts.viam.dev/modules/navigationApi.html).[GetPropertiesResponse](https://ts.viam.dev/classes/navigationApi.GetPropertiesResponse.html)>) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +const navigation = new VIAM.NavigationClient(machine, "my_navigation"); + +const properties = await navigation.getProperties(); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#getproperties). + +{{% /tab %}} +{{< /tabs >}} + +### Reconfigure + +Reconfigure this resource. +Reconfigure must reconfigure the resource atomically and in place. + +{{< tabs >}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `deps` [(Dependencies)](https://pkg.go.dev/go.viam.com/rdk/resource#Dependencies): The resource dependencies. +- `conf` [(Config)](https://pkg.go.dev/go.viam.com/rdk/resource#Config): The resource configuration. + +**Returns:** + +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource). + +{{% /tab %}} +{{< /tabs >}} + +### DoCommand + +Execute model-specific commands that are not otherwise defined by the service API. +Most models do not implement `DoCommand`. +Any available model-specific commands should be covered in the model's documentation. +If you are implementing your own navigation service and want to add features that have no corresponding built-in API method, you can implement them with [`DoCommand`](/reference/sdks/docommand/). + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `command` (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), ValueTypes]) (required): The command to execute. +- `timeout` ([float](https://docs.python.org/3/library/stdtypes.html#numeric-types-int-float-complex)) (optional): An option to set how long to wait (in seconds) before calling a time-out and closing the underlying RPC call. + +**Returns:** + +- (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), viam.utils.ValueTypes]): : Result of the executed command. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_navigation_svc = NavigationClient.from_robot(robot=machine, "my_navigation_svc") + +my_command = { + "cmnd": "dosomething", + "someparameter": 52 +} + +await my_navigation_svc.do_command(command=my_command) +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.do_command). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. +- `cmd` [(map[string]interface{})](https://go.dev/blog/maps): The command to execute. + +**Returns:** + +- [(map[string]interface{})](https://pkg.go.dev/builtin#string): The command response. +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +myNavigationSvc, err := navigation.FromProvider(machine, "my_navigation_svc") + +command := map[string]interface{}{"cmd": "test", "data1": 500} +result, err := myNavigationSvc.DoCommand(context.Background(), command) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- `command` ([Struct](https://ts.viam.dev/classes/Struct.html)) (required): The command to execute. Accepts either a [Struct](https://ts.viam.dev/classes/Struct.html) or + a plain object, which will be converted automatically. +- `callOptions` (CallOptions) (optional) + +**Returns:** + +- (Promise<[JsonValue](https://ts.viam.dev/types/JsonValue.html)>) + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +// Plain object (recommended) +const result = await resource.doCommand({ + myCommand: { key: "value" }, +}); + +// Struct (still supported) +import { Struct } from "@viamrobotics/sdk"; + +const result = await resource.doCommand( + Struct.fromJson({ myCommand: { key: "value" } }), +); +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#docommand). + +{{% /tab %}} +{{< /tabs >}} + +### GetResourceName + +Get the `ResourceName` for this instance of the navigation service. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- `name` ([str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str)) (required): The name of the Resource. + +**Returns:** + +- ([viam.proto.common.ResourceName](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName)): : The ResourceName of this Resource. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_navigation_svc_name = NavigationClient.get_resource_name("my_navigation_svc") +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.get_resource_name). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- None. + +**Returns:** + +- [(Name)](https://pkg.go.dev/go.viam.com/rdk@v0.89.0/resource#Name) + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +my_nav, err := navigation.FromProvider(machine, "my_nav_svc") + +err := my_nav.Name() +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource). + +{{% /tab %}} +{{% tab name="TypeScript" %}} + +**Parameters:** + +- None. + +**Returns:** + +- (string): The name of the resource. + +**Example:** + +```ts {class="line-numbers linkable-line-numbers"} +navigation.name; +``` + +For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/NavigationClient.html#name). + +{{% /tab %}} +{{< /tabs >}} + +### Close + +Safely shut down the resource and prevent further use. + +{{< tabs >}} +{{% tab name="Python" %}} + +**Parameters:** + +- None. + +**Returns:** + +- None. + +**Example:** + +```python {class="line-numbers linkable-line-numbers"} +my_navigation_svc = NavigationClient.from_robot(robot=machine, name="my_navigation_svc") +await my_navigation_svc.close() +``` + +For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/viam/services/navigation/client/index.html#viam.services.navigation.client.NavigationClient.close). + +{{% /tab %}} +{{% tab name="Go" %}} + +**Parameters:** + +- `ctx` [(Context)](https://pkg.go.dev/context#Context): A Context carries a deadline, a cancellation signal, and other values across API boundaries. + +**Returns:** + +- [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. + +**Example:** + +```go {class="line-numbers linkable-line-numbers"} +my_nav, err := navigation.FromProvider(machine, "my_nav_svc") + +err := my_nav.Close(context.Background()) +``` + +For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/resource#Resource). + +{{% /tab %}} +{{< /tabs >}} diff --git a/static/include/services/apis/generated/slam.md b/static/include/services/apis/generated/slam.md index 827c64431d..836ac14a56 100644 --- a/static/include/services/apis/generated/slam.md +++ b/static/include/services/apis/generated/slam.md @@ -11,7 +11,7 @@ Get the current position of the component the SLAM service is configured to sour **Returns:** -- ([viam.services.slam.Pose](https://python.viam.dev/autoapi/viam/services/slam/index.html#viam.services.slam.Pose)): : The current position of the specified component. +- ([viam.services.slam.Pose](https://python.viam.dev/autoapi/viam/services/slam/index.html#viam.services.slam.Pose)): : The current position of the specified component. **Example:** @@ -60,11 +60,11 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/s **Example:** ```ts {class="line-numbers linkable-line-numbers"} -const slam = new VIAM.SlamClient(machine, 'my_slam'); +const slam = new VIAM.SlamClient(machine, "my_slam"); // Get the current position of the robot in the SLAM map const position = await slam.getPosition(); -console.log('Current position:', position); +console.log("Current position:", position); ``` For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/SlamClient.html#getposition). @@ -86,8 +86,8 @@ Get the point cloud map. **Returns:** -- (List[[bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)]): : Complete pointcloud in standard PCD format. Chunks of the PointCloud, concatenating all - GetPointCloudMapResponse.point\_cloud\_pcd\_chunk values. +- (List[[bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)]): : Complete pointcloud in standard PCD format. Chunks of the PointCloud, concatenating all + GetPointCloudMapResponse.point_cloud_pcd_chunk values. **Example:** @@ -129,7 +129,7 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/s **Example:** ```ts {class="line-numbers linkable-line-numbers"} -const slam = new VIAM.SlamClient(machine, 'my_slam'); +const slam = new VIAM.SlamClient(machine, "my_slam"); // Get the point cloud map const pointCloudMap = await slam.getPointCloudMap(); @@ -156,7 +156,7 @@ Get the internal state of the SLAM algorithm required to continue mapping/locali **Returns:** -- (List[[bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)]): : Chunks of the internal state of the SLAM algorithm. +- (List[[bytes](https://docs.python.org/3/library/stdtypes.html#bytes-objects)]): : Chunks of the internal state of the SLAM algorithm. **Example:** @@ -196,7 +196,7 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/s **Example:** ```ts {class="line-numbers linkable-line-numbers"} -const slam = new VIAM.SlamClient(machine, 'my_slam'); +const slam = new VIAM.SlamClient(machine, "my_slam"); // Get the internal state of the SLAM algorithm const internalState = await slam.getInternalState(); @@ -220,7 +220,7 @@ Get information about the current SLAM session. **Returns:** -- ([viam.services.slam.slam.SLAM.Properties](https://python.viam.dev/autoapi/viam/services/slam/slam/index.html#viam.services.slam.slam.SLAM.Properties)): : The properties of SLAM. +- ([viam.services.slam.slam.SLAM.Properties](https://python.viam.dev/autoapi/viam/services/slam/slam/index.html#viam.services.slam.slam.SLAM.Properties)): : The properties of SLAM. **Example:** @@ -242,13 +242,13 @@ For more information, see the [Python SDK Docs](https://python.viam.dev/autoapi/ **Returns:** -- [(Properties)](https://pkg.go.dev/go.viam.com/rdk/services/slam#Properties): -Information about the current SLAM session. -An object containing four fields: +- [(Properties)](https://pkg.go.dev/go.viam.com/rdk/services/slam#Properties): + Information about the current SLAM session. + An object containing four fields: - `SensorInfo` [(SensorInfo[])](https://pkg.go.dev/go.viam.com/api/service/slam/v1#SensorInfo): Information about the sensors (camera and movement sensor) configured for your SLAM service, including the name and type of sensor. - `CloudSlam` [(bool)](https://pkg.go.dev/builtin#bool): A boolean which indicates whether the session is being run in the cloud. -- `MappingMode` [(MappingMode)](https://pkg.go.dev/go.viam.com/rdk/services/slam#MappingMode): Represents the [form of mapping and localizing the current session is performing](/reference/services/slam/cartographer/#using-cartographer). This includes creating a new map, localizing on an existing map and updating an existing map. +- `MappingMode` [(MappingMode)](https://pkg.go.dev/go.viam.com/rdk/services/slam#MappingMode): Represents the form of mapping and localizing the current session is performing. This includes creating a new map, localizing on an existing map and updating an existing map. - `InternalStateFileType` [(string)](https://pkg.go.dev/builtin#string): The file type the service's internal state algorithm is stored in. - [(error)](https://pkg.go.dev/builtin#error): An error, if one occurred. @@ -275,11 +275,11 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/s **Example:** ```ts {class="line-numbers linkable-line-numbers"} -const slam = new VIAM.SlamClient(machine, 'my_slam'); +const slam = new VIAM.SlamClient(machine, "my_slam"); // Get the properties of the SLAM service const properties = await slam.getProperties(); -console.log('SLAM properties:', properties); +console.log("SLAM properties:", properties); ``` For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/SlamClient.html#getproperties). @@ -372,7 +372,7 @@ If you are implementing your own SLAM service and want to add features that have **Returns:** -- (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), viam.utils.ValueTypes]): : Result of the executed command. +- (Mapping[[str](https://docs.python.org/3/library/stdtypes.html#text-sequence-type-str), viam.utils.ValueTypes]): : Result of the executed command. **Example:** @@ -431,14 +431,14 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/r ```ts {class="line-numbers linkable-line-numbers"} // Plain object (recommended) const result = await resource.doCommand({ - myCommand: { key: 'value' }, + myCommand: { key: "value" }, }); // Struct (still supported) -import { Struct } from '@viamrobotics/sdk'; +import { Struct } from "@viamrobotics/sdk"; const result = await resource.doCommand( - Struct.fromJson({ myCommand: { key: 'value' } }) + Struct.fromJson({ myCommand: { key: "value" } }), ); ``` @@ -460,7 +460,7 @@ Get the `ResourceName` for this instance of the SLAM service. **Returns:** -- ([viam.proto.common.ResourceName](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName)): : The ResourceName of this Resource. +- ([viam.proto.common.ResourceName](https://python.viam.dev/autoapi/viam/proto/common/index.html#viam.proto.common.ResourceName)): : The ResourceName of this Resource. **Example:** @@ -505,7 +505,7 @@ For more information, see the [Go SDK Docs](https://pkg.go.dev/go.viam.com/rdk/r **Example:** ```ts {class="line-numbers linkable-line-numbers"} -slam.name +slam.name; ``` For more information, see the [TypeScript SDK Docs](https://ts.viam.dev/classes/SlamClient.html#name).