idnits 2.17.1 draft-groves-core-obsattr-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.ietf-core-dynlink]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHALL not' in this paragraph: The snw and stw attributes SHALL not be used in the same query together. Synchronizations based on pmin and pmax are added to the snw/stw sample window. In effect this overrides the pmin and pmax mechanism because resource state synchronizations will not occur between the source and destination resources based on these parameters. For snw the minimum period will be snw * pmin. The maximum period will be snw * pmax. For stw the state synchronization will occur after time stw and is not dependent on pmin and pmax (unless a state synchronization occurs due to memory constraints). The stw must be more than pmax if it is present, otherwise the pmax attribute becomes invalid. -- The document date (February 21, 2017) is 2614 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-14) exists of draft-ietf-core-dynlink-01 ** Downref: Normative reference to an Informational draft: draft-ietf-core-dynlink (ref. 'I-D.ietf-core-dynlink') ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-16) exists of draft-ietf-core-senml-04 Summary: 3 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group C. Groves 3 Internet-Draft W. Yang 4 Intended status: Standards Track Huawei 5 Expires: August 25, 2017 February 21, 2017 7 Additional CoAP Binding and Observe Attributes 8 draft-groves-core-obsattr-00 10 Abstract 12 [I-D.ietf-core-dynlink] defines five CoAP Observaton attributes 13 (minimum period, maximum period, band step, less than and greater 14 than) to control when notifications are sent. These attributes are 15 insufficient for some use cases. This document specifies additional 16 attributes allowing for notification bands, initialization values, 17 band step, sample number window and sample time window to allow for a 18 wider range of use cases. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on August 25, 2017. 37 Copyright Notice 39 Copyright (c) 2017 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Requirements Language . . . . . . . . . . . . . . . . . . . . 2 55 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 57 4. Binding and Resource Observation Attributes . . . . . . . . . 4 58 4.1. Initialization Value (iv) . . . . . . . . . . . . . . . . 5 59 4.2. Notification Band Minimum (bmn) . . . . . . . . . . . . . 6 60 4.3. Notification Band Maximum (bmx) . . . . . . . . . . . . . 6 61 4.4. Band Step (bst) . . . . . . . . . . . . . . . . . . . . . 6 62 4.5. Sample Number Window . . . . . . . . . . . . . . . . . . 7 63 4.6. Sample Time Window . . . . . . . . . . . . . . . . . . . 7 64 4.7. Interactions . . . . . . . . . . . . . . . . . . . . . . 8 65 4.8. Examples . . . . . . . . . . . . . . . . . . . . . . . . 9 66 4.8.1. Example 1 - Band Minimum and Maximum . . . . . . . . 9 67 4.8.2. Example 2 - Band Minimum and Maximum and Step . . . . 10 68 4.8.3. Example 3 - Band Minimum and Maximum, Step and 69 Initialization Value . . . . . . . . . . . . . . . . 10 70 4.8.4. Example 4 - Step and Initialization Value . . . . . . 11 71 4.8.5. Example 5 - Band Minimum and Maximum, Band Step and 72 Initial Value . . . . . . . . . . . . . . . . . . . . 11 73 4.8.6. Example 6 - Band Minimum and Sample Number Window . . 12 74 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 75 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 76 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 77 8. Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . 12 78 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 79 9.1. Normative References . . . . . . . . . . . . . . . . . . 12 80 9.2. Informative References . . . . . . . . . . . . . . . . . 13 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 83 1. Requirements Language 85 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 86 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 87 "OPTIONAL" in this document are to be interpreted as described in 88 [RFC2119]. 90 2. Introduction 92 [I-D.ietf-core-dynlink] defines five CoAP Binding and Observaton 93 attributes (minimum period, maximum period, change step, less than 94 and greater than) to control when notifications are sent. The 95 currently defined attributes have characteristics that means some use 96 cases cannot be supported. These are described below: 98 o A transition across a less than (lt), or greater than (gt) limit 99 or a change step (st) only generates one notification. This means 100 that it is not possible to describe a case where multiple 101 notifications are sent so long as the limit is exceeded. 103 o The change step (st) value is not deterministic when setting the 104 attribute. A client cannot set the initial value that the change 105 step applies to. The change step is based on the initial value 106 sent by the server. This means that a client cannot indicate that 107 it wants the change step (st=10) to apply to a certain increment 108 (e.g. 10, 20, 30) instead it relies on the initial value from the 109 client. Thus a change step of 10 could result in reporting (11, 110 21, 31) or equally (15, 27, 53). 112 o SenML allows for multiple values (records) to be reported for a 113 resource. The current attributes do not allow a method for a 114 client to request a particular number of records or sample time 115 window. 117 In order to allow a more complete set of use cases to be supported 118 this specification introduces several new attributes. 120 The notification band attributes "Notification Band Minimum" (bmn) 121 and "Notification Band Maximum" (bmx) attributes allow a bounded or 122 unbounded (based on a minimum or maximum) value range that may 123 trigger multiple state synchronizations. This enables use cases 124 where different ranges results in differing behaviour. For example: 125 monitoring the temperature of machinery. Whilst the temperature is 126 in the normal operating range only periodic observations are needed. 127 However as the temperature moves to more abnormal ranges more 128 frequent synchronization/reporting may be needed. 130 An "Initialization Value" (iv) attribute allows a seed value for the 131 calculation of the change step to be specified. This allows use 132 cases where synchronization occurs around a known value. For 133 example: synchronization will occur based on the operating 134 temperature set point of a machine. Without the initialization 135 synchronization will occur around the first measured value. 137 A "Band Step" (bst) attribute defines a series of bands that will 138 trigger state synchronization. This allows use cases where state 139 synchronization is required against known levels. Rather than 140 synchronizing based on a difference to a previous synchronization 141 value, synchronization occurs against a fixed known level. For 142 example: it allows state sychronisation for a sensor when it's value 143 is between (5,10],(10,15],(15,20] etc. 145 The "Sample Number Window" (snw) attribute allows a number of state 146 synchronizations to be queued before the actual queue synchronization 147 occurs. Once the number of queued state synchronizations has reached 148 a certain level then a single queue synchronization occurs with the 149 multiple resource values related to individual state synchronizations 150 included. This allows use cases where multiple resource values are 151 required but frequent synchronization is not required as there is a 152 need to minimise resource usage. For example: a meter may need to be 153 recorded once an hour but the values only need to be synchronized 154 once a day. 156 The "Sample Time Window" (stw) attribute as per the sample number 157 window allows state synchronizations to be queued before the actual 158 queue synchronization occurs. The queue synchronization occurs when 159 the indicated period expires independent of the number of samples. 161 3. Terminology 163 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 164 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 165 "OPTIONAL" in this specification are to be interpreted as described 166 in [RFC2119]. 168 This specification requires readers to be familiar with all the terms 169 and concepts that are discussed in [RFC5988] and [RFC6690]. This 170 specification makes use of the following additional terminology: 172 Notification Band: A resource value range that results in state 173 sychronization. The value range may be bounded by a minimum and 174 maximum value or may be unbounded having either a minimum or 175 maximum value. 177 4. Binding and Resource Observation Attributes 179 The attributes defined in this section are additional attributes that 180 may be used as binding attributes (3.3/[I-D.ietf-core-dynlink]) and 181 resource observation attributes (4.2/[I-D.ietf-core-dynlink]). 183 This specification introduces several new attributes: 185 +---------------------------+-----------------+------------------+ 186 | Attribute Name | Parameter | Data Format | 187 +---------------------------+-----------------+------------------+ 188 | Initialialization Value | /{resource}?iv | xsd:decimal | 189 | | | | 190 | Band Minimum Notification | /{resource}?bmn | xsd:decimal | 191 | | | | 192 | Band Maximum Notification | /{resource}?bmx | xsd:decimal | 193 | | | | 194 | Band Step | /{resource}?bst | xsd:decimal (>0) | 195 | | | | 196 | Sample Number Window | /{resource}?snw | xsd:integer (>0) | 197 | | | | 198 | Sample Time Window | /{resource}?stw | xsd:integer (>0) | 199 +---------------------------+-----------------+------------------+ 201 Table 1: Resource Observation Attribute Summary 203 The attributes may only be included at most once in a query. 205 4.1. Initialization Value (iv) 207 The attribute indicates the initialization value to be used to 208 determine when a change step is notified. As such it MUST only be 209 present in a query when the change step (st) or band step (bst) 210 attribute is present (see [I-D.ietf-core-dynlink]). If st or bst is 211 not present then the receiver MUST return a CoAP error code 4.00 "Bad 212 Request" (or equivalent). 214 Without iv, on reception of a query the synchronization initiator 215 uses the current value for the observed resource as the initial value 216 to which the change step is applied. The use of iv overrides this 217 behaviour and the iv value is used for the initial value (STinit or 218 BSTinit). A state synchronization occurs once the resource value 219 differs from the initial value by the change step value (i.e. 220 CurrVal >= STinit + ST or CurrVal <= STint - ST). The initial value 221 is then set to the state synchronization value. 223 A state synchronization due to Pmax (or Pmin) does not cause an 224 update of the initial value. However once the initial value is 225 updated by a state synchronization due to the other attributes in the 226 query then the normal behaviour defined by 227 3.3.7/[I-D.ietf-core-dynlink] occurs. 229 4.2. Notification Band Minimum (bmn) 231 This attribute defines the lower bound for the notification band. 232 State synchronization occurs when the resource value is equal to or 233 above the notification band minimum. This attribute is optional. If 234 not present there is no minimum value for the band. If present bmn 235 must be less than bmx if it is also present otherwise the receiver 236 MUST return a CoAP error code 4.00 "Bad Request" (or equivalent). 238 4.3. Notification Band Maximum (bmx) 240 This attribute defines the upper bound for the notification band. 241 State synchronization occurs when the resource value is equal to or 242 less than the notification band maximum. This attribute is optional. 243 If not present there is no maximum value for the band. If present 244 bmx must be more than bmn if it is also present, otherwise the 245 receiver MUST return a CoAP error code 4.00 "Bad Request" (or 246 equivalent). 248 4.4. Band Step (bst) 250 Like change step (st) this attribute indicates how much the value of 251 a resource SHOULD change before triggering a state synchronization. 252 The difference however is that the values used for the band step 253 calculation are based on a constant step rather than being based on 254 the synchronized value. 256 The current resource value or the initialization value (if provided) 257 is used a seed to determine the band thresholds. 259 For example: Given a bst=10 and an initialization value=25. This 260 defines a series of band step thresholds: i.e. ..., 261 (5,15],(15,25],(25,35], ... 263 When the resource value enters a new band step by exceeding the 264 minimum threshold value and being less than or equal to the maximum 265 threshold value for a band step then synchronisation occurs. 267 A new synchronization occurs whenever the value enters a new band 268 step. If the value jumps across band steps e.g. from 13 to 27 only 269 one synchronisation occurs. 271 The band step MUST be greater than zero otherwise the server MUST 272 return a CoAP error code 4.00 "Bad Request" (or equivalent). 274 Change step (st) and band step (bst) MUST NOT occur together in the 275 same query. 277 4.5. Sample Number Window 279 If queuing of a number of state synchronizations are required then 280 the sample number window attribute is set to the desired size of the 281 window. The attribute may be set with valid combinations of other 282 binding/resource observation attributes. When a state 283 synchronization is triggered due to the other attributes the resource 284 value is added to the list of samples instead of resulting in an 285 update of the source and destination resource (state 286 synchronization). Only when the number of samples in the window 287 reaches the sample number window is a state sycnhronisation peformed 288 for the resource. The samples are then flushed from the window and 289 the process is repeated. 291 The use of the sample number window attribute may require the use of 292 a suitable content-format (such as SenML [I-D.ietf-core-senml]) that 293 allows multiple values/data points to be specified during the state 294 synchronization. 296 Consideration should also be given to the resource capacity (i.e. 297 memory) of the CoAP server for storing data associated with the 298 sample window. The sample number window should not exceed its 299 capabilities. Even if the sample number window has not been reached, 300 if resource (memory) consumption is an issue then state 301 synchronization for the stored resource values SHOULD occur enabling 302 resources to be freed. 304 The pmin and pmax attributes have an indirect effect on the overall 305 state sychronization. Whilst pmin and pmax do not directly specify 306 the period for the overall state sychronization the setting of pmin 307 and pmax may trigger samples entering the sample window as thus 308 affect the frequency of state synchronization. 310 4.6. Sample Time Window 312 If state synchronizations are to be queued during a certain period of 313 time (in seconds) then the sample time window attribute is used. The 314 attribute may be set with valid combinations of other binding/ 315 resource observation attributes. On reception of a query with the 316 stw attribute a timer (T1=0) is started. Whilst T1; rel="boundto";anchor="/a/ 418 temperature";bind="obs";pmin="10";pmax="60";bmn="20",bmx="40" 420 Res: 2.04 Changed 421 The above will result in a state synchronization through an Observe: 423 o Every 60 seconds if the value is not between 20 and 40. 425 o When the temperature is equal to or between 20 and 40 at least 426 every 10 seconds. 428 4.8.2. Example 2 - Band Minimum and Maximum and Step 430 Req: POST /bnd/ (Content-Format: application/link-format) 431 ; rel="boundto";anchor="/a/ 432 temperature";bind="obs";pmin="10";pmax="60";bmn="20",bmx="40",st="5" 434 Res: 2.04 Changed 436 The above will result in: 438 o STinit being set to the temperature value at the time of the POST. 440 o A state synchronization through an Observe: 442 * Every 60 seconds if the value is not between 20 and 40 and if 443 the value has not changed by 5 445 * When the temperature is equal to or between 20 and 40 and the 446 value has changed by 5 from STinit at least every 10 seconds. 448 4.8.3. Example 3 - Band Minimum and Maximum, Step and Initialization 449 Value 451 Req: POST /bnd/ (Content-Format: application/link-format) 452 ; rel="boundto";anchor="/a/t 453 emperature";bind="obs";pmin="10";pmax="60";bmn="20",bmx="40",st="5",i 454 v="20" 456 Res: 2.04 Changed 458 The above will result in: 460 o STinit being set to 20 due to iv. 462 o A state synchronization through an Observe: 464 * Every 60 seconds if the value is not between 20 and 40 and if 465 the value has not changed by 5 from 20 467 * When the temperature is equal to or between 20 and 40 and the 468 value has changed by 5 from STinit at least every 10 seconds. 470 4.8.4. Example 4 - Step and Initialization Value 472 Req: POST /bnd/ (Content-Format: application/link-format) 473 ; rel="boundto";anchor="/a/ 474 temperature";bind="obs";pmin="10";pmax="60";st="5",iv="20" 476 Res: 2.04 Changed 478 The above will result in: 480 o STinit being set to 20 due to iv. 482 o A state synchronization through an Observe: 484 * Every 60 seconds if the temperature does not differ from STinit 485 by 5. 487 * When the temperature differs from STinit by 5 at least every 10 488 seconds. 490 4.8.5. Example 5 - Band Minimum and Maximum, Band Step and Initial 491 Value 493 Req: POST /bnd/ (Content-Format: application/link-format) 494 ; rel="boundto";anchor="/a/t 495 emperature";bind="obs";pmin="10";pmax="60";bmn="20",bmx="40",bst="5", 496 iv="15" 498 Res: 2.04 Changed 500 The above will result in: 502 o A series of bands being created of a width of 5 with the seed 503 value 15. Given bmn="20" and bmx="40" this effectively means that 504 bands with the following 505 thresholds(15,20],(20,25],(25,30],(30,35],(35,40] are created. 507 o A state synchronization through an Observe: 509 * Every 60 seconds if the value is not between 20 and 40 510 (inclusive) and if the value has not entered into a new band. 512 * When the temperature is equal to or between 20 and 40 and the 513 value changes between the bands at least every 10 seconds. 515 4.8.6. Example 6 - Band Minimum and Sample Number Window 517 Req: POST /bnd/ (Content-Format: application/link-format) 518 ; rel="boundto";anchor="/a/ 519 temperature";bind="obs";pmin="10";pmax="60";bmn="50";snw="5" 521 Res: 2.04 Changed 523 The above will result in: 525 o A state sychronization added to the queue at pmax or whenever the 526 value changes and is equal to or above 50. 528 o A state sychronization through an Observe occuring once 5 529 synchronizations have been added to the queue resulting in 530 multiple values being synchronized between the source and 531 destination resources. 533 5. Security Considerations 535 As per 5/[I-D.ietf-core-dynlink]. 537 6. IANA Considerations 539 None. 541 7. Acknowledgements 543 Michael Koster for discussions leading to the creation of these 544 notification band and initialization attributes. 546 8. Changelog 548 draft-groves-core-intparam-00 550 o Initial version 552 9. References 554 9.1. Normative References 556 [I-D.ietf-core-dynlink] 557 Shelby, Z., Vial, M., Koster, M., and C. Groves, "Dynamic 558 Resource Linking for Constrained RESTful Environments", 559 draft-ietf-core-dynlink-01 (work in progress), October 560 2016. 562 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 563 Requirement Levels", BCP 14, RFC 2119, 564 DOI 10.17487/RFC2119, March 1997, 565 . 567 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, 568 DOI 10.17487/RFC5988, October 2010, 569 . 571 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 572 Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, 573 . 575 9.2. Informative References 577 [I-D.ietf-core-senml] 578 Jennings, C., Shelby, Z., Arkko, J., Keranen, A., and C. 579 Bormann, "Media Types for Sensor Measurement Lists 580 (SenML)", draft-ietf-core-senml-04 (work in progress), 581 October 2016. 583 Authors' Addresses 585 Christian Groves 586 Huawei 587 Australia 589 Email: Christian.Groves@mail01.huawei.com 591 Weiwei Yang 592 Huawei 593 P.R.China 595 Email: tommy@huawei.com