Skip to content

GPS Example

The GPS Device Service contains a pre-defined device that is registered to Edge Xpert when the service first 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. This example uses the Stemedu USB GPS Module VK-162.

Setup

Prior to starting the GPS Device Service, there are a few steps that must be completed to set up the GPS device and GPS daemon.

Get the Address of the GPS Device

Before plugging the GPS device into the USB socket use the command:

ls /dev

This will show a list of all the connected devices.

Plug the GPS device into the USB. You can check that the device is connected by using the command:

lsusb

This shows all the connected devices, the Stemedu GPD device shows as U-Blox AG.

$ lsusb
Bus 002 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 001 Device 003: ID 1546:01a7 U-Blox AG [u-blox 7]
Bus 001 Device 002: ID 2109:3431 VIA Labs, Inc. Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Repeat the first command and the GPS device will now be listed. The Stemedu USB GPS module is typically listed at /dev/ttyACMO.

Configure the GPS Daemon

Before running this example, ensure that the GPS daemon is running and that the Edge Xpert GPS Device Service has been configured as described in GPS Configuration.

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:

Field Example Value Description Required
Name GPS The unique name used to identify the device Required
Description Global Positioning System Any additional information to help identify the device Optional
Labels GPS Coordinates Any additonal information to help identify the device Optional

Managing Auto Events with Edge Xpert Manager UI

Warning

The onboarded GPS device should not be modified for anything other than auto event management. Changing other configuration values could cause adverse effects.

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:

Note

Please refer to the Edge Xpert Manager UI Device Management capability for full details.

  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 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

Warning

The onboarded GPS device should not be modified for anything other than auto event management. Changing other configuration values could cause adverse effects.

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 below steps:

  1. Retrieve the device ID with the following command:

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

  2. Use the following cURL command to set up two auto events. Ensure you replace <device-id> with the ID retrieved in step 1.

    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"
        }
      ]
    }
  }
]'

    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, set OnChange to true.

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:59987/api/v2/device/name/{deviceName}/{commandName}
Using the example above, this could be: 
http://localhost:59987/api/v2/device/name/GPS/Climb

Note

59987 is the default port for the GPS device service

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.

Note

The profile is already included in the container but is supplied locally for inspection.

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

Any data collected by the Device Service can then be treated 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.

Back to top