The TraX mobile app is used to commission/decommission sensors in SKF's platform. The "sensor configuration integration" enables TSP's mirror these activities in their platform.
🚩 IoT platform integration objectives
- Identifying sensors
- Sensor configuration attributes to manage
- Storing sensor data
🚩 Application integration objectives
- Propagate sensor configuration changes from SKF to the TSP platform, i.e. adding or removing the sensor to the TSP platform
🚩 Device integration objectives
- Instruct gateway to start/stop listening to specific sensors (MAC address filtering)
We recommend that you review the TraX Partner API reference to learn about the behavior of the API (endpoints, payloads, and much more). The API reference can be viewed online, or downloaded for viewing in your preferred OpenAPI renderer.
Identifying sensors
Depending on the TSP's platform capabilities, the platform may have to be extended to support (1) sensor identification, (2) managing sensor attributes, and (3) storing sensor data.
RECOMMENDED: Identify the sensor using the sensor's hardware address
We recommend that the sensor is identified using its hardware address. All sensors have the same first 6 characters (
004424
) in the hardware address. The trailing 6 characters are unique and they are sent in the `End of MAC address portion of the sensor's payload.
It's also possible to identify a sensor using a combination of vehicle ID and sensor position (i.e. axle number & left/right wheel end). Note that the sensor's hardware address will still be required for sharing sensor data with SKF.
See WEM200/US technical specification for more information about where End of MAC address
, Position
and Axle
are located in the sensor's payload.
Sensor configuration attributes to manage
RECOMMENDED: Implement support for sensor configuration attributes
For managing sensors, we believe it's good practice to support these sensor configuration attributes in the TSP's platform:
- Sensor identity (MAC address)
- Sensor mounting position (axle & wheel end)
- Vehicle the sensor is mounted on
- The fleet the vehicle is part of
Storing sensor data
Sensor data is captured by the gateway and transferred to the TSP's platform. In the platform, the sensor data usually needs to be persisted awaiting additional processing.
RECOMMENDED: Store sensor data as it was sent from the sensor
We recommend that the entire sensor data payload is captured and stored in TSP's platform as it was sent from the sensor (i.e. the complete hex encoded string) to make it easier to meet the sensor data sharing requirement (more about it in the sensor data integration).
The TSP may in addition decide to parse parts of the sensor data for ease of access in the TSPs platform.
Propagate sensor configuration changes in the TSP's platform
How TSPs become aware of sensor configuration changes
When a sensor is commissioned or decommissioned using the TraX mobile app, an sensor configuration outdated
event is generated. The event serves as a trigger for the TSP to either commission- or decommission a sensor in their platform.
It can take up to 2 minutes from the moment a sensor was commissioned/decommissioned in the TraX mobile app, for the related Sensor configuration changed event
to become available.
Sensor configuration changes can be retrieved using a queue- or web API endpoint
Sensor configuration changed events can be retrieved in two ways: either from a queue or via the TraX web API.
When retrieving events from a queue, each message will contain a single event, whereas when events are retrieved using the web API endpoint, all the events in the queue will be retrieved in a list.
Note that a TSP can only consume the same sensor configuration event(s) once. Please see the heading Alternative approach for retrieving sensor configuration for an entire vehicle
if there is a need to repeatedly query currently configured sensors on a vehicle.
RECOMMENDED: Sensor configuration changed events should be retrieved from a queue
We generally recommend that
Sensor configuration changed events
are retrieved from a queue because queueing protocols are connection-oriented and often provide a more reliable data transport.
The sensor configuration changed
event can be retrieved either directly from a queue or via a web API endpoint:
- Queue endpoint:
trax.{name of TSP}.sensor-configuration
- Web API endpoint:
GET /vehicles/sensor-configurations/events
{
// Payload example for a "sensor configuration changed" event
"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"
}
}
]
}
RECOMMENDED: Assume the queue can contain different events types
Currently, it's only "sensor configuration changed" events in the queue, however, in the future other event types may be sent to the queue. Hence, as a developer of the TSP's API client, do not assume the queue only will contain "sensor configuration changed events". A practical implication of this assumption is that when you fetch a message from a queue, the event's expected payload structure (schema) needs first to be determined by using the eventId. Only when the event type has been determined, the API client can know how to safely parse the complete payload structure.
An alternative approach for retrieving sensor configuration for an entire vehicle
The Sensor configuration changed event
contains all the information required for commissioning/decommissioning the sensor to the TSP's platform. As an alternative, some TSPs prefer to retrieve all sensor configurations for an entire vehicle.
API request example for retrieving all the currently commissioned sensors on a vehicle:
Request: GET /fleets/{fleetId}/vehicles/{vehicleId}/sensor-configurations
// Response payload example
{
"sensors": {
"expected": 6,
"commissioned": 6,
"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"
},
...
The fleetId
and vehicleId
attributes required to construct the request path/URL are obtained in the sensor configuration outdated event
.
When using this approach, the TPS may have to compare the sensor configuration retrieved from SKF with the reported sensor configuration from the TSP's device configuration repository in their platform to determine if a sensor has been commissioned or decommissioned. Once the "delta" has been identified, then update the TSP's device configuration repository to ensure it holds the current configuration state.
Instruct gateway to start/stop listening to specific sensors (MAC address filtering)
Now 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, then the gateway needs to be instructed to start listening for sensor broadcasts from the newly added sensor. And vice versa if the sensor has been decommissioned.
Comments
0 comments
Article is closed for comments.