Through this legacy API the device can send only part of the Device Management & Monitoring information to be processed & collected by the platform. Please see the mapping of legacy parameters to the device datamodel profile

By default the platform automatically generates through DMM collected information, several DMM datastreams through which it can be retrieved the history of different Device Monitoring & Management parameters. See Default Datamodels to know the list of datastreams.

JSON object

Table 1. DMM Collection object
Attribute Description

version

indicates the version of the structure

trustedBoot(optional)

In this case you are indicating that is required a validation type trusted_boot, it’s not necessary introduce the field value but if you introduce it all the message received by the platform will compare the trustedBoot value with the provisioned value if are diferent the message will not be collected

event

See Event object definition

Table 2. DMM Event Collection object
Attribute Description

id(optional)

Event Identifier

If not present the platform generates one with an internal counter.

device

Array of datastreams to be collected. See Device object definition

Table 3. Device object attributes
Attribute Description

id (optional)

Device Identifier.

If not present the platform assumes that the device id is the same than the id in the URI.

path

Array of device identifiers traversed to reach gateway

Filled only when devices is not connected directly to the platform. See Device to Platform connection scenarios

name

String with a human readable device name

description

String with a human readable device description

hardware

operationalStatus

See Device Operational Status Enumeration

softwareList[]

Array of software objects, See Software object

location

temperature

cpuUsage

ram

volatilStorage

nonVolatilStorage

powerSupply

communicationsModules[]

Table 4. Hardware object attributes
Attribute Description

serialnumber

Device Identifier.

manufacturer

model

Device Model. See Model Object

clockDate

Device internal datetime retrieved of the device internal clock. The format is YYYY-MM-DDThh:mm:ssTZD (eg 2015-07-16T19:20:30+01:00) as described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime

upTime

Time in seconds since the device has correctly started after a reboot or restart

Table 5. Hardware Model object attributes
Attribute Description

name

Model Name

version

Model Version

Table 6. Hardware object attributes
Attribute Description

name

Manufacturer Name

oui

Manufacturer Code (Organizational Unique Identifier)

Table 7. Software object attributes
Attribute Description

name

String. Name of the software

type

version

String. Version of the software

date

String with the Date of the software release in ISO 8601 format (eg 2015-07-16T19:20:30+01:00) as described in http://www.w3.org/TR/NOTE-datetime

Table 8. Location object attributes
Attribute Description

timestamp

String with the Date of the location release in ISO 8601 format(eg 2015-07-16T19:20:30+01:00) as described in http://www.w3.org/TR/NOTE-datetime

coordinates

Table 9. Coordinates object attributes
Attribute Description

latitude

Number in decimal degress

longitude

Number in decimal degress

Table 10. Temperature object attributes
Attribute Description

unit

String indicating units symbol (by default "C")

current

String with current temperature value in a float format

status

String indicating the status regarding the current temperature value. See Parameter Value Status Enumeration

trend

String indicating the trend of the temperature. See Parameter Trend Enumeration values

average

String with average of temperature value in a float format

maximum

String with the maximum of temperature value in a float format

minimum

String with the minimum of temperature value in a float format

Table 11. Cpu Usage object attributes
Attribute Description

unit

String indicating units symbol (by default "%")

current

String with current cpu usage value in a float format

average

String with average of cpu usage value in a float format

maximum

String with the maximum of cpu usage value in a float format

minimum

String with the minimum of cpu usage value in a float format

Table 12. Ram object attributes
Attribute Description

unit

String indicating units symbol (by default "%")

total

String indicating the total amount in the device

usage

Table 13. Ram Usage object attributes
Attribute Description

unit

String indicating units symbol (by default "%")

current

String with current usage value in a float format

average

String with average of usage value in a float format

maximum

String with the maximum of usage value in a float format

minimum

String with the minimum of usage value in a float format

Table 14. Volatile Storage object attributes
Attribute Description

unit

String indicating units symbol (by default "%")

total

String indicating the total amount in the device

usage

Table 15. Volatil Storage Usage object attributes
Attribute Description

unit

String indicating units symbol (by default "%")

