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 navigate to the Create component menu. Enter a name for your movement sensor, select the movement-sensor type, and select the gps-nmea model.

Click Create Component.

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

Edit and fill in the attributes as applicable.

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

{
  "components": [
    {
      "name": "my-gps-nmea",
      "type": "movement_sensor",
      "model": "gps-nmea",
      "attributes": {
        "connection_type": "serial",
        "serial_attributes": {
          "serial_baud_rate": 115200,
          "serial_path": "/dev/serial/by-path/<device_ID>"
        }
      },
      "depends_on": [],
    }
  ]
}

Note that the example "serial_path" filepath is specific to serial devices connected to Linux systems.

{
  "components": [
    {
      "name": "my-gps-nmea",
      "type": "movement_sensor",
      "model": "gps-nmea",
      "attributes": {
        "board": "local",
        "connection_type": "I2C",
        "i2c_attributes": {
          "i2c_baud_rate": 115200,
          "i2c_addr": 111,
          "i2c_bus": "<name_of_bus_on_board>"
        }
      },
      "depends_on": []
    }
  ]
}

Attributes

NameTypeInclusionDescription
connection_typestringRequired"I2C" or "serial". See connection configuration info.
boardstringdepends on connection typeThe name of the board connected to the chip. Required for NMEA over I2C. Not required for serial communication.
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 also 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.

Serial Config Attributes

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

NameTypeDefault ValueDescription
serial_pathstring-The name of the port through which the sensor communicates with the computer.
serial_baud_rateint115200The rate at which data is sent from the sensor. Optional.

Serial communication uses a filepath instead of relying on any specific piece of board hardware, so no “board” attribute is needed when configuring a movement sensor with this communication method.

{
    "name": "<my-movement-sensor-name>",
    "type": "<type>",
    "model": "<model>",
    "attributes": {
        "<whatever other attributes>": "<example>",
        "connection_type": "serial",
        "serial_attributes": {
            "serial_baud_rate": 115200,
            "serial_path": "<PATH>"
        }
    }
}

I2C Config Attributes

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

NameTypeDefault ValueDescription
i2c_busstring-The name of I2C bus wired to the sensor.
i2c_addrint-The device’s I2C address.
i2c_baud_rateint115200The rate at which data is sent from the sensor. Optional.

You’ll also need to configure the board attribute with the name of the board to which the I2C connection is being made.

{
    "name": "<my-movement-sensor-name>",
    "type": "<TYPE>",
    "model": "<MODEL>",
    "attributes": {
        "board": "<name of board, e.g. local>",
        "<whatever other attributes>": "<example>",
        "connection_type": "I2C",
        "i2c_attributes": {
            "i2c_addr": 111,
            "i2c_bus": "1"
        }
    }
}


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