Internet DRAFT - draft-mietz-core-coap-state-option

draft-mietz-core-coap-state-option






core                                                            R. Mietz
Internet-Draft                                     University of Luebeck
Intended status: Standards Track                       December 10, 2013
Expires: June 13, 2014


                 CoAP High-Level State Option Extension
                 draft-mietz-core-coap-state-option-01

Abstract

   CoAP is a RESTful application protocol for constrained devices which
   are often equipped with sensors measuring a physical phenomenon such
   as temperature on a precise scale.  These sensor values are made
   available by a resource on the CoAP endpoint.  However, for many
   applications it is not necessary to have the full precision a sensor
   can provide.  It's often even enough to only have some high-level
   states instead of raw values.  This document presents a new option
   for CoAP to dynamically create new resources for a sensor which
   provides user-defined high-level states instead of raw sensor values.

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 June 13, 2014.

Copyright Notice

   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



Mietz                     Expires June 13, 2014                 [Page 1]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   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.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Motivation . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . .  4
   2.  High-Level State Option Extension  . . . . . . . . . . . . . .  4
     2.1.  High-level State Option Definition . . . . . . . . . . . .  4
     2.2.  Using the High-level State Option  . . . . . . . . . . . .  5
       2.2.1.  Creating State Resources . . . . . . . . . . . . . . .  5
       2.2.2.  Querying State Resources . . . . . . . . . . . . . . .  9
       2.2.3.  Deleting States Resources  . . . . . . . . . . . . . . 10
   3.  Examples of Usage  . . . . . . . . . . . . . . . . . . . . . . 10
     3.1.  Example 1  . . . . . . . . . . . . . . . . . . . . . . . . 10
     3.2.  Example 2  . . . . . . . . . . . . . . . . . . . . . . . . 13
   4.  Security Considerations  . . . . . . . . . . . . . . . . . . . 15
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 16
   6.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 16
   7.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 16
     7.1.  Normative reference  . . . . . . . . . . . . . . . . . . . 16
     7.2.  Informative Reference  . . . . . . . . . . . . . . . . . . 16
   Appendix A.  XML Schema for XML Serialization of One State
                Resources . . . . . . . . . . . . . . . . . . . . . . 16
   Appendix B.  XML Schema for XML Serialization of Multiple
                State Resources . . . . . . . . . . . . . . . . . . . 18
   Appendix C.  Changelog . . . . . . . . . . . . . . . . . . . . . . 19
   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 19



















Mietz                     Expires June 13, 2014                 [Page 2]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


1.  Introduction

   This document adds a new option to the Constrained Application
   Protocol (CoAP): High-Level State.

1.1.  Motivation

   The Constrained Application Protocol [I-D.ietf-core-coap] (CoAP) is a
   lightweight efficient variant of the well-known Hypertext Transfer
   Protocol specifically designed for devices with limited resources
   such as small memory, little processing power, and constrained energy
   capacities.  The main area of operation of CoAP is on wireless sensor
   nodes, i.e., wireless devices equipped with sensors to monitor
   environmental parameters such as temperature, air quality, or
   humidity.  Hence, not only static metadata but also sensor values are
   retrieved by users via CoAP.  The change frequency of measured sensor
   values depends on the one hand on the accuracy of the sensor but on
   the other hand on the (physical) property the sensor measures.  It
   therefore may vary from milliseconds up to minutes, hours, or even
   days.  A user interested in a parameter needs to request the current
   value periodically to keep track of changes.  However, periodic
   querying can consume a good portion of the total amount of energy
   available and results in the quick depletion of a device's energy.
   Additionally, many requests might be unnecessary because the sensor
   value did not change compared to the last request.  For that reason,
   CoAP observe [I-D.ietf-core-observe] introduces a mechanism to
   register interest in a resource much like with publish-subscribe
   systems.  A CoAP server then only sends a response whenever the
   sensor value changes.  As a result, only a reduced number of messages
   are required to keep track of the sensor readings.

   Although the CoAP observe option can save resources, it might happen
   that the number of messages and thus, resource consumption even
   increases.  This happens if the sensor value changes very often
   resulting in frequent update messages.  Besides that, some clients
   may not be interested in raw precise sensor values but in a range a
   sensor values falls into.  We call this range a high-level state
   because it categorizes the sensor value.  So, instead of being
   interested if a room has 21.9 oC or 22.1 oC, the user might only want
   to know if it is "warm" in that room.  The number of states for an
   environmental parameter is typically low.  Accordingly, states change
   with much lower frequency as the underlying raw sensor values.
   Consequently, this leads to fewer responses when using CoAP observe.

   The High-Level State option allows creating, querying and deleting
   high-level state resources for sensor resources on CoAP servers with
   the known CoAP request methods GET, POST, and DELETE.  The user can
   define which sensor values are mapped to which high-level state.