current

String with current usage value in a float format

average

String with average of usage value in a float format

maximum

String with the maximum of usage value in a float format

minimum

String with the minimum of usage value in a float format

Table 16. Non Volatile Storage object attributes
Attribute Description

unit

String indicating units symbol (by default "%")

unit

String indicating the total amount in the device

usage

Table 17. Non Volatil Usage object attributes
Attribute Description

unit

String indicating units symbol (by default "%")

current

String with current ram usage value in a float format

average

String with average of ram usage value in a float format

maximum

String with the maximum of ram usage value in a float format

minimum

String with the minimum of ram usage value in a float format

Table 18. Power Supply object attributes
Attribute Description

source

String indicating the source of power currently used by the device. See Power Supply Source Enumeration values

status

String indicating the status regarding the power supply. See Parameter Value Status Enumeration

batteryChargeLevel

outage

Table 19. Battery Charge Level object attributes
Attribute Description

trend

String indicating the trend of the battery charge. See Parameter Trend Enumeration values

status

String indicating the status regarding the current charge. See Battery Charge Status Enumeration values

percentage

Seting indicating the percentage of charge

Table 20. Power Supply Outage object attributes
Attribute Description

timestamp

String with the Date of the software release in ISO 8601 format

duration

Number os seconds of power supply outage

Table 21. Communications Module object attributes
Attribute Description

id (optional)

Module Identifier.

name

String with a human readable module name

type

String Identifying the communications technology

hardware

operationalStatus

antennaStatus

softwareList[]

Array of software objects, See Software object

mobile

subscriber

subscription

Table 22. Mobile object attributes
Attribute Description

mr

String. Measure Results

apn

String. Access Point Name used to establish mobile data session

bcch

String. Broadcast Control Channel

cgi

String. Cell Global Identity

cellId

String. Cell Identification

lac

String. Location Area Code

ratType

String. Radio Access Technology Type

plmn

String. Public Land Mobile Network. Is identified by a (MCC, MNC) or by (CC, NDC)

timingAdvance

String. Length of time a signal from the mobile phone takes to reach the base station.

signalStrength

String. Current Radio Signal Strengh in dBms

signalStrengthMax

String. Maximum of Radio Signal Strengh in dBms

signalStrengthMin

String. Minimum of Radio Signal Strengh in dBms

signalQuality

String. Current Radio Signal Quality

signalQualityMax

String. Maximum of Radio Signal Quality

signalQualityMin

String. Minimum of Radio Signal Quality

Table 23. Subscriber Object attributes
Attribute Description

id

Subscriber Identifier.

name

String with a human readable suscriber name

type

String Identifying the communications technology

hardware

Table 24. Subscription Object attributes
Attribute Description

id

Subscription Identifier.

name

String with a human readable suscription name

type

String Identifying the communications technology

description

String with a human readable device description

operator

String with the name of the mobile operator

imsi

String with the global identifier of the subscription (IMSI)

msisdn

String with the mobile number

address

Collecting information

POST /south/v80/devices/{device.id}/collect/dmm

This request allows the device to append or modify information to an existing device

Using curl to perform the request:

curl --request POST \
     --data-binary @device.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_opengate_address]/south/v80/devices/{device.id}/collect/dmm \
     -H "Content-type: application/json"

In the response we should see a status code of 200 (updated the collected information). Let’s look the response.

HTTP/1.1 201 Added

JSON Examples

Let’s see some examples:

