How to connect a device?

TABLE OF CONTENTS

Introduction

This section explains how to connect a device after it has been produced and equipped with a unique external identification number. 

Onboard devices on the platform

In order to make the device available on the platform you need to upload a JSON file. Before you upload the file, it must be adjusted:

  1. Chose the right file for the type of sensor you want to onboard
  2. Insert the external device ID which can be found on every device
  3. Add all necessary tags to the device in order to use the filter functionality of the platform. Which tags are used is highly dependant on the internal naming of on-site installations of your company. You are completely free to choose your own tags and system to suit your needs.
  4. After saving the adjusted JSON file it simply needs to be uploaded to the Device Manager of the platform:
  5. Go to the Device Manager (1) and upload the adjusted file to the platform (2). You will see the device appearing in the device list (3).

Example and explanation of a JSON file

This example shows the pre-defined JSON file with all necessary configurations for a "ES 10" sensor. The sensor in this example is transmitting the following values:

  • UUID of the Device Type
  • External ID of the Device
  • Name of the sensor
  • All data channel of  the device:
    • Version
    • Battery Voltage
    • Signal Strength
    • Temperature
    • Relative Humidity
    • Barometric Pressure
  • Tags

Define the Device Type and External ID of the Sensor 

The first section of the JSON file defines the Device Type and the External ID of the device. The Device Type must be created within the platform in the Device Manager. Every Device Type is unique by it´s Device Type UUID. The created device type includes all data channels of a device. The External ID of the device relates to the specific device. This could be a serial number of a device. Therefore, every External ID needs to be unique to point to a singe device and not to a device group as the Device Type UUID does.

    "device_type_uuid": "67ec4bca-7f79-47b7-b26e-5dd8896ae916",
    "external_id": "352656101434408",

Define device name

The device name can be defined in different languages. Therefore it is necessary to state the language and region code. In the example the sensor will have an English (US region) and German name. The value relates to the actual name of the sensor "ES 10".  Please note, that for this sensor the name in both languages is the same.

    "name": [
      {
        "value": "ES 10",
        "language": {
          "code": "en",
          "region": "US"
        }
      },
      {
        "value": "ES 10",
        "language": {
          "code": "de",
          "region": "DE"
        }
      }
    ],

Define data and metadata 

In the next section the data transmitted by the device is defined. All data can be defined by a describing name. In the same way as the sensor name, the data name can be described in different languages. 


Please note, that for this description only the value "Version" is shown. In the full example of this sensor more data will be included (Battery Voltage, Signal Strength, Temperature, Relative Humidity, Barometric Pressure).


The type UUID ("type") defines is pointing to the created Channel Type in the platform. For compatibility reason for a legacy version of the platform the "data_schema_uuid", "tsId" and "organizationId" stated but optional and not used anymore.

    "channels": [
      {
        "name": [
          {
            "value": "Version",
            "language": {
              "code": "de",
              "region": "DE"
            }
          },
          {
            "value": "Version",
            "language": {
              "code": "en",
              "region": "US"
            }
          }
        ],

        "type": "4d541254-d355-42a8-803c-940668b70a71",
        "data_schema_uuid": "254c29ba-bbdc-44da-9d7a-fc899cd97a57",
        "data": {
          "tsId": "7aceedba-4926-4bf3-aacf-931dfe05ef86",
          "organizationId": "99f23c52-e8e3-413e-8495-d65efc665b6d"
        }
      },
 ],

Adding tags to a device

In addition tags can be to a singel device when it is introduced to the platform. This is done in the last section of the file:

    "tags": ["ris", "134-3_OG_1/421.0", "Trockenabsaugung_Ventilator"]

Complete JSON file

Ones a JSON file has been created it is only necessary to adjust the external_id value for every sensor. The tag values are located at the very end of the JOSN file and my also be adjusted. You can add and adjust these tags and their text as you wish. After adjusting the file it needs to be saved and uploaded.

