Print bookPrint book

Guide for Extensions

Issues like getting aligned with FIESTA-IoT’s semantic data models, testbed and resource registration, send data/observations and testbed management are explained in detail here.

Site: FIESTA-IoT Training Platform
Course: Guide for 3rd Parties
Book: Guide for Extensions
Printed by: Guest user
Date: Monday, 22 May 2017, 9:22 PM

1 Getting aligned with FIESTA-IoT’s semantic data models

When it comes to put your testbed into the FIESTA-IoT federation, it is deemed necessary to get aligned to the data model (i.e. ontology) we have defined under the umbrella of the whole project. Otherwise, you will not be able to put your data into our repositories, since it will not pass the validation stage (nor the testbed registration module beforehand). As a direct consequence, as a testbed administrator, you will have to undertake the role of adapting your datasets into the semantically annotated formats that have been shaped up in our project.

Before going any further, we strongly recommend that you take a look at the ontology’s webpage and the deliverable responsible for digging into its depths: (FIESTA-IoT D3.1, 2016).

Moreover, we include herewith the raw graph that depicts the ontology:

FIESTA-IOT ONTOLOGY

1.1 FIESTA-IoT ontology alignment phase

It is worth highlighting that this ontology is the outcome of a thorough tailoring process from all the different platforms that were part of the FIESTA-IoT’s initial line-up, i.e. SmartSantander (Spain), Smart ICS (UK), Com4Innov (France) and KETI (South Korea). Amongst all their assets, where sensors stand out as the dominant realm, we have outlined the most appropriate means of how to describe a single resource, focusing on the essential parts that must be defined in every one, i.e. physical location, owner (testbed), sensor or sensors that are embedded in that concrete resource and their respective quantity kind and units. Aside these key concepts, you can see in the graph another set of nodes that hold a secondary level of information, like VirtualEntity, Coverage or Source, just to cite a few.

They are addressed to describe additional information about the resources, though they are not strictly necessary. Moreover, there is a Metadata class (right side of the figure), where any kind of information could be appended, thus opening the ontology to non-foreseen items (for instance, if a sensor follows a synchronous operation, we might want to represent its frequency or rate, said in other words, the time between consecutive observations).

Having said this, bear in mind that the current version of the ontology is clearly biased towards the sensor realm, as we have only nailed down the details of ssn:SensingDevice downwards. Yet we have introduced the concepts of actuating and tag devices, we have not thoroughly dived into the details.

Together with the part in charge of the description of the resources, we have modelled how an observation harvested by one of these sensors would look like. Essentially, it answer the following questions: who (sensor that has actually measured the observation), where (physical location of the sensor), when (timestamp of the observation), what (quantity kind and unit of measurement of the observation) and last, and the most important, the value of the observation itself.

1.2 M3-lite taxonomy alignment phase

An essential part of the solution we have brought about is the gathering of the set of capabilities covered between the four heterogeneous testbeds, giving rise to a standalone taxonomy that spans all the quantity kinds, units of measurement and domains of interest of the different sensing devices (i.e. sensors).

As we have mentioned before, it is strongly recommendable to go over this taxonomy and double check that all your assets actually match the concepts we have already defined. It goes without saying that, despite covering a wide range of sensor types and domains of interest, you might have different stuff than that of we have contemplated so far. In such a case, the first thing you would have to do is to inform us, digging into the corresponding details, so as to let us know your new requirements. With this information, we could modify the taxonomy and append your new elements.

1.3 FIESTA-IoT Amendment proposals

As can be easily inferred from the two previous sections, the solution we are proposing for the semantic annotation of IoT resources might not fulfil everybody’s needs.


Recall that the ontology is a living entity and is prone to be modified throughout the upcoming months, either by ourselves (the FIESTA-IoT consortium) or upon requests coming from externals. Your platform(s) might own some elements that have not been envisaged or covered by our latest stable version.

Therefore, we might need to upgrade it in order to suit them. Then, what you would have to do is to put in contact with us in order to double check whether your stuff are worth modifying the picture or not. In essence, these changes might belong either to the ontology itself or to the m3-lite taxonomy, where these latter ones pertain to the concepts of quantity kinds, units of measurement or domains of interest.


