Introduction

The OpenGate Devices API is a Web REST based Interface that allows integration of devices, sensors, machines, etc. to the services provided by the OpenGate platform. In the next figure it is showed the main features of the API:

opengate api south intro services
Figure 1. OpenGate Web API main features

The main features provided by the API are:

  • Inventory & Operational Status Collection: Allows the devices (communication devices, machines, sensors, etc.) providing to the platform information about themselves and their logical resources as communications lines (subscribers, subscriptions/lines).

  • Operations: Allows the devices receiving remote operations requests from the platform and provide response to these requests with the result of the performed operation.

  • Events: Allows the devices communicating to the platform the raised events associated to devices.

  • Internet of Things (IoT) Information: Allows the devices providing to the platform all non structured information using the datastream paradigm.

The main services of the API are:

  • Collection Service: Allows to collect information from devices

    • /south/v80/devices/{device.id}/collect/dmm: Inventory and operational status information.

    • /south/v80/devices/{device.id}/collect/iot: Non structured information from sensors and machines

  • Event Service: Allows to provide device raised events.

    • /south/v80/devices/{device.id}/events/alarms: Device Alarms Notifications

  • Operations Service (/south/v80/devices/{device.id}/operation/response): Allows to implement the response to commands in the request/response/notifying message flows

    • /south/v80/devices/{device.id}/operation/response:

opengate api south intro navigable tree
Figure 2. OpenGate Web API navigable tree

Quick start

Start using curl

This guide will show you the minimum required to get started using OpenGate OSS API.

This guide assumes you have signed up to OpenGate and have an API key. All the examples in this quick start use curl[1]. If you are not familiar with curl and you have a public OpenGate installation try hurl.

API keys and authentication

The OpenGate API is enabled by default on all accounts. You don’t have to do anything to turn on this feature. However, API keys are used to control access to the resources via the API. When a third-party application asks for your API key, you can find it on your My info page by clicking the “Show your API keys” link.

The OpenGate API allows device to communicate with OpenGate.

The API keys can be sent using one of two methods: as a request header or as a parameter in the request URL (with the former preferred for security reasons).

  • Using an HTTP header: This is the recommended method of sending your API key because, whilst still not secure if sent over an unencrypted connection, it is less likely to be logged as part of the URL:

    X-ApiKey: YOUR_API_KEY_HERE
    API Key in HTTP Header example
    POST /south/v80/devices/{device.id}/collect/dmm
Host: [your_opengate_address]
X-ApiKey: YOUR_API_KEY_HERE

  • As a request parameter:

    Table 1. South API Key as Url Parameter
    Parameter Name Value

    X-ApiKey

    YOUR_API_KEY_HERE

    		 
    http://[your_opengate_address]/south/v80/devices/{device.id}/collect/dmm?X-ApiKey=YOUR_API_KEY_HERE
    API Key as URL Parameter Example
    POST /south/v80/devices/{device.id}/collect/dmm?X-ApiKey=YOUR_API_KEY_HERE
Host: [your_opengate_address]

Response status and error messages

HTTP status codes

The OpenGate OSS API attempts to return appropriate HTTP status codes for every request.

Table 2. HTTP status codes
Code Text Description

200

OK

GET, PUT and DELETE operation Success!

201

OK

POST operation Success!

204

No Content

No elements found for the given URL.

304

Not Modified

There was no new data to return.

400

Bad Request

The request was invalid. An accompanying error message will explain why.

401

Unauthorized

Authentication credentials were missing or incorrect.

403

Forbidden

The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why.

404

Not Found

The URI requested is invalid or the resource requested, does not exists. An accompanying error message will explain why.

405

Not Allowed

The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.

406

Not Acceptable

Returned by the API when an invalid format is specified in the request.

409

Conflict

The request could not be completed due to a conflict with the current state of the resource

412

Precondition Failed

The precondition given in one or more of the request-header fields evaluated to false when it was tested on the server.

500

Internal Server Error

Something is broken. Please contact with your administrator.

Error messages

When the OpenGate API returns error messages, it does so in JSON format.

Table 3. Error message object attributes
Attribute (* required) Description

code *

code of error

message *

description of error

context

context of the error, attempts to clarify the point where the error occurs

For example, an error requesting a non existent entity might look like this:

Error Message Example1 in JSON format
{
    "errors":[
        {
            "code":2,
            "message":"Json is malformed"
        }
    ]
}
Error Message Example2 in JSON format
{
    "errors":[
        {
             "code":34,
             "message":"Sorry, that entity does not exist",
             "context" : [ {"name" : "param1", "value" : "value1"}, {"name" : "param2", "value" : "value2"}]
        }
    ]
}

List of Errors

If you see an error response which is not listed in the above table, then fall back to the HTTP status code in order to determine the best way to address the error.

Table 4. Generic Errors
Code Returned HTTP Status Description

1

HTTP 400

Reserved

2

HTTP 400

Json is malformed

Special Protocols

The platform by default implement http protocol for the exchange of message, but you can use other special protocols using the same message format than defined for http protocol.

The payload of the protocols used in the platform always will be the same

Web socket

In order to establish the connection web socket it’s necessary connect to the next url:

ws://[your_opengate_addres]/south/v80/sessions/{device.id}

where in OpenGate the port used for the web socket connection is 9955

Due to security purposes identification Api-key must be included, for doing that you have two options

  • In the header of the HTTP message involved in the web socket establishment

  • in the URL using the parameter "X-ApiKey"

Example 1. Example using parameter X-ApiKey for introduce api-key
ws://[your_opengate_addres]/south/v80/sessions/{device.id}?X-ApiKey={ApiKey}

In this moment you can use web socket only for responses of operations and secure web socket is not available

MQTT

As in the case of web socket the first step for use a Mqtt conexion with OpenGate platform is stablish the connection, for do that it’s necessary connect to the next url:

tcp://[your_opengate_addres]:1883

where you can configurate the next parameters: * userName: this is the name used by the device for identify himself, deviceId * password: this is the ApiKey necessary that identify the user.

With just only one conection, the devices could recive messages from the platform, operation request, and send messages: operation responses, dmm, iot events and request on demand operations, taking care the next points:

  • Using subscriber rol, the device could recive operation request subscribing to the topic ---odm/request/[deviceId]

  • Using publisher rol, the device could send

    • Operation responsens with the topic ---odm/response

    • Dmm events with the topic ---odm/dmm

    • Iot events with the topic ---odm/iot

    • Alarm events with the topic ---odm/event

    • Request on demand operations ---odm/operationOnDemand

All the json objects are similar than in the case of http comunications but in Mqtt is mandatory the deviceId field where you can indicate gatewayId or assetId.

Example of ondemand operation request json from an asset
{
    "trustedBoot": "ñasdohfñasjkdfñ",
    "operation": {
        "request": {
            "deviceId": "asset_1",
            "path": [
                "gateway1"
            ]
        }
    }
}

Data Collection

DMM (Legacy- Deprecated)

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 5. 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 6. 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 7. 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 8. 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 9. Hardware Model object attributes
Attribute Description

name

Model Name

version

Model Version
Table 10. Hardware object attributes
Attribute Description

name

Manufacturer Name

oui

Manufacturer Code (Organizational Unique Identifier)
Table 11. 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 12. 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 13. Coordinates object attributes
Attribute Description

latitude

Number in decimal degress

longitude

Number in decimal degress
Table 14. 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 15. 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 16. Ram object attributes
Attribute Description

unit

String indicating units symbol (by default "%")

total

String indicating the total amount in the device

usage
Table 17. 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 18. Volatile Storage object attributes
Attribute Description

unit

String indicating units symbol (by default "%")

total

String indicating the total amount in the device

usage
Table 19. 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 20. 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 21. 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 22. 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 23. 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 24. 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 25. 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 26. 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 27. Subscriber Object attributes
Attribute Description

id

Subscriber Identifier.

name

String with a human readable suscriber name

type

String Identifying the communications technology

hardware
Table 28. 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"
                        }
                    ]
                }
            ]
        }
    }
}

Datamodels DMM Mapping

This chapter describes how are mapped

Table 29. Dmm South API to IoT datastreams Mapping
South API Attribute (path) IoT Datastream

trustedBoot

device.trustedBoot

event.device.id

device.identifier

event.device.path

device.topology.path

event.device.name

device.name

event.device.description

device.description

event.device.hardware.serialnumber

device.serialNumber

event.device.hardware.manufacturer.name

device.model

event.device.hardware.manufacturer.oui

device.model

event.device.hardware.model.name

device.model

event.device.hardware.model.version

device.model

event.device.hardware.clockDate

device.clock

event.device.hardware.upTime

device.upTime

event.device.operationalStatus

device.operationalStatus

event.device.softwareList[].name

device.software

event.device.softwareList[].type

device.software

event.device.softwareList[].version

device.software

event.device.softwareList[].date

N/A

event.device.location.timestamp

N/A

event.device.location.coordinates.latitude

device.location

event.device.location.coordinates.longitude

device.location

event.device.temperature.unit

N/A

event.device.temperature.current

device.temperature.value

event.device.temperature.status

device.temperature.status

event.device.temperature.trend

N/A

event.device.temperature.average

N/A

event.device.temperature.maximum

N/A

event.device.temperature.minimum

N/A

event.device.cpuUsage.unit

N/A

event.device.cpuUsage.current

device.cpu.usage

event.device.cpuUsage.average

N/A

event.device.cpuUsage.maximum

N/A

event.device.cpuUsage.minimum

N/A

event.device.ram.unit

N/A

event.device.ram.total

device.ram.total

event.device.ram.usage.unit

N/A

event.device.ram.usage.current

device.ram.usage

event.device.ram.usage.average

N/A

event.device.ram.usage.maximum

N/A

event.device.ram.usage.minimum

N/A

event.device.volatilStorage.unit

N/A

event.device.volatilStorage.total

device.storage.ramDisk.total

event.device.volatilStorage.usage.unit

N/A

event.device.volatilStorage.usage.currentt

device.storage.ramDisk.usage

event.device.volatilStorage.usage.average

N/A

event.device.volatilStorage.usage.maximum

N/A

event.device.volatilStorage.usage.minimum

N/A

event.device.nonVolatilStorage.unit

N/A

event.device.nonVolatilStorage.total

device.storage.disk.total

event.device.nonVolatilStorage.usage.unit

N/A

event.device.nonVolatilStorage.usage.current

device.storage.disk.usage

event.device.nonVolatilStorage.usage.average

N/A

event.device.nonVolatilStorage.usage.maximum

N/A

event.device.nonVolatilStorage.usage.minimum

N/A

event.device.powerSupply.source

device.powersupply.source

event.device.powerSupply.status

device.powersupply.status

event.device.powerSupply.batteryChargeLevel.trend

N/A

event.device.powerSupply.batteryChargeLevel.status

device.powersupply.battery.status

event.device.powerSupply.batteryChargeLevel.percentage

device.powersupply.battery.charge

event.device.powerSupply.outage.timestamp

device.powersupply.outage

event.device.powerSupply.outage.duration

device.powersupply.outage

event.device.communicationsModules[].id

device.communicationModules[].identifier

event.device.communicationsModules[].name

device.communicationModules[].name

event.device.communicationsModules[].type

device.communicationModules[].specificType

event.device.communicationsModules[].hardware.serialnumber

device.communicationModules[].serialNumber

event.device.communicationsModules[].hardware.manufacturer.name

device.communicationModules[].model

event.device.communicationsModules[].hardware.manufacturer.oui

device.communicationModules[].model

event.device.communicationsModules[].hardware.model.name

device.communicationModules[].model

event.device.communicationsModules[].hardware.model.version

device.communicationModules[].model

event.device.communicationsModules[].hardware.clockDate

N/A

event.device.communicationsModules[].hardware.upTime

N/A

event.device.communicationsModules[].operationalStatus

device.communicationModules[].operationalStatus

event.device.communicationsModules[].antennaStatus

device.communicationModules[].mobile.antenna.status

event.device.communicationsModules[].softwareList[].name

device.communicationModules[].software

event.device.communicationsModules[].softwareList[].type

device.communicationModules[].software

event.device.communicationsModules[].softwareList[].version

device.communicationModules[].software

event.device.communicationsModules[].softwareList[].date

N/A

event.device.communicationsModules[].mobile.mr

device.communicationModules[].subscription.mobile.mr

event.device.communicationsModules[].mobile.apn

N/A

event.device.communicationsModules[].mobile.bcch

device.communicationModules[].subscription.mobile.bcch

event.device.communicationsModules[].mobile.cgi

device.communicationModules[].subscription.mobile.uli.cgi

event.device.communicationsModules[].mobile.cellId

device.communicationModules[].subscription.mobile.uli.cellId

event.device.communicationsModules[].mobile.lac

device.communicationModules[].subscription.mobile.uli.cgiLac

event.device.communicationsModules[].mobile.ratType

device.communicationModules[].subscription.mobile.ratType

event.device.communicationsModules[].mobile.plmn

device.communicationModules[].subscription.mobile.registeredPlmn

event.device.communicationsModules[].mobile.timingAdvance

device.communicationModules[].subscription.mobile.timingAdvance

event.device.communicationsModules[].mobile.signalStrength

device.communicationModules[].subscription.mobile.signalStrength

event.device.communicationsModules[].mobile.signalStrengthMax

N/A

event.device.communicationsModules[].mobile.signalStrengthMin

N/A

event.device.communicationsModules[].mobile.signalQuality

device.communicationModules[].subscription.mobile.signalQuality

event.device.communicationsModules[].mobile.signalQualityMax

N/A

event.device.communicationsModules[].mobile.signalQualityMin

N/A

event.device.communicationsModules[].subscriber.id

device.communicationModules[].subscriber.identifier

event.device.communicationsModules[].subscriber.name

device.communicationModules[].subscriber.name

event.device.communicationsModules[].subscriber.type

device.communicationModules[].subscriber.specificType

event.device.communicationsModules[].subscriber.hardware.serialnumber

device.communicationModules[].subscriber.serialNumber

event.device.communicationsModules[].subscriber.hardware.manufacturer.name

