The Device Configuration Integration enables automatic onboarding and offboarding of TraX devices within the TSP platform.
This integration provides configuration data required to maintain synchronization between the SKF platform and the TSP system, including:
- Fleet identification
- Vehicle identification
- Device identification (MAC address)
- Device position on the vehicle
Identifying devices
The hardware address (MAC address) of all TraX devices has the leading six characters ("c4bd6a") in common. The trailing six characters are unique for each device. It´s included in each device data broadcast.
We recommend using the hardware address to identify devices, 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 devices using their hardware address.
Device configuration attributes to manage
Support for several device attributes can make it easier to manage TraX devices in the TSP platform. We recommend to manage these device attributes:
- Device identity (MAC address)
- Device mounting position (axle number & wheel end side)
- Vehicle the device is mounted on
- The fleet the vehicle is part of
Notifications when a device Is commissioned or decommissioned
An event is generated when a device 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 devices commissioned on a vehicle, refer to the section “Alternative approach for retrieving device configuration for an entire vehicle.”
Consuming events
The TSP can consume these events using the TraX web or Queue API. Information in the event enables the TSP to onboard or offboard the device to its platform.
Retrieving events from a queue (recommended):
Events from queue are fetched one by one.
// Fetch a single event using queue API
// Example 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 events from a queue.
Queueing protocols are connection-oriented and often provide more reliable data transport.
Retrieving events via the web API
It´s also possible to retrieve events using the TraX web API. A difference compared to feting events from a queue is that when fetching events using the web API, a single request includes all available events.
GET /vehicles/sensor-configurations/events
// Example 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 configured devices for an entire vehicle
Another option is to use events as a trigger to execute a second request that fetches all the configured devices on a vehicle.
Step 1: A TraX mobile app user commissions a device.
Step 2: Fetch the resulting event using the queue API (serving as a trigger).
Step 3: Use properties fleetId and vehicleId in the event payload to build the request URL for retrieving all configured device on the vehicle.
// fleetId = a14d379e
// vehicleId = 740f410b
GET /fleets/a14d379e/vehicles/740f410b/sensor-configurations
// Example 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 devices in the response with devices in the TSP platform to determine if a device 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 for specific devices
Once the TSP has obtained information about newly commissioned or decommissioned devices, the next step is to instruct the gateway on the vehicle:
- If a device has been commissioned, instruct the gateway to start listening for broadcasts from the newly added devices.
- If a device has been decommissioned, instruct the gateway to stop listening for broadcasts from that device.
Recommended: The gateway should filter device broadcasts by hardware (MAC) address to ensure that data from nearby vehicles is not inadvertently captured.
If hardware address (MAC) filtering is not feasible, additional downstream processing within the TSP platform will be required to accurately correlate device data with the appropriate vehicle.