Write Device Inventory Info
{
    "version" : "7.0",
    "event" : {
        "id" : "12345566678",
        "device" : {
            "id" : "my_device",
            "path" : [],
            "name" : "my device",
            "description" : "device description",
            "hardware" : {
                "serialnumber" : "XXXXXXXXX",
                "manufacturer" :
                {
                    "name" : "hitachi",
                    "oui" : "XXXXXX"
                },
                "model" : {
                    "name": "XXXXX",
                    "version": "YYYY"
                }
            },
            "softwareList": [
                {
                    "name" : "firmware_name",
                    "type" : "FIRMWARE",
                    "version" : "1_0",
                    "date" : "2012-09-11T13:02:41Z"
                },
                {
                    "name" : "software_name",
                    "type" : "SOFTWARE",
                    "version" : "1_0",
                    "date" : "2012-09-11T13:02:41Z"
                }
            ],
            "communicationsModules": [
                {
                    "id" : "<identifier>. Ex: IMEI",
                    "name" : "2G-Modem",
                    "type" : "MOBILE",
                    "hardware" : {
                        "serialnumber" : "XXXXXXXXX or IMEI",
                        "manufacturer" :
                        {
                            "name" : "xxxxxx",
                            "oui" : "XXXXXX"
                        },
                        "model":
                        {
                            "name": "12345",
                            "version": "1.0"
                        }
                    },
                    "subscriber" : {
                        "id": "<identifier>. Ex: ICC",
                        "name" : "SIM-1 or ICC",
                        "type" : "SIM"
                    },
                    "subscription" : {
                        "id" : "<identifier. Ej: IMSI>",
                        "name" : "IMSI",
                        "description" : "MSISDN",
                        "operator" : "xxxxxx",
                        "imsi": "IMSI",
                        "msisdn": "MSISDN",
                        "type": "<MOBILE or other>",
                        "address" : {
                            "type" : "IPV4",
                            "value" : "X.X.X.X",
                            "apn" : "xxxx.xxx"
                        }
                    },
                    "softwareList": [
                        {
                            "name" : "firmware_name",
                            "type" : "FIRMWARE",
                            "version" : "1_0",
                            "date" : "2012-09-11T13:02:41Z"
                        }
                    ]
                },
                {
                    "name" : "Zigbee-Modem",
                    "type" : "Zigbee",
                    "hardware" : {
                        "serialnumber" : "XXXXXXXXX",
                        "manufacturer" :
                        {
                            "name" : "xxxxxx",
                            "oui" : "XXXXXX"
                        },
                        "model":
                        {
                            "name": "12345",
                            "version": "1.0"
                        }
                    },
                    "subscription" : {
                        "name" : "Network ID",
                        "description" : "",
                        "operator" : "",
                        "address" : {
                            "type" : "MAC",
                            "value" : "XXXXXXXX",
                            "apn" : ""
                        }
                    },
                    "softwareList": [
                        {
                            "name" : "firmware_name",
                            "type" : "FIRMWARE",
                            "version" : "1_0",
                            "date" : "2012-09-11T13:02:41Z"
                        }
                    ]
                }
            ]
        }
    }
}
Write both Device Inventory and Operational Status Info
{
    "version" : "7.0",
    "event" : {
        "id" : "12345566678",
        "device" : {
            "id" : "my_device",
            "path" : [],
            "name" : "my device",
            "description" : "device description",
            "hardware" : {
                "serialnumber" : "XXXXXXXXX",
                "manufacturer" :
                {
                    "name" : "hitachi",
                    "oui" : "XXXXXX"
                },
                "model" : {
                    "name": "XXXXX",
                    "version": "YYYY"
                },
                "clockDate" : "2014-07-08T13:02:41Z",
                "upTime" : "3600"
            },
            "operationalStatus": "NORMAL",
            "softwareList": [
                {
                    "name" : "firmware_name",
                    "type" : "FIRMWARE",
                    "version" : "1_0",
                    "date" : "2012-09-11T13:02:41Z"
                },
                {
                    "name" : "software_name",
                    "type" : "SOFTWARE",
                    "version" : "1_0",
                    "date" : "2012-09-11T13:02:41Z"
                }
            ],
            "location" : {
                "timestamp" : "2012-09-11T13:02:41Z",
                "coordinates": {
                    "latitude": 40.41675,
                    "longitude": -3.7028
                }
            },
            "temperature" : {
                "unit" : "C",
                "current" : "25.2",
                "status" : "NORMAL",
                "trend" : "DECREASING",
                "average" : "20",
                "maximum" : "25",
                "minimum" : "15"
            },
            "cpuUsage" : {
                "unit" : "%",
                "current" : "15.2",
                "average" : "15",
                "maximum" : "17",
                "minimum" : "9"
            },
            "ram" : {
                "unit" : "MB",
                "total" : "2048",
                "usage" : {
                    "unit" : "%",
                    "current" : "55",
                    "average" : "50",
                    "maximum" : "80",
                    "minimum" : "10"
                }
            },
            "volatilStorage" : {
                "unit" : "MB",
                "total" : "2048",
                "usage" : {
                    "unit" : "%",
                    "current" : "55",
                    "average" : "50",
                    "maximum" : "80",
                    "minimum" : "10"
                }
            },
            "nonVolatilStorage" : {
                "unit" : "MB",
                "total" : "1024",
                "usage" : {
                    "unit" : "%",
                    "current" : "55",
                    "average" : "50",
                    "maximum" : "80",
                    "minimum" : "10"
                }
            },
            "powerSupply": {
                "source" : "BATTERY",
                "status" : "NORMAL",
                "batteryChargeLevel" : {
                    "trend" : "EMPTY",
                    "status" : "CHARGED",
                    "percentage" : "100"
                },
                "outage" : {
                    "timestamp" : "2012-09-11T13:02:41Z",
                    "duration": 12000
                }
            },
            "communicationsModules": [
                {
                    "id" : "<identifier>. Ex: IMEI",
                    "name" : "2G-Modem",
                    "type" : "MOBILE",
                    "hardware" : {
                        "serialnumber" : "XXXXXXXXX or IMEI",
                        "manufacturer" :
                        {
                            "name" : "xxxxxx",
                            "oui" : "XXXXXX"
                        },
                        "model":
                        {
                            "name": "12345",
                            "version": "1.0"
                        }
                                        },
                    "operationalStatus" : "RUNNING",
                    "antennaStatus" : "OK",
                    "subscriber" : {
                        "id" : "SIM-1 or ICC",
                                                "name" : "SIM-1 or ICC",
                        "type" : "SIM"
                    },
                    "subscription" : {
                        "id" : "<identifier. Ej: IMSI>",
                        "name" : "IMSI",
                        "description" : "MSISDN",
                        "operator" : "xxxxxx",
                        "imsi": "IMSI",
                        "msisdn": "MSISDN",
                        "type": "<MOBILE or other>",
                        "address" : {
                            "type" : "IPV4",
                            "value" : "X.X.X.X",
                            "apn" : "xxxx.xxx"
                        }
                    },
                    "softwareList": [
                        {
                            "name" : "firmware_name",
                            "type" : "FIRMWARE",
                            "version" : "1_0",
                            "date" : "2012-09-11T13:02:41Z"
                        }
                    ],
                    "mobile" : {
                        "mr" : "",
                        "apn" : "",
                        "bcch" : "",
                        "cgi" : "",
                        "cellId" : "",
                        "lac" : "",
                        "ratType" : "",
                        "plmn" : "",
                        "timingAdvance" : "",
                        "signalStrength" : "-55",
                        "signalStrengthMax" : "-49",
                        "signalStrengthMin" : "-81",
                        "signalQuality" : "0",
                        "signalQualityMax" : "3.2",
                        "signalQualityMin" : "0"
                    }
                },
                {
                    "name" : "Zigbee-Modem",
                    "type" : "Zigbee",
                    "hardware" : {
                        "serialnumber" : "XXXXXXXXX or MAC",
                        "manufacturer" :
                        {
                            "name" : "xxxxxx",
                            "oui" : "XXXXXX"
                        },
                        "model":
                        {
                            "name": "12345",
                            "version": "1.0"
                        }
                    },
                    "subscription" : {
                        "name" : "Network ID",
                        "description" : "",
                        "operator" : "",
                        "address" : {
                            "type" : "MAC",
                            "value" : "XXXXXXXX",
                            "apn" : ""
                        }
                    },
                    "softwareList": [
                        {
                            "name" : "firmware_name",
                            "type" : "FIRMWARE",
                            "version" : "1_0",
                            "date" : "2012-09-11T13:02:41Z"
                        }
                    ]
                }
            ]
        }
    }
}