GPS Example

The GPS Device Service contains a pre-defined device that is registered with Edge Xpert when the service initializes. The GPS device is defined by a built-in device profile that ships with the GPS Device Service.

This example demonstrates how to use the GPS Device Service to connect to a GPS sensor. In this example, a GPS simulator is used.

Run the GPS simulator

To start the GPS simulator, enter the following command:

docker run --rm -d --name gps-sim -p 2947:2947 knowhowlab/gpsd-nmea-simulator

podman run --rm -d --name gps-sim -p 2947:2947 knowhowlab/gpsd-nmea-simulator

Start the GPS Device Service

To start the GPS Device Service, enter the following command:

edgexpert up device-gps

Device Onboarding

The GPS Device Service initializes with a pre-configured device. This is a connection to the GPS daemon which acts as a bridge between the device service and GPS devices.

As the GPS Device Service does not connect to devices directly, device onboarding is not required with this Device Service. However, the device configuration properties are defined below for reference purposes.

Device Configuration Properties

The pre-defined device has the following properties:

Managing Auto Events with Edge Xpert Manager UI

Although the device is pre-configured, it is possible to modify the GPS device to manage auto events to issue automated commands. The Edge Xpert GPS device can be modified to add, edit, and delete auto events. To manage auto events in Edge Xpert Manager UI, follow the below steps:

1. Ensure the Edge Xpert Manager UI is started, for example:

   edgexpert up xpert-manager
   

2. Open a browser and go to localhost:9090. The default username and password is admin.

3. Navigate to Devices, and locate the GPS entry. Select the pencil icon to edit the device.

4. Scroll down until you find Auto Events. Select the plus button and use the following to create an auto event:

   • Interval: 1s
   • On Change: false/unchecked
   • Resource Name: Latitude

   Create another with the following:

   • Interval: 1s
   • On Change: false/unchecked
   • Resource Name: Longitude

   This will create an auto event each for Latitude and Longitude. These will issue the relevant commands every second, regardless of whether the values have changed. To only receive auto events if data has changed within your specified interval, select the check box for On Change.

Managing Auto Events with Edge Xpert REST API

The Edge Xpert GPS device can be modified to add, edit, and delete auto events. To manage auto events with Edge Xpert REST API commands, follow the steps below:

curl http://localhost:59881/api/v2/device/name/GPS

curl -X 'PATCH' \
  'http://localhost:59881/api/v2/device' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '[
 {
    "apiVersion": "v2",
    "device": {
      "id": "<device-id>",
      "name": "GPS",
      "autoEvents": [
        {
          "interval": "1s",
          "onChange": false,
          "sourceName": "Latitude"
        },
        {
          "interval": "1s",
          "onChange": false,
          "sourceName": "Longitude"
        }
      ]
    }
  }
]'

curl http://localhost:59881/api/v2/device -H "Content-Type:application/json" -X POST \
-d '[ {
        "apiVersion": "v2",
         "device": {
           "name" :"gps-sim",
           "description":"GPS simulator",
           "serviceName": "device-gps",
           "profileName": "GPS",
           "protocols":{
              "GPS":{
                  "GpsdConnTimeout": "2500",
                  "GpsdHostname": "<your_host_network_ip_address>",
                  "GpsdMode": "poll",
                  "GpsdPort": "2947",
                  "GpsdRequestTimeout": "5000",
                  "GpsdRetries": "5"
              }
           },
           "adminState":"UNLOCKED",
           "operatingState":"UP"
        }
    }
]'

Device Data Flow

Data flow between the Device Service and the connected device can be verified in a number of ways.

The Edge Xpert Manager UI supports Read and Write functionality for each device. Readings can also be viewed and queried within the Edge Xpert Manager UI Data Center.

Alternatively, you can read and write data with cURL commands or through REST API applications, such as Postman.

Both the GET and PUT requests can be made to the following address:

http://localhost:59882/api/v2/device/name/{deviceName}/{commandName}

Using the example above, a GET request to this device service could be:

curl http://localhost:59882/api/v2/device/name/GPS/Climb

This command retrieves the vertical speed in meters per second from the Climb sensor. The commands available for use with the GPS Device Service can be found at /usr/share/edgexpert/examples/device-services/gps/GPS.yaml.

For more information on using API commands, see the API.

Any data collected by the Device Service can then be processed like all other Edge Xpert sensor data. The data readings can be exported for data processing in a number of other applications and services. See the Supporting Services and Application Services documentation for more details.