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 which the product belongs;

• get the partner who provides product service;

• update a recipe.

These kinds of messages are exchanged along the _systemRequest and _systemResponse topic paths.

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

MQTT clients (products) must make these request to the _systemRequest topic path, and must listen for responses on the _systemResponse topic path.

Get Thing Local Time

Gets the local date of the thing considering 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"
			},
			"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 on.

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"
			},
			"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 where the thing is installed on.

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": {
				"vatNumber": "1231861318168"
			}
		}
	}
}

Get Partner Details

Gets the partner associated with the location where the thing is installed on.

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"
			}
		}
	}
}

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 Servitly 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 parameters node contains the set of parameter names and values to be saved in the recipe. Values are encoded by using the JSON standard encoding.