draft-ietf-core-dynlink-07.txt   draft-ietf-core-dynlink-08.txt 
CoRE Working Group Z. Shelby CoRE Working Group Z. Shelby
Internet-Draft ARM Internet-Draft ARM
Intended status: Informational M. Koster Intended status: Informational M. Koster
Expires: April 25, 2019 SmartThings Expires: September 9, 2019 SmartThings
C. Groves C. Groves
J. Zhu J. Zhu
Huawei Huawei
B. Silverajan, Ed. B. Silverajan, Ed.
Tampere University of Technology Tampere University
October 22, 2018 March 08, 2019
Dynamic Resource Linking for Constrained RESTful Environments Dynamic Resource Linking for Constrained RESTful Environments
draft-ietf-core-dynlink-07 draft-ietf-core-dynlink-08
Abstract Abstract
For CoAP (RFC7252), Dynamic linking of state updates between This specification defines Link Bindings, which provide dynamic
resources, either on an endpoint or between endpoints, is defined linking of state updates between resources, either on an endpoint or
with the concept of Link Bindings. This specification defines between endpoints, for systems using CoAP (RFC7252). This
conditional observation attributes that work with Link Bindings or specification also defines Conditional Notification Attributes that
with CoAP Observe (RFC7641). work with Link Bindings or with CoAP Observe (RFC7641).
Editor note Editor note
The git repository for the draft is found at https://github.com/core- The git repository for the draft is found at https://github.com/core-
wg/dynlink wg/dynlink
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
skipping to change at page 1, line 46 skipping to change at page 1, line 46
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 25, 2019. This Internet-Draft will expire on September 9, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Conditional Notification Attributes . . . . . . . . . . . . . 4
3.1. The "bind" attribute and Binding Methods . . . . . . . . 4 3.1. Attribute Definitions . . . . . . . . . . . . . . . . . . 4
3.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 5 3.1.1. Minimum Period (pmin) . . . . . . . . . . . . . . . . 5
3.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 5 3.1.2. Maximum Period (pmax) . . . . . . . . . . . . . . . . 5
3.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1.3. Change Step (st) . . . . . . . . . . . . . . . . . . 5
3.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 6 3.1.4. Greater Than (gt) . . . . . . . . . . . . . . . . . . 6
4. Binding and Resource Observation Attributes . . . . . . . . . 6 3.1.5. Less Than (lt) . . . . . . . . . . . . . . . . . . . 6
4.1. Minimum Period (pmin) . . . . . . . . . . . . . . . . . . 7 3.1.6. Notification Band (band) . . . . . . . . . . . . . . 7
4.2. Maximum Period (pmax) . . . . . . . . . . . . . . . . . . 7 3.2. Server processing of Conditional Notification Attributes 8
4.3. Change Step (st) . . . . . . . . . . . . . . . . . . . . 7 4. Link Bindings . . . . . . . . . . . . . . . . . . . . . . . . 8
4.4. Greater Than (gt) . . . . . . . . . . . . . . . . . . . . 8 4.1. The "bind" attribute and Binding Methods . . . . . . . . 9
4.5. Less Than (lt) . . . . . . . . . . . . . . . . . . . . . 8 4.1.1. Polling . . . . . . . . . . . . . . . . . . . . . . . 10
4.6. Notification Band (band) . . . . . . . . . . . . . . . . 8 4.1.2. Observe . . . . . . . . . . . . . . . . . . . . . . . 10
4.7. Attribute Interactions . . . . . . . . . . . . . . . . . 9 4.1.3. Push . . . . . . . . . . . . . . . . . . . . . . . . 11
5. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 10 4.2. Link Relation . . . . . . . . . . . . . . . . . . . . . . 11
6. Implementation Considerations . . . . . . . . . . . . . . . . 11 5. Binding Table . . . . . . . . . . . . . . . . . . . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 6. Implementation Considerations . . . . . . . . . . . . . . . . 12
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13
8.1. Interface Description . . . . . . . . . . . . . . . . . . 12 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
8.1. Resource Type value 'core.bnd' . . . . . . . . . . . . . 13
8.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 13 8.2. Link Relation Type . . . . . . . . . . . . . . . . . . . 13
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 13 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14
10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 13 10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 14
11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 13 11. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 14
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 16
12.1. Normative References . . . . . . . . . . . . . . . . . . 15 12.1. Normative References . . . . . . . . . . . . . . . . . . 16
12.2. Informative References . . . . . . . . . . . . . . . . . 16 12.2. Informative References . . . . . . . . . . . . . . . . . 17
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 16 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 17
A.1. Greater Than (gt) example . . . . . . . . . . . . . . . . 16 A.1. Greater Than (gt) example . . . . . . . . . . . . . . . . 17
A.2. Greater Than (gt) and Period Max (pmax) example . . . . . 17 A.2. Greater Than (gt) and Period Max (pmax) example . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction 1. Introduction
IETF Standards for machine to machine communication in constrained IETF Standards for machine to machine communication in constrained
environments describe a REST protocol [RFC7252] and a set of related environments describe a REST protocol [RFC7252] and a set of related
information standards that may be used to represent machine data and information standards that may be used to represent machine data and
machine metadata in REST interfaces. CoRE Link-format [RFC6690] is a machine metadata in REST interfaces. CoRE Link-format [RFC6690] is a
standard for doing Web Linking [RFC8288] in constrained environments. standard for doing Web Linking [RFC8288] in constrained environments.
This specification introduces the concept of a Link Binding, which This specification introduces the concept of a Link Binding, which
defines a new link relation type to create a dynamic link between defines a new link relation type to create a dynamic link between
resources over which state updates are conveyed. Specifically, a resources over which state updates are conveyed. Specifically, a
Link Binding is a unidirectional link for binding the states of Link Binding is a unidirectional link for binding the states of
source and destination resources together such that updates to one source and destination resources together such that updates to one
are sent over the link to the other. CoRE Link Format are sent over the link to the other. CoRE Link Format
representations are used to configure, inspect, and maintain Link representations are used to configure, inspect, and maintain Link
Bindings. This specification additionally defines a set of Bindings. This specification additionally defines Conditional
conditional Observe Attributes for use with Link Bindings and with Notification Attributes for use with Link Bindings and with the CoRE
the standalone CoRE Observe [RFC7641] method. Observe [RFC7641] method.
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This specification requires readers to be familiar with all the terms This specification requires readers to be familiar with all the terms
skipping to change at page 4, line 5 skipping to change at page 4, line 7
the resource values between a source and a destination. The the resource values between a source and a destination. The
process of using a REST method to achieve this is defined as process of using a REST method to achieve this is defined as
"State Synchronization". The endpoint triggering the state "State Synchronization". The endpoint triggering the state
synchronization is the synchronization initiator. synchronization is the synchronization initiator.
Notification Band: A resource value range that results in state Notification Band: A resource value range that results in state
sychronization. The value range may be bounded by a minimum and sychronization. The value range may be bounded by a minimum and
maximum value or may be unbounded having either a minimum or maximum value or may be unbounded having either a minimum or
maximum value. maximum value.
3. Link Bindings 3. Conditional Notification Attributes
In a M2M RESTful environment, endpoints may directly exchange the
content of their resources to operate the distributed system. For
example, a light switch may supply on-off control information that
may be sent directly to a light resource for on-off control.
Beforehand, a configuration phase is necessary to determine how the
resources of the different endpoints are related to each other. This
can be done either automatically using discovery mechanisms or by
means of human intervention and a so-called commissioning tool. In
this specification such an abstract relationship between two
resources is defined, called a link Binding. The configuration phase
necessitates the exchange of binding information so a format
recognized by all CoRE endpoints is essential. This specification
defines a format based on the CoRE Link-Format to represent binding
information along with the rules to define a binding method which is
a specialized relationship between two resources. The purpose of
such a binding is to synchronize the content between a source
resource and a destination resource. The destination resource MAY be
a group resource if the authority component of the destination URI
contains a group address (either a multicast address or a name that
resolves to a multicast address). Since a binding is unidirectional,
the binding entry defining a relationship is present only on one
endpoint. The binding entry may be located either on the source or
the destination endpoint depending on the binding method.
3.1. The "bind" attribute and Binding Methods
A binding method defines the rules to generate the web-transfer
exchanges that synchronize state between source and destination
resources. By using REST methods content is sent from the source
resource to the destination resource.
In order to use binding methods, this specification defines a special
CoRE link attribute "bind". This is the identifier of a binding
method which defines the rules to synchronize the destination
resource. This attribute is mandatory.
+----------------+-----------+------------+
| Attribute | Parameter | Value |
+----------------+-----------+------------+
| Binding method | bind | xsd:string |
+----------------+-----------+------------+
Table 1: The bind attribute
The following table gives a summary of the binding methods defined in
this specification.
+---------+------------+-------------+---------------+
| Name | Identifier | Location | Method |
+---------+------------+-------------+---------------+
| Polling | poll | Destination | GET |
| | | | |
| Observe | obs | Destination | GET + Observe |
| | | | |
| Push | push | Source | PUT |
+---------+------------+-------------+---------------+
Table 2: Binding Method Summary
The description of a binding method must define the following
aspects:
Identifier: This is the value of the "bind" attribute used to
identify the method.
Location: This information indicates whether the binding entry is
stored on the source or on the destination endpoint.
REST Method: This is the REST method used in the Request/Response
exchanges.
Conditions: A binding method definition must state how the condition
attributes of the abstract binding definition are actually used in
this specialized binding.
The binding methods are described in more detail below.
3.1.1. Polling
The Polling method consists of sending periodic GET requests from the
destination endpoint to the source resource and copying the content
to the destination resource. The binding entry for this method MUST
be stored on the destination endpoint. The destination endpoint MUST
ensure that the polling frequency does not exceed the limits defined
by the pmin and pmax attributes of the binding entry. The copying
process MAY filter out content from the GET requests using value-
based conditions (e.g based on the Change Step, Less Than, Greater
Than attributes).
3.1.2. Observe
The Observe method creates an observation relationship between the
destination endpoint and the source resource. On each notification
the content from the source resource is copied to the destination
resource. The creation of the observation relationship requires the
CoAP Observation mechanism [RFC7641] hence this method is only
permitted when the resources are made available over CoAP. The
binding entry for this method MUST be stored on the destination
endpoint. The binding conditions are mapped as query string
parameters (see Section 4).
3.1.3. Push
When the Push method is assigned to a binding, the source endpoint
sends PUT requests to the destination resource when the binding
condition attributes are satisfied for the source resource. The
source endpoint MUST only send a notification request if the binding
conditions are met. The binding entry for this method MUST be stored
on the source endpoint.
3.2. Link Relation
Since Binding involves the creation of a link between two resources,
Web Linking and the CoRE Link-Format are a natural way to represent
binding information. This involves the creation of a new relation
type, named "boundto". In a Web link with this relation type, the
target URI contains the location of the source resource and the
context URI points to the destination resource.
4. Binding and Resource Observation Attributes 3.1. Attribute Definitions
In addition to "bind", this specification further defines Web link This specification defines Conditional Notification Attributes, which
attributes allowing a fine-grained control of the type of state provide for fine-grained control of notification and state
synchronization along with the conditions that trigger an update. synchronization when using CoRE Observe [RFC7641] or Link Bindings
(see Section 4). Conditional Notification Attributes define the
conditions that trigger a notification.
When resource interfaces following this specification are made When resource interfaces following this specification are made
available over CoAP, the CoAP Observation mechanism [RFC7641] MAY available over CoAP, the CoAP Observation mechanism [RFC7641] MAY
also be used to observe any changes in a resource, and receive also be used to observe any changes in a resource, and receive
asynchronous notifications as a result. A resource using an asynchronous notifications as a result. A resource marked as
interface description defined in this specification and marked as Observable in its link description SHOULD support these Conditional
Observable in its link description SHOULD support these observation Notification Attributes.
parameters.
In addition, the set of parameters are defined here allow a client to The set of parameters defined here allow a client to control how
control how often a client is interested in receiving notifications often a client is interested in receiving notifications and how much
and how much a resource value should change for the new a resource value should change for the new representation to be
representation to be interesting, as query parameters. interesting.
These query parameters MUST be treated as resources that are read One or more Notification Attributes MAY be included as query
using GET and updated using PUT, and MUST NOT be included in the parameters in an Observe request.
Observe request. Multiple parameters MAY be updated at the same time
by including the values in the query string of a PUT. Before being
updated, these parameters have no default value.
These attributes are defined below: These attributes are defined below:
+--------------------+-----------+------------------+ +--------------------+-----------+------------------+
| Attribute | Parameter | Value | | Attribute | Parameter | Value |
+--------------------+-----------+------------------+ +--------------------+-----------+------------------+
| Minimum Period (s) | pmin | xsd:integer (>0) | | Minimum Period (s) | pmin | xsd:decimal (>0) |
| | | | | | | |
| Maximum Period (s) | pmax | xsd:integer (>0) | | Maximum Period (s) | pmax | xsd:decimal (>0) |
| | | | | | | |
| Change Step | st | xsd:decimal (>0) | | Change Step | st | xsd:decimal (>0) |
| | | | | | | |
| Greater Than | gt | xsd:decimal | | Greater Than | gt | xsd:decimal |
| | | | | | | |
| Less Than | lt | xsd:decimal | | Less Than | lt | xsd:decimal |
| | | | | | | |
| Notification Band | band | xsd:boolean | | Notification Band | band | xsd:boolean |
+--------------------+-----------+------------------+ +--------------------+-----------+------------------+
Table 3: Binding Attributes Summary Table 1: Conditional Notification Attributes
4.1. Minimum Period (pmin) Conditional Notification Attributes SHOULD be evaluated on all
potential notifications from a resource, whether resulting from an
internal server-driven sampling process or from external update
requests to the server.
When present, the minimum period indicates the minimum time to wait Note: In this draft, we assume that there are finite quantization
(in seconds) before triggering a new state synchronization (even if effects in the internal or external updates to the value of a
it has changed). In the absence of this parameter, the minimum resource; specifically, that a resource may be updated at any time
period is up to the synchronization initiator. The minimum period with any valid value. We therefore avoid any continuous-time
MUST be greater than zero otherwise the receiver MUST return a CoAP assumptions in the description of the Conditional Notification
error code 4.00 "Bad Request" (or equivalent). Attributes and instead use the phrase "sampled value" to refer to a
member of a sequence of values that may be internally observed from
the resource state over time.
4.2. Maximum Period (pmax) 3.1.1. Minimum Period (pmin)
When present, the maximum period indicates the maximum time in When present, the minimum period indicates the minimum time, in
seconds between two consecutive state synchronizations (regardless if seconds, between two consecutive notifications (whether or not the
it has changed). In the absence of this parameter, the maximum resource value has changed). In the absence of this parameter, the
period is up to the synchronization initiator. The maximum period minimum period is up to the server. The minimum period MUST be
MUST be greater than zero and MUST be greater than the minimum period greater than zero otherwise the receiver MUST return a CoAP error
code 4.00 "Bad Request" (or equivalent).
A server MAY report the last sampled value that occured during the
pmin interval, after the pmin interval expires.
Note: Due to finite quantization effects, the time between
notifications may be greater than pmin even when the sampled value
changes within the pmin interval. Pmin may or may not be used to
drive the internal sampling process.
3.1.2. Maximum Period (pmax)
When present, the maximum period indicates the maximum time, in
seconds, between two consecutive notifications (whether or not the
resource value has changed). In the absence of this parameter, the
maximum period is up to the server. The maximum period MUST be
greater than zero and MUST be greater than the minimum period
parameter (if present) otherwise the receiver MUST return a CoAP parameter (if present) otherwise the receiver MUST return a CoAP
error code 4.00 "Bad Request" (or equivalent). error code 4.00 "Bad Request" (or equivalent).
4.3. Change Step (st) 3.1.3. Change Step (st)
When present, the change step indicates how much the value of a When present, the change step indicates how much the value of a
resource SHOULD change before triggering a new state synchronization resource SHOULD change before triggering a notification, compared to
(compared to the value of the previous synchronization). Upon the value of the previous notification. Upon reception of a query
reception of a query including the st attribute the current value including the st attribute, the most recently sampled value of the
(CurrVal) of the resource is set as the initial value (STinit). Once resource is reported, and then set as the last reported value
the resource value differs from the STinit value (i.e. CurrVal >= (last_rep_v). When a subsequent sample or update of the resource
STinit + ST or CurrVal <= STint - ST) then a new state value differs from the last reported value by an amount, positive or
synchronization occurs. STinit is then set to the state negative, greater than or equal to st, and the time for pmin has
synchronization value and new state synchronizations are based on a elapsed since the last notification, a notification is sent and the
change step against this value. The change step MUST be greater than last reported value is updated to the value sent in the notification.
zero otherwise the receiver MUST return a CoAP error code 4.00 "Bad The change step MUST be greater than zero otherwise the receiver MUST
Request" (or equivalent). return a CoAP error code 4.00 "Bad Request" (or equivalent).
The Change Step parameter can only be supported on resources with an The Change Step parameter can only be supported on resources with a
atomic numeric value. scalar numeric value.
Note: Due to the state synchronization based update of STint it may Note: Due to sampling and other constraints, e.g. pmin, the resource
result in that resource value received in two sequential state value received in two sequential notifications may differ by more
synchronizations differs by more than st. than st.
4.4. Greater Than (gt) 3.1.4. Greater Than (gt)
When present, Greater Than indicates the upper limit value the When present, Greater Than indicates the upper limit value the
resource value SHOULD cross before triggering a new state sampled value SHOULD cross before triggering a notification. A
synchronization. State synchronization only occurs when the resource notification is sent whenever the sampled value crosses the specified
value exceeds the specified upper limit value. The actual resource upper limit value, relative to the last reported value, and the time
value is used for the synchronization rather than the gt value. If fpr pmin has elapsed since the last notification. The sampled value
the value continues to rise, no new state synchronizations are is sent in the notification. If the value continues to rise, no
generated as a result of gt. If the value drops below the upper notifications are generated as a result of gt. If the value drops
limit value and then exceeds the upper limit then a new state below the upper limit value then a notification is sent, subject
synchronization is generated. again to the pmin time.
4.5. Less Than (lt) The Greater Than parameter can only be supported on resources with a
scalar numeric value.
3.1.5. Less Than (lt)
When present, Less Than indicates the lower limit value the resource When present, Less Than indicates the lower limit value the resource
value SHOULD cross before triggering a new state synchronization. value SHOULD cross before triggering a notification. A notification
State synchronization only occurs when the resource value is less is sent when the samples value crosses the specified lower limit
than the specified lower limit value. The actual resource value is value, relative to the last reported value, and the time fpr pmin has
used for the synchronization rather than the lt value. If the value elapsed since the last notification. The sampled value is sent in
continues to fall no new state synchronizations are generated as a the notification. If the value continues to fall no notifications
result of lt. If the value rises above the lower limit value and are generated as a result of lt. If the value rises above the lower
then drops below the lower limit then a new state synchronization is limit value then a new notification is sent, subject to the pmin
generated. time..
4.6. Notification Band (band) The Less Than parameter can only be supported on resources with a
scalar numeric value.
3.1.6. Notification Band (band)
The notification band attribute allows a bounded or unbounded (based The notification band attribute allows a bounded or unbounded (based
on a minimum or maximum) value range that may trigger multiple state on a minimum or maximum) value range that may trigger multiple
synchronizations. This enables use cases where different ranges notifications. This enables use cases where different ranges results
results in differing behaviour. For example: monitoring the in differing behaviour. For example: monitoring the temperature of
temperature of machinery. Whilst the temperature is in the normal machinery. Whilst the temperature is in the normal operating range
operating range only periodic observations are needed. However as only periodic observations are needed. However as the temperature
the temperature moves to more abnormal ranges more frequent moves to more abnormal ranges more frequent synchronization/reporting
synchronization/reporting may be needed. may be needed.
Without a notification band, a transition across a less than (lt), or Without a notification band, a transition across a less than (lt), or
greater than (gt) limit only generates one notification. This means greater than (gt) limit only generates one notification. This means
that it is not possible to describe a case where multiple that it is not possible to describe a case where multiple
notifications are sent so long as the limit is exceeded. notifications are sent so long as the limit is exceeded.
The band attribute works as a modifier to the behaviour of gt and lt. The band attribute works as a modifier to the behaviour of gt and lt.
Therefore, if band is present in a query, gt, lt or both, MUST be Therefore, if band is present in a query, gt, lt or both, MUST be
included. included.
When band is present with the lt attribute, it defines the lower When band is present with the lt attribute, it defines the lower
bound for the notification band (notification band minimum). State bound for the notification band (notification band minimum).
synchronization occurs when the resource value is equal to or above Notifications occur when the resource value is equal to or above the
the notification band minimum. If lt is not present there is no notification band minimum. If lt is not present there is no minimum
minimum value for the band. value for the band.
When band is present with the gt attribute, it defines the upper When band is present with the gt attribute, it defines the upper
bound for the notification band (notification band maximum). State bound for the notification band (notification band maximum).
synchronization occurs when the resource value is equal to or below Notifications occur when the resource value is equal to or below the
the notification band maximum. If gt is not present there is no notification band maximum. If gt is not present there is no maximum
maximum value for the band. value for the band.
If band is present with both the gt and lt attributes, two kinds of If band is present with both the gt and lt attributes, notification
signaling bands are specified. occurs when the resource value is greater than or equal to gt or when
the resource value is less than or equal to lt.
If a band is specified in which the value of gt is less than that of If a band is specified in which the value of gt is less than that of
lt, in-band signaling occurs. State synchronization occurs whenever lt, in-band notification occurs. That is, notification occurs
the resource value is between the notification band minimum and whenever the resource value is between the gt and lt values,
maximum or is equal to the notification band minimum or maximum. including equal to gt or lt.
On the other hand if the band is specified in which the value of gt If the band is specified in which the value of gt is greater than
is greater than that of lt, out-of-band signaling occurs. State that of lt, out-of-band notification occurs. That is, notification
synchronization occurs whenever the resource value is outside the occurs when the resource value not between the gt and lt values,
notification band minimum and maximum or is equal to the notification excluding equal to gt and lt.
band minimum or maximum.
4.7. Attribute Interactions The Notification Band parameter can only be supported on resources
with a scalar numeric value.
Pmin, pmax, st, gt and lt may be present in the same query. 3.2. Server processing of Conditional Notification Attributes
Parameters are not defined at multiple prioritization levels.
Instead, the server state machine generates a notification whenever Pmin, pmax, st, gt, lt and band may be present in the same query.
any of the parameter conditions are met, after which it performs a Howver, they are not defined at multiple prioritization levels. The
reset on all the requested conditions. State synchronization also server sends a notification whenever any of the parameter conditions
occurs only once even if there are multiple conditions being met at are met, upon which it updates its last notification value and time
the same time. The reference code below illustrates how to prepare for the next notification. Only one notification occurs
notifications are generated. when there are multiple conditions being met at the same time. The
reference code below illustrates the logic to determine when a
notification is to be sent.
bool notifiable( Resource * r ) { bool notifiable( Resource * r ) {
#define BAND r->band #define BAND r->band
#define SCALAR_TYPE ( num_type == r->type ) #define SCALAR_TYPE ( num_type == r->type )
#define STRING_TYPE ( str_type == r->type ) #define STRING_TYPE ( str_type == r->type )
#define BOOLEAN_TYPE ( bool_type == r->type ) #define BOOLEAN_TYPE ( bool_type == r->type )
#define PMIN_EX ( r->last_sample_time - r->last_rep_time >= r->pmin ) #define PMIN_EX ( r->last_sample_time - r->last_rep_time >= r->pmin )
#define PMAX_EX ( r->last_sample_time - r->last_rep_time > r->pmax ) #define PMAX_EX ( r->last_sample_time - r->last_rep_time > r->pmax )
#define LT_EX ( r->v < r->lt ^ r->last_rep_v < r->lt ) #define LT_EX ( r->v < r->lt ^ r->last_rep_v < r->lt )
skipping to change at page 10, line 33 skipping to change at page 8, line 44
( ( !BAND && ( GT_EX || LT_EX || ST_EX || PMAX_EX ) ) || ( ( !BAND && ( GT_EX || LT_EX || ST_EX || PMAX_EX ) ) ||
( BAND && IN_BAND && ( ST_EX || PMAX_EX) ) ) ( BAND && IN_BAND && ( ST_EX || PMAX_EX) ) )
: STRING_TYPE ? : STRING_TYPE ?
( VS_CHANGE || PMAX_EX ) ( VS_CHANGE || PMAX_EX )
: BOOLEAN_TYPE ? : BOOLEAN_TYPE ?
( VB_CHANGE || PMAX_EX ) ( VB_CHANGE || PMAX_EX )
: false ) : false )
); );
} }
Figure 1: Code logic for attribute interactions for observe Figure 1: Code logic for conditional notification attribute
notification interactions
4. Link Bindings
In a M2M RESTful environment, endpoints may directly exchange the
content of their resources to operate the distributed system. For
example, a light switch may supply on-off control information that
may be sent directly to a light resource for on-off control.
Beforehand, a configuration phase is necessary to determine how the
resources of the different endpoints are related to each other. This
can be done either automatically using discovery mechanisms or by
means of human intervention and a so-called commissioning tool.
In this specification such an abstract relationship between two
resources is defined, called a Link Binding. The configuration phase
necessitates the exchange of binding information, so a format
recognized by all CoRE endpoints is essential. This specification
defines a format based on the CoRE Link-Format to represent binding
information along with the rules to define a binding method which is
a specialized relationship between two resources.
The purpose of such a binding is to synchronize content updates
between a source resource and a destination resource. The
destination resource MAY be a group resource if the authority
component of the destination URI contains a group address (either a
multicast address or a name that resolves to a multicast address).
Since a binding is unidirectional, the binding entry defining a
relationship is present only on one endpoint. The binding entry may
be located either on the source or the destination endpoint depending
on the binding method.
Conditional Notification Attributes defined in Section 3 can be used
with Link Bindings in order to customize the notification behavior
and timing.
4.1. The "bind" attribute and Binding Methods
A binding method defines the rules to generate the network-transfer
exchanges that synchronize state between source and destination
resources. By using REST methods content is sent from the source
resource to the destination resource.
This specification defines a new CoRE link attribute "bind". This is
the identifier for a binding method which defines the rules to
synchronize the destination resource. This attribute is mandatory.
+----------------+-----------+------------+
| Attribute | Parameter | Value |
+----------------+-----------+------------+
| Binding method | bind | xsd:string |
+----------------+-----------+------------+
Table 2: The bind attribute
The following table gives a summary of the binding methods defined in
this specification.
+---------+------------+-------------+---------------+
| Name | Identifier | Location | Method |
+---------+------------+-------------+---------------+
| Polling | poll | Destination | GET |
| | | | |
| Observe | obs | Destination | GET + Observe |
| | | | |
| Push | push | Source | PUT |
+---------+------------+-------------+---------------+
Table 3: Binding Method Summary
The description of a binding method defines the following aspects:
Identifier: This is the value of the "bind" attribute used to
identify the method.
Location: This information indicates whether the binding entry is
stored on the source or on the destination endpoint.
REST Method: This is the REST method used in the Request/Response
exchanges.
Conditional Notification: How Conditional Notification Attributes
are used in the binding.
The binding methods are described in more detail below.
4.1.1. Polling
The Polling method consists of sending periodic GET requests from the
destination endpoint to the source resource and copying the content
to the destination resource. The binding entry for this method MUST
be stored on the destination endpoint. The destination endpoint MUST
ensure that the polling frequency does not exceed the limits defined
by the pmin and pmax attributes of the binding entry. The copying
process MAY filter out content from the GET requests using value-
based conditions (e.g based on the Change Step, Less Than, Greater
Than attributes).
4.1.2. Observe
The Observe method creates an observation relationship between the
destination endpoint and the source resource. On each notification
the content from the source resource is copied to the destination
resource. The creation of the observation relationship requires the
CoAP Observation mechanism [RFC7641] hence this method is only
permitted when the resources are made available over CoAP. The
binding entry for this method MUST be stored on the destination
endpoint. The binding conditions are mapped as query parameters in
the Observe request (see Section 3).
4.1.3. Push
When the Push method is assigned to a binding, the source endpoint
sends PUT requests to the destination resource when the Conditional
Notification Attributes are satisfied for the source resource. The
source endpoint SHOULD only send a notification request if any
included Conditional Notification Attributes are met. The binding
entry for this method MUST be stored on the source endpoint.
4.2. Link Relation
Since Binding involves the creation of a link between two resources,
Web Linking and the CoRE Link-Format used to represent binding
information. This involves the creation of a new relation type,
"boundto". In a Web link with this relation type, the target URI
contains the location of the source resource and the context URI
points to the destination resource.
5. Binding Table 5. Binding Table
The Binding table is a special resource that gives access to the The Binding Table is a special resource that describes the bindings
bindings on a endpoint. This section defines a REST interface for on an endpoint. An endpoint offering a representation of the Binding
Binding table resources. The Binding table resource MUST support the Table resource SHOULD indicate its presence and enable its discovery
Binding interface defined below. The interface supports the link- by advertising a link at "/.well-known/core" [RFC6690]. If so, the
format type. Binding Table resource MUST be discoverable by using the Resource
Type (rt) 'core.bnd'.
The if= column defines the Interface Description (if=) attribute The Methods column defines the REST methods supported by the Binding
value to be used in the CoRE Link Format for a resource conforming to Table, which are described in more detail below.
that interface. When this value appears in the if= attribute of a
link, the resource MUST support the corresponding REST interface
described in this section. The resource MAY support additional
functionality, which is out of scope for this specification.
Although this interface description is intended to be used with the
CoRE Link Format, it is applicable for use in any REST interface
definition.
The Methods column defines the REST methods supported by the +---------------+----------+----------+----------------+
interface, which are described in more detail below. | Resource | rt= | Methods | Content-Format |
+---------------+----------+----------+----------------+
| Binding Table | core.bnd | GET, PUT | link-format |
+---------------+----------+----------+----------------+
+-----------+----------+-------------------+-----------------+ Table 4: Binding Table Description
| Interface | if= | Methods | Content-Formats |
+-----------+----------+-------------------+-----------------+
| Binding | core.bnd | GET, POST, DELETE | link-format |
+-----------+----------+-------------------+-----------------+
Table 4: Binding Interface Description The REST methods GET and PUT are used to manipulate a Binding Table.
A GET request simply returns the current state of a Binding Table. A
request with a PUT method and a content format of application/link-
format is used to clear the bindings to the table or replaces its
entire contents. All links in the payload of a PUT rquest MUST have
a relation type "boundto".
The Binding interface is used to manipulate a binding table. A (Editor's Note: Usage of the PATCH method for fine-grained addition
request with a POST method and a content format of application/link- and removal of individual bindings is under study.)
format simply appends new bindings to the table. All links in the
payload MUST have a relation type "boundto". A GET request simply
returns the current state of a binding table whereas a DELETE request
empties the table. Individual entries may be deleted from the table
by specifying the resource path in a DELETE request.
The following example shows requests for adding, retrieving and The following example shows requests for discovering, retrieving and
deleting bindings in a binding table. replacing bindings in a binding table.
Req: POST /bnd/ (Content-Format: application/link-format) Req: GET /.well-known/core?rt=core.bnd (application/link-format)
Res: 2.05 Content (application/link-format)
</bnd/>;rt=core.bnd;ct=40
Req: GET /bnd/
Res: 2.05 Content (application/link-format)
<coap://sensor.example.com/a/switch1/>;
rel=boundto;bind=obs;anchor=/a/fan,;bind="obs",
<coap://sensor.example.com/a/switch2/>;
rel=boundto;bind=obs;anchor=/a/light;bind="obs"
Req: PUT /bnd/ (Content-Format: application/link-format)
<coap://sensor.example.com/s/light>; <coap://sensor.example.com/s/light>;
rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"
Res: 2.04 Changed Res: 2.04 Changed
Req: GET /bnd/ Req: GET /bnd/
Res: 2.05 Content (application/link-format) Res: 2.05 Content (application/link-format)
<coap://sensor.example.com/s/light>; <coap://sensor.example.com/s/light>;
rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60" rel="boundto";anchor="/a/light";bind="obs";pmin="10";pmax="60"
Req: DELETE /bnd/a/light Figure 2: Binding Table Example
Res: 2.04 Changed
Req: DELETE /bnd/
Res: 2.04 Changed
Figure 2: Binding Interface Example
6. Implementation Considerations 6. Implementation Considerations
When using multiple resource bindings (e.g. multiple Observations of When using multiple resource bindings (e.g. multiple Observations of
resource) with different bands, consideration should be given to the resource) with different bands, consideration should be given to the
resolution of the resource value when setting sequential bands. For resolution of the resource value when setting sequential bands. For
example: Given BandA (Abmn=10, Bbmx=20) and BandB (Bbmn=21, Bbmx=30). example: Given BandA (Abmn=10, Bbmx=20) and BandB (Bbmn=21, Bbmx=30).
If the resource value returns an integer then notifications for If the resource value returns an integer then notifications for
values between and inclusive of 10 and 30 will be triggered. Whereas values between and inclusive of 10 and 30 will be triggered. Whereas
if the resolution is to one decimal point (0.1) then notifications if the resolution is to one decimal point (0.1) then notifications
for values 20.1 to 20.9 will not be triggered. for values 20.1 to 20.9 will not be triggered.
The use of the notification band minimum and maximum allow for a The use of the notification band minimum and maximum allow for a
synchronization whenever a change in the resource value occurs. synchronization whenever a change in the resource value occurs.
Theoretically this could occur in-line with the server internal Theoretically this could occur in-line with the server internal
sample period for the determining the resource value. Implementors sample period for the determining the resource value. Implementors
SHOULD consider the resolution needed before updating the resource, SHOULD consider the resolution needed before updating the resource,
e.g. updating the resource when a temperature sensor value changes by e.g. updating the resource when a temperature sensor value changes by
0.001 degree versus 1 degree. 0.001 degree versus 1 degree.
The initiation of a link binding can be delegated from a client to a The initiation of a Link Binding can be delegated from a client to a
link state machine implementation, which can be an embedded client or link state machine implementation, which can be an embedded client or
a configuration tool. Implementation considerations have to be given a configuration tool. Implementation considerations have to be given
to how to monitor transactions made by the configuration tool with to how to monitor transactions made by the configuration tool with
regards to link bindings, as well as any errors that may arise with regards to Link Bindings, as well as any errors that may arise with
establishing link bindings as well as with established link bindings. establishing Link Bindings in addition to established Link Bindings.
7. Security Considerations 7. Security Considerations
Consideration has to be given to what kinds of security credentials Consideration has to be given to what kinds of security credentials
the state machine of a configuration tool or an embedded client needs the state machine of a configuration tool or an embedded client needs
to be configured with, and what kinds of access control lists client to be configured with, and what kinds of access control lists client
implementations should possess, so that transactions on creating link implementations should possess, so that transactions on creating Link
bindings and handling error conditions can be processed by the state Bindings and handling error conditions can be processed by the state
machine. machine.
8. IANA Considerations 8. IANA Considerations
8.1. Interface Description 8.1. Resource Type value 'core.bnd'
The specification registers the "binding" CoRE interface description This specification registers a new Resource Type Link Target
link target attribute value as per [RFC6690]. Attribute 'core.bnd' in the Resource Type (rt=) registry established
as per [RFC6690].
Attribute Value: core.bnd Attribute Value: core.bnd
Description: The binding interface is used to manipulate a binding Description: See Section 5. This attribute value is used to discover
table which describes the link bindings between source and the resource representing a binding table, which describes the link
destination resources for the purposes of synchronizing their bindings between source and destination resources for the purposes of
content. synchronizing their content.
Reference: This specification. Note to RFC editor: please insert the Reference: This specification. Note to RFC editor: please insert the
RFC of this specification. RFC of this specification.
Notes: None Notes: None
8.2. Link Relation Type 8.2. Link Relation Type
This specification registers the new "boundto" link relation type as This specification registers the new "boundto" link relation type as
per [RFC8288]. per [RFC8288].
skipping to change at page 13, line 47 skipping to change at page 14, line 35
Matthieu Vial Matthieu Vial
Schneider-Electric Schneider-Electric
Grenoble Grenoble
France France
Phone: +33 (0)47657 6522 Phone: +33 (0)47657 6522
EMail: matthieu.vial@schneider-electric.com EMail: matthieu.vial@schneider-electric.com
11. Changelog 11. Changelog
draft-ietf-core-dynlink-08
o Reorganize the draft to introduce Conditional Notification
Attributes at the beginning
o Made pmin and pmax type xsd:decimal to accommodate fractional
second timing
o updated the attribute descriptions. lt and gt notify on all
crossings, both directions
o updated Binding Table description, removed interface description
but introduced core.bnd rt attribute value
draft-ietf-core-dynlink-07 draft-ietf-core-dynlink-07
o Added reference code to illustrate attribute interactions for o Added reference code to illustrate attribute interactions for
observations observations
draft-ietf-core-dynlink-06
o Document restructure and refactoring into three main sections o Document restructure and refactoring into three main sections
o Clarifications on band usage o Clarifications on band usage
o Implementation considerations introduced o Implementation considerations introduced
o Additional text on security considerations o Additional text on security considerations
draft-ietf-core-dynlink-05 draft-ietf-core-dynlink-05
skipping to change at page 19, line 26 skipping to change at page 20, line 26
Jintao Zhu Jintao Zhu
Huawei Huawei
No.127 Jinye Road, Huawei Base, High-Tech Development District No.127 Jinye Road, Huawei Base, High-Tech Development District
Xi'an, Shaanxi Province Xi'an, Shaanxi Province
China China
Email: jintao.zhu@huawei.com Email: jintao.zhu@huawei.com
Bilhanan Silverajan (editor) Bilhanan Silverajan (editor)
Tampere University of Technology Tampere University
Korkeakoulunkatu 10 Kalevantie 4
Tampere FI-33720 Tampere FI-33100
Finland Finland
Email: bilhanan.silverajan@tut.fi Email: bilhanan.silverajan@tuni.fi
 End of changes. 59 change blocks. 
324 lines changed or deleted 372 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/