Mietz                     Expires June 13, 2014                 [Page 3]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   Additionally, he can retrieve descriptions of already existing high-
   level state resources to reuse them.

1.2.  Terminology

   The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [RFC2119].

   This document uses terms of the Constrained Application Protocol as
   defined in the terminology section of [I-D.ietf-core-coap].

   Additionally, this specification defines the following terms:

   High-level state:

      In contrast to a raw sensor reading a high-level state combines a
      number of sensor outputs under a new descriptive term given as a
      string.

   High-level state resource:

      A CoAP resource, which returns different high-level states.  State
      resource will be used synonymously with the term high-level state
      resource.


2.  High-Level State Option Extension

2.1.  High-level State Option Definition


   +------+---+---+---+---+------------+--------+----------+---------+
   | Type | C | U | N | R |   Name     | Format |  Length  | Default |
   +------+---+---+---+---+------------+--------+----------+---------+
   | TBD  | - | - | - | x | High-Level | (see   |  1-257 B | (none)  |
   |      |   |   |   |   |   State    | below) |          |         |
   +------+---+---+---+---+------------+--------+----------+---------+

               Figure 1: High-Level State Option Definition

   The High-Level State Option is "elective" and "proxy-safe".  It is
   "repeatable".  Hence, the High-Level State Option can occur more than
   once.  The use of repetition will be described in the following
   sections.

   This Option can only be present in requests.  Additionally, it has
   different semantics when used with different request methods.  These



Mietz                     Expires June 13, 2014                 [Page 4]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   are described in the following sections.

   The value carried in the Option has the following general format:

                           0 1 2 3 4 5 6 7
                          +-+-+-+-+-+-+-+-+
                          | T |     -     |
                          +-+-+-+-+-+-+-+-+
                          |    Optional   |
                          +     Values    +
                                 ...
                          + (0-256 bytes) +
                          |               |
                          +-+-+-+-+-+-+-+-+

                         Figure 2: General format

   T (TYPE): The value of the TYPE field is a 2 bit integer.  If used in
   POST requests, it indicates the value format after the first byte.
   If used in GET requests, it specifies what representation a client
   expects in response to that request.  Further details are discussed
   in Section 2.2.1 and Section 2.2.2 about the creation respectively
   querying of state resources.

   The bits 2-7 are unused and MUST be ignored by the server.

2.2.  Using the High-level State Option

   The semantics of the Option depend on the used CoAP request method.
   In short, POST and DELETE create and remove state resources while GET
   is used to retrieve the state or a description of existing state
   resources.

2.2.1.  Creating State Resources

   To create a new state resource for a sensor resource, the client has
   to POST a request to the Uri-Path of the sensor.  The server MUST
   create the state resource as a subresource of the sensor resource.

   The output of most sensors is on a continuous numerical scale.
   However, some sensors output string or Boolean data types (true/
   false respectively 1/0).  The client should be able to map each of
   these data types to high-level states.  For numerical values, the
   client should be able to specify mappings from intervals to states
   and for strings it should be able to map one or several different
   strings to a state.  Boolean values can be easily mapped by using
   either the string mapping if the output is true or false or the
   numerical mapping if the output is 1 or 0.  Hence, two formats for



