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.

Sign up for GitHub

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

Update README.md #9

Merged
merged 2 commits into from
Feb 11, 2025
Merged

Update README.md #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d9b57e
Update README.md
JohnN193 Feb 10, 2025
3a84b82
Update meta.json
JohnN193 Feb 10, 2025
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
138 changes: 40 additions & 98 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,14 +11,14 @@ The `rtk-serial` model uses an over-the-internet correction source like an RTK r

Follow the guide to [Set up a SparkFun RTK Reference Station](https:docs.viam.com/components/movement-sensor/set-up-base-station/) to configure a SparkFun station for use with this RTK-enabled GPS movement sensor model.

## Configure your rtk-serial movement_sensor

> [!NOTE]
> Before configuring your movement_sensor, you must [create a machine](https://docs.viam.com/cloud/machines/#add-a-new-machine).

Navigate to the [**CONFIGURE** tab](https://docs.viam.com/configure/) of your [machine](https://docs.viam.com/fleet/machines/) in the [Viam app](https://app.viam.com/).
[Add movement_sensor / gps:MODEL to your machine](https://docs.viam.com/configure/#components).

## Configure your rtk-serial movement_sensor

On the new component panel, copy and paste the following attribute template into your movement_sensor's attributes field:

```json
Expand Down Expand Up @@ -47,25 +47,17 @@ The following attributes are available for `viam:gps:rtk-serial` movement_sensor
| `ntrip_connect_attempts` | int | Optional | How many times to attempt connection before timing out. <br> Default: `10` |
| `ntrip_mountpoint` | string | Optional | If you know of an RTK mountpoint near you, write its identifier here. It will be appended to NTRIP address string (for example, "nysnet.gov/rtcm/**NJMTPT1**") and that mountpoint's data will be used for corrections. |

## Example configuration
### Example Configuration

### `viam:gps:rtk-serial`
```json
{
"name": "<your-gps-rtk-serial-movement_sensor-name>",
"model": "viam:gps:rtk-serial",
"type": "movement_sensor",
"namespace": "rdk",
"attributes": {
"serial_path": "/dev/serial/by-path/usb-0:1.1:1.0",
"serial_baud_rate": 115200,
"ntrip_connect_attempts": 12,
"ntrip_mountpoint": "MNTPT",
"ntrip_password": "pass",
"ntrip_url": "http://ntrip/url",
"ntrip_username": "usr"
},
"depends_on": []
"serial_path": "/dev/serial/by-path/usb-0:1.1:1.0",
"serial_baud_rate": 115200,
"ntrip_connect_attempts": 12,
"ntrip_mountpoint": "MNTPT",
"ntrip_password": "pass",
"ntrip_url": "http://ntrip/url",
"ntrip_username": "usr"
}
```

Expand All @@ -79,12 +71,6 @@ If you are not sure where to start, check out this [GPS-RTK2 Hookup Guide from S

## Configure your rtk-pmtk movement_sensor

> [!NOTE]
> Before configuring your movement_sensor, you must [create a machine](https://docs.viam.com/cloud/machines/#add-a-new-machine).

Navigate to the [**CONFIGURE** tab](https://docs.viam.com/configure/) of your [machine](https://docs.viam.com/fleet/machines/) in the [Viam app](https://app.viam.com/).
[Add movement_sensor / gps:MODEL to your machine](https://docs.viam.com/configure/#components).

On the new component panel, copy and paste the following attribute template into your movement_sensor's attributes field:

```json
Expand Down Expand Up @@ -115,16 +101,10 @@ The following attributes are available for `viam:gps:rtk-pmtk` movement_sensors:
| `ntrip_connect_attempts` | int | Optional | How many times to attempt connection before timing out. <br> Default: `10` |
| `ntrip_mountpoint` | string | Optional | If you know of an RTK mountpoint near you, write its identifier here. It will be appended to NTRIP address string (for example, "nysnet.gov/rtcm/**NJMTPT1**") and that mountpoint's data will be used for corrections. |

## Example configuration
### Example Configuration

### `viam:gps:rtk-pmtk`
```json
{
"name": "<your-gps-rtk-pmtk-movement_sensor-name>",
"model": "viam:gps:rtk-pmtk",
"type": "movement_sensor",
"namespace": "rdk",
"attributes": {
"i2c_addr": 66,
"i2c_baud_rate": 115200,
"i2c_bus": "1",
Expand All @@ -133,8 +113,6 @@ The following attributes are available for `viam:gps:rtk-pmtk` movement_sensors:
"ntrip_password": "pass",
"ntrip_url": "http://ntrip/url",
"ntrip_username": "usr"
},
"depends_on": []
}
```

Expand All @@ -150,12 +128,6 @@ The `gps-nmea` movement sensor model supports [NMEA-based](https://en.wikipedia.
This GPS model uses communication standards set by the National Marine Electronics Association (NMEA).
The `gps-nmea` model can be connected using USB and send data through a serial connection to any device, or employ an I<sup>2</sup>C connection to a board.

> [!NOTE]
> Before configuring your movement_sensor, you must [create a machine](https://docs.viam.com/cloud/machines/#add-a-new-machine).

Navigate to the [**CONFIGURE** tab](https://docs.viam.com/configure/) of your [machine](https://docs.viam.com/fleet/machines/) in the [Viam app](https://app.viam.com/).
[Add movement_sensor / gps:MODEL to your machine](https://docs.viam.com/configure/#components).

On the new component panel, copy and paste the following attribute template into your movement_sensor's attributes field:

```json
Expand All @@ -179,7 +151,7 @@ The following attributes are available for `viam:gps:nmea` movement_sensors:

| Attribute | Type | Required? | Description |
| --------- | ---- | --------- | ---------- |
| `connection_type` | string | **Required** | `"I2C"` or `"serial"`. See [Connection Attributes](#connection-attributes) below. |
| `connection_type` | string | **Required** | `"I2C"` or `"serial"`. See **Connection Attributes** below. |

### Connection attributes

Expand All @@ -193,75 +165,53 @@ Then create a struct within `attributes` for either `serial_attributes` or `i2c_

For a movement sensor communicating over serial, you'll need to include a `serial_attributes` struct containing:

<!-- prettier-ignore -->
| Name | Type | Required? | Description |
| ------------------ | ------ | --------- | ------------ |
| `serial_path` | string | **Required** | The full filesystem path to the serial device, starting with <file>/dev/</file>. To find your serial device path, first connect the serial device to your machine, then:<ul><li>On Linux, run <code>ls /dev/serial/by-path/\*</code> to show connected serial devices, or look for your device in the output of <code>sudo dmesg \| grep tty</code>. Example: <code>"/dev/serial/by-path/usb-0:1.1:1.0"</code>.</li><li>On macOS, run <code>ls /dev/tty\* \| grep -i usb</code> to show connected USB serial devices, <code>ls /dev/tty\*</code> to browse all devices, or look for your device in the output of <code>sudo dmesg \| grep tty</code>. Example: <code>"/dev/ttyS0"</code>.</li></ul> |
| `serial_baud_rate` | int | Optional | The rate at which data is sent from the sensor. <br> Default: `38400` |
| `serial_path` | string | **Required** | The full filesystem path to the serial device, starting with `/dev/` |
| `serial_baud_rate` | int | Optional | The rate at which data is sent from the sensor. Default: `38400` |

- On Linux, run `ls /dev/serial/by-path/` to show connected serial devices, or look for your device in the output of `sudo dmesg | grep tty`. Example: `"/dev/serial/by-path/usb-0:1.1:1.0"`.
- On macOS, run `ls /dev/tty* | grep -i usb` to show connected USB serial devices, `ls /dev/tty*` to browse all devices, or look for your device in the output of `sudo dmesg | grep tty`. Example: `"/dev/ttyS0"`.

### I2C config attributes

For a movement sensor communicating over I<sup>2</sup>C, you'll need a `i2c_attributes` struct containing:
For a movement sensor communicating over I2C, you'll need a `i2c_attributes` struct containing:

<!-- prettier-ignore -->
| Name | Type | Required? | Description |
| --------------- | ------ | --------- | ----------- |
| `i2c_bus` | string | **Required** | The index of the I<sup>2</sup>C bus on the board wired to the sensor. |
| `i2c_addr` | int | **Required** | The device's I<sup>2</sup>C address. |
| `i2c_baud_rate` | int | Optional | The rate at which data is sent from the sensor. Optional. <br> Default: `38400` |
| `i2c_bus` | string | **Required** | The index of the I2C bus on the board wired to the sensor. |
| `i2c_addr` | int | **Required** | The device's I2C address. |
| `i2c_baud_rate` | int | Optional | The rate at which data is sent from the sensor. Optional. Default: `38400` |

## Example configurations
### Example configurations

### `viam:gps:nmea` serial connection
#### `viam:gps:nmea` serial connection
```json
{
"name": "<your-gps-nmea-movement_sensor-name>",
"model": "viam:gps:nmea",
"type": "movement_sensor",
"namespace": "rdk",
"attributes": {
"connection_type": "serial",
"serial_attributes": {
"serial_path": "/dev/serial/by-path/usb-0:1.1:1.0",
"serial_baud_rate": 38400
}
},
"depends_on": []
"connection_type": "serial",
"serial_attributes": {
"serial_path": "/dev/serial/by-path/usb-0:1.1:1.0",
"serial_baud_rate": 38400
}
}
```

The `"serial_path"` filepath used in this example is specific to serial devices connected to Linux systems.
The `"serial_path"` filepath on a macOS system might resemble <file>"/dev/ttyUSB0"</file> or <file>"/dev/ttyS0"</file>.

### `viam:gps:nmea` i2c connection
#### `viam:gps:nmea` i2c connection
```json
{
"name": "<your-gps-nmea-movement_sensor-name>",
"model": "viam:gps:nmea",
"type": "movement_sensor",
"namespace": "rdk",
"attributes": {
"connection_type": "I2C",
"i2c_attributes": {
"i2c_bus": "1",
"i2c_addr": 111,
"i2c_baud_rate": 38400
}
},
"depends_on": []
"connection_type": "I2C",
"i2c_attributes": {
"i2c_bus": "1",
"i2c_addr": 111,
"i2c_baud_rate": 38400
}
}
```

## Configure your rtk-dual-gps movement_sensor

The `dual-gps-rtk` model of movement sensor calculates a compass heading from two GPS movement sensors, and returns the midpoint position between the first and second GPS devices as its position.

> [!NOTE]
> Before configuring your movement_sensor, you must [create a machine](https://docs.viam.com/cloud/machines/#add-a-new-machine).

Navigate to the [**CONFIGURE** tab](https://docs.viam.com/configure/) of your [machine](https://docs.viam.com/fleet/machines/) in the [Viam app](https://app.viam.com/).
[Add movement_sensor / gps:MODEL to your machine](https://docs.viam.com/configure/#components).

On the new component panel, copy and paste the following attribute template into your movement_sensor's attributes field:

```json
Expand All @@ -280,23 +230,15 @@ The following attributes are available for `viam:gps:rtk-dual-gps` movement_sens
| --------- | ---- | --------- | ---------- |
| `first_gps` | int | **Required** | The name you have configured for the first movement sensor you want to combine the measurements from. Must be a GPS model. |
| `second_gps` | string | **Required** | The name you have configured for the second movement sensor you want to combine the measurements from. Must be a GPS model. |
| `offset_degrees` | int | Optional | The value to offset the compass heading calculation between the two GPS devices based on their positions on the base. Calculate this as the degrees between the vector from `first_gps` to `second_gps` and the vector from the vehicle's back to the vehicle's front, counterclockwise. {{< imgproc src="/components/movement-sensor/offset_degrees.png" alt="Rand's diagram of 3 offset degree calculations." resize="600x" >}} <br> Default: `90` |
| `offset_degrees` | int | Optional | The value to offset the compass heading calculation between the two GPS devices based on their positions on the base. Calculate this as the degrees between the vector from `first_gps` to `second_gps` and the vector from the vehicle's back to the vehicle's front, counterclockwise. Default: `90` |

## Example configuration
### Example configuration

### `viam:gps:rtk-dual-gps`
```json
{
"name": "<your-gps-rtk-dual-gps-movement_sensor-name>",
"model": "viam:gps:rtk-dual-gps",
"type": "movement_sensor",
"namespace": "rdk",
"attributes": {
"first_gps": "gps-1",
"second_gps": "gps-2",
"offset_degrees": 90
},
"depends_on": []
"first_gps": "gps-1",
"second_gps": "gps-2",
"offset_degrees": 90
}
```

Expand Down
18 changes: 13 additions & 5 deletions meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,19 +7,27 @@
"models": [
{
"api": "rdk:component:movement_sensor",
"model": "viam:gps:rtk-serial"
"model": "viam:gps:rtk-serial",
"markdown_link": "README.md#configure-your-rtk-serial-movement_sensor",
"short_description": "movement sensor model for gps rtk using a serial connection."
},
{
"api": "rdk:component:movement_sensor",
"model": "viam:gps:rtk-pmtk"
"model": "viam:gps:rtk-pmtk",
"markdown_link": "README.md#configure-your-rtk-pmtk-movement_sensor",
"short_description": "movement sensor model for gps rtk using a serial connection."
},
{
"api": "rdk:component:movement_sensor",
"model": "viam:gps:nmea"
"model": "viam:gps:nmea",
"markdown_link": "README.md#configure-your-nmea-movement_sensor",
"short_description": "movement sensor model for basic gps capabilities."
},
{
"api": "rdk:component:movement_sensor",
"model": "viam:gps:rtk-dual-gps"
"model": "viam:gps:rtk-dual-gps",
"markdown_link": "README.md#configure-your-rtk-dual-gps-movement_sensor",
"short_description": "movement sensor model for a dual gps rtk setup."
}
],
"build": {
Expand All @@ -28,4 +36,4 @@
"arch" : ["linux/arm64", "linux/amd64", "darwin/arm64"]
},
"entrypoint": "bin/gps"
}
}