idnits 2.17.1 draft-ietf-6tisch-coap-03.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 document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([IEEE802154e], [I-D.ietf-6tisch-6top-interface]), 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 -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: Each revision of this draft will define a version number which will uniquely identify the set of resources defined in that particular revision of the draft. Specifically, a change to the major version number indiactes that resources have been added, deleted, renamed or their message formats have changed. In most cases, this MAY require changes to the implementation. The minor version number indicates changes to options supported by resources or other textual/language changes to the draft. In most cases, this MAY NOT require any changes to the implementation. -- The document date (March 9, 2015) is 3335 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) == Missing Reference: 'IEEE802154e' is mentioned on line 684, but not defined == Unused Reference: 'I-D.ietf-6tisch-architecture' is defined on line 632, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-6tisch-minimal' is defined on line 638, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-6tisch-terminology' is defined on line 643, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-6tisch-tsch' is defined on line 649, but no explicit reference was found in the text == Unused Reference: 'I-D.wang-6tisch-6top-sublayer' is defined on line 664, but no explicit reference was found in the text == Outdated reference: A later version (-04) exists of draft-ietf-6tisch-6top-interface-02 == Outdated reference: A later version (-30) exists of draft-ietf-6tisch-architecture-06 == Outdated reference: A later version (-21) exists of draft-ietf-6tisch-minimal-06 == Outdated reference: A later version (-10) exists of draft-ietf-6tisch-terminology-03 == Outdated reference: A later version (-06) exists of draft-ietf-6tisch-tsch-05 == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-06 == Outdated reference: A later version (-04) exists of draft-wang-6tisch-6top-sublayer-01 -- Obsolete informational reference (is this intentional?): RFC 7049 (Obsoleted by RFC 8949) Summary: 3 errors (**), 0 flaws (~~), 15 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 6TiSCH R. Sudhaakar, Ed. 3 Internet-Draft Cisco 4 Intended status: Standards Track P. Zand 5 Expires: September 10, 2015 University of Twente 6 March 9, 2015 8 6TiSCH Resource Management and Interaction using CoAP 9 draft-ietf-6tisch-coap-03 11 Abstract 13 The [IEEE802154e] standardizes the TSCH mode of operation and defines 14 the mechanisms for layer 2 communication between conforming devices. 15 6top defines a set of commands to monitor and manage the TSCH 16 schedule. To realize the full functionality of sensor networks and 17 allow their adoption and use in real applications we need additional 18 mechanisms. Specifically, the interaction with 6top, control and 19 modify schedules, monitor parameters etc must be defined. Higher 20 layers monitoring and management entities are then able to use these 21 capabilities to create feedback loops. Although, there have been 22 many custom implementations of such feedback loops between the 23 routing, transport and MAC layers in sensor network deployments, 24 there has been a lack of standards based approaches. This draft 25 defines the messaging between monitoring and management entities and 26 the 6top layer and a mapping to the 6top commands. The document also 27 presents a particular implementation of the generic data model 28 specified in [I-D.ietf-6tisch-6top-interface] based on CoAP and CBOR. 30 Requirements Language 32 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 33 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 34 "OPTIONAL" in this document are to be interpreted as described in RFC 35 2119 [RFC2119]. 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at http://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on September 10, 2015. 54 Copyright Notice 56 Copyright (c) 2015 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents 61 (http://trustee.ietf.org/license-info) in effect on the date of 62 publication of this document. Please review these documents 63 carefully, as they describe your rights and restrictions with respect 64 to this document. Code Components extracted from this document must 65 include Simplified BSD License text as described in Section 4.e of 66 the Trust Legal Provisions and are provided without warranty as 67 described in the Simplified BSD License. 69 Table of Contents 71 1. Requirements notation . . . . . . . . . . . . . . . . . . . . 3 72 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 73 3. Scope of the document . . . . . . . . . . . . . . . . . . . . 3 74 4. Data Model definition for CoAP . . . . . . . . . . . . . . . 4 75 4.1. Naming Convention for URI schemes . . . . . . . . . . . . 4 76 4.2. Convention for accessing URIs . . . . . . . . . . . . . . 5 77 4.3. 6TiSCH Resources . . . . . . . . . . . . . . . . . . . . 5 78 4.3.1. Versioning . . . . . . . . . . . . . . . . . . . . . 6 79 4.3.2. Management Resources . . . . . . . . . . . . . . . . 6 80 4.3.3. Informational Resources . . . . . . . . . . . . . . . 8 81 4.3.4. Message Formats . . . . . . . . . . . . . . . . . . . 9 82 4.3.5. Extensible Resources . . . . . . . . . . . . . . . . 11 83 4.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 12 84 4.4.1. Request-Response . . . . . . . . . . . . . . . . . . 12 85 4.4.2. Publish-Subscribe . . . . . . . . . . . . . . . . . . 13 86 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 87 5.1. Normative References . . . . . . . . . . . . . . . . . . 14 88 5.2. Informative References . . . . . . . . . . . . . . . . . 14 89 5.3. External Informative References . . . . . . . . . . . . . 16 90 Appendix A. . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 93 1. Requirements notation 95 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 96 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 97 document are to be interpreted as described in [RFC2119]. 99 2. Introduction 101 The 6TiSCH Operation Sublayer (6top) [I-D.ietf-6tisch-6top-interface] 102 describes the main commands provided to higher layers that allow them 103 to build TSCH schedules, make routing decisions, perform TSCH 104 configuration and control procedures and supports centralized and 105 decentralized scheduling policies among other functionalities. 106 However, there is still a need for specifying the methods, including 107 message exchanges and message formats that higher layers use to 108 invoke these command described by 6top. 110 +------------------------------------+ 111 | Higher Layers | 112 +------------------------------------+ 113 | CoAP - Resource Management | 114 | and Interaction | 115 +------------------------------------+ 116 | 6top | 117 +------------------------------------+ 118 | 802.15.4e TSCH | 119 +------------------------------------+ 121 Figure 1: Logical positioning of layers 123 Interoperation with any protocol that may be used by the network 124 layer is necessary to have a wide impact. This documents aims at 125 defining the message exchanges and the formats of the messages that 126 the network layer uses to interact with the 6top sub-layer. The 127 messaging scheme defined in this document is aimed for use between 128 6top nodes and higher layer management entities as well as between 129 6top nodes. 131 This document also specifies an implementation of this generic 132 message exchange and data model using CoAP as the transport 133 mechanism. 135 3. Scope of the document 137 This draft defines the communication mechanism between PCE and 6top 138 nodes using COAP. The generic YANG data model defined in 139 [I-D.ietf-6tisch-6top-interface] is used to define the various CoAP 140 messages and payloads. The payload used CBOR for the encoding 141 format. The document also defines the URIs that used to identify the 142 resources exposed by 6top. 144 This document also defines how users can install custom resources 145 that allow them to extend the basic resource exposed by 6top. 147 The CoAP Management Interface (CoMI) [I-D.vanderstok-core-comi] draft 148 specifies a common constrained device managment interface. The 149 conventions used in this draft follow the guidelines in the CoMI 150 draft . This draft expects CoMI to define the access methodologies, 151 discovery mechanisms, resource installation procedures required for 152 the management of constrained devices. This draft presents some 153 examples in Section 4.3.4 on how to use the CoMI specifications to 154 manage the 6top sublayer. 156 NOTE: CoMI specifications are not finalized at the time of this 157 writing. In case of any discrepancies, CoMI will supersede the 158 message formats in the examples presented in Section 4.3.4. 160 4. Data Model definition for CoAP 162 4.1. Naming Convention for URI schemes 164 Universal Resource Identifiers (URIs) help us uniquely identify the 165 various commands and parameters that 6top exposes to the higher 166 layers. The basic URI naming conventions and terminology specified 167 in [RFC3986] is used. Specifically, the terms, 'scheme', 168 'authority', 'path', 'query' are used as defined in the [RFC3986]. 170 The following provides the guidelines that are followed in this draft 171 to name the URIs that identify the resources exposed by 6top. 173 1. All URIs naming 6top resources MUST use the 'coap' scheme 175 2. The authority MUST have the username '6top' and the IP address of 176 6top node 178 3. The root path MUST always start with '6top' 180 4. Each component of the path SHOULD be of minimum possible length 181 while being self descriptive. 183 5. Typographical conventions as described in A SHOULD be followed 185 These guidelines MUST be followed by users who install extensible 186 resources. It SHOULD be followed for future extensions of the data 187 model in order to provide consistency. 189 4.2. Convention for accessing URIs 191 We use the GET, POST and DELETE methods described by CoAP. These 192 methods MUST be used in accordance with their definition in Sec. 5.8 193 of [RFC7252] and as specified in the CoMI draft 194 [I-D.vanderstok-core-comi]. There is no need for the PUT method as 195 the functionality of the POST method can be used for all situations 196 that need updating or modification of a resource. 198 The CoAP methods are mapped to 6top commands as shown in the figure 199 below. 201 +-------------+--------------+-------------------------+ 202 | CoAP method | 6top command | Description | 203 +-------------+--------------+-------------------------+ 204 | GET | READ | Retrieves 6top resources| 205 +-------------+--------------+-------------------------+ 206 | POST | CREATE / | Creates/Updates a new | 207 | | UPDATE | entry | 208 +-------------+--------------+-------------------------+ 209 | DELETE | DELETE | Deletes an entry | 210 +-------------+--------------+-------------------------+ 211 | POST | CONFIGURE | Configures a setting | 212 +-------------+--------------+-------------------------+ 214 Figure 2: Mapping between CoAP methods and 6top commands 216 The GET method may use queries to allow higher layer entities to 217 perform conditional GETs or filter the results of a GET on resource 218 that is a collection. 220 The POST method is used in all situations where an argument needs to 221 be passed to the 6top layer. The Content-Type option is set to 222 'application/cbor'. The payload is encoded using CBOR format as 223 described in [I-D.vanderstok-core-comi] and [RFC7049]. 225 The DELETE method is used to invoke the 6top DELETE command on a 226 particular resource. 228 The GET method may use queries to allow higher layer entities to 229 perform conditional GETs or filter the results of a GET on resource 230 that is a collection. 232 4.3. 6TiSCH Resources 234 The 6TiSCH resources presented in this draft offer a comprehensive 235 way to manage 6top nodes based on the requirement known to us as of 236 this writing. These resources are bound to evolve and will be 237 identified by appropriate version numbers that will be tied to 238 revisions of this draft. 240 Management resources are classified as resources to which a higher 241 layer entity may create, update or delete. They are typically used 242 to create schedules, identify time sources that TSCH needs. They are 243 the means to close the control loop between TSCH and higher layers. 245 Informational resources are classified as resources to which a higher 246 layer entity typically has only READ access. They are typically used 247 to monitor operational parameters of TSCH and the values used as 248 input to routing algorithms and other mechanisms. 250 4.3.1. Versioning 252 The version number describes the set of resources that can be 253 accessed on a node that implements the recommendations in this draft. 255 Each revision of this draft will define a version number which will 256 uniquely identify the set of resources defined in that particular 257 revision of the draft. Specifically, a change to the major version 258 number indiactes that resources have been added, deleted, renamed or 259 their message formats have changed. In most cases, this MAY require 260 changes to the implementation. The minor version number indicates 261 changes to options supported by resources or other textual/language 262 changes to the draft. In most cases, this MAY NOT require any 263 changes to the implementation. 265 The 6TiSCH resource version information is available by executing a 266 GET method on the resource '/6top/version' of a 6top node. 268 4.3.2. Management Resources 270 All the attributes in the management resources have the Read/Write 271 accessibility. The following table lists the 6top management 272 resources and the related URI paths. 274 +-------------+-----------------+-----------------+ 275 | Name | Accessibility | URI path | 276 | | 6top Commands | | 277 +-------------+-----------------+-----------------+ 278 | Neighbor | CREATE/READ/ | 6top/nbrList | 279 | List | DELETE/UPDATE | | 280 +-------------+-----------------+-----------------+ 281 | slotframe | CREATE/READ/ | 6top/slotFrame | 282 | List | DELETE/UPDATE | | 283 +-------------+-----------------+-----------------+ 284 | Cell | CREATE/READ/ | 6top/cellList | 285 | List | DELETE/UPDATE | | 286 +-------------+-----------------+-----------------+ 287 | Time | CREATE/READ/ | 6top/timeSource | 288 | Source | DELETE/UPDATE | | 289 +-------------+-----------------+-----------------+ 290 | LabelSwitch | CREATE/READ/ | 6top/labelSwitch| 291 | List | DELETE/UPDATE | | 292 +-------------+-----------------+-----------------+ 293 | Track | CREATE/READ/ | 6top/tracklist | 294 | List | DELETE/UPDATE | | 295 +-------------+-----------------+-----------------+ 296 | EB | CREATE/READ/ | 6top/ebList | 297 | List | DELETE/UPDATE | | 298 +-------------+-----------------+-----------------+ 299 | Chunk | CREATE/READ/ | 6top/chunkList | 300 | List | DELETE/UPDATE | | 301 +-------------+-----------------+-----------------+ 303 Figure 3: List of Management Resources 305 The following table provides an example about how Neighbor List 306 components (leafs in the YANG model) can be addressed. 308 +-------------+---------------------------+ 309 | Field name | URI path | 310 +-------------+---------------------------+ 311 | Target | | 312 | Neighbor | 6top/nbrList/tna | 313 | Addr | | 314 +-------------+---------------------------+ 315 | ASN | 6top/nbrList/asn | 316 +-------------+---------------------------+ 317 | RSSI | 6top/nbrList/rssi | 318 +-------------+---------------------------+ 319 | LinkQuality | 6top/nbrList/linkQ | 320 +-------------+---------------------------+ 322 Figure 4: Neighbor Table 324 4.3.3. Informational Resources 326 All the attributes in the Informational resources have the Read 327 accessibility. The following table lists the 6top informational 328 resources and the related URI paths. 330 +-------------+-----------------+-----------------------+ 331 | Name | Accessibility | URI path | 332 | | 6top Commands | | 333 +-------------+-----------------+-----------------------+ 334 | Version | READ | 6top/version | 335 +-------------+-----------------+-----------------------+ 336 | Queue | READ/CONFIGURE | 6top/queue | 337 +-------------+-----------------+-----------------------+ 338 | Monitoring | READ/CONFIGURE | 6top/monitStatus | 339 | status | | | 340 +-------------+-----------------+-----------------------+ 341 | Statistics | READ/CONFIGURE | 6top/stats | 342 | metrics | | | 343 +-------------+-----------------+-----------------------+ 345 Figure 5: List of Informational Resources 347 4.3.3.1. Version 349 The version resource is a read-only resource that provides 350 information on the methods, resources, message formats that is 351 supported by the node. The version resource does not directly map to 352 a 6top resource defined in [I-D.ietf-6tisch-6top-interface]. 354 Upon receiving a GET on the '/6top/version' resource, the node MUST 355 respond with a version number that is described by a major and minor 356 number. It is expressed using 2 bytes - The first and second bytes 357 are 8-bit unsigned integers indicating the major and minor version 358 numbers respectively. The valid values for the major version are 1 359 through 255 (both inclusive) and for the minor version are 0 through 360 255 (both inclusive). 362 A 6top node implmenting the recommendations in this draft will 363 respond with the following 2 byte version number - '0x01 0x00', 364 indicating major version = 1 and minor version = 0. 366 The major and minor versions are separately accessible using the 367 resources '/6top/version/major' and '/6top/version/minor' 368 respectively. The response will be an 8-bit unsigned integer 369 containing the major or minor version number, respectively. 371 4.3.3.2. Resource Discovery 373 As new resources are defined (both native and custom), it is 374 essential for the PCE as well peers to discover the resources. The 375 CoMI draft presents methods by which standard CoAP resource discovery 376 mechanisms are extended to the management of constrained devices. 377 The methods described in Section 4.3 of [I-D.vanderstok-core-comi] 378 SHALL be used for discovering new resources available at a node. 380 4.3.4. Message Formats 382 NOTE: The message formats presented in this section follow the 383 specifications in the CoMI draft [I-D.vanderstok-core-comi]. In case 384 of any discrepancies, the CoMI draft will take precedence. 386 GET messages do not contain any payload. However, they can contain a 387 query option to filter on the resource that is being retrieved. An 388 example query on the neighbor list is: 390 +------------------------------------------+ 391 Header | GET | 392 +------------------------------------------+ 393 Uri-Path| /6top/nbrList | 394 +------------------------------------------+ 395 Options | Accept: application/cbor | 396 | Uri-Query: ABNF(TargetNodeAddr==0x1234) | 397 +------------------------------------------+ 399 Figure 6: Example GET message 401 Since this resources points to the entire neighbor list, the response 402 returns all the entries (the list of neighbors of that node) and all 403 fields in each entry (i.e. entry for a neighbor) of the list in CBOR 404 format. A request with a Uri-Query option may be used to retrieve 405 only specific entries in the list. The value of Uri-Query MUST be in 406 the ABNF format as described in [RFC5234]. 408 Resources that point to collection within a list, such as 409 '/6top/nbrList/tna', returns only the values in the TargetNodeAddr 410 entry of the Neighbor list. The usage of the Uri-Query option has 411 the same effect of filtering on the result. 413 The endpoint MUST appropriately respond with a 2.05 Content or 4.04 414 Not Found message as defined in [RFC7252]. If the resource is found 415 then the payload of the response MUST contain a CBOR representation 416 of the data that is referenced by the URI. 418 To create or update a Neighbor, the CoAP client MUST send a POST 419 message as shown in Figure 7. The payload MUST describe the argument 420 that is passed to 6top in CBOR format. 422 +-------------------------------------+ 423 Header | POST | 424 +-------------------------------------+ 425 Uri-Path| /6top/nbrList | 426 +-------------------------------------+ 427 Payload | CBOR( {TargetNodeAddr: 0x1234} ) | 428 +-------------------------------------+ 430 Figure 7: Example POST message 432 The POST method may not be used on resources that are collection 433 within a list, such as '/6top/nbrList/tna'. 435 To delete a Neighbor, the CoAP client MUST send a DELETE message as 436 shown in Figure 8. 438 +-------------------------------------+ 439 Header | DELETE | 440 +-------------------------------------+ 441 Uri-Path| /6top/nbrList | 442 +-------------------------------------+ 443 Options | Uri-Query: ABNF(TargetNodeAddr | 444 | == 0x1234) | 445 +-------------------------------------+ 447 Figure 8: Example DELETE message 449 A DELETE message SHOULD always contain a Uri-Query option in order to 450 clearly specify which entry(s) within the list must be deleted. 451 Ideally, the CoAP client SHOULD make one call per entry that must be 452 deleted. An implementation may decide whether or not a DELETE method 453 on '/6top/nbrList' may be allowed. 455 The endpoint MUST appropriately respond with a 2.02 (Deleted) 456 message. 458 A sample of mapping between CoAP methods and 6top commands for 459 manipulating the neighbor list is shown in the figure below. 461 +---------------------+----------------+---------------+-------------+ 462 | CoAP method | 6top command |6top behaviour |CoAP Response| 463 +---------------------+----------------+---------------+-------------+ 464 | POST /6top/nbrList | Create.neighbor| Adds a | 2.01 Created| 465 | CBOR( | | neighbor | | 466 | {TargetNodeAddr: | (address,stats)| | | 467 | 1234}) | | | | 468 +---------------------+----------------+---------------+-------------+ 469 | GET /6top/nbrList | Read.all. | Reads | 2.05 Content| 470 | | neighbor() | all | CBOR(Neigh- | 471 | | | neighbors | bor List) | 472 +---------------------+----------------+---------------+-------------+ 473 | GET /6top/nbrList | Read.neighbor | Reads neighbor| 2.05 Content| 474 | Uri-Query - | (address) | information | CBOR(Neigh- | 475 | TargetNodeAddr: | | | bor List) | 476 | 1234}) | | | | 477 +---------------------+----------------+---------------+-------------+ 478 | POST /6top/nbrList | Update.neighbor| Updates an | 2.04 Changed| 479 | CBOR( | (address,stats)| entry | | 480 | {TargetNodeAddr: | | | | 481 | 1234}) | | | | 482 +---------------------+----------------+---------------+-------------+ 483 | DELETE /6top/nbrList|Delete.neighbor | Removes | 2.02 Deleted| 484 | Uri-Query - | (address) | the neighbor | | 485 | TargetNodeAddr | | | | 486 | == 1234}) | | | | 487 +---------------------+----------------+---------------+-------------+ 489 Figure 9: CoAP methods and resulting invocation 6top commands 491 4.3.5. Extensible Resources 493 Extensible resources are to be used when a higher layer entity wants 494 to be notified of an event. An event may be defined as the result of 495 a mathematical operation on a 6top resource. For example, the CoAP 496 client might want to monitor when the DAG rank of a particular node 497 crosses a threshold. Once the extensible resource is installed the 498 CoAP client uses the observe mechanism defined in 499 [I-D.ietf-core-observe] to monitor the resource. 501 4.3.5.1. Defining new resources 503 An extensible resource path MUST always start with '/6top/custom' and 504 follow the guideline for URI naming as described in 4.1. The event 505 associated with the extensible resource must be defined using the 506 ABNF notation described in [RFC5234]. 508 An extensible resource may be created by performing POST operation to 509 the resource '/6top/custom' with the following payload encoded using 510 CBOR. 512 +---------------+------------+ 513 | Field Name | Type | 514 +---------------+------------+ 515 | Resource | String | 516 | Name | | 517 +---------------+------------+ 518 | Event | String | 519 | Definition | | 520 +---------------+------------+ 522 Figure 10: Payload format for creating an Extensible Resource 524 4.4. Example 526 This section gives a number of short examples of how to use the data 527 model and CoAP mapping defined in this document. 529 4.4.1. Request-Response 531 Figure 11 shows how a CoAP client adds an entry in the neighbor list 532 of node A. This new neighbor has a target node address 0x1234. The 533 client sends out a POST request containing the CBOR encoding of 534 '{TargetNodeAddr: 1234}'. This message is received and processed by 535 the CoAP endpoint of Node A and in turn, the 6top command, 536 Create.neighbor is invoked with the appropriate parameters. In this 537 case, the address is the 'TargetNodeAddr' parameter passed in the 538 payload of the POST message and the stats argument has the default 539 value. In the response to the invocation of the Create.neighbor 540 command, the 6top sublayer adds an entry to the neighbor list with 541 appropriate values and returns a confirm message. The CoAP endpoint 542 in turn send out an appropriate CoAP response to indicate success. 543 If the addition of the neighbor failed, a failure message will be 544 returned. 546 CoAP Client Node A Node A 547 (CoAP-endpoint) (6top sublayer) 548 | CoAP Request | | 549 |- - - - - - - - - - - ->| 6top Request | 550 | POST /6top/nbrList |----------------------->| 551 | payload: | Create.neighbor | Adds a 552 | CBOR({TargertNodeAddr: | (address,stats) | neighbor 553 | 1234}) | | with address 554 | | | 1234 555 | | 6top Confirm | 556 | CoAP Response |<-----------------------| 557 |<- - - - - - - - - - - -| | 558 | | | 559 | | | 561 Figure 11: Example of adding a neighbor 563 In Figure 12, a CoAP client reads a neighbor entry from node A. This 564 neighbor has a target node address 0x1234. 566 CoAP Client Node A Node A 567 (CoAP-endpoint) (6top sublayer) 568 | CoAP Request | | 569 |- - - - - - - - - - - ->| 6top Request | 570 | GET /6top/nbrList |----------------------->| 571 | Uri-Query - | Read.neighbor(address) |Reads neighbor 572 | TargetNodeAddr | |information 573 | == 0x1234 | | 574 | | | 575 | | 6top Confirm | 576 | CoAP Response |<-----------------------| 577 |<- - - - - - - - - - - -| Reads neighbor | 578 | 2.05 Content | information | 579 | | | 581 Figure 12: Example of reading a neighbor 583 4.4.2. Publish-Subscribe 585 In Figure 13, a CoAP client subscribes to Monitoring Status of node 586 A. The Monitoring status of Node A is constantly monitored by the 587 CoAP client. 589 CoAP Client Node A Node A 590 (CoAP-endpoint) (6top sublayer) 591 | CoAP Register | | 592 |- - - - - - - - - - - - >| 6top Request | 593 | GET /6top/monitStatus |----------------------->| 594 | | Read.Monitoring.Status |Reads 595 | | |the current 596 | | |Monitoring 597 | | |status 598 | | 6top Notification | 599 | CoAP Notification |<-----------------------| 600 |<- - - - - - - - - - - - | Reads the current | 601 | 2.05 Content | Monitoring status | 602 | | |The Status 603 | | |changes 604 | | 6top Notification | 605 | CoAP Notification |<-----------------------| 606 |<- - - - - - - - - - - - | Notifies upon the | 607 | 2.05 Content | status change | 608 | | |The Status 609 | | |changes 610 | | 6top Notification | 611 | CoAP Notification |<-----------------------| 612 |<- - - - - - - - - - - - | Notifies upon the | 613 | 2.05 Content | status change | 614 | | | 616 Figure 13: Example of Subscribing to Monitoring Status 618 5. References 620 5.1. Normative References 622 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 623 Requirement Levels", BCP 14, RFC 2119, March 1997. 625 5.2. Informative References 627 [I-D.ietf-6tisch-6top-interface] 628 Wang, Q., Vilajosana, X., and T. Watteyne, "6TiSCH 629 Operation Sublayer (6top) Interface", draft-ietf-6tisch- 630 6top-interface-02 (work in progress), October 2014. 632 [I-D.ietf-6tisch-architecture] 633 Thubert, P., Watteyne, T., Struik, R., and M. Richardson, 634 "An Architecture for IPv6 over the TSCH mode of IEEE 635 802.15.4e", draft-ietf-6tisch-architecture-06 (work in 636 progress), March 2015. 638 [I-D.ietf-6tisch-minimal] 639 Vilajosana, X. and K. Pister, "Minimal 6TiSCH 640 Configuration", draft-ietf-6tisch-minimal-06 (work in 641 progress), March 2015. 643 [I-D.ietf-6tisch-terminology] 644 Palattella, M., Thubert, P., Watteyne, T., and Q. Wang, 645 "Terminology in IPv6 over the TSCH mode of IEEE 646 802.15.4e", draft-ietf-6tisch-terminology-03 (work in 647 progress), January 2015. 649 [I-D.ietf-6tisch-tsch] 650 Watteyne, T., Palattella, M., and L. Grieco, "Using 651 IEEE802.15.4e TSCH in an IoT context: Overview, Problem 652 Statement and Goals", draft-ietf-6tisch-tsch-05 (work in 653 progress), January 2015. 655 [I-D.ietf-core-observe] 656 Hartke, K., "Observing Resources in CoAP", draft-ietf- 657 core-observe-16 (work in progress), December 2014. 659 [I-D.vanderstok-core-comi] 660 Stok, P., Greevenbosch, B., Bierman, A., Schoenwaelder, 661 J., and A. Sehgal, "CoAP Management Interface", draft- 662 vanderstok-core-comi-06 (work in progress), February 2015. 664 [I-D.wang-6tisch-6top-sublayer] 665 Wang, Q., Vilajosana, X., and T. Watteyne, "6TiSCH 666 Operation Sublayer (6top)", draft-wang-6tisch-6top- 667 sublayer-01 (work in progress), July 2014. 669 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 670 Resource Identifier (URI): Generic Syntax", STD 66, RFC 671 3986, January 2005. 673 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 674 Specifications: ABNF", STD 68, RFC 5234, January 2008. 676 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 677 Representation (CBOR)", RFC 7049, October 2013. 679 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 680 Application Protocol (CoAP)", RFC 7252, June 2014. 682 5.3. External Informative References 684 [IEEE802154e] 685 IEEE standard for Information Technology, "IEEE std. 686 802.15.4e, Part. 15.4: Low-Rate Wireless Personal Area 687 Networks (LR-WPANs) Amendment 1: MAC sublayer", April 688 2012. 690 Appendix A. 692 Guidelines for constructing URI path names: 694 1. The first letter of each element of the path SHOULD be 695 capitalized 697 2. If an element has multiple words, each the first letter of each 698 work SHOULD be capitalized 700 Authors' Addresses 702 Raghuram S Sudhaakar (editor) 703 Cisco Systems, Inc 704 Building 24 705 510 McCarthy Blvd 706 San Jose 95135 707 USA 709 Phone: +1 408 853 0844 710 Email: rsudhaak@cisco.com 712 Pouria Zand 713 University of Twente 714 Department of Computer Science 715 Zilverling Building 716 Enschede 7522 NB 717 The Netherlands 719 Phone: +31 619040718 720 Email: p.zand@utwente.nl