diff --git a/md/annex-d.md b/md/annex-d.md index 11cd30f76f8a3842b0f38773dbee58a269d881bf..5450f28199fb09cd4c9b38d3236c8c925e462a9b 100644 --- a/md/annex-d.md +++ b/md/annex-d.md @@ -1,162 +1,3 @@ -# Annex D [(informative)]{.inform}: Transformation algorithms +# Annex D [(informative)]{.inform}: RDF-compatible specification of NGSI-LD meta-model -## D.1 Introduction - -These algorithms are informative but NGSI-LD implementations should aim at -either implementing them as they are described here or devising similar -algorithms which take exactly the same input and provides exactly the same -output (or an equivalent one as per the JSON-LD specification [n.8]). - -## D.2 Algorithm for transforming an NGSI-LD Entity into a JSON-LD document (ALG1) - -This algorithm takes as input an NGSI-LD graph which top level node is a -particular Entity and returns as output a JSON-LD document which represents all -the data associated to the entity. The JSON-LD document (and its associated -_`@context`_) corresponds to a representation of the Entity in JSON-LD as per -the NGSI-LD Information Model. - - - ->>> [!note] NOTE: - -An early implementation of this algorithm can be found at [i.21]. - ->>> - - - -Let: - -- **G** be a graph defined as follows: - - Let **N** be G's top level node. - - N is an Entity instance of type **T** or types **Ts**. Type name is "AliasT" - or there is an Array of Type names ["AliasT1", ...,"AliasTn"], N's - identifier is **I**. - - N has 0 or more associated _Property_. Each _Property_ (**Psi**) is defined - as follows: - - _Property_ type identifier is **Pi**. - - _Property_ name is "AliasPi". - - _Property_ Value is **Vi**. - - _Property_ Value's associated data type is **Di**. - - N is the subject of 0 or more _Relationship_. Each _Relationship_ is defined - as follows: - - _Relationship_ type identifier is **Ri**. - - _Relationship_ name is "AliasRi". - - _Relationship_ target object identifier is **Robji**. -- **O** be a JSON object initialized to the empty object ({}). -- **C** be a JSON-LD _`@context`_ initialized as described by annex B. - -The algorithm should run as follows, provided all the preconditions defined -above are satisfied: - -1. Add to C a new member <"AliasT", T> or new members <"AliasT1", T1> ... - <"AliasTn", Tn>. - -2. Add to O two new members: - - - - a. <"id", I>. - b. <"type", "AliasT"> or <"type", "AliasT1", ...,"AliasTn"> .">. - - - -3. For each _Property_ Psi (Pi, "AliasP", Vi, Di) associated to N: - - - - a. Run Algorithm ALG1.1 taking the following inputs: - - Ps → Psi. - - O → O. - - C → C. - - - -4. For each _Relationship_ Rs (Ri, AliasRi, Robji) associated to N: - - - - a. Run Algorithm ALG1.2 taking the following inputs: - - Rs → Rsi. - - O → O. - - C → C. - - - -5. Return (O, C) and end of the algorithm. - -## D.3 Algorithm for transforming an NGSI-LD Property into JSON-LD (ALG1.1) - -Let **Ps** be the _Property_ that has to be transformed. It is defined by (P, -"AliasP", V, D), where **P** denotes a _Property_ Type Id, "**AliasP**" is the -_Property_ name, **V** is the _Property_ Value and **D** is the _Property_ -Value's data type. - -Ps might be associated to extra _Properties_ or _Relationships_. - -Let O be the output JSON-LD object and C the associated JSON-LD context: - -1. Execute the following steps: - - - - a. If no member with "AliasP" is present in O, add a new member to O with - key "AliasP" and value an object structure, let it be named **Op** - <"type", "Property">. - - If D is not a native JSON data type add a new member to Op with name - "value" and which value has to be an object structure as follows: - 1. <"@type", D>. - 2. <"@value", V>. - - Else If D is a native JSON data type add a new member to Op as follows: - 1. <"value", V>. - b. Add a new member to C as follows: - - <"AliasP", P>. - c. For each _Property_ associated to Ps (Pss) - recursively run the present algorithm (ALG1.1) taking the following - inputs: - - Ps → Pss. - - O → Op. - - C → C. - d. For each _Relationship_ associated to Ps (Rss) run - algorithm ALG1.2 taking the following inputs: - - Rs → Rss. - - O → Op. - - C → C. - - - -2. Return (O,C) and end of the algorithm. - -## D.4 Algorithm for transforming an NGSI-LD Relationship into JSON-LD (ALG1.2) - -Let **Rs** be the _Relationship_ that has to be transformed. It is defined by -(R, "AliasR", Robj), where **R** denotes a _Relationship_ Type Id, "**AliasR**" -is the _Relationship_'s name and **Robj** is the identifier of the target object -of the _Relationship_. - -Rs might be associated to extra _Properties_ or _Relationships_. - -Let O be the output JSON-LD object and C the current JSON-LD context: - -1. Execute the following statements: - - - - a. If no member with "AliasR" is present in O, add a new member to O with - key "AliasR" and value an object structure, let it be named **Or** - - <"object", Robj>. - - <"type", "Relationship">. - b. For each _Property_ associated to Rs (Pss) run the - algorithm ALG1.1 taking the following inputs: - - Ps → Pss. - - O → Or. - - C → C. - c. For each _Relationship_ associated to Rs (Rss) - recursively run the present algorithm ALG1.2 taking the following inputs: - - Rs → Rss. - - O → Or. - - C → C. - - - -2. Return (O,C) and end of the algorithm. +The content of this annex is now in ETSI TS 104 178 [i.6]. diff --git a/md/annex-e.md b/md/annex-e.md index a6b25d2890960cc4d221e7c8b1d3c70fc4dd7623..2eed56fea22c6424828dd90c76e280693ff4d641 100644 --- a/md/annex-e.md +++ b/md/annex-e.md @@ -1,3 +1,107 @@ -# Annex E [(informative)]{.inform}: RDF-compatible specification of NGSI-LD meta-model +# Annex E [(informative)]{.inform}: Conventions and syntax guidelines -The content of this annex is now in ETSI TS 104 178 [i.6]. +When new terms are defined, they are marked in bold, and terms are capitalized +thereafter. + + + +>>> [!tip] EXAMPLE 1: + +**NGSI-LD Linked Entity**, [Linked Entity]{.HTML-Keyboard}. + +>>> + + + +API Parameter names are always in lowercase. + + + +>>> [!tip] EXAMPLE 2: + +_`options`_. + +>>> + + + +Entity Types are defined using lowercase but with a starting capital letter. + + + +>>> [!tip] EXAMPLE 3: + +Vehicle, Building, ParkingSpace. + +>>> + + + +JSON-LD nodes and terms are always defined using camel case notation starting +with lower case. + + + +>>> [!tip] EXAMPLE 4: + +_`createdAt`_, _`value`_, _`unitCode`_. + +>>> + + + +When referring to special terms, data types or words defined previously in the +present document or by other referenced specifications, italics format is used. + + + +>>> [!tip] EXAMPLE 5: + +_ListRelationship_, _GeoProperty_, _Geometry_, _Second_, _Number_. + +>>> + + + +When referring to literal strings double quotes are used. + + + +>>> [!tip] EXAMPLE 6: + +["application/json"]{.HTML-Code}, ["Subscription"]{.HTML-Code}. + +>>> + + + +When referring to the JSON-LD Context the mnemonic text string _`@context`_ is +used as a placeholder. + +All the dates and times are given in UTC format. + + + +>>> [!tip] EXAMPLE 7: + +[2018-02-09T11:00:00Z]{.HTML-Code}. + +>>> + + + +The measurement units used in the API are those defined by the International +System of Units. + + + +>>> [!tip] EXAMPLE 8: + +The distance in geo-queries is provided in meters. + +>>> + + + +When defining application-specific elements or API extensions the same +conventions and syntax guidelines should be followed. diff --git a/md/annex-f.md b/md/annex-f.md index 7d44c8b7778dee1d02d0d32087fdeb94f283ef7d..c7717fe92203e2b7251c7b8b974a8fd9378f311b 100644 --- a/md/annex-f.md +++ b/md/annex-f.md @@ -1,107 +1,232 @@ -# Annex F [(informative)]{.inform}: Conventions and syntax guidelines +# Annex F [(informative)]{.inform}: Localization and internationalization support + +## F.1 Introduction + +These algorithms described below are informative, but NGSI-LD implementations +should aim at either implementing them as they are described here or providing +equivalent _`@context`_ elements for their payloads to provide interoperability +with their internationalized context entities. + +## F.2 Localization and internationalization + +### F.2.1 Introduction + +Since Internationalization is not core to context information management, any +direct support within NGSI-LD systems is limited. Annex+++root proposes a series +of best practices for maintaining, querying and displaying interoperable +internationalized data. + +The content of the _`@context`_ utilized for the referred Entities within these +examples uses pre-existing URNs used for internationalization and is as follows: + +```json +{ + "inLanguage": "http://schema.org/inLanguage", + "sameAs": "http://schema.org/sameAs" +} +``` + +### F.2.2 Associating an Entity with a natural language + +Where a context Entity is associated with a single natural language, include a +well-defined _Property_ indicating the natural language of the content. For +example an Event taking place in French may be defined as follows: + +```json +{ + "type": "Event", + "id": "urn:ngsi-ld:Event:bonjourLeMonde", + "name": { + "type": "Property", + "value": "Bonjour le Monde" + }, + "description": { + "type": "Property", + "value": "«Bonjour le monde» sont les mots traditionnellement écrits par un programme informatique simple" + }, + "inLanguage": { + "type": "Property", + "value": "fr" + } +} +``` + +### F.2.3 Associating a Property with a natural language + +Where a _Property_ of a context entity can be associated to one more natural +language, include additional metadata as a sub-Property of that _Property_. For +example, a Hotel with booking forms available in English, French and German may +be defined as follows: + +```json +{ + "type": "Hotel", + "id": "urn:ngsi-ld:Hotel:XXXXX", + "name": { + "type": "Property", + "value": "Grand Hotel" + }, + "bookingUrl": { + "type": "Property", + "value": [ + "http://example.com/booking-in-french/", + "http://example.com/booking-in-english/", + "http://example.com/booking-in-german/" + ], + "inLanguage": { + "type": "Property", + "value": ["fr", "en", "de"] + } + } +} +``` + +### F.2.4 Associating as equivalent Entity + +Where equivalent context entities in multiple natural languages exist, they may +be associated with each other through the use of a one-to-many _Relationships_, +where each _Relationships_ holds an additional sub-Property indicating the +natural language of the equivalent entities. + +For example, three Events (such as a walking tour which is available in English, +French and German) may be associated to each other as follows: + +```json +{ + "type": "Event", + "id": "urn:ngsi-ld:Event:bonjourLeMonde", + "name": { + "type": "Property", + "value": "Bonjour le Monde" + }, + "sameAs": [ + { + "type": "Relationship", + "datasetId": "urn:ngsi-ld:Relationship:1", + "object": "urn:ngsi-ld:Event:helloWorld", + "inLanguage": { + "type": "Property", + "value": "en" + } + }, + { + "type": "Relationship", + "object": "urn:ngsi-ld:Event:halloWelt", + "inLanguage": { + "type": "Property", + "value": "de" + } + } + ] +} +``` + +## F.3 Natural language collation support + +### F.3.1 Introduction + +All strings within an NGSI-LD system are defined and sorted as a sequence of +Unicode characters. As such there is no simple collation mechanism to query +entities ignoring case, diacritic marks or matching diphthong single letters +such as the German ["ö"]{.HTML-Code} to also match with ["oe"]{.HTML-Code}. + +Many databases support a degree of natural language support, in general +collation support will always depend upon the underlying database and as such +will vary from implementation to implementation. This therefore and cannot be +standardized and exposed as part of the context information management API. +Furthermore, collation is slow and processor intensive, and for massive systems +is better achieved using a separate index. + +For systems that require it, this clause proposes a mechanism as an extension to +a NGSI-LD [Context Broker]{.HTML-Keyboard} which can be modified and used to +offer collation support to the natural language attributes found within context +entities where necessary through creating, querying and maintaining an +additional property of a property for collated attributes. + +### F.3.2 Maintain collations as metadata + +- Create a subscription on the attribute (e.g. _`name`_) +- Create a simple microservice to add/upsert a _`name.collate`_ + property-of-a-property using a simple function to strip all diacritic marks - + for example: [str.normalize("NFD").replace(/\[\\u0300-\\u036f\]/g, + "").toLower()]{.HTML-Sample} + +Other substitutions could be made where local spelling rules vary (for example +different for German ö = oe). + +### F.3.3 Route language sensitive queries via a proxy + +Create a simple forwarding proxy around the NGSI-LD system. For any urls with a +_`q`_ param (and a _`collate`_ flag) run a clean-up of the _`q`_ param and amend +the query string: + +The following request on the proxy: + +- **GET** + _`/ngsi-ld/v1/entities/?type=Building&q=name==%22Schöne%20Grüße%22&collate=name`_ + +is altered on the fly and is sent to the NGSI-LD system as shown: + +- **GET** + _`/ngsi-ld/v1/entities/?type=Building&q=name.collate==%22schoene%20gruesse%22`_ + +Once again, the substitutions to make to the query string will depend on the +rules of the natural language to be supported. + +## F.4 Localization of dates, currency formats, etc. + +### F.4.1 Introduction + +Context data entities are designed to be interoperable and therefore all dates +are held as UTC dates, all currency amounts are held as JSON numbers (with the +unitCode property-of-a-property available to hold the currency), etc. +Localization should not occur within the context data entities themselves. +Offering fully localized responses is not a concern of the NGSI-LD API. + +If localization support is necessary, a simple proxying a conversion mechanism +could be used to amend the context data received from the NGSI-LD system before +being passed to a third party system for display. + +### F.4.2 Localizing dates + +For example, if a system needs to display _DateTime_ data in Islamic Date format + +The following request on the proxy: + +- **GET** + _`/ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified`_ + +is forwarded unaltered and is sent to the NGSI-LD system as shown: + +- **GET** + _`/ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified`_ -When new terms are defined, they are marked in bold, and terms are capitalized -thereafter. +The response from the NGSI-LD system is always in UTC format: - +```json +{ + "date": "2020-09-28T17:13:39+02:00" +} +``` ->>> [!tip] EXAMPLE 1: +And the proxy can be used to update this to the desired format: -**NGSI-LD Linked Entity**, [Linked Entity]{.HTML-Keyboard}. +```json +{ + "date": "11 Safar, 1442 1:13:39PM" +} +``` ->>> +Using an internationalization script such as the following: - +```js +new Intl.DateTimeFormat("en-u-ca-islamic", { + day: "numeric", + month: "long", + weekday: "long", + year: "numeric", +}).format(date); +``` -API Parameter names are always in lowercase. - - - ->>> [!tip] EXAMPLE 2: - -_`options`_. - ->>> - - - -Entity Types are defined using lowercase but with a starting capital letter. - - - ->>> [!tip] EXAMPLE 3: - -Vehicle, Building, ParkingSpace. - ->>> - - - -JSON-LD nodes and terms are always defined using camel case notation starting -with lower case. - - - ->>> [!tip] EXAMPLE 4: - -_`createdAt`_, _`value`_, _`unitCode`_. - ->>> - - - -When referring to special terms, data types or words defined previously in the -present document or by other referenced specifications, italics format is used. - - - ->>> [!tip] EXAMPLE 5: - -_ListRelationship_, _GeoProperty_, _Geometry_, _Second_, _Number_. - ->>> - - - -When referring to literal strings double quotes are used. - - - ->>> [!tip] EXAMPLE 6: - -["application/json"]{.HTML-Code}, ["Subscription"]{.HTML-Code}. - ->>> - - - -When referring to the JSON-LD Context the mnemonic text string _`@context`_ is -used as a placeholder. - -All the dates and times are given in UTC format. - - - ->>> [!tip] EXAMPLE 7: - -[2018-02-09T11:00:00Z]{.HTML-Code}. - ->>> - - - -The measurement units used in the API are those defined by the International -System of Units. - - - ->>> [!tip] EXAMPLE 8: - -The distance in geo-queries is provided in meters. - ->>> - - - -When defining application-specific elements or API extensions the same -conventions and syntax guidelines should be followed. +It should be noted that post-localization, the transformed date is no longer +valid NGSI-LD. diff --git a/md/annex-g.md b/md/annex-g.md index 8c1d7bc814232dce589d700a14a550e218981410..f163ab73d94c49339782a86aa220e317de0991b5 100644 --- a/md/annex-g.md +++ b/md/annex-g.md @@ -1,232 +1,579 @@ -# Annex G [(informative)]{.inform}: Localization and internationalization support +# Annex G [(informative)]{.inform}: Suggested actuation workflows + +## G.1 Actuators and feedback to the consumer + +Actuators are things that can change their state (light on/off) or execute +actions (move forward, detect face, etc.). + +There is currently no explicitly and precisely specified support for actuation +in the NGSI-LD API. Thus, this clause describes some conventions that represent +a proposed best-practice about how NGSI-LD API and data models can be used for +the interaction between applications and actuators represented by NGSI-LD +Entities. + +The conventions and approach described in this clause are not powerful enough to +implement complex actuation jobs that depend on each other and, for instance, +make actuation decisions conditional on the outcome of other actuations, unless +that behaviour is implemented in a custom way within the application logic. The +concept of a more evolved service execution logic, being a first-class citizen +of the NGSI-LD API and able to offer more structured building blocks for +actuation, is outside the scope of this annex. + +An NGSI-LD system that comprises an actuator and supports actuation workflows is +represented as one or more NGSI-LD Entities, plus a [Context +Broker]{.HTML-Keyboard}, a [Context Source]{.HTML-Keyboard} or a [Context +Producer]{.HTML-Keyboard}, and a [Context Consumer]{.HTML-Keyboard}, which +collaborate. + +The interaction between actuator and [Context Consumer]{.HTML-Keyboard} needs to +be bidirectional. Thus, actuators are triggered by the reception of +actuation-specific commands (e.g. "set the on state of the lamp to false", to +turn the light off) that are encoded as NGSI-LD data, following a suggested data +model. They respond with feedback, similarly encoded as NGSI-LD data. + +Command feedbacks may serve to control the maximum operations rate a controlling +application needs to achieve, and different levels of feedback can be requested, +by associating a specific Quality of Service value to the command: + +- Some applications need high operation rate but no feedback. For this case a + QoS = 0 can be used. The typical example is to control the arms of a robot + with a joystick. +- Some applications need to be sure that the actuators actually received the + command request or need to get back a payload in response to the command. In + this case a QoS = 1 can be used. The typical case is switching on a light with + confirmation, or request face-detection with consequent notification of + matching events. +- Commands can either require a short or a long execution time. For commands + with long execution time, the application may require a continuous status + feedback. In this case a QoS = 2 can be used. The typical example is that of a + door opening, where feedback continuously reports the current level (10 % + open, 50 % open, etc.). + +## G.2 Architecture for actuation + +In this architecture, the application acts as [Context +Consumer]{.HTML-Keyboard}, and the terms are used interchangeably. + +Commands are sent to the [Context Broker]{.HTML-Keyboard} by the [Context +Consumer]{.HTML-Keyboard}, using the standard NGSI-LD API and a suggested +convention for representing them. In turn, feedback about command execution is +received by the [Context Consumer]{.HTML-Keyboard}, both as continuous status +updates and/or a final command result. + +More specifically, the component that handles direct communication with the +actuator is the [Context Source]{.HTML-Keyboard} or the [Context +Producer]{.HTML-Keyboard}: it uses an actuator-specific protocol to control the +actuator and get responses and updates from it, i.e. from the real system. Such +[Context Source]{.HTML-Keyboard}/Consumer or [Context +Producer]{.HTML-Keyboard}/Storage acting as a proxy or intermediary to the +actuator is referred to, in the following, as Context Adapter. + +Thus, the Context Adapter is able to use the NGSI-LD API to receive NGSI-LD +command requests from the NGSI-LD [Context Broker]{.HTML-Keyboard} and send back +command status and result to it, as well as using an actuator-specific protocol +to communicate with the actuator. + +The NGSI-LD [Context Broker]{.HTML-Keyboard} is responsible for handling direct +communication with the [Context Consumer]{.HTML-Keyboard}. + +Thus, to support actuation, there is a need to specify: + +- Additional NGSI-LD Properties the NGSI-LD system has to have, in order to + represent and manage command Request, Status, Result. +- A communication model that allows commands to flow in forward direction and + feedback to flow in reverse. This communication model has to comprise a + mapping, to be held within the NGSI-LD system, that is able to route the + command requests to the appropriate handler within the Context Adapter and + vice-versa. + + + +::: FL + +::: + +::: TF +Figure: Architecture for actuation +::: + + + +## G.3 Structure of commands and additional Properties -## G.1 Introduction +### G.3.1 Introduction + +The NGSI-LD system has, in addition to the usual NGSI-LD Properties representing +the actuator's status, a set of additional, dedicated NGSI-LD Properties +associated with: + +- the list of available commands, i.e. the list of commands supported by the + actuator; +- command endpoints, one for each command, that are used to send and receive + command related messages and optionally hold state for the ongoing commands. -These algorithms described below are informative, but NGSI-LD implementations -should aim at either implementing them as they are described here or providing -equivalent _`@context`_ elements for their payloads to provide interoperability -with their internationalized context entities. +The structure of the commands needs to be specified, but not the internal format +of their payloads. By using commands with a custom payload, one can support all +kinds of operations, for example: -## G.2 Localization and internationalization +- ["set-on": "true"]{.HTML-Sample} +- ["detect-face": {"face-features": "...."}]{.HTML-Sample} +- ["move": "forward"]{.HTML-Sample} -### G.2.1 Introduction +The data model for command requests, status and responses has to include +metadata such as the QoS of the command, its identifier, and the custom payload +itself. -Since Internationalization is not core to context information management, any -direct support within NGSI-LD systems is limited. Annex+++root proposes a series -of best practices for maintaining, querying and displaying interoperable -internationalized data. +Both the requests/responses and the list of commands the NGSI-LD system is able +to support can be represented with additional NGSI-LD Properties, as follows. -The content of the _`@context`_ utilized for the referred Entities within these -examples uses pre-existing URNs used for internationalization and is as follows: +### G.3.2 Property for listing available commands + +The additional _Property_ dedicated to the list of available commands is as +follows: ```json -{ - "inLanguage": "http://schema.org/inLanguage", - "sameAs": "http://schema.org/sameAs" +"commands": { + "type": "Property", + "value": ["<​cmd_name1>", "<​cmd_name2>", …, "<​cmd_nameN>"] } ``` -### G.2.2 Associating an Entity with a natural language +It is a _Property_ whose value is an array of Strings, each string representing +the unique name of a supported command. + +### G.3.3 Properties for command endpoints + +For each available command, a set of three endpoints is to be additionally +created within the NGSI-LD system, by means of three dedicated _Properties_ per +command. The first endpoint will manage that command's requests, the second +endpoint will manage its status, and the third endpoint will manage command's +results. + +This convention dictates that: + +- The NGSI-LD _Property_ that manages requests has the same name as the command, + e.g. ["<​cmd_name1>"]{.HTML-Code}. +- The NGSI-LD _Property_ that manages results has the same name as the command + plus the ["-RESULT"]{.HTML-Code} suffix. +- The NGSI-LD _Property_ that manages status has the same name as the command + plus the ["-STATUS"]{.HTML-Code} suffix. -Where a context Entity is associated with a single natural language, include a -well-defined _Property_ indicating the natural language of the content. For -example an Event taking place in French may be defined as follows: +Each endpoint can receive multiple requests or responses, and it supports +queueing of messages. For example, the command _`moveToLocation`_ may receive a +sequence of requests that are to be stored in an array and orderly processed +depending on the arrival timestamps. A number of respective responses may be +produced, as well. Thus, each endpoint, represented by its dedicated NGSI-LD +_Property_, exploits the multi-Attribute feature (see Clause+++clause-8+++8.5), +as follows: + +**Command Request endpoint** ```json -{ - "type": "Event", - "id": "urn:ngsi-ld:Event:bonjourLeMonde", - "name": { - "type": "Property", - "value": "Bonjour le Monde" - }, - "description": { - "type": "Property", - "value": "«Bonjour le monde» sont les mots traditionnellement écrits par un programme informatique simple" - }, - "inLanguage": { - "type": "Property", - "value": "fr" - } +"<​cmd_name>": { + "datasetId": "a URI uniquely identifying the specific command request + (optional, if the use case does not need command queueing)", + "type": "Property", + "qos": "an Integer, representing the desired QoS (optional, default=0)", + "value": "custom parameters of the command (mandatory)" } ``` -### G.2.3 Associating a Property with a natural language - -Where a _Property_ of a context entity can be associated to one more natural -language, include additional metadata as a sub-Property of that _Property_. For -example, a Hotel with booking forms available in English, French and German may -be defined as follows: +**Command Status endpoint** ```json -{ - "type": "Hotel", - "id": "urn:ngsi-ld:Hotel:XXXXX", - "name": { - "type": "Property", - "value": "Grand Hotel" - }, - "bookingUrl": { - "type": "Property", - "value": [ - "http://example.com/booking-in-french/", - "http://example.com/booking-in-english/", - "http://example.com/booking-in-german/" - ], - "inLanguage": { - "type": "Property", - "value": ["fr", "en", "de"] - } - } +"<​cmd_name>-STATUS": { + "datasetId": "a URI uniquely identifying the specific status feedback message + (optional, if the use case does not need queueing them)", + "type": "Property", + "value": "custom status of the command (mandatory)" } ``` -### G.2.4 Associating as equivalent Entity +**Command Result endpoint** -Where equivalent context entities in multiple natural languages exist, they may -be associated with each other through the use of a one-to-many _Relationships_, -where each _Relationships_ holds an additional sub-Property indicating the -natural language of the equivalent entities. +```json +"<​cmd_name>-RESULT": { + "datasetId": "a URI uniquely identifying the specific result feedback message + (optional, if the use case does not need queueing them)", + "type": "Property", + "value": "custom result of the command (mandatory)" +} +``` -For example, three Events (such as a walking tour which is available in English, -French and German) may be associated to each other as follows: +Usually, the Context Adapter (or the actuator behind it), upon receiving a +command request with a specific _`datasetId`_, will then generate status and +result with the same _`datasetId`_, so that, when the status/result is received +by the application, it can link it back to the corresponding command that is +generating the received feedback. The value of the request, status and result is +generic, and it is up to the specific application to define useful values. As an +example, the PackML language for the control of packaging machines defines a set +of possible values for statuses during an actuation workflow. + + + +>>> [!tip] EXAMPLE 1: + +An example follows, where the NGSI-LD system represents a simple actuator. The +example shows the NGSI-LD Entity representing a light that can change colour by +manipulation of its brightness, hue and saturation values; further, it is +possible to turn the lamp on and off. Apart from the _`id`_ and +the _`type`_, the actuator entity has a set of regular properties +that represent the current status of the lamp. In the example these are +_`colorRGB`_ and _`is-on`_. Then it has the +conventional _Property_ named _`commands`_, +signalling that it supports four commands: ["turn-on"]{.HTML-Code}, +["set-saturation"]{.HTML-Code}, ["set-brightness"]{.HTML-Code}, +["set-hue"]{.HTML-Code}. Further, it has four (times three) additional +properties serving the purpose of command endpoints. ```json { - "type": "Event", - "id": "urn:ngsi-ld:Event:bonjourLeMonde", - "name": { + "id": "urn:ngsi-ld:pHueActuator:light1", + "type": "Lamp", + // REGULAR PROPERTIES + "colorRGB": {"type": "Property", "value": "0xABABAB"}, + "is-on": {"type": "Property", "value": true}, + // AVAILABLE COMMANDS + "commands": { "type": "Property", - "value": "Bonjour le Monde" + "value": ["turn-on", "set-saturation", "set-hue", "set-brightness"] }, - "sameAs": [ - { - "type": "Relationship", - "datasetId": "urn:ngsi-ld:Relationship:1", - "object": "urn:ngsi-ld:Event:helloWorld", - "inLanguage": { - "type": "Property", - "value": "en" - } - }, - { - "type": "Relationship", - "object": "urn:ngsi-ld:Event:halloWelt", - "inLanguage": { - "type": "Property", - "value": "de" - } - } - ] + // COMMAND ENDPOINTS + "turn-on": {"type": "Property", "value": "<​custom request>"}, + "turn-on-STATUS": {"type": "Property", "value": "<​custom status>"}, + "turn-on-RESULT": {"type": "Property", "value": "<​custom response>"}, + "set-hue": … , + "set-hue-STATUS": … , + "set-hue-RESULT": … , + … } ``` -## G.3 Natural language collation support - -### G.3.1 Introduction - -All strings within an NGSI-LD system are defined and sorted as a sequence of -Unicode characters. As such there is no simple collation mechanism to query -entities ignoring case, diacritic marks or matching diphthong single letters -such as the German ["ö"]{.HTML-Code} to also match with ["oe"]{.HTML-Code}. - -Many databases support a degree of natural language support, in general -collation support will always depend upon the underlying database and as such -will vary from implementation to implementation. This therefore and cannot be -standardized and exposed as part of the context information management API. -Furthermore, collation is slow and processor intensive, and for massive systems -is better achieved using a separate index. - -For systems that require it, this clause proposes a mechanism as an extension to -a NGSI-LD [Context Broker]{.HTML-Keyboard} which can be modified and used to -offer collation support to the natural language attributes found within context -entities where necessary through creating, querying and maintaining an -additional property of a property for collated attributes. - -### G.3.2 Maintain collations as metadata - -- Create a subscription on the attribute (e.g. _`name`_) -- Create a simple microservice to add/upsert a _`name.collate`_ - property-of-a-property using a simple function to strip all diacritic marks - - for example: [str.normalize("NFD").replace(/\[\\u0300-\\u036f\]/g, - "").toLower()]{.HTML-Sample} - -Other substitutions could be made where local spelling rules vary (for example -different for German ö = oe). - -### G.3.3 Route language sensitive queries via a proxy - -Create a simple forwarding proxy around the NGSI-LD system. For any urls with a -_`q`_ param (and a _`collate`_ flag) run a clean-up of the _`q`_ param and amend -the query string: +>>> -The following request on the proxy: + -- **GET** - _`/ngsi-ld/v1/entities/?type=Building&q=name==%22Schöne%20Grüße%22&collate=name`_ + -is altered on the fly and is sent to the NGSI-LD system as shown: +>>> [!tip] EXAMPLE 2: -- **GET** - _`/ngsi-ld/v1/entities/?type=Building&q=name.collate==%22schoene%20gruesse%22`_ +The following example shows an NGSI-LD Entity Fragment that can be used as a +command request to request that the lamp be turned off. -Once again, the substitutions to make to the query string will depend on the -rules of the natural language to be supported. - -## G.4 Localization of dates, currency formats, etc. - -### G.4.1 Introduction - -Context data entities are designed to be interoperable and therefore all dates -are held as UTC dates, all currency amounts are held as JSON numbers (with the -unitCode property-of-a-property available to hold the currency), etc. -Localization should not occur within the context data entities themselves. -Offering fully localized responses is not a concern of the NGSI-LD API. - -If localization support is necessary, a simple proxying a conversion mechanism -could be used to amend the context data received from the NGSI-LD system before -being passed to a third party system for display. - -### G.4.2 Localizing dates - -For example, if a system needs to display _DateTime_ data in Islamic Date format +```json +{ + "id": "urn:ngsi-ld:pHueActuator:light1", + "type": "Lamp", + "turn-on": { + "type": "Property", + "qos": { + "type": "Property", + "value": 1 + }, + "value": false + } +} +``` -The following request on the proxy: +>>> -- **GET** - _`/ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified`_ + -is forwarded unaltered and is sent to the NGSI-LD system as shown: + -- **GET** - _`/ngsi-ld/v1/entities/urn:ngsi-ld:Event:XXX?attrs=date&format=simplified`_ +>>> [!tip] EXAMPLE 3: -The response from the NGSI-LD system is always in UTC format: +In the following example, the value of the command request is a more complex +JSON Object, to show that complex actions can be conveyed by just one request. +Further, the request has an identifier that makes it possible to enqueue it, +together with other request that may arrive to the same command endpoint within +a timespan. ```json { - "date": "2020-09-28T17:13:39+02:00" + "id": "urn:ngsi-ld:pHueActuator:light1", + "type": "Lamp", + "set-hue": { + "type": "Property", + "qos": { + "type": "Property", + "value": 1 + }, + "datasetId": "myapp:mycommand:1342", + "value": { "red": "1 seconds", "green": "2 seconds" } + } } ``` -And the proxy can be used to update this to the desired format: +>>> + + + +In summary, the suggested convention prescribes a _`commands`_ _Property_ that +contains a list of commands supported by the actuator. For each of these +commands, the convention requires a command endpoint consisting of three +properties, the name of the command, e.g. ["turn-on"]{.HTML-Code}, the status +_Property_, which is the name of the command with ["-STATUS"]{.HTML-Code} as +suffix, and the result, which is the name of the command with +["-RESULT"]{.HTML-Code} as suffix. Nevertheless, it is noted that such suffixes +are just a convention to distinguish the endpoints. So far, two practical +implementations exist, see Clause+++root.5 and Clause+++root.6, that adopt the +general scheme of this convention, with minor deviations. In fact, this +convention is derived as a generalization that leverages the full potential of +NGSI-LD sub-Attributes and multi-Attributes. + +## G.4 Communication model + +### G.4.1 Possible communication models + +This convention can be leveraged by two different communication models: + +- Subscription/notification, where both the application and the Context Adapter + use NGSI-LD Subscriptions to have the command requests delivered to the + appropriate handler within the Context Adapter and vice-versa. In this case + the Context Adapter acts as a [Context Source]{.HTML-Keyboard} as well as a + [Context Consumer]{.HTML-Keyboard}. +- Forwarding, which uses the NGSI-LD Registry and a Context Adapter able to + federate itself with the [Context Broker]{.HTML-Keyboard} holding the + actuator's Entity, as a means to deliver the commands. In this case the + Context Adapter acts as a Context Storage as well as a [Context + Producer]{.HTML-Keyboard}. + +### G.4.2 Subscription/notification model + +For the interaction to work, the Context Adapter, acting as a proxy to the +actuator, subscribes to all command properties; in example 1 of +Clause+++root.3.3, these are ["set-brightness"]{.HTML-Code}, +["set-saturation"]{.HTML-Code}, ["set-hue"]{.HTML-Code} and +["turn-on"]{.HTML-Code}. When the application, acting as the actuation client, +updates the value of a command property, the Context Adapter will receive the +notification with the new value. This will be translated into the proprietary +format and forwarded to the actuator using the actuator-specific protocol. The +application in turn can subscribe to the command status and the result. The +Context Adapter updates the status of the actuation during the execution of the +command, which is primarily relevant in the case of longer-lasting actuations, +and finally updates the result once the actuation has been completed. If the +application has subscribed to the status and result, it will receive the +corresponding notifications. Independent of the command-related properties, the +status of the actuator, held within its regular properties, will be updated. + +The detailed workflow is depicted in Figure+++below, and can be interpreted as +follows: + +1. Application updates _`turn-on`_ command Property with ["value": + true]{.HTML-Code} +2. Context Adapter gets notification of the new value _`true`_ +3. Context Adapter updates _`turn-on-STATUS`_ command Property with ["value": + "PENDING"]{.HTML-Code} +4. Application gets notification of the new value ["PENDING"]{.HTML-Code} +5. Context Adapter updates _`is-on`_ regular Property with ["value": + true]{.HTML-Code} +6. Application gets notification with value: [true]{.HTML-Code} +7. Context Adapter updates _`turn-on-RESULT`_ command Property with ["value": + "OK"]{.HTML-Code} +8. Application gets notification with of the new value ["OK"]{.HTML-Code} + + + +::: FL + +::: + +::: TF +Figure: Steps of the actuation workflow using subscription/notification +::: + + + +### G.4.3 Forwarding model + +The forwarding model uses registrations and forwarding of requests. Actuation of +commands is provisioned via registration(s) to the NGSI-LD Registry done by the +Context Adapter that states "I am responsible for command property +<​X>". When the Application changes the value of a command property, +first the NGSI-LD [Context Broker]{.HTML-Keyboard} asks to the NGSI-LD Registry +whether the property is delegated to some other component. The NGSI-LD Registry +knows that property <​X> of the Entity is delegated to the Context +Adapter. Hence, the request is forwarded to the Context Adapter. Similar to the +other communication model, the request will then be translated into the +proprietary format and forwarded to the actuator using the actuator-specific +protocol. + +In this model, the NGSI-LD Entity is distributed over two different components, +because some of its properties live in the [Context Brokers]{.HTML-Keyboard} and +other properties live in the Context Adapter, as indicated in Figure+++below +with a dotted rectangle. + +The rest of the workflow, i.e. delivery of status and result messages to the +application, is done similarly to the subscription/notification model. The +detailed workflow is depicted in Figure+++below, and can be interpreted as +follows: + +1. Application updates _`turn-on`_ command _Property_ with ["value": + true]{.HTML-Code} +2. a. [Context Broker]{.HTML-Keyboard} ask Registry where to forward the + request b. [Context Broker]{.HTML-Keyboard} forwards request to Context + Adapter +3. Context Adapter updates _`turn-on-STATUS`_ command _Property_ with ["value": + "PENDING"]{.HTML-Code} +4. Application gets notification of the new value ["PENDING"]{.HTML-Code} +5. Context Adapter updates _`is-on`_ regular _Property_ with ["value": + true]{.HTML-Code} +6. Application gets notification with value:[true]{.HTML-Code} +7. Context Adapter updates _`turn-on-RESULT`_ command _Property_ with ["value": + "OK"]{.HTML-Code} +8. Application gets notification with the new value["OK"]{.HTML-Code} + + + +::: FL + +::: + +::: TF +Figure: Steps of the actuation workflow using forwarding +::: + + + +## G.5 Implementation of the subscription-based actuation workflow + +The [Fed4IoT project](https://fed4iot.org) leverages the NGSI-LD architecture +and the subscription/notification workflow for actuation, in order to implement +the concept of a Cloud of Things. It enables virtualization of existing IoT +sensors/actuators through Virtual Things and IoT Brokers. IoT application +developers can simply rent the Virtual Things and the Brokers their applications +need. + +The Fed4IoT's Cloud of Things is named +[VirIoT](https://github.com/fed4iot/VirIoT), and it is based on the concept of +Virtual Silos as-a-service: isolated and secure IoT environments made of Virtual +Things whose data can be accessed through standard IoT Brokers (oneM2M, NGSI, +NGSI-LD, etc.). + +In Figure+++below a diagram shows how VirIoT implements the concept of a +large-scale and distribute NGSI-LD system that leverages the architecture and +the workflow convention described in Clause+++root.4.2. + + + +::: FL + +::: + +::: TF +Figure: VirIoT implementation of the NGSI-LD system and actuation workflow +::: + + + +All components encapsulate requests in a neutral-format message that leverages +NGSI-LD Entities at its core. But, since VirIoT uses MQTT as its internal data +distribution system, all information and actuation commands are encoded as +NGSI-LD entities, plus an additional "meta header" that is used by the MQTT to +publish and subscribe in a broadcast fashion to multiple vThings, because the +same virtual sensor can be used by multiple applications at the same time. + +For the actuation workflow, the "data" part of this message contains the command +request, as specified in clause+++root.3, but with an additional value key that +is the "command notification uri" ([cmd-nuri]{.HTML-Sample}), representing a +location where feedback (status, result) should be sent by the ThingVisor. For +example, the [cmd-nuri]{.HTML-Sample} contains the "data_in" MQTT topic of the +issuing vSilo, so that command feedbacks (status and results) are sent to it, +only, instead of being broadcasted to all subscribing applications. + +VirIoT is agnostic to access control issues to a virtual actuator, since the +relevant policies are implemented in the specific ThingVisor, which can grant +tokens to execute actuation-commands to a subset of vSilos only, through +preliminary exchange of specific actuation-commands (a kind of log-in). + +Fed4IoT has developed several different ThingVisors (Context Adapters for +different sensors and hardware): for example, lamp systems and robot devices are +virtualized through specific ThingVisors, and applications can control the +lighting system of a rented conference room or control camera and position of a +bot by adding related virtual actuators to their vSilo. + +## G.6 Implementation of the registration-based actuation workflow + +The IoT Agent node library [i.21] introduces the concept of an IoT Agent, which +is a component that lets a group of devices send their data to and be managed +from a [Context Broker]{.HTML-Keyboard} using their own native protocols. Thus, +it corresponds to the Context Adapter, and wires up the IoT devices so that +measurements can be read and commands can be sent using NGSI-LD requests sent to +an NGSI-LD compliant context [Context Broker]{.HTML-Keyboard}. + +IoT Agents already exist or are in development for many IoT communication +protocols and data models. Examples include the following: + +- IoTAgent-JSON - a bridge between HTTP/MQTT messaging (with a JSON payload) and + NGSI-LD +- IoTAgent-LWM2M - a bridge between the Lightweight M2M protocol and NGSI-LD +- IoTAgent-UL - a bridge between HTTP/MQTT messaging (with an UltraLight2.0 + payload) and NGSI-LD +- IoTagent-LoRaWAN - a bridge between the LoRaWAN protocol and NGSI-LD + +This implementation follows the communication model described in +Clause+++root.4.3, as explained in Figure+++below. In this workflow: + +- Requests between User and [Context Broker]{.HTML-Keyboard} use NGSI-LD +- Requests between [Context Broker]{.HTML-Keyboard} and IoT Agent use NGSI-LD +- Requests between IoT Agent and IoT Device use native protocols +- Requests between IoT Device and IoT Agent use native protocols +- Requests between IoT Agent and [Context Broker]{.HTML-Keyboard} use NGSI-LD + + + +::: FL + +::: + +::: TF +Figure: IoT Agent node library implementation of the NGSI-LD system and actuation workflow +::: + + + +Provisioning of the devices will be carried out (via REST API) through IoT +Agents, as well. This provisioning implies that, on the one hand, the +corresponding entities (with their commands), that represent the devices, are +generated in the [Context Broker]{.HTML-Keyboard} and, on the other hand, that +the corresponding IoT Agent is configured for communication with the +corresponding device, all in one provisioning step. Below, an example how to +provision a device which supports start and stop commands is presented. ```json { - "date": "11 Safar, 1442 1:13:39PM" + "devices": [ + { + "device_id": "device001", + "entity_name": "urn:ngsi-ld:Device:001", + "entity_type": "Device", + "attributes": [ + { + "object_id": "s", + "name": "isOpen", + "type": "boolean" + } + ], + "commands": [ + { + "name": "start", + "type": "command" + }, + { + "name": "stop", + "type": "command" + } + ], + "static_attributes": [ + { + "name": { + "type": "Text", + "value": "Device:001 provision" + } + } + ] + } + ] } ``` - -Using an internationalization script such as the following: - -```js -new Intl.DateTimeFormat("en-u-ca-islamic", { - day: "numeric", - month: "long", - weekday: "long", - year: "numeric", -}).format(date); -``` - -It should be noted that post-localization, the transformed date is no longer -valid NGSI-LD. diff --git a/md/annex-h.md b/md/annex-h.md deleted file mode 100644 index be491185ce9cfbe24991280639dea7a9b3ecf69f..0000000000000000000000000000000000000000 --- a/md/annex-h.md +++ /dev/null @@ -1,579 +0,0 @@ -# Annex H [(informative)]{.inform}: Suggested actuation workflows - -## H.1 Actuators and feedback to the consumer - -Actuators are things that can change their state (light on/off) or execute -actions (move forward, detect face, etc.). - -There is currently no explicitly and precisely specified support for actuation -in the NGSI-LD API. Thus, this clause describes some conventions that represent -a proposed best-practice about how NGSI-LD API and data models can be used for -the interaction between applications and actuators represented by NGSI-LD -Entities. - -The conventions and approach described in this clause are not powerful enough to -implement complex actuation jobs that depend on each other and, for instance, -make actuation decisions conditional on the outcome of other actuations, unless -that behaviour is implemented in a custom way within the application logic. The -concept of a more evolved service execution logic, being a first-class citizen -of the NGSI-LD API and able to offer more structured building blocks for -actuation, is outside the scope of this annex. - -An NGSI-LD system that comprises an actuator and supports actuation workflows is -represented as one or more NGSI-LD Entities, plus a [Context -Broker]{.HTML-Keyboard}, a [Context Source]{.HTML-Keyboard} or a [Context -Producer]{.HTML-Keyboard}, and a [Context Consumer]{.HTML-Keyboard}, which -collaborate. - -The interaction between actuator and [Context Consumer]{.HTML-Keyboard} needs to -be bidirectional. Thus, actuators are triggered by the reception of -actuation-specific commands (e.g. "set the on state of the lamp to false", to -turn the light off) that are encoded as NGSI-LD data, following a suggested data -model. They respond with feedback, similarly encoded as NGSI-LD data. - -Command feedbacks may serve to control the maximum operations rate a controlling -application needs to achieve, and different levels of feedback can be requested, -by associating a specific Quality of Service value to the command: - -- Some applications need high operation rate but no feedback. For this case a - QoS = 0 can be used. The typical example is to control the arms of a robot - with a joystick. -- Some applications need to be sure that the actuators actually received the - command request or need to get back a payload in response to the command. In - this case a QoS = 1 can be used. The typical case is switching on a light with - confirmation, or request face-detection with consequent notification of - matching events. -- Commands can either require a short or a long execution time. For commands - with long execution time, the application may require a continuous status - feedback. In this case a QoS = 2 can be used. The typical example is that of a - door opening, where feedback continuously reports the current level (10 % - open, 50 % open, etc.). - -## H.2 Architecture for actuation - -In this architecture, the application acts as [Context -Consumer]{.HTML-Keyboard}, and the terms are used interchangeably. - -Commands are sent to the [Context Broker]{.HTML-Keyboard} by the [Context -Consumer]{.HTML-Keyboard}, using the standard NGSI-LD API and a suggested -convention for representing them. In turn, feedback about command execution is -received by the [Context Consumer]{.HTML-Keyboard}, both as continuous status -updates and/or a final command result. - -More specifically, the component that handles direct communication with the -actuator is the [Context Source]{.HTML-Keyboard} or the [Context -Producer]{.HTML-Keyboard}: it uses an actuator-specific protocol to control the -actuator and get responses and updates from it, i.e. from the real system. Such -[Context Source]{.HTML-Keyboard}/Consumer or [Context -Producer]{.HTML-Keyboard}/Storage acting as a proxy or intermediary to the -actuator is referred to, in the following, as Context Adapter. - -Thus, the Context Adapter is able to use the NGSI-LD API to receive NGSI-LD -command requests from the NGSI-LD [Context Broker]{.HTML-Keyboard} and send back -command status and result to it, as well as using an actuator-specific protocol -to communicate with the actuator. - -The NGSI-LD [Context Broker]{.HTML-Keyboard} is responsible for handling direct -communication with the [Context Consumer]{.HTML-Keyboard}. - -Thus, to support actuation, there is a need to specify: - -- Additional NGSI-LD Properties the NGSI-LD system has to have, in order to - represent and manage command Request, Status, Result. -- A communication model that allows commands to flow in forward direction and - feedback to flow in reverse. This communication model has to comprise a - mapping, to be held within the NGSI-LD system, that is able to route the - command requests to the appropriate handler within the Context Adapter and - vice-versa. - - - -::: FL - -::: - -::: TF -Figure: Architecture for actuation -::: - - - -## H.3 Structure of commands and additional Properties - -### H.3.1 Introduction - -The NGSI-LD system has, in addition to the usual NGSI-LD Properties representing -the actuator's status, a set of additional, dedicated NGSI-LD Properties -associated with: - -- the list of available commands, i.e. the list of commands supported by the - actuator; -- command endpoints, one for each command, that are used to send and receive - command related messages and optionally hold state for the ongoing commands. - -The structure of the commands needs to be specified, but not the internal format -of their payloads. By using commands with a custom payload, one can support all -kinds of operations, for example: - -- ["set-on": "true"]{.HTML-Sample} -- ["detect-face": {"face-features": "...."}]{.HTML-Sample} -- ["move": "forward"]{.HTML-Sample} - -The data model for command requests, status and responses has to include -metadata such as the QoS of the command, its identifier, and the custom payload -itself. - -Both the requests/responses and the list of commands the NGSI-LD system is able -to support can be represented with additional NGSI-LD Properties, as follows. - -### H.3.2 Property for listing available commands - -The additional _Property_ dedicated to the list of available commands is as -follows: - -```json -"commands": { - "type": "Property", - "value": ["<​cmd_name1>", "<​cmd_name2>", …, "<​cmd_nameN>"] -} -``` - -It is a _Property_ whose value is an array of Strings, each string representing -the unique name of a supported command. - -### H.3.3 Properties for command endpoints - -For each available command, a set of three endpoints is to be additionally -created within the NGSI-LD system, by means of three dedicated _Properties_ per -command. The first endpoint will manage that command's requests, the second -endpoint will manage its status, and the third endpoint will manage command's -results. - -This convention dictates that: - -- The NGSI-LD _Property_ that manages requests has the same name as the command, - e.g. ["<​cmd_name1>"]{.HTML-Code}. -- The NGSI-LD _Property_ that manages results has the same name as the command - plus the ["-RESULT"]{.HTML-Code} suffix. -- The NGSI-LD _Property_ that manages status has the same name as the command - plus the ["-STATUS"]{.HTML-Code} suffix. - -Each endpoint can receive multiple requests or responses, and it supports -queueing of messages. For example, the command _`moveToLocation`_ may receive a -sequence of requests that are to be stored in an array and orderly processed -depending on the arrival timestamps. A number of respective responses may be -produced, as well. Thus, each endpoint, represented by its dedicated NGSI-LD -_Property_, exploits the multi-Attribute feature (see Clause+++clause-8+++8.5), -as follows: - -**Command Request endpoint** - -```json -"<​cmd_name>": { - "datasetId": "a URI uniquely identifying the specific command request - (optional, if the use case does not need command queueing)", - "type": "Property", - "qos": "an Integer, representing the desired QoS (optional, default=0)", - "value": "custom parameters of the command (mandatory)" -} -``` - -**Command Status endpoint** - -```json -"<​cmd_name>-STATUS": { - "datasetId": "a URI uniquely identifying the specific status feedback message - (optional, if the use case does not need queueing them)", - "type": "Property", - "value": "custom status of the command (mandatory)" -} -``` - -**Command Result endpoint** - -```json -"<​cmd_name>-RESULT": { - "datasetId": "a URI uniquely identifying the specific result feedback message - (optional, if the use case does not need queueing them)", - "type": "Property", - "value": "custom result of the command (mandatory)" -} -``` - -Usually, the Context Adapter (or the actuator behind it), upon receiving a -command request with a specific _`datasetId`_, will then generate status and -result with the same _`datasetId`_, so that, when the status/result is received -by the application, it can link it back to the corresponding command that is -generating the received feedback. The value of the request, status and result is -generic, and it is up to the specific application to define useful values. As an -example, the PackML language for the control of packaging machines defines a set -of possible values for statuses during an actuation workflow. - - - ->>> [!tip] EXAMPLE 1: - -An example follows, where the NGSI-LD system represents a simple actuator. The -example shows the NGSI-LD Entity representing a light that can change colour by -manipulation of its brightness, hue and saturation values; further, it is -possible to turn the lamp on and off. Apart from the _`id`_ and -the _`type`_, the actuator entity has a set of regular properties -that represent the current status of the lamp. In the example these are -_`colorRGB`_ and _`is-on`_. Then it has the -conventional _Property_ named _`commands`_, -signalling that it supports four commands: ["turn-on"]{.HTML-Code}, -["set-saturation"]{.HTML-Code}, ["set-brightness"]{.HTML-Code}, -["set-hue"]{.HTML-Code}. Further, it has four (times three) additional -properties serving the purpose of command endpoints. - -```json -{ - "id": "urn:ngsi-ld:pHueActuator:light1", - "type": "Lamp", - // REGULAR PROPERTIES - "colorRGB": {"type": "Property", "value": "0xABABAB"}, - "is-on": {"type": "Property", "value": true}, - // AVAILABLE COMMANDS - "commands": { - "type": "Property", - "value": ["turn-on", "set-saturation", "set-hue", "set-brightness"] - }, - // COMMAND ENDPOINTS - "turn-on": {"type": "Property", "value": "<​custom request>"}, - "turn-on-STATUS": {"type": "Property", "value": "<​custom status>"}, - "turn-on-RESULT": {"type": "Property", "value": "<​custom response>"}, - "set-hue": … , - "set-hue-STATUS": … , - "set-hue-RESULT": … , - … -} -``` - ->>> - - - - - ->>> [!tip] EXAMPLE 2: - -The following example shows an NGSI-LD Entity Fragment that can be used as a -command request to request that the lamp be turned off. - -```json -{ - "id": "urn:ngsi-ld:pHueActuator:light1", - "type": "Lamp", - "turn-on": { - "type": "Property", - "qos": { - "type": "Property", - "value": 1 - }, - "value": false - } -} -``` - ->>> - - - - - ->>> [!tip] EXAMPLE 3: - -In the following example, the value of the command request is a more complex -JSON Object, to show that complex actions can be conveyed by just one request. -Further, the request has an identifier that makes it possible to enqueue it, -together with other request that may arrive to the same command endpoint within -a timespan. - -```json -{ - "id": "urn:ngsi-ld:pHueActuator:light1", - "type": "Lamp", - "set-hue": { - "type": "Property", - "qos": { - "type": "Property", - "value": 1 - }, - "datasetId": "myapp:mycommand:1342", - "value": { "red": "1 seconds", "green": "2 seconds" } - } -} -``` - ->>> - - - -In summary, the suggested convention prescribes a _`commands`_ _Property_ that -contains a list of commands supported by the actuator. For each of these -commands, the convention requires a command endpoint consisting of three -properties, the name of the command, e.g. ["turn-on"]{.HTML-Code}, the status -_Property_, which is the name of the command with ["-STATUS"]{.HTML-Code} as -suffix, and the result, which is the name of the command with -["-RESULT"]{.HTML-Code} as suffix. Nevertheless, it is noted that such suffixes -are just a convention to distinguish the endpoints. So far, two practical -implementations exist, see Clause+++root.5 and Clause+++root.6, that adopt the -general scheme of this convention, with minor deviations. In fact, this -convention is derived as a generalization that leverages the full potential of -NGSI-LD sub-Attributes and multi-Attributes. - -## H.4 Communication model - -### H.4.1 Possible communication models - -This convention can be leveraged by two different communication models: - -- Subscription/notification, where both the application and the Context Adapter - use NGSI-LD Subscriptions to have the command requests delivered to the - appropriate handler within the Context Adapter and vice-versa. In this case - the Context Adapter acts as a [Context Source]{.HTML-Keyboard} as well as a - [Context Consumer]{.HTML-Keyboard}. -- Forwarding, which uses the NGSI-LD Registry and a Context Adapter able to - federate itself with the [Context Broker]{.HTML-Keyboard} holding the - actuator's Entity, as a means to deliver the commands. In this case the - Context Adapter acts as a Context Storage as well as a [Context - Producer]{.HTML-Keyboard}. - -### H.4.2 Subscription/notification model - -For the interaction to work, the Context Adapter, acting as a proxy to the -actuator, subscribes to all command properties; in example 1 of -Clause+++root.3.3, these are ["set-brightness"]{.HTML-Code}, -["set-saturation"]{.HTML-Code}, ["set-hue"]{.HTML-Code} and -["turn-on"]{.HTML-Code}. When the application, acting as the actuation client, -updates the value of a command property, the Context Adapter will receive the -notification with the new value. This will be translated into the proprietary -format and forwarded to the actuator using the actuator-specific protocol. The -application in turn can subscribe to the command status and the result. The -Context Adapter updates the status of the actuation during the execution of the -command, which is primarily relevant in the case of longer-lasting actuations, -and finally updates the result once the actuation has been completed. If the -application has subscribed to the status and result, it will receive the -corresponding notifications. Independent of the command-related properties, the -status of the actuator, held within its regular properties, will be updated. - -The detailed workflow is depicted in Figure+++below, and can be interpreted as -follows: - -1. Application updates _`turn-on`_ command Property with ["value": - true]{.HTML-Code} -2. Context Adapter gets notification of the new value _`true`_ -3. Context Adapter updates _`turn-on-STATUS`_ command Property with ["value": - "PENDING"]{.HTML-Code} -4. Application gets notification of the new value ["PENDING"]{.HTML-Code} -5. Context Adapter updates _`is-on`_ regular Property with ["value": - true]{.HTML-Code} -6. Application gets notification with value: [true]{.HTML-Code} -7. Context Adapter updates _`turn-on-RESULT`_ command Property with ["value": - "OK"]{.HTML-Code} -8. Application gets notification with of the new value ["OK"]{.HTML-Code} - - - -::: FL - -::: - -::: TF -Figure: Steps of the actuation workflow using subscription/notification -::: - - - -### H.4.3 Forwarding model - -The forwarding model uses registrations and forwarding of requests. Actuation of -commands is provisioned via registration(s) to the NGSI-LD Registry done by the -Context Adapter that states "I am responsible for command property -<​X>". When the Application changes the value of a command property, -first the NGSI-LD [Context Broker]{.HTML-Keyboard} asks to the NGSI-LD Registry -whether the property is delegated to some other component. The NGSI-LD Registry -knows that property <​X> of the Entity is delegated to the Context -Adapter. Hence, the request is forwarded to the Context Adapter. Similar to the -other communication model, the request will then be translated into the -proprietary format and forwarded to the actuator using the actuator-specific -protocol. - -In this model, the NGSI-LD Entity is distributed over two different components, -because some of its properties live in the [Context Brokers]{.HTML-Keyboard} and -other properties live in the Context Adapter, as indicated in Figure+++below -with a dotted rectangle. - -The rest of the workflow, i.e. delivery of status and result messages to the -application, is done similarly to the subscription/notification model. The -detailed workflow is depicted in Figure+++below, and can be interpreted as -follows: - -1. Application updates _`turn-on`_ command _Property_ with ["value": - true]{.HTML-Code} -2. a. [Context Broker]{.HTML-Keyboard} ask Registry where to forward the - request b. [Context Broker]{.HTML-Keyboard} forwards request to Context - Adapter -3. Context Adapter updates _`turn-on-STATUS`_ command _Property_ with ["value": - "PENDING"]{.HTML-Code} -4. Application gets notification of the new value ["PENDING"]{.HTML-Code} -5. Context Adapter updates _`is-on`_ regular _Property_ with ["value": - true]{.HTML-Code} -6. Application gets notification with value:[true]{.HTML-Code} -7. Context Adapter updates _`turn-on-RESULT`_ command _Property_ with ["value": - "OK"]{.HTML-Code} -8. Application gets notification with the new value["OK"]{.HTML-Code} - - - -::: FL - -::: - -::: TF -Figure: Steps of the actuation workflow using forwarding -::: - - - -## H.5 Implementation of the subscription-based actuation workflow - -The [Fed4IoT project](https://fed4iot.org) leverages the NGSI-LD architecture -and the subscription/notification workflow for actuation, in order to implement -the concept of a Cloud of Things. It enables virtualization of existing IoT -sensors/actuators through Virtual Things and IoT Brokers. IoT application -developers can simply rent the Virtual Things and the Brokers their applications -need. - -The Fed4IoT's Cloud of Things is named -[VirIoT](https://github.com/fed4iot/VirIoT), and it is based on the concept of -Virtual Silos as-a-service: isolated and secure IoT environments made of Virtual -Things whose data can be accessed through standard IoT Brokers (oneM2M, NGSI, -NGSI-LD, etc.). - -In Figure+++below a diagram shows how VirIoT implements the concept of a -large-scale and distribute NGSI-LD system that leverages the architecture and -the workflow convention described in Clause+++root.4.2. - - - -::: FL - -::: - -::: TF -Figure: VirIoT implementation of the NGSI-LD system and actuation workflow -::: - - - -All components encapsulate requests in a neutral-format message that leverages -NGSI-LD Entities at its core. But, since VirIoT uses MQTT as its internal data -distribution system, all information and actuation commands are encoded as -NGSI-LD entities, plus an additional "meta header" that is used by the MQTT to -publish and subscribe in a broadcast fashion to multiple vThings, because the -same virtual sensor can be used by multiple applications at the same time. - -For the actuation workflow, the "data" part of this message contains the command -request, as specified in clause+++root.3, but with an additional value key that -is the "command notification uri" ([cmd-nuri]{.HTML-Sample}), representing a -location where feedback (status, result) should be sent by the ThingVisor. For -example, the [cmd-nuri]{.HTML-Sample} contains the "data_in" MQTT topic of the -issuing vSilo, so that command feedbacks (status and results) are sent to it, -only, instead of being broadcasted to all subscribing applications. - -VirIoT is agnostic to access control issues to a virtual actuator, since the -relevant policies are implemented in the specific ThingVisor, which can grant -tokens to execute actuation-commands to a subset of vSilos only, through -preliminary exchange of specific actuation-commands (a kind of log-in). - -Fed4IoT has developed several different ThingVisors (Context Adapters for -different sensors and hardware): for example, lamp systems and robot devices are -virtualized through specific ThingVisors, and applications can control the -lighting system of a rented conference room or control camera and position of a -bot by adding related virtual actuators to their vSilo. - -## H.6 Implementation of the registration-based actuation workflow - -The IoT Agent node library [i.22] introduces the concept of an IoT Agent, which -is a component that lets a group of devices send their data to and be managed -from a [Context Broker]{.HTML-Keyboard} using their own native protocols. Thus, -it corresponds to the Context Adapter, and wires up the IoT devices so that -measurements can be read and commands can be sent using NGSI-LD requests sent to -an NGSI-LD compliant context [Context Broker]{.HTML-Keyboard}. - -IoT Agents already exist or are in development for many IoT communication -protocols and data models. Examples include the following: - -- IoTAgent-JSON - a bridge between HTTP/MQTT messaging (with a JSON payload) and - NGSI-LD -- IoTAgent-LWM2M - a bridge between the Lightweight M2M protocol and NGSI-LD -- IoTAgent-UL - a bridge between HTTP/MQTT messaging (with an UltraLight2.0 - payload) and NGSI-LD -- IoTagent-LoRaWAN - a bridge between the LoRaWAN protocol and NGSI-LD - -This implementation follows the communication model described in -Clause+++root.4.3, as explained in Figure+++below. In this workflow: - -- Requests between User and [Context Broker]{.HTML-Keyboard} use NGSI-LD -- Requests between [Context Broker]{.HTML-Keyboard} and IoT Agent use NGSI-LD -- Requests between IoT Agent and IoT Device use native protocols -- Requests between IoT Device and IoT Agent use native protocols -- Requests between IoT Agent and [Context Broker]{.HTML-Keyboard} use NGSI-LD - - - -::: FL - -::: - -::: TF -Figure: IoT Agent node library implementation of the NGSI-LD system and actuation workflow -::: - - - -Provisioning of the devices will be carried out (via REST API) through IoT -Agents, as well. This provisioning implies that, on the one hand, the -corresponding entities (with their commands), that represent the devices, are -generated in the [Context Broker]{.HTML-Keyboard} and, on the other hand, that -the corresponding IoT Agent is configured for communication with the -corresponding device, all in one provisioning step. Below, an example how to -provision a device which supports start and stop commands is presented. - -```json -{ - "devices": [ - { - "device_id": "device001", - "entity_name": "urn:ngsi-ld:Device:001", - "entity_type": "Device", - "attributes": [ - { - "object_id": "s", - "name": "isOpen", - "type": "boolean" - } - ], - "commands": [ - { - "name": "start", - "type": "command" - }, - { - "name": "stop", - "type": "command" - } - ], - "static_attributes": [ - { - "name": { - "type": "Text", - "value": "Device:001 provision" - } - } - ] - } - ] -} -``` diff --git a/md/clause-2_References.md b/md/clause-2_References.md index 1dd98f8ef2843860d9faf8e930e1b2a14afcc9d1..a6f26e7dbd07047d606824c336e0fb506db1572d 100644 --- a/md/clause-2_References.md +++ b/md/clause-2_References.md @@ -144,9 +144,7 @@ conformance to the present document. [i.20] [NGSI-LD Examples](https://forge.etsi.org/rep/NGSI-LD/NGSI-LD/tree/master/examples). -[i.21] [NGSI-LD Wrapper](https://github.com/Fiware/NGSI-LD_Wrapper): "Experimental proxy for adaptation between FIWARE® and NGSI-LD". - -[i.22] [IoT Agent Library](https://github.com/telefonicaid/iotagent-node-lib). +[i.21] [IoT Agent Library](https://github.com/telefonicaid/iotagent-node-lib). ::: diff --git a/md/clause-4.md b/md/clause-4.md index 03eb3368a515c8d6e92be57a152c7c8de2c49434..97be4e160d0ec2ed419ead20b0cabfd5550b6fc8 100644 --- a/md/clause-4.md +++ b/md/clause-4.md @@ -15,7 +15,7 @@ As stated in clause 3.1, the letters "NGSI-LD" which are part of most terms, to confirm that they are distinct from other terms of similar/same name in use in other organizations, are generally omitted in the present document for brevity. In the present document, a number of rather obvious typographic conventions and -syntax guidelines are followed, and the reader is referred to annex f for +syntax guidelines are followed, and the reader is referred to Annex E for details. ## 4.2 NGSI-LD information model diff --git a/md/clause-5.md b/md/clause-5.md index 77926d0219d661a673bd1403fc849e7267d5b98c..49248b6de99749a7bb4e0171222650cae3634243 100644 --- a/md/clause-5.md +++ b/md/clause-5.md @@ -3824,9 +3824,8 @@ Link header (see Clause+++clause-6+++6.2.4). An NGSI-LD Entity shall be represented by an object encoded using JSON-LD [n.8]. The rules described below state the default encoding (known as the **normalized -format**) that shall be supported by implementations. Annex D provides a -computational description of this process in terms of an algorithm. An example -of this representation can be found in Annex C, Clause+++annex-c+++C.2.2.1. +format**) that shall be supported by implementations. An example of this +representation can be found in Annex C, Clause+++annex-c+++C.2.2.1. The JSON-LD object that contains the following members: