Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS-906: Document wheeled-odometry model of movement sensor #1734

Merged
merged 35 commits into from
Sep 6, 2023
Merged
Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
dfcd2b5
make wheeledodometry page
sguequierre Sep 1, 2023
366cabf
make wheeledodometry page better
sguequierre Sep 1, 2023
4975d81
Update wheeledodometry.md make time_interval_msec optional
sguequierre Sep 1, 2023
8d20302
Update docs/components/movement-sensor/wheeledodometry.md
sguequierre Sep 1, 2023
9cc187d
Add configure base step
sguequierre Sep 1, 2023
f801f13
Apply rand's inline suggestions from code review
sguequierre Sep 1, 2023
4afa892
Apply suggestions from code review position reporting motors
sguequierre Sep 1, 2023
45eb353
Apply suggestions from code review more fix with `wheeledodometry`
sguequierre Sep 1, 2023
e968221
Update wheeledodometry.md more suggestions from code review
sguequierre Sep 1, 2023
047e2cd
Update wheeledodometry.md more suggestions from code review
sguequierre Sep 1, 2023
0b589d4
Remove trailing space
sguequierre Sep 1, 2023
3a761f2
Fix typo (#1726)
mcvella Aug 31, 2023
4c897d8
Update image on servo test sections (#1728)
npentrel Sep 1, 2023
5b503f4
DOCS-1058: Add --force flag to CLI (#1727)
andf-viam Sep 1, 2023
eff3ebd
add tip about roboclaw and rename file
sguequierre Sep 1, 2023
e7f6bc8
Update movement sensor page link to wheeled-odometry for page renaming
sguequierre Sep 1, 2023
c9f4d34
Apply suggestions from code review
sguequierre Sep 1, 2023
0d485e5
Merge branch 'main' into DOCS-906/wheeled-encoder
sguequierre Sep 1, 2023
eef4f19
Apply suggestions from rand/martha inline code review
sguequierre Sep 5, 2023
904d382
Apply suggestions from code review add warning for time interval
sguequierre Sep 5, 2023
26dc6df
Update docs/components/movement-sensor/wheeled-odometry.md
sguequierre Sep 5, 2023
b845418
Remove trailing space
sguequierre Sep 5, 2023
138bd6c
Update docs/components/movement-sensor/wheeled-odometry.md
sguequierre Sep 5, 2023
8cb1e0d
Apply final suggestions from code review
sguequierre Sep 5, 2023
8858a08
Apply andrew suggestions from code review for clarity
sguequierre Sep 6, 2023
5b8efa3
Apply suggestions from code review change tags
sguequierre Sep 6, 2023
8095af2
Apply suggestions from code review make what this is more clear
sguequierre Sep 6, 2023
0a657dd
Apply suggestions from code review
sguequierre Sep 6, 2023
24dc836
fixup
sguequierre Sep 6, 2023
af320a2
fixup blank line
sguequierre Sep 6, 2023
72afcd6
Fixup
sguequierre Sep 6, 2023
5a8a967
Fixup modelname `wheeled-odometry`
sguequierre Sep 6, 2023
498f4f0
Fixup `wheeledodometry` to `wheeled-odometry`
sguequierre Sep 6, 2023
4ed6cea
Update docs/components/movement-sensor/wheeled-odometry.md
sguequierre Sep 6, 2023
e07588d
Merge branch 'main' into DOCS-906/wheeled-encoder
sguequierre Sep 6, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/components/movement-sensor/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ Model | Description <a name="model-table"></a>
[`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`](./wheeledodometry/) | A model that uses [encoders](/components/encoder/) to get an odometry estimate from a wheeled base
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
[`fake`](./fake/) | Used to test code without hardware

## Control your movement sensor with Viam's client SDK libraries
Expand Down
60 changes: 60 additions & 0 deletions docs/components/movement-sensor/wheeledodometry.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
title: "Configure a wheeledodometry movement sensor"
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
linkTitle: "wheeled-odometry"
type: "docs"
description: "Configure a wheeled-odometry movement sensor."
images: ["/icons/components/imu.svg"]
tags: ["movement sensor", "components", "movement sensor"]
# SMEs: Rand, Martha
---

Configure a `wheeled-odometry` movement sensor to implement _wheeled odometry_ on your robot.

_Wheeled odometry_ is the estimation of position, orientation, linear velocity, and angular velocity using the dimensions of a base.
This model uses [encoders](/components/encoder/) from [position reporting motors](/components/motor/gpio/) to get an odometry estimate from a wheeled base.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved

## 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This instruction is specific to the gpio motor model only - I would say "pick out a motor that can report it's position through encoders"

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Put this on line 25-- lmk if you want me to move to be in that first sentence! I also moved a lot of the info
i had on the bottom of the page before so that people scanning can see the info about why it's useful more easily-- lmk what you think

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

happy to add a few more sentences like this is why this is useful if you want!


- Configure your rover as a [wheeled base component](/components/base/wheeled/).
- Configure each of these position-reporting motors [as `gpio` motor components](/components/motor/gpio/).
randhid marked this conversation as resolved.
Show resolved Hide resolved
- Configure an [encoder component](/components/encoder/#configuration) for each of the encoders you attached to the position-reporting motors.
- Then, proceed to [configure](#configuration) a `wheeledodometry` movement sensor with the name of each of the encoder 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" : "<your-wheeledodometry-movement-sensor-name>",
"type" : "movement_sensor",
"model" : "wheeledodometry",
"attributes" : {
"base" : "<your-base-name>",
"left_motors" : ["<your-base-left-motor-name-1>", "<your-base-left-motor-name-2>"],
"right_motors" : ["<your-base-right-motor-name-1", "your-base-right-motor-name-2>"],
"time-interval-msec": <number>
}
```

Fill in and edit the attributes as applicable.

## Attributes

The following attributes are available for `wheeledodometry` 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 struct holding the name of each of the bases' left [position-reporting motors](/components/motor/gpio/). |
| `right_motors` | object | **Required** | A struct holding the name of each of the bases' right [position-reporting motors](/components/motor/gpio/). |
| `time_interval_msec` | number | Optional | The time in between each wheeled odometry calculation. <br> Default: `500.0` </br> |

With a configured `wheeledodometry` movement sensor, after every time `time_interval_msec` elapses during a [session](/program/apis/sessions/), your robot calculates an estimation of the position, orientation, linear velocity, and angular velocity of the wheeled base.
sguequierre marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
With a configured `wheeledodometry` movement sensor, after every time `time_interval_msec` elapses during a [session](/program/apis/sessions/), your robot calculates an estimation of the position, orientation, linear velocity, and angular velocity of the wheeled base.
With a configured `wheeled-odometry` movement sensor, after every time `time_interval_msec` elapses during a [session](/program/apis/sessions/), your robot calculates an estimation of the position, orientation, linear velocity, and angular velocity of the wheeled base.

You can access these readings through the [movement sensor API](/components/movement-sensor/#api).

After configuring a `wheeled-odometry` movement sensor, you can operate your base with Viam's built-in services like the [navigation service](/services/navigation/).