Payload Conventions

As a general rule, Managed IoT Cloud doesn’t enforce any special format or structure for the thing state document. There is however, a set of conventions that you can follow to get special visualizations in App Board.

latlng : Resources with this name, at any level (except inside the tcxn namespace), will be treated as a GPS location and are used to show the thing on a map in App Board. It is preferred to place latlng at the top level, otherwise it won’t show up in the specific thing type map showing all things of one type. The format is "lat,lng" (e.g. "57.652,11.958").
tcxn : All other resources with special meaning are placed inside the tcxn namespace and since new resources may be added in the future you should avoid adding custom resources to this namespace.
- battery_level : The battery level in percent (0-100).
- connection_status : The status of the connection.
  
  0 = Offline
  1 = Connected to Managed IoT Cloud only
  2 = Fully connected (normal operation)
- fw_ver : The firmware version (“1.2.1”).
- iccid : The ICC ID number (“zzzzzzzzzzzzzzzzzzzz”).
- imei: The IMEI number (“yyyyyy”).
- imsi : The IMSI number of the SIM card (“xxxxxx”).
- ip_addr : The WAN IP address (“10.0.0.44”).
- network_type : The type of network connection (“WLAN”, “2G”, “3G”, “4G”, “LTE” or something else).
- rssi : The signal strength in percent (0-100).

You should also note that resources that are nested in namespaces other than tcxn are treated as nested resources in Managed IoT Cloud. You can read more about nested resources here.

Example payload

{
  "state": {
    "reported": {
    
      "latlng": "57.652,11.958",
      
      "tcxn": {
        "connection_status": 2,
        "battery_level": 50,
        "ip_addr": "10.0.0.44",
        "fw_ver": "0.2.1",
        "network_type": "3G",
        "rssi": 77,
        "imsi": "xxxxxx",
        "imei": "yyyyyy",
        "iccid": "zzzzzzzzzzzzzzzzzzzz"
      },
      
      "resource1": 98,
      "resource2": 233
    }
  }
}

Resources are dynamically typed

One really important thing to understand is that all data that you send to Managed IoT Cloud is indexed in Elasticsearch. The challenge here is that since the platform is extremly flexible it allows you to send basically any payload and since Elasticsearch automatically assigns a data type to each resource that you send based on its first value, you need to be very careful.

One really common error that our users do is that they send the value 23 as the first value and 24.2 as the second. If you try to do a sum aggregation of these values you’ll get 27, not 27.2 as you would expect. The reason for this is that the first value Elasticsearch saw was an integer and therefore all values will be indexed as integers.

The data type for a resource is stored per thing type.

Note: A value reported as 3.0 will be indexed as a long, and not a float. To index as a float, the value needs a fractional part > 0.

Old conventions

Before version 2.14.0 the tcxn namespace had two sub namespaces called cellular (containing network_type, rssi, imsi, imei, iccid) and wlan (containing rssi). For simplicity the structure have been flattened but the old conventions will still work in App Board.