[
  {
    "device_type_uuid": "67ec4bca-7f79-47b7-b26e-5dd8896ae916",
    "external_id": "352656101434408",
    "name": [
      {
        "value": "ES 10",
        "language": {
          "code": "en",
          "region": "US"
        }
      },
      {
        "value": "ES 10",
        "language": {
          "code": "de",
          "region": "DE"
        }
      }
    ],
    "channels": [
      {
        "name": [
          {
            "value": "Version",
            "language": {
              "code": "de",
              "region": "DE"
            }
          },
          {
            "value": "Version",
            "language": {
              "code": "en",
              "region": "US"
            }
          }
        ],
        "type": "4d541254-d355-42a8-803c-940668b70a71",
        "data_schema_uuid": "254c29ba-bbdc-44da-9d7a-fc899cd97a57",
        "data": {
          "tsId": "7aceedba-4926-4bf3-aacf-931dfe05ef86",
          "organizationId": "99f23c52-e8e3-413e-8495-d65efc665b6d"
        }
      },
      {
        "name": [
          {
            "value": "Batteriespannung",
            "language": {
              "code": "de",
              "region": "DE"
            }
          },
          {
            "value": "Battery Voltage",
            "language": {
              "code": "en",
              "region": "US"
            }
          }
        ],
        "type": "1806685a-5e02-40fb-a5e6-c599fd96a7e6",
        "data_schema_uuid": "254c29ba-bbdc-44da-9d7a-fc899cd97a57",
        "data": {
          "tsId": "8ab18e4c-dbb6-4905-a4d5-244fbe07dbd1",
          "organizationId": "99f23c52-e8e3-413e-8495-d65efc665b6d"
        }
      },
      {
        "name": [
          {
            "value": "Signalstärke",
            "language": {
              "code": "de",
              "region": "DE"
            }
          },
          {
            "value": "Signal Strength",
            "language": {
              "code": "en",
              "region": "US"
            }
          }
        ],
        "type": "0e6af303-c71c-49b2-a9a8-5618938a00ed",
        "data_schema_uuid": "254c29ba-bbdc-44da-9d7a-fc899cd97a57",
        "data": {
          "tsId": "043c8d3d-73d1-4c8f-96f5-9aae0ddf08f1",
          "organizationId": "99f23c52-e8e3-413e-8495-d65efc665b6d"
        }
      },
      {
        "name": [
          {
            "value": "Temperatur",
            "language": {
              "code": "de",
              "region": "DE"
            }
          },
          {
            "value": "Temperature",
            "language": {
              "code": "en",
              "region": "US"
            }
          }
        ],
        "type": "3924eb1d-dbb0-47ce-bc6a-10d40b943eea",
        "data_schema_uuid": "254c29ba-bbdc-44da-9d7a-fc899cd97a57",
        "data": {
          "tsId": "13e21c65-4181-4db7-bebc-5b70d822eaa0",
          "organizationId": "99f23c52-e8e3-413e-8495-d65efc665b6d"
        }
      },
      {
        "name": [
          {
            "value": "Luftfeuchtigkeit",
            "language": {
              "code": "de",
              "region": "DE"
            }
          },
          {
            "value": "Relative Humidity",
            "language": {
              "code": "en",
              "region": "US"
            }
          }
        ],
        "type": "a6a0f4eb-86b4-4f58-917a-2979120d722f",
        "data_schema_uuid": "254c29ba-bbdc-44da-9d7a-fc899cd97a57",
        "data": {
          "tsId": "a233301e-8e28-4b58-8c0a-b746aca8e61e",
          "organizationId": "99f23c52-e8e3-413e-8495-d65efc665b6d"
        }
      },
      {
        "name": [
          {
            "value": "Luftdruck",
            "language": {
              "code": "de",
              "region": "DE"
            }
          },
          {
            "value": "Barometric Pressure",
            "language": {
              "code": "en",
              "region": "US"
            }
          }
        ],
        "type": "71f6fe02-1f00-4a57-9a9d-eabdfb0a893f",
        "data_schema_uuid": "254c29ba-bbdc-44da-9d7a-fc899cd97a57",
        "data": {
          "tsId": "8116ee42-eaa1-4734-acde-57eb58fe0e2d",
          "organizationId": "99f23c52-e8e3-413e-8495-d65efc665b6d"
        }
      }
    ],
    "tags": ["ris", "134-3_OG_1/421.0", "Trockenabsaugung_Ventilator"]
  }
]

Pre-defined JSON files:

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.