Configure an NTRIP-based RTK 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-ntrip movement sensor model supports NTRIP-based real time kinematic positioning (RTK) GPS units (such as these).

The chip requires a correction source to get to the required positional accuracy. Our gps-rtk model uses an over-the-internet correction source NTRIP and sends the data over serial or I2C.

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-rtk model.

Click Create Component.

Creation of a gps-rtk 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-rtk",
      "attributes": {
        "board": "<your-board-name-if-using-I2C>",
        "connection_type": "<serial|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>"
        },
        "ntrip_attributes": {
          "ntrip_addr": "<URL of NTRIP server>",
          "ntrip_baud": <int>,
          "ntrip_password": "<password for NTRIP server>",
          "ntrip_path": "<your-device-path>",
          "ntrip_username": "<username for NTRIP server>"
        }
      },
      "depends_on": [],
    }
  ]
}

{
  "components": [
    {
      "name": "my_GPS",
      "type": "movement_sensor",
      "model": "gps-rtk",
      "attributes": {
        "connection_type": "serial",
        "correction_source": "ntrip",
        "serial_attributes": {
          "serial_baud_rate": 115200,
          "serial_path": "/dev/serial/by-path/12345"
        },
        "ntrip_attributes": {
          "ntrip_addr": "ntrip_address",
          "ntrip_baud": 38400,
          "ntrip_password": "password",
          "ntrip_username": "username"
        }
      },
      "depends_on": []
    }
  ]
}

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

{
  "components": [
    {
      "name": "my_GPS",
      "type": "movement_sensor",
      "model": "gps-rtk",
      "attributes": {
        "board": "board",
        "connection_type": "I2C",
        "correction_source": "ntrip",
        "i2c_attributes": {
          "i2c_baud_rate": 115200,
          "i2c_addr": 111,
          "I2c_bus": "main",
        },
        "ntrip_attributes": {
          "ntrip_addr": "ntrip_address",
          "ntrip_baud": 38400,
          "ntrip_password": "password",
          "ntrip_username": "username"
        }
      },
      "depends_on": []
    }
  ]
}

Attributes

NameTypeInclusionDescription
boardstringdepends on connection typeRequired for NMEA over I2C; the name of the board connected to the chip. Not required for serial communication.
connection_typestringRequired"I2C" or "serial", respectively. See connection configuration info.
ntrip_addrstringRequiredThe URL of the NTRIP server from which you get correction data. Connects to a base station (maintained by a third party) for RTK corrections
ntrip_usernamestringRequiredUsername for the NTRIP server
ntrip_passwordstringRequiredPassword for the NTRIP server
ntrip_baudintOptionaldefaults to serial_baud_rate
ntrip_connect_attemptsintOptionalHow many times to attempt connection before timing out.
Default: 10
ntrip_mountpointstringOptionalIf 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.
ntrip_pathstringOptionalUse this when extra hardware is piping RTCM data through a second USB port on an board instead of getting it directly from the internet.

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.