Entities

Entities provisioning

• Entity types & statuses
• Devices
• Subscriptions
• Subscribers
• Assets
• Bulk provisioning

OpenGate offers four types of entities: asset, device, subscription, and subscriber. Use the resourceType field to set the type. The following table show how to set each entity type:

1. entity.asset: It allows to create new entities by the user different to the environment of the device.
2. entity.device: It represents a remote hardware unit.
3. entity.subscription: It stores information regarding the contracts with your communication operators.
4. entity.subscriber: It stores information regarding a specific communication channel.

Common objects and attributes

All the entities have several attributes, objects, and arrays in common. The following sections show the details associated with these shared objects.

{
  "provision": {
    "administration": {
      "channel": {
        "_current": {
          "value": "wind_farm_channel"
        }
      },
      "organization": {
        "_current": {
          "value": "wind_farm_organization"
        }
      },
      "serviceGroup": {
        "_current": {
          "value": "emptyServiceGroup"
        }
      }
    },
    "device": {
      "identifier": {
        "_current": {
          "value": "wind_mill_id"
        }
      }
    }
  }
}

Identifier attributes

There are different identifiers for the entities supported by OpenGate.

Administrative data attributes

• id: each IoT entity has a unique identifier all over the platform. This identifier is auto-generated by the platform.
• provision.device.identifier: it is a customer generated ID consisting in a string that identifies a device in a specific organization. HTTP/1.1 201 Created Location: http://api.opengate.es/north/v80/provision/organizations/{organizationName}/devices/device_1 You must use this identifier as URL suffix when you want to get, update or delete your device.
• provision.device.communicationModules[].identifier: it is a customer-generated id consisting of a string that identifies a Communication Module
• provision.device.communicationModules[].subscription.identifier: it is a customer-generated identifier consisting of a string that identifies a subscription
• provision.device.communicationModules[].subscriber.identifier: it is a customer-generated identifier consisting of a string that identifies a subscriber.

Administration object attributes

An administrative context is mandatory for all OpenGate entities.

Attributes

• organization: the organization that owns the entity.
  • Forbidden in entity update operation
  • Required in entity insert operation
  • Constraints: [a-zA-Z0-9] max 50 chars
• channel: an administrative grouping method for your entities.
  • Required in entity insert operation.
  • Constraints: [a-zA-Z0-9] max 50 chars.
• administrativeState: see administrativeState values

• serviceGroup: Service configuration: configuration of services, operations available, etc.
  • Constraints: [a-zA-Z0-9] max 50 chars.
  • Forbidden in bundle operations.
• workgroup: the workgroup is the way to establish the relationships between devices and users. It’s used, for example, when you want to create software bundles.
  • Constraints: [a-zA-Z0-9] max 50 chars.
  • This field only applies to OpenGate users. -plan (optional): an administrative concept that allows limiting the number of events sent by the device, this concept only applies to devices
  • Constraints: [a-zA-Z0-9] max 50 chars
  • Forbidden in bundle operations.
  • Optional in entity insert and update operation.

{
  "provision": {
    "administration": {
      "channel": {
        "_current": {
          "value": "YOUR_CHANNEL_NAME"
        }
      },
      "organization": {
        "_current": {
          "value": "YOUR_ORGANIZATION_NAME"
        }
      },
      "serviceGroup": {
        "_current": {
          "value": "SERVICE_GROUP_FOR_THE_ENTITY"
        }
      },
      "plan": {
        "_current": {
          "value": "FLOW_RATE_100"
        }
      }
    }
  }
}

Service group

Please, pay special attention to the entity service group. You must select the appropriate service group because a service group determines how OpenGate behaves when managing your devices in terms of:

• Permitted operations.
• How the platform sends scheduled operations to devices
  • Always: this type is oriented to devices always connected. In this case, OpenGate will send operations to the devices according to the job schedule. If the target device is not connected, the operation will expire and finish with an error. On-session-connection: in this case, the platform saves operations for later use. When a device connects to the platform, it will detect this connection and send to the device its pending operations. This mode applies to devices using web sockets or MQTT connectors.
  • On-demand: in this case, the device will request pending operations. This way, devices can save battery and retrieve pending operations when awake.

• Trusted boot, all the messages the platform receives must include a field with the trusted boot value. If the trusted boot field is not present, OpenGate will reject the message.
• Device security mode, with this option, you can select the security level in the communications between the device and platform. You can choose between:
  • None, all the communications won’t be encrypted
  • Level 1, One-way authentication (or platform authentication): Only the platform authenticates itself to the client. The platform sends the client a certificate verifying that the platform is authentic.
  • Level 2, Two-way authentication (or bilateral authentication): Both client and server authenticate themselves to each other, verifying that the certificate authenticator it’s available on the platform
• Level 3, Two-way authentication with certificate checking: both client and server authenticate themselves to each other, verifying that the platform’s device certificate is available.

Service groups available on OpenGate cloud instance

Plan feature

The plan feature is an essential concept in OpenGate. The plan holds the organization and device usage limits. Every organization will have a particular plan setting:

• The maximum number of devices, gateways, or assets the organization can have.
• The maximum time the collected data will remain stored until its evicted.
• The maximum number of events collected by the platform in a period.

Flattened format

It’s possible to create and search for data stream values (see default data models) using the flat format. This flat format is the same used on the south API. Use the boolean parameter flattened in the URL to indicate if data streams are in a flattened form.

The format is:

{
  "parameter1_id": {
    "_value": {
      "_current": {
        "value": "value1"
      }
    }
  },
  "parameter2_id": {
    "_value": {
      "_current": {
        "value": "value2"
      }
    }
  },
  ...
  "parameterN_id": {
    "_value": {
      "_current": {
        "value": "valueN"
      }
    }
  }
}

