Eclipse Kanto - AWS Connector
The AWS Connector is the main coordination center which forwards the local
and remote messages. Messages processed by the AWS Connector will
typically be related to telemetry data from the devices or command &
control from the cloud. Messages sent to the Twin Channel
are processed and redirected to the Device Shadow service.
Additionally, the connector is responsible for announcing the provisioning
thing information to the local MQTT broker subscribers.
For most of the connectivity options (e.g. certificates, alpn, tpm),
AWS Connector is using the Suite Connector
as a library.
Table of Contents
- Transform Ditto message to Shadow message
- Exclude message by Ditto topic
- Exclude parts of the message payload
- Example Ditto message sent to root thing
- Example Ditto message sent to child thing
Messages sent to the Twin Channel will be processed as follows:
-
Check the message against the topic exclusion filter. See exclude message by Ditto topic.
-
Check the message payload paths against the payload exclusion filters. See exclude parts of the message payload
-
Check if the message contains some attributes. Attributes of the root thing will be sent with topic:
$aws/things/root-thing-name/shadow/update
While attributes of child things will be sent with topic:
$aws/things/root-thing-name/shadow/name/child-thing-name/update
-
Check if the message contains some features. Features of the root thing will be sent with topic:
$aws/things/root-thing-name/shadow/name/feature-name/update
While attributes of child things will be sent with topic:
$aws/things/root-thing-name/shadow/name/child-thing-name:feature-name/update
The transformation may result in multiple smaller messages sent to the
Device Shadow
service. See the examples Root Thing
and Child Thing below for more details.
Exclude message by Ditto topic
Filtering unnecessary messages can save a lot of cloud traffic/cost. AWS Connector
can exclude messages by their Ditto Topic.
To do so, provide a regex filter via topicFilter command line parameter or its
corresponding JSON configuration.
The following example will exclude all of the messages, for which their topic
starts with test/device:edge:containers/
-topicFilter "^test/device:edge:containers/.*"
Exclude parts of the message payload
Filtering unnecessary parts of a message can improve the cost savings and
reduce the traffic load. The payloadFilters command line parameter or
its corresponding JSON configuration can be used to remove the
unnecessary parts of it. Multiple payload filters can be provided.
The message payload is in JSON format and each complete JSON path
will be tested against all payload filters. If there is a match, the particular
part of the message will be removed.
An example Ditto message
{
...
"value":{
"code":[
{"value":"test"},
{"keep":201},
{"unwanted":500}
],
"status":200,
"unwanted":1234
}
}
Applying following payload filters
-payloadFilters "./unwanted$" -payloadFilters "./0/value$"
Will trim the message payload to
{
...
"value":{
"code":[
{"keep":201}
],
"status":200
}
}
Example Ditto message sent to root thing
{
"topic":"ex/root/things/twin/commands/modify",
"headers":{"response-required":false},
"path":"/attributes/test",
"value":{
"attributes": {
"location": {
"latitude": 44.673856,
"longitude": 8.261719
}
},
"features": {
"accelerometer": {
"properties": {
"x": 3.141,
"y": 2.718,
"z": 1,
"unit": "g"
}
}
}
}
}
The root thing name is ex:root and following messages will be send
to Device Shadow service:
- Topic $aws/things/ex:root/shadow/update with value
{
"state": {
"reported": {
"location": {
"latitude": 44.673856,
"longitude": 8.261719
}
}
}
}
- Topic $aws/things/ex:root/shadow/name/accelerometer/update with value
{
"state": {
"reported": {
"x": 3.141,
"y": 2.718,
"z": 1,
"unit": "g"
}
}
}
Example Ditto message sent to child thing
{
"topic":"ex/root:child/things/twin/commands/modify",
"headers":{"response-required":false},
"path":"/attributes/test",
"value":{
"attributes": {
"location": {
"latitude": 44.673856,
"longitude": 8.261719
}
},
"features": {
"accelerometer": {
"properties": {
"x": 3.141,
"y": 2.718,
"z": 1,
"unit": "g"
}
}
}
}
}
The root thing name is ex:root, its child thing name is child and following
messages will be send to Device Shadow service:
- Topic $aws/things/ex:root/shadow/name/child/update with value
{
"state": {
"reported": {
"location": {
"latitude": 44.673856,
"longitude": 8.261719
}
}
}
}
- Topic $aws/things/ex:root/shadow/name/child:accelerometer/update with value
{
"state": {
"reported": {
"x": 3.141,
"y": 2.718,
"z": 1,
"unit": "g"
}
}
}