Mietz                     Expires June 13, 2014                 [Page 5]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   the Option are available.

   The used format is indicated by the TYPE field.  Figure 3 shows the
   data types of a sensor output along with the integer used for the
   TYPE field and the format which is assumed to follow.  Boolean is not
   listed because, as argued before, it can be mapped with the integer
   or string type.

                  +-----------+------+--------+
                  | Data type | TYPE | Format |
                  +-----------+------+--------+
                  | integer   |   0  |   1    |
                  | float     |   1  |   1    |
                  | string    |   2  |   2    |
                  +-----------+------+--------+

                          Figure 3: Format types

   The number of bytes used for values in the different Option formats
   is given in Figure 4.  Floats are encoded in Single-precision
   floating-point format as defined in [IEEE754].  One Option defines
   one state.  Therefore, by repeating the High-Level State Option
   several states can be defined.

                  +-----------+----------------+
                  | Data type | Length (bytes) |
                  +-----------+----------------+
                  | integer   |       2        |
                  | float     |       4        |
                  | string    |     0-128      |
                  +-----------+----------------+

                        Figure 4: Data type lengths


















Mietz                     Expires June 13, 2014                 [Page 6]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   Format 1 is used for a mapping of an interval of numerical values to
   a state.  It consists of a numerical lower and a numerical upper
   bound as well as a string giving the state name.  The lower bound is
   inclusive while the upper bound is exclusive.  This allows defining
   consecutive, continuous, non-intersecting intervals.

                           0 1 2 3 4 5 6 7
                          +-+-+-+-+-+-+-+-+
                          | T |     -     |
                          +-+-+-+-+-+-+-+-+
                          |  Lower Bound  |
                          +    (incl.)    +
                                 ...
                          +  (2/4 bytes)  +
                          |               |
                          +-+-+-+-+-+-+-+-+
                          |  Upper Bound  |
                          +    (excl.)    +
                                 ...
                          +  (2/4 bytes)  +
                          |               |
                          +-+-+-+-+-+-+-+-+
                          |               |
                          +     State     +
                                 ...
                          + (1-128 bytes) +
                          |               |
                          +-+-+-+-+-+-+-+-+

             Figure 5: Format 1: Used for an interval mapping





















Mietz                     Expires June 13, 2014                 [Page 7]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   Format 2 is to map a string to a state.  Whenever the string output
   of the sensor matches the string which is given as the first
   parameter the string given as the second parameter is the current
   state.

                          0 1 2 3 4 5 6 7
                          +-+-+-+-+-+-+-+-+
                          | T |     -     |
                          +-+-+-+-+-+-+-+-+
                          |               |
                          +     Output    +
                                 ...
                          + (1-128 bytes) +
                          |               |
                          +-+-+-+-+-+-+-+-+
                          |               |
                          +     State     +
                                 ...
                          + (1-128 bytes) +
                          |               |
                          +-+-+-+-+-+-+-+-+

               Figure 6: Format 2: Used for a string mapping

   The server MUST ignore payload enclosed in the request.

   If the server successfully created the state resource serving the
   defined states, it MUST send a response with response code 2.01
   (Created) and the Location-Path Option which gives the relative Uri-
   Path for the newly created resource.  The Uri-Path of the created
   resource can be an arbitraly allowed string.  However, it is
   RECOMMENDED to use short Uri-Paths.

   As already mentioned, by repeating the Option, several states can be
   defined.  However, if the Option is repeated with different values
   for the TYPE field, the server MUST NOT process the request, and MUST
   send a response with response code 4.02 (Bad Option).

   If the upper bound of an interval is smaller than the lower bound of
   that interval, the server MUST NOT process the request, and MUST send
   a response with response code 4.02 (Bad Option).

   Due to ambiguity, it is forbidden to define different states for the
   same value.  Hence, if a numerical mapping is used and if at least
   one intersection of any two intervals is non-empty, the server MUST
   NOT process the request, and MUST send a response with response code
   4.02 (Bad Option).  The same holds, if a string mapping is used and
   the same string is mapped to different states.



