Deliverable 3.1.b: BIG IoT API Design - Second Release

343 Pages·2017·4.06 MB·English

BIG IoT – Bridging the Interoperability Gap of the Internet of Things
Deliverable 3.1.b:
BIG IoT API Design - Second Release
Version 1.0
Delivery Date: 30.09.2017

This project has received funding from the European Union’s Horizon 2020 research and in-
novation program under grant agreement No 688038.
DELIVERABLE 3.1.B: BIG IOT API DESIGN - SECOND RELEASE D.3.1.B

Document Information
Responsible Person and Affiliation Siemens AG:
Andreas Ziller
Due Date / Delivery Date 30.09.2017
State Final Version
Reviewers Ernest Teniente (UPC)
Karina Rehfeldt (TUC)
Version 1.0
Confidentiality Public

Version Description of Changes Date of Resolution
0.1 Draft sent to reviewers 01.09.2017
0.9 RC sent to reviewers 17.09.2017
1.0 Document to be submitted 30.09.2017

List of Authors
Organization Authors Main organizations’ contributions
Bosch Stefan Schmid, Denis Kramer Chapter 2, 3
Econais Costas Pipilas Section 4.5
Siemens Andreas Ziller, Arne Bröring Chapter 1, 3, 4, 5

© 2017 2
DELIVERABLE 3.1.B: BIG IOT API DESIGN - SECOND RELEASE D.3.1.B

Abbreviations
Abbreviation Meaning
A1 Access Interface #1
API Advanced Programming Interface
BCN Barcelona (pilot)
BIG IoT Project title: Bridging the Interoperability Gap of the Internet of Things
DOA Description of Action
HTTP Hypertext Transfer Protocol
ID Identifier
IoT Internet of Things
IP Internet Protocol
ISO International Organization for Standardization
JAR Java Archive
JSON JavaScript Object Notation
MQTT Message Queue Telemetry Support
MS Milestone
NAT Network Address Translation
NG Northern Germany (pilot)
OD Offering Description
OGC Open Geospatial Consortium
P1 Programming Interface #1
P2 Programming Interface #2
P3 Programming Interface #1
PIE Piedmont (pilot)
RDF Resource Description Framework
REST Representational State Transfer
© 2017 3
DELIVERABLE 3.1.B: BIG IOT API DESIGN - SECOND RELEASE D.3.1.B

SDK Software Development Kit
SES Sensor Event Service
SOS Sensor Observation Service
SPARQL SPAQRL Protocol and RDF Query Language
SPS Sensor Planning Service
SWE Sensor Web Enablement
TCP Transmission Control Protocol
UI User Interface
URI Uniform Resource Identifier
URL Uniform Resource Locator

© 2017 4
Deliverable 3.1.b – BIG IoT API Design D3.1.b

Table of Contents
Summary.................................................................................................................................................. 8
1. Introduction ...................................................................................................................................... 9
1.1. Motivation ..................................................................................................................................... 9
1.2. Relation to other Deliverables ..................................................................................................... 10
2. BIG IoT API in context of the High-Level Architecture ..................................................................... 13
2.1. Core Concepts of the BIG IoT Architecture ................................................................................. 13
2.2. BIG IoT Architecture Overview .................................................................................................... 15
2.3. Interfaces and Interactions ......................................................................................................... 17
3. BIG IoT API Tutorial ......................................................................................................................... 19
3.1. Installation of the Tooling ........................................................................................................... 19
3.2. Setting up an Example ................................................................................................................. 20
3.3. BIG IoT from a Provider's Perspective ......................................................................................... 29
3.4. BIG IoT from a Consumer's Perspective ...................................................................................... 33
4. BIG IoT API Mechanisms ................................................................................................................. 47
4.1. Operations of BIG IoT Offerings .................................................................................................. 47
4.2. API mechanisms for Integration Mode 1 ..................................................................................... 48
4.3. API mechanisms for Integration Mode 2 ..................................................................................... 48
4.4. API mechanisms for Integration Mode 3 ..................................................................................... 63
4.5. API mechanisms for Integration Mode 4 ..................................................................................... 67
5. Conclusion & Outlook ..................................................................................................................... 70
References ............................................................................................................................................. 72
Appendix A UML Class Diagrams ............................................................................................................ 73
Appendix B BIG IoT API Documentation ................................................................................................. 77

