Networked Things - Multiple Device Shadows

Networked things is a concept providing a way to layout your fleet of things. Since MIC only can handle 8kb in the device shadow, you might encounter situations where you need more than that, e.g. in a scenario where your thing reports for a multitude of sensors with their own independent sensor data. Networked things with multiple device shadows will help you separate your thing in to several smaller things, each with their own device shadow up to 8kb. This will help you manage large amounts of data and also get the data separation that you need.

How it works

Normally a thing will report to the topic $aws/things/<thingName>/shadow/* for interactions with the device shadow. The networked things with multiple device shadows has a namespace where you can, in your device configuration code, specify a number of networked things that should be reported as well.

Publishing networked thing data

When you want to publish data from a networked thing, the data should be published on the $aws/things/<thingName>__<networkedThingName>/shadow/* topic. MIC will then create a new thing, based on the <thingName>, and you can manage that thing separately from its parent. Please note that you can also use the Thing API to create networked things in order to prepare your thing with networked things before the thing has started publishing data.

By default, this new networked thing will be created on the same thing type as the parent that is reporting it. If you want to specify a thing type on where to create these dynamic networked things, you can specify tcxn: {thingType: <thingTypeId>} in the payload of the publish request. MIC will then take the thingTypeId and try to create the new networked thing there. If any error occurs during the creation, an event with type THING.CREATE and level WARNING will be sent and be visible in the event/# topic namespace based on the parent thing domain. In either the event topic or the event lambda you can read information about a networked thing that couldn’t be created dynamically.

Creating networked things through the API

It is possible to use the Thing Management API to create networked things as well. To create a networked thing you specify the attribute parentThingName to a thing you have access to and a thingName for your networked thing and it will be ready to get data from your remote thing.

Subscribing to changes

Since these networked things are treated as regular things in MIC, subscribing to changes to i.e. the delta is as simple as subscribing to $aws/things/<thingName>__<networkedThingName>/shadow/update/delta. Please note that you must use the certificate of <thingName> (the parent) in order to receive changes on nested things. This is due to the fact that the parent is meant to be a gateway for its networked things that doesn’t have a certificate directly attached to them.

You can use the thing-update/<domainPath>/<thingName>__<networkedThingName> topic to publish and subscribe to the networked thing and MIC will handle the communication as it does with regular things.

Usage Patterns

There are several usage patterns but the foremost is to be able to extend your total device shadow size by splitting your device into several networked things. Comparing to the nested structure that we currently also support, this would mean that a payload as the following:

{
  "state": {
    "reported": {
      "tcxn": {
        "rssi": "12",
        "imsi": "123456789",
        "imei": "12415151511",
        "...": "..."
      },
      "gatewayResource": "15",
      "...": "...",
      "sensor1": {
        "type": "sensor",
        "resource1": "1",
        "resource2": "15",
        "...": "..."
      },
      "sensor2": {
        "type": "sensor",
        "resource1": "1",
        "resource2": "15",
        "...": "..."
      },
      "sensor3": {
        "type": "sensor",
        "resource1": "1",
        "resource2": "15",
        "...": "..."
      },
      "sensor4": {
        "type": "sensor",
        "resource1": "1",
        "resource2": "15",
        "...": "..."
      }
    }
  }
}

would be split into 1 gateway thing and 4 networked things, such as:

Topic: $aws/things/<thingName>/shadow/update

{
  "state": {
    "reported": {
      "tcxn": {
        "rssi": "12",
        "imsi": "123456789",
        "imei": "12415151511",
        "...": "..."
      },
      "gatewayResource": "15",
      "...": "..."
    }
  }
}

Topic: $aws/things/<thingName>__sensor1/shadow/update

{
  "state": {
    "reported": {
      "resource1": "1",
      "resource2": "15",
      "...": "..."
    }
  }
}

Topic: $aws/things/<thingName>__sensor2/shadow/update

{
  "state": {
    "reported": {
      "resource1": "1",
      "resource2": "15",
      "...": "..."
    }
  }
}

Topic: $aws/things/<thingName>__sensor3/shadow/update

{
  "state": {
    "reported": {
      "resource1": "1",
      "resource2": "15",
      "...": "..."
    }
  }
}

Topic: $aws/things/<thingName>__sensor4/shadow/update

{
  "state": {
    "reported": {
      "resource1": "1",
      "resource2": "15",
      "...": "..."
    }
  }
}

There are several other scenarios like this but in general, this is what you want to use when you are running short on space in the device shadow and need to separate your device into several to reduce the possibility of breaking the device shadow size. If your device can fit all data in one thing, then please continue doing that as this feature does increase the amount of data sent (due to overhead in JSON structures and TLS).