Mietz                     Expires June 13, 2014                 [Page 8]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   In the case that a client requests creation of a state resource with
   exactly same mappings and states as an already existing one, the
   server SHOULD send a response with response code 2.05 (Content) with
   the Uri-Path of the existing state resource as payload instead of
   creating another resource with the same semantics.  Implementers must
   be aware that state resources can be deleted anytime.  Accordingly,
   if a state resource is used by several clients and one deletes it,
   the other clients are not aware of that.  Contrary, creating state
   resources with same semantics for each client, consumes more
   resources.

   If the server is not able to create the state resource for the given
   sensor resource, e.g., because of insufficient resources, it MUST
   send a response with response code 5.03 (Service Unavailable).  The
   server SHOULD include a payload indicating the reason for not
   creating the state resource.

   If a client requests to create a state resource for a non-sensor
   resource, the server MUST NOT process the request and MUST send a
   response with response code 4.03 (Forbidden).

   If the TYPE of a request is not matching the data type outputted by
   the sensor, the server SHOULD reject the request and SHOULD send a
   response with response code 4.02 (Bad Option).

2.2.2.  Querying State Resources

   The current state of a state resource can be retrieved by a normal
   GET-request without the High-Level State Option present in the
   request.  However, by including the Option, the client can control
   the data which should be returned.  The type of data that the server
   should return is indicated by the TYPE field in the request.
   Figure 7 gives an overview of all available T values.


                         +--------------+-----+
                         |       T      | No. |
                         +--------------+-----+
                         | State        |  0  |
                         | State Number |  1  |
                         | Description  |  2  |
                         +--------------+-----+

                         Figure 7: Response types

   If T = 0, the server MUST return the current state.  With T = 1 an
   integer representing the state MUST be returned by the server.  The
   integer is determined as follows: in each state resource creation



Mietz                     Expires June 13, 2014                 [Page 9]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   process upon a POST-request the states MUST be enumerated starting
   with 0 by their order of appearance in the High-Level State Options.
   If T = 2 the server MUST return a description of the state resource
   describing the mappings and the appropriate states.  An XML Schema
   for the XML format is given in Appendix A.  If there is no defined
   state for a sensor value, i.e., there is no mapping for this value,
   the server MUST return the state "undefined" if T = 0 and -1 if T =
   1.

   A list of all available state resource of a sensor resources can be
   retrieved by sending a GET-request with High-Level-State Option to
   the sensor resource with T = 2 included.  The xml format the server
   MUST return is defined by the XML Schema in Appendix B.  All other
   requests with the High-Level State Option to a sensor resource SHOULD
   be ignored by the server.

2.2.3.  Deleting States Resources

   If a client wants to remove a state resource, it has to send a DELETE
   message to the state resource.  The server MUST delete the state
   resource and a "2.02 (Deleted) response code SHOULD be used on
   success or in case the resource did not exist before the request" as
   stated in Section 5.8.4 in [I-D.ietf-core-coap].


3.  Examples of Usage

   In the following sections two examples show how the high-level state
   option is used to create, query, and delete state resources.

3.1.  Example 1

   Consider four users who want to retrieve data from a temperature
   sensor.  However, they are not interested in the raw values but high-
   level states.  Hence, they want to create state resources on the
   server.  The parameters of the High-Level State Option in the
   examples are T and the appropriate optional values as described in
   Section 2.2.













Mietz                     Expires June 13, 2014                [Page 10]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   User 1 is the first to communicate with the CoAP server.  He wants to
   have two states, namely a "cold" and a "warm" state, where the first
   is defined as temperature between -50 oC and 20 oC and the second all
   values which are between 20 oC and 50 oC.  For that, a POST-request
   with the bounds is send to the server:

          Client Server
            |      |
            |      |
            +----->|           Header: POST
            | POST |            Token: 0x06
            |      |         Uri-Path: "temp"
            |      | High-Level State: "1 -50.0 20.0 cold"
            |      | High-Level State: "1 20.0 50.0 warm"
            |      |
            |<-----+           Header: 2.01 Created
            | 2.01 |            Token: 0x06
            |      |    Location-Path: x42y
            |      |

        Figure 8: User 1 creating a state resource with two states

   The server answers with a response code of 2.01 (Created) and a
   Location-Path indicating that a state resource, which can serve the
   two desired high-level states, is now available under the given path.

   Second, the next user wants to have four states ("cold", "moderate",
   "warm", and "hot") with bounds of -50 oC, 0 oC, 10 oC, 25 oC, and 50
   oC.  The communication to create these states looks as follows:

          Client Server
            |      |
            |      |
            +----->|           Header: POST
            | POST |            Token: 0x09
            |      |         Uri-Path: "temp"
            |      | High-Level State: "1 -50.0 0.0 cold"
            |      | High-Level State: "1 0.0 10.0 moderate"
            |      | High-Level State: "1 10.0 25.0 warm"
            |      | High-Level State: "1 25.0 50 hot"
            |      |
            |<-----+           Header: 2.01 Created
            | 2.01 |            Token: 0x09
            |      |    Location-Path: 1ee7
            |      |

             Figure 9: User 2 creating another state resource




