Fleet of Devices

Consider there are a number of vehicles running the QNX CAR platform that need to be tracked and managed. To achieve this, location data is required. In this use case, we explore how to generate data from a single device running the QNX CAR platform. This data can be used to develop useful dashboards to monitor and analyze fleets of devices.


1. Configure QNX Agent

Configure the QNX Agent to listen to location data and sync that data to the BlackBerry IoT Platform. Follow steps from Connect QNX CAR Platform to BlackBerry IoT Platform to add the following path to the configuration file.

{
  "path": "/pps/qnxcar/navigation/status",
  "id": "location.status",
  "realtime": true
}


Here's what the QNX Agent configuration file should look like after you modify it:

{
  "url": "https://bbryiot.com",
  "auth_url": "https://auth.bbryiot.com",
  "secretsfile": "/var/bipd/secrets",
  "keyfile": "/var/bipd/private_key",
  "certfile": "/var/bipd/certificate",
  "sync": {
    "paths": [
      {
        "path": "/pps/qnxcar/sensors",
        "id": "carsensors",
        "realtime":true
      },
      {
        "path": "/pps/qnxcar/navigation/status",
        "id": "location.status",
        "realtime": true
      }
    ]
  }
}


2. Configure data persistence for QNX CAR Application

Use the QNX Agent application from Connect QNX Car to the BlackBerry IoT Platform and configure it to persist 30 days worth of data. By default, data isn't retained and only last value is retained. To persist data, add a data retention in the administration console.

Use the following values:

To learn more about the supported data categories, see Working with Data.


3. Generating location data from device running the QNX CAR platform reference image

The QNX CAR platform reference image comes with a Navigation screen (an application running Eletrobit (EB) street director navigation software) that simulates the car driving to a specified address. The Navigation screen shows turn-by-turn directions stored in a Persistent Publish/Subscribe (PPS) object located at /pps/qnxcar/navigation/status.

To run use the navigation software:

  1. Launch the Navigation screen on the QNX CAR platform image (VMWare image/target board).
  2. Tap MENU (in the middle of the screen) and provide a destination address.
  3. The Navigation screen starts to simulate driving to the specified location.


The device generates data that looks like this:

destination:json:{"country":"Canada","province":"Ontario","city":"Ottawa","street":"Anywhere Cres","number":"123","longitude":-75.69891600000001,"latitude":45.358923}
eta:n:1434588522
maneuver:json:{"street":"HWY-401 E","turn_type":"nc"}
maneuver_distance:n:6814
maneuvers:json:[{"street":"HWY-401 E","command":"nc","distance":6814},{"street":"HWY-416 N","command":"tr-r","distance":78884},{"street":"Somewhere Rd","command":"tr-r","distance":136748}]
navigating:b:true
speed_limit:n:27
total_distance_remaining:n:155453
total_time_remaining:n:106


4. Create a dashboard application to search location data

Use the administration console to create the application entity. The dashboard will be publicly available with the use of device-based authentication, which uses certificates to authenticate the device. If user-based authentication is required, see user-based authentication.

  1. Create the dashboard application and get the application UUID.

  2. Get the API KEY and API SECRET for the dashboard application

5. Decide on the authentication type to use and get the access token

If this dashboard application requires users to be authenticated before viewing data, make use of user-based authentication. On the other hand, if the dashboard is available publicly make use of cert-based auth. For simplicity of this use case, pick user-based authentication.

Use the Authentication wizard application to get an access_token for user-based authentication. The access token identifies the device that is allowed to interact with the BlackBerry IoT Platform.

Note: The access_token is required to continue with the rest of the steps.


6. Grant capabilities to the dashboard application

For the dashboard application to search data produced by the device running the QNX CAR platform, the application you created called, QNX CAR application, must grant the search.data capability to a user of the dashboard application or an instance (device) of it. This can be done using the administration console.

To understand how capabilities work read Working with Capabilities and Tags

  1. In the administration console, select the QNX CAR Application.

  2. Click Capabilities.

  3. Grant the search.data capability to a user that is logging in from a device.


7. Query all devices that are driving to a specific city

Use the Search API to retrieve data that was gathered from device running the QNX CAR platform.

The search API uses Elasticsearch DSL:

Query

{
  "query": {
    "query_string": {
      "query": "values.destination.city: Ottawa AND id: location.status"
    }
  }
}

The above search query makes use of Elastic Search Query String. The query searches for devices that have a data ID of location.status and within it, has a destination of Ottawa.

Note: The city you use depends on the address entered.

Request

Replace {app_id} with app_id from step 4 and {access_token} from step 6.

curl -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST -d '{"query": {"query_string": {"query": "values.destination.city: Ottawa AND id: location.status"}}}' https://bbryiot.com/api/1/search/data?app_ids={app_id}

8. Query all vehicles (devices) that have been in a specific city.

Historical data to extract driving patterns is available through the search API using the data_ts document type.

The data_ts document type is an index that has 30 days worth of data. You configured this data retention in step 2.

Query

{
  "query": {
    "query_string": {
      "query": "values.destination.city: Ottawa AND id: location.status"
    }
  }
}

Request

Replace {app_id} and {access_token} in the curl command below to what was obtained in step 4 to perform a search.

curl -H "Content-Type: application/json" -H "Authorization: Bearer {access_token}" -X POST -d '{"query": {"query_string": {"query": "values.destination.city: Ottawa AND id: location.status"}}}' https://bbryiot.com/api/1/search/data_ts?app_ids={app_id}


Next Steps