Skip to content

GPS Device Service Component

The GPS Device Service component integrates the GPS protocol with XRT and supports reading the following GPS data:

  • Time
  • Date
  • Track
  • Climb
  • Altitude
  • Speed
  • Latitude
  • Longitude

GPS Device Service Configuration

Note

The core components required for running GPS (and all other device services) are contained in Device Service Component Configuration. Please refer to this page to ensure the appropriate core components are assigned before continuing.

GPS Configuration File Example

An example for the GPS configuration file is shown below:

{
  "Library": "libxrt-gps-device-service.so",
  "Factory": "xrt_gps_device_service_factory",
  "Name":"gps",
  "TelemetryTopic":"xrt/devices/gps/telemetry",
  "RequestTopic": "xrt/devices/gps/request",
  "ReplyTopic": "xrt/devices/gps/reply",
  "AutoRegister": true,
  "PublishRegisteredDevices": true,
  "PublishAttributes": true,
  "ProfileDir":"./deployment/profiles",
  "StateDir":"./deployment/state",
  "Scheduler":"sched",
  "Logger":"logger",
  "ThreadPool":"pool",
  "Bus":"bus",
}

GPS Device Profile

Details on general profile usage can be found on the Device Profiles page.

The following sections will cover how device resources are used in GPS.

Attributes

The attributes used in a GPS device resource are used to identify what GPS data is to be read. The attribute options are detailed in the following table:

Attribute Description Valid Values
data The type of GPS data the resource will be requesting
  • date - The date data from the GPS endpoint
  • time - The time from the GPS endpoint
  • track - Course over ground in degrees from true north
  • climb - Vertical speed in meters per second
  • altitude - Altitude in meters
  • speed - Speed over ground in meters per second
  • latitude - Latitude positional data in degrees
  • longitude - Longitude positional data in degrees

Data Types

The table below details the Data Type that the resource in the Device Profile should be set to based on the attitbute data value:

Attribute Value Data Type
date String
time Float64
track Float64
climb Float64
altitude Float64
speed Float64
latitude Float64
longitude Float64

Example Device Resources

In the following example the resource is set to read longitude data from GPSD. Longitude data is returned in degrees with a Data Type of Float64.

"deviceResources": [
    {
      "description": "Get the longitude in Degrees",
      "attributes": {
        "data": "longitude"
      },
      "name": "Longitude", 
      "properties": {
        "readWrite": "R",
        "valueType": "Float64"
      }
    }
  ]

In the following example the resource is set to read latitude data from GPSD. Latitude data is returned in degrees with a Data Type of Float64.

"deviceResources": [
    {
      "description": "Get the latitude in Degrees",
      "attributes": {
        "data": "latitude"
      },
      "name": "Latitude", 
      "properties": {
        "readWrite": "R",
        "valueType": "Float64"
      }
    }
]

Device Commands

See the Device Profiles page for details on how to define device commands for grouping device resources for fewer requests.

GPS Device Provisioning

The following section will explain how to configure a device for the GPS Device Service.

Note

For information on dynamic device additions, removals and updates please see the MQTT API Guide.

GPS Device Protocol Properties

The GPS Device Service component has protocol properties that can be set to configure a device. If these are not set in the GPS device configuration file, default values will be used to attempt a connection to a default instance of GPSD. The table below details these protocol properties showing the default values in the examples:

Parameter Type Description Default Value
GpsdHostname String The host name for where the GPSD instance is running. This can be set to an IP address or a container name if GPSD is running in a docker container "0.0.0.0"
GpsdPort Unsigned Integer The port to connect to the GPSD instance. 2947
GpsdMode String The mode in which to connect to GPSD. The options are poll or nopoll, with poll maintaining a constant connection and data update and nopoll establishing a connection per request to update with the current GPS data "poll"
GpsdRetries Unsigned Integer The amount of times to retry establishing a connection 3
GpsdConnTimeout Unsigned Integer The time in milliseconds for timeout when establishing a connection 2500
GpsdRequestTimeout Unsigned Integer the time in milliseconds for timeout when making a request 5000

Provisioning

An example of a GPS device within the devices.json file is provided below:

{
  "gps-sim": {
    "profileName": "GPS-Device",
    "protocols": {
        "GPS": {
          "GpsdConnTimeout": 2500,
          "GpsdHostname": "0.0.0.0",
          "GpsdMode": "poll",
          "GpsdPort": 2947,
          "GpsdRequestTimeout": 5000,
          "GpsdRetries": 5
      }
    }
  }
}

GPS Device Interaction

For information on how to dynamically execute reads, writes, setting up schedules and more, please refer to the MQTT API Guide.

For interactive examples of the GPS Device Service refer to GPS XRT Example. Follow the instructions in those links which will demonstrate many features of XRT with the device service running against a GPS simulator.

Run the GPS Device Service

Find details on how to run the GPS Device Service on the Run Device Services page.

Back to top