Configure an NMEA-based GPS

A global positioning system (GPS) receives signals from satellites in the earth’s orbit to determine where it is and how fast it is going. All supported GPS models provide data for the Position, CompassHeading and LinearVelocity methods. You can obtain fix and correction data by using the sensor GetReadings method, which is available because GPSes wrap the sensor component.

The gps-nmea movement sensor model supports NMEA-based GPS units.

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 I2C connection to a board:

Navigate to the Config tab of your robot’s page in the Viam app. Click on the Components subtab and click Create component. Select the movement-sensor type, then select the gps-nmea model. Enter a name for your movement sensor and click Create.

Creation of a `gps-nmea` movement sensor in the Viam app config builder.

Copy and paste the following attribute template into your movement sensor’s Attributes box. Then remove and fill in the attributes as applicable to your movement sensor, according to the table below.

{
  "connection_type": "<serial|I2C>",
  "serial_attributes": {
    "serial_path": "<your-device-path>",
    "serial_baud_rate": <int>
  },
  "i2c_attributes": {
    "board": "<your-board-name>",
    "i2c_bus": "<name-of-bus-on-board>",
    "i2c_addr": <int>,
    "i2c_baud_rate": <int>
  },
  "disable_nmea": <boolean>
}

{
  "connection_type": "serial",
  "serial_attributes": {
    "serial_path": "/dev/serial/by-path/<device_ID>",
    "serial_baud_rate": 38400
  }
}

{
  "connection_type": "I2C",
  "i2c_attributes": {
    "board": "local",
    "i2c_bus": "1",
    "i2c_addr": 111,
    "i2c_baud_rate": 38400
  }
}

{
  "components": [
    {
      "name": "<your-sensor-name>",
      "model": "gps-nmea",
      "type": "movement_sensor",
      "namespace": "rdk",
      "attributes": {
        "connection_type": "<serial|I2C>",
        "serial_attributes": {
          "serial_path": "<your-device-path>",
          "serial_baud_rate": <int>
        },
        "i2c_attributes": {
            "board": "<your-board-name>",
            "i2c_bus": "<name-of-bus-on-board>",
            "i2c_addr": <int>,
            "i2c_baud_rate": <int>
        },
        "disable_nmea": <boolean>
      },
      "depends_on": [],
    }
  ]
}

{
  "components": [
    {
      "name": "my-gps-nmea",
      "model": "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": []
    }
  ]
}

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 "/dev/ttyUSB0" or "/dev/ttyS0".

{
  "components": [
    {
      "name": "my-gps-nmea",
      "model": "gps-nmea",
      "type": "movement_sensor",
      "namespace": "rdk",
      "attributes": {
        "connection_type": "I2C",
        "i2c_attributes": {
          "board": "local",
          "i2c_bus": "1",
          "i2c_addr": 111,
          "i2c_baud_rate": 38400
        }
      },
      "depends_on": []
    }
  ]
}

Attributes

NameTypeInclusionDescription
connection_typestringRequired"I2C" or "serial". See Connection Attributes below.
disable_nmeabooleanOptionalIf set to true, changes the NMEA message protocol to RTCM when using a chip as a base station.
Default: false

Connection Attributes

You need to configure attributes to specify how the GPS connects to your computer. You can use either serial communication (over USB) or I2C communication (through pins to a board).

Use connection_type to specify "serial" or "I2C" connection in the main attributes config. Then create a struct within attributes for either serial_attributes or i2c_attributes, respectively. See examples of this struct in the example tabs above.

Serial Config Attributes

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

NameTypeInclusionDescription
serial_pathstringRequiredThe full filesystem path to the serial device, starting with /dev/. To find your serial device path, first connect the serial device to your machine, then:
  • 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".
serial_baud_rateintOptionalThe rate at which data is sent from the sensor.
Default: 38400

I2C Config Attributes

For a movement sensor communicating over I2C, you’ll need a i2c_attributes struct containing:

NameTypeInclusionDescription
boardstringRequiredThe name of the board to which the I2C connection is being made.
i2c_busstringRequiredThe name of the I2C bus wired to the sensor.
i2c_addrintRequiredThe device’s I2C address.
i2c_baud_rateintOptionalThe rate at which data is sent from the sensor. Optional.
Default: 38400

Test the movement sensor

After you configure your movement sensor, navigate to the Control tab and select the dedicated movement sensor dropdown panel. This panel presents the data collected by the movement sensor. The sections in the panel include the position, linear velocity and compass heading.

The movement sensor component in the control tab


Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.