Mietz                     Expires June 13, 2014                [Page 11]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   Afterwards, the server has two state resources for the sensor
   resource.  The one serves two states and the other one which serves
   four states.

   Also the third user wants to create a high-level resource.  By
   chance, he requests the same states and bounds as the first user
   which can be seen in the POST-request:

          Client Server
            |      |
            |      |
            +----->|           Header: POST
            | POST |            Token: 0x19
            |      |         Uri-Path: "temp"
            |      | High-Level State: "1 -50.0 20.0 cold"
            |      | High-Level State: "1 20.0 50.0 warm"
            |      |
            |<-----+           Header: 2.05 Content
            | 2.05 |            Token: 0x19
            |      |    Location-Path: x42y
            |      |

      Figure 10: Creation of a State Resource with Same Semantics as
                      Already Existing State Resource

   Consequently, the response is different too the one sent to user 1.
   The response code is 2.04 (Changed) and the Location-Path Option
   gives the path of the already existing resource.

   The last user finally sends his POST-request to create another
   resource with three states:

          Client Server
            |      |
            |      |
            +----->|           Header: POST
            | POST |            Token: 0x83
            |      |         Uri-Path: "temp"
            |      | High-Level State: "1 -60.0 12.3 cold"
            |      | High-Level State: "1 12.3 21.9 medium"
            |      | High-Level State: "1 21.9 72.0 warm"
            |      |
            |<-----+           Header: 5.03 Service Unavailable
            | 5.03 |            Token: 0x83
            |      |          Payload: "Already too many resources"
            |      |

    Figure 11: Failing of State Resource Creation due to Low Resources



Mietz                     Expires June 13, 2014                [Page 12]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   Unfortunately, the server rejected to create a new resource due to
   insufficient resources which is indicated by the response.  Because
   of that the user sent another request to retrieve a list of already
   available state resources:

          Client Server
            |      |
            |      |
            +----->|           Header: GET
            | GET  |            Token: 0x84
            |      |         Uri-Path: "temp"
            |      |           Accept: application/json
            |      | High-Level State: 2
            |      |
            |      |
            |<-----+           Header: 2.05 Content
            | 2.05 |            Token: 0x84
            |      |          Payload: "{res:{r:[{
            |      |                    p:'x42y',
            |      |                    num:[{l:-50,h:20,s:'cold'},
            |      |                       {l:20,h:50,s:'warm'}]},{
            |      |                    p:'1ee7',
            |      |                    num:[{l:-50,h:0,s:'cold'},
            |      |                       {l:0,h:10,s:'moderate'},
            |      |                       {l:10,h:25,s:'warm'},
            |      |                       {l:25,h:50,s:'hot'}]}]}}"
            |      |

          Figure 12: Retrieving List of Existing State Resources

   With this list of JSON-encoded state resource the user has the
   ability to decide if he wants to use one of the existing state
   resources.

3.2.  Example 2

   In the second example, we consider a sensor which outputs strings
   describing the current weather and a user who first wants to use a
   string mapping to create a state resource for the weather sensor.
   Afterwards, he queries the state resource and finally deletes it.
   The output range of the sensor is "rainy", "cloudy", "sunny", and
   "foggy".









