6TiSCH Data Model for CoAP
draft-sudhaakar-6tisch-coap-00
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Replaced".
|
|
|---|---|---|---|
| Authors | Raghuram S Sudhaakar , Pouria Zand | ||
| Last updated | 2013-10-22 | ||
| Replaced by | draft-ietf-6tisch-coap | ||
| RFC stream | (None) | ||
| Formats | |||
| Additional resources | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-sudhaakar-6tisch-coap-00
6TiSCH R. Sudhaakar, Ed.
Internet-Draft Cisco
Intended status: Standards Track P. Zand
Expires: April 24, 2014 University of Twente
October 21, 2013
6TiSCH Data Model for CoAP
draft-sudhaakar-6tisch-coap-00
Abstract
The [IEEE802154e] standardizes the TSCH mode of operation and defines
the mechanisms for layer 2 communication between conforming devices.
6top defines a set of commands to monitor and manage the TSCH
schedule. To realize the full functionality of sensor networks and
allow their adoption and use in real applications we need additional
mechanisms. Specifically, we need to define how to interact with
6top, control and modify schedules, monitor parameters etc. Higher
layers monitoring and management entities are then able to use these
capabilities to create feedback loops. Although, there have been
many custom implementations of such feedback loops between the
routing, transport and MAC layers in sensor network deployments,
there has been a lack of standards based approaches. The goal of the
memo is to define a generic data model between monitoring and
management entities and the 6top layer and define a mapping to the
6top commands. The document also presents a particular
implementation of the model based on CoAP and CBOR.
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 April 24, 2014.
Copyright Notice
Sudhaakar & Zand Expires April 24, 2014 [Page 1]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
Copyright (c) 2013 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
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
1. Requirements notation . . . . . . . . . . . . . . . . . . . . 2
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Scope of the document . . . . . . . . . . . . . . . . . . . . 3
4. Generic Data Model . . . . . . . . . . . . . . . . . . . . . 4
5. Data Model definition for CoAP . . . . . . . . . . . . . . . 4
5.1. Naming Convention for URI schemes . . . . . . . . . . . . 4
5.2. Convention for accessing URIs . . . . . . . . . . . . . . 4
5.3. 6TiSCH Resources . . . . . . . . . . . . . . . . . . . . 5
5.3.1. Management Resources . . . . . . . . . . . . . . . . 5
5.3.2. Informational Resources . . . . . . . . . . . . . . . 7
5.3.3. Message Formats . . . . . . . . . . . . . . . . . . . 7
5.3.4. Extensible Resources . . . . . . . . . . . . . . . . 10
5.4. Example . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.4.1. Request-Response . . . . . . . . . . . . . . . . . . 10
5.4.2. Publish-Subscribe . . . . . . . . . . . . . . . . . . 12
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1. Normative References . . . . . . . . . . . . . . . . . . 12
6.2. Informative References . . . . . . . . . . . . . . . . . 12
6.3. External Informative References . . . . . . . . . . . . . 13
Appendix A. . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14
1. Requirements notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
Sudhaakar & Zand Expires April 24, 2014 [Page 2]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
2. Introduction
The 6TiSCH Operation Sublayer (6top) [I-D.wang-6tsch-6top] describes
the main commands provided to higher layers that allow them to build
TSCH schedules, make routing decisions, perform TSCH configuration
and control procedures and supports centralized and decentralized
scheduling policies among other functionalities. However, there is
still a need for specifying the methods, including message exchanges
and message formats that higher layers use to invoke these command
described by 6top.
+------------------------------------+
| Higher Layers |
+------------------------------------+
| Information and Data Model |
| for interacting with 6top |
+------------------------------------+
| 6top |
+------------------------------------+
| 802.15.4e TSCH |
+------------------------------------+
Figure 1: Logical positioning of layers
In order to have an wide impact we need to be able to interoperate
with any protocol that may be used by the network layer. This
documents aims at defining the message exchanges and the formats of
the messages that the network layer uses to interact with the 6top
sub-layer. We use the YANG data modelling language to specify a data
format reusable across different protocols/elements including RPL,
RSVP, PCE, etc.
This document also specifies an implementation of this generic
message exchange and data model using CoAP as the transport
mechanism.
3. Scope of the document
We first define a generic data model that is applicable to extensions
on other transport protocols. The generic data model uses YANG to
describe the message and formats that are used by the higher layers
to interact with 6top.
It is followed by the implementation details of the data model for
the specific scenario where the higher layer may use CoAP to interact
with the 6top nodes. The document defines the URIs that are used to
identify resources exposed by 6top. The messages that are required
to be sent to the 6top sublayer are defined using the CBOR format.
Sudhaakar & Zand Expires April 24, 2014 [Page 3]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
This document also defines how users can install custom resources
that allow them to extend the basic resource exposed by 6top.
4. Generic Data Model
[TODO]
5. Data Model definition for CoAP
5.1. Naming Convention for URI schemes
Universal Resource Identifiers (URIs) help us uniquely identify the
various commands and parameters that 6top exposes to the higher
layers. We use the basic URI naming conventions and terminology
specified in [RFC3986]. Specifically, the terms, 'scheme',
'authority', 'path', 'query' are used as defined in the [RFC3986].
The following provides the guidelines that are followed in this draft
to name the URIs that identify the resources exposed by 6top.
1. All URIs naming 6top resources MUST use the 'coap' scheme
2. The authority MUST have the username '6top' and the IP address of
6top node
3. The root path MUST always start with '6t'
4. Each component of the path SHOULD be of minimum possible length
while being self descriptive.
5. Typographical conventions as described in A SHOULD be followed
These guidelines MUST be followed by users who install extensible
resources. It SHOULD be followed for future extensions of the data
model in order to provide consistency.
5.2. Convention for accessing URIs
We use the GET, POST and DELETE methods described by CoAP. These
methods MUST be used in accordance with their definition in Sec. 5.8
of [I-D.ietf-core-coap]. We have no need for the PUT method as the
functionality of the POST method can be used for all situations that
need updating or modification of a resource. The CoAP methods are
mapped to 6top commands as shown in the figure below.
+-------------+--------------+-------------------------+
| CoAP method | 6top command | Description |
+-------------+--------------+-------------------------+
Sudhaakar & Zand Expires April 24, 2014 [Page 4]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
| GET | READ | Retrieves 6top resources|
+-------------+--------------+-------------------------+
| POST | CREATE / | Creates/Updates a new |
| | UPDATE | entry |
+-------------+--------------+-------------------------+
| DELETE | DELETE | Deletes an entry |
+-------------+--------------+-------------------------+
| POST | CONFIGURE | Configures a setting |
+-------------+--------------+-------------------------+
Figure 2: Mapping between CoAP methods and 6top commands
The GET method may use queries to allow higher layer entities to
perform conditional GETs or filter the results of a GET on resource
that is a collection.
The POST method is used in all situations where an argument needs to
be passed to the 6top layer. The Content-Type option is set to
'application/cbor'. The payload is encoded using CBOR format as
described in [I-D.bormann-cbor].
The DELETE method is used to invoke the 6top DELETE command on a
particular resource.
The GET method may use queries to allow higher layer entities to
perform conditional GETs or filter the results of a GET on resource
that is a collection.
5.3. 6TiSCH Resources
Management resources are classified as resources to which a higher
layer entity may create, update or delete. They are typically used
to create schedules, identify time sources that TSCH needs. They are
the means to close the control loop between TSCH and higher layers.
Informational resources are classified as resources to which a higher
layer entity typically has only READ access. They are typically used
to monitor operational parameters of TSCH and the values used as
input to routing algorithms and other mechanisms.
5.3.1. Management Resources
All the attributes in the management resources have the Read/Write
accessibility. The following table lists the 6top management
resources and the related URI paths.
+-------------+-----------------+---------------+
| Name | Accessibility | URI path |
Sudhaakar & Zand Expires April 24, 2014 [Page 5]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
| | 6top Commands | |
+-------------+-----------------+---------------+
| Neighbor | CREATE/READ/ | 6t/Neighbor |
| Table | DELETE/UPDATE | |
+-------------+-----------------+---------------+
| slotframe | CREATE/READ/ | 6t/slotframe |
| Table | DELETE/UPDATE | |
+-------------+-----------------+---------------+
| Cell | CREATE/READ/ | 6t/Cell |
| Table | DELETE/UPDATE | |
+-------------+-----------------+---------------+
| Time | CREATE/READ/ | 6t/TimeSource |
| Source | DELETE/UPDATE | |
+-------------+-----------------+---------------+
| Bundle | CREATE/READ/ | 6t/Bundle |
| Table | DELETE/UPDATE | |
+-------------+-----------------+---------------+
| Track | CREATE/READ/ | 6t/Track |
| Table | DELETE/UPDATE | |
+-------------+-----------------+---------------+
| EB | CREATE/READ/ | 6t/EB |
| Table | DELETE/UPDATE | |
+-------------+-----------------+---------------+
Figure 3: List of Management Resources
In the following table, we provide an example about how Neighbor
table attributes can be addressed.
+-------------+---------------------------+
| Field name | URI path |
+-------------+---------------------------+
| Neighbor | 6t/Neighbor/ShortAddr |
| Short Addr | |
+-------------+---------------------------+
| numTx | 6t/Neighbor/numTx |
+-------------+---------------------------+
| numTxAck | 6t/Neighbor/numTxAck |
+-------------+---------------------------+
| numRx | 6t/Neighbor/numRx |
+-------------+---------------------------+
| Neighbor | 6t/Neighbor/LongAddr |
| Long Addr | |
+-------------+---------------------------+
| ASN | 6t/Neighbor/ASN |
+-------------+---------------------------+
| RPL rank | 6t/Neighbor/RPLrank |
+-------------+---------------------------+
Sudhaakar & Zand Expires April 24, 2014 [Page 6]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
| Time Source | 6t/Neighbor/TSFlag |
| Flag | |
+-------------+---------------------------+
| RSSI | 6t/Neighbor/RSSI |
+-------------+---------------------------+
| LQI | 6t/Neighbor/LQI |
+-------------+---------------------------+
Figure 4: Neighbor Table
5.3.2. Informational Resources
All the attributes in the Informational resources have the Read
accessibility. The following table lists the 6top informational
resources and the related URI paths.
+-------------+-----------------+-----------------------+
| Name | Accessibility | URI path |
| | 6top Commands | |
+-------------+-----------------+-----------------------+
| Queue | READ/CONFIGURE | 6t/Queue |
+-------------+-----------------+-----------------------+
| Queue | READ/CONFIGURE | 6t/QueueStats |
| stats | | |
+-------------+-----------------+-----------------------+
| Monitoring | READ/CONFIGURE | 6t/MonitoringStatus |
| status | | |
+-------------+-----------------+-----------------------+
| Statistics | READ/CONFIGURE | 6t/StatisticsMetrics |
| metrics | | |
+-------------+-----------------+-----------------------+
Figure 5: List of Informational Resources
5.3.3. Message Formats
GET messages do not contain any payload. However, they can contain a
query option to filter on the resource that is being retrieved. An
example query on the neighbor table is:
+-------------------------------------+
Header | GET |
+-------------------------------------+
Uri-Path| /6t/Neighbor |
+-------------------------------------+
Options | Accept: application/cbor |
| Uri-Query: ABNF(ShortAddr==0x1234) |
+-------------------------------------+
Sudhaakar & Zand Expires April 24, 2014 [Page 7]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
Figure 6: Example GET message
Since this resources points to the entire neighbor table the response
returns all the rows (the list of neighbors of that node) and all
fields in each row (i.e. entry for a neighbor) of the table in CBOR
format. A request with a Uri-Query option may be used to retrieve
only specific rows in the table. The value of Uri-Query MUST be in
the ABNF formatas described in [RFC5234].
Resources that point to collection within a table, such as '/6t/
Neighbor/ShortAddr', returns only the values in the ShortAddr column
of the Neighbor table. The usage of the Uri-Query option has the
same effect of filtering on the result.
The endpoint MUST appropriately respond with a 2.05 Content or 4.04
Not Found message as defined in [I-D.ietf-core-coap]. If the
resource is found then the payload of the response MUST contain a
CBOR representation of the data that is referenced by the URI.
To create or update a Neighbor, the CoAP client MUST send a POST
message as shown in Figure 7. The payload MUST describe the argument
that is passed to 6top in CBOR format.
+-------------------------------------+
Header | POST |
+-------------------------------------+
Uri-Path| /6t/Neighbor |
+-------------------------------------+
Payload | CBOR( {ShortAddr: 0x1234} ) |
+-------------------------------------+
Figure 7: Example POST message
The POST method may not be used on resources that are collection
within a table, such as '/6t/Neighbor/ShortAddr'.
To delete a Neighbor, the CoAP client MUST send a DELETE message as
shown in Figure 8.
Sudhaakar & Zand Expires April 24, 2014 [Page 8]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
+-------------------------------------+
Header | DELETE |
+-------------------------------------+
Uri-Path| /6t/Neighbor |
+-------------------------------------+
Options | Uri-Query: ABNF(ShortAddr==0x1234) |
| |
+-------------------------------------+
Figure 8: Example DELETE message
A DELETE message SHOULD always contain a Uri-Query option in order to
clearly specify which row(s) within the table must be deleted.
Ideally, the CoAP client SHOULD make one call per row that must be
deleted. An implementation may decide whether or not a DELETE method
on '/6t/Neighbor' may be allowed.
The endpoint MUST appropriately respond with a 2.02 (Deleted)
message.
A sample of mapping between CoAP methods and 6top commands for
manipulating the neighbor table is shown in the figure below.
+--------------------+----------------+---------------+-------------+
| CoAP method | 6top command |6top behaviour |CoAP Response|
+--------------------+----------------+---------------+-------------+
| POST /6t/Neighbor | Create.neighbor| Adds a | 2.01 Created|
| CBOR( | | neighbor | |
| {ShortAddr: 1234}) | (address,stats)| | |
+--------------------+----------------+---------------+-------------+
| GET /6t/Neighbor | Read.all. | Reads | 2.05 Content|
| | neighbor() | all | CBOR(Neigh- |
| | | neighbors | bor Table) |
+--------------------+----------------+---------------+-------------+
| GET /6t/Neighbor | Read.neighbor | Reads neighbor| 2.05 Content|
| Uri-Query - | (address) | information | CBOR(Neigh- |
| ShortAddr == 0x1234| | | bor Table) |
+--------------------+----------------+---------------+-------------+
| POST /6t/Neighbor | Update.neighbor| Updates an | 2.04 Changed|
| CBOR( | (address,stats)| entry | |
| {ShortAddr: 1234}) | | | |
+--------------------+----------------+---------------+-------------+
| DELETE /6t/Neighbor|Delete.neighbor | Removes | 2.02 Deleted|
| Uri-Query - | (address) | the neighbor | |
| ShortAddr == 0x1234| | | |
+--------------------+----------------+---------------+-------------+
Figure 9: CoAP methods and resulting invocation 6top commands
Sudhaakar & Zand Expires April 24, 2014 [Page 9]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
5.3.4. Extensible Resources
Extensible resources are to be used when a higher layer entity wants
to be notified of an event. An event may be defined as the result of
a mathematical operation on a 6top resource. For example, the CoAP
client might want to monitor when the DAG rank of a particular node
crosses a threshold. Once the extensible resource is installed the
CoAP client uses the observe mechanism defined in
[I-D.ietf-core-observe] to monitor the resource.
5.3.4.1. Defining new resources
An extensible resource path MUST always start with '/6t/custom' and
follow the guideline for URI naming as described in 5.1. The event
associated with the extensible resource must be defined using the
ABNF notation described in [RFC5234].
An extensible resource may be created by performing POST operation to
the resource '/6t/custom' with the following payload encoded using
CBOR.
+---------------+------------+
| Field Name | Type |
+---------------+------------+
| Resource | String |
| Name | |
+---------------+------------+
| Event | String |
| Definition | |
+---------------+------------+
Figure 10: Payload format for creating an Extensible Resource
5.3.4.2. Resource Profiles
[TODO]
5.3.4.3. Resource and Profile Discovery
[TODO]
5.4. Example
This section gives a number of short examples of how to use the data
model and CoAP mapping defined in this document.
5.4.1. Request-Response
Sudhaakar & Zand Expires April 24, 2014 [Page 10]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
Figure 11 shows how a CoAP client adds an entry in the neighbor table
of node A. This new neighbor has short address 0x1234. The client
sends out a POST request containing the CBOR encoding of '{ShortAddr:
1234}'. This message is received and processed by the CoAP endpoint
of Node A and in turn, the 6top command, Create.neighbor is invoked
with the appropriate parameters. In this case, the address is the
'ShortAddr' parameter passed in the payload of the POST message and
the stats argument has the default value. In the response to the
invocation of the Create.neighbor command, the 6top sublayer adds an
entry to the neighbor table with appropriate values and returns a
confirm message. The CoAP endpoint in turn send out an appropriate
CoAP response to indicate success. In situation where the addition
of the neighbor failed, a failure message will be returned.
CoAP Client Node A Node A
(CoAP-endpoint) (6top sublayer)
| CoAP Request | |
|- - - - - - - - - - - ->| 6top Request |
| POST /6t/Neighbor |----------------------->|
| payload: | Create.neighbor | Adds a
| CBOR({ShortAddr: 1234})| (address,stats) | neighbor
| | | ShortAddr:
| | | 1234
| | 6top Confirm |
| CoAP Response |<-----------------------|
|<- - - - - - - - - - - -| |
| | |
| | |
Figure 11: Example of adding a neighbor
In Figure 12, a CoAP client reads a neighbor entry from node A. This
neighbor has short address 0x1234.
CoAP Client Node A Node A
(CoAP-endpoint) (6top sublayer)
| CoAP Request | |
|- - - - - - - - - - - ->| 6top Request |
| GET /6t/Neighbor |----------------------->|
| Uri-Query - | Read.neighbor(address) |Reads neighbor
| ShortAddr == 0x1234 | |information
| | |
| | |
| | 6top Confirm |
| CoAP Response |<-----------------------|
|<- - - - - - - - - - - -| Reads neighbor |
| 2.05 Content | information |
| | |
Sudhaakar & Zand Expires April 24, 2014 [Page 11]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
Figure 12: Example of reading a neighbor
5.4.2. Publish-Subscribe
In Figure 13, a CoAP client subscribes to Monitoring Status of node
A. The Monitoring status of Node A is constantly monitored by the
CoAP client.
CoAP Client Node A Node A
(CoAP-endpoint) (6top sublayer)
| CoAP Register | |
|- - - - - - - - - - - - >| 6top Request |
| GET /6t/MonitoringStatus|----------------------->|
| | Read.Monitoring.Status |Reads
| | |the current
| | |Monitoring
| | |status
| | 6top Notification |
| CoAP Notification |<-----------------------|
|<- - - - - - - - - - - - | Reads the current |
| 2.05 Content | Monitoring status |
| | |The Status
| | |changes
| | 6top Notification |
| CoAP Notification |<-----------------------|
|<- - - - - - - - - - - - | Notifies upon the |
| 2.05 Content | status change |
| | |The Status
| | |changes
| | 6top Notification |
| CoAP Notification |<-----------------------|
|<- - - - - - - - - - - - | Notifies upon the |
| 2.05 Content | status change |
| | |
Figure 13: Example of Subscribing to Monitoring Status
6. References
6.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
6.2. Informative References
[I-D.bormann-cbor]
Sudhaakar & Zand Expires April 24, 2014 [Page 12]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
Bormann, C. and P. Hoffman, "Concise Binary Object
Representation (CBOR)", draft-bormann-cbor-09 (work in
progress), September 2013.
[I-D.ietf-core-coap]
Shelby, Z., Hartke, K., and C. Bormann, "Constrained
Application Protocol (CoAP)", draft-ietf-core-coap-18
(work in progress), June 2013.
[I-D.ietf-core-observe]
Hartke, K., "Observing Resources in CoAP", draft-ietf-
core-observe-11 (work in progress), October 2013.
[I-D.wang-6tsch-6top]
Wang, Q., Vilajosana, X., and T. Watteyne, "6TSCH
Operation Sublayer (6top)", draft-wang-6tsch-6top-00 (work
in progress), July 2013.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008.
6.3. External Informative References
[IEEE802154e]
IEEE standard for Information Technology, "IEEE std.
802.15.4e, Part. 15.4: Low-Rate Wireless Personal Area
Networks (LR-WPANs) Amendment 1: MAC sublayer ", April
2012.
Appendix A.
Guidelines for constructing URI path names:
1. The first letter of each element of the path SHOULD be
capitalized
2. If an element has multiple words, each the first letter of each
work SHOULD be capitalized
Sudhaakar & Zand Expires April 24, 2014 [Page 13]
Internet-Draft 6TiSCH Data Model for CoAP October 2013
Authors' Addresses
Raghuram S Sudhaakar (editor)
Cisco Systems, Inc
Building 24
510 McCarthy Blvd
San Jose 95135
USA
Phone: +1 408 853 0844
Email: rsudhaak@cisco.com
Pouria Zand
University of Twente
Graaf Florisstraat
1-F18
Deventer 7415 LK
Netherlands
Phone: +31 619040718
Email: p.zand@utwente.nl
Sudhaakar & Zand Expires April 24, 2014 [Page 14]