device.communicationModules[].subscriber.model

event.device.communicationsModules[].subscriber.hardware.manufacturer.oui

device.communicationModules[].subscriber.model

event.device.communicationsModules[].subscriber.hardware.model.name

device.communicationModules[].subscriber.model

event.device.communicationsModules[].subscriber.hardware.model.version

device.communicationModules[].subscriber.model

event.device.communicationsModules[].subscriber.hardware.clockDate

N/A

event.device.communicationsModules[].subscriber.hardware.upTime

N/A

event.device.communicationsModules[].subscription.id

device.communicationModules[].subscription.identifier

event.device.communicationsModules[].subscription.name

device.communicationModules[].subscription.name

event.device.communicationsModules[].subscription.type

device.communicationModules[].subscription.specificType

event.device.communicationsModules[].subscription.description

device.communicationModules[].subscription.description

event.device.communicationsModules[].subscription.operator

device.communicationModules[].subscription.mobile.registeredOperator

event.device.communicationsModules[].subscription.imsi

device.communicationModules[].subscription.mobile.imsi

event.device.communicationsModules[].subscription.msisdn

device.communicationModules[].subscription.mobile.msisdn

event.device.communicationsModules[].subscription.address.type

device.communicationModules[].subscription.address

event.device.communicationsModules[].subscription.addres.value

device.communicationModules[].subscription.address

event.device.communicationsModules[].subscription.address.apn

device.communicationModules[].subscription.address

Datastream (Old Iot)

Through this API the device can send unstructured IoT information to be processed & collected by the platform.

JSON Objects

Table 30. Datapoint Collection object
Attribute Description

version

indicates the version of the structure

device (optional)

Device Identifier in case of be different that the device Identifier that sends information (included in the URI)

path (optional)

Identifier of the gateway or gateways that as been used by the asset for sending the information

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

datastreams[]

Array of datastreams to be collected. See Datastream object definition
Table 31. Datastream object attributes
Attribute Description

id

Identifier of the datastream

feed (optional)

Feed Identifier

datapoints[]

Array of datapoints data to be collected. See Datapoint object definition

The feeds concept in the JSON object can be used to differentiate:

  • Collected information of a same sensor used by different sources (Example: People using a same eHealth glucometer sensor)

  • Collected information of the multiple sensors at he same type (example: temperature) placed in different locations and connected to the same device. (Example: temperatures of different places of a room)

If no multiples feeds are needed the name "default" of the feed must be used as feed to collect information from sensor
Table 32. Datapoint object attributes
Attribute Description

from (optional)

Number with the time in miliseconds from epoch of the start period of measurement. This indicates that value is the same within this time interval (from -→ at).

This field is necessary if you are using datastream period = pulse, if this field is not incorporated the default value is the same than the value of the field "at". If the value of the field from is greater than the value of the field at, the value of the field from will be changed by the value of the field at, and both of them will have the same value.

at (optional)

Number with the time in miliseconds from epoch of the measurement

If this field is missing, the platform will assign the server current time to the datapoint whe data is received.

It is necessary to observe that in the multiple Datapoints scenario, only a datapoint value can appear without "at" field. If not the platform will take the first datapoint (in JSON object) where the field is missing and drop the others in the same situation. See next valid examples:

  • Single DataPoint

"datapoints":[
    {"at":1431602523123,"value":41}
]
"datapoints":[
    {"value":333}
]

  • Multiple DataPoints

"datapoints":[
    {"at":1431602523123,"value":41},
    {"at":1431602623123,"value":84},
    {"at":1431607623123,"value":41},
    {"value":83}
]

value

This is a polyvalent field that can be any of the JSON supported data types:

"value" : 10

  • String delimited with double-quotation marks. Example:

"value" : "string value"

  • Boolean either of the values true or false. Example:

"value" : true

  • Array of JSON data types. Example:

"value" : [ "text1", "text2" ]

  • Object with JSON format. Example:

"value" : {
    "field1": "text",
    "field2": 12
}

  • Null. Example:

"value" : null

The format of the field is defined in the datastream template. See Templates description section

tags[] (optional)

Array of tags (in string format) to be associated to a datapoint

Collecting information

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

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

It can be done:

  • Writing datapoints with their respective timestamps in different datastreams in a only request

  • Writing datapoints without timestamp in different datastreams in a only request

The second request type is used when the device hasn’t internal clock. In this case the platform connector puts the associated timestam. It is mainly used to provide latest value of a signal in the sensor or the machine

Using curl to perform the request:

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

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

HTTP/1.1 201 Added

JSON Examples

Let’s see some examples:

Write Multiple Datapoints to Each Datastream (With timestamp)
{
  "version":"1.0.0",
  "datastreams" : [
    {
      "id" : "example",
      "feed" : "feed_1",
      "datapoints":[
        {"at":1431602523123,"value":41},
        {"at":1431602623123,"value":84},
        {"at":1431607623123,"value":41},
        {"at":1431608623123,"value":83}
      ]
    },
    {
      "id" : "key",
      "feed" : "feed_2",
      "datapoints":[
        {"at":1431602523123,"value":"revalue"},
        {"at":1431602623123,"value":"string value"},
        {"at":1431607623123,"value":"any string"},
        {"at":1431608623123,"value":"structured data"}
      ]
    },
    {
      "id" : "datastream",
      "datapoints":[
        {"at":1431602523123,"value":51, "tags":["tag_1","tag_2"]},
        {"at":1431602623123,"value":102, "tags":["tag_2","tag_3"]},
        {"at":1431607623123,"value":32},
        {"at":1431608623123,"value":16, "tags":["tag_3"]}
      ]
    }
  ]
}
Write Latest value with a single Datapoint to Each Datastream (Without timestamp)
{
  "version":"1.0.0",
  "datastreams" : [
    {
      "id" : "example",
      "feed" : "feed_1",
      "datapoints":[
        {"value":333}
      ]
    },
    {
      "id" : "key",
      "feed" : "feed_2",
      "datapoints":[
        {"value":"value"}
      ]
    },
    {
      "id" : "datastream",
      "datapoints":[
        {"value":1337}
      ]
    }
  ]
}
Write Latest value with a single datapoint to one Datastream sended by an asset with trusted boot
{
    "version": "1.0.0",
    "device": "asset1",
    "path": [
        "gateway1"
    ],
    "trustedBoot": "ñasdohfñasjkdfñ",
    "datastreams": [
        {
            "id": "example",
            "datapoints": [
                {
                    "at": 1490092712000,
                    "value": "1"
                }
            ]
        }
    ]
}

To find a list of specific datastream and examples of using it see Default Datamodels

Operations

The operations API defines the way the platform interacts with the Devices to perform remote operations on the device and receive the associated response.

The platform implements by default a set of device operation types that it is recommended to be implemented by the device. Find the list in the Default Operations Catalogue

To understand the possible behaviours you need understand first the next concepts:

  • Flow Strategies (Synchronous/Asynchronous): Describe different alternatives to manage the message exchange between Platform and Device using HTTP protocol

  • Operation Structure (Simple/Multistep): Describe different possibilities to complete the result of the operation. Sometimes it is necessary that the operation can be completed in two or more steps (example: update or reboot operation)

Flow Strategies

  • Synchronous: The Request/Response is embedded in a only HTTP dialog. Only a HTTP connection is used

opengate api south operation workflows synchronous
Figure 3. Synchronous Operation Strategy

  • Asynchronous :The Request/Response is embedded in different HTTP dialogues. At two or more HTTPs connections is used to communicate the request and to communicate the response or responses

    • Simple Response: Only a Final Response message is sent by the Device to answer the Request

opengate api south operation workflows asynchronous simple
Figure 4. Asynchronous Operation Strategy - Simple Response

  • Multiple Response: Multiple Partial responses can be sent by the device and a Final Response at the end of the sequence

opengate api south operation workflows asynchronous multiple
Figure 5. Asynchronous Operation Strategy - Multiple Responses

Operation Structure

  • Simple Request/Response: The Operation has only a Request and a Response to finish it. There is no intermediate steps. It can be used Synchronous or Asynchronous (Simple response) flow strategy

Example 2. Simple Response
1 Device Operation Request Json Object
{
    "operation": {
        "request": {
            "timestamp": 1432454277950,
            "name": "REBOOT_EQUIPMENT",
            "parameters": [
                {
                    "name": "type",
                    "value": {
                        "string": "HARDWARE"
                    }
                }
            ],
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327"
        }
    }
}
2 Device Operation Final Response Json Object
{
    "version": "7.0",
    "operation": {
        "response": {
            "timestamp": 1432454278000,
            "name": "REBOOT_EQUIPMENT",
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327",
            "resultCode": "SUCCESSFUL",
            "resultDescription": "No Error.",
            "variableList": [],
            "steps": []
        }
    }
}

Note that the field "resultCode" is present in the final response

  • Multistep Response: The Operation requires a list of steps to track the operation. This steps can arrive all together in the final response or gradually in partial responses until finishing with the Final response. It can be used Synchronous or Asynchronous (Simple or Multiple response) flow strategy

Example 3. Multistep Simple Response
1 Device Operation Request Json Object
{
    "operation": {
        "request": {
            "timestamp": 1432454277950,
            "name": "REBOOT_EQUIPMENT",
            "parameters": [
                {
                    "name": "type",
                    "value": {
                        "string": "HARDWARE"
                    }
                }
            ],
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327"
        }
    }
}
2 Device Operation Final Response Json Object
{
    "version": "7.0",
    "operation": {
        "response": {
            "timestamp": 1432454278000,
            "name": "REBOOT_EQUIPMENT",
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327",
            "resultCode": "SUCCESSFUL",
            "resultDescription": "No Error.",
            "variableList": [],
            "steps": [
                {
                    "name" : "STEP_1",
                    "result" : "SUCCESSFUL",
                    "timestamp" : 1432454278000,
                    "response" : []
                },
                {
                    "name" : "STEP_2",
                    "result" : "SUCCESSFUL",
                    "timestamp" : 1432454278000,
                    "response" : []
                }
            ]
        }
    }
}

Note that the field "resultCode" is present in the final response
Example 4. Multistep Multiple Responses
1 Device Operation Request Json Object
{
    "operation": {
        "request": {
            "timestamp": 1432454277950,
            "name": "REBOOT_EQUIPMENT",
            "parameters": [
                {
                    "name": "type",
                    "value": {
                        "string": "HARDWARE"
                    }
                }
            ],
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327"
        }
    }
}
2 Device Operation Partial Response Json Object
{
    "version": "7.0",
    "operation": {
        "response": {
            "timestamp": 1432454278000,
            "name": "REBOOT_EQUIPMENT",
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327",
            "variableList": [],
            "steps": [
                {
                    "name" : "STEP_1",
                    "result" : "SUCCESSFUL",
                    "timestamp" : 1432454278000,
                    "response" : []
                }
            ]
        }
    }
}
3 Device Operation Final Response Json Object
{
    "version": "7.0",
    "operation": {
        "response": {
            "timestamp": 1432454278500,
            "name": "REBOOT_EQUIPMENT",
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327",
            "resultCode": "SUCCESSFUL",
            "resultDescription": "No Error.",
            "variableList": [],
            "steps": [
			    {
                    "name" : "STEP_2",
                    "result" : "SUCCESSFUL",
                    "timestamp" : 1432454278000,
                    "response" : []
                }
			]
        }
    }
}

Note that the field "resultCode" is present in the final response

URIs

Attending to the flow strategies described above shouth operations API can be summarized:

  • It is used HTTP request/response mechanism with and embedded JSON file to both flow directions:

    • Platform → Device: Synchronous/Asynchronous Operation Request

    • Device → Platform:

      • Operation Response

      • On demand Request

  • Both Platform and Device must to implement a HTTP web service publishing a URI as defined in the next table

Table 33. Operation URIs and ports
Side URI Port

Device

/v80/devices/{device.id}/operation/request

1123 / 11235 (secure mode)

Platform

/south/v80/devices/{device.id}/operation/response

/south/v80/devices/{device.id}/operation/pending

Implicit the port through /south/

Operation Request

POST /south/v80/devices/{device.id}/operation/request

The device is notified by the platform using the URI above with the Operation Request to be executed

As stated in the workflow figure, the platform sends a HTTP request to the device using this URI.

JSON Object

This is the JSON object embedded to the HTTP Request

Table 34. Operation object attributes
Attribute Description

request
Table 35. Operation Request object attributes
Attribute Description

id

Unique identifier (platform generated) for the request. This will contain an string in UUID format

timestamp

Number with the time in seconds from epoch when platform has launched the request

deviceId(optional)

Only used when device that executes the operation is different than the device used as a gateway or proxy. Example: Operation on a Zigbee sensor behind a device proxy which is connected to the platform. If the field is not present the final device to execute the operation is that is indicated in the URI

path

Array of device identifiers traversed from the Gateway device to reach the deviceId device

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

name

String with the name or identifier of the type of operation.

The platform implements by default a set of device operations type that it is recommended to be implemented by the device. Find the list in the Default Operations Catalogue

New, adhoc operations can be added to the platform depending on the device capabilities

parameters[]

Array of parameters associated to the operation request. See Parameter Object
Table 36. Operation Request parameter object attributes
Attribute Description

name

Name of the parameter

value

This is a polyvalent field that can be any of the JSON supported data types:

"value" : 10

  • String delimited with double-quotation marks. Example:

"value" : "string value"

  • Boolean either of the values true or false. Example:

"value" : true

  • Array of JSON data types. Example:

"value" : [ "text1", "text2" ]

  • Object with JSON format. Example:

"value" : {
    "field1": "text",
    "field2": 12
}

  • Null. Example:

"value" : null

Operation Request Example

HTTP Request JSON example
{
    "operation" :
    {
        "request" :
        {
            "id" : "f508ce84-01e9-11e5-a322-1697f925ec7b",
            "deviceId": "device_1",
            "path" : [],
            "timestamp" : 1432454275000,
            "name" : "SET_CLOCK",
            "parameters": [
                {
                    "name" : "datetime",
                    "value" : "YYYY-MM-DD"
                },
                {
                    "name" : "time",
                    "value" : "hh:mm:ss.s"
                },
                {
                    "name" : "timezone",
                    "value" : "(+/-)hh:mm"
                },
                {
                    "name" : "daylightsavingtime",
                    "value" : "(+/-)hh:mm"
                }
            ]
        }
    }
}

