idnits 2.17.1 draft-ietf-6tisch-coap-02.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 (December 4, 2014) is 3403 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 685, but not defined == Unused Reference: 'I-D.ietf-6tisch-architecture' is defined on line 628, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-6tisch-coap' is defined on line 634, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-6tisch-minimal' is defined on line 639, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-6tisch-terminology' is defined on line 644, but no explicit reference was found in the text == Unused Reference: 'I-D.ietf-6tisch-tsch' is defined on line 650, but no explicit reference was found in the text == Unused Reference: 'I-D.wang-6tisch-6top-sublayer' is defined on line 665, 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-04 == Outdated reference: A later version (-03) exists of draft-ietf-6tisch-coap-01 == Outdated reference: A later version (-21) exists of draft-ietf-6tisch-minimal-04 == Outdated reference: A later version (-10) exists of draft-ietf-6tisch-terminology-02 == Outdated reference: A later version (-06) exists of draft-ietf-6tisch-tsch-03 == Outdated reference: A later version (-16) exists of draft-ietf-core-observe-15 == Outdated reference: A later version (-11) exists of draft-vanderstok-core-comi-05 == 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 (~~), 18 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: June 7, 2015 University of Twente 6 December 4, 2014 8 6TiSCH Resource Management and Interaction using CoAP 9 draft-ietf-6tisch-coap-02 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 June 7, 2015. 54 Copyright Notice 56 Copyright (c) 2014 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 GET messages do not contain any payload. However, they can contain a 383 query option to filter on the resource that is being retrieved. An 384 example query on the neighbor list is: 386 +------------------------------------------+ 387 Header | GET | 388 +------------------------------------------+ 389 Uri-Path| /6top/nbrList | 390 +------------------------------------------+ 391 Options | Accept: application/cbor | 392 | Uri-Query: ABNF(TargetNodeAddr==0x1234) | 393 +------------------------------------------+ 395 Figure 6: Example GET message 397 Since this resources points to the entire neighbor list, the response 398 returns all the entries (the list of neighbors of that node) and all 399 fields in each entry (i.e. entry for a neighbor) of the list in CBOR 400 format. A request with a Uri-Query option may be used to retrieve 401 only specific entries in the list. The value of Uri-Query MUST be in 402 the ABNF format as described in [RFC5234]. 404 Resources that point to collection within a list, such as 405 '/6top/nbrList/tna', returns only the values in the TargetNodeAddr 406 entry of the Neighbor list. The usage of the Uri-Query option has 407 the same effect of filtering on the result. 409 The endpoint MUST appropriately respond with a 2.05 Content or 4.04 410 Not Found message as defined in [RFC7252]. If the resource is found 411 then the payload of the response MUST contain a CBOR representation 412 of the data that is referenced by the URI. 414 To create or update a Neighbor, the CoAP client MUST send a POST 415 message as shown in Figure 7. The payload MUST describe the argument 416 that is passed to 6top in CBOR format. 418 +-------------------------------------+ 419 Header | POST | 420 +-------------------------------------+ 421 Uri-Path| /6top/nbrList | 422 +-------------------------------------+ 423 Payload | CBOR( {TargetNodeAddr: 0x1234} ) | 424 +-------------------------------------+ 426 Figure 7: Example POST message 428 The POST method may not be used on resources that are collection 429 within a list, such as '/6top/nbrList/tna'. 431 To delete a Neighbor, the CoAP client MUST send a DELETE message as 432 shown in Figure 8. 434 +-------------------------------------+ 435 Header | DELETE | 436 +-------------------------------------+ 437 Uri-Path| /6top/nbrList | 438 +-------------------------------------+ 439 Options | Uri-Query: ABNF(TargetNodeAddr | 440 | == 0x1234) | 441 +-------------------------------------+ 443 Figure 8: Example DELETE message 445 A DELETE message SHOULD always contain a Uri-Query option in order to 446 clearly specify which entry(s) within the list must be deleted. 447 Ideally, the CoAP client SHOULD make one call per entry that must be 448 deleted. An implementation may decide whether or not a DELETE method 449 on '/6top/nbrList' may be allowed. 451 The endpoint MUST appropriately respond with a 2.02 (Deleted) 452 message. 454 A sample of mapping between CoAP methods and 6top commands for 455 manipulating the neighbor list is shown in the figure below. 457 +---------------------+----------------+---------------+-------------+ 458 | CoAP method | 6top command |6top behaviour |CoAP Response| 459 +---------------------+----------------+---------------+-------------+ 460 | POST /6top/nbrList | Create.neighbor| Adds a | 2.01 Created| 461 | CBOR( | | neighbor | | 462 | {TargetNodeAddr: | (address,stats)| | | 463 | 1234}) | | | | 464 +---------------------+----------------+---------------+-------------+ 465 | GET /6top/nbrList | Read.all. | Reads | 2.05 Content| 466 | | neighbor() | all | CBOR(Neigh- | 467 | | | neighbors | bor List) | 468 +---------------------+----------------+---------------+-------------+ 469 | GET /6top/nbrList | Read.neighbor | Reads neighbor| 2.05 Content| 470 | Uri-Query - | (address) | information | CBOR(Neigh- | 471 | TargetNodeAddr: | | | bor List) | 472 | 1234}) | | | | 473 +---------------------+----------------+---------------+-------------+ 474 | POST /6top/nbrList | Update.neighbor| Updates an | 2.04 Changed| 475 | CBOR( | (address,stats)| entry | | 476 | {TargetNodeAddr: | | | | 477 | 1234}) | | | | 478 +---------------------+----------------+---------------+-------------+ 479 | DELETE /6top/nbrList|Delete.neighbor | Removes | 2.02 Deleted| 480 | Uri-Query - | (address) | the neighbor | | 481 | TargetNodeAddr | | | | 482 | == 1234}) | | | | 483 +---------------------+----------------+---------------+-------------+ 485 Figure 9: CoAP methods and resulting invocation 6top commands 487 4.3.5. Extensible Resources 489 Extensible resources are to be used when a higher layer entity wants 490 to be notified of an event. An event may be defined as the result of 491 a mathematical operation on a 6top resource. For example, the CoAP 492 client might want to monitor when the DAG rank of a particular node 493 crosses a threshold. Once the extensible resource is installed the 494 CoAP client uses the observe mechanism defined in 495 [I-D.ietf-core-observe] to monitor the resource. 497 4.3.5.1. Defining new resources 499 An extensible resource path MUST always start with '/6top/custom' and 500 follow the guideline for URI naming as described in 4.1. The event 501 associated with the extensible resource must be defined using the 502 ABNF notation described in [RFC5234]. 504 An extensible resource may be created by performing POST operation to 505 the resource '/6top/custom' with the following payload encoded using 506 CBOR. 508 +---------------+------------+ 509 | Field Name | Type | 510 +---------------+------------+ 511 | Resource | String | 512 | Name | | 513 +---------------+------------+ 514 | Event | String | 515 | Definition | | 516 +---------------+------------+ 518 Figure 10: Payload format for creating an Extensible Resource 520 4.4. Example 522 This section gives a number of short examples of how to use the data 523 model and CoAP mapping defined in this document. 525 4.4.1. Request-Response 527 Figure 11 shows how a CoAP client adds an entry in the neighbor list 528 of node A. This new neighbor has a target node address 0x1234. The 529 client sends out a POST request containing the CBOR encoding of 530 '{TargetNodeAddr: 1234}'. This message is received and processed by 531 the CoAP endpoint of Node A and in turn, the 6top command, 532 Create.neighbor is invoked with the appropriate parameters. In this 533 case, the address is the 'TargetNodeAddr' parameter passed in the 534 payload of the POST message and the stats argument has the default 535 value. In the response to the invocation of the Create.neighbor 536 command, the 6top sublayer adds an entry to the neighbor list with 537 appropriate values and returns a confirm message. The CoAP endpoint 538 in turn send out an appropriate CoAP response to indicate success. 539 If the addition of the neighbor failed, a failure message will be 540 returned. 542 CoAP Client Node A Node A 543 (CoAP-endpoint) (6top sublayer) 544 | CoAP Request | | 545 |- - - - - - - - - - - ->| 6top Request | 546 | POST /6top/nbrList |----------------------->| 547 | payload: | Create.neighbor | Adds a 548 | CBOR({TargertNodeAddr: | (address,stats) | neighbor 549 | 1234}) | | with address 550 | | | 1234 551 | | 6top Confirm | 552 | CoAP Response |<-----------------------| 553 |<- - - - - - - - - - - -| | 554 | | | 555 | | | 557 Figure 11: Example of adding a neighbor 559 In Figure 12, a CoAP client reads a neighbor entry from node A. This 560 neighbor has a target node address 0x1234. 562 CoAP Client Node A Node A 563 (CoAP-endpoint) (6top sublayer) 564 | CoAP Request | | 565 |- - - - - - - - - - - ->| 6top Request | 566 | GET /6top/nbrList |----------------------->| 567 | Uri-Query - | Read.neighbor(address) |Reads neighbor 568 | TargetNodeAddr | |information 569 | == 0x1234 | | 570 | | | 571 | | 6top Confirm | 572 | CoAP Response |<-----------------------| 573 |<- - - - - - - - - - - -| Reads neighbor | 574 | 2.05 Content | information | 575 | | | 577 Figure 12: Example of reading a neighbor 579 4.4.2. Publish-Subscribe 581 In Figure 13, a CoAP client subscribes to Monitoring Status of node 582 A. The Monitoring status of Node A is constantly monitored by the 583 CoAP client. 585 CoAP Client Node A Node A 586 (CoAP-endpoint) (6top sublayer) 587 | CoAP Register | | 588 |- - - - - - - - - - - - >| 6top Request | 589 | GET /6top/monitStatus |----------------------->| 590 | | Read.Monitoring.Status |Reads 591 | | |the current 592 | | |Monitoring 593 | | |status 594 | | 6top Notification | 595 | CoAP Notification |<-----------------------| 596 |<- - - - - - - - - - - - | Reads the current | 597 | 2.05 Content | Monitoring status | 598 | | |The Status 599 | | |changes 600 | | 6top Notification | 601 | CoAP Notification |<-----------------------| 602 |<- - - - - - - - - - - - | Notifies upon the | 603 | 2.05 Content | status change | 604 | | |The Status 605 | | |changes 606 | | 6top Notification | 607 | CoAP Notification |<-----------------------| 608 |<- - - - - - - - - - - - | Notifies upon the | 609 | 2.05 Content | status change | 610 | | | 612 Figure 13: Example of Subscribing to Monitoring Status 614 5. References 616 5.1. Normative References 618 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 619 Requirement Levels", BCP 14, RFC 2119, March 1997. 621 5.2. Informative References 623 [I-D.ietf-6tisch-6top-interface] 624 Wang, Q., Vilajosana, X., and T. Watteyne, "6TiSCH 625 Operation Sublayer (6top) Interface", draft-ietf-6tisch- 626 6top-interface-02 (work in progress), October 2014. 628 [I-D.ietf-6tisch-architecture] 629 Thubert, P., Watteyne, T., and R. Assimiti, "An 630 Architecture for IPv6 over the TSCH mode of IEEE 631 802.15.4e", draft-ietf-6tisch-architecture-04 (work in 632 progress), October 2014. 634 [I-D.ietf-6tisch-coap] 635 Sudhaakar, R. and P. Zand, "6TiSCH Resource Management and 636 Interaction using CoAP", draft-ietf-6tisch-coap-01 (work 637 in progress), July 2014. 639 [I-D.ietf-6tisch-minimal] 640 Vilajosana, X. and K. Pister, "Minimal 6TiSCH 641 Configuration", draft-ietf-6tisch-minimal-04 (work in 642 progress), November 2014. 644 [I-D.ietf-6tisch-terminology] 645 Palattella, M., Thubert, P., Watteyne, T., and Q. Wang, 646 "Terminology in IPv6 over the TSCH mode of IEEE 647 802.15.4e", draft-ietf-6tisch-terminology-02 (work in 648 progress), July 2014. 650 [I-D.ietf-6tisch-tsch] 651 Watteyne, T., Palattella, M., and L. Grieco, "Using 652 IEEE802.15.4e TSCH in an IoT context: Overview, Problem 653 Statement and Goals", draft-ietf-6tisch-tsch-03 (work in 654 progress), October 2014. 656 [I-D.ietf-core-observe] 657 Hartke, K., "Observing Resources in CoAP", draft-ietf- 658 core-observe-15 (work in progress), October 2014. 660 [I-D.vanderstok-core-comi] 661 Stok, P., Greevenbosch, B., Bierman, A., Schoenwaelder, 662 J., and A. Sehgal, "CoAP Management Interface", draft- 663 vanderstok-core-comi-05 (work in progress), October 2014. 665 [I-D.wang-6tisch-6top-sublayer] 666 Wang, Q., Vilajosana, X., and T. Watteyne, "6TiSCH 667 Operation Sublayer (6top)", draft-wang-6tisch-6top- 668 sublayer-01 (work in progress), July 2014. 670 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 671 Resource Identifier (URI): Generic Syntax", STD 66, RFC 672 3986, January 2005. 674 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 675 Specifications: ABNF", STD 68, RFC 5234, January 2008. 677 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 678 Representation (CBOR)", RFC 7049, October 2013. 680 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 681 Application Protocol (CoAP)", RFC 7252, June 2014. 683 5.3. External Informative References 685 [IEEE802154e] 686 IEEE standard for Information Technology, "IEEE std. 687 802.15.4e, Part. 15.4: Low-Rate Wireless Personal Area 688 Networks (LR-WPANs) Amendment 1: MAC sublayer", April 689 2012. 691 Appendix A. 693 Guidelines for constructing URI path names: 695 1. The first letter of each element of the path SHOULD be 696 capitalized 698 2. If an element has multiple words, each the first letter of each 699 work SHOULD be capitalized 701 Authors' Addresses 703 Raghuram S Sudhaakar (editor) 704 Cisco Systems, Inc 705 Building 24 706 510 McCarthy Blvd 707 San Jose 95135 708 USA 710 Phone: +1 408 853 0844 711 Email: rsudhaak@cisco.com 713 Pouria Zand 714 University of Twente 715 Department of Computer Science 716 Zilverling Building 717 Enschede 7522 NB 718 The Netherlands 720 Phone: +31 619040718 721 Email: p.zand@utwente.nl