The following list represents the fields that you have to fill for every elements you want to bring to the ontology/taxonomy:

  • Need: Type of entity/class/concept you are about to define.
  • Legacy FIESTA-IoT: In case your proposal matches with any in FIESTA, specify it.
  • Name: Your proposed name.
  • Comment: Provide a description of what you are proposing.
  • SubclassOf: If the element is a subclass of any other, specify its parent. Otherwise, we assume that you inherit from ssn:SensingDevice (as most of the proposals will have to do with updates to the taxonomy).
  • rdfs:isDefinedBy or rdfs:seeAlso. Provide any existing reference to your proposal in case you have borrowed the concept from another existing ontology.
  • Justification for addition: Provide justification on why do you need it and if there is a near match in the Taxonomy.



Apart from the list above, in case you do want to make any change to the ontology, you have to provide also a modified picture of it including your stuff and the way it is connected with the rest of the classes. This would help us identify and determine whether its addition is welcome or not.
Last, but not least, this is an exercise that shall be tackled in the initial phase of your 6 months. Thus, we have set a deadline till which you can send us your proposals.

1.4 Implementation of Testbed to FIESTA-IoT annotators

After having defined all the mappings between your platform’s assets (both in terms of resource descriptions and observations), including the possible modifications that may be brought about on the ontology, it is time to talk about the implementation of the annotator between your datasets and those of FIESTA-IoT.

For that, you can choose among a number of different RDF serialization formats, as the ones listed below (annotated according to the “Content-type” field of the HTTP header):

  • application/ld+json
  • application/n-quads
  • application/n-triples
  • application/n3
  • application/rdf+json
  • application/rdf+thrift
  • application/rdf+xml
  • application/trig
  • application/trix
  • application/trix+xml
  • application/turtle
  • application/x-trig
  • application/x-turtle
  • null/rdf
  • text/csv
  • text/n-quads
  • text/n3
  • text/nquads
  • text/plain
  • text/rdf+n3
  • text/trig
  • text/turtle

In order to show you a pragmatic example of how to annotate a resource or an observation, in the following notes we have included an illustrative example of one of the SmartSantander’s resources, using json-ld as the serialization format. Besides, you can dynamically query another content type by means of the IoT-Registry API (FIESTA-IoT Consortium, 2016).

In case you want to check whether your annotations are compliant with our ontology, you can use the FIESTA-IoT Ontology Validator (for resource or observation) to receive a real-time validation report. Moreover, in case your annotated document does not 100% match the correct format, this report not only return the binary correct/error output, but also a detailed explanation of the actual source(s) of the error(s).

 

Notes:

Resource description:

{

  "@context": {

    "owl": "http://www.w3.org/2002/07/owl#",

    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",

    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",

    "rdfa": "http://www.w3.org/ns/rdfa#",

    "xhv": "http://www.w3.org/1999/xhtml/vocab#",

    "xml": "http://www.w3.org/XML/1998/namespace",

    "xsd": "http://www.w3.org/2001/XMLSchema#",

    "dul": "http://www.loa.istc.cnr.it/ontologies/DUL.owl#",

    "ssn": "http://purl.oclc.org/NET/ssnx/ssn#",

    "iot-lite": "http://purl.oclc.org/NET/UNIS/fiware/iot-lite#",

    "geo": "http://www.w3.org/2003/01/geo/wgs84_pos#",

    "time": "http://www.w3.org/2006/time#",

    "qu-unit": "http://purl.oclc.org/NET/ssnx/qu/unit#",

    "qu-quantity": "http://purl.oclc.org/NET/ssnx/qu/quantity#",

    "m3-lite": "http://purl.org/iot/vocab/m3-lite#",

    "sms-srd": "http://api.smartsantander.eu#",

    "sms-srd-href": "http://api.smartsantander.eu/v2/resources/"

  },

  "@graph": [

    {

      "@id": "sms-srd:SmartSantanderTestbed",

      "@type": "ssn:Deployment"

    },

    {

      "@id": "sms-srd:platform.urn:x-iot:smartsantander:u7jcfa:t3230",

      "@type": "ssn:Platform",

      "geo:location": {

        "@id": "sms-srd:location.urn:x-iot:smartsantander:u7jcfa:t3230"

      }

    },

    {

      "@id": "sms-srd:location.urn:x-iot:smartsantander:u7jcfa:t3230",

      "@type": "geo:Point",

      "geo:lat": {

        "@type": "xsd:float",

        "@value": "43.46769"

      },

      "geo:long": {

        "@type": "xsd:float",

        "@value": "-3.81217"

      }

    },

    {

      "@id": "sms-srd-href:urn:x-iot:smartsantander:u7jcfa:t3230",

      "@type": "ssn:Device",

      "ssn:hasDeployment": {

        "@id": "sms-srd:SmartSantanderTestbed"

      },

      "ssn:hasSubSystem": [

        {

          "@id": "sms-srd:urn:x-iot:smartsantander:u7jcfa:t3230.batteryLevel.sensor"

        },

        {

          "@id": "sms-srd:urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor"

        },

        {

          "@id": "sms-srd:urn:x-iot:smartsantander:u7jcfa:t3230.relativeHumidity.sensor"

        }

      ],

      "ssn:onPlatform": {

        "@id": "sms-srd:platform.urn:x-iot:smartsantander:u7jcfa:t3230"

      }

    },

    {

      "@id": "sms-srd:service.urn:x-iot:smartsantander:u7jcfa:t3230.batteryLevel.sensor",

      "@type": "iot-lite:Service",

      "iot-lite:endpoint": {

        "@type": "xsd:anyURI",

        "@value": "https://api-dev.smartsantander.eu:10443/v2/measurements/batteryLevel/urn/urn:x-iot:smartsantander:u7jcfa:t3230/last?format=jsonld"

      },

      "iot-lite:interfaceType": "REST"

    },

    {

      "@id": "sms-srd:urn:x-iot:smartsantander:u7jcfa:t3230.batteryLevel.sensor",

      "@type": "m3-lite:ElectricalSensor",

      "iot-lite:exposedBy": {

        "@id": "sms-srd:service.urn:x-iot:smartsantander:u7jcfa:t3230.batteryLevel.sensor"

      },

      "iot-lite:hasQuantityKind": {

        "@id": "sms-srd:quantity.urn:x-iot:smartsantander:u7jcfa:t3230.batteryLevel.sensor"

      },

      "iot-lite:hasUnit": {

        "@id": "sms-srd:unit.urn:x-iot:smartsantander:u7jcfa:t3230.batteryLevel.sensor"

      }

    },

    {

      "@id": "sms-srd:quantity.urn:x-iot:smartsantander:u7jcfa:t3230.batteryLevel.sensor",

      "@type": "m3-lite:BatteryLevel"

    },

    {

      "@id": "sms-srd:unit.urn:x-iot:smartsantander:u7jcfa:t3230.batteryLevel.sensor",

      "@type": "m3-lite:Percent"

    },

    {

      "@id": "sms-srd:service.urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor",

      "@type": "iot-lite:Service",

      "iot-lite:endpoint": {

        "@type": "xsd:anyURI",

        "@value": "https://api-dev.smartsantander.eu:10443/v2/measurements/temperature:ambient/urn/urn:x-iot:smartsantander:u7jcfa:t3230/last?format=jsonld"

      },

      "iot-lite:interfaceType": "REST"

    },

    {

      "@id": "sms-srd:urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor",

      "@type": "m3-lite:AirThermometer",

      "iot-lite:exposedBy": {

        "@id": "sms-srd:service.urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor"

      },

      "iot-lite:hasQuantityKind": {

        "@id": "sms-srd:quantity.urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor"

      },

      "iot-lite:hasUnit": {

        "@id": "sms-srd:unit.urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor"

      }

    },

    {

      "@id": "sms-srd:quantity.urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor",

      "@type": "m3-lite:TemperatureAmbient"

    },

    {

      "@id": "sms-srd:unit.urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor",

      "@type": "m3-lite:DegreeCelsius"

    },

    {

      "@id": "sms-srd:service.urn:x-iot:smartsantander:u7jcfa:t3230.relativeHumidity.sensor",

      "@type": "iot-lite:Service",

      "iot-lite:endpoint": {

        "@type": "xsd:anyURI",

        "@value": "https://api-dev.smartsantander.eu:10443/v2/measurements/relativeHumidity/urn/urn:x-iot:smartsantander:u7jcfa:t3230/last?format=jsonld"

      },

      "iot-lite:interfaceType": "REST"

    },

    {

      "@id": "sms-srd:urn:x-iot:smartsantander:u7jcfa:t3230.relativeHumidity.sensor",

      "@type": "m3-lite:HumiditySensor",

      "iot-lite:exposedBy": {

        "@id": "sms-srd:service.urn:x-iot:smartsantander:u7jcfa:t3230.relativeHumidity.sensor"

      },

      "iot-lite:hasQuantityKind": {

        "@id": "sms-srd:quantity.urn:x-iot:smartsantander:u7jcfa:t3230.relativeHumidity.sensor"

      },

      "iot-lite:hasUnit": {

        "@id": "sms-srd:unit.urn:x-iot:smartsantander:u7jcfa:t3230.relativeHumidity.sensor"

      }

    },

    {

      "@id": "sms-srd:quantity.urn:x-iot:smartsantander:u7jcfa:t3230.relativeHumidity.sensor",

      "@type": "m3-lite:RelativeHumidity"

    },

    {

      "@id": "sms-srd:unit.urn:x-iot:smartsantander:u7jcfa:t3230.relativeHumidity.sensor",

      "@type": "m3-lite:Percent"

    }

  ]

}