A similar behaviour of the platform can be implemented using CURL

curl --request POST \
     --data-binary @opengate-api-south-operation-request-set-clock.json \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_device_address]/south/v80/devices/{device.id}/operation/request \
     -H "Content-type: application/json"

On demand Operation Request

Is a mechanism to allow the Device asking for the pending operations requests to the Platform. The platform answers with the pending requests.

opengate api south operation workflows ondemand
Figure 6. Ondemand Operation Request

Used by the devices that are sleeping when they wake up to take pending operation requests

POST /south/v80/devices/{device.id}/operation/pending

The device ask to the platform for pending operations using the URI above with the Operation Request to be executed

JSON Objects

Table 37. On demand operation object
Attribute Description

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

operation

See Operation request object definition
Table 38. Operation Request object attributes
Attribute Description

deviceId(optional)

Only used when device that executes the operation is different than the device used as a gateway or proxy. Example: Operation on a Zigbee sensor behind a device proxy which is connected to the platform. If the field is not present the final device to execute the operation is that is indicated in the URI

path(optional)

Array of device identifiers traversed from the Gateway device to reach the deviceId device

Only the next pending operation request is returned. If there is more than one pending operations the device has to call several times until there is no more operation requests pending

As stated in the work flow figure, the device sends a HTTP request to the platform using this URI

If you are going to use http this is an example using curl of operation request

curl --request POST \
     --header "X-ApiKey: YOUR_API_KEY_HERE" \
     --verbose \
     http://[your_platform_address]/south/v80/devices/{device.id}/operation/pending \
     -H "Content-type: application/json"
Example of ondemand operation request json from an asset
{
    "trustedBoot": "ñasdohfñasjkdfñ",
    "operation": {
        "request": {
            "deviceId": "asset_1",
            "path": [
                "gateway1"
            ]
        }
    }
}

In the response we should see a status code of 201 (created)

HTTP/1.1 201 Created

If you are going to use mqtt you have to send a message to the topic odm/operationOnDemand with a string with deviceId identification

The device must be waiting some seconds for receiving the request of the pending operation, the platform will send the first of the operations ordered by date, the older the first, when the device finish the execution of an operation have to ask again for new operations repiting the last cicle. when there is no more operation the device will not recive a request.

Response (Device to Platform)

POST /south/v80/devices/{device.id}/operation/response

There is no difference between Synchronous and Asynchronous flow strategies implies regarding to the Jsons format. Only when this file is embedded in to the HTTP body

  • Synchronous: The file is embedded in the HTTP Response

  • Asynchronous: : The file is embedded in a new HTTP POST initiated in the device

JSON Object

Table 39. Reponse 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

operation

See Operation Response object definition
Table 40. Operation Response object attributes
Attribute Description

id

Unique identifier (platform generated) for the request/response. This will contain an string in UUID format and it must be the same than the received request

timestamp

Number with the time in seconds from epoch when platform has launched the request

deviceId (optional, mandatory with MQTT)

Only used when device that response to the executed operation is different than the device used as a gateway or proxy. Example: Operation on a Zigbee sensor behind a device proxy which is connected to the platform. If the field is not present the final device to execute the operation is that is indicated in the URI

name

String with the name or identifier of the type of operation.

The platform implements by default a set of device operations type that it is recommended to be implemented by the device. Find the list in the Default Operations Catalogue

New, adhoc operations can be added to the platform depending on the device capabilities

path

String indicating the path of the underliying device

resultCode (optional)

String indicating the result code. Valid values are:

  • SUCCESSFUL: The operation request has been executed and finished without errors

  • OPERATION_PENDING

  • ERROR_IN_PARAM

  • NOT_SUPPORTED

  • ALREADY_IN_PROGRESS

  • ERROR_PROCESSING

  • ERROR_TIMEOUT

  • TIMEOUT_CANCELLED

  • CANCELLED

  • CANCELLED_INTERNAL

When this field is present the platform considers that the operation has finished

If the field is not present the platform considers a partial response in a multi-step operation that requires notifying intermediate results before to complete the operation. Example File downloading progress

resultDescription (optional)

String indicating the result code. Present when "resultCode" parameter is included

steps[](optional)

Array of steps returned associated to the operation response. See Step Object
Table 41. Operation Response Step object attributes
Attribute Description

name

String with the name of the step.

result

String indicating the result code. Valid values are:

  • ERROR: The step has been executed and finished with error

  • SUCCESSFUL: The step has been executed and finished with success

  • SKIPPED

timestamp

Number with the time in seconds from epoch when platform has launched the request

description

String describing the result

response[](optional)

Array of variables returned associated to the step. See Parameter Object
Operation Response JSON example
{
    "version" : "7.0",
    "operation" :
    {
        "response" :
        {
            "id" : "f508ce84-01e9-11e5-a322-1697f925ec7b",
            "timestamp" : 1432454282000,
            "deviceId" : "device_1",
            "name" : "SET_CLOCK",
            "resultCode" : "SUCCESS",
            "resultDescription" : "No Error",
        }
    }
}

As stated in the work flow figure, the device sends a HTTP or HTTPS request on the device using this URI

A similar behaviour of the platform can be implemented using CURL

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

Multistep Operation JSON example

Operation Request
{
    "operation" :
    {
        "request" :
        {
            "id" : "e05e4354-ffe0-4cfa-8030-f6b9500b64ab",
            "deviceId": "device_1",
            "path" : [],
            "timestamp" : 1432454276000,
            "name" : "EQUIPMENT_DIAGNOSTIC",
            "parameters": [
                {
                    "name" : "name",
                    "value" : "DEVICE"
                }
            ]
        }
    }
}
Operation Response JSON example
{
    "version" : "7.0",
    "operation" :
    {
        "response" :
        {
            "id" : "e05e4354-ffe0-4cfa-8030-f6b9500b64ab",
            "timestamp" : 1432454278000,
            "deviceId" : "device_1",
            "name" : "EQUIPMENT_DIAGNOSTIC",
            "resultCode" : "SUCCESS",
            "resultDescription" : "No Error",
            "steps":[
                {
                    "name":"MOTHER_BOARD",
                    "timestamp" : 1432454278000,
                    "result":"SUCCESSFUL",
                    "description":"Motherboard is Ok"
                },
                {
                    "name":"COMMUNICATIONS_MODULE",
                    "timestamp" : 1432454278000,
                    "result":"SUCCESSFUL",
                    "description":"Communications is Ok"
                },
                {
                    "name":"STORAGE",
                    "timestamp" : 1432454278000,
                    "result":"SUCCESSFUL",
                    "description":"Storage is Ok"
                }
            ]
        }
    }
}

Security

In this flow the platform is implements the role of HTTP server and it has to implement the next security strategy:

By default the security mechanism implemented by the platform is based on API_KEY. This key is included in the HTTP header.

It is possible configure the platform to use a different KEY organization or per channel.

HTTPS for encryption messages is supported and can be configured in the platform.

Other mechanisms as mutual authentication using HTTPS PKI infrastructure can be supported.

Events

This platform API allows the devices sending asynchronous events to notify extraordinary operational situations

The next figure shows the workflow of the events

opengate api south event workflow
Figure 7. Event flow

As it is shown in the image:

  • It is used HTTP request/response mechanism with and embedded JSON file

  • Platform implements a HTTP web service publishing the next URIs

Table 42. Event URI
URI Description

POST - /south/v80/devices/{device.id}/events/alarms

For device alarm events

Alarms Event

POST /south/v80/devices/{device.id}/events/alarms

JSON Object

Table 43. Alarm object attributes
Attribute Description

id

Unique identifier (platform generated) for the event. This will contain an string in UUID format

timestamp

Number with the time in seconds from epoch when platform has launched the event

deviceId(optional)

Only used when device that generates the operation is different than the device used as a gateway or proxy. Example: Event from a Zigbee sensor behind a device proxy which is connected to the platform. If the field is not present the final device to execute the operation is that is indicated 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 the name or identifier of the type of event.

See Events examples

New events can be added depending on the device capabilities

specific

String with a device specific name for this type of event.

description

String describing the alarm or reason of raising it

variables[]

Array of variables associated to the operation request. See Parameter Object
AlarmEvent JSON example
{
    "event" :
    {
        "alarm" :
        {
            "id": "50dca9ab-f552-4805-9cff-019090d5b92b",
            "deviceId":"device_1",
            "severity": "CRITICAL",
            "priority" : "HIGH",
            "name": "Alarm_1",
            "specific" : "",
            "description": "alarm description",
            "timestamp" : 1432454275000,
            "variables": [
			    {
					"name" : "variable1",
					"value" : "value1"
				},
				{
					"name" : "variable2",
					"value" : 10
				},
				{
					"name" : "variable3",
					"value" : {
                        "variable3.1" : "value3.1",
                        "variable3.2" : 20
                    }
				}
			]
        }
    }
}

Annexes

Common Information

Events examples

Below is a set of events that will be transformed into alarms in the north API if the associated rule (eventReceived) is configured correctly.

New ad-hoc Alarms can be added
Table 44. Possible events
Name Description Variables

birthEvent

Alert Sent when device is turned on for first time

endLifeTimeEvent

Alert Sent when the device is close to finalize its hardware life

This event could be sent several times to notify the approaching to deadline

  • timeRemaining: Number. Seconds to reach end of life

statusEvent

Alert sent by the device periodically or when device changes its operational status

DMM Device Collection, Object. Mandatory next JSON objects:

  • hardware with operationalStatus (see Device Operational Status valid values)

  • location

  • temperature

  • cpuUsage

  • ram

  • volatilStorage

  • nonVolatilStorage

  • powerSupply

tamperingEvent

Alert sent by the device when a non allowed physical manipulation has been produced

  • reason: String describing the reason

temperatureEvent

Alert sent by the device when a predetermined threshold is overcome

  • temperature: Number

  • threshold: Number. Temperature threshold that has been overcome

  • trend: for example RISING, DECREASING, FLAT, UNKNOWN

batteryEvent

Alert sent by the device when a predetermined threshold is overcome

  • batteryLevel: Number

  • threshold: Number. Battery threshold that has been overcome

  • trend: for example RISING, DECREASING, FLAT, UNKNOWN

Other files like priority, severity could be fixed by the device with the values appropriated for each event, device or scenario. Example: EndOfLife severity depends on when the event was sent and how many time is remaining for the end of life of the hardware

Device Connection Scenarios

The OpenGate platform supports different device connection strategies:

  • Direct Connection Strategy: Most common scenario used by Endpoint or Gateway devices

opengate api common device connection scenarios direct
Figure 8. Direct Connection Scenario

  • Indirect Connection Strategy: Used in scenarios that monitorized devices are behind a device (called Gateway) or in most complex scenarios that implement non transparent Mesh Networks. To support this kind of scenarios the platform uses the concept of path that associated to the device Identifier (deviceId) allows to know which devices has to be traversed in order to reach the destination:

opengate api common device connection scenarios indirect
Figure 9. Indirect Connection Scenario

  • The Endpoint device in case of operations, diagnostics sent by the plaftorm

  • The Platform in case of events, responses, etc. sent by the Endpoint device

"path" parameter examples

Taking an indirect connection scenario we have:

  • A Gateway device with the id: "GatewayA"

  • An intermediate device connected to the Gateway with the id: "Device_1"

  • Two Endpoint devices connected to the intermediate device with the ids: "Device_1_1" and "Device_1_2" respectively.

From a platform point of view, the path, deviceId parameter values are:

  • To reach the Gateway:

    • "deviceId": "GatewayA"

    • "path": []

  • To reach the intermediate device:

    • "deviceId": "Device_1"

    • "path": ["GatewayA"]

  • To reach an endpoint device:

    • "deviceId": "Device_1_1"

    • "path": ["GatewayA", "Device_1"]

IoT Concepts

Based in the "bigdata" paradigm, the OpenGate platform allows collecting non structured information from devices (sensors, machines, etc.) using South API (connectors) using the datastream concept. Next figure shows the main concepts of the IoT API:

iot basics V8
Figure 10. IoT API basics

Understanding the usage of this API requires understand first the main resources involved. They are:

  • Device: Represents the physical element (communications devices, concentrators, machines, sensors, etc.) which information is being collected.

  • Feed: Represents the logical elements (users, multiple instances of the same datastream in a device, etc.) which information is being collected.

  • Datamodel: It defines all the variables associated to a device or type of entity for its management and monitoring. These variables are defined like datastreams template and they represent the information about an individual "measure" that evolves over time, that is, define the main features of a datastream, see DataStream Template.

To know all the necessary attributes of the datamodel, see Datamodel description

To know all datastreams that offers the OpenGate platform, see Default Datamodels

To find information about how to provision new datamodels See Datamodels Provision in the provision API

  • Datastream (Instance of Datastream): It is the current value of a datastream. Every datastream instance must have a unique (within the device) alphanumeric Identifier. If the name of the datastream instance matches with the datastream template name the instance inherits main features of the datamodel as units, period, tags, etc.

  • Datapoint: It represents a single value of a datastream at a specific point in time. See datapoint attribute to know all the necessary attributes. The instance of datastream will be a datapoint in the time.

The at attribute indicates when the measure was collected.

The set of datapoints is the historical data of the measure

Device Datamodel Concept

The device datamodel is formed by the set of parameters defined in one or several profiles.

The name or identifier of each parameter can have the character . to separate the different parts of the datamodel. Then the entire list can be viewed as a parameters tree. See following parameter list:

  • provision.device.administrativeState

  • provision.device.operationalStatus

  • provision.customerParameter

  • device.operationalStatus

  • health.heart.rate

Can be viewed as:

iot basics device datamodel concept

Understanding OpenGate IoT resources usage

To clearly understand usage of the concepts described above it is necessary to explain two differents IoT scenarios Smart metering scenario and eHealth scenario to know how resources can be used to support the requirements:

Smart metering scenario

This example describes a scenario involving two basic parameters that are collected periodically from a device:

  • energy consumption

  • power consumption

Basic use case

The simplest design is showed in the next figure:

iot basics smartmeter scenario basic

It will be implemented using:

  • Two datastreams of information

    • electricity.consumption

    • electricity.power

  • The device will be associated to the smart meter using as device identifier the unique number of the meter

  • Feed resource is not used because all measures can be collected and retrieved using device identifier only.

Enhanced use case

In a more realistic scenario the device meter can be changed (due to a maintenance issue or other) but the new measures need to be associated to the same measurement point.

iot basics smartmeter scenario enhanced

In this case it will be implemented using:

  • Two datastreams of information

    • electricity.consumption

    • electricity.power

  • The device will be associated to the smart meter using as device identifier the unique number of the meter

  • The feed resource is used to:

    • To identify the user

    • To group around it the measures of each datastream but taken from different devices as a same collection of datapoints

    • To group all the datastreams of the different sensor types

  • The measure-device association can be traced because for the collection of datapoints of a same datastream

eHealth scenario

This example describes a scenario involving two basic parameters that are collected periodically from a device:

  • Weight

  • Heart Rate

To be more realistic, the user can take the measures in different medical centres

iot basics ehealth scenario

In this case it will be implemented using:

  • Two datastreams of information

    • health.weight

    • health.heart.rate

  • The device will be associated to the different health sensors using as device identifier (serial number or other) the unique number of each device

  • The feed resource is used to:

    • To identify the user

    • To group around it the measures of each datastream but taken from different devices as a same collection of datapoints

    • To group all the datastreams of the different sensor types

  • The measure-device association can be traced because for the collection of datapoints of a same datastream to know from which device was recovered each measure

Datamodel Description

A datamodel is a set of datastream templates. The JSON format of a datamodel is:

Table 45. Datamodel object attributes
Attribute Mandatory Description

identifier

Yes

Datamodel Identifier. It must be unique.

organizationName

Yes

Name of the organization

name

Yes

Name of the datamodel

description

No

Description of the datamodel

version

Yes

Version of the datamodel

allowedResourceTypes[]

Yes

Array of resourceType allowed, see entities

categories[]

No

Set of categories that group the templates. If it does not exist a defined category, the list can be empty. See Datamodel Category Object
Table 46. Datamodel Category Object
Attribute Mandatory Description

identifier

Yes

Identifier of the category

name

No

Name of the category

datastreams[]

No

Set of templates grouped. If it does not exist a defined datastream in the category, the list can be empty. See IoT Datastream template Object

Datastream Template Description

Table 47. IoT Datastream: Template Object
Attribute Mandatory Description

identifier

Yes

Identifier of the template. It is unique by organization (not by datamodel). It can not start with device or provision.device. It can not contain the character "underline".

name

Yes

Name of the template

description

Yes

Description of the template

period

No

String enumeration, one of:

- PULSE

- CUMULATIVE

- INSTANT. This is the default value

access

No

Only used when you want to determinate if a datastream is writeable. The access field can take three values

- READ. This is the default value

- WRITE

- READ,WRITE

All the datastreams are by default read, I mean, all datastreams can be readen, the devices or third parties can send the value of a datastream and this value processed by the platform, read. But, If you want to send a datastream value to a specific device, e.g. you want to change the value of a specific configuration parameter in one device, you can do it with a set operation and only datastreams with access type WRITE can be part of a set operation, so if you want use datastreams for changing values in configuration parameters you have to set the access value to WRITE.

schema

Yes

Used for defining the format of the datastream value. It must have a correct jsonSchema format. See see schema object

storage

No

Only used when you want to determinate the time to life of the collected datastream values. See IoT Datastream Storage Object, The default value is the organization’s plan storage value.

unit

No

See unit object attributes

modifiable

No

Boolean value to indicate if it is modifiable this datastream. The default value is true

calculated

No

Boolean value to indicate if it is a datastream internally calculated by the platform. The default value is false

required

No

Boolean value to indicate if it is required for this datastream. The default value is false

qrating

No

Only used when you want to quantify the collected datapoints and datastreams. If it exists, it must be complete. See IoT Datastream Qrating Object

tags[]

No

Array of strings used to tag the datastream, 50 characters max. per tag

views

No

To be used in the future

icon

No

Used for asociate an icon in the web datastream visualitation, See IoT Datastream Icon Object.
Table 48. Unit object attributes
Attribute Description

type

String describing the type of unit you want

label

String with the label you want for your unit

symbol

String with the symbol you want for your unit

This fields are not mandatory and its default value is empty
Datamodel example
{
  "identifier": "health",
  "name": "health name",
  "description": "health description",
  "version": "1.2",
  "allowedResourceTypes":[
    "entity.device"
  ],
  "categories": [
    {
      "identifier": "heart",
      "name": "heart name",
      "datastreams": [
        {
          "identifier": "health.heart.rate",
		  "name": "health.heart.rate name",
		  "description": "health.heart.rate description",
		  "period": "INSTANT",
		  "schema": {
            "type": "string"
          },
          "unit": {
            "type": "SI",
            "label": "beats/second",
            "symbol": "bpm"
          },
          "access": "READ",
          "storage": {
            "period": "DAYS",
            "total": 30
          },
          "tags": [
            "health",
            "heart"
          ],
          "modifiable": true,
          "required": false
        }
      ]
    }
  ]
}

Datastream Schema field description

It allows to define a valid schema json. There are some predefined types than can be used.

Datastream Qrating field description

QRating ponders all the data streams giving more importance to some over others based on their results giving a more reliable picture of the value collected and device status.

QRating show for each data point / datastream based on the configuration provided for each datastream the next outputs:

  • Scoring

  • Performance

  • Data quality.

The set of all qRating parameters values allow calculate the overall performance of the device.

Table 49. Qrating object attributes
Attribute Mandatory Type Description

version

Yes

String

Version of the configurated Qrating

max_score

Yes

Number

Datastream weight within the datastream

ideal

Yes

Number

The best value that can be collected for the datastream

min_required

Yes

Number

Minimum value accepted by the datastream (indicates when a data point collected is critical below the ideal)

min_desired

Yes

Number

Datastream desired minimum value (the datapoint collected is not critical but is below the ideal)

max_desired

Yes

Number

Datastream desired maximum value (the datapoint collected is not critical but is above the ideal)

max_allowed

Yes

Number

Maximum value accepted by the datastream (indicates when a data point collected is critical above ideal)

conversion_matrix

No

Object

It only applies if the collected datapoints are text typed, give a number for each allowed text value for calculate the qRating. See Conversion Matrix object attributes

cumulative_period_divisor

No

Number, Seconds

Allows calculate the median velocity of collection against the previous value collected taking this parameter as divisor

