MQTT System Requests

The Servitly Thing Connector (STC) provides a way to get or update metadata (e.g., Thing, Customer) by using the opened MQTT channel. A predefined set of MQTT messages allows your products to make system requests in order to:

Get the product's local time.
Get the location where the product is installed.
Get the customer to whom the product belongs.
Get the partner who provides the product or service.
Update a recipe.
Update the Connection Status

MQTT clients (products, machines) can exchange these special messages along the following MQTT topics:

<BASE_TOPIC>/_systemRequest: The topic where to publish requests.
<BASE_TOPIC>/_systemResponse: The topic to listen to for the responses.

Note that, the MQTT is a pub/sub protocol, so messages are processed asynchronously.

The BASE_TOPIC is structured as follows:

// without thing mapping path
<USERNAME>/<ASSET_ID>

// with thing mapping path
<USERNAME>/<ASSET_ID>/<THING_PATH>

Get Thing Local Time

Gets the local date/time for the thing, taking into account the time zone of the location where the thing is installed.

Topic: <BASE_TOPIC>/_systemRequest

{
	"action": "read",
	"data": {
		"property": "thingDate",
		"format": "yyyyMMddHHmm"
	}
}

The cloud will respond with the following message.

Topic: <BASE_TOPIC>/_systemResponse

{
	"action": "write",
	"data": {
		"property": "thingDate",
		"value": "201702121940"
	}
}

If the request does not contain the desired format, the response value will be in milliseconds.
If the location does not define the time zone, the response will be UTC.
For more details about how to specify the date format (e.g. yyyy-MM-dd HH:mm), refer to this article.

Get Thing Details

Gets the details of the thing registered within the cloud.

Topic: <BASE_TOPIC>/_systemRequest

{
	"action": "read",
	"data": {
		"property": "thingDetails"
	}
}

The cloud will respond with the thing details.

Topic: <BASE_TOPIC>/_systemResponse

{
	"action": "write",
	"data": {
		"property": "thingDetails",
		"value": {
			"id": "123456789",
			"name": "Oven-123",
			"serialNumber": "123124234",
			"gpsPosition": "42.56789,23.45645",
			"properties": {
				"foo": "bar",
                "abc": 123,
                "yxz": true 
			},
			"timeZone": {
				"offset": 3600000,
				"dstStartDay": 89,
				"dstEndDay": 299,
				"posix": "CET-1CEST,M3.5.0,M10.5.0/3"
			}
		}
	}
}

Get Location Details

Gets the details of the location where the thing is installed.

Topic: <BASE_TOPIC>/_systemRequest

{
	"action": "read",
	"data": {
		"property": "locationDetails"
	}
}

The cloud will respond with the location details.

Topic: <BASE_TOPIC>/_systemResponse

{
	"action": "write",
	"data": {
		"property": "locationDetails",
		"value": {
			"name": "Sweet Milan",
			"gpsPosition": "42.56789,23.45645",
			"properties": {
				"address": "via Cairoli 12",
				"city": "Milan",
                "foo": "bar",
                "abc": 123,
                "yxz": true 
			},
			"timeZone": {
				"offset": 3600000,
				"dstStartDay": 89,
				"dstEndDay": 299,
				"posix": "CET-1CEST,M3.5.0,M10.5.0/3"
			}
		}
	}
}

Get Customer Details

Gets the details of the customer who owns the thing.

Topic: <BASE_TOPIC>/_systemRequest

{
	"action": "read",
	"data": {
		"property": "customerDetails"
	}
}

The cloud will respond with the customer details.

Topic: <BASE_TOPIC>/_systemResponse

{
	"action": "write",
	"data": {
		"property": "customerDetails",
		"value": {
			"name": "Sweet Bakery",
			"code": "C56066896",
			"properties": {
				"foo": "bar",
                "abc": 123,
                "yxz": true 
			}
		}
	}
}

Get Partner Details

Gets the partner providing services to the location where the thing is installed.

Topic: <BASE_TOPIC>/_systemRequest

{
	"action": "read",
	"data": {
		"property": "partnerDetails"
	}
}

The cloud will respond with the partner details.

Topic: <BASE_TOPIC>/_systemResponse

{
	"action": "write",
	"data": {
		"property": "partnerDetails",
		"value": {
			"name": "Ovens Maintenance",
			"code": "P24384",
			"properties": {
				"phoneNumber": "+39 02 25689711",
                "foo": "bar",
                "abc": 123,
                "yxz": true 
			}
		}
	}
}

Recipe Update

In case you are managing recipes, you can trigger the recipe update from the connected product.

Topic: <BASE_TOPIC>/_systemRequest

{
	"action": "saveRecipe",
	"data": {
		"recipeName": "Package-1",
		"recipeDescription": "The recipe description",
		"sharedRecipe": false,
		"parameters": {
			"temperatura": 22,
			"spessore": 30,
			"metriDaAvvolgere": 1
		}
	}
}

The DPS backend searches for a recipe with the given name and, if it is missing, creates a new one.
The recipe is updated with the given description and sharing flag (if true, the recipe is saved at the customer level).
The node named parameters contains the set of parameter names and values to be saved in the recipe. Values are encoded by using the JSON standard encoding.

Connection Status Update

You can force the Connection Status of the thing by providing a status code and the start and end timestamps.

Topic: <BASE_TOPIC>/_systemRequest
{
  "action":"updateConnectionStatus",
  "data": {
    "startTimestamp": 123456789,
    "endTimestamp": 123456789,
    "status": 1
  }
}

When the DPS backend receives the given system requests, the following tasks are performed:

Given the period (start/end timestamps), the last connection status value is retrieved.
Given the period (start/end timestamps), all the saved connection status values are deleted.
The provided status (e.g., 1) is saved to the start timestamp.
The last retrieved value (step 1) is stored in endTimestamp if it differs from the provided one (step 3); if it is null, 0 (OFFLINE) is stored instead.

Note that any insight or event based on the Connection Status metric is NOT recomputed in case the provided period is in the past.

Documentation Index