--- 1/draft-ietf-core-dynlink-01.txt 2017-02-23 20:13:10.499685436 -0800 +++ 2/draft-ietf-core-dynlink-02.txt 2017-02-23 20:13:10.535686291 -0800 @@ -1,59 +1,57 @@ CoRE Working Group Z. Shelby Internet-Draft ARM Intended status: Informational Z. Vial -Expires: May 1, 2017 Schneider-Electric +Expires: August 28, 2017 Schneider-Electric M. Koster SmartThings C. Groves Huawei - October 28, 2016 + February 24, 2017 Dynamic Resource Linking for Constrained RESTful Environments - draft-ietf-core-dynlink-01 + draft-ietf-core-dynlink-02 Abstract For CoAP [RFC7252] Dynamic linking of state updates between resources, either on an endpoint or between endpoints, is defined with the concept of Link Bindings. This specification defines conditional observation attributes that work with Link Bindings or with CoAP Observe [RFC7641]. Editor's note: o The git repository for the draft is found at https://github.com/ core-wg/dynlink - o Examples need to be added. - Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on May 1, 2017. + This Internet-Draft will expire on August 28, 2017. Copyright Notice - Copyright (c) 2016 IETF Trust and the persons identified as the + Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as @@ -61,42 +59,46 @@ Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 3 3.1. Binding Methods . . . . . . . . . . . . . . . . . . . . . 4 3.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 5 3.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 5 3.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 5 - 3.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 5 + 3.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 6 3.3. Binding Attributes . . . . . . . . . . . . . . . . . . . 6 3.3.1. Bind Method (bind) . . . . . . . . . . . . . . . . . 6 3.3.2. Minimum Period (pmin) . . . . . . . . . . . . . . . . 6 - 3.3.3. Maximum Period (pmax) . . . . . . . . . . . . . . . . 6 + 3.3.3. Maximum Period (pmax) . . . . . . . . . . . . . . . . 7 3.3.4. Change Step (st) . . . . . . . . . . . . . . . . . . 7 - 3.3.5. Greater Than (gt) . . . . . . . . . . . . . . . . . . 7 - 3.3.6. Less Than (lt) . . . . . . . . . . . . . . . . . . . 7 + 3.3.5. Greater Than (gth) . . . . . . . . . . . . . . . . . 7 + 3.3.6. Less Than (lth) . . . . . . . . . . . . . . . . . . . 7 3.3.7. Attribute Interactions . . . . . . . . . . . . . . . 8 4. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 8 4.1. Binding Interface Description . . . . . . . . . . . . . . 8 4.2. Resource Observation Attributes . . . . . . . . . . . . . 9 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 6.1. Interface Description . . . . . . . . . . . . . . . . . . 11 6.2. Link Relations Type . . . . . . . . . . . . . . . . . . . 11 - 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 + 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 12 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 9.1. Normative References . . . . . . . . . . . . . . . . . . 13 9.2. Informative References . . . . . . . . . . . . . . . . . 13 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 + Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 13 + A.1. Greater Than (gth) example . . . . . . . . . . . . . . . 13 + A.2. Greater Than (gth) and Period Max (pmax) example . . . . 14 + + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 1. Introduction IETF Standards for machine to machine communication in constrained environments describe a REST protocol and a set of related information standards that may be used to represent machine data and machine metadata in REST interfaces. CoRE Link-format is a standard for doing Web Linking [RFC5988] in constrained environments. This specification introduces the concept of a Link Binding, which @@ -249,23 +252,23 @@ | Attribute | Parameter | Value | +--------------------+-----------+------------------+ | Binding method | bind | xsd:string | | | | | | Minimum Period (s) | pmin | xsd:integer (>0) | | | | | | Maximum Period (s) | pmax | xsd:integer (>0) | | | | | | Change Step | st | xsd:decimal (>0) | | | | | - | Greater Than | gt | xsd:decimal | + | Greater Than | gth | xsd:decimal | | | | | - | Less Than | lt | xsd:decimal | + | Less Than | lth | xsd:decimal | +--------------------+-----------+------------------+ Table 2: Binding Attributes Summary 3.3.1. Bind Method (bind) This is the identifier of a binding method which defines the rules to synchronize the destination resource. This attribute is mandatory. 3.3.2. Minimum Period (pmin) @@ -299,65 +302,66 @@ synchronization occurs. STinit is then set to the state synchronization value and new state synchronizations are based on a change step against this value. The change step MUST be greater than zero otherwise the receiver MUST return a CoAP error code 4.00 "Bad Request" (or equivalent). Note: Due to the state synchronization based update of STint it may result in that resource value received in two sequential state synchronizations differs by more than st. -3.3.5. Greater Than (gt) +3.3.5. Greater Than (gth) When present, Greater Than indicates the upper limit value the resource value SHOULD cross before triggering a new state synchronization. State synchronization only occurs when the resource value exceeds the specified upper limit value. The actual resource - value is used for the synchronization rather than the gt value. If + value is used for the synchronization rather than the gth value. If the value continues to rise, no new state synchronizations are - generated as a result of gt. If the value drops below the upper + generated as a result of gth. If the value drops below the upper limit value and then exceeds the upper limit then a new state synchronization is generated. -3.3.6. Less Than (lt) +3.3.6. Less Than (lth) When present, Less Than indicates the lower limit value the resource value SHOULD cross before triggering a new state synchronization. State synchronization only occurs when the resource value is less than the specified lower limit value. The actual resource value is - used for the synchronization rather than the lt value. If the value + used for the synchronization rather than the lth value. If the value continues to fall no new state synchronizations are generated as a - result of lt. If the value rises above the lower limit value and + result of lth. If the value rises above the lower limit value and then drops below the lower limit then a new state synchronization is generated. 3.3.7. Attribute Interactions - Pmin, pmax, st, gt and lt may be present in the same query. + Pmin, pmax, st, gth and lth may be present in the same query. If pmin and pmax are present in a query then they take precedence - over the other parameters. Thus even if st, gt or lt are met, if + over the other parameters. Thus even if st, gth or lth are met, if pmin has not been exceeded then no state synchronization occurs. - Likewise if st, gt or lt have not been met and pmax time has expired - then state synchronization occurs. The current value of the resource - is used for the synchronization. If pmin time is exceeded and st, gt - or lt are met then the current value of the resource is synchronized. - If st is also included, a state synchronization resulting from pmin - or pmax updates STinit with the synchronized value. + Likewise if st, gth or lth have not been met and pmax time has + expired then state synchronization occurs. The current value of the + resource is used for the synchronization. If pmin time is exceeded + and st, gth or lth are met then the current value of the resource is + synchronized. If st is also included, a state synchronization + resulting from pmin or pmax updates STinit with the synchronized + value. - If gt and lt are included gt MUST be greater than lt otherwise an + If gth and lth are included gth MUST be greater than lth otherwise an error CoAP error code 4.00 "Bad Request" (or equivalent) MUST be returned. - If st is included in a query with a gt or lt attribute then state + If st is included in a query with a gth or lth attribute then state synchronizations occur only when the conditions described by st AND - gt or st AND gl are met. + gth or st AND gl are met. 4. Binding Table The binding table is a special resource that gives access to the bindings on a endpoint. A binding table resource MUST support the Binding interface defined below. A profile SHOULD allow only one resource table per endpoint. 4.1. Binding Interface Description @@ -437,23 +441,23 @@ +----------------+------------------+------------------+ | Resource | Parameter | Data Format | +----------------+------------------+------------------+ | Minimum Period | /{resource}?pmin | xsd:integer (>0) | | | | | | Maximum Period | /{resource}?pmax | xsd:integer (>0) | | | | | | Change Step | /{resource}?st | xsd:decimal (>0) | | | | | - | Less Than | /{resource}?lt | xsd:decimal | + | Less Than | /{resource}?lth | xsd:decimal | | | | | - | Greater Than | /{resource}?gt | xsd:decimal | + | Greater Than | /{resource}?gth | xsd:decimal | +----------------+------------------+------------------+ Table 4: Resource Observation Attribute Summary Minimum Period: As per Section 3.3.2 Maximum Period: As per Section 3.3.3 Change Step: As per Section 3.3.4 @@ -472,27 +476,21 @@ attempt to take advantage of a poorly implemented client for example to crash the node or perform denial of service. 6. IANA Considerations 6.1. Interface Description The specification registers the "binding" CoRE interface description link target attribute value as per [RFC6690]. - Attribute Value: binding - - Editor's note: RFC6690 actually indicates the use of core. for CoRE - WG documents. Therefore it probably is more correct to register - core.binding . However this may cause a problem for existing - implementations. One approach may be to register two attributes - "binding" and "core.binding." + Attribute Value: core.binding Description: The binding interface is used to manipulate a binding table which describes the link bindings between source and destination resources for the purposes of synchronizing their content. Reference: This specification. Note to RFC editor: please insert the RFC of this specification. Notes: None @@ -521,20 +519,32 @@ Acknowledgement is given to colleagues from the SENSEI project who were critical in the initial development of the well-known REST interface concept, to members of the IPSO Alliance where further requirements for interface types have been discussed, and to Szymon Sasin, Cedric Chauvenet, Daniel Gavelle and Carsten Bormann who have provided useful discussion and input to the concepts in this specification. 8. Changelog + draft-ietf-core-dynlink-02 + + o General: Changed the name of the greater than attribute "gt" to + "gth" and the name of the less than attribute "lt" to "lth" due to + conlict with the core resource directory draft lifetime "lt" + attribute. + + o Clause 6.1: Addressed the editor's note by changing the link + target attribute to "core.binding". + + o Added Appendix A for examples. + draft-ietf-core-dynlink-01 o General: The term state synchronization has been introduced to describe the process of synchronization between destination and source resources. o General: The document has been restructured the make the information flow better. o Clause 3.1: The descriptions of the binding attributes have been @@ -585,20 +595,110 @@ [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014, . [RFC7641] Hartke, K., "Observing Resources in the Constrained Application Protocol (CoAP)", RFC 7641, DOI 10.17487/RFC7641, September 2015, . +Appendix A. Examples + + This appendix provides some examples of the use of binding attribute + / observe attributes. + + Note: For brevity the only the method or response code is shown in + the header field. + +A.1. Greater Than (gth) example + Observed CLIENT SERVER Actual + t State | | State + ____________ | | ____________ + 1 | | + 2 unknown | | 18.5 Cel + 3 +----->| Header: GET + 4 | GET | Token: 0x4a + 5 | | Uri-Path: temperature + 6 | | Uri-Query: gth="25" + 7 | | Observe: 0 (register) + 8 | | + 9 ____________ |<-----+ Header: 2.05 + 10 | 2.05 | Token: 0x4a + 11 18.5 Cel | | Observe: 9 + 12 | | Payload: "18.5 Cel" + 13 | | + 14 | | + 15 | | ____________ + 16 ____________ |<-----+ Header: 2.05 + 17 | 2.05 | 26 Cel Token: 0x4a + 18 26 Cel | | Observe: 16 + 29 | | Payload: "26 Cel" + 20 | | + 21 | | + + Figure 2: Client Registers and Receives one Notification of the + Current State and One of a New State when it passes through the + greather than threshold of 25. + +A.2. Greater Than (gth) and Period Max (pmax) example + + Observed CLIENT SERVER Actual + t State | | State + ____________ | | ____________ + 1 | | + 2 unknown | | 18.5 Cel + 3 +----->| Header: GET + 4 | GET | Token: 0x4a + 5 | | Uri-Path: temperature + 6 | | Uri-Query: pmax="20";gth="25" + 7 | | Observe: 0 (register) + 8 | | + 9 ____________ |<-----+ Header: 2.05 + 10 | 2.05 | Token: 0x4a + 11 18.5 Cel | | Observe: 9 + 12 | | Payload: "18.5 Cel" + 13 | | + 14 | | + 15 | | + 16 | | + 17 | | + 18 | | + 19 | | + 20 | | + 21 | | + 22 | | + 23 | | + 24 | | + 25 | | + 26 | | + 27 | | + 28 | | + 29 | | ____________ + 30 ____________ |<-----+ Header: 2.05 + 31 | 2.05 | 23 Cel Token: 0x4a + 32 23 Cel | | Observe: 30 + 33 | | Payload: "23 Cel" + 34 | | + 35 | | + 36 | | ____________ + 37 ____________ |<-----+ Header: 2.05 + 38 | 2.05 | 26 Cel Token: 0x4a + 39 26 Cel | | Observe: 37 + 40 | | Payload: "26 Cel" + 41 | | + 42 | | + + Figure 3: Client Registers and Receives one Notification of the + Current State, one when pmax time expires and one of a new State when + it passes through the greather than threshold of 25. + Authors' Addresses Zach Shelby ARM 150 Rose Orchard San Jose 95134 FINLAND Phone: +1-408-203-9434 Email: zach.shelby@arm.com @@ -615,11 +715,11 @@ 665 Clyde Avenue Mountain View 94043 USA Email: michael.koster@smartthings.com Christian Groves Huawei Australia - Email: Christian.Groves@nteczone.com + Email: cngroves.std@gmail.com