© 2017 5
Deliverable 3.1.b – BIG IoT API Design D3.1.b

List of Figures
Figure 1 Relation of deliverables .............................................................................................. 11
Figure 2 Core architecture concepts and terminology ............................................................. 14
Figure 3 Building block view on BIG IoT architecture ............................................................... 16
Figure 4 Install Buildship Gradle Integration ............................................................................ 21
Figure 5 Eclipse Oxygen with fresh, empty workspace ............................................................ 22
Figure 6 Importing a Gradle project ......................................................................................... 23
Figure 7 Import Gradle Project Wizard .................................................................................... 23
Figure 8 Import Gradle Project Wizard - Setting project root directory ................................... 24
Figure 9 Dialog during Gradle build .......................................................................................... 24
Figure 10 Having the BIG IoT API imported in Eclipse .............................................................. 25
Figure 11 Login button on Marketplace ................................................................................... 26
Figure 12 Marketplace ............................................................................................................. 26
Figure 13 Add a provider .......................................................................................................... 27
Figure 14 Enter a provider name .............................................................................................. 27
Figure 15 Your screen after you created a provider ................................................................. 28
Figure 16 Add the provider ID .................................................................................................. 29
Figure 17 Typical workflow in integration mode 2 ................................................................... 49
Figure 18 Deployment example ............................................................................................... 50
Figure 19 Sequence diagram for offering access in integration mode 2 .................................. 51
Figure 20 Blocking call .............................................................................................................. 53
Figure 21 Non-blocking call ...................................................................................................... 54
Figure 22 Synchronous and asynchronous feeds ..................................................................... 58
Figure 23 Feeds in integration modes 1 and 3 ......................................................................... 59
Figure 24 Feeds in integration modes 2 ................................................................................... 59
Figure 25 Retrofitting synchronous feeds ................................................................................ 60
Figure 26 Retrofitting asynchronous feeds .............................................................................. 61
© 2017 6
Deliverable 3.1.b – BIG IoT API Design D3.1.b

Figure 27 Typical workflow in integration mode 3 ................................................................... 64
Figure 28 Proxy service integration in integration mode 4 ...................................................... 68
Figure 29 Integration mode 4 interactions ............................................................................... 69
Figure 30 Focus consumer ....................................................................................................... 73
Figure 31 Focus offering query ................................................................................................. 74
Figure 32 Focus offering ........................................................................................................... 75
Figure 33 Focus provider .......................................................................................................... 76

List of Tables
Table 1 Tools used for development of providers and consumers .......................................... 20
Table 2 A1-ACCESS specification .............................................................................................. 55
Table 3 A1-FEED specification .................................................................................................. 63
Table 4 API characteristics relevant for integration mode 3 .................................................... 67
© 2017 7
Deliverable 3.1.b – BIG IoT API Design D3.1.b

Summary
The deliverable D3.1.b is second version of the technical report for the BIG IoT API. It describes
the design and the underlying mechanisms of the BIG API. Furthermore, it gives a developer-
oriented tutorial for the utilization for the API functions.
The second version includes multiple changes since the initial version. So, the high-level ar-
chitecture (chapter 2) is updated with respect to recent findings in work package 2. The tuto-
rial chapter 3 is updated to cover the most recent version 0.9.4 of the BIG API. It includes an
improved start to end real world example for setting up a provider as well as a consumer
instance. The new lib support of integration mode 3 is now included chapter 4. In addition,
the conceptual mechanisms have been complemented with recent findings plus the chapter
is restructured in order to improve readability. The appendix is updated to the specification
of the most recent API version 0.9.4.
© 2017 8
Deliverable 3.1.b – BIG IoT API Design D3.1.b

