Sensor Configuration Integration – SKF Technical Support

Introduction

The Sensor Configuration integration allows for automatic onboarding and offboarding of TraX sensors within the TSPs platform.

The integration handles data such as the Bluetooth address, vehicle identity, and the sensor's position on the vehicle.

We highly recommend reviewing the TraX web API OpenAPI document to fully understand the API's functionality, including its endpoints, payloads, and other important details.

Objectives 🎯

IoT Platform Integration

Identifying sensors.
Managing sensor configuration attributes.
Storing sensor data.

Application Integration

Align the status (sync) of commissioned and decommissioned sensors between SKF and the TSP platforms.

Device Integration

Instruct the gateway to start/stop listening to specific sensors (MAC address filtering).

Identifying Sensors

The hardware address (MAC address) of all TraX sensors has the leading six characters ("c4bd6a") in common. The trailing six characters are unique for each sensor. It´s included in each sensor data broadcast.

We recommend using the hardware address to identify sensors, as opposed to relying on a combination of vehicle ID, axle number, and wheel side. The latter approach creates a tighter coupling to the advertisement frame structure, making it less flexible.

RECOMMENDED: Identify sensors using their hardware address.

Device Configuration Attributes to Manage

Support for several device attributes can make it easier to manage the TraX sensor in the TSP platform. We recommend to manage these device attributes:

Sensor identity (MAC address)
Sensor mounting position (axle & wheel end)
Vehicle the sensor is mounted on
The fleet the vehicle is part of

Notifications When a Sensor Is Commissioned or Decommissioned

A "Sensor configuration changed" event is generated when a sensor is commissioned or decommissioned using the TraX mobile app. It can take up to two minutes for an event to become available.

These events can only be consumed once. To repeatedly query sensors commissioned on a vehicle, refer to the section “Alternative Approach for Retrieving Sensor Configuration for an Entire Vehicle.”

Consume Sensor Configuration Changed Events

The TSP consumes these events using the TraX web or Queue API. Information in the event enables the TSP to onboard or offboard the sensor to its platform.

Retrieving Events From a Queue (recommended):

// Fetch single "Sensor configuration changed" events using queue API
// Queue pattern: trax.{name-of-TSP}.sensor-configuration

// Message payload:

{

  "eventId": 2,
  "eventType": "Sensor configuration changed",
  "resourceType": "Sensor configuration",
  "eventData": {
    "fleetName": "TraX Demo",
    "fleetId": "a14d379e",
    "vehicleName": "SPACE TRUCK 8459",
    "vehicleId": "740f410b",
    "sensorCommissioningStatus": "Commissioned",
    "sensorHardwareAddress": "c4bd6a004091",
    "sensorFirmwareVersion": "bss08d",
    "sensorAxlePosition": 1,
    "sensorWheelSide": "right",
    "sensorChangedAt": "2023-12-19T10:58:11Z"
  }
}

RECOMMENDED: Retrieve sensor configuration changed events from a queue.

Queueing protocols are connection-oriented and often provide more reliable data transport.

Retrieving Events Via the Web API

// Fetch multiple "Sensor configuration changed" events using the web API

GET /vehicles/sensor-configurations/events

// Response payload

{
  "sensorConfigurationEvents": [
    {
      "eventId": 2,
      "eventType": "Sensor configuration changed",
      "resourceType": "Sensor configuration",
      "eventData": {
        "fleetName": "Ken Foods Inc.",
        "fleetId": "159032dc-e809-4a84-b5eb-15b4c0159138",
        "vehicleName": "SPACE TRUCK 8459",
        "vehicleId": "740f410b-7f37-4dbc-9cc5-f7c160005dc7",
        "sensorCommissioningStatus": "Commissioned",
        "sensorHardwareAddress": "000a959d6816",
        "sensorFirmwareVersion": "bss08d",
        "sensorAxlePosition": 1,
        "sensorWheelSide": "left",
        "sensorChangedAt": "2017-07-21T17:32:28Z"
      }
    },
    {
      "eventId": 2,
      "eventType": "Sensor configuration changed",
      "resourceType": "Sensor configuration",
      "eventData": {
        "fleetName": "Ken Foods Inc.",
        "fleetId": "159032dc-e809-4a84-b5eb-15b4c0159138",
        "vehicleName": "SPACE TRUCK 8459",
        "vehicleId": "740f410b-7f37-4dbc-9cc5-f7c160005dc7",
        "sensorCommissioningStatus": "Commissioned",
        "sensorHardwareAddress": "000a959d6812",
        "sensorFirmwareVersion": "bss08d",
        "sensorAxlePosition": 2,
        "sensorWheelSide": "right",
        "sensorChangedAt": "2017-07-21T17:32:28Z"
      }
    }
  ]
}

Alternative Approach for Retrieving Sensor Configuration for an Entire Vehicle

Another option to use the "Sensor configuration changed" event as a trigger to another request that, based on information in the event, fetches all the configured sensors on a vehicle.

Step 1: A TraX mobile app user commissions a sensor.

Step 2: Dequeue a "Sensor configuration changed" event from the queue.

// Queue trax.{name-of-TSP}.sensor-configuration

{

  "eventId": 2,
  "eventType": "Sensor configuration changed",
  "resourceType": "Sensor configuration",
  "eventData": {
    "fleetName": "TraX Demo",
    "fleetId": "a14d379e",
    "vehicleName": "SPACE TRUCK 8459",
    "vehicleId": "740f410b",
    "sensorCommissioningStatus": "Commissioned",
    "sensorHardwareAddress": "c4bd6a004091",
    "sensorFirmwareVersion": "bss08d",
    "sensorAxlePosition": 1,
    "sensorWheelSide": "right",
    "sensorChangedAt": "2023-12-19T10:58:11Z"
  }
}

Step 3: Use "fleetId" and "vehicleId" in the "Sensor configuration changed" event payload to build the URL for retrieving all configured sensors on a vehicle.

// Retrieve all configured sensors on a vehicle

GET /fleets/a14d379e/vehicles/740f410b/sensor-configurations

// Response payload:

{

  "sensors": {
    "expected": 4,
    "commissioned": 4,
    "configurations": [
      {
        "hardwareAddress": "c4bd6addd0f9",
        "firmwareVersion": "bss08b",
        "axlePosition": 3,
        "wheelSide": "right",
        "changedAt": "2022-03-07T16:16:40Z"
      },
      {
        "hardwareAddress": "c4bd6a754714",
        "firmwareVersion": "bss08b",
        "axlePosition": 1,
        "wheelSide": "left",
        "changedAt": "2022-03-07T16:14:52Z"
      },
     ....

    ]

  }

}

Step 4: Compare the sensors in the response with sensors in the TSP platform to determine if a sensor has been commissioned or decommissioned. Once the “delta” is identified, update the TSP’s device configuration repository to ensure it reflects the current configuration state.

Instruct Gateway to Start/Stop Listening to Specific Sensors / MAC Address Filtering

Once the TSP has obtained the sensor configuration for the newly commissioned or decommissioned sensor, the next step is to instruct the gateway.

If a sensor has been commissioned, instruct the gateway to start listening for broadcasts from the newly added sensor.
If a sensor has been decommissioned, instruct the gateway to stop listening for broadcasts from that sensor.

RECOMMENDED: The gateway should filter sensor broadcasts based on hardware address (MAC address) to ensure that data from nearby vehicles is not captured.

If hardware address filtering is not possible, additional downstream processing steps in TSP’s platform will be required to correlate and connect sensor data with the relevant vehicle.