We can see how to transform a hierarchical JSON format into a flattened JSON format in the following examples. There are two types of values, simple and complex:

Simple values

The hierarchical JSON format is:

{
  "provision": {
    "administration": {
      "identifier": {
        "_current": {
          "value": "device_battery"
        }
      }
    }
  }
}

The flattened JSON format is:

{
  "provision.administration.identifier": {
    "_value": {
      "_current": {
        "value": "device_battery"
      }
    }
  }
}

Complex values

We are going to see two different examples to clarify this concept.

The hierarchical JSON format is:

{
  "provision": {
    "device": {
      "location": {
        "_current": {
          "value": {
            "position": {
              "type": "Point",
              "coordinates": [-3.7028, 40.41675]
            },
            "postal": "28013"
          }
        }
      }
    }
  }
}

The flattened JSON format is:

{
  "provision.device.location": {
    "_value": {
      "_current": {
        "value": {
          "position": {
            "type": "Point",
            "coordinates": [-3.7028, 40.41675]
          },
          "postal": "28013"
        }
      }
    }
  }
}

Another example:

The hierarchical JSON format is:

{
  "provision": {
    "device": {
      "communicationModules": [
        {
          "identifier": {
            "_current": {
              "value": "commsMod_battery_id"
            }
          },
          "name": {
            "_current": {
              "value": "commsMod_battery_name"
            }
          }
        }
      ]
    }
  }
}

The flattened JSON format when it is a creative operation is:

{
  "provision.device.communicationModules[].identifier": [
    {
      "_index": {
        "value": "commsMod_battery_id"
      },
      "_value": {
        "_current": {
          "value": "commsMod_battery_id"
        }
      }
    }
  ],
  "provision.device.communicationModules[].name": [
    {
      "_index": {
        "value": "commsMod_battery_id"
      },
      "_value": {
        "_current": {
          "value": "commsMod_battery_name"
        }
      }
    }
  ]
}

The flattened JSON format when it is a reading operation is:

{
  "provision.device.communicationModules[].identifier": [
    {
      "_index": {
        "path": "provision.device.communicationModules[].identifier",
        "value": {
          "_current": {
            "value": "commsMod_battery_id",
            "provType": "MONITORING",
            "date": "2017-09-25T09:34:32.119Z"
          }
        }
      },
      "_value": {
        "_current": {
          "value": "commsMod_battery_id",
          "provType": "MONITORING",
          "date": "2017-09-25T09:34:32.119Z"
        }
      }
    }
  ],
  "provision.device.communicationModules[].name": [
    {
      "_index": {
        "path": "provision.device.communicationModules[].identifier",
        "value": {
          "_current": {
            "value": "commsMod_battery_id",
            "provType": "MONITORING",
            "date": "2017-09-25T09:34:32.119Z"
          }
        }
      },
      "_value": {
        "_current": {
          "value": "commsMod_battery_name",
          "provType": "MONITORING",
          "date": "2017-09-25T09:34:32.169Z"
        }
      }
    }
  ]
}

We will also see how to transform the previous normal/flattened JSON examples into CSV format. We are going to join the examples above in a unique CSV file with three lines, one for each example above (a straightforward example and two complex examples)

It is easier to transform the flattened format into CSV format because the CSV file’s content follows the same guidelines as the flattened format. The first line (header) contains the name of the data stream separated by “;” and the following lines are the different entities and have the field value of the data stream separated by “;” in the same order as the first line.

The following lines show an example of a CSV format.

provision.administration.identifier;provision.device.location;provision.device.communicationModules[].identifier;provision.device.communicationModules[].name
device_battery;;;
;"{"position":{"type":"Point","coordinates":[-3.7028,40.41675]},"postal":"28013"}";;
;;commsMod_battery_id;commsMod_battery_name

When an entity contains a unique communication module, it is possible to indicate the name without [] and without the identifier. Taking this into consideration, [commsMod_battery_name(commsMod_battery_id)] and commsMod_battery_name are the same.

Asset provision

It allows the creation of entities that are not devices and usually represent business-related objects like workers, spools, parking places, vending machines, etc.​

It’s possible to link assets and devices. For example, a worker (the asset) may have one or more devices measuring several parameters like bracelets measuring heart rate, thermometer collecting temperature, or GPS locating its position.

Provision is the way to link assets and devices. The field asset.related datastream contains an array with the identifiers of the associated devices.

It’s also possible to have the collected device’s information available in the assets. To enable this feature, activate the allowed resource types entity.asset and entity.device in data model creation. This way, all data points from data streams collected by the devices will be available in the asset. This feature is also called dual data streams. The default entity data model has two dual data streams: entity.location and entity.areas.

Asset object structure

An asset stores information about the new entity created by the user.

Regarding to provisioned data there are the following attributes:

• Minium attributes:
  • provision.administration
  • provision.asset.identifier
  • resourceType
• Recommended attributes by OpenGate:
  • provision.asset.administrativeState
  • provision.asset.specificType
  • provision.asset.name
  • provision.asset.description
• Extended attributes:
  • provision.asset.location
  • Defined attributes in human data model
  • Defined by the user in his new data models. For example photo, position

A resourceType can have a specificType to denote differences. Example: "resourceType": "entity. asset" and "specificType": "WORKER"

Device Provision

A device can be related to an asset through the provision.device.related data stream. It must contain the identifier of the asset.

Subscribers Provision

The subscriber entity holds information regarding a specific communication channel. It can exist isolated or inside a device.

Subscription Provision

A subscription stores information regarding the contracts with your communication operators. It can exist in isolation or inside the device.

Spec