1. Introduction
This chapter introduces to this deliverable, motivates the topic, and defines its scope.
1.1. Motivation
The idea of an Internet of Things is no more a futuristic vision, but indeed an increasing com-
mercial reality that reaches to various application domains ranging from quantified self and
smart home applications, over smarter cities and eHealth systems, to Industry 4.0. Dozens of
IoT platforms are upcoming. These include cloud solutions, such as Evrythng [1], ThingWorx
[2], Xively [3], or Yaler [4], but also on premise solutions such as Bosch’s IoT Suite [5], as well
as thematically or geographically focused platforms, such as the Smart Data platform for the
Piedmont region [6]. However, up to now, these IoT platforms failed to form vibrant IoT eco-
systems.
Currently, there is no vibrant collaborative IoT ecosystem, since the number of stakeholders
involved in IoT ecosystems (e.g., IoT platform providers, service and application providers) is
large, the market entry barriers are high, and the potential gain is low for a single stakeholder.
Providers of platforms and services require a simple, established way to offer access to their
resources. Marketplaces that enable providers to monetize access to the resources offered
by their platforms and services are not yet available. Once these marketplaces are estab-
lished, developers will be able to easily build IoT services and applications and build their
products around these. Revenue streams can then be shared across all contributing entities
(i.e., IoT platform and service providers). A key task of a marketplace is to provide extended
functionalities to enable the advertising, dynamic discovery, automated orchestration, and
negotiation of services to facilitate their usage.
However, before such marketplaces can bring their effect, a serious market barrier needs to
be tackled: the missing interoperability. The fragmentation of the IoT and the lack of interop-
erability prevent the emergence of broadly accepted IoT ecosystems [7]. A recent McKinsey
study [8] estimates that a 40% share of the potential economic value of the IoT directly de-
pends on interoperability between IoT platforms. Today, we are dealing with various vertically
oriented and mostly closed systems. Architectures for IoT are built on heterogeneous stand-
ards (e.g., IETF CoAP [9], OASIS MQTT [10], OMA LWM2M [11], OGC SWE [12], or OneM2M
[13]) or even proprietary interfaces. As a result, most existing and emerging IoT platforms
offer heterogeneous ways for accessing IoT resources.
© 2017 9
Deliverable 3.1.b – BIG IoT API Design D3.1.b

This causes interoperability problems when overarching, cross-platform, and cross-domain
applications are to be built, and eventually prevents the emergence of vibrant IoT ecosys-
tems. Additionally, it leads to barriers for business opportunities, especially for small innova-
tive enterprises, which cannot afford to offer their solution across multiple platforms. They
can only provide applications and services for a small number of platforms, e.g., a traffic in-
formation application for an IoT platform of a specific city. This lack of interoperability results
in lost business opportunities and prevents innovative business ideas.
In order to address these shortcomings in today's IoT landscape, the BIG IoT project has de-
veloped an architecture as a foundation for building IoT ecosystems (see D2.4). It overcomes
the above described hurdles through (1) a common API, (2) semantic descriptions of re-
sources and services, as well as (3) a marketplace as a nucleus of the ecosystem. This will
allow new services by combining data from multiple platforms (e.g., parking information from
various smart city platforms). In addition, platforms from multiple domains (e.g. home and
city) and regions will be combined, such that applications can utilize all relevant information
and work seamlessly across regions (e.g. the same smart parking application works on top of
a smart city platform in Berlin, in Barcelona and in London).
The scope of this document is the specification of the BIG IoT API. This BIG IoT API can be seen
from two complementary perspectives, as (1) a programming API implemented as libraries
(libs) of an SDK and (2) a web API. Both perspectives are covered in this document. The pro-
gramming API is provided to developers in order to facilitate the implementation of applica-
tions or the provision of platforms and services. The web API defines protocols and encodings
for actual message exchange to implement the various interactions and workflows designed.
Thereby, the programming API abstracts from the underlying communication protocols de-
fined in the web API.
Parts of this deliverable (mainly section 3) will be used as online documentation, which will
be accessible to developers. For an easy understanding, those parts are written in a tutorial-
style. This documentation will facilitate the onboarding of external developers joining through
an open call and it will generally help to grow the BIG IoT ecosystem.
1.2. Relation to other Deliverables
The tasks of WP3 and WP4 are highly interrelated, however, their deliverables have each their
own, clear responsibilities. They address the technical concepts for BIG IoT. The outcomes are
evaluated in the pilots and demonstrators of WP5.
© 2017 10