Private Public Partnership Project (PPP)
Large-scale Integrated Project (IP)
D.5.1.2: FI-WARE GE Open Specification – IoT Chapter
Project acronym: FI-WARE
Project full title: Future Internet Core Platform
Contract No.: 285248
Strategic Objective: FI.ICT-2011.1.7 Technology foundation: Future Internet Core Platform
Project Document Number: ICT-2011-FI-285248-WP5-D.5.1.2
Project Document Date: 2013-05-15
Deliverable Type and Security: Public
Author: FI-WARE Consortium
Contributors: FI-WARE Consortium
Table of Contents
1 Introduction 9
1.1 Executive Summary 9
1.2 About This Document 9
1.3 Intended Audience 9
1.4 Chapter Context 9
1.5 Structure of this Document 11
1.6 Typographical Conventions 12
1.6.1 Links within this document 12
1.6.2 Figures 13
1.6.3 Sample software code 13
1.7 Acknowledgements 13
1.8 Keyword list 13
1.9 Changes History 13
2 FIWARE OpenSpecification IoT Backend IoTBroker 14
2.1 Preface 14
2.2 Copyright 14
2.3 Legal Notice 14
2.4 Overview 14
2.4.1 Data model outline 14
2.4.2 Functionality outline 15
2.5 Main Concepts 16
2.5.1 Basic Concepts 16
2.5.2 Additional Concepts 17
2.6 Main Interactions 17
2.6.1 Query Handling 17
2.6.2 Subscription Handling 18
2.6.3 Update 19
2.6.4 Notification 20
2.6.5 Availability Notification 21
2.7 Basic Design Principles 21
2.8 References 21
2.9 Detailed Open Specifications 22
2.9.1 Open API Specifications 22
2.9.2 Other Open Specifications 22
2.10 Re-utilised Technologies/Specifications 22
2.11 Terms and definitions 23
3 FI-WARE NGSI-9 Open RESTful API Specification (PRELIMINARY) 27
3.1 Introduction to the FI-WARE NGSI-9 API 27
3.1.1 FI-WARE NGSI-9 API Core 27
3.1.2 Intended Audience 27
3.1.3 Change history 27
3.1.4 Additional Resources 28
3.1.5 Legal Notice 28
3.2 General NGSI-9 API information 29
3.2.1 Resources Summary 29
3.2.2 Representation Format 30
3.2.3 Representation Transport 30
3.2.4 API Operations on Context Management Component 32
3.2.5 API operation on Context Consumer Component 33
4 FI-WARE NGSI-10 Open RESTful API Specification (PRELIMINARY) 34
4.1 Introduction to the FI-WARE NGSI 10 API 34
4.1.1 FI-WARE NGSI 10 API Core 34
4.1.2 Intended Audience 34
4.1.3 Change history 34
4.1.4 Additional Resources 35
4.2 General NGSI 10 API information 35
4.2.1 Resources Summary 35
4.2.2 Representation Format 36
4.2.3 Representation Transport 36
4.2.4 API Operations on Context Management Component 36
4.2.5 API operation on Context Consumer Component 39
5 FIWARE OpenSpecification IoT Backend ConfMan 40
5.1 Preface 40
5.2 Copyright 40
5.3 Legal Notice 40
5.4 Overview 40
5.4.1 Data model outline 40
5.4.2 Functionality outline 41
5.5 Basic Concepts 41
5.5.1 FI-WARE NGSI 41
5.5.2 ConfMan GE Architecture 41
5.6 Additional Concepts 42
5.6.1 Associations in FI-WARE NGSI-9 42
5.7 Main Interactions 42
5.7.1 Reception of RegisterContext operations from Agents 43
5.7.2 Query Discover Availability 43
5.7.3 Subscription to Context Availability 44
5.7.4 Notification 44
5.8 Added-value (Optional) Features 45
5.8.1 Geo-discovery 45
5.8.2 Discovery 45
5.9 Detailed Open Specifications 53
5.9.1 Open API Specifications 53
5.9.2 Other Open Specifications 53
5.10 Re-utilised Technologies/Specifications 53
5.11 Terms and definitions 53
6 FI-WARE NGSI-9 Open RESTful API Specification (PRELIMINARY) 57
6.1 Introduction to the FI-WARE NGSI-9 API 57
6.1.1 FI-WARE NGSI-9 API Core 57
6.1.2 Intended Audience 57
6.1.3 Change history 57
6.1.4 Additional Resources 58
6.1.5 Legal Notice 58
6.2 General NGSI-9 API information 59
6.2.1 Resources Summary 59
6.2.2 Representation Format 60
6.2.3 Representation Transport 60
6.2.4 API Operations on Context Management Component 60
6.2.5 API operation on Context Consumer Component 63
7 FI-WARE NGSI-10 Open RESTful API Specification (PRELIMINARY) 64
7.1 Introduction to the FI-WARE NGSI 10 API 64
7.1.1 FI-WARE NGSI 10 API Core 64
7.1.2 Intended Audience 64
7.1.3 Change history 64
7.1.4 Additional Resources 65
7.2 General NGSI 10 API information 65
7.2.1 Resources Summary 65
7.2.2 Representation Format 66
7.2.3 Representation Transport 66
7.2.4 API Operations on Context Management Component 66
7.2.5 API operation on Context Consumer Component 69
8 FIWARE OpenSpecification IoT Backend DeviceManagement 70
8.1 Preface 70
8.2 Copyright 70
8.3 Legal Notice 70
8.4 Overview 70
8.4.1 Main Components 71
8.4.2 Basic Concepts 74
8.5 Main Interactions 74
8.5.1 Retrieve Device information 74
8.5.2 Sending control operations to Device 75
8.5.3 Device Push Update 75
8.5.4 Device Registration Southbound 75
8.5.5 Measurement Collection 76
8.6 Basic Design Principles 76
8.7 Detailed Open Specifications 77
8.7.1 Open API Specifications 77
8.7.2 Other Open Specifications 77
8.8 Re-utilised Technologies/Specifications 77
8.9 Terms and definitions 78
9 ETSI M2M mIa Open RESTful API Specification (DRAFT) 81
9.1 Introduction to the ETSI M2M mIa API 81
9.1.1 ETSI M2M mIa API Core 81
9.1.2 Intended Audience 81
9.1.3 API Change History 81
9.1.4 Additional Resources 82
9.2 General ETSI M2M mId API Information 82
9.2.1 Representation Format 82
9.2.2 Representation Transport 82
9.3 API Operations 82
9.3.1 Data Retrieval 83
9.3.2 Subscription 84
10 ETSI M2M mId RESTful API Specification (PRELIMINARY) 86
10.1 Introduction to the ETSI M2M mId API 86
10.1.1 ETSI M2M mId API Core 86
10.1.2 Intended Audience 86
10.1.3 API Change History 86
10.1.4 Additional Resources 87
10.2 General ETSI M2M mId API Information 87
10.2.1 Representation Format 87
10.2.2 Representation Transport 87
10.3 API Operations 87
10.3.1 Data Retrieval 88
10.3.2 Subscription 89
11 FI-WARE NGSI Open RESTful API Specification (PRELIMINARY) 91
12 FIWARE OpenSpecification IoT Gateway DeviceManagement 92
12.1 Preface 92
12.2 Copyright 92
12.3 Legal Notice 92
12.4 Overview 92
12.5 Basic Concepts 93
12.5.1 Resource Management 94
12.5.2 Discontinuous connectivity 95
12.5.3 Communication Core 95
12.6 Main interactions 95
12.6.1 Resource Management 95
12.6.2 Accessing resources 98
12.7 Basic Design Principles 99
12.8 Detailed Open Specifications 99
12.8.1 Open API Specifications 99
12.8.2 Other Open Specifications 100
12.9 Re-utilised Technologies/Specifications 100
12.10 Terms and definitions 100
13 IETF CoRE 104
13.1 Introduction to IETF CoRE 104
13.1.1 IETF CoRE API core 104
13.1.2 Intended Audience 104
13.1.3 Change history 105
13.2 General IETF CoRE API information 105
13.2.1 Representation Format 105
13.2.2 Resource Identification 105
13.2.3 Links and References 105
13.3 API Operations 105
13.3.1 Northbound API 105
13.3.2 Southbound API 106
14 FIWARE OpenSpecification IoT Gateway DataHandling 108
14.1 Preface 108
14.2 Copyright 108
14.3 Legal Notice 108
14.4 Overview 108
14.4.1 Internal architecture components diagram 110
14.4.2 Main interfaces 111
14.4.3 Main components 112
14.5 Basic concepts 114
14.5.1 Event concepts 114
14.5.2 Esper Complex Event Processing engine 115
14.5.3 SOL/CEP Complex Event Processing engine 116
14.5.4 NGSI 119
14.5.5 ETSI M2M 119
14.5.6 XACML 119
14.6 Main Interactions 120
14.7 Basic design principles 121
14.8 Re-utilised Technologies/Specifications 121
14.9 Detailed Open Specifications 121
14.9.1 Open Restful API Specifications(DRAFT) 122
14.9.2 Other Open Specifications 122
14.10 Terms and definitions 122
15 FI-WARE NGSI-9 Open RESTful API Specification (PRELIMINARY) 126
15.1 Introduction to the FI-WARE NGSI-9 API 126
15.1.1 FI-WARE NGSI-9 API Core 126
15.1.2 Intended Audience 126
15.1.3 Change history 126
15.1.4 Additional Resources 127
15.1.5 Legal Notice 127
15.2 General NGSI-9 API information 128
15.2.1 Resources Summary 128
15.2.2 Representation Format 129
15.2.3 Representation Transport 129
15.2.4 API Operations on Context Management Component 129
15.2.5 API operation on Context Consumer Component 132
16 FI-WARE NGSI-10 Open RESTful API Specification (PRELIMINARY) 133
16.1 Introduction to the FI-WARE NGSI 10 API 133
16.1.1 FI-WARE NGSI 10 API Core 133
16.1.2 Intended Audience 133
16.1.3 Change history 133
16.1.4 Additional Resources 134
16.2 General NGSI 10 API information 134
16.2.1 Resources Summary 134
16.2.2 Representation Format 135
16.2.3 Representation Transport 135
16.2.4 API Operations on Context Management Component 135
16.2.5 API operation on Context Consumer Component 138
17 FIWARE OpenSpecification IoT Gateway ProtocolAdapter 139
17.1 Preface 139
17.2 Copyright 139
17.3 Legal Notice 139
17.4 Overview 139
17.5 Basic Concepts 140
17.6 Main Interactions 143
17.7 Basic Design Principles 144
17.8 Re-utilised Technologies/Specifications 144
17.9 Terms and definitions 144
18 FI-WARE Open Specifications Legal Notice 148
19 Open Specifications Interim Legal Notice 150
1 Introduction
1.1 Executive Summary
This document describes the Generic Enablers in the Internet of Things Service Enablement chapter, their basic functionality and their interaction. These Generic Enablers form the core business framework of the FI-WARE platform by supporting the business functionality for commercializing services.
The functionality of the frame work is illustrated with several abstract use case diagrams, which show how the individual GE can be used to construct a domain-specific application environment and system architecture. Each GE Open Specification is first described on a generic level, describing the functional and non-functional properties and is supplemented by a number of specifications according to the interface protocols, API and data formats.
1.2 About This Document
FI-WARE GE Open Specifications describe the open specifications linked to Generic Enablers GEs of the FI-WARE project (and their corresponding components) being developed in one particular chapter.
GE Open Specifications contain relevant information for users of FI-WARE to consume related GE implementations and/or to build compliant products which can work as alternative implementations of GEs developed in FI-WARE. The later may even replace a GE implementation developed in FI-WARE within a particular FI-WARE instance. GE Open Specifications typically include, but not necessarily are limited to, information such as:
· Description of the scope, behavior and intended use of the GE
· Terminology, definitions and abbreviations to clarify the meanings of the specification
· Signature and behavior of operations linked to APIs (Application Programming Interfaces) that the GE should export. Signature may be specified in a particular language binding or through a RESTful interface.
· Description of protocols that support interoperability with other GE or third party products
· Description of non-functional features
1.3 Intended Audience
The document targets interested parties in architecture and API design, implementation and usage of FI-WARE Generic Enablers from the FI-WARE project.
1.4 Chapter Context
FI-WARE will build the relevant Generic Enablers for Internet of Things Service Enablement, in order for things to become citizens of the Internet–available, searchable, accessible, and usable – and for FI services to create value from real-world interaction enabled by the ubiquity of heterogeneous and resource-constrained devices.
From a physical standpoint, IoT enablers have been spread in two different domains:
· FI-WARE IoT Gateway. A hardware device hosting a number of features of one or several Gateway Generic Enablers of the IoT Service Enablement. It is usually located at proximity of the devices (sensors/actuators) to be connected. In the FI-WARE IoT model, the IoT Gateway is an optional element aiming to optimize the network traffic sent to the Backend and IoT services efficiency and reliability. Zero, one or more IoT Gateways can be part of a FI-WARE IoT setting. Several m2m technologies introduce specific gateway devices too, where it is not feasible to install FI-WARE gateway features. Those gateways are considered plain devices grouping other devices and not FI-WARE IoT Gateways.
· FI-WARE IoT Backend. A setting in the cloud hosting a number of features of one or several Generic Enablers of the IoT Service Enablement. It is typically part of a FI-WARE platform instance in a Datacenter. In the FI-WARE IoT model, a single IoT Backend is mandatory and it is connected to all IoT end devices either via IoT Gateway(s) and/or straight interfaces. Normally, during FI-WARE Releases R1 and R3 timeframes, the Backend will refer to the IoT Backend enablers installed in the FI-WARE Testbed or Open Innovation Lab (OIL), as described in the project Catalogue.
A key design statement is that, whenever present, IoT Gateways are not expected to be permanently connected to the Backend as per communications design or failures. Another relevant remark is that IoT Gateways are expected to be constrained devices in some scenarios. Therefore, light-weight implementations of the same GEs plus additional GEs interfaces helping to save unnecessary features/GEs are specially considered in the Gateway domain.
From the functionality point of view, FI-WARE IoT design aims to expose the "Things" abstraction to services developers, cope with different vertical m2m applications and provide a uniform access to heterogeneous m2m hardware and protocols. There is a number IoT features which are somehow duplicated in the Backend and the gateway domains in order to fulfill the goals and statements described above. For instance, a CEP engine at the Gateway level reduces the network overload and improves condition-based-events triggering time. Application developers will be able to access Things and devices observation and control interfaces in two ways:
· Directly, by using Northbound IoT interfaces as described in this Wiki.
· Throughout Data/Context GEs, by configuring Backend IoT GEs (IoT Broker) as NGSI notifications Context Providers of Data/Context Publish-Subscribe-Context-Broker GE.
Nota Bene: For the reader, we are using in the following chapters the same vocabulary as in theFI-Ware Product Vision chapter:
· Thing. Physical object, living organism, person or concept interesting from the perspective of an application.
· Device. Hardware entity, component or system that either measures properties of a thing/group of things or influences the properties of a thing/group of things or both measures/influences. Sensors and actuators are devices.
· IoT Resource. Computational elements (software) that provide the technical means to perform sensing and/or actuation on the device. The resource is usually hosted on the device.
More information about the IoT Service Enablement Chapter and FI-WARE in general can be found within the following pages:
http://wiki.fi-ware.eu
Internet_of_Things_Services_Enablement_Architecture
Materializing_Internet-Of-Things-Services-Enablement_in_FI-Ware
1.5 Structure of this Document
The document is generated out of a set of documents provided in the public FI-WARE wiki. For the current version of the documents, please visit the public wiki at http://wiki.fi-ware.eu/
The following resources were used to generate this document:
D.5.1.2 FI-WARE GE Open Specifications front page
FIWARE.OpenSpecification.IoT.Backend.IoTBroker
FI-WARE_NGSI-9_Open_RESTful_API_Specification_(PRELIMINARY)
FI-WARE_NGSI-10_Open_RESTful_API_Specification_(PRELIMINARY)
FIWARE.OpenSpecification.IoT.Backend.ConfMan