diff --git a/docs/components/movement-sensor/_index.md b/docs/components/movement-sensor/_index.md index e86223619d..8a06c78fc0 100644 --- a/docs/components/movement-sensor/_index.md +++ b/docs/components/movement-sensor/_index.md @@ -38,6 +38,7 @@ Model | Description [`accel-adxl345`](./adxl345/) | The [Analog Devices ADXL345](https://www.analog.com/en/products/adxl345.html) digital accelerometer [`gyro-mpu6050`](./mpu6050/) | A gyroscope/accelerometer manufactured by TDK InvenSense [`merged`](./merged/) | A model that allows you to aggregate the API methods supported by multiple sensors into a singular sensor client, effectively merging the models of the individual resources +[`wheeled-odometry`](./wheeled-odometry/) | A model that uses [encoders](/components/encoder/) to get an odometry estimate from a wheeled base [`fake`](./fake/) | Used to test code without hardware ## Control your movement sensor with Viam's client SDK libraries diff --git a/docs/components/movement-sensor/wheeled-odometry.md b/docs/components/movement-sensor/wheeled-odometry.md new file mode 100644 index 0000000000..0e7d40f571 --- /dev/null +++ b/docs/components/movement-sensor/wheeled-odometry.md @@ -0,0 +1,64 @@ +--- +title: "Configure a wheeled-odometry movement sensor" +linkTitle: "wheeled-odometry" +type: "docs" +description: "Configure a wheeled-odometry movement sensor." +images: ["/icons/components/imu.svg"] +tags: ["movement sensor", "components", "encoder", "motor", "base", "wheeled", "odometry"] +# SMEs: Rand, Martha +--- + +Configure a `wheeled-odometry` movement sensor to implement _wheeled odometry_ on your robot. + +_Wheeled odometry_ is the estimation of the rate of change of position, orientation, linear velocity, and angular velocity using the dimensions of a base, calculated by measuring the movement of the motors through encoders. +Because of this method of estimation, you don't have to have a specific piece of movement sensor hardware to implement `wheeled-odometry` on your robot. +This model uses [encoders](/components/encoder/) from [position reporting motors](/components/motor/) to get an odometry estimate of a wheeled base as it moves. + +With a configured `wheeled-odometry` movement sensor, your robot calculates an estimation of the position, orientation, linear velocity, and angular velocity of the wheeled base each time `time_interval_msec` elapses during a [session](/program/apis/sessions/). +You can access these readings through the [movement sensor API](/components/movement-sensor/#api). +For the best accuracy with odometry calculations, it is recommended you configure a time interval of less than `1000` milliseconds. + +After configuring a `wheeled-odometry` movement sensor, you can operate your base with Viam's built-in services like the [navigation service](/services/navigation/). + +## Set-up requirements + +To prepare your robot, attach [encoders](/components/encoder/) to each of the position-reporting motors on your base to measure their rotation. + +- Select motors that can report their own position, like an encoded [`roboclaw`](/components/motor/roboclaw/) or [`gpio` motors](/components/motor/gpio/) with [encoders](/components/encoder/#configuration), or the [`odrive`](/extend/modular-resources/examples/odrive/) module. +You can access this property of a configured motor through the [motor API's `GetProperties()`](/components/motor/#getproperties). +- Configure your rover as a [wheeled base component](/components/base/wheeled/). +Make sure to configure the base width and circumference, as these measurements as a property of the base are vital for accurate odometry estimations by your movement sensor. This movement sensor accesses these values through the base's `GetProperties()` API method. +- Configure each of the position-reporting motors [as motor components](/components/motor/). +- Then, proceed to [configure](#configuration) a `wheeled-odometry` movement sensor with the name of each of the motor components. + +## Configuration + +Navigate to the **Config** tab of your robot's page in [the Viam app](https://app.viam.com). +Click on the **Components** subtab and navigate to the **Create component** menu. +Select **Raw JSON** mode. +Copy and paste the following: + +```json {class="line-numbers linkable-line-numbers"} +"name" : "", +"type" : "movement_sensor", +"model" : "wheeled-odometry", +"attributes" : { + "base" : "", + "left_motors" : ["", ""], + "right_motors" : [""], + "time-interval-msec": +} +``` + +Fill in and edit the attributes as applicable. + +## Attributes + +The following attributes are available for `wheeled-odometry` movement sensors: + +| Name | Type | Inclusion | Description | +| ---- | ---- | --------- | ----------- | +| `base` | string | **Required** | The `name` of the [base](/components/base/) to which the encoders making up this movement sensor are wired. | +| `left_motors` | object | **Required** | A list containing the name of each of the bases' left [position-reporting motors](/components/motor/gpio/). | +| `right_motors` | object | **Required** | A list containing the name of each of the bases' right [position-reporting motors](/components/motor/gpio/). | +| `time_interval_msec` | number | Optional | The time in milliseconds between each wheeled odometry calculation.
Default: `500.0`
|