Thing-to-Thing Research Group K. Hartke Internet-Draft Universitaet Bremen TZI Intended status: Experimental September 14, 2015 Expires: March 17, 2016 CoRE Lighting draft-hartke-core-lighting-00 Abstract CoRE Lighting is an application-level protocol for discovering, configuring and controlling smart objects (or "things") in a simple lighting scenario. The protocol is based on CoAP transfer of representations that are formatted according to media types defined in this document. Note to Readers This Internet-Draft is discussed on the Thing-to-Thing Research Group (T2TRG) mailing list . 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 March 17, 2016. Copyright Notice Copyright (c) 2015 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 Hartke Expires March 17, 2016 [Page 1] Internet-Draft CoRE Lighting September 2015 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. Foreword . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Description . . . . . . . . . . . . . . . . . . . . . . . 6 3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 6 3.3. Configuration . . . . . . . . . . . . . . . . . . . . . . 7 3.4. Operation . . . . . . . . . . . . . . . . . . . . . . . . 7 4. Links and Forms in JSON . . . . . . . . . . . . . . . . . . . 9 4.1. Resource Objects . . . . . . . . . . . . . . . . . . . . 9 4.2. Link Objects . . . . . . . . . . . . . . . . . . . . . . 10 4.3. Form Objects . . . . . . . . . . . . . . . . . . . . . . 10 5. Application Description . . . . . . . . . . . . . . . . . . . 11 5.1. The 'application/thing-description+json' Media Type . . . 12 5.2. The 'application/bulletin-board+json' Media Type . . . . 13 5.3. The 'application/lighting-config+json' Media Type . . . . 14 5.4. The 'application/lighting+json' Media Type . . . . . . . 15 5.5. The 'config' Link Relation Type . . . . . . . . . . . . . 16 6. Interoperability Considerations . . . . . . . . . . . . . . . 17 7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 8.1. Link Relation Types . . . . . . . . . . . . . . . . . . . 17 8.2. CoAP Content Formats . . . . . . . . . . . . . . . . . . 17 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 9.1. Normative References . . . . . . . . . . . . . . . . . . 18 9.2. Informative References . . . . . . . . . . . . . . . . . 18 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 20 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20 1. Foreword Hypermedia helps greatly with change (i.e., evolving clients and servers) in the Web. Can it also work for the Internet of Things (IoT)? The Thing-to-Thing Research Group (T2TRG) wants to answer this question by implementing and evolving an example IoT application. This document presents a CoRE Application [I-D.hartke-core-apps], media types, and link and form relation types for a simple lighting scenario. Hartke Expires March 17, 2016 [Page 2] Internet-Draft CoRE Lighting September 2015 The purpose of this document is not to attempt to set a solution in stone. Rather, it aims to present a starting point for discussion and experimentation within the T2TRG. The idea is that people can add further appliances, media types, and interactions in an uncoordinated fashion ("permissionless innovation"), thus evolving, twisting and growing the application just like a real application might evolve over a longer period of time. For a first plugfest, this document makes the following simplifying assumptions: o There are exactly two types of "things": light bulbs and light remote controls (LRCs). o Bulbs and LRCs support on/off, brightness level, and color control (hue/saturation, color coordinates, and color temperature). o LRCs and light bulbs are connected on a one-to-one basis. o Things are 'always on', i.e., it is expected that things do not disconnect from the network to save energy. o CoAP [RFC7252] is used as transport protocol. o JSON [RFC7159] is used as serialization format. More efficient formats (such as CBOR [RFC7049]) will be incorporated at a later stage. o Group communication will be considered at a later stage. o Mobile things will be considered at a later stage. o Security will be considered at a later stage. It is further expected that parts of the application (such as the machine-readable description of Things) will converge with the work of the W3C Web of Things (WoT) Interest Group [WOT-IG]. Hartke Expires March 17, 2016 [Page 3] Internet-Draft CoRE Lighting September 2015 2. Introduction CoRE Lighting is an application-level protocol for discovering, configuring and controlling smart objects (or "things") in a simple lighting scenario. The protocol is based on CoAP [RFC7252] transfer of representations that are formatted according to media types defined in this document. 2.1. Terminology This document uses the following terms: Thing: In the context of the Internet of Things, a "thing" is an Internet-connected, physical device that is placed at the boundary between the physical world and the virtual world. Actuator: An Actuator is a Thing that enables the virtual world to produce an effect on the physical environment. Examples are "heating things" that produce a heating effect on the physical environment, or "light bulb things" that produce an illumination effect on the physical environment. Sensor: A Sensor is a Thing that quantifies its physical environment and exposes the data to the virtual world. Examples are "temperature things" that measure the temperature of the physical environment, or "light switch things" that expose the state of a light switch to the virtual world. LRC: A Light Remote Control (LRC) is a Thing that can turn a light bulb on/off, and adjust colors and brightness levels. CoRE: Constrained RESTful Environments (CoRE) is a vision for the Internet of Things where Actuators and Sensors communicate with each other in REST style. REST: Representational State Transfer (REST) is an architectural style for building scalable web applications. The key concept is the hypermedia-driven transfer of resource state representations between clients and servers. Resource: A resource is anything that can be identified by a URI. Representation: A representation is a sequence of bytes that captures the current or intended state of a resource. Media Type: A media type is a string that labels a representation so that it is known how the representation should be interpreted, and how it is encoded. Hartke Expires March 17, 2016 [Page 4] Internet-Draft CoRE Lighting September 2015 Hypermedia Control: A hypermedia control is a construct embedded in a representation that affords a potential next or future request from the client to a server. Hypermedia controls range from simple links to complex forms. Link: A link provides a means for navigating from one resource to another. It consists of a context (the link origin), a link relation type, the target of the link, and optional hints about the link target. Form: A form provides a means for changing resource state. It consists of a context (the subject of the state change), a form relation type, and instructions for creating a request that triggers the state change. Link Relation Type: A link relation type identifies the semantics of a link. Form Relation Type: A form relation type identifies the semantics of a form. 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]. Hartke Expires March 17, 2016 [Page 5] Internet-Draft CoRE Lighting September 2015 3. Overview CoRE Lighting follows a Description-Discovery-Configuration-Operation pattern. 3.1. Description Things have a Thing Description: a representation of the Thing that describes its attributes and capabilities. Attributes include basic human-readable information like name, purpose, location, and owner. Capabilities include the capability of the Thing to interact with the physical environment or to be configured to interact with other Things. Capabilities are exposed as hypermedia controls. ______ __ | |\ / \__| |_\ \__/ | what | | who | | where | |_______| Since Thing Descriptions are representations, they can be transferred to and stored on other devices, for example, a directory that lists all Things in an area or a spider that builds an index of Things. Thing Descriptions are formatted according to the 'application/thing- description+json' Media Type (Section 5.1). 3.2. Discovery For a start, the discovery of Actuators and Sensors is enabled by a simple bulletin board-style service: Things are pre-configured out- of-band with a single entry-point URI to a bulletin board. The bulletin board provides hypermedia controls to publish the presence of a new Thing and to discover other Things. ____________ | | __ | * thing 1 | / \ ----------> | * thing 2 | \__/ <---------- | * thing 3 | | * ... | |____________| Thing Bulletin Board (Client) (Server) Hartke Expires March 17, 2016 [Page 6] Internet-Draft CoRE Lighting September 2015 While the bulletin board is primarily intended to list Things along with their respective Thing Description, it can in principle be used to publish representations in any Media Type. The bulletin board itself is formatted according to the 'application/bulletin- board+json' Media Type (Section 5.2). The bulletin board is conceptually very similar to Simple Directory Discovery [I-D.ietf-core-resource-directory]. The difference is that a Thing publishes a Thing Description with links rather than links with link attributes. 3.3. Configuration Once Things have been discovered and their attributes and capabilities are known, pairs of light bulbs and Light Remote Controls (LRCs) can be associated with each other. This is accomplished by using a configurator device (e.g., a mobile phone) that configures the light bulb to take the client role and observe [I-D.ietf-core-observe] a specific resource at the LRC, which takes the server role. _________ _...._ | _______ | .' '. || || / \ || || | | || || ----------> \ ~~ / || || <---------- `\ || /` || || |_||_| ||_______|| {____} | o | {____} |_________| () Configurator Light Bulb (Client) (Server) The configuration of a light bulb is represented in the 'application/ lighting-config+json' Media Type (Section 5.3). 3.4. Operation Once the Things have been configured, the light bulb observes the specified resource at the LRC and produces an illumination effect on the physical environment according to the observed LRC state. The LRC state is represented in the 'application/lighting+json' Media Type (Section 5.4). Hartke Expires March 17, 2016 [Page 7] Internet-Draft CoRE Lighting September 2015 _...._ ___________ .' '. | o | o | / \ | /|\ | | | | |_____|_____| \ ~~ / ----------> | | | `\ || /` <---------- | + | - | |_||_| |_____|_____| {____} | | | {____} | < | > | () |_____|_____| Light Bulb Remote Control (Client) (Server) Hartke Expires March 17, 2016 [Page 8] Internet-Draft CoRE Lighting September 2015 4. Links and Forms in JSON The representation formats defined in this document are based on JSON [RFC7159]. JSON does not support hypermedia controls such as links and forms. However, representation formats that derive from JSON can define objects to represent a link or a form, thus extending JSON to a hypermedia format. The "hypermediafied" JSON used in this document is inspired by the JSON Hypertext Application Language (HAL) [I-D.kelly-json-hal]. In comparison, HAL does not support forms and provides some features that are omitted here for simplicity, such as templated links and CURIEs. This section specifies the JSON objects that are common to all representation formats defined in this document. In particular, all of the formats are "hypermediafied" JSON documents: JSON text [RFC7159] that serializes a Resource Object. 4.1. Resource Objects A Resource Object is a JSON object that represents a resource. It has four reserved members: "_base": string Specifies a base URI for relative references. "_links": object Contains links that reference other resources that are related to the resource. It is an object whose names are link relation types (as defined by [RFC5988]) and values are either a Link Object or an array of Link Objects (Section 4.2). "_forms": object Contains forms that describe actions that can be performed on the resource. It is an object whose names are form relation types (as defined by [I-D.hartke-core-apps]) and values are either a Form Object or an array of Form Objects (Section 4.3). "_embedded": object Contains embedded resources. It is an object whose names are link relation types (as defined by [RFC5988]) and values are either a Resource Object or an array of Resource Objects (Section 4.1). All other name/value pairs represent the current or intended state of the resource. Hartke Expires March 17, 2016 [Page 9] Internet-Draft CoRE Lighting September 2015 4.2. Link Objects A Link Object is a JSON object that represents a link from the containing resource to a target resource. It has the following members: "href": string Conveys the link target URI as a URI-Reference [RFC3986]. If the URI-Reference is relative, parsers MUST resolve it as per [RFC3986], Section 5. "type": string Provides a hint indicating what the media type of the result of dereferencing the link should be. 4.3. Form Objects A Form Object is a JSON object that represents a form which can be used to perform an action on the containing resource. The action is performed by issuing a request according to the following members: "href": string Conveys the form target URI as a URI-Reference [RFC3986]. If the URI-Reference is relative, parsers MUST resolve it as per [RFC3986], Section 5. "method": string Specifies the method to use for form submission ("POST", "PUT", "PATCH" or "DELETE"). "accept": string Specifies the media type acceptable for the representation to be enclosed in the request message payload as part of form submission. Hartke Expires March 17, 2016 [Page 10] Internet-Draft CoRE Lighting September 2015 5. Application Description Application name: CoRE Lighting 1.0 URI schemes: coap [RFC7252] Media types: application/thing-description+json (Section 5.1) application/bulletin-board+json (Section 5.2) application/lighting-config+json (Section 5.3) application/lighting+json (Section 5.4) Link relations: about [RFC6903] config (Section 5.5) item [RFC6573] Form relations: create-item [I-D.hartke-core-apps] update [I-D.hartke-core-apps] Well-known locations: None. Interoperability considerations: See Section 6. Security considerations: See Section 7. Contact: See "Author's Address" section. Author/Change controller: IESG Hartke Expires March 17, 2016 [Page 11] Internet-Draft CoRE Lighting September 2015 5.1. The 'application/thing-description+json' Media Type A representation in the 'application/thing-description+json' Media Type serializes a Thing Description Object. A Thing Description Object is a Resource Object that conveys the attributes and capabilities of a Thing. It has the following members: "name": string The name of the Thing. "purpose": string The purpose of the Thing. "location": string The physical location of the Thing. All three members are intended to be human-readable and have no meaning from a Thing's point of view. 5.1.1. Examples Example Thing Description of a light bulb: { "_links": { "config": { "href": "/config", "type": "application/lighting-config+json" } }, "name": "Light 2", "purpose": "Illuminates the couch.", "location": "Living Room" } This light bulb has the name "Light 2" and is described to illuminate the couch in the living room. The description links to an associated "config" resource that provides the current configuration of the light bulb in the 'application/lighting-config+json' Media Type. Example Thing Description of a Light Remote Control (LRC): { "_links": { "about": { "href": "/state", "type": "application/lighting+json" } Hartke Expires March 17, 2016 [Page 12] Internet-Draft CoRE Lighting September 2015 }, "name": "LRC 1", "purpose": "Controls Light 2.", "location": "Living Room" } This LRC has the name "LRC 1" and is described to control the light bulb "Light 2" in the living room. The description links to a resource that the Thing Description is about, namely a resource that provides the current state of the LRC. [TODO: Is there a better link relation type for this link?] 5.2. The 'application/bulletin-board+json' Media Type A representation in the 'application/bulletin-board+json' Media Type serializes a Bulletin Board Object. A Bulletin Board Object is a Resource Object that is a collection of embedded Thing Description Objects. It has no further members. 5.2.1. Example Example bulletin board with two embedded Thing Descriptions: { "_forms": { "create-item": { "href": "/bulletins", "method": "POST", "accept": "application/thing-description+json" } }, "_embedded": { "item": [ { "_base": "coap://light-bulb.example/", "_links": { "config": { "href": "/config", "type": "application/lighting-config+json" } }, "name": "Light 2", "purpose": "Illuminates the couch.", "location": "Living Room" }, { "_base": "coap://remote-control.example/", "_links": { Hartke Expires March 17, 2016 [Page 13] Internet-Draft CoRE Lighting September 2015 "about": { "href": "/state", "type": "application/lighting+json" } }, "name": "LRC 1", "purpose": "Controls Light 2.", "location": "Living Room" } ] } } This bulletin board provides a "create-item" form which can be used to publish new Thing Descriptions. It also has two embedded Thing Descriptions, to which it links using the "item" link relation type. Both Thing Descriptions link back to the respective Thing. 5.3. The 'application/lighting-config+json' Media Type A representation in the 'application/lighting-config+json' media type serializes a Lighting Configuration Object. A Lighting Configuration Object is a Resource Object that represents the current or intended configuration of a light bulb. It has the following members: "src": object/null A Link Object (Section 4.2) linking to the resource to observe. Dereferencing the target URI SHOULD result in a representation in the 'application/lighting+json' Media Type (Section 5.4). [TODO: Should the supported media type(s) be included in the Thing Description?] 5.3.1. Example Example configuration of a light bulb: { "_forms": { "update": { "href": "", "method": "PUT", "accept": "application/lighting-config+json" } }, "src": { "href": "coap://remote-control.example/state" } Hartke Expires March 17, 2016 [Page 14] Internet-Draft CoRE Lighting September 2015 } This configuration indicates that the light bulb should observe the resource . The representation also includes a form that can be used to update the configuration. To update the configuration, the form instructs the client to make a PUT request with a 'application/lighting-config+json' representation to the relative URI "" (i.e., the empty string which resolves to the base URI as per [RFC3986], Section 5). 5.4. The 'application/lighting+json' Media Type A representation in the 'application/lighting+json' media type serializes a Lighting Object. A Lighting Object is a Resource Object that represents the current or intended state of a light bulb. It has the following members: "on": true/false true if the light is on; otherwise, false. "brightness": number The brightness, expressed as a value between 0.0 (minimum brightness) and 1.0 (maximum brightness). Note that a value of 0.0 does not mean that the light is off. "hue": number The hue, expressed as a value between 0 and 360. "saturation": number The saturation, expressed as a value between 0.0 (least saturated) and 1.0 (most saturated). "x": number The X coordinate of a color in CIE color space, expressed as a value between 0.0 and 1.0. "y": number The Y coordinate of a color in CIE color space, expressed as a value between 0.0 and 1.0. "colorTemperature": number The color temperature in mired. "colorMode": string The color mode. Possible values are: "hs" - "hue" and "saturation" are used to set the color. Hartke Expires March 17, 2016 [Page 15] Internet-Draft CoRE Lighting September 2015 "xy" - "x" and "y" are used to set the color. "ct" - "colorTemperature" is used to set the color. The "colorMode" member determines the color mode used. For example, when the color mode is set to "ct", the light bulb reflects the color specified by "colorTemperature" member, and the other members ("hue", "saturation", "x", and "y") are ignored. If a light bulb receives a value that is outside of the achievable range, the light bulb SHOULD choose the closest value it can produce. 5.4.1. Example Example representation: { "on": true, "brightness": 0.5, "hue": 210, "saturation": 0.9, "x": 0.4448, "y": 0.4066, "colorTemperature": 343, "colorMode": "ct" } 5.5. The 'config' Link Relation Type The "config" link relation can be used to refer to a resource describing the configuration of the link's context. For example, if the context resource is a Thing, the "config" link can be used to reference the URI of the Thing's configuration: { "_links": { "config": { "href": "/config" } } } Hartke Expires March 17, 2016 [Page 16] Internet-Draft CoRE Lighting September 2015 6. Interoperability Considerations [TODO.] 7. Security Considerations [TODO.] 8. IANA Considerations [TODO: The media types defined in Section 5 need to be registered.] 8.1. Link Relation Types o Relation Name: config Description: Refers to a resource that can be used to configure the link's context. Reference: [RFCXXXX] 8.2. CoAP Content Formats o Media Type: application/thing-description+json Encoding: - ID: 65200 Reference: [RFCXXXX] o Media Type: application/bulletin-board+json Encoding: - ID: 65201 Reference: [RFCXXXX] o Media Type: application/lighting-config+json Encoding: - ID: 65202 Reference: [RFCXXXX] o Media Type: application/lighting+json Encoding: - ID: 65203 Reference: [RFCXXXX] Note: The IDs are from the 'Experimental Use' range for the purpose of interoperability testing. They are not for operational use. Hartke Expires March 17, 2016 [Page 17] Internet-Draft CoRE Lighting September 2015 9. References 9.1. Normative References [I-D.hartke-core-apps] Hartke, K., "CoRE Application Descriptions", draft-hartke- core-apps-02 (work in progress), August 2015. [I-D.ietf-core-observe] Hartke, K., "Observing Resources in CoAP", draft-ietf- core-observe-16 (work in progress), December 2014. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, . [RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010, . [RFC6573] Amundsen, M., "The Item and Collection Link Relations", RFC 6573, DOI 10.17487/RFC6573, April 2012, . [RFC6903] Snell, J., "Additional Link Relation Types", RFC 6903, DOI 10.17487/RFC6903, March 2013, . [RFC7159] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014, . [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014, . 9.2. Informative References Hartke Expires March 17, 2016 [Page 18] Internet-Draft CoRE Lighting September 2015 [I-D.ietf-core-resource-directory] Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE Resource Directory", draft-ietf-core-resource-directory-04 (work in progress), July 2015. [I-D.kelly-json-hal] Kelly, M., "JSON Hypertext Application Language", draft- kelly-json-hal-07 (work in progress), July 2015. [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, October 2013, . [WOT-IG] W3C, "Web of Things Interest Group Charter", January 2015, . Hartke Expires March 17, 2016 [Page 19] Internet-Draft CoRE Lighting September 2015 Acknowledgements Thanks to Carsten Bormann, Stefanie Gerdes, Michael Koster, Matthias Kovatsch, and Peter van der Stok for helpful comments and discussions that have shaped the document. Author's Address Klaus Hartke Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63905 EMail: hartke@tzi.org Hartke Expires March 17, 2016 [Page 20]