Mietz                     Expires June 13, 2014                [Page 13]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   The client sends a POST-request with a string mapping to create the
   two states "home" and "beach".

          Client Server
            |      |
            |      |
            +----->|           Header: POST
            | POST |            Token: 0x06
            |      |         Uri-Path: "weather"
            |      | High-Level State: "2 rainy home"
            |      | High-Level State: "2 cloudy home"
            |      | High-Level State: "2 foggy home"
            |      | High-Level State: "2 sunny beach"
            |      |
            |<-----+           Header: 2.01 Created
            | 2.01 |            Token: 0x06
            |      |    Location-Path: mr21
            |      |

               Figure 13: The User Creates a State Resource

   After creation of the state resource, he retrieves the current state
   by sending a GET-request.

          Client Server
            |      |
            |      |
            +----->|           Header: GET
            | GET  |            Token: 0x09
            |      |         Uri-Path: "weather/mr21"
            |      | High-Level State: "0"
            |      |
            |<-----+           Header: 2.05 Content
            | 2.05 |            Token: 0x09
            |      |          Payload: "beach"
            |      |

              Figure 14: The User Retrieves the Current State













Mietz                     Expires June 13, 2014                [Page 14]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   Because it is good weather, the user decides to go to the beach.  But
   before, he releases the resources on the server by deleting the state
   resource.

          Client Server
            |        |
            |        |
            +------->|           Header: DELETE
            | DELETE |            Token: 0x83
            |        |         Uri-Path: "weather/mr21"
            |        |
            |<-------+           Header: 2.02 Deleted
            |  2.05  |            Token: 0x83
            |        |

              Figure 15: The User Deletes the State Resource


4.  Security Considerations

   PUT operations, often used for updates, in conjunction with the High-
   Level State Option are forbidden.  Hence, the server MUST NOT process
   such requests and MUST respond with a response code of 4.05 (Method
   not allowed).  Updates of state resources can lead to unexpected
   behavior of clients if several clients use the same state resource.
   If one client is updating mappings or states of a state resource,
   other clients which are not aware of the update could end up in
   abnormal behavior because they cannot handle the unexpected results.
   For the same reason, a server SHOULD NOT reuse Uri-Paths of deleted
   state resources.

   Depending on the implementation and the remaining resources of the
   server, creation of state resources can consume a considerable amount
   of resources.  However, this is true for all resource creations and
   not limited to the presented new High-Level State Option.  Anyway,
   implementers SHOULD be aware of this fact and consider
   countermeasures such as limiting the number of state resources which
   can be created, limiting the number of state resource creation
   requests per client, or to introduce a duration after a successful
   state resource creation in which further requests are rejected.











Mietz                     Expires June 13, 2014                [Page 15]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


5.  IANA Considerations

   The IANA is requested to add the following "CoAP Option Numbers"
   entry as per Section 12.2 of [I-D.ietf-core-coap]:

   +--------+------------------+-----------------------------+
   | Number | Name             | Reference                   |
   +--------+------------------+-----------------------------+
   |  TBD   | High-Level State | Section 2 of this document  |
   +--------+------------------+-----------------------------+


6.  Acknowledgements

   Thanks to Lukas Ruge, Dennis Pfisterer, Kay Roemer and Philipp
   Abraham for proof-reading, helpful comments and discussions that have
   helped to shape this document.


7.  References

