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 allow your products to make system requests in order to:

• Get the product 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

These kinds of messages are exchanged along the _systemRequest and _systemResponse topic paths.
MQTT clients (products) must make these requests to the _systemRequest topic path, and must listen for responses on the _systemResponse topic path.

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

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: <USERNAME>/<ASSET_ID>/_systemRequest

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

The cloud will respond with the following message.

Topic: <USERNAME>/<ASSET_ID>/_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: <USERNAME>/<ASSET_ID>/_systemRequest

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

The cloud will respond with the thing details.

Topic: <USERNAME>/<ASSET_ID>/_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: <USERNAME>/<ASSET_ID>/_systemRequest

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

The cloud will respond with the location details.

Topic: <USERNAME>/<ASSET_ID>/_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: <USERNAME>/<ASSET_ID>/_systemRequest

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

The cloud will respond with the customer details.

Topic: <USERNAME>/<ASSET_ID>/_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: <USERNAME>/<ASSET_ID>/_systemRequest

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

The cloud will respond with the partner details.

Topic: <USERNAME>/<ASSET_ID>/_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: <USERNAME>/<ASSET_ID>/_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, the start and end timestamps.

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

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

1. Given the period (start/end timestamps), the last connection status value is retrieved.

2. Given the period (start/end timestamps), all the saved connection status values are deleted.

3. The provided status (e.g., 1) is saved to the start timestamp.

4. 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 are note recomputed in case the provided period is in the past.