It`s an array of value pairs

Table 50. Conversion Matrix object attributes
Attribute Value of the attribute

expected value

Value translated for the expected value
Datamodel example with typical number datastream qRating object
{
  "identifier": "datamodel",
  "name": "datamodel.health",
  "version": "1.2",
  "categories": [
    {
      "identifier": "category",
      "name": "heart",
      "datastreams": [
        {
          "schema": {
            "type": "string"
          },
          "identifier": "health.heart.rate",
          "period": "INSTANT",
          "unit": {
            "type": "SI",
            "label": "beats/second",
            "symbol": "bpm"
          },
          "access": "READ",
          "name": "health.heart.rate",
          "storage": {
            "period": "DAYS",
            "total": 30
          },
          "tags": [
            "health",
            "heart"
          ],
          "qrating": {
            "version": "1.0.0",
            "min_required": {
              "value": -5,
              "label": "FROZEN"
            },
            "min_desired": {
              "value": 5,
              "label": "COLD"
            },
            "ideal": {
              "value": 25,
              "label": "NORMAL/IDEAL"
            },
            "max_desired": {
              "value": 35,
              "label": "HIGH"
            },
            "max_allowed": {
              "value": 60,
              "label": "HOT"
            },
            "max_score": 1000,
            "conversion_matrix": {
              "FROZEN": -5,
              "COLD": 5,
              "NORMAL": 36,
              "IDEAL": 36,
              "HIGH": 38,
              "HOT": 40
            }
          },
          "modifiable": true,
          "required": false
        }
      ]
    }
  ]
}

Pay attention to the conversion matrix field, with this option when for example the datapoint collect a value of Frozen, the value is changed by -100 for allowing the qRating calculation.

Pay attention to the cumulative period divisor field, without this option you receive a calculation of the datastream qrating comparing the last collected datapoint with the last one. With this option, qrating algorithm considers this value as a period divisor calculating the increment or decreasing median speed of the datastream cumulative value. For example, if you collect a total connection value of 60 in 1 hour and previous value was 0, the qrating value calculated is the increment (final value): 1 per minute (60 seconds divisor configured).

Final value = (Difference since last datapoint * Time Divisor) / (Total time in seconds between datapoints)

Datastream Storage field description

This field is oriented to save just only the datastream’s datapoints collected since a specific period of time, allowing the platform for deleting automatically the older datapoints.

In other words, the time a data point will be stored into OpenGate depends on the conjunction of this complex field period plus total and the value of the date field of the data point.

Table 51. Storage object attributes
Attribute Description

period

Specify the units of time that OpenGate have to consider for deleting historical datapoints, the available values are:

- DAYS

- MONTHS

- YEARS

- NEVER, if you select this value, no one datapoint will be storaged, the information of the last one could be got in datastream’s search

total

Amount of period units for considering in the deleting process.

It is impossible to have total without period

If the period is NEVER, the total field is empty

The storage can not be greater than the one defined in the organization

Datastream Icon field description

This field is oriented to asociate an icon in the web datastream visualitation

Table 52. Storage object attributes
Attribute Description

class

Specify the class to represent icon’s name
Datamodel example with icon object
{
  "icon": {
    "class": "fas fa-hourglass-end"
  }
}

The name of the icon class is defined in https://fontawesome.com/icons?d=gallery

Default Datamodels

This chapter describes the default built-in OpenGate datamodels through which the platform can provide already impleented added value services

This approach doesn’t prevent if you need that you can use other template format to implement the same scenario. New templates can be added using the right provision API to create datastream templates.

CollectionAsset-8.0.0.0

Parameter Description

ProvisionAsset-8.0.0.0

Parameter Description

ProvisionDevice-8.0.0.0

Parameter Description

ProvisionGenericIdentifier-8.0.2.0

Parameter Description

Ticket-8.0.21.0

Parameter Description

CollectionDevice-8.0.0.0

Parameter Description

Bts-8.0.32.0

Parameter Description

CollectionSubscription-8.0.21.0

Parameter Description

CollectionChannel-8.0.2.0

Parameter Description

CollectionOrganization-8.0.2.0

Parameter Description

ProvisionChannel-8.0.2.0

Parameter Description

ProvisionGeneric-8.0.2.0

Parameter Description

ProvisionOrganization-8.0.1.0

Parameter Description

Human-8.0.21.0

Parameter Description

ProvisionGenericChannel-8.0.2.0

Parameter Description

ProvisionGenericOrganization-8.0.2.0

Parameter Description

ProvisionSubscriber-8.0.0.0

Parameter Description

ProvisionSubscription-8.0.21.0

Parameter Description

CollectionSubscriber-8.0.0.0

Parameter Description

Entity-8.0.0.0

Parameter Description

SIM Management Specific Datamodels

This chapter describes how different flavour sensor signals can be modelled using the OpenGate datastream concept.

AnalyticSimManagement-1.1

Parameter Description

CollectionSimManagement-1.1

Parameter Description

ProvisioSimManagement-1.4

Parameter Description

IoT Energy Datamodels (Not preloaded)

This chapter describes how different flavour sensor signals can be modelled using the OpenGate datastream concept.

You can use provision these datamodels in your organization using the righ API

Og Electricity-1.0

Parameter Description

Og Health-1.2

Parameter Description

Og Water-1.0

Parameter Description

Datamodel Basic Types

Type: address

Table 53. Attributes
Attribute Value

type

object

description
Type in JSON format
{
    "properties": {
        "apn": {
            "title": "APN",
            "type": "string"
        },
        "type": {
            "enum": [
                "IPV4",
                "IPV6",
                "MAC48",
                "UNKNOWN",
                "SIGFOX",
                "HOSTNAME"
            ],
            "javaEnumNames": [
                "IPV4",
                "IPV6",
                "MAC48",
                "UNKNOWN",
                "SIGFOX",
                "HOSTNAME"
            ],
            "title": "Type",
            "type": "string"
        },
        "value": {
            "description": "value of the parameter",
            "title": "Value",
            "type": "string"
        }
    },
    "public": true,
    "type": "object"
}

Type: administrativeState

Table 54. Attributes
Attribute Value

type

string

description

values

  • ACTIVE

  • BANNED

  • DELETED

  • INVALID

  • READY

  • REPAIR

  • REQUESTED

  • RETIRED

  • SUSPENDED

  • TESTED

  • TESTING

  • UNKNOWN
Type in JSON format
{
    "description": "",
    "enum": [
        "ACTIVE",
        "BANNED",
        "DELETED",
        "INVALID",
        "READY",
        "REPAIR",
        "REQUESTED",
        "RETIRED",
        "SUSPENDED",
        "TESTED",
        "TESTING",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "ACTIVE",
        "BANNED",
        "DELETED",
        "INVALID",
        "READY",
        "REPAIR",
        "REQUESTED",
        "RETIRED",
        "SUSPENDED",
        "TESTED",
        "TESTING",
        "UNKNOWN"
    ],
    "title": "Administrative State",
    "type": "string"
}

Type: antennaStatus

Table 55. Attributes
Attribute Value

type

string

description

values

  • NORMAL

  • OPEN

  • SHORT_CIRCUIT

  • UNKNOWN
Type in JSON format
{
    "enum": [
        "NORMAL",
        "OPEN",
        "SHORT_CIRCUIT",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "NORMAL",
        "OPEN",
        "SHORT_CIRCUIT",
        "UNKNOWN"
    ],
    "type": "string"
}

Type: area

Table 56. Attributes
Attribute Value

type

object

description
Type in JSON format
{
    "properties": {
        "description": {
            "type": "string"
        },
        "identifier": {
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "order": {
            "type": "integer"
        }
    },
    "type": "object"
}

Type: areas

Table 57. Attributes
Attribute Value

type

array

description
Type in JSON format
{
    "items": {
        "$ref": "#/definitions/area"
    },
    "type": "array"
}

Type: arrayIdentifier

Table 58. Attributes
Attribute Value

type

array

description
Type in JSON format
{
    "items": {
        "$ref": "#/definitions/ogIdentifier"
    },
    "type": "array"
}

Type: arrayString

Table 59. Attributes
Attribute Value

type

array

description
Type in JSON format
{
    "items": {
        "type": "string"
    },
    "type": "array"
}

Type: assetAdministrativeState

Table 60. Attributes
Attribute Value

type

string

description

values

  • BANNED

  • DELETED

  • IN_MAINTENANCE

  • IN_STOCK

  • IN_TRANSIT

  • IN_USE

  • MISSING

  • ORDERED

  • READY

  • RETIRED
Type in JSON format
{
    "description": "",
    "enum": [
        "BANNED",
        "DELETED",
        "IN_MAINTENANCE",
        "IN_STOCK",
        "IN_TRANSIT",
        "IN_USE",
        "MISSING",
        "ORDERED",
        "READY",
        "RETIRED"
    ],
    "javaEnumNames": [
        "BANNED",
        "DELETED",
        "IN_MAINTENANCE",
        "IN_STOCK",
        "IN_TRANSIT",
        "IN_USE",
        "MISSING",
        "ORDERED",
        "READY",
        "RETIRED"
    ],
    "title": "Asset Administrative State",
    "type": "string"
}

Type: assetSpecificType

Table 61. Attributes
Attribute Value

type

string

description

values

  • BOX

  • BUILDING

  • CONTROL_HOUSE

  • CRANE

  • FOUNTAIN

  • ENGINE

  • HOUSE

  • MACHINE

  • OTHER

  • PALLET

  • PIPELINE

  • SPOOL

  • TOWER

  • VEHICLE

  • WIRE

  • WORKER

  • SUPPLY_POINT

  • CONTRACTOR

  • ORGANIZATION

  • OPERATOR

  • CHANNEL

  • ZONE

  • PROVINCE

  • BTS

  • POSTAL_CODE
Type in JSON format
{
    "enum": [
        "BOX",
        "BUILDING",
        "CONTROL_HOUSE",
        "CRANE",
        "FOUNTAIN",
        "ENGINE",
        "HOUSE",
        "MACHINE",
        "OTHER",
        "PALLET",
        "PIPELINE",
        "SPOOL",
        "TOWER",
        "VEHICLE",
        "WIRE",
        "WORKER",
        "SUPPLY_POINT",
        "CONTRACTOR",
        "ORGANIZATION",
        "OPERATOR",
        "CHANNEL",
        "ZONE",
        "PROVINCE",
        "BTS",
        "POSTAL_CODE"
    ],
    "javaEnumNames": [
        "BOX",
        "BUILDING",
        "CONTROL_HOUSE",
        "CRANE",
        "FOUNTAIN",
        "ENGINE",
        "HOUSE",
        "MACHINE",
        "OTHER",
        "PALLET",
        "PIPELINE",
        "SPOOL",
        "TOWER",
        "VEHICLE",
        "WIRE",
        "WORKER",
        "SUPPLY_POINT",
        "CONTRACTOR",
        "ORGANIZATION",
        "OPERATOR",
        "CHANNEL",
        "ZONE",
        "PROVINCE",
        "BTS",
        "POSTAL_CODE"
    ],
    "type": "string"
}

Type: batteryStatus

Table 62. Attributes
Attribute Value

type

string

description

values

  • CHARGING

  • CHARGED

  • UNPLUGGED

  • ERROR

  • UNKNOWN
Type in JSON format
{
    "enum": [
        "CHARGING",
        "CHARGED",
        "UNPLUGGED",
        "ERROR",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "CHARGING",
        "CHARGED",
        "UNPLUGGED",
        "ERROR",
        "UNKNOWN"
    ],
    "type": "string"
}

Type: certificateList

Table 63. Attributes
Attribute Value

type

array

description
Type in JSON format
{
    "items": {
        "type": "string"
    },
    "type": "array"
}

Type: clock

Table 64. Attributes
Attribute Value

type

object

description
Type in JSON format
{
    "description": "",
    "properties": {
        "datetime": {
            "$ref": "#/definitions/timestamp"
        },
        "dst": {
            "properties": {
                "begin": {
                    "$ref": "#/definitions/timestamp"
                },
                "deviation": {
                    "type": "number"
                },
                "enabled": {
                    "type": "boolean"
                },
                "end": {
                    "$ref": "#/definitions/timestamp"
                }
            },
            "type": "object"
        },
        "timezone": {
            "type": "number"
        }
    },
    "public": true,
    "title": "Clock",
    "type": "object"
}

Type: commsModuleOperationalStatus

Table 65. Attributes
Attribute Value

type

string

description

values

  • STOPPED

  • STOPPING

  • STARTING

  • RUNNING

  • DISABLED

  • ERROR
Type in JSON format
{
    "description": "",
    "enum": [
        "STOPPED",
        "STOPPING",
        "STARTING",
        "RUNNING",
        "DISABLED",
        "ERROR"
    ],
    "javaEnumNames": [
        "STOPPED",
        "STOPPING",
        "STARTING",
        "RUNNING",
        "DISABLED",
        "ERROR"
    ],
    "title": "Operational Status",
    "type": "string"
}

Type: commsModuleSpecificType

Table 66. Attributes
Attribute Value

type

string

description

values

  • ADSL

  • CAN

  • ETH

  • GENERIC

  • GSM

  • HAN

  • I2C

  • LOWPAN

  • MESH

  • MOBILE

  • MULTIMOBILE

  • PLC

  • RS232

  • RS422

  • RS485

  • SIGFOX

  • UMTS

  • WIFI

  • ZIGBEE

  • ZWAVE

  • NARROWBAND

  • LTE_M
Type in JSON format
{
    "enum": [
        "ADSL",
        "CAN",
        "ETH",
        "GENERIC",
        "GSM",
        "HAN",
        "I2C",
        "LOWPAN",
        "MESH",
        "MOBILE",
        "MULTIMOBILE",
        "PLC",
        "RS232",
        "RS422",
        "RS485",
        "SIGFOX",
        "UMTS",
        "WIFI",
        "ZIGBEE",
        "ZWAVE",
        "NARROWBAND",
        "LTE_M"
    ],
    "javaEnumNames": [
        "ADSL",
        "CAN",
        "ETH",
        "GENERIC",
        "GSM",
        "HAN",
        "I2C",
        "LOWPAN",
        "MESH",
        "MOBILE",
        "MULTIMOBILE",
        "PLC",
        "RS232",
        "RS422",
        "RS485",
        "SIGFOX",
        "UMTS",
        "WIFI",
        "ZIGBEE",
        "ZWAVE",
        "NARROWBAND",
        "LTE_M"
    ],
    "type": "string"
}

Type: coordinates

Table 67. Attributes
Attribute Value

type

array

description

A geographical coordinates
Type in JSON format
{
    "description": "A geographical coordinates",
    "items": {
        "type": "number"
    },
    "maxItems": 2,
    "public": true,
    "type": "array"
}

Type: cpuStatus

Table 68. Attributes
Attribute Value

type

string

description

values

  • IDLE

  • IDLE/WORKING

  • WORKING

  • STRESSED

  • OVERLOAD
Type in JSON format
{
    "enum": [
        "IDLE",
        "IDLE/WORKING",
        "WORKING",
        "STRESSED",
        "OVERLOAD"
    ],
    "javaEnumNames": [
        "IDLE",
        "IDLE_WORKING",
        "WORKING",
        "STRESSED",
        "OVERLOAD"
    ],
    "type": "string"
}

Type: datamodelParamName

Table 69. Attributes
Attribute Value

type

string

description

Id of the parameter
Type in JSON format
{
    "description": "Id of the parameter",
    "title": "Id",
    "type": "string"
}

Type: datamodelParamNameValue

Table 70. Attributes
Attribute Value

type

object

description
Type in JSON format
{
    "properties": {
        "name": {
            "$ref": "#/definitions/datamodelParamName"
        },
        "value": {
            "description": "Value of the parameter",
            "title": "Value",
            "type": "string"
        }
    },
    "required": [
        "name",
        "value"
    ],
    "type": "object"
}

Type: datamodelResponse

Table 71. Attributes
Attribute Value

type

object

description
Type in JSON format
{
    "properties": {
        "name": {
            "description": "Id of the parameter",
            "title": "Id",
            "type": "string"
        },
        "resultCode": {
            "$ref": "#/definitions/datamodelResultCode"
        },
        "resultDescription": {
            "description": "Result description of Get Operation",
            "title": "Result Description",
            "type": "string"
        },
        "value": {
            "description": "value of the parameter",
            "title": "type",
            "type": "string"
        }
    },
    "required": [
        "name",
        "value"
    ],
    "type": "object"
}

Type: datamodelResultCode

Table 72. Attributes
Attribute Value

type

string

description

Result code of Get Operation

values

  • SUCCESS

  • PARAM_NOT_SUPPORTED

  • INVALID_FORMAT

  • WRONG_VALUE

  • UNKNOWN
Type in JSON format
{
    "description": "Result code of Get Operation",
    "enum": [
        "SUCCESS",
        "PARAM_NOT_SUPPORTED",
        "INVALID_FORMAT",
        "WRONG_VALUE",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "SUCCESS",
        "PARAM_NOT_SUPPORTED",
        "INVALID_FORMAT",
        "WRONG_VALUE",
        "UNKNOWN"
    ],
    "title": "Result Code",
    "type": "string"
}

Type: date

Table 73. Attributes
Attribute Value

type

string

description

date in ISO 8601
Type in JSON format
{
    "description": "date in ISO 8601",
    "format": "date",
    "pattern": "^([0-9]{4})-?(1[0-2]|0[1-9])-?(3[01]|0[1-9]|[12][0-9])$",
    "public": true,
    "title": "date",
    "type": "string"
}

Type: datetime

Table 74. Attributes
Attribute Value

type

object

description
Type in JSON format
{
    "properties": {
        "date": {
            "$ref": "#/definitions/date"
        },
        "dst": {
            "$ref": "#/definitions/dst"
        },
        "time": {
            "description": "time in ISO 8601",
            "format": "time",
            "pattern": "^(2[0-3]|[01][0-9]):?([0-5][0-9]):?([0-5][0-9])$",
            "title": "time",
            "type": "string"
        },
        "timezone": {
            "$ref": "#/definitions/timezone"
        }
    },
    "required": [
        "date",
        "time",
        "timezone",
        "dst"
    ],
    "type": "object"
}

Type: deviceOperationalStatus

Table 75. Attributes
Attribute Value

type

string

description

values

  • NORMAL

  • SAFE_MODE

  • TAMPER

  • TEST

  • DOWN

  • ALARM

  • UNKNOWN
Type in JSON format
{
    "description": "",
    "enum": [
        "NORMAL",
        "SAFE_MODE",
        "TAMPER",
        "TEST",
        "DOWN",
        "ALARM",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "NORMAL",
        "SAFE_MODE",
        "TAMPER",
        "TEST",
        "DOWN",
        "ALARM",
        "UNKNOWN"
    ],
    "title": "Operational Status",
    "type": "string"
}

Type: deviceSpecificType

Table 76. Attributes
Attribute Value

type

string

description

values

  • BLOODPRESSURE_SENSOR

  • COMHUB

  • CONCENTRATOR

  • CONTAINER

  • COORDINATOR

  • GATEWAY

  • GENERIC

  • GLUCOMETER_SENSOR

  • METER

  • MODEM

  • ROUTER

  • SENSOR

  • TPV

  • VEHICLE

  • VENDING

  • WEIGHT_SENSOR
Type in JSON format
{
    "enum": [
        "BLOODPRESSURE_SENSOR",
        "COMHUB",
        "CONCENTRATOR",
        "CONTAINER",
        "COORDINATOR",
        "GATEWAY",
        "GENERIC",
        "GLUCOMETER_SENSOR",
        "METER",
        "MODEM",
        "ROUTER",
        "SENSOR",
        "TPV",
        "VEHICLE",
        "VENDING",
        "WEIGHT_SENSOR"
    ],
    "javaEnumNames": [
        "BLOODPRESSURE_SENSOR",
        "COMHUB",
        "CONCENTRATOR",
        "CONTAINER",
        "COORDINATOR",
        "GATEWAY",
        "GENERIC",
        "GLUCOMETER_SENSOR",
        "METER",
        "MODEM",
        "ROUTER",
        "SENSOR",
        "TPV",
        "VEHICLE",
        "VENDING",
        "WEIGHT_SENSOR"
    ],
    "type": "string"
}

Type: dst

Table 77. Attributes
Attribute Value

type

integer

description
Type in JSON format
{
    "default": 0,
    "minimum": 0,
    "title": "DST",
    "type": "integer"
}

Type: entityType

Table 78. Attributes
Attribute Value

type

string

description

values

  • GATEWAY

  • ASSET

  • COMMUNICATIONS_MODULE

  • SUBSCRIPTION

  • SUBSCRIBER
Type in JSON format
{
    "description": "",
    "enum": [
        "GATEWAY",
        "ASSET",
        "COMMUNICATIONS_MODULE",
        "SUBSCRIPTION",
        "SUBSCRIBER"
    ],
    "javaEnumNames": [
        "GATEWAY",
        "ASSET",
        "COMMUNICATIONS_MODULE",
        "SUBSCRIPTION",
        "SUBSCRIBER"
    ],
    "title": "Entity Type",
    "type": "string"
}

Type: ipStatus

Table 79. Attributes
Attribute Value

type

string

description

values

  • OK

  • NOK
Type in JSON format
{
    "description": "",
    "enum": [
        "OK",
        "NOK"
    ],
    "javaEnumNames": [
        "OK",
        "NOK"
    ],
    "title": "IP Reachability Status",
    "type": "string"
}

Type: ipv4

Table 80. Attributes
Attribute Value

type

string

description

IPV4 format
Type in JSON format
{
    "description": "IPV4 format",
    "format": "ipv4",
    "pattern": "((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])",
    "public": true,
    "title": "ipv4",
    "type": "string"
}

Type: ipv6

Table 81. Attributes
Attribute Value

type

string

description

IPV6 format
Type in JSON format
{
    "description": "IPV6 format",
    "format": "ipv6",
    "pattern": "(([0-9a-fA-F]{1,4}:){7,7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|fe80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}|::(ffff(:0{1,4}){0,1}:){0,1}((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9])\\.){3,3}(25[0-5]|(2[0-4]|1{0,1}[0-9]){0,1}[0-9]))",
    "public": true,
    "title": "ipv6",
    "type": "string"
}

Type: location

Table 82. Attributes
Attribute Value

type

object

description

A geojson enriched for OpenGate
Type in JSON format
{
    "description": "A geojson enriched for OpenGate",
    "properties": {
        "accuracy": {
            "description": "position accuracy in meters",
            "type": "number"
        },
        "address": {
            "type": "string"
        },
        "country": {
            "type": "string"
        },
        "position": {
            "description": "compatible with geojson format",
            "properties": {
                "coordinates": {
                    "additionalItems": false,
                    "description": "Format [longitude, latitude]",
                    "items": {
                        "type": "number"
                    },
                    "minItems": 2,
                    "type": "array"
                },
                "type": {
                    "default": "Point",
                    "type": "string"
                }
            },
            "required": [
                "coordinates"
            ],
            "type": "object"
        },
        "postal": {
            "type": "string"
        },
        "province": {
            "type": "string"
        },
        "region": {
            "type": "string"
        },
        "source": {
            "enum": [
                "MOBILE",
                "GPS",
                "GLONASS",
                "RTK",
                "RFID",
                "WIFI",
                "ZIGBEE",
                "LORA",
                "SIGFOX-BASIC",
                "SIGFOX-SPOTIT",
                "UNKNOWN"
            ],
            "javaEnumNames": [
                "MOBILE",
                "GPS",
                "GLONASS",
                "RTK",
                "RFID",
                "WIFI",
                "ZIGBEE",
                "LORA",
                "SIGFOX_BASIC",
                "SIGFOX_SPOTIT",
                "UNKNOWN"
            ],
            "type": "string"
        },
        "town": {
            "type": "string"
        },
        "zoom": {
            "description": "zoom for the web map",
            "type": "number"
        }
    },
    "public": true,
    "type": "object"
}

Type: mac48

Table 83. Attributes
Attribute Value

type

string

description

MAC48 format
Type in JSON format
{
    "description": "MAC48 format",
    "pattern": "(([0-9A-Fa-f]{2}[-:]){5}[0-9A-Fa-f]{2})|(([0-9A-Fa-f]{4}){2}[0-9A-Fa-f]{4})",
    "public": true,
    "title": "mac48",
    "type": "string"
}

Type: model

Table 84. Attributes
Attribute Value

type

object

description
Type in JSON format
{
    "description": "",
    "properties": {
        "manufacturer": {
            "type": "string"
        },
        "manufacturerOUI": {
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "version": {
            "type": "string"
        }
    },
    "public": true,
    "title": "Model",
    "type": "object"
}

Type: msisdn

Table 85. Attributes
Attribute Value

type

string

description
Type in JSON format
{
    "maxLength": 15,
    "minLength": 7,
    "public": true,
    "type": "string"
}

Type: ogIdentifier

Table 86. Attributes
Attribute Value

type

string

description
Type in JSON format
{
    "pattern": "^[a-zA-Z0-9_@.-]*$",
    "public": true,
    "type": "string"
}

Type: ogIdentifierUnreferenced

Table 87. Attributes
Attribute Value

type

string

description
Type in JSON format
{
    "pattern": "^[a-zA-Z0-9_@.-]*$",
    "public": true,
    "type": "string"
}

Type: ogImage

Table 88. Attributes
Attribute Value

type

string

description
Type in JSON format
{
    "type": "string"
}

Type: outage

Table 89. Attributes
Attribute Value

type

object

description
Type in JSON format
{
    "properties": {
        "duration": {
            "type": "number"
        },
        "started": {
            "$ref": "#/definitions/timestamp"
        }
    },
    "type": "object"
}

Type: percentage

Table 90. Attributes
Attribute Value

type

number

description
Type in JSON format
{
    "maximum": 100,
    "minimum": 0,
    "public": true,
    "type": "number"
}

Type: powerSupplySource

Table 91. Attributes
Attribute Value

type

string

description

values

  • BATTERY

  • DIESEL_GENERATOR

  • NETWORK_PLUGGED

  • SOLAR

  • OTHER
Type in JSON format
{
    "enum": [
        "BATTERY",
        "DIESEL_GENERATOR",
        "NETWORK_PLUGGED",
        "SOLAR",
        "OTHER"
    ],
    "javaEnumNames": [
        "BATTERY",
        "DIESEL_GENERATOR",
        "NETWORK_PLUGGED",
        "SOLAR",
        "OTHER"
    ],
    "type": "string"
}

Type: powerSupplyStatus

Table 92. Attributes
Attribute Value

type

string

description

values

  • PLUGGED_CHARGING

  • PLUGGED_CHARGED

  • OUTAGE

  • UNPLUGGED

  • UNKNOWN
Type in JSON format
{
    "enum": [
        "PLUGGED_CHARGING",
        "PLUGGED_CHARGED",
        "OUTAGE",
        "UNPLUGGED",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "PLUGGED_CHARGING",
        "PLUGGED_CHARGED",
        "OUTAGE",
        "UNPLUGGED",
        "UNKNOWN"
    ],
    "type": "string"
}

Type: presenceGprs

Table 93. Attributes
Attribute Value

type

string

description

values

  • START

  • STOP

  • INTERIM_UPDATE

  • ON

  • OFF

  • NOK
Type in JSON format
{
    "enum": [
        "START",
        "STOP",
        "INTERIM_UPDATE",
        "ON",
        "OFF",
        "NOK"
    ],
    "javaEnumNames": [
        "START",
        "STOP",
        "INTERIM_UPDATE",
        "ON",
        "OFF",
        "NOK"
    ],
    "type": "string"
}

Type: presenceGsm

Table 94. Attributes
Attribute Value

type

string

description

values

  • OK

  • NOK

  • UNCONFIG

  • UNKNOWN
Type in JSON format
{
    "enum": [
        "OK",
        "NOK",
        "UNCONFIG",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "OK",
        "NOK",
        "UNCONFIG",
        "UNKNOWN"
    ],
    "type": "string"
}

Type: presenceIp

Table 95. Attributes
Attribute Value

type

string

description

values

  • OK

  • NOK
Type in JSON format
{
    "enum": [
        "OK",
        "NOK"
    ],
    "javaEnumNames": [
        "OK",
        "NOK"
    ],
    "type": "string"
}

Type: signalQualityStatus

Table 96. Attributes
Attribute Value

type

string

description

values

  • LOW_CRITICAL

  • LOW_WARNING

  • NORMAL

  • EXCELENT
Type in JSON format
{
    "enum": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "EXCELENT"
    ],
    "javaEnumNames": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "EXCELENT"
    ],
    "type": "string"
}

Type: signalStrengthStatus

Table 97. Attributes
Attribute Value

type

string

description

values

  • LOW_CRITICAL

  • LOW_WARNING

  • NORMAL

  • EXCELENT
Type in JSON format
{
    "enum": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "EXCELENT"
    ],
    "javaEnumNames": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "EXCELENT"
    ],
    "type": "string"
}

Type: software

Table 98. Attributes
Attribute Value

type

object

description
Type in JSON format
{
    "description": "",
    "properties": {
        "name": {
            "type": "string"
        },
        "type": {
            "enum": [
                "SOFTWARE",
                "FIRMWARE"
            ],
            "javaEnumNames": [
                "SOFTWARE",
                "FIRMWARE"
            ],
            "type": "string"
        },
        "version": {
            "type": "string"
        }
    },
    "public": true,
    "title": "Software",
    "type": "object"
}

Type: softwareList

Table 99. Attributes
Attribute Value

type

array

description
Type in JSON format
{
    "items": {
        "$ref": "#/definitions/software"
    },
    "type": "array"
}

Type: subscriberSpecificType

Table 100. Attributes
Attribute Value

type

string

description

values

  • ADSL

  • CAN

  • ETH

  • GENERIC

  • GSM

  • HAN

  • I2C

  • LOWPAN

  • MESH

  • MOBILE

  • PLC

  • RS232

  • RS422

  • RS485

  • SIM

  • UMTS

  • WIFI

  • ZIGBEE

  • ZWAVE

  • NARROWBAND

  • LTE_M
Type in JSON format
{
    "enum": [
        "ADSL",
        "CAN",
        "ETH",
        "GENERIC",
        "GSM",
        "HAN",
        "I2C",
        "LOWPAN",
        "MESH",
        "MOBILE",
        "PLC",
        "RS232",
        "RS422",
        "RS485",
        "SIM",
        "UMTS",
        "WIFI",
        "ZIGBEE",
        "ZWAVE",
        "NARROWBAND",
        "LTE_M"
    ],
    "javaEnumNames": [
        "ADSL",
        "CAN",
        "ETH",
        "GENERIC",
        "GSM",
        "HAN",
        "I2C",
        "LOWPAN",
        "MESH",
        "MOBILE",
        "PLC",
        "RS232",
        "RS422",
        "RS485",
        "SIM",
        "UMTS",
        "WIFI",
        "ZIGBEE",
        "ZWAVE",
        "NARROWBAND",
        "LTE_M"
    ],
    "type": "string"
}

Type: subscriptionSpecificType

Table 101. Attributes
Attribute Value

type

string

description

values

  • ADSL

  • CAN

  • ETH

  • GENERIC

  • GSM

  • HAN

  • I2C

  • LOWPAN

  • MESH

  • MOBILE

  • PLC

  • RS232

  • RS422

  • RS485

  • SIGFOX

  • UMTS

  • WIFI

  • ZIGBEE

  • ZWAVE

  • NARROWBAND

  • LTE_M
Type in JSON format
{
    "enum": [
        "ADSL",
        "CAN",
        "ETH",
        "GENERIC",
        "GSM",
        "HAN",
        "I2C",
        "LOWPAN",
        "MESH",
        "MOBILE",
        "PLC",
        "RS232",
        "RS422",
        "RS485",
        "SIGFOX",
        "UMTS",
        "WIFI",
        "ZIGBEE",
        "ZWAVE",
        "NARROWBAND",
        "LTE_M"
    ],
    "javaEnumNames": [
        "ADSL",
        "CAN",
        "ETH",
        "GENERIC",
        "GSM",
        "HAN",
        "I2C",
        "LOWPAN",
        "MESH",
        "MOBILE",
        "PLC",
        "RS232",
        "RS422",
        "RS485",
        "SIGFOX",
        "UMTS",
        "WIFI",
        "ZIGBEE",
        "ZWAVE",
        "NARROWBAND",
        "LTE_M"
    ],
    "type": "string"
}

Type: temperatureStatus

Table 102. Attributes
Attribute Value

type

string

description

values

  • LOW_CRITICAL

  • LOW_WARNING

  • NORMAL

  • HIGH_WARNING

  • HIGH_CRITICAL
Type in JSON format
{
    "enum": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "HIGH_WARNING",
        "HIGH_CRITICAL"
    ],
    "javaEnumNames": [
        "LOW_CRITICAL",
        "LOW_WARNING",
        "NORMAL",
        "HIGH_WARNING",
        "HIGH_CRITICAL"
    ],
    "type": "string"
}

Type: text

Table 103. Attributes
Attribute Value

type

string

description
Type in JSON format
{
    "type": "string"
}

Type: ticketIdentifier

Table 104. Attributes
Attribute Value

type

string

description
Type in JSON format
{
    "pattern": "^[a-zA-Z0-9_@.-]*$",
    "public": true,
    "type": "string"
}

Type: ticketPriority

Table 105. Attributes
Attribute Value

type

string

description

values

  • MAJOR

  • MINOR

  • CRITICAL

  • BLOCKER
Type in JSON format
{
    "enum": [
        "MAJOR",
        "MINOR",
        "CRITICAL",
        "BLOCKER"
    ],
    "javaEnumNames": [
        "MAJOR",
        "MINOR",
        "CRITICAL",
        "BLOCKER"
    ],
    "title": "Priority",
    "type": "string"
}

Type: ticketSeverity

Table 106. Attributes
Attribute Value

type

string

description

values

  • CRITICAL

  • URGENT

  • WARNING

  • NORMAL
Type in JSON format
{
    "enum": [
        "CRITICAL",
        "URGENT",
        "WARNING",
        "NORMAL"
    ],
    "javaEnumNames": [
        "CRITICAL",
        "URGENT",
        "WARNING",
        "NORMAL"
    ],
    "title": "Severity",
    "type": "string"
}

Type: ticketSpecificType

Table 107. Attributes
Attribute Value

type

string

description

values

  • WORKORDER

  • INCIDENT

  • REQUEST

  • FORM
Type in JSON format
{
    "enum": [
        "WORKORDER",
        "INCIDENT",
        "REQUEST",
        "FORM"
    ],
    "javaEnumNames": [
        "WORKORDER",
        "INCIDENT",
        "REQUEST",
        "FORM"
    ],
    "title": "Specific Type",
    "type": "string"
}

Type: ticketStatus

Table 108. Attributes
Attribute Value

type

string

description

values

  • CREATED

  • ASSIGNED

  • ANSWERED

  • RESTORED

  • RESOLVED

  • CLOSED
Type in JSON format
{
    "enum": [
        "CREATED",
        "ASSIGNED",
        "ANSWERED",
        "RESTORED",
        "RESOLVED",
        "CLOSED"
    ],
    "javaEnumNames": [
        "CREATED",
        "ASSIGNED",
        "ANSWERED",
        "RESTORED",
        "RESOLVED",
        "CLOSED"
    ],
    "title": "Status",
    "type": "string"
}

Type: ticketType

Table 109. Attributes
Attribute Value

type

string

description

values

  • INSTALLATION

  • TEST

  • TECHNICAL_TASK

  • UNINSTALLATION

  • MODIFICATION

  • BALANCES_AT_MT_TELEMEDIDA
Type in JSON format
{
    "enum": [
        "INSTALLATION",
        "TEST",
        "TECHNICAL_TASK",
        "UNINSTALLATION",
        "MODIFICATION",
        "BALANCES_AT_MT_TELEMEDIDA"
    ],
    "javaEnumNames": [
        "INSTALLATION",
        "TEST",
        "TECHNICAL_TASK",
        "UNINSTALLATION",
        "MODIFICATION",
        "BALANCES_AT_MT_TELEMEDIDA"
    ],
    "title": "Type",
    "type": "string"
}

Type: time

Table 110. Attributes
Attribute Value

type

string

description

time in ISO 8601
Type in JSON format
{
    "description": "time in ISO 8601",
    "format": "time",
    "pattern": "^(2[0-3]|[01][0-9]):?([0-5][0-9]):?([0-5][0-9])(\\.([0-9]{3}))?([Z]|(\\+|-)(2[0-3]|[01][0-9]):?([0-5][0-9]))$",
    "public": true,
    "title": "time",
    "type": "string"
}

Type: timestamp

Table 111. Attributes
Attribute Value

type

string

description

date & time in ISO 8601
Type in JSON format
{
    "description": "date & time in ISO 8601",
    "format": "date-time",
    "pattern": "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):?([0-5][0-9]):?([0-5][0-9])(\\.([0-9]{1,3}))?([Z]|(\\+|-)(2[0-3]|[01][0-9]):?([0-5][0-9]))$",
    "public": true,
    "title": "timestamp",
    "type": "string"
}

Type: timezone

Table 112. Attributes
Attribute Value

type

string

description
Type in JSON format
{
    "title": "timezone",
    "type": "string"
}

Type: topologyPath

Table 113. Attributes
Attribute Value

type

array

description
Type in JSON format
{
    "items": {
        "type": "string"
    },
    "type": "array"
}

Type: trafficSession

Table 114. Attributes
Attribute Value

type

object

description
Type in JSON format
{
    "properties": {
        "address": {
            "$ref": "#/definitions/address"
        },
        "duration": {
            "type": "number"
        },
        "id": {
            "type": "string"
        },
        "nasIp": {
            "$ref": "#/definitions/address"
        },
        "radiusClientIp": {
            "$ref": "#/definitions/address"
        },
        "receivedBytes": {
            "type": "number"
        },
        "receivedPackets": {
            "type": "number"
        },
        "sentBytes": {
            "type": "number"
        },
        "sentPackets": {
            "type": "number"
        },
        "status": {
            "enum": [
                "TERMINATED",
                "IN_PROGRESS",
                "UNKNOWN"
            ],
            "javaEnumNames": [
                "TERMINATED",
                "IN_PROGRESS",
                "UNKNOWN"
            ],
            "type": "string"
        },
        "terminateCause": {
            "type": "string"
        }
    },
    "public": true,
    "type": "object"
}

Type: unifiedPresence

Table 115. Attributes
Attribute Value

type

string

description

values

  • IP

  • GPRS

  • GSM

  • NOT_REGISTERED

  • UNKNOWN
Type in JSON format
{
    "enum": [
        "IP",
        "GPRS",
        "GSM",
        "NOT_REGISTERED",
        "UNKNOWN"
    ],
    "javaEnumNames": [
        "IP",
        "GPRS",
        "GSM",
        "NOT_REGISTERED",
        "UNKNOWN"
    ],
    "type": "string"
}

Administrative Status Enumeration

Table 116. Administrative State attribute values
State Description

REQUESTED

Entity requested to the supplier

READY

Entity ready for installation

REPAIR

Entity under repair

TESTING

Entity in tests

ACTIVE

Field deployed entity

SUSPENDED

Suspended its operation

DELETED

Entity removed from available stock

RETIRED

Field entity withdrawal

BANNED

Entity banned, It means that received information of this entity is not going to be collected

For the BANNED administrative state there is a default alarm (See Rules Catalog, this alarm is launched when an event is collected with information of this entity. On the other hand you can program job or task over entities whit banned administrative state

Operational Status Enumeration

Table 117. Device Operational Status
Name Description

UNKNOWN

Not known

NORMAL

Normal Operation

ALARM

The device has active alarms

DOWN

The device is not operative. Could be running but it is not performing its operation

SAFE_MODE

The device is in Safe Mode (Sleeping, etc.)

TAMPER

The device was tampered

TEST

The device is working in test mode
Table 118. Communications Modules Operational Status
Name Description

UNKNOWN

Not known

STOPPED

The module is not working

STARTING

The module is booting

RUNNING

The module is working

STOPPING

The is shutting down

ERROR

The module has an error

Common Objects Definition

Table 119. Subscription Object attributes
Attribute Description

type

String Identifying the type of address

value

String. Address associated to the subscription

apn

String. Access Point Name used to establish mobile data session
Table 120. Dimensions object
attribute Description

width

number

heigth

number

Fields Definition

This section describes how fields can be defined. It is used in several JSON objects of the platform like Operations Catalog, Device Datamodels, IoT Datastream templates, etc.

Next tables describes the different elements of this definition.

Table 121. type & subtype definition available values
Type Subtype Description

string

  • text

  • password

Text based value

boolean

Boolean based value. Exmaples: true or false

calendar

  • datetime

  • date

  • time

Format is described in the ISO 8601 or in http://www.w3.org/TR/NOTE-datetime. Examples: * datetime: "1997-07-16T19:20:30+01:00" * date: "1997-07-16" * time: "19:20:30+01:00"

address

  • ip

  • ipv4

  • ipv6

  • mac48

Network address value

number

  • integer

  • float

  • percentage

Numeric value

enumeration

  • string

  • number

Choice list values

array

  • string

  • number

Array of values

coordinates

  • geo

  • geotime

  • geojson

Object indicating coordinates and timestamp in geotime subtype. Example:

geo ([<longitude>,<latitude>])
[-3.700345, 40.416691]
geotime
{
  "timestamp": "1997-07-16T19:20:30+01:00",
  "latitude": 40.416691,
  "longitude": -3.700345
}
geojson (described in the RFC 7946. Visit https://tools.ietf.org/html/rfc7946)
{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [-3.700345, 40.416691]
  },
  "properties": {
    "name": "Madrid-Spain"
  }
}

topology

  • path

  • tree (not supported yet)

Object indicating relations. See following examples

path
[ "granparent_1", "parent_1"]

object

None

Not yet supported. For future uses only
Table 122. field definition attributes object
Type Description

list[]

It is an array with the values available when "type": "enumeration"

visible

Takes values as true or false and indicates that the field must be visible or not

editable

Takes values as true or false and indicates that the field must be editable or not

gte

Greater and Equal Than. Used when type or subtype is "number". Indicates the value range the field can take

lte

Lower and Equal Than. Used when type or subtype is "number". Indicates the value range the field can take

gt

Greater Than. Used when type or subtype is "number". Indicates the value range the field can take

lt

Lower Than. Used when type or subtype is "number". Indicates the value range the field can take

Default Operations Catalog

OpenGate implements a default set of operations which is listed below:

Available operations through north api catalog searching is only indicative because the type of operations visibility can be enabled or disabled by the platform administrator to an specific user

New adhoc Operations can be added to adapt to specific needs
Table 123. Built in operations
Applicable To Name North Api parameters South Api parameters

Device

UPDATE (See Device update)

  • bundleName: String with the name of the bundle to be applied

  • bundleVersion: Version of the bundle to be applied

  • bundleName: String with the name of the bundle to be applied

  • bundleVersion: Version of the bundle to be applied

  • url: String with URL to download the bundle files in a zip format

Device

SET_CLOCK_EQUIPMENT

  • date (optional)

  • time (Optional)

  • timezone

  • dst

If you don’t include parameters the time sent to the device will be the actual in the moment of operation execution.

  • datetime: Number with the time in seconds from epoch

  • timezone

  • dst

Device

POWER_ON_EQUIPMENT

Device

POWER_OFF_EQUIPMENT

Device

REBOOT_EQUIPMENT

  • type

    • HARDWARE

    • SOFTWARE

    • APPLICATION

  • applications: Array of strings with name of applications to be rebooted

Same

Device

REFRESH_LOCATION

Device

REFRESH_INFO

Device

REFRESH_PRESENCE

Device

STATUS_DIAGNOSTIC

ADMINISTRATIVE_STATUS

Device

EQUIPMENT_DIAGNOSTIC

  • name

    • HARDWARE

    • SOFTWARE

    • DEVICE

Same

Device

WAKE_UP_COMMUNICATIONS

  • mode

    • ALL

    • SELECTED

  • profile

  • channel

    • IP-GPRS

    • IP-WIFI

    • SMS

Device

RESET_COMMUNICATIONS

PROFILE

Device, Subscription, Subscriber

ADMINISTRATIVE_STATUS_CHANGE

STATUS

Device

SHUT_DOWN_COMMUNICATIONS

PROFILE

Subscription

SERVICE_CONFIGURATION

  • data

    • ENABLED

    • DISABLED

  • smsIncoming

    • ENABLED

    • DISABLED

  • smsIncomingMode

    • BLACK_LIST

    • WHITE_LIST

  • smsOutgoing

    • ENABLED

    • DISABLED

  • smsOutGoingMode

    • BLACK_LIST

    • WHITE_LIST

    • smsOutGoingList[]

  • dataCallIncomingMode

    • ENABLED

    • DISABLED

  • dataCallOutgoing

    • ENABLED

    • DISABLED

  • dataCallOutgoingMode

    • BLACK_LIST

    • WHITE_LIST

  • dataCallOutgoingList[]

  • voiceCallIncoming

    • ENABLED

    • DISABLED

  • voiceCallOutgoing

    • ENABLED

    • DISABLED

  • voiceCallOutgoingMode

    • BLACK_LIST

    • WHITE_LIST

  • voiceCallOutgoingList[]

Subscription

RATE_PLAN_CHANGE

  • ratePlan

    • RATE_PLAN

    • TEST_RATE_PLAN

    • DISCOUNT_RATE_PLAN

    • SPECIAL_OFFER_RATE_PLAN

    • GENERIC_RATE_PLAN

Subscription

APN_ALLOWED

  • apnList[]

Subscription

SIM_REPLACEMENT

ICCid

Device

FACTORY_RESET

The SMS capability is possible onpremise solution. It is required integration with a external service provider

Device Operations details

Device operations flows

Normally all the operations in the catalog has at least a minimun workflow to be fulfilled. Nevertheless there are operations that can have different flows depending on the devices behaviour. They are showed in the South Operations API.

Device operations parameters

As is stated above operations can have parameters as a list of different simple or complex fields with the necessary data for the operation execution.

Normally the specific parameters of a operation will be the same for the both APIs (North and South). Nevertheless there are operations that can have different list of parameters for North and South APIs. They are showed below. In this section it is described how the parameters in operations has to be interpreted in both API sides.

Tho understand this we take the next operation example:

  • Operation: REBOOT_EQUIPMENT

  • Parameters:

    • type (String. Enumeration indicating the type of the hardware)

    • applications (String array with the list of applications to be rebooted)

North API invocation

The next example shows how the parameters has to be filled in the North API call

North API Parameters format
"parameters": [
    {
        "name":"TYPE",
        "value":{
            "string":"HARDWARE"
        }
    },
    {
        "name":"applications",
        "value":{
            "array":[ "application1", "application2"]
        }
    }
]

South API invocation

The next example shows how the parameters will be received by the device through the Soutth API call

South API Parameters format
"parameters": [
    {
        "name":"TYPE",
        "type":"string",
        "value":{
            "string":"HARDWARE"
        }
    },
    {
        "name":"applications",
        "type":"array",
        "subtype":"string",
        "value":{
            "array":[ "application1", "application2"]
        }
    }
]

Device Operations: Update Operation

Flow diagram

This is an special operation for the platform. OpenGate suggest the implementation of a complete flow that allow cover all the possible stages of a device update.

In the real world the device can implement only part of the suggested stages or steps. Also it is supported any number and kind of steps your device implements

The next figure shows this flow:

opengate api south operation UPDATE flow
Figure 11. Update operation Flow

In bold format are marked the operations of the minimun flow required

North API invocation

Device update operations are invoked by Backoffice applications through the OpenGate North API Operations section. So you can use all you learned about this API, you only have to pay attention to the specific operation name and parameters involved in device updates:

Table 124. Device Update operation parameters
Parameter (*required) Constraints Description

bundleName*

String

Name of the bundle.

bundleVersion *

String

Version of the bundle
Device Update Example
{
    "job" :
    {
        "request" : {
            "name" : "UPDATE",
            "parameters": [
                {
                    "name" : "bundleName",
                    "type":"string",
                    "value" : {
                        "string" : "bundle_1"
                    }
                },
                {
                    "name" : "bundleVersion",
                    "type":"string",
                    "value" : {
                        "string" : "1.0"
                    }
                }
            ],
            "active" : true,
            "notify" : true,
            "callback" : "http://[your_application_address]/[your_URI]",

            "schedule" : {
                "start" : {
                  "date" : "2012-09-10T12:33:43Z"
                },
                "stop" : {
                  "delayed" : 300000
                }
            },
            "operationParameters" : {
                "ackTimeout" : 5000,
                "timeout" : 6000,
                "retries" : 0,
                "retriesDelay" : 1000
            },
            "target" : {
                "append" : {
                    "entities" : [ "device_1", "device_2" ]
                }
            }
        }
    }
}

South API invocation

Device update operations are invoked by the OpenGate platform to the device through the OpenGate (see South API Operations section). So you can use all you learned about this API, you only have to pay attention to the specific operation name and parameters involved in device updates:

Table 125. Device Update operation parameters
Parameter Constraints Description

bundleName

String

Name of the bundle.

bundleVersion

String

Version of the bundle

deploymentElements

String

Array of elements to be updated. See <South API Deployment Element Object
Table 126. South API Deployment Element Object
Parameter Constraints Description

Name

string

deployment element name

version

string

deployment element version

type

string

Type of the deployment element

downloadUrl

string

Version of the bundle

path

string

Path in the device to install the element

operation

string

Indicates the action to be done with the element

option

String

Information additional if the element is optional or mandatory

order

String

Order of the different deployment element into the bundle

validators

array

To verify downloaded file. See <South API Deployment Element Object
Table 127. South API Deployment Element Object
Parameter Constraints Description

type

string

Type of the validation algorithm

value

string

string to perform the validation
Device Update Example
{
    "operation": {
        "request": {
            "timestamp": 1453822201099,
            "name": "UPDATE",
            "parameters": [
                {
                    "name": "bundleName",
                    "value": {
                        "string": "bundle_1"
                    }
                },
                {
                    "name": "bundleVersion",
                    "value": {
                        "string": "version_1"
                    }
                },
                {
                    "name": "deploymentElements",
                    "value": {
                        "array": [
                            {
                                "type": "FIRMWARE",
                                "downloadUrl": "http://[your_opengate_address]/bundles/74427c0c-a28c-4765-92ef-30010adb733d/1002/firmware-1_1.1.bin",
                                "path": "/home",
                                "order": 1,
                                "operation": "INSTALL",
                                "option": "OPTIONAL",
                                "validators": [
                                    {
                                        "type": "SHA-256",
                                        "value": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
                                    }
                                ],
                                "size": 18
                            }
                        ]
                    }
                }
            ],
            "id": "072b08d1-0fcb-4a0c-a2d8-99773f9b9327"
        }
    }
}

Rules Catalog

OpenGate implements a default set of rules which is listed below:

GET /north/v80/rules/catalog

In the next table is shown the list of the rules catalog incorporated to the platform by default

"Rule type" column indicates if the rule conditon is evaluated because you collected data in the South API (DATASTREAM), an operation were execute in Opengate platform (OPERATION), or an event were sent to Opengate platform (See device default allowed events in the Events examples section in the South API, and default operations in the Operations Catalog)
Table 128. Built in rules catalog
Rule type Name Description Configurable Parameters

DATASTREAM

activityForbiddenDatastream

Activity detected for an entity with administrative state disabled

OPERATION

activityForbiddenOperation

Activity detected for an entity with administrative state disabled

DATASTREAM

areaInputWithParameter

Checks if an entity has entered in a geofence

  • datastream_location_name: Datastream location of the resource that is wanted to check, example: "entity.location"

  • datastream_name: Added parameter to check also

  • area: Identifier of the area, example: "Zone3"

  • datastream_value: Value of added parameter (datastream_name)

DATASTREAM

areaOutputWithParameter

Checks if an entity has exitted of a geofence

  • datastream_location_name: Datastream location of the resource that is wanted to check, example: "entity.location"

  • datastream_name: Added parameter to check also

  • area: Identifier of the area, example: "Zone3"

  • datastream_value: Value of added parameter (datastream_name)

DATASTREAM

batteryThreshold

Current value of datastream has an unusual value

  • threshold: Threshold that allows to manage if a measure is lower, example: 5 (integer)

DATASTREAM

cancelBatteryThreshold

Current value of datastream has is returned to usual value

  • threshold: Threshold that allows to manage if a measure is higher, example: 5 (integer)

DATASTREAM

changeCommsModuleOperationalStatusByNokPing

Put selected operational status to communication module if consecutive NOK Ping reach selected value. Needs countPings rule enabled

  • operational_status: Value to collect in datastream "device.communicationModules[].operationalStatus" when condition has been satisfied, example: "DISABLED"

  • threshold: Number of pings NOK in order to satisfy condition: 50 (integer)

DATASTREAM

changeCommsModuleOperationalStatusByOkPing

Put selected operational status to communication module if OK Ping received

  • operational_status: Value to collect in datastream "device.communicationModules[].operationalStatus" when condition has been satisfied, example: "RUNNING"

DATASTREAM

checkDistance

Checks if entity is farther than a defined distance

  • datastream_name: Datastream location of the resource that is wanted to check, example: "entity.location"

  • latitude: Coordinates of latitude, example: 40.47 (number)

  • longitud: Coordinates of latitude, example: -3.66 (number)

  • distance: Distance to be checked, example: 2000 (integer)

  • entityKeys: example: "ALL"

DATASTREAM

collectAreas

Calculate entity.area datastream (and its derivatives) based on entity.location datastream

  • datastream_location_name: Datastream location of the resource that is wanted to check, example: "entity.location"

  • datastream_area_name: Added parameter to check also, example: "entity.areas"

DATASTREAM

countAccountingStart

Count accounting start in subscription

  • subscription_accounting_datastream: example: "device.communicationModules[].subscription.counters.presence.accountingStartLastDay"

  • device_accounting_datastream: example: "device.counters.presence.accountingStartLastDay"

  • ttl_datapoints_collector: ttl for datapoints collected

DATASTREAM

countPings

Count number of ping [OK/NOK/NOK consecutives] to get information in mobile net

  • ignored_operational_status: example: "DISABLED"

  • ttl_datapoints_collector: ttl for datapoints collected

OPERATION

diagnosticFailed

Diagnostic with error in some operation

EVENT

messageFlowRateExceeded

Message flow rate exceeded, not process message

DATASTREAM

mobileICCMismatch

Collected ICC does not match with provisioned

DATASTREAM

mobileICCValueChanged

Compare current with previous values of one datastream

DATASTREAM

presenceReachableAllInterfaces

Verify if, at least one communication interface is reachable

  • datastream_name: Added parameter to check also

  • threshold: Value to compare datastream "device.communicationModules[].subscription.presence.unifiedPresence"

  • extra_threshold: Extra value to compare datastream "device.communicationModules[].subscription.presence.unifiedPresence"

  • collect_datastream_to: Name of the data stream to set to true when condition is satisfied. By default its value is "presenciaTotal".

  • rule_to_close: Rule to close

DATASTREAM

presenceUnreachableAllInterfaces

Verify if the device is unreacheable through all its communication interfaces

  • datastream_name: Added parameter to check also

  • threshold: Value to compare datastream "device.communicationModules[].subscription.presence.unifiedPresence"

  • extra_threshold: Extra value to compare datastream "device.communicationModules[].subscription.presence.unifiedPresence"

  • collect_datastream_to: Name of the data stream to set to false when condition is satisfied. By default its value is "presenciaTotal".

DATASTREAM

receivedBanned

Received data for a banned entity

EVENT

securityConfigMismatch

Security error validate, device validation failedSecurity error validate, device validation failed

DATASTREAM

subscriptionActivation

Check if subscription is administrativeState = ACTIVE for a configured operator

  • operator_name: example, "Sigfox Operator"

DATASTREAM

subscriptionSuspension

Check if subscription is administrativeState = SUSPENSION for a configured operator

  • operator_name: example, "Sigfox Operator"

DATASTREAM

sumSessionBytes

Sum traffic bytes can get information in mobile net

  • daily_subscription_total_datastream: example, "device.communicationModules[].subscription.counters.totalBytesLastDay"

  • daily_subscription_sent_datastream: example, "device.communicationModules[].subscription.counters.sentBytesLastDay"

  • daily_subscription_received_datastream: example, "device.communicationModules[].subscription.counters.receivedBytesLastDay"

  • monthly_subscription_total_datastream: example, "device.communicationModules[].subscription.counters.totalBytesLastMonth"

  • monthly_subscription_sent_datastream: example, "device.communicationModules[].subscription.counters.sentBytesLastMonth"

  • monthly_subscription_received_datastream: example, "device.communicationModules[].subscription.counters.receivedBytesLastMonth"

  • daily_device_total_datastream: example, "device.counters.totalBytesLastDay"

  • daily_device_sent_datastream: example, "device.counters.sentBytesLastDay"

  • daily_device_received_datastream: example, "device.counters.receivedBytesLastDay"

  • monthly_device_total_datastream: example, "device.counters.totalBytesLastMonth"

  • monthly_device_sent_datastream: example, "device.counters.sentBytesLastMonth"

  • monthly_device_received_datastream: example, "Sigfox Operator"

  • ttl_datapoints_collector_daily: ttl for daily datapoints collected

  • ttl_datapoints_collector_monthly: ttl for monthly datapoints collected

Notifications

The platform can send notifications using SNMP protocol using the OpenGate MIB

Legal information

Contact

Contact Information

  • AMPLIA SOLUCIONES

  • Golfo de Salónica 27, 1ª

  • 28033 Madrid

  • Info@amplia.es

  • +34 91 112 67 47

Conditions and disclaimers

The information contained in this document is copyrighted and all rights are reserved by Amplia soluciones s.l.. Amplia soluciones s.l. reserves the right to make periodic modifications to the document without obligation to notify any person or entity of such revision. Copying, duplicating, selling, or otherwise distributing any part of the software or documentation without prior written consent of an authorized representative of microstrategy, inc. are prohibited.

Documentation is provided as a reference sample on an "as is'' basis, without warranty of any kind, either expressed or implied, including, without limitation, warranties that the documentation is free of defects, merchantable, fit for a particular purpose or non-infringing. The entire risk as to the quality, accuracy, and performance of the documentation is with you. Should any documentation prove defective in any respect, you (not the initial writer or any other contributor) assume the cost of any necessary servicing, repair or correction. This disclaimer of warranty constitutes an essential part of this license. No use of any documentation is authorized hereunder except under this disclaimer.

Under no circumstances and under no legal theory, whether in tort (including negligence), contract, or otherwise, shall the initial writer, any other contributor, or any distributor of documentation, or any supplier of any of such parties, be liable to any person for any direct, indirect, special, incidental, or consequential damages of any character including, without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other damages or losses arising out of or relating to the use of the documentation, even if such party shall have been informed of the possibility of such damages.

OpenGate and amplia))) are trademarks or registered trademarks of Amplia soluciones s.l.. All other company and product names may be trademarks of the respective companies with which they are associated. Specifications subject to change without notice. Amplia soluciones s.l.. is not responsible for errors or omissions.

Amplia soluciones s.l. makes no warranties or commitments concerning the availability of future products or versions that may be planned or under development whether they were notified or not in any format.

Default User Profiles

OpenGate by default incorporates a set of user profiles which is listed below:

New adhoc User Profiles can be added to adapt to specific needs
Table 129. Built in user profiles
Profile Permissions

root

  • Total control for managing all resources in the platform

admin_domain

  • Access to the Provision APIs:

    • Domains (create, update, delete)

    • Subdomains (create and update)

    • Organizations (create, update, delete)

    • Workgroups (create, update, delete)

    • Channels (create, update, delete)

    • Users (create, update, delete)

    • Certificates (create, update, delete, download)

    • Datamodels (create, update, delete)

    • Areas (create, read, update, delete)

    • Bulk of Assets, Devices, subscriptions (create, update, delete)

    • Assets entities (create, read, update, delete)

    • Devices entities (create, read, update, delete)

    • Subscriptions entities (create, read, update, delete)

    • Subscribers entities (create, read, update, delete)

    • APNs (create)

    • Radius Clients (create)

    • Tags (create)

    • Tickets (create, read, update, delete)

  • Access to the Search APIs: (Full access)

  • Access to the Operation APIs:

    • Jobs (create, read, update, delete)

    • Tasks (create, read, update, delete)

    • Alarms (read, attend, close)

    • Rules (read, update, clone, delete)

    • Bundles (create, read, update, delete, execute)

    • Download csv

admin

  • Access to the Provision APIs:

    • Workgroups (create, update, delete)

    • Channels (create, update, delete)

    • Users (create, update, delete)

    • Certificates (create, update, delete, download)

    • Datamodels (create, update, delete)

    • Areas (create, read, update, delete)

    • Bulk of Assets, Devices, subscriptions (create, update, delete)

    • Assets entities (create, read, update, delete)

    • Devices entities (create, read, update, delete)

    • Subscriptions entities (create, read, update, delete)

    • Subscribers entities (create, read, update, delete)

    • APNs (create)

    • Radius Clients (create)

    • Tags (create)

    • Tickets (create, read, update, delete)

  • Access to the Search APIs: (Full access)

  • Access to the Operation APIs:

    • Jobs (create, read, update, delete)

    • Tasks (create, read, update, delete)

    • Alarms (read, attend, close)

    • Rules (read, update, clone, delete)

    • Bundles (create, read, update, delete, execute)

    • Download csv

advanced

  • Access to the Provision APIs:

    • Users (update yourself)

    • Certificates (download)

    • Areas (create, read, update, delete)

    • Bulk of Assets, Devices, subscriptions (create, update, delete)

    • Assets entities (create, read, update, delete)

    • Devices entities (create, read, update, delete)

    • Subscriptions entities (create, read, update, delete)

    • Subscribers entities (create, read, update, delete)

    • Tags (create)

    • Tickets (create, read, update, delete)

  • Access to the Search APIs: (Full access)

  • Access to the Operation APIs:

    • Jobs (create, read, update, delete)

    • Tasks (create, read, update, delete)

    • Alarms (read, attend, close)

    • Rules (read, update, clone, delete)

    • Bundles (create, read, update, delete, execute)

    • Download csv

viewer

  • Access to the Provision APIs:

    • Users (update yourself)

    • Certificates (download)

    • Areas (read)

    • Assets entities (read)

    • Devices entities (read)

    • Subscriptions entities (read)

    • Subscribers entities (read)

    • Tickets (read)

  • Access to the Search APIs: (Full access)

  • Access to the Operation APIs:

    • Jobs (read)

    • Tasks (read)

    • Alarms (read)

    • Rules (read)

    • Bundles (read)

    • Download csv
1. curl is a widely used tool you can find regarding information about it in the wikipedia and in the project home page. If you’re using a Linux flavour, curl is probably already installed. If you’re using windows you can find a ported version here or you can install the fantastic Cygwin.