7.1.  Normative reference

   [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.

   [IEEE754]  Institute of Electrical and Electronics Engineers (IEEE),
              "754-2008  -  IEEE Standard for Floating-Point
              Arithmetic", August 2008.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

7.2.  Informative Reference

   [I-D.ietf-core-observe]
              Hartke, K., "Observing Resources in CoAP",
              draft-ietf-core-observe-11 (work in progress),
              October 2013.


Appendix A.  XML Schema for XML Serialization of One State Resources







Mietz                     Expires June 13, 2014                [Page 16]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


   <?xml version="1.0" encoding="utf-8"?>
   <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
              xmlns="http://www.example.com/state-option"
              targetNamespace="http://www.example.com/state-option"
              elementFormDefault="qualified"
              attributeFormDefault="unqualified">

    <!-- To describe a state resources -->
    <xs:element name="r" type="resource"/>

    <!-- To describe the mappings of a state resource along
         with the uri-path-->
    <xs:complexType name="resource">
     <xs:sequence>
      <xs:choice>
       <xs:element name="num" type="num_map" maxOccurs="unbounded"/>
       <xs:element name="str" type="string_map" maxOccurs="unbounded"/>
      </xs:choice>
     </xs:sequence>
    </xs:complexType>

   <!-- To describe a numerical mapping with lower bound,
        upper bound and state -->
    <xs:complexType name="num_map">
     <xs:sequence>
      <xs:sequence maxOccurs="unbounded">
       <xs:element name="l" type="xs:float"/>
       <xs:element name="h" type="xs:float"/>
      </xs:sequence>
      <xs:element name="s" type="xs:string"/>
     </xs:sequence>
    </xs:complexType>

    <!-- To describe a string mapping with
         one or more strings and state -->
    <xs:complexType name="string_map">
     <xs:sequence>
      <xs:element name="str" type="xs:string" maxOccurs="unbounded"/>
      <xs:element name="s" type="xs:string"/>
     </xs:sequence>
    </xs:complexType>

   </xs:schema>








Mietz                     Expires June 13, 2014                [Page 17]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


Appendix B.  XML Schema for XML Serialization of Multiple State
             Resources


   <?xml version="1.0" encoding="utf-8"?>
   <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
              xmlns="http://www.example.com/state-option"
              targetNamespace="http://www.example.com/state-option"
              elementFormDefault="qualified"
              attributeFormDefault="unqualified">

    <xs:element name="res" type="res"/>

    <!-- To describe one or more state resources -->
    <xs:complexType name="res">
     <xs:sequence>
      <xs:element name="r" type="resource" maxOccurs="unbounded"/>
     </xs:sequence>
    </xs:complexType>

    <!-- To describe the mappings of a state resource along
         with the uri-path-->
    <xs:complexType name="resource">
     <xs:sequence>
      <xs:element name="p" type="xs:normalizedString"/>
      <xs:choice>
       <xs:element name="num" type="num_map" maxOccurs="unbounded"/>
       <xs:element name="str" type="string_map" maxOccurs="unbounded"/>
      </xs:choice>
     </xs:sequence>
    </xs:complexType>

    <!-- To describe a numerical mapping with lower bound,
         upper bound and state -->
    <xs:complexType name="num_map">
     <xs:sequence>
      <xs:sequence maxOccurs="unbounded">
       <xs:element name="l" type="xs:float"/>
       <xs:element name="h" type="xs:float"/>
      </xs:sequence>
      <xs:element name="s" type="xs:string"/>
     </xs:sequence>
    </xs:complexType>

    <!-- To describe a string mapping with
         one or more strings and state -->
    <xs:complexType name="string_map">
     <xs:sequence>



Mietz                     Expires June 13, 2014                [Page 18]

Internet-Draft   CoAP High-Level State Option Extension    December 2013


      <xs:element name="str" type="xs:string" maxOccurs="unbounded"/>
      <xs:element name="s" type="xs:string"/>
     </xs:sequence>
    </xs:complexType>

   </xs:schema>


Appendix C.  Changelog

   Changes from draft-00 to draft-01:

   o  Changed contact details of author.

   o  Updated references of CoAP and CoAP observe.

   o  Fixed number of Bytes in Figure Figure 2 from 257 to 256.

   o  Fixed number of Bytes in Figure Figure 5 from 2-4 to 2/4.

   o  Fixed number of Bytes in Figures Figure 5 and Figure 6 from 0-128
      to 1-128.

   o  Fixed tokens in Figure Figure 15 and Figure 14.

   o  Corrected caption of Figure Figure 15.  Before it was the same as
      in Figure Figure 14 because of copy \& paste.

   o  Removed "or equal" from the paragraph where handling of a upper
      bound smaller than the lower bound is described (Section
      Section 2.2.1).  Equal upper and lower bound are allowed because
      one is inclusive and the other exclusive.


Author's Address

   Richard Mietz
   University of Luebeck
   Ratzeburger Allee 160
   Luebeck, Schleswig-Holstein  23562
   DE

   Phone: +49 451 500 5984
   Email: mietz@itm.uni-luebeck.de
   URI:   http://www.itm.uni-luebeck.de/






Mietz                     Expires June 13, 2014                [Page 19]