Introduction
The Sensor module external API history and last value endpoints are available as soon as a new integration is created from the SCALAR UI including the sensor module.
The Feed endpoint is a little special because it has been designed and optimized specifically for a M2M (Machine To Machine) integration.
This section provides detailed information on how to start to use the FEED endpoint effectively.
Getting started with FEED endpoint
The feed endpoint is highly optimized: we introduced the concept of subscription where the integration can describe what are the sensors, assets and communication units they are interested. After describing the subscription like this, and create accordingly, the sensor module API will be able to retrieve those information and optimize the communication.
For example, the history endpoints, on each call, requires to provide the list of sensors the integration is interested on. In addition, the endpoint has some rate limits which discourage its usage for a large interval. The idea is that the history endpoint should be used by the integrators only in special case when for some reason some of the sensor values has been missed for a given period in the past.
For normal M2M integration, we strongly recommend to use the FEED endpoint. But before to start, let's explain how it works.
Let's go a little more in details by describing the steps to do to create a subscription and use the feed endpoint.
List all available sensors
When creating a subscription, we need to specify the list of sensors we are interested. The integrator can retrieve the list of available sensors by calling the following endpoint
GET /v1/sensors/action/list
Check the following link for details on how to use this endpoint (request/response):https://developers.zf-scalar.com/reference/get_v1-sensors-action-list-1. In short, the endpoint returns the whole list of available sensors and, for each of them, provides the id and data type.
Using the above information, the integrator can provide the list of sensors he is interested in.
Data type can be used to implement the code to decode sensor data. Details on the available data types are available here: SEM - Available Sensors
Now we are ready to create the subscription.
Create subscription
Use the following endpoint to create a new subscription
POST /v1/subscriptions
Check the following link for details on how to use this endpoint (request/response): https://developers.zf-scalar.com/reference/post_v1-subscriptions-1. A JSON object is required as body of the POST call. Below is a simple example
{
"sensorIds": [
"mileage", "reeferLoggerTemperature"
],
"assetIds": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"unitIds": [ ]
}
The example shows the body of a subscription we want to create to retrieve sensor data for sensor mileage and reeferLoggerTemperature but only for the asset "3fa85f64-5717-4562-b3fc-2c963f66afa6". No filter specified for communication units.
The following example is creating a subscription to pull data for sensors "gnssSpeed", "tirePressure", and "position". No further condition expressed on asset and communication units which means that the integrator will be able to poll the sensor value listed in the sensorIds property for all the asset/devices belonging to the integrator's organization.
{
"sensorIds": [
"gnssSpeed", "tirePressure" and "position"
],
"assetIds": \[],
"unitIds": \[]
}
The only mandatory information is the sensorIds. As described above, if no filter is required on assets and communication units, we can leave the two filters above empty, otherwise we can list the assets/units we want to limit the subscription.
After a subscription is created, SCALAR starts to automatically collect feed data for that subscription and the feed endpoint can be called with success.
Time To Live (TTL)
As stated above, this is an optimized way to exchange data. Data points are collected in a specific database only for a limited duration (TTL = 1 day). This is more than enough for a M2M integration. But, in case, for some reason, the integrator fails to receive some data, it can always use the history endpoint to retrieve the missing data.
In order to achieve this optimization, we use special data store which, both for cost and performance reason, doesn’t allow to store huge quantity of data. For this reason, we keep the data for 1 day and then data points will be automatically removed
Call feed endpoint
Now we are ready to call the feed endpoint https://developers.zf-scalar.com/reference/get_v1-sensors-feed-1
GET /v1/sensors/feed
The feed call doesn’t require any parameter.
The first time we call it, the sensor module external API returns all the data point collected since the subscription has been created or since last 24 hours if the feed has not been called in the last 24 hours and the subscription has been created previously. In formula, feed returns data points received in the following interval:
_start datetime: MIN(lastCall, datetime.now - 24 hours) end datetime: datetime.now of the call_
Here are some examples:
Suppose the subscription is created at 21 September 2022 at 8:00 am. The sensor module starts to collect data for this subscription since the created data, that is, all the data points we receive from the devices related to the organization, sensors list, assets and units specified in the subscription with “TriggeredOn” >= “2022-09-21T08:00:00Z”
if we call the feed endpoint say, at 21 September 2022, 12:00 am, we will get all data points in the time interval between “2022-09-21T08:00:00Z” and “2022-09-21T012:00:00Z”.
Now, suppose we call again the feed endpoint at 5:10pm, with this second call we will get all the data point received in the interval between the previous call and now, that is, we will get all data points in the time interval between “2022-09-21T12:00:00Z” and “2022-09-21T017:10:00Z”.
Please, note that, as stated above, data is stored for 24 hours. If, after the second call, we call again the feed the day after at 20:00pm, we will get the data point from MIN(lastCall, datetim.now - 24 hours). In this case, the interval will be:
start datetime: “2022-09-21T020:00:00Z”
end datetime : “2022-09-22T020:00:00Z”
The reason for this is because more than 24 hours have passed since the last call so the data relating to the interval “2022-09-21T017:10:00Z” and “2022-09-21T020:00:00Z” has already been deleted.
If you want to retrieve such data, you can use the history endpoint.
Reset Feed
By its nature, the feed endpoint keeps going forward in time as the next call uses the datetime of the previous call as the upper bound to pull data from the database. In some cases it is possible that you want to go back in time. For example, while developing integration software, you want to retrieve already downloaded data again. To do this, the PATCH endpoint has been exposed which allows you to manually assign the upper bound of the next feed call https://developers.zf-scalar.com/reference/patch_v1-sensors-feed-subscriptionid-1.
PATCH /v1/sensors/feed/{subscriptionId}
As a body, the only thing you can specify is the datetime as in the example below where we force the upper bound limit to 10:30am
{
"triggeredOn": "2022-09-21T10:30:00.0000000Z"
}
Suspend/Resume
To reduce cost, and in case for some period the feed end point is not used, we suggest to “suspend” the subscription. To do it is very simple and just call the following endpoint https://developers.zf-scalar.com/reference/patch_v1-subscriptions-id-1 specifying the status as in the example below:
PATCH /v1/subscriptions/{id}
{
"status" : "suspend"
}
Using the PATCH endpoint with the body above allows to suspend a subscription. The subscription can be resumed using the same endpoint but this time specifying “resumed” as status value in the body.
A subscription can be automatically suspended by SCALAR in case of prolonged inactivity