CoRE Working Group C. Bormann Internet-Draft Universitaet Bremen TZI Intended status: Informational A. Keranen Expires: January 9, 2017 Ericsson July 08, 2016 The BLE (Bluetooth Low Energy) URI Scheme and Media Types draft-bormann-t2trg-ble-uri-00 Abstract In addition to its use as a subnetwork layer for IP (e.g., via RFC 7668), in various IoT web applications Bluetooth Low Energy (BLE) can serve as a "local interconnect", connecting devices locally (i.e., not over IP) for use as a source of information and a target for actuation. In order to fully use these capabilities in applications using web technologies, there is a need for a method for addressing the resources, i.e., a URI scheme, and definition of the representation of the data exchanged between the application and devices, i.e., media types. This document is a straw man proposal for such a URI scheme and media types for interacting with the Bluetooth GAP and GATT protocols. 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 January 9, 2017. Copyright Notice Copyright (c) 2016 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 Bormann & Keranen Expires January 9, 2017 [Page 1] Internet-Draft concert July 2016 (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. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Access to local resources via Bluetooth Low Energy . . . . . 3 3. Media types . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. application/ble-nodelist . . . . . . . . . . . . . . . . 5 3.2. application/ble-gap-enablement . . . . . . . . . . . . . 6 3.3. application/ble-gap-nameinfo . . . . . . . . . . . . . . 6 3.4. application/ble-gatt-servicelist . . . . . . . . . . . . 6 3.5. application/ble-gatt-characteristics . . . . . . . . . . 6 4. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 4.1. Normative References . . . . . . . . . . . . . . . . . . 7 4.2. Informative References . . . . . . . . . . . . . . . . . 8 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 1. Introduction In the context of the W3C Web of Things (WoT) Interest Group work, the need to address both resources connected over the Internet of Things and those connected over a "local interconnect" has been raised. The present document is a straw man proposal for a URI format addressing the latter kind, using the example of the Bluetooth GAP and GATT protocols. The Bluetooth GAP and GATT REST API white papers [BT-GAP-REST] [BT-GATT-REST] describe how an HTTP gateway can be used for interacting with Bluetooth devices and their resources over the Internet, using HTTP. If a Bluetooth device is IP-enabled (e.g., [RFC7668]), also regular IP protocols (e.g., CoAP) and URI schemes can be used for end-to-end communication. When a web application is running on a Bluetooth device, or the Bluetooth device is directly connected to the same device where the web application is running, IP communication is not always necessary but a mechanism for addressing the resources is still needed. This document specifies a URI scheme for addressing such locally connected Bluetooth resources and functionality. In addition to locally connected resources, a BLE URI scheme can be used to address resources on a remote host that implements a proxy Bormann & Keranen Expires January 9, 2017 [Page 2] Internet-Draft concert July 2016 supporting both the BLE scheme and another scheme that is possible to use over a network (e.g., HTTP or CoAP). The focus of this document is on interaction with the attributes and characteristics that would be exposed as resources for an IoT web application. That is, functionality such as being able to create synchronous audio connection with a Bluetooth headset is out of scope. (Note that the version you are looking at is less than half-way complete. We plan to fill in the rest of the proposal after receiving some initial feedback about the general approach.) 1.1. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. GAP and GATT are protocols defined in [BTCorev4.2]. Terminology for constrained nodes and constrained node networks can be found in [RFC7228]. In this specification, the term "byte" is used in its now customary sense as a synonym for "octet". All multi-byte integers in this specification are interpreted in network byte order. Enabled nodes: Nodes that have been configures for automatic connection (and reconnection each time a connection is lost). 2. Access to local resources via Bluetooth Low Energy For GAP, clients operating in the GAP Central and Observer roles [BTCorev4.2] are supported. Security setup ("pairing") and the specifics of link encryption are out of scope for this version of the present document. Specifically, there is an assumption that any necessary access control to nodes and resources on these nodes is performed when the URIs defined in this document are operated. The following URIs are predefined: Bormann & Keranen Expires January 9, 2017 [Page 3] Internet-Draft concert July 2016 +------------------------+-------------------------+-----+--------+ | URI | Semantics | Op. | Result | +------------------------+-------------------------+-----+--------+ | ble:/gap/nodes/passive | passive scan for nodes | GET | (1) | | | | | | | ble:/gap/nodes/active | active scan for nodes | GET | (1) | | | | | | | ble:/gap/nodes/enabled | scan for enabled nodes | GET | (1) | | | | | | | ble:/gatt/nodes | list of available nodes | GET | (2) | +------------------------+-------------------------+-----+--------+ The GAP operations return gap node links, operations on which are detailed below. The implementation is free to choose the form of these node links, e.g. from the template "ble:/gap/node/{handle}". +---------------+-------------------------------+-----+--------+ | URI | Semantics | Op. | Result | +---------------+-------------------------------+-----+--------+ | {node} | Information about node {node} | GET | (1) | | | | | | | {node}/enable | Enablement of {node} | PUT | (3) | | | | | | | {node}/name | Name of {node} | GET | (4) | +---------------+-------------------------------+-----+--------+ The above GATT operations return gatt node links, operations on which are detailed below. Again, the implementation is free to choose the form of these node links, e.g. from the template "ble:/gatt/ node/{handle}". [[twotypes: Do we really need two types of node links or are the GAP and GATT ones possibly interchangeable?]] +-----------------+----------------------------+-----+--------+ | URI | Semantics | Op. | Result | +-----------------+----------------------------+-----+--------+ | {node}/services | Services offered by {node} | GET | (5) | +-----------------+----------------------------+-----+--------+ The above GATT operations return gatt service links, operations on which are detailed below. Again, the implementation is free to choose the form of these node links, e.g. from the template "ble:/gatt/service/{nodehandle}/{servicehandle}". [[nodesvsservices: In the current draft, it is not always clear whether a node leads to some resource or the client needs to go through a service to get there. This needs to be clarified (or possibly unified).]] Bormann & Keranen Expires January 9, 2017 [Page 4] Internet-Draft concert July 2016 +-------------------------------+--------------------+-----+--------+ | URI | Semantics | Op. | Result | +-------------------------------+--------------------+-----+--------+ | {service}/secondaryservices | Secondary services | GET | (5) | | | for {service} | | | | | | | | | {service}/characteristics | Characteristics of | GET | (6) | | | {service} | | | | | | | | | {node}/{uuid}/characteristics | {uuid} | GET | (6) | | | Characteristics of | | | | | {node} | | | +-------------------------------+--------------------+-----+--------+ +-----+-------------------------------------------------------+ | | media type | +-----+-------------------------------------------------------+ | (1) | application/ble-nodelist+json or +cbor | | | | | (2) | application/ble-nodelist+json or +cbor, no attributes | | | | | (3) | application/ble-gap-enablement+json or +cbor | | | | | (4) | application/ble-gap-nameinfo+json or +cbor | | | | | (5) | application/ble-gatt-servicelist+json or +cbor | | | | | (5) | application/ble-gatt-characteristics+json or +cbor | +-----+-------------------------------------------------------+ 3. Media types The media types below are tentatively defined in CDDL, for both JSON (add +json) and CBOR (add +cbor) use. Where the type "bytes" is used with JSON, the representation is a base64url [RFC4648] string. [[separatemediatypes: In the next version, we might possibly move to a single media type that has a choice between all these formats.]] 3.1. application/ble-nodelist Bormann & Keranen Expires January 9, 2017 [Page 5] Internet-Draft concert July 2016 nodelist = [* node] node = { href: text, ; link to that specific node bdaddr: bdaddr, ? ad: attributelist, ; only for GAP use } bdaddr = bytes .size 6 attributelist = [* attribute] ; could this be a map? attribute = [attributename, bytes] attributename = text 3.2. application/ble-gap-enablement enablement = { enabled: bool, ? interval: uint, ; define what unit ? latency: uint, ; define what unit } 3.3. application/ble-gap-nameinfo node = { href: text, ; link to that specific node name: text, } 3.4. application/ble-gatt-servicelist servicelist = [* service] service = { href: text, uuid: uuid, } uuid = bytes .size 16 3.5. application/ble-gatt-characteristics Bormann & Keranen Expires January 9, 2017 [Page 6] Internet-Draft concert July 2016 characteristics = [* characteristic] characteristic = { href: text, ; link for this characteristic properties: properties, } properties = bytes .bits property property = &( Broadcast: 0 Readable: 1 Writable-with-no-response: 2 Writable: 3 Notify: 4 Indicate: 5 Authenticated-signed-write: 6 Extended-property-available: 7 ) 4. References 4.1. Normative References [BT-GAP-REST] Bluetooth Special Interest Group, Internet Working Group, "GAP REST API White Paper", April 2014, . [BT-GATT-REST] Bluetooth Special Interest Group, Internet Working Group, "GATT REST API White Paper", April 2014, . [BTCorev4.2] Bluetooth Special Interest Group, "Bluetooth Core Specification Version 4.2", 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, . Bormann & Keranen Expires January 9, 2017 [Page 7] Internet-Draft concert July 2016 4.2. Informative References [RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006, . [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for Constrained-Node Networks", RFC 7228, DOI 10.17487/ RFC7228, May 2014, . [RFC7668] Nieminen, J., Savolainen, T., Isomaki, M., Patil, B., Shelby, Z., and C. Gomez, "IPv6 over BLUETOOTH(R) Low Energy", RFC 7668, DOI 10.17487/RFC7668, October 2015, . Authors' Addresses Carsten Bormann Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63921 Email: cabo@tzi.org Ari Keranen Ericsson Jorvas 02420 Finland Email: ari.keranen@ericsson.com Bormann & Keranen Expires January 9, 2017 [Page 8]