Observation description:

{

  "@context": {

    "owl": "http://www.w3.org/2002/07/owl#",

    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",

    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",

    "rdfa": "http://www.w3.org/ns/rdfa#",

    "xhv": "http://www.w3.org/1999/xhtml/vocab#",

    "xml": "http://www.w3.org/XML/1998/namespace",

    "xsd": "http://www.w3.org/2001/XMLSchema#",

    "dul": "http://www.loa.istc.cnr.it/ontologies/DUL.owl#",

    "ssn": "http://purl.oclc.org/NET/ssnx/ssn#",

    "iot-lite": "http://purl.oclc.org/NET/UNIS/fiware/iot-lite#",

    "geo": "http://www.w3.org/2003/01/geo/wgs84_pos#",

    "time": "http://www.w3.org/2006/time#",

    "qu-unit": "http://purl.oclc.org/NET/ssnx/qu/unit#",

    "qu-quantity": "http://purl.oclc.org/NET/ssnx/qu/quantity#",

    "m3-lite": "http://purl.org/iot/vocab/m3-lite#",

    "sms-srd": "http://api.smartsantander.eu#",

    "sms-srd-href": "http://api.smartsantander.eu/v2/resources/"

  },

  "@graph": [

    {

      "@id": "_:b66",

      "@type": "ssn:Observation",

      "ssn:observationResult": {

        "@id": "_:b69"

      },

      "ssn:observationSamplingTime": {

        "@id": "_:b67"

      },

      "ssn:observedBy": {

        "@id": "sms-srd:urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor"

      },

      "ssn:observedProperty": {

        "@id": "sms-srd:quantity.urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor"

      },

      "geo:location": {

        "@id": "_:b68"

      }

    },

    {

      "@id": "sms-srd:quantity.urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor",

      "@type": "m3-lite:TemperatureAmbient"

    },

    {

      "@id": "_:b67",

      "@type": "time:Instant",

      "time:inXSDDateTime": {

        "@type": "xsd:dateTime",

        "@value": "2016-03-08T17:41:40.853Z"

      }

    },

    {

      "@id": "_:b68",

      "@type": "geo:Point",

      "geo:lat": {

        "@type": "xsd:float",

        "@value": 43.46769

      },

      "geo:long": {

        "@type": "xsd:float",

        "@value": -3.81217

      }

    },

    {

      "@id": "_:b69",

      "@type": "ssn:SensorOutput",

      "ssn:hasValue": {

        "@id": "_:b70"

      }

    },

    {

      "@id": "_:b70",

      "@type": "ssn:ObservationValue",

      "iot-lite:hasUnit": {

        "@id": "sms-srd:unit.urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor"

      },

      "dul:hasDataValue": {

        "@type": "xsd:float",

        "@value": 9.95

      }

    },

    {

      "@id": "sms-srd:unit.urn:x-iot:smartsantander:u7jcfa:t3230.temperature-ambient.sensor",

      "@type": "m3-lite:DegreeCelsius"

    }

  ]

}

1.5 Annotator as a Service (iot-registry utils)

Aside the option of designing and developing the whole annotator module on your own and deploy it at the tested level, we have come up with another alternative, based on the usage of an annotator-as-a-service-like operation. This way, through one of the set of tools included in the iot-registry API (FIESTA-IoT Consortium, 2016), you could straightforwardly pass from your legacy documents to FIESTA-IoT’s.

In a nutshell, you can generate annotated documents just by sending simple JSON objects to the corresponding endpoints that are resumed in following tables. However, bear in mind that the nature between these web services is to provide a generic way to annotate resources, so complex descriptions might not be suited through this approach. It goes without saying that for these cases, you would have to carry out the annotator on your own.

Testbed description generation through the annotator service:

https://platform.fiesta-iot.eu/utils/annotator/testbed

Method

Description

Request Body (example)

POST

Service to generate a semantically annotated testbed document (with or without subjacent resources)

