Trigger actions from the Thing and TR50 categories result in TR50 commands that are sent to the deviceWISE Cloud. When the TR50 Command Aggregator is enabled, the TR50 commands are queued for a time interval before sending. This allows multiple TR50 commands to be grouped together and sent as one message packet to the deviceWISE Cloud. This grouping reduces messaging overhead.
The TR50 commands are queued and then sent together when the selected Command Aggregator Interval (secs) is met. This time interval is from when the first TR50 command is added to the TR50 Command Aggregator queue. The range for the time interval is from 1 to 300 seconds.
The TR50 Command Aggregator has a message size limit of 20,000 bytes. If the queued TR50 commands result in a grouped message that would be larger than this size limit, then multiple messages are created - each one honoring the size limit.
The TR50 Command Aggregator also supports batching. If the TR50 command for a trigger action has a corresponding batch command, then individual TR50 commands are converted to use a single batch command. For example, the Publish Property action normally is sent to the deviceWISE Cloud using the property.publish TR50 command. If the TR50 Command Aggregator is enabled, then multiple property.publish TR50 commands can be converted to a single property.batch TR50 command.
Thing actions that support Command Aggregation
This table shows the relationship between trigger actions, the TR50 command used to send the information to the deviceWISE Cloud, and (if supported) the corresponding TR50 batch command.
| Trigger Action | TR50 Command | TR50 Batch Command |
|---|---|---|
| Add Thing Tag | thing.tag.add | Unsupported |
| Bind Thing | thing.bind | Unsupported |
| Delete Thing Tag | thing.tag.delete | Unsupported |
| Publish Alarm | alarm.publish | alarm.batch |
| Publish Location | location.publish | location.batch |
| Publish Log | log.publish | Unsupported |
| Publish Property | property.publish | property.batch |
| Set Thing Attr | thing.attr.set | Unsupported |
| Unbind Thing | thing.unbind | Unsupported |
| Unset Thing Attr | thing.attr.unset | Unsupported |
Command Aggregation
The following examples show how trigger actions result in TR50 commands and the message packets that are sent to the deviceWISE Cloud.
Example 1: A Publish Alarm action with the Command Aggregator parameter set to False. The alarm.publish command would be immediately sent to the deviceWISE Cloud.
{
"1": {
"command": "alarm.publish",
"params": {
"key": "thing_1",
"state": 4,
"ts": "2015-12-08T15:08:41Z"
}
}Example 2: A Publish Log action with
the Command Aggregator parameter set to True is executed,
and the TR50 Command Aggregator is enabled on the TR50
Advanced Connection Management tab.
The log.publish command would not be sent immediately, but
instead be added to the TR50 Command Aggregator queue where
it would wait for the Command Aggregator Interval (sec) to
expire.
As other actions that support TR50 Command Aggregation are executed within the Command Aggregator Interval (sec), they will be added to the TR50 Command Aggregator queue.
For this example: a Publish Log action, a Thing Tag Add action, and then a Publish Log action again.
{
"1": {
"command": "log.publish",
"params": {
"msg": "log message",
"ts": "2016-06-22T17:47:08Z"
}
},
"2": {
"command": "thing.tag.add",
"params": {
"tags": [
"tag1",
"tag2"
],
"thingKey": "test"
}
},
"3": {
"command": "log.publish",
"params": {
"msg": "log message again",
"ts": "2016-06-22T17:47:08Z"
}
}
}When the Command Aggregator Interval
(sec) expires, the three commands are grouped and
sent as a single message packet, in the above format, to
the deviceWISE Cloud.
Note that the three trigger actions do not have to be in
the same trigger. The TR50 Command Aggregator and the queue
it uses to hold TR50 commands are for the TR50
connection.
Example 3: Without TR50 Command
Aggregation enabled, the individual commands will be sent
individually at the time the trigger action is executed to
the deviceWISE Cloud.
The deviceWISE Cloud would receive them in the following
format:
1st packet:
{
"1": {
"command": "log.publish",
"params": {
"msg": "log message",
"ts": "2016-06-22T17:47:08Z"
}
}
}2nd packet:
{
"1": {
"command": "thing.tag.add",
"params": {
"tags": [
"tag1",
"tag2"
],
"thingKey": "test"
}
}
}3rd packet:
{
"1": {
"command": "log.publish",
"params": {
"msg": "log message again",
"ts": "2016-06-22T17:47:08Z"
}
}
}Command Aggregator size limit
The TR50 Command Aggregator has a maximum message size limit of 20,000 bytes. If the queued TR50 commands result in a grouped message that would be larger than this size limit, then multiple messages are created - each one honoring the size limit.
Example 4: If the size limit was 400 bytes, then taking Example 3 from above, the Publish Log action followed by the Thing Tag Add action would result in a message packet size of 358 bytes.
When the Publish Log action is executed again, the total message packet size for the three TR50 commands would be 521 bytes, which exceeds the example message size limit of 400 bytes. The TR50 Command Aggregator will end up sending two message packets when the Command Aggregator Interval (sec) expires.
1st packet:
{
"1": {
"command": "log.publish",
"params": {
"msg": "log message",
"ts": "2016-06-22T17:47:08Z"
}
},
"2": {
"command": "thing.tag.add",
"params": {
"tags": [
"tag1",
"tag2"
],
"thingKey": "test"
}
}
}2nd packet:
{
"1": {
"command": "log.publish",
"params": {
"msg": "log message again",
"ts": "2016-06-22T17:47:08Z"
}
}
}Batching
When the TR50 Command Aggregator is enabled, TR50 commands will automatically use their corresponding TR50 batch command. Sending the data as a batched command reduces the messaging overhead further when compared to simple command aggregation.
When a TR50 command is batched, it is automatically grouped in timestamp order and grouped by thing key. When a item key exists, the command will also be grouped based on that key. For example, an item key in the property publish is the property key and the item key in an alarm publish is the alarm key.
Example 5: Multiple Publish Property actions will not be grouped as individual property.publish commands but instead are converted to a single property.batch command. Specifically, the property.batch command will be batched (or grouped) by thing key for the different property keys and values.
{
"1": {
"command": "property.batch",
"params": {
"data": [
{
"corrId": "1",
"key": "key1",
"ts": "2008-03-18T10:00:00Z",
"value": 335.17
},
{
"corrId": "1",
"key": "key2",
"ts": "2008-03-18T10:00:00Z",
"value": 135.17
}
],
"thingKey": "thing"
}
}
}If multiple Publish Propertyactions are executed for the same property key, the property.batch command will be batched (or grouped) by thing key and property key for the different values.
{
"1": {
"command": "property.batch",
"params": {
"data": [
{
"corrId": "1",
"ts": "2008-03-18T10:00:00Z",
"value": 335.17
},
{
"corrId": "1",
"ts": "2008-03-18T10:00:00Z",
"value": 135.17
}
],
"thingKey": "thing"
"key": "key2",
}
}
}TR50 Command Aggregator error handling
Once the TR50 commands are sent to the deviceWISE Cloud, the deviceWISE Cloud will send back a reply for each TR50 command. If the reply returns an error for a command, an Exception Log entry will be written indicating what Project, Trigger, and Action failed, along with the error code and error message for the failure. This failure can also be viewed in the deviceWISE Cloud'sAPI log.
If the message packet contained a batch command, then an Exception Log entry will be written indicating what Project, Trigger, and Action failed, along with the error code and error message for the failure for each TR50 command that was grouped into the batch command. However, the deviceWISE Cloud will report the entire batch command packet as failed, and only process data up to the failure within the batch command packet, causing only a portion of the batched data to be processed. This failure can also be viewed in the deviceWISE Cloud'sAPI log.
Example 6: A property.batch is sent to the deviceWISE Cloud (see below).
{
"1": {
"command": "property.batch",
"params": {
"data": [
{
"corrId": "1",
"ts": "2008-03-18T10:00:00Z",
"value": 335.17,
"key": "processed"
},
{
"corrId": "1",
"ts": "2008-03-18T10:00:00Z",
"value": 135.17,
"key": "invalid.key"
},
{
"corrId": "1",
"ts": "2008-03-18T10:00:00Z",
"value": 135.17,
"key": "failed_to_process"
},
{
"corrId": "1",
"ts": "2008-03-18T10:00:00Z",
"value": 135.17,
"key": "failed_to_process"
}
],
"thingKey": "thing"
}
}
}The entire batch will fail with the error message: "Invalid key format for 'invalid.key': Key must only contain letters, numbers, '_' (underscore), and '-' (hyphen)."
However, the first key will be processed. The second key will cause the failure, and the rest of the batched command will go unprocessed.