Help

System architecture

The system is composed of

• a cloud infrastructure that acquires and stores the telemetry
• a web application to
  • visualize and export telemetry data
  • manage devices, sensors and channels
• a programming interface (API) to manage devices, sensors and channels (for complex scenarios)
• a component that sends notifications by email when a telemetry datum exceeds a configured threshold

The set of devices is grouped in a federation.
Each device has one or more sensors.
Each sensor has one or more data channels.
Sensors can have a special purpose (e.g. latitude and longitude channels used to define the device location).
Each federation can have one or more views to display the telemetry data and can be accessed by one or more users.
Devices, sensors and channels can be managed through the web application or through the API.
Older telemetry can be aggregated hourly to decrease the subscription cost. Each hourly aggregated datum contains the number, the sum and the average of the original values.

Federations

A federation is a set of related devices.
It is the main entity of the system and it has associated subscriptions, users and views. A federation has a token used to call the provided programming interface (API) (see Management API).
The web application shows the list of federations you have access to.
By selecting a federation, you have access to the related devices, users and views.
You can create a federation by activating a new subscription.
You can also join an existing federation if invited by another user.

Structure

The structure section shows devices, sensors and channels of the selected federation in three columns in a hierarchical layout.
The checkmarks are used to select the channels to show on the view. If you change the selected channels, click the button Update to reflect the changes on the view.
By clicking on an item name, you can select the sub-items contained in it.
By selecting the cog icon, you can edit an item.

Subscriptions

The web application shows the list of your subscriptions and allows you to create new subscriptions.
A valid subscription is needed to create a federation.
A subscription defines

• the contractual duration
• the period of time the telemetry is stored, detailed and hourly aggregated
• the maximum amount of telemetry data per hour
• the maximum number of users of the web application

The subscription lasts for a whole number of months, where a month is always considered to be 31 days long.
A subscription can be renewed at the expiration.
Subscription parameters can be extended during its period of validity or when renewed.
A calculator helps to count the amount of telemetry data that will be sent by federation devices.

Users

Users can be associated to any number of federations. Users can have the following permissions set by the administrator of the federation

• Administrator: user has full control
• Modify: user can modify the federation devices
• Download: user can download telemetry data

Users can join a federation if invited by an administrator of the federation.
Invitations are sent by email and can be accepted by clicking on a link inside the email.

Data visualization

Data are shown on customizable views.
Type of a view can be

• Static chart
• Real-time chart
• Map
• User-provided map/plan/image

By a selection interface with columns for devices, sensors and channels, you can choose the channels to show on a view.
Charts of a view can be grouped per device, per sensor or per measurement unit. Each chart shows a group.
Maps, plans and images show an info box per device to show its data and to open the related chart.
Charts may use hourly aggregated data when a single data point contains one or more hours of data.

Data export

Static charts can be exported as

• chart image
• HTML data file
• comma-separated values (CSV) file

Methods

GetFederation

Returns a federation with its devices, sensors and channels.
This method cannot be called by a device.

Request

Request is empty. The federation id is inferred from the authentication token.

Response

CreateFederationToken

Returns the federation token.
This method cannot be called by a device.

Request

Response

AddDevices

Adds devices to a federation.

Request

Response

GetDevice

Returns a device.

Request

Response

ModifyDevice

Modifies a device.

Request

Response

DeleteDevice

Deletes a device.

Request

Response

CreateDeviceToken

Returns the device token.

Request

Response

AddSensors

Adds sensors to a device.

Request

Response

ModifySensor

Modifies a sensor.

Request

Response

DeleteSensor

Deletes a sensor.

Request

Response

AddChannels

Adds channels to a sensor.

Request

Note: If both the threshold values are used, they must define a range of normality (e.g. the threshold condition "< 0 or > 10" defines a normality range from 0 to 10).

Response

ModifyChannel

Modifies a channel.

Request

Response

DeleteChannel

Deletes a channel.

Request

Response

Error codes

List of the error codes that can be returned by the API service.
Each error code has a corresponding HTTP status code returned.

Requirements

• send data over a HTTPS connection;
• store the data destination uri and the authorization string (or get them from federation gateway, but this is not covered by the system)

Data sending

Devices send data (usually called "telemetry") by a HTTPS communication using the POST method.
Devices must send an authorization string in the packet header. The authorization string and the destination uri can be found in the device editor form of the web application or they can be retrieved by all the programming interface (API) methods that return a device in the response.
A data packet has the following format (replace text within the brackets):

POST <destination uri>
Authorization: <authorization string>
Content-Type: application/json;charset=utf-8
Content-Length: <JSON payload length>

<JSON payload>

JSON payload is an object in JSON format with the following structure:

{
"t":<timestamp>,
"c":
[
{
"i":<channel communication id>,
"v":<value>
}
... (max. 100 array items)
]
}

Every timestamp will be stored as sent, without any assumption about timezone or daylight saving time. Timestamp is optional. If omitted, the current time in UTC (i.e. without a time zone offset) is used.
Timestamp of devices in a federation should refer to a common time zone and daylight saving time. If some devices of the federation don't send the measurements' time, we recommend using the UTC time for the devices that send the timestamp.
If the devices in a federation are not in the same time zone and daylight saving time, again, we recommend using the UTC time.
Instead, if all the devices are in the same time zone and daylight saving time, you can use the UTC time or the local time zone.
The federation time zone can be set in the federation properties of the web application. This allows any user to correctly display timestamps in his own preferred time zone.
Timestamps should not be older than the effective upload date/time for more than 48 hours otherwise the related values could be missing in hourly aggregated data.
Timestamps are expressed as the number of milliseconds since January 1, 1970, 00:00:00 UTC.
A value is a 64-bit number ranging approximately from ±5.0 × 10³²⁴ to ±1.7 × 10³⁰⁸ with 15-16 digits of precision, conforming to IEEE Standard for Floating-Point Arithmetic (IEEE 754).
For data aggregation purposes, it is required that the sum of all or part of the values sent in the same hour for each channel falls within the range of a 64-bit number as defined above.
The channel communication id can be found in the channel editor form of the web application or it can be retrieved by all the API methods that return a channel in the response.
Your subscription defines the maximum amount of data that can be sent per hour. If this limit is exceeded, acquisition of data from federation devices can be temporary suspended (i.e. all data sent will be temporary discarded) without any notice. Severe or repeated breaches could lead to the termination of the agreement.

Test tools

Free test tools are provided to ease the sending of telemetry data.

Test device for Android

You can use the Android app Sensorbis Test Device to simulate a device.
Follow the help contained in the application to send telemetry data.
You can download it from the Google Play Store.

Google Play and the Google Play logo are trademarks of Google LLC.