{

  "id": <Testbed IRI (string)>,

  "devices": [

    {

      "id": <Device 1 unique ID (string)>,

      "location": {

        "lat": <Latitude (double)>,

        "lon": <Longitude (double)>

      },

      "sensing_devices": [

        {

          "id": <Device 1 Sensor 1 unique ID (string)>,

          "qk": <m3-lite’s QuantityKind (string)>,

          "uom": <m3-lite’s Unit (string)>

        },

        {

          "id": < Device 1 Sensor 2 unique ID (string)>,

          "qk": <m3-lite’s QuantityKind (string)>,

          "uom": <m3-lite’s Unit (string)>        }

      ]

    },

    {

      "id": <Device 2 Sensor 1 unique ID (string)>,

      "location": {

        "lat": <Latitude (double)>,

        "lon": <Longitude (double)>

      },

      "type": "AirThermometer",

      "qk": "TemperatureAmbient",

      "uom": "DegreeCelsius"

    }

  ]

}

Resource description generation through the annotator service:

https://platform.fiesta-iot.eu/utils/annotator/device

Method

Description

Request Body (example)

POST

Service to generate a semantically annotated resource document 

{

  "id": <Device i unique ID (string)>,

  "location": {

    "lat": <Latitude (double)>,

    "lon": <Longitude (double)>

  },

  "sensing_devices": [

    {

      "id": <Device i Sensor 1 unique ID (string)>,

      "qk": <m3-lite’s QuantityKind (string)>,

      "uom": <m3-lite’s Unit (string)>

    },

    {

      "id": <Device i Sensor 2 unique ID (string)>,

      "qk": <m3-lite’s QuantityKind (string)>,

      "uom": <m3-lite’s Unit (string)>

    }

  ]

}

Observation description generation through the annotator service:

https://platform.fiesta-iot.eu/utils/annotator/observation

Method

Description

Request Body (example)

POST

Service to generate a semantically annotated observation document 

{

  "observed_by": <Sensor unique ID (string)>,

  "location": {

    "lat": <Latitude (double)>,

    "lon": <Longitude (double)>

  },

  "quantity_kind": "TemperatureAmbient",

  "value": <Value>,

  "format": <Type (integer, float, etc.)>,

  "unit": <m3-lite’s Unit (string)>,

  "timestamp": <Date>

}

As for the responses, the iot-registry module can return them in the same formats as the ones enumerated in Section 1.4.

The Testbed Registration UI can be found at the FIESTA-IoT portal under the Testbed Provider Menu (see 1st Figure below) item named the “Register Testbed”. 

Register Testbed page (see 2nd Figure below) will show the list of registered testbeds and enable user to Register a new testbed. The admin user can view all the registered testbeds, whereas the testbed providers only see their own testbeds that they have registered.

The use can register a new testbed by clicking “Register new testbed” button, a register testbed page (see 3rd Figure)  will be shown where the user inputs testbed related information:

  • Input IRI this is unique for each registered testbed.
  • Input Annotated Resource Observation, Annotated Resource Description user must specify data format by selecting a format from combo-box list.
  • User can validate resource observation and resource description by click validate button.
  • User must input latitude, longitude
  • Other remain textbox are optional

When the user clicks save button, if the registration process is successful the register testbed page will disappear and a success message is displayed along with the identifier of the registered testbed.

2 Resource registration

