CoRE Working Group C. Groves Internet-Draft W. Yang Intended status: Standards Track Huawei Expires: August 25, 2017 February 21, 2017 Additional CoAP Binding and Observe Attributes draft-groves-core-obsattr-00 Abstract [I-D.ietf-core-dynlink] defines five CoAP Observaton attributes (minimum period, maximum period, band step, less than and greater than) to control when notifications are sent. These attributes are insufficient for some use cases. This document specifies additional attributes allowing for notification bands, initialization values, band step, sample number window and sample time window to allow for a wider range of use cases. 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 August 25, 2017. Copyright Notice 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 Groves & Yang Expires August 25, 2017 [Page 1] Internet-Draft CoAP Observe Attr. February 2017 the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Requirements Language . . . . . . . . . . . . . . . . . . . . 2 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Binding and Resource Observation Attributes . . . . . . . . . 4 4.1. Initialization Value (iv) . . . . . . . . . . . . . . . . 5 4.2. Notification Band Minimum (bmn) . . . . . . . . . . . . . 6 4.3. Notification Band Maximum (bmx) . . . . . . . . . . . . . 6 4.4. Band Step (bst) . . . . . . . . . . . . . . . . . . . . . 6 4.5. Sample Number Window . . . . . . . . . . . . . . . . . . 7 4.6. Sample Time Window . . . . . . . . . . . . . . . . . . . 7 4.7. Interactions . . . . . . . . . . . . . . . . . . . . . . 8 4.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . 9 4.8.1. Example 1 - Band Minimum and Maximum . . . . . . . . 9 4.8.2. Example 2 - Band Minimum and Maximum and Step . . . . 10 4.8.3. Example 3 - Band Minimum and Maximum, Step and Initialization Value . . . . . . . . . . . . . . . . 10 4.8.4. Example 4 - Step and Initialization Value . . . . . . 11 4.8.5. Example 5 - Band Minimum and Maximum, Band Step and Initial Value . . . . . . . . . . . . . . . . . . . . 11 4.8.6. Example 6 - Band Minimum and Sample Number Window . . 12 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 12 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 9.1. Normative References . . . . . . . . . . . . . . . . . . 12 9.2. Informative References . . . . . . . . . . . . . . . . . 13 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 1. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2. Introduction [I-D.ietf-core-dynlink] defines five CoAP Binding and Observaton attributes (minimum period, maximum period, change step, less than and greater than) to control when notifications are sent. The currently defined attributes have characteristics that means some use cases cannot be supported. These are described below: Groves & Yang Expires August 25, 2017 [Page 2] Internet-Draft CoAP Observe Attr. February 2017 o A transition across a less than (lt), or greater than (gt) limit or a change step (st) only generates one notification. This means that it is not possible to describe a case where multiple notifications are sent so long as the limit is exceeded. o The change step (st) value is not deterministic when setting the attribute. A client cannot set the initial value that the change step applies to. The change step is based on the initial value sent by the server. This means that a client cannot indicate that it wants the change step (st=10) to apply to a certain increment (e.g. 10, 20, 30) instead it relies on the initial value from the client. Thus a change step of 10 could result in reporting (11, 21, 31) or equally (15, 27, 53). o SenML allows for multiple values (records) to be reported for a resource. The current attributes do not allow a method for a client to request a particular number of records or sample time window. In order to allow a more complete set of use cases to be supported this specification introduces several new attributes. The notification band attributes "Notification Band Minimum" (bmn) and "Notification Band Maximum" (bmx) attributes allow a bounded or unbounded (based on a minimum or maximum) value range that may trigger multiple state synchronizations. This enables use cases where different ranges results in differing behaviour. For example: monitoring the temperature of machinery. Whilst the temperature is in the normal operating range only periodic observations are needed. However as the temperature moves to more abnormal ranges more frequent synchronization/reporting may be needed. An "Initialization Value" (iv) attribute allows a seed value for the calculation of the change step to be specified. This allows use cases where synchronization occurs around a known value. For example: synchronization will occur based on the operating temperature set point of a machine. Without the initialization synchronization will occur around the first measured value. A "Band Step" (bst) attribute defines a series of bands that will trigger state synchronization. This allows use cases where state synchronization is required against known levels. Rather than synchronizing based on a difference to a previous synchronization value, synchronization occurs against a fixed known level. For example: it allows state sychronisation for a sensor when it's value is between (5,10],(10,15],(15,20] etc. Groves & Yang Expires August 25, 2017 [Page 3] Internet-Draft CoAP Observe Attr. February 2017 The "Sample Number Window" (snw) attribute allows a number of state synchronizations to be queued before the actual queue synchronization occurs. Once the number of queued state synchronizations has reached a certain level then a single queue synchronization occurs with the multiple resource values related to individual state synchronizations included. This allows use cases where multiple resource values are required but frequent synchronization is not required as there is a need to minimise resource usage. For example: a meter may need to be recorded once an hour but the values only need to be synchronized once a day. The "Sample Time Window" (stw) attribute as per the sample number window allows state synchronizations to be queued before the actual queue synchronization occurs. The queue synchronization occurs when the indicated period expires independent of the number of samples. 3. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in [RFC2119]. This specification requires readers to be familiar with all the terms and concepts that are discussed in [RFC5988] and [RFC6690]. This specification makes use of the following additional terminology: Notification Band: A resource value range that results in state sychronization. The value range may be bounded by a minimum and maximum value or may be unbounded having either a minimum or maximum value. 4. Binding and Resource Observation Attributes The attributes defined in this section are additional attributes that may be used as binding attributes (3.3/[I-D.ietf-core-dynlink]) and resource observation attributes (4.2/[I-D.ietf-core-dynlink]). This specification introduces several new attributes: Groves & Yang Expires August 25, 2017 [Page 4] Internet-Draft CoAP Observe Attr. February 2017 +---------------------------+-----------------+------------------+ | Attribute Name | Parameter | Data Format | +---------------------------+-----------------+------------------+ | Initialialization Value | /{resource}?iv | xsd:decimal | | | | | | Band Minimum Notification | /{resource}?bmn | xsd:decimal | | | | | | Band Maximum Notification | /{resource}?bmx | xsd:decimal | | | | | | Band Step | /{resource}?bst | xsd:decimal (>0) | | | | | | Sample Number Window | /{resource}?snw | xsd:integer (>0) | | | | | | Sample Time Window | /{resource}?stw | xsd:integer (>0) | +---------------------------+-----------------+------------------+ Table 1: Resource Observation Attribute Summary The attributes may only be included at most once in a query. 4.1. Initialization Value (iv) The attribute indicates the initialization value to be used to determine when a change step is notified. As such it MUST only be present in a query when the change step (st) or band step (bst) attribute is present (see [I-D.ietf-core-dynlink]). If st or bst is not present then the receiver MUST return a CoAP error code 4.00 "Bad Request" (or equivalent). Without iv, on reception of a query the synchronization initiator uses the current value for the observed resource as the initial value to which the change step is applied. The use of iv overrides this behaviour and the iv value is used for the initial value (STinit or BSTinit). A state synchronization occurs once the resource value differs from the initial value by the change step value (i.e. CurrVal >= STinit + ST or CurrVal <= STint - ST). The initial value is then set to the state synchronization value. A state synchronization due to Pmax (or Pmin) does not cause an update of the initial value. However once the initial value is updated by a state synchronization due to the other attributes in the query then the normal behaviour defined by 3.3.7/[I-D.ietf-core-dynlink] occurs. Groves & Yang Expires August 25, 2017 [Page 5] Internet-Draft CoAP Observe Attr. February 2017 4.2. Notification Band Minimum (bmn) This attribute defines the lower bound for the notification band. State synchronization occurs when the resource value is equal to or above the notification band minimum. This attribute is optional. If not present there is no minimum value for the band. If present bmn must be less than bmx if it is also present otherwise the receiver MUST return a CoAP error code 4.00 "Bad Request" (or equivalent). 4.3. Notification Band Maximum (bmx) This attribute defines the upper bound for the notification band. State synchronization occurs when the resource value is equal to or less than the notification band maximum. This attribute is optional. If not present there is no maximum value for the band. If present bmx must be more than bmn if it is also present, otherwise the receiver MUST return a CoAP error code 4.00 "Bad Request" (or equivalent). 4.4. Band Step (bst) Like change step (st) this attribute indicates how much the value of a resource SHOULD change before triggering a state synchronization. The difference however is that the values used for the band step calculation are based on a constant step rather than being based on the synchronized value. The current resource value or the initialization value (if provided) is used a seed to determine the band thresholds. For example: Given a bst=10 and an initialization value=25. This defines a series of band step thresholds: i.e. ..., (5,15],(15,25],(25,35], ... When the resource value enters a new band step by exceeding the minimum threshold value and being less than or equal to the maximum threshold value for a band step then synchronisation occurs. A new synchronization occurs whenever the value enters a new band step. If the value jumps across band steps e.g. from 13 to 27 only one synchronisation occurs. The band step MUST be greater than zero otherwise the server MUST return a CoAP error code 4.00 "Bad Request" (or equivalent). Change step (st) and band step (bst) MUST NOT occur together in the same query. Groves & Yang Expires August 25, 2017 [Page 6] Internet-Draft CoAP Observe Attr. February 2017 4.5. Sample Number Window If queuing of a number of state synchronizations are required then the sample number window attribute is set to the desired size of the window. The attribute may be set with valid combinations of other binding/resource observation attributes. When a state synchronization is triggered due to the other attributes the resource value is added to the list of samples instead of resulting in an update of the source and destination resource (state synchronization). Only when the number of samples in the window reaches the sample number window is a state sycnhronisation peformed for the resource. The samples are then flushed from the window and the process is repeated. The use of the sample number window attribute may require the use of a suitable content-format (such as SenML [I-D.ietf-core-senml]) that allows multiple values/data points to be specified during the state synchronization. Consideration should also be given to the resource capacity (i.e. memory) of the CoAP server for storing data associated with the sample window. The sample number window should not exceed its capabilities. Even if the sample number window has not been reached, if resource (memory) consumption is an issue then state synchronization for the stored resource values SHOULD occur enabling resources to be freed. The pmin and pmax attributes have an indirect effect on the overall state sychronization. Whilst pmin and pmax do not directly specify the period for the overall state sychronization the setting of pmin and pmax may trigger samples entering the sample window as thus affect the frequency of state synchronization. 4.6. Sample Time Window If state synchronizations are to be queued during a certain period of time (in seconds) then the sample time window attribute is used. The attribute may be set with valid combinations of other binding/ resource observation attributes. On reception of a query with the stw attribute a timer (T1=0) is started. Whilst T1; rel="boundto";anchor="/a/ temperature";bind="obs";pmin="10";pmax="60";bmn="20",bmx="40" Res: 2.04 Changed Groves & Yang Expires August 25, 2017 [Page 9] Internet-Draft CoAP Observe Attr. February 2017 The above will result in a state synchronization through an Observe: o Every 60 seconds if the value is not between 20 and 40. o When the temperature is equal to or between 20 and 40 at least every 10 seconds. 4.8.2. Example 2 - Band Minimum and Maximum and Step Req: POST /bnd/ (Content-Format: application/link-format) ; rel="boundto";anchor="/a/ temperature";bind="obs";pmin="10";pmax="60";bmn="20",bmx="40",st="5" Res: 2.04 Changed The above will result in: o STinit being set to the temperature value at the time of the POST. o A state synchronization through an Observe: * Every 60 seconds if the value is not between 20 and 40 and if the value has not changed by 5 * When the temperature is equal to or between 20 and 40 and the value has changed by 5 from STinit at least every 10 seconds. 4.8.3. Example 3 - Band Minimum and Maximum, Step and Initialization Value Req: POST /bnd/ (Content-Format: application/link-format) ; rel="boundto";anchor="/a/t emperature";bind="obs";pmin="10";pmax="60";bmn="20",bmx="40",st="5",i v="20" Res: 2.04 Changed The above will result in: o STinit being set to 20 due to iv. o A state synchronization through an Observe: * Every 60 seconds if the value is not between 20 and 40 and if the value has not changed by 5 from 20 * When the temperature is equal to or between 20 and 40 and the value has changed by 5 from STinit at least every 10 seconds. Groves & Yang Expires August 25, 2017 [Page 10] Internet-Draft CoAP Observe Attr. February 2017 4.8.4. Example 4 - Step and Initialization Value Req: POST /bnd/ (Content-Format: application/link-format) ; rel="boundto";anchor="/a/ temperature";bind="obs";pmin="10";pmax="60";st="5",iv="20" Res: 2.04 Changed The above will result in: o STinit being set to 20 due to iv. o A state synchronization through an Observe: * Every 60 seconds if the temperature does not differ from STinit by 5. * When the temperature differs from STinit by 5 at least every 10 seconds. 4.8.5. Example 5 - Band Minimum and Maximum, Band Step and Initial Value Req: POST /bnd/ (Content-Format: application/link-format) ; rel="boundto";anchor="/a/t emperature";bind="obs";pmin="10";pmax="60";bmn="20",bmx="40",bst="5", iv="15" Res: 2.04 Changed The above will result in: o A series of bands being created of a width of 5 with the seed value 15. Given bmn="20" and bmx="40" this effectively means that bands with the following thresholds(15,20],(20,25],(25,30],(30,35],(35,40] are created. o A state synchronization through an Observe: * Every 60 seconds if the value is not between 20 and 40 (inclusive) and if the value has not entered into a new band. * When the temperature is equal to or between 20 and 40 and the value changes between the bands at least every 10 seconds. Groves & Yang Expires August 25, 2017 [Page 11] Internet-Draft CoAP Observe Attr. February 2017 4.8.6. Example 6 - Band Minimum and Sample Number Window Req: POST /bnd/ (Content-Format: application/link-format) ; rel="boundto";anchor="/a/ temperature";bind="obs";pmin="10";pmax="60";bmn="50";snw="5" Res: 2.04 Changed The above will result in: o A state sychronization added to the queue at pmax or whenever the value changes and is equal to or above 50. o A state sychronization through an Observe occuring once 5 synchronizations have been added to the queue resulting in multiple values being synchronized between the source and destination resources. 5. Security Considerations As per 5/[I-D.ietf-core-dynlink]. 6. IANA Considerations None. 7. Acknowledgements Michael Koster for discussions leading to the creation of these notification band and initialization attributes. 8. Changelog draft-groves-core-intparam-00 o Initial version 9. References 9.1. Normative References [I-D.ietf-core-dynlink] Shelby, Z., Vial, M., Koster, M., and C. Groves, "Dynamic Resource Linking for Constrained RESTful Environments", draft-ietf-core-dynlink-01 (work in progress), October 2016. Groves & Yang Expires August 25, 2017 [Page 12] Internet-Draft CoAP Observe Attr. February 2017 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010, . [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, . 9.2. Informative References [I-D.ietf-core-senml] Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. Bormann, "Media Types for Sensor Measurement Lists (SenML)", draft-ietf-core-senml-04 (work in progress), October 2016. Authors' Addresses Christian Groves Huawei Australia Email: Christian.Groves@mail01.huawei.com Weiwei Yang Huawei P.R.China Email: tommy@huawei.com Groves & Yang Expires August 25, 2017 [Page 13]