Once your testbed has become part of the FIESTA-IoT federation, you are ready to start registering your assets. To do so, what you have to do is to upload (send) valid FIESTA-IoT-compliant resource description documents (could be more than one in the very same document. After registering a testbed with specified IRI, a user can use this IRI for registering resources related to the testbed. Register Resources can be found at the FIESTA-IoT portal under the Testbed Provider Menu item named the “Register Resources”.

Once the user chooses this option, resource registration can be done through three options (see following Figure):

  • Register Devices Manual,
  • Register Device by Text,
  • Register Devices by Upload.

2.1 Register Devices Manual

When registering devices manual, the user must select a testbed (IRI) for which the he/she wants to register devices manual (see 1st Figure).

After selecting the registered testbed IRI, user clicks on ‘Register Devices manual’ button and a form is displayed (see 2nd Figure).

After entering the information related to device manual the user clicks the save button to complete the devices manual registration process. Upon success, the user will return back the main options window of ‘Register Resources’ (see 3rd Figure below).

2.2 Register Devices by text

When registering devices by text, the user must specify the format and then input the text into the text-area (see 1st Figure).

After providing the text for registering a device, the user click the save button. Upon success, the user will return back the main options window of ‘Register Resources’ (see 2nd Figure below).

2.3 Register Devices by Upload

When registering devices by Upload, the user must select the format of the document and then upload the file to register resource (see 1st Figure). The current max size of the file upload is set to 10MB.

The system will only register resources after validating the document. If the process was success on save, the window register by upload will disappear and user will return to Register Resources page with green message (see 2nd Figure below).

3 Testbed Provider Services (Testbed to FIESTA-IoT)

In this subchapter you can find relevant information about the four following topics:

  1. Configuration and Runtime Sequence example,
  2. TPS API Definition,
  3. TPS Implementation (Wildfly Container) and
  4. Testbed Configuration management

3.1 Configuration and Runtime Sequence example

The required steps and interactions between the Testbed provider and the different FIESTA-IoT components in order to set up and integrate a Testbed to the system is depicted in 1st Figure to 5th Figure below.

Where we can see the Testbed & Resource registration and the TPI configuration and runtime. For the Testbed setup we presume that the Testbed Provider has already generated the Data Semantic Annotator and initiated an instance of the Testbed Provider Interface for his/her Testbed.

For the Testbed Registration as depicted in 5th Figure:

  1. The first step is to open the Testbed Registration UI (preferably thru the FIESTA-IoT portal). If the Testbed Provider is not logged in yet the User credential will be requested to be entered.
  2. The credentials are forwarded to the Security component where a SSO token id is generated and send back to the container (browser) that the Testbed Registration UI is opened from.
  3. This SSO token id is then used from the Testbed Registration UI in order to retrieve from the security module information like the UserID, User role etc.
  4. With the user ID Testbed Registration UI is now contacting Testbed Registration Data Storage (TRR) in order to retrieve potentially other Testbeds info that have already been registered from the specific Testbed Provider (by UserID).
  5. The Testbed Provider now initiates the process of registering a new Testbed.
  6. An already annotated resource script has to be entered to the form in order to be validated.
  7. The resource script is send from the Testbed Registration UI to the Validator component and a report is generated with a success or no success message from it.
  8. The rest of the Testbed information are entered to the Testbed Registration UI form like the Testbed’ s TPS endpoints along with the API key (if it exists).
  9. By hitting the register button the information are stored both on the Testbed Registration data storage (TRR) and the Resource Registry data storage (IoT Registry) depending on the non-semantic or semantic nature of it.

An equivalent process for the Resource registration shall be followed and is depicted in 2nd Figure below:

  1. The first step is to open the Resource Registration UI (preferably thru the FIESTA-IoT portal). If the Testbed Provider is not logged in yet the User credential will be requested to be entered and the next two steps are the same as step 2 and 3 of the Testbed Registration Sequence above.
  2. With the user ID the Resource Registration UI is now contacting Testbed Registration Data Storage (TRR) in order to retrieve all the testbeds registered from the specific Testbed Provider (by UserID).
  3. The Testbed Provider can now choose the Testbed of interest from the presented list. If no testbed is registered yet then the Testbed registration process should be followed to register one.
  4. With the Testbed ID the Resource Registration UI is now contacting Testbed Registration Data Storage (TRR) in order to retrieve potentially other resource info that have already been registered for the specific Testbed.
  5. The Testbed Provider can now initiate the process of registering a new Resource.
  6. An already annotated resource script has to be entered to the form in order to be validated.
  7. The resource script is send from the Resource Registration UI to the Validator component and a report is generated with a success or no success message from it.
  8. The rest of the Resource information are entered to the Resource Registration UI form.

By hitting the register button the information are stored both on the Testbed Registration data storage (TRR) and the Resource Registry data storage (IoT Registry) depending on the non-semantic or semantic nature of it.

Now we can move to the TPI Configuration sequence shown in 3rd Figure below:

  1. The first step is to open the TPI Configuration UI (preferably thru the FIESTA-IoT portal). If the Testbed Provider is not logged in yet the User credential will be requested to be entered and the next two steps are the same as step 2 and 3 of the Testbed Registration Sequence above.
  2. With the user ID the Resource Registration UI is now contacting Testbed Registration Data Storage (TRR) in order to retrieve all the testbeds registered from the specific Testbed Provider (by UserID).
  3. The Testbed Provider can now choose the Testbed of interest from the presented list. If no testbed is registered yet then the Testbed registration process should be followed to register one.
  4. When the Testbed Provider picks a Testbed ID the TPI Configuration UI contacts the Resource Registry Data storage (IoT-Registry) in order to retrieve the list of registered resources for the specific testbed. If there are no registered resources the user should follow the Resource registration process to register some.
  5. The User can choose a list of resources to set up, identify an execution schedule and choose the TPS retrieval method (i.e. getObservation). Finally all these info can be sent to the DMS in order to start a scheduled job which is going to retrieve the annotated measurements from the TPS and forward them to the FIESTA-IoT platform (which is described below).

Finally, a runtime sequence of acquiring the annotated measurements and forwarding them to the FIESTA-IoT platform is depicted in 4th Figure below. In this example, we presume that the testbed TPS instance has been implemented and exposes the “getObservations” services, which provides the FIESTA-IoT annotated measurements of a given list of resources for a specific time period. 

  1. After successfully initiating a DMS scheduled job as described in the sequence diagram above the DMS scheduler enters a loop with the identified time period from the Testbed provider. In every loop the DMS sends a message to the identified Testbed TPS with a list of resource IDs and a timeperiod (from->to time) that the TPS needs to produce the annotated measurements.
  2. TPS replies back to DMS with an FIESTA-IoT annotated document with all the requested measurements.
  3. DMS collects this document and forwards it along with the annotation type to the Message Bus under a specific topic.
  4. In the meantime the Message Bus Dispatcher (MBD) has subscribed to the above topic so every time something is published to it the MBD gets informed and receives the message which was pushed to the Message Bus from the DMS.

 The collected annotated document is now pushed to the Validator and if the document is semantically and syntactically valid is forwarded to the Meta-Cloud Data storage (IoT-Registry) for storage.

3.2 TPS API Definition

The 1st Table below illustrates the main API primitives that support the Testbed Provider Services functionalities, while 2nd Table provides more details about each one of the functions that comprise the API.

List of primitives comprising the Testbed Provider Services API

<<interface>>

TpiServicesInterface

---

POST:getLastObservations (getLastObservationsPayload:JsonObject):List <SensorValue>

POST:getObservations (getObservationsPayload:JsonObject):List <SensorValue>



A Testbed SHALL implement methods of the Testbed Provider Services API as specified in 2nd Table below:

Testbed Provider Services API definition

Service Name

Input

Output

Info

getLastObservations

JsonObject getLastObservationsPayload

List <SensorValue>

This service provides the latest values of a specific Sensor list.

getObservations

JsonObject  getObservationsPayload

List <SensorValue>

This service provides the values of a specific Sensor list for a specific time period once.



Object Definition

The analysis of the JSON objects that are introduced in the previous section is provided below:

Definition of getLastObservationsPayload object:

{

    "sensorIDs": [<String> sensorIDs]

}

 

Definition of getObservationsPayload object:

{

     "sensorIDs": [<String> sensorIDs],

     "startDate": <Date> startDate,

     "stopDate": <Date> stopDate

}

Note: the Date has the following format "yyyy-MM-ddThh:mm:ss" and the start date precedes the stop date in time. If the startDate and the stopDate appear in other format, they have to be converted to the above one.

3.3 TPS Implementation (Wildfly Container)

A TPS instance may be implemented in any language and or environment the Testbed provider chooses to as long as it follows the above API as a REST web service. Shall you choose to implement it in Java we provide a skeleton Java project in order to help you bootstrap the process. Information where this project can be found and to be used is provided in the following sections.



Code Availability and Structure

The Testbed Provider Interface components are offered at FIESTA-IoT GitHub repository, which can be found here: https://github.com/fiesta-iot. The latest version of the components are under the “develop branch”.

The project is divided into two main packages. The “eu.fiestaiot.tpi.api.tps.rest” and “eu.fiestaiot.tpi.api.tps.impl.dataservices”:

eu.fiestaiot.tpi.api.tps.rest

Within this package, the “TpiApiTestbedProviderServices.java”[1]  class can be found which is the entry point for the Services described at the TPS API above.

The two main methods of interest are:

  • public Response getLastObservations(String getLastObservationsPayload)
  • public Response getObservations(String getObservationsPayload)

These methods analyse the payload and forwards it to the implementation of them, which resides in the following package.

eu.fiestaiot.tpi.api.tps.impl.dataservices

In this package, we have a list of the implementations classes of the different web services exposed from the TPS instance. The Testbed provider needs to implement at least one of them. The two classes are:
  • GetLastObservationsImpl.java[2]
  • GetObservationsImpl.java[3]


System Requirements

The TPS component described above is deployed within a WildFly container and is using Maven as project management.

The prototype runs on Windows, Linux, Mac OS X, and Solaris. In order to run the prototype, you need to ensure that Java 8 and WildFly are installed and/or available on your system. In order to build the prototype you will also need Maven. Before attempting to deploy and run the prototype applications, make sure that you have started WildFly. More details about the specific versions of the tools and libraries that have been used for the development or that are required for the deployment and execution of the prototypes are given in the section below.



Install & Run

The prototype has been implemented as a Maven-based web application. Below WILDFLY_HOME indicates the root directory of the WildFly distribution, and PROJECT_HOME indicates the root directory of the project.

In order to configure the prototype,

  1. make sure that all properties listed in $PROJECT_HOME/src/main/resources/fiesta-iot.properties have the appropriate values,
  2. copy that file into $WILDFLY_HOME/standalone/configuration, and
  3. issue the following commands:

In order to build the prototype, run the following command in PROJECT_HOME:

mvn clean package

Finally, in order to deploy the prototype, run the following command in PROJECT_HOME:

mvn wildfly:deploy
The last step assumes that WildFly is already running on the machine where you run the command.
The produced (from the build process above) project is the tpi.api.tps-X.war file. Alternatively copy the produced (from the build process above) ProjectName.war file from the target directory ($PROJECT_HOME/target/), into the standalone/deployments directory of the WildFly distribution, in order to be automatically deployed.

If the deployment has been successfully completed, you will be able to access all web services described in the section above using the following URLs:

  • http://[HOST]:[PORT]/tpi.api.tps/rest/tps/getLastObservations
  • http://[HOST]:[PORT]/tpi.api.tps/rest/tps/getObservations
where [HOST] is the host and [PORT] the port that WildFly uses.




[1] /tpi.api.tps/src/main/java/eu/fiestaiot/tpi/api/tps/rest/TpiApiTestbedProviderServices.java

[2] /tpi.api.tps/src/main/java/eu/fiestaiot/tpi/api/tps/impl/dataservices/GetLastObservationsImpl.java

[3] /tpi.api.tps/src/main/java/eu/fiestaiot/tpi/api/tps/impl/dataservices/GetObservationsImpl.java

3.4 Testbed Configuration management

In this section, we are going to introduce the User Interface that is provided by FIESTA-IoT in order to facilitate the testbed provider manage the testbed behaviour with the FIESTA-IoT platform. FIESTA-IoT offers a TPI configuration UI that enables the testbed provider to discover the semantically registered resources of his/her testbed, by utilizing the IoT-Registry services. Moreover, it manages the data retrieval process, by utilizing the TPI DMS services.

The TPI Configurator UI can be found at the FIESTA-IoT portal under the Testbed Provider Menu (see 1st Figure below) by clicking the “TPI Configurator”.

As soon as the tool opens it identifies the user and automatically searches for Testbeds bound with the logged-in User ID. The available testbeds are listed at the Testbed dropdown list of the tool’s Discovery tab (see 2nd Figure below).

When a testbed is chosen the registered resources appear at the resource list where the user can select in order to proceed with their data retrieval scheduling (see 2nd Figure above and 3rd Figure below) by hitting next.

The Testbed provider can now define a specific schedule to retrieve their measurements. This is achieved by defining it in the “Schedule” tab as shown in 4th Figure below. In the schedule tab the user can specify the properties of the schedule to be defined and these are:

  • a name for the schedule,
  • to choose the Testbed ‘s exposed service (TPS) (see 4th Figure below) that has already been defined in the Testbed registration process. This Testbed URI will expose one of the TPS services (i.e. get observation, push observation etc.),

  • Select the Security Key (see 5th Figure below), identified in the Testbed registration process, in order to access the Testbed URI above and

  • To specify a timeschedule (if the get methodology for TPS has been implemented) for the daretrieval (get) to be executed from the DMS to TPS component. This is achieved by identifying:
    • The start time (optional): which defines a historical date in order to adittionally retrieve historical measurements for a resource (i.e. to retrieve the data from last month set the start time date 30 days in the past). Note that this feature is not curently implemented.
    • The frequency and the time unit of it which defines the periodicity frequency of the measurements retrieval (get) from the Testbed’s TPS.

After completing the required flow and the definition of the requested properties, the testbed provider needs to hit the schedule button (see 6th Figure below) to initiate both the equivalent service of the TPI DMS and the process of pushing data to FIESTA-IoT platform or retrieving data from the Testbed (depending on the TPS service implemented from the Testbed TPS).

This step will take the Testbed Provider to the status tab (see 7th Figure below) where an overview of all the scheduled jobs can be found. In case the Experimenter needs to stop a job the job should be picked from the Status list and the stop button should be clicked (see 7th Figure below). This stops the schedule for the specific job of retrieving measurements from TPS (in case the get method has been implemented) or instructs TPS to stop pushing measurements to DMS (in case the push methodology was chosen).