1 scons --debug=explain VERBOSE=true RELEASE=false TARGET_TRANSPORT=IP 2 BUILD_SAMPLE=ON 3 4
OCF BRIDGING SPECIFICATION Version 0.8
Open Connectivity Foundation (OCF) [email protected]
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 0
1 Legal Disclaimer 2
3 THIS IS A DRAFT SPECIFICATION ONLY AND HAS NOT BEEN ADOPTED BY THE OPEN 4 CONNECTIVITY FOUNDATION. THIS DRAFT SPECIFICATION MAY NOT BE RELIED UPON 5 FOR ANY PURPOSE OTHER THAN REVIEW OF THE CURRENT STATE OF THE 6 DEVELOPMENT OF THIS DRAFT SPECIFICATION. THE OPEN CONNECTIVITY FOUNDATION 7 AND ITS MEMBERS RESERVE THE RIGHT WITHOUT NOTICE TO YOU TO CHANGE ANY OR 8 ALL PORTIONS HEREOF, DELETE PORTIONS HEREOF, MAKE ADDITIONS HERETO, 9 DISCARD THIS DRAFT SPECIFICATION IN ITS ENTIRETY OR OTHERWISE MODIFY THIS 10 DRAFT SPECIFICATION AT ANY TIME. YOU SHOULD NOT AND MAY NOT RELY UPON THIS 11 DRAFT SPECIFICATION IN ANY WAY, INCLUDING BUT NOT LIMITED TO THE DEVELOPMENT 12 OF ANY PRODUCTS OR SERVICES. IMPLEMENTATION OF THIS DRAFT SPECIFICATION IS 13 DONE AT YOUR OWN RISK AMEND AND IT IS NOT SUBJECT TO ANY LICENSING GRANTS 14 OR COMMITMENTS UNDER THE OPEN CONNECTIVITY FOUNDATION INTELLECTUAL 15 PROPERTY RIGHTS POLICY OR OTHERWISE. IN CONSIDERATION OF THE OPEN 16 CONNECTIVITY FOUNDATION GRANTING YOU ACCESS TO THIS DRAFT SPECIFICATION, 17 YOU DO HEREBY WAIVE ANY AND ALL CLAIMS ASSOCIATED HEREWITH INCLUDING BUT 18 NOT LIMITED TO THOSE CLAIMS DISCUSSED BELOW, AS WELL AS CLAIMS OF 19 DETRIMENTAL RELIANCE.
20 The OCF logo is a trademark of Open Connectivity Foundation, Inc. in the United States or other 21 countries. *Other names and brands may be claimed as the property of others.
22 Copyright © 2017 Open Connectivity Foundation, Inc. All rights reserved.
23 Copying or other form of reproduction and/or distribution of these works are strictly prohibited. 24
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 1
1
2 CONTENTS 3
4 1 Scope ...... 6 5 2 Normative references ...... 6 6 3 Terms, definitions, symbols and abbreviations ...... 7 7 3.1 Terms and definitions ...... 7 8 3.2 Symbols and abbreviations ...... 9 9 3.3 Conventions ...... 9 10 4 Document conventions and organization ...... 9 11 4.1 Notation ...... 9 12 4.2 Data types ...... 10 13 4.3 Document structure ...... 10 14 5 Operational Scenarios ...... 10 15 5.1 “Deep translation” vs. “on-the-fly” ...... 10 16 5.2 Use of introspection ...... 11 17 5.3 Stability and loss of data ...... 11 18 6 OCF Bridge Device ...... 12 19 6.1 Resource Discovery...... 12 20 6.2 General Requirements ...... 16 21 6.3 Security ...... 17 22 Blocking communication of Bridged Devices with the OCF ecosystem ...... 18 23 7 AllJoyn Translation ...... 18 24 7.1 Requirements Specific to an AllJoyn Translator ...... 18 25 Exposing AllJoyn producer devices to OCF Clients ...... 18 26 Exposing OCF resources to AllJoyn consumer applications ...... 25 27 7.2 On-the-Fly Translation from D-Bus and OCF payloads...... 31 28 Translation without aid of introspection ...... 31 29 Translation with aid of introspection ...... 37 30 8 Device Type Definitions ...... 42 31 9 Resource Type definitions ...... 42 32 9.1 List of resource types ...... 42 33 9.2 Secure Mode ...... 42 34 9.2.1 Introduction ...... 42 35 9.2.2 Example URI ...... 42 36 9.2.3 Resource Type ...... 43 37 9.2.4 RAML Definition ...... 43 38 9.2.5 Property Definition ...... 45 39 9.2.6 CRUDN behaviour ...... 45 40 9.3 AllJoyn Object ...... 45 41 Introduction ...... 45 42 Example URI ...... 45
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 2
1 Resource Type ...... 45 2 RAML Definition ...... 45 3 CRUDN behaviour ...... 47 4
5
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 3
1 Figures 2 Figure 1. OCF Bridge Device Components ...... 7 3 Figure 2: Schematic overview of an OCF Bridge Device bridging non-OCF devices ...... 12 4
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 4
1 Tables 2 Table 7 Alphabetical list of resource types ...... 42 3 Table 1: oic.wk.d resource type definition ...... 21 4 Table 2: oic.wk.con resource type definition ...... 22 5 Table 3: oic.wk.p Resource Type definition ...... 24 6 Table 4: oic.wk.con.p Resource Type definition ...... 25 7 Table 5: AllJoyn About Data fields ...... 27 8 Table 6: AllJoyn Configuration Data fields ...... 30 9 Table 7 Alphabetical list of resource types ...... 42 10 11
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 5
1 1 Scope
2 This document specifies a framework for translation between OCF devices and other ecosystems, 3 and specifies the behaviour of a translator that exposes AllJoyn producer applications to OCF 4 clients, and exposes OCF servers to AllJoyn consumer applications. Translation of specific AllJoyn 5 interfaces to or from specific OCF resource types is left to other specifications. Translation of 6 protocols other than AllJoyn is left to a future version of this specification. This document provides 7 generic requirements that apply unless overridden by a more specific document.
8 2 Normative references
9 The following documents, in whole or in part, are normatively referenced in this document and are 10 indispensable for its application. For dated references, only the edition cited applies. For undated 11 references, the latest edition of the referenced document (including any amendments) applies.
12 AllJoyn About Interface Specification, About Feature Interface Definitions, Version 14.12 13 https://allseenalliance.org/framework/documentation/learn/core/about-announcement/interface
14 AllJoyn Configuration Interface Specification, Configuration Interface Definition, Version 14.12 15 https://allseenalliance.org/framework/documentation/learn/base-services/configuration/interface
16 D-Bus Specification, D-Bus Specification 17 https://dbus.freedesktop.org/doc/dbus-specification.html
18 IEEE 754, IEEE Standard for Floating-Point Arithmetic, August 2008
19 IETF RFC 4122, A Universally Unique IDentifier (UUID) URN Namespace, July 2005 20 https://www.rfc-editor.org/info/rfc4122
21 IETF RFC 4648, The Base16, Base32, and Base64 Data Encodings, October 2006 22 https://www.rfc-editor.org/info/rfc4648
23 IETF RFC 6973, Privacy Considerations for Internet Protocols, July 2013 24 https://www.rfc-editor.org/info/rfc6973
25 IETF RFC 7049, Concise Binary Object Representation (CBOR), October 2013 26 https://www.rfc-editor.org/info/rfc7049
27 IETF RFC 7159, The JavaScript Object Notation (JSON) Data Interchange Format, March 2014 28 https://www.rfc-editor.org/info/rfc7159
29 JSON Schema Core, JSON Schema: core definitions and terminology, January 2013 30 http://json-schema.org/latest/json-schema-core.html
31 JSON Schema Validation, JSON Schema: interactive and non interactive validation, January 32 2013 33 http://json-schema.org/latest/json-schema-validation.html
34 JSON Hyper-Schema, JSON Hyper-Schema: A Vocabulary for Hypermedia Annotation of JSON, 35 October 2016 36 http://json-schema.org/latest/json-schema-hypermedia.html
37 OCF 1.0 Core Specification, Open Connectivity Foundation Core Specification, Version 1.0
38 OCF Security Specification, Open Connectivity Foundation Security Specification, Version 1.0
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 6
1 OCF ASA Mapping, OCF Resource to ASA Interface Mapping, v0.3 candidate, July 2016 2 https://workspace.openconnectivity.org/apps/org/workgroup/smarthome_tg/download.php/6287/O 3 CF_Resource_to_ASA_Interface_Mapping_v.0.3_candidate.docx
4 OIC 1.1 Core Specification, Open Interconnect Consortium Core Specification, Version 1.1
5 RAML Specification, Restful API modelling language, Version 0.8. 6 https://github.com/raml-org/raml-spec/blob/master/versions/raml-08/raml-08.md
7 3 Terms, definitions, symbols and abbreviations
8 3.1 Terms and definitions 9 3.1.1 10 OCF Bridge Device 11 An OCF Device that is capable of representing devices that exist on the network but communicate 12 using a Bridged Protocol rather than OCF protocols.
OCF Bridge Device
Virtual Virtual OCF OCF Bridged Bridged OCF Bridged Server Protocol Protocol Client Client Translator Server
Virtual Virtual OCF OCF Bridged Bridged OCF Bridged Client Protocol Protocol Server Server Client
13 14 15 Figure 1. OCF Bridge Device Components 16 3.1.2 17 Bridged Protocol 18 another protocol (e.g., AllJoyn) that is being translated to or from OCF protocols
19 3.1.3 20 Translator 21 an OCF Bridge Device component that is responsible for translating to or from a specific Bridged 22 Protocol. More than one translator can exist on the same OCF Bridge Device, for different Bridged 23 Protocols.
24 3.1.4 25 OCF Client 26 a logical entity that accesses an OCF Resource on an OCF Server, which might be a Virtual OCF 27 Server exposed by the OCF Bridge Device.
28 3.1.5 29 Bridged Client 30 a logical entity that accesses data via a Bridged Protocol. For example, an AllJoyn Consumer 31 application is a Bridged Client.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 7
1 3.1.6 2 Virtual OCF Client 3 a logical representation of a Bridged Client, which an OCF Bridge Device exposes to OCF Servers.
4 3.1.7 5 Virtual Bridged Client 6 a logical representation of an OCF Client, which an OCF Bridge Device exposes to Bridged Servers.
7 3.1.8 8 OCF Device 9 a logical entity that assumes one or more OCF roles (OCF Client, OCF Server). More than one 10 OCF Device can exist on the same physical platform.
11 3.1.9 12 Virtual OCF Server 13 a logical representation of a Bridged Server, which an OCF Bridge Device exposes to OCF Clients.
14 3.1.10 15 Bridged Server 16 a logical entity that provides data via a Bridged Protocol. For example, an AllJoyn Producer is a 17 Bridged Server. More than one Bridged Server can exist on the same physical platform.
18 3.1.11 19 Virtual Bridged Server 20 a logical representation of an OCF Server, which an OCF Bridge Device exposes to Bridged Clients.
21 3.1.12 22 OCF Resource 23 represents an artifact modelled and exposed by the OCF Framework
24 3.1.13 25 Virtual OCF Resource 26 a logical representation of a Bridged Resource, which an OCF Bridge Device exposes to OCF 27 Clients.
28 3.1.14 29 Bridged Resource 30 represents an artifact modelled and exposed by a Bridged Protocol. For example, an AllJoyn 31 object is a Bridged Resource.
32 3.1.15 33 OCF Resource Property 34 a significant aspect or notion including metadata that is exposed through the OCF Resource
35 3.1.16 36 OCF Resource Type 37 an OCF Resource Property that represents the data type definition for the OCF Resource
38 3.1.17 39 Bridged Resource Type 40 a schema used with a Bridged Protocol. For example, AllJoyn Interfaces are Bridged Resource 41 Types. 42 3.1.18 43 OCF Server 44 a logical entity with the role of providing resource state information and allowing remote control of 45 its resources.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 8
1 3.1.19 2 Onboarding Tool 3 defined by the OCF Security Specification as: A logical entity within a specific IoT network that 4 establishes ownership for a specific device and helps bring the device into operational state within 5 that network.
6 3.1.20 7 Bridged Device 8 a Bridged Client or Bridged Server.
9 3.1.21 10 Virtual OCF Device 11 a Virtual OCF Client or Virtual OCF Server.
12 3.2 Symbols and abbreviations 13 3.2.1 14 CRUDN 15 Create Read Update Delete Notify 16 indicating which operations are possible on the resource
17 3.2.2 18 CSV 19 Comma Separated Value List 20 construction to have more fields in 1 string separated by commas. If a value contains a comma, 21 then the comma can be escaped by adding “\” in front of the comma.
22 3.2.3 23 OCF 24 Open Connectivity Foundation 25 organization that created these specifications
26 3.2.4 27 RAML 28 RESTful API Modeling Language 29 Simple and succinct way of describing practically RESTful APIs (see the RAML Specification)
30 3.3 Conventions 31 In this specification a number of terms, conditions, mechanisms, sequences, parameters, events, 32 states, or similar terms are printed with the first letter of each word in uppercase and the rest 33 lowercase (e.g., Network Architecture). Any lowercase uses of these words have the normal 34 technical English meaning.
35 4 Document conventions and organization
36 For the purposes of this document, the terms and definitions given in the OCF 1.0 Core 37 Specification apply.
38 4.1 Notation 39 In this document, features are described as required, recommended, allowed or DEPRECATED as 40 follows:
41 Required (or shall or mandatory).
42 – These basic features shall be implemented to comply with this specification. The phrases “shall 43 not”, and “PROHIBITED” indicate behaviour that is prohibited, i.e. that if performed means the 44 implementation is not in compliance.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 9
1 Recommended (or should).
2 – These features add functionality supported by this specification and should be implemented. 3 Recommended features take advantage of the capabilities of this specification, usually without 4 imposing major increase of complexity. Notice that for compliance testing, if a recommended 5 feature is implemented, it shall meet the specified requirements to be in compliance with these 6 guidelines. Some recommended features could become requirements in the future. The phrase 7 “should not” indicates behaviour that is permitted but not recommended. 8 Allowed (or allowed).
9 – These features are neither required nor recommended, but if the feature is implemented, it 10 shall meet the specified requirements to be in compliance with these guidelines. 11 Conditionally allowed (CA)
12 – The definition or behaviour depends on a condition. If the specified condition is met, then the 13 definition or behaviour is allowed, otherwise it is not allowed. 14 Conditionally required (CR)
15 – The definition or behaviour depends on a condition. If the specified condition is met, then the 16 definition or behaviour is required. Otherwise the definition or behaviour is allowed as default 17 unless specifically defined as not allowed. 18 DEPRECATED
19 – Although these features are still described in this specification, they should not be implemented 20 except for backward compatibility. The occurrence of a deprecated feature during operation of 21 an implementation compliant with the current specification has no effect on the 22 implementation’s operation and does not produce any error conditions. Backward compatibility 23 may require that a feature is implemented and functions as specified but it shall never be used 24 by implementations compliant with this specification. 25 Strings that are to be taken literally are enclosed in “double quotes”.
26 Words that are emphasized are printed in italic. 27 4.2 Data types 28 Data types are defined in the OCF 1.0 Core Specification.
29 4.3 Document structure 30 Section 5 discusses operational scenarios. Section 6 covers generic requirements for any OCF 31 Bridge, and section 7 covers the specific requirements for a Bridge that translates to/from AllJoyn. 32 These are covered separately in order to ease the task of defining translation to other protocols in 33 the future.
34 5 Operational Scenarios
35 The overall goals are to:
36 1. make Bridged Servers appear to OCF clients as if they were native OCF servers, and
37 2. make OCF servers appear to Bridged Clients as if they were native non-OCF servers
38 5.1 “Deep translation” vs. “on-the-fly” 39 When translating a service between a Bridged Protocol (e.g., AllJoyn) and OCF protocols, there 40 are two possible types of translation. Translators are expected to dedicate most of their logic to 41 “deep translation” types of communication, in which data models used with the Bridged Protocol
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 10
1 are mapped to the equivalent OCF Resource Types and vice-versa, in such a way that a compliant 2 OCF Client or Bridged Client would be able to interact with the service without realising that a 3 translation was made.
4 “Deep translation” is out of the scope of this document, as the procedure far exceeds mapping of 5 types. For example, clients on one side of a translator may decide to represent an intensity as an 6 8-bit value between 0 and 255, whereas the devices on the other may have chosen to represent 7 that as a floating-point number between 0.0 and 1.0. It’s also possible that the procedure may 8 require storing state in the translator. Either way, the programming of such translation will require 9 dedicated effort and study of the mechanisms on both sides.
10 The other type of translation, the “on-the-fly” or “one-to-one” translation, requires no prior 11 knowledge of the device-specific schema in question on the part of the translator. The burden is, 12 instead, on one of the other participants in the communication, usually the client application. That 13 stems from the fact that “on-the-fly” translation always produces Bridged Resource Types and OCF 14 Resource Types as vendor extensions.
15 For AllJoyn, deep translation is specified in OCF ASA Mapping, and on-the-fly translation is 16 covered in section 7.2 of this document. 17 5.2 Use of introspection 18 Whenever possible, the translation code should make use of metadata available that indicates 19 what the sender and recipient of the message in question are expecting. For example, devices that 20 are AllJoyn Certified are required to carry the introspection data for each object and interface they 21 expose. The OIC 1.1 Core Specification makes no such requirement, but the OCF 1.0 Core 22 Specification does. When the metadata is available, translators should convert the incoming 23 payload to exactly the format expected by the recipient and should use information when 24 translating replies to form a more useful message.
25 For example, for an AllJoyn translator, the expected interaction list is presented on the list below: Message Type Sender Receiver Metadata Request AllJoyn 16.10 OIC 1.1 Not available Request AllJoyn 16.10 OCF 1.0 Available Request OIC 1.1 or OCF 1.0 AllJoyn 16.10 Available Response AllJoyn 16.10 OIC 1.1 or OCF 1.0 Available Response OIC 1.1 AllJoyn 16.10 Not available Response OCF 1.0 AllJoyn 16.10 Available
26 5.3 Stability and loss of data 27 Round-tripping through the translation process specified in this document is not expected to 28 reproduce the same original message. The process is, however, designed not to lose data or 29 precision in messages, though it should be noted that both OCF and AllJoyn payload formats allow 30 for future extensions not taken into account in this document.
31 However, a third round of translation should produce the same identical message as was 32 previously produced, provided the same information is available. That is to say, in the following 33 chain, payloads 2 and 4 as well as 3 and 5 should be identical.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 11
1 6 OCF Bridge Device
2 This section describes the functionality of an OCF Bridge Device; such a device is illustrated in 3 Figure 2.
4 An OCF Bridge Device is a device that represents one or more Bridged Devices as Virtual OCF 5 Devices on the network and/or represents one or more OCF Devices as Virtual Devices using 6 another protocol on the network. The Bridged Devices themselves are out of the scope of this 7 document. The only difference between a native OCF Device and a Virtual Bridged Device is how 8 the device is encapsulated in an OCF Bridge Device.
9 An OCF Bridge Device shall be indicated on the OCF network with a Device Type of “oic.d.bridge”. 10 This provides to an OCF Client an explicit indication that the discovered Device is performing a 11 bridging function. This is useful for a number of reasons; 1) when establishing a home network 12 the Client can determine that the bridge is reachable and functional when no bridged devices are 13 present, 2) allows for specific actions to be performed on the bridge taking into account the known 14 functionality a bridge supports, 3) should the bridged devices be subject to a progressive reveal it 15 enables user indications to be provided showing that sequence of discovery, 4) allows for explicit 16 discovery of all devices that are serving a bridging function which benefits trouble shooting and 17 maintenance actions on behalf of a user. When such a device is discovered the exposed Resources 18 on the OCF Bridge Device describe other devices. For example, as shown in Figure 2.
OCF facing Bridged Devices
OCF Bridge Device
Fan Virtual OCF Server 1 (oic.d.fan) Virtual OCF Server 2 (oic.d.light) Light 1 Virtual OCF Server 3 (oic.d.light) Light 2
19
20 Figure 2: Schematic overview of an OCF Bridge Device bridging non-OCF devices 21 It is expected that the OCF Bridge Device creates a set of devices during the start-up of the OCF 22 Bridge Device. The exposed set of Virtual OCF Devices can change as Bridged Devices are added 23 or removed from the bridge. The adding and removing of Bridged Devices is implementation 24 dependent. When an OCF Bridge Device changes the set of exposed Virtual OCF Devices, it shall 25 notify any OCF Clients subscribed to its “/oic/res”.
26 6.1 Resource Discovery 27 An OCF Bridge Device shall detect devices that arrive and leave the Bridged network or the OCF 28 network. Where there is no pre-existing mechanism to reliably detect the arrival and departure of 29 devices on a network, an OCF Bridge Device shall periodically poll the network to detect arrival
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 12
1 and departure of devices, for example using COAP multicast discovery (a multicast RETRIEVE of 2 “/oic/res”) in the case of the OCF network. OCF Bridge Device implementations are encouraged to 3 use a poll interval of 30 seconds plus or minus a random delay of a few seconds.
4 An OCF Bridge Device shall respond to network discovery commands on behalf of the exposed 5 bridged devices. All bridged devices with all their Resources shall be listed in “/oic/res” of the 6 Bridge. The response to a RETRIEVE on “/oic/res” shall only include the devices that match the 7 RETRIEVE request.
8 The resource reference determined from each Link exposed by “/oic/res” on the Bridge shall be 9 unique. The Bridge shall meet the requirements defined in the OCF 1.0 Core Specification for 10 population of the Properties and Link parameters in “/oic/res”.
11 For example, if an OCF Bridge Device exposes Virtual OCF Servers for the fan and lights shown 12 in Figure 2, the bridge might return the following information corresponding to the JSON below to a 13 legacy OIC 1.1 client doing a RETRIEVE on “/oic/res”. (Note that what is returned is not in the 14 JSON format but in a suitable encoding as defined in the OCF 1.0 Core Specification.) 15 16 [ 17 { 18 "di": "e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 19 "links": [ 20 { 21 "href": "coap://[fe80::b1d4]:55555/oic/res", 22 "rel": "self", 23 "rt": "oic.wk.res", 24 "if": ["oic.if.ll", "oic.if.baseline"], 25 "p": {"bm": 3, "sec": true, "port": 11111} 26 }, 27 { 28 "href": "/oic/p", 29 "rt": ["oic.wk.p"], 30 "if": ["oic.if.r", "oic.if.baseline"], 31 "p": {"sec": true, "port": 11111} 32 }, 33 { 34 "href": "/oic/d", 35 "rt": ["oic.wk.d", "oic.d.bridge"], 36 "if": ["oic.if.r", "oic.if.baseline"], 37 "p": {"sec": true, "port": 11111} 38 }, 39 { 40 "href": "/mySecureMode", 41 "rt": ["oic.r.securemode"], 42 "if": ["oic.if.rw", "oic.if.baseline"], 43 "p": {"sec": true, "port": 11111} 44 } 45 ] 46 }, 47 { 48 "di": "88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 49 "links": [ 50 { 51 "anchor": "coaps://[fe80::b1d4]:22222", 52 "href": "/oic/p", 53 "rt": ["oic.wk.p"], 54 "if": ["oic.if.r", "oic.if.baseline"] 55 }, 56 { 57 "anchor": "coaps://[fe80::b1d4]:22222", 58 "href": "/oic/d",
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 13
1 "rt": ["oic.wk.d", "oic.d.fan"], 2 "if": ["oic.if.r", "oic.if.baseline"] 3 }, 4 { 5 "anchor": "coaps://[fe80::b1d4]:22222", 6 "href": "/myFan", 7 "rt": ["oic.r.switch.binary"], 8 "if": ["oic.if.a", "oic.if.baseline"] 9 } 10 ] 11 }, 12 { 13 "di": "dc70373c-1e8d-4fb3-962e-017eaa863989", 14 "links": [ 15 { 16 "anchor": "coaps://[fe80::b1d4]:33333", 17 "href": "/oic/p", 18 "rt": ["oic.wk.p"], 19 "if": ["oic.if.r", "oic.if.baseline"] 20 }, 21 { 22 "anchor": "coaps://[fe80::b1d4]:33333", 23 "href": "/oic/d", 24 "rt": ["oic.wk.d", "oic.d.light"], 25 "if": ["oic.if.r", "oic.if.baseline"] 26 }, 27 { 28 "anchor": "coaps://[fe80::b1d4]:33333", 29 "href": "/myLight", 30 "rt": ["oic.r.switch.binary"], 31 "if": ["oic.if.a", "oic.if.baseline"] 32 } 33 ] 34 }, 35 { 36 "di": "2983844a-5893-468b-bac93957ddf7", 37 "links": [ 38 { 39 "anchor": "coaps://[fe80::b1d4]:44444", 40 "href": "/oic/p", 41 "rt": ["oic.wk.p"], 42 "if": ["oic.if.r", "oic.if.baseline"] 43 }, 44 { 45 "anchor": "coaps://[fe80::b1d4]:44444", 46 "href": "/oic/d", 47 "rt": ["oic.wk.d", "oic.d.light"], 48 "if": ["oic.if.r", "oic.if.baseline"] 49 }, 50 { 51 "anchor": "coaps://[fe80::b1d4]:44444", 52 "href": "/myLight", 53 "rt": ["oic.r.switch.binary"], 54 "if": ["oic.if.a", "oic.if.baseline"] 55 } 56 ] 57 }, 58 ]
59 The above example illustrates that each Virtual OCF Server has its own “di” and endpoint exposed 60 by the bridge, and that “/oic/p” and “/oic/d” are available for each Virtual OCF Server. 61
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 14
1 When an OCF Client requests a content format of “application/vnd.ocf+cbor”, the same bridge will return 2 information corresponding to the JSON below. (Note that what is returned is not in the JSON format but in 3 a suitable encoding as defined in the OCF 1.0 Core Specification.) 4 5 [ 6 { 7 "href": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9/oic/res", 8 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 9 "rel": "self", 10 "rt": "oic.wk.res", 11 "if": ["oic.if.ll", "oic.if.baseline"], 12 "eps": [{"ep": "coap://[fe80::b1d4]:55555"}, 13 {"ep": "coaps://[fe80::b1d4]:11111"}], 14 "p": {"bm": 3} 15 }, 16 { 17 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 18 "href": "/oic/p", 19 "rt": ["oic.wk.p"], 20 "if": ["oic.if.r", "oic.if.baseline"], 21 "eps": [{"ep": "coaps://[fe80::b1d4]:11111"}] 22 }, 23 { 24 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 25 "href": "/oic/d", 26 "rt": ["oic.wk.d", "oic.d.bridge"], 27 "if": ["oic.if.r", "oic.if.baseline"], 28 "eps": [{"ep": "coaps://[fe80::b1d4]:11111"}] 29 }, 30 { 31 "anchor": "ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9", 32 "href": "/mySecureMode", 33 "rt": ["oic.r.securemode"], 34 "if": ["oic.if.rw", "oic.if.baseline"], 35 "eps": [{"ep": "coaps://[fe80::b1d4]:11111"}] 36 } 37 38 39 { 40 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 41 "href": "/oic/p", 42 "rt": ["oic.wk.p"], 43 "if": ["oic.if.r", "oic.if.baseline"], 44 "eps": [{"ep": "coaps://[fe80::b1d4]:22222"}] 45 }, 46 { 47 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 48 "href": "/oic/d", 49 "rt": ["oic.wk.d", "oic.d.fan"], 50 "if": ["oic.if.r", "oic.if.baseline"], 51 "eps": [{"ep": "coaps://[fe80::b1d4]:22222"}] 52 }, 53 { 54 "anchor": "ocf://88b7c7f0-4b51-4e0a-9faa-cfb439fd7f49", 55 "href": "/myFan", 56 "rt": ["oic.r.switch.binary"], 57 "if": ["oic.if.a", "oic.if.baseline"], 58 "eps": [{"ep": "coaps://[fe80::b1d4]:22222"}] 59 }, 60 61 62 {
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 15
1 "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 2 "href": "/oic/p", 3 "rt": ["oic.wk.p"], 4 "if": ["oic.if.r", "oic.if.baseline"], 5 "eps": [{"ep": "coaps://[fe80::b1d4]:33333"}] 6 }, 7 { 8 "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 9 "href": "/oic/d", 10 "rt": ["oic.wk.d", "oic.d.light"], 11 "if": ["oic.if.r", "oic.if.baseline"], 12 "eps": [{"ep": "coaps://[fe80::b1d4]:33333"}] 13 }, 14 { 15 "anchor": "ocf://dc70373c-1e8d-4fb3-962e-017eaa863989", 16 "href": "/myLight", 17 "rt": ["oic.r.switch.binary"], 18 "if": ["oic.if.a", "oic.if.baseline"], 19 "eps": [{"ep": "coaps://[fe80::b1d4]:33333"}] 20 }, 21 22 23 { 24 "anchor": "ocf://2983844a-5893-468b-bac93957ddf7", 25 "href": "/oic/p", 26 "rt": ["oic.wk.p"], 27 "if": ["oic.if.r", "oic.if.baseline"], 28 "eps": [{"ep": "coaps://[fe80::b1d4]:44444"}] 29 }, 30 { 31 "anchor": "ocf://2983844a-5893-468b-bac93957ddf7", 32 "href": "/oic/d", 33 "rt": ["oic.wk.d", "oic.d.light"], 34 "if": ["oic.if.r", "oic.if.baseline"], 35 "eps": [{"ep": "coaps://[fe80::b1d4]:44444"}] 36 }, 37 { 38 "anchor": "ocf://2983844a-5893-468b-bac93957ddf7", 39 "href": "/myLight", 40 "rt": ["oic.r.switch.binary"], 41 "if": ["oic.if.a", "oic.if.baseline"], 42 "eps": [{"ep": "coaps://[fe80::b1d4]:44444"}] 43 } 44 ]
45 6.2 General Requirements 46 47 The translator shall check the protocol-independent UUID of each device and shall not advertise 48 back into a Bridged Protocol a device originally seen via that Bridged Protocol. The translator 49 shall stop translating any Bridged Protocol device exposed in OCF via another translator if the 50 translator sees the device via the Bridged Protocol. Similarly, the translator shall not advertise an 51 OCF Device back into OCF, and the translator shall stop translating any OCF device exposed in 52 the Bridged Protocol via another translator if the translator sees the device via OCF. These require 53 that the translator can determine when a device is already being translated. A Virtual OCF Device 54 shall be indicated on the OCF network with a Device Type of “oic.d.virtual”. This allows translators 55 to determine if a device is already being translated when multiple translators are present. How a 56 translator determines if a device is already being translated on a non-OCF network is described in 57 the protocol-specific sections below. 58
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 16
1 Each Bridged Server shall be exposed as a separate Virtual OCF Server, with its own endpoint, 2 and its own “/oic/d” and “/oic/p”. The Virtual OCF Server’s “/oic/res” resource would be the same 3 as for any ordinary OCF Server that uses a resource directory. That is, it does not respond to 4 multicast discovery requests (because the OCF Bridge Device responds on its behalf), but a 5 unicast query elicits a response listing its own resources with a “rel”=“hosts” relationship, and an 6 appropriate “anchor” to indicate that it is not the OCF Bridge Device itself. This allows platform- 7 specific, device-specific, and resource-specific fields to all be preserved across translation. 8 6.3 Security 9 The OCF Bridge Device shall go through OCF ownership transfer as any other onboardee would. 10 Separately, it shall go through the Bridged Protocol’s ownership transfer mechanism (e.g., AllJoyn 11 claiming) normally as any other onboardee would. 12 13 The OCF Bridge Device shall be field updatable. (This requirement need not be tested but can 14 be certified via a vendor declaration.) 15 16 Unless an administrator opts in to allow it (see section 9.2), a translator shall not expose 17 connectivity to devices that it cannot get a secure connection to. 18 Each Virtual OCF Device shall be provisioned for security by an OCF Onboarding tool. Each Virtual 19 Bridged Device should be provisioned as appropriate in the Bridged ecosystem. In other words, 20 Virtual Devices are treated the same way as physical Devices. They are entities that have to be 21 provisioned in their network.
22 The Translator shall provide a “piid” value that can be used to correlate a non-OCF Device with its 23 corresponding Virtual OCF Device, as specified in Section 6.2. An Onboarding Tool might use this 24 correlation to improve the Onboarding user experience by eliminating or reducing the need for user 25 input, by automatically creating security settings for Virtual OCF Devices that are equivalent to the 26 security settings of their corresponding non-OCF Devices. See the OCF Security Specification for 27 detailed information about Onboarding. 28 Each Virtual Device shall implement the security requirements of the ecosystem that it is connected 29 to. For example, each Virtual OCF Device shall implement the behaviour required by the OCF 1.0 30 Core Specification and the OCF Security Specification. Each Virtual OCF Device shall perform 31 authentication, access control, and encryption according to the security settings it received from 32 the Onboarding Tool.
33 Depending on the architecture of the Translator, authentication and access control might take 34 place just within each ecosystem, but not within the Translator. For example, when an OCF Client 35 sends a request to a Virtual OCF Server:
36 - Authentication and access control might be performed by the Virtual OCF Server, when 37 receiving the request from the OCF Client 38 - The Translator might not perform authentication or access control when the request travels 39 through the Translator to the corresponding Virtual Bridged Client 40 - Authentication and access control might be performed by the target Bridged Server, when 41 it receives the request from the Virtual Bridged Client, according to the security model of 42 the Bridged ecosystem
43 A Translator may receive unencrypted data coming from a Bridged Client, through a Virtual Bridged 44 Device. The translated message shall be encrypted by the corresponding Virtual OCF Client, 45 before sending it to the target OCF Device, if this OCF Device requires encryption
46 A Translator may receive unencrypted data coming from an OCF Client, through a Virtual OCF 47 Server. After translation, this data shall be encrypted by the corresponding Virtual Bridged Client, 48 before sending it to the target Bridged Server, if this Bridged Server requires encryption.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 17
1 A Translator shall protect the data while that data travels between a Virtual Client and a Virtual 2 Server, through the Translator. For example, if the Translator sends data over a network, the 3 Translator shall perform appropriate authentication and access control, and shall encrypt the data, 4 between all peers involved in this communication.
5 Blocking communication of Bridged Devices with the OCF ecosystem 6 An OCF Onboarding Tool shall be able to block the communication of all OCF Devices with all 7 Bridged Devices that don’t communicate securely with the Bridge, by using the Bridge 8 Device’s ”oic.r.securemode” Resource.
9 In addition, an OCF Onboarding Tool can block the communication of a particular Virtual OCF 10 Client with all OCF Servers, or block the communication of all OCF Clients with a particular Virtual 11 OCF Server, in the same way as it would for any other OCF Device. See section 8.5 of the OCF 12 Security Specification for information about the soft reset state.
13 7 AllJoyn Translation
14 7.1 Requirements Specific to an AllJoyn Translator 15 The translator shall be an AllJoyn Router Node. (This is a requirement so that users can expect 16 that a certified OCF Bridge Device will be able to talk to any AllJoyn device, without the user having 17 to buy some other device.) 18 The requirements in this section apply when using algorithmic translation, and by default apply to 19 deep translation unless the relevant specification for such deep translation specifies otherwise.
20 Exposing AllJoyn producer devices to OCF Clients 21 As specified in the OCF Security Specification, the value of the “di” property of OCF Devices 22 (including Virtual OCF Devices) shall be established as part of Onboarding of that Virtual OCF 23 Device. 24 25 Each AllJoyn object shall be mapped to one or more Virtual OCF Resources. If all AllJoyn 26 interfaces can be translated to resource types on the same resource (as discussed below), there 27 should be a single Virtual OCF Resource, and the path component of the URI of the Virtual OCF 28 Resource shall be the AllJoyn object path. Otherwise, a Resource with that path shall exist with a 29 Resource type of [“oic.wk.col”, “oic.r.alljoynobject”] which is a Collection of links, where 30 “oic.r.alljoynobject” is defined in Section 9.3, and the items in the collection are the Resources with 31 the translated Resource Types as discussed below. 32 33 The value of the “piid” property of “/oic/d” for each Virtual OCF Device shall be the value of the 34 OCF-defined AllJoyn field “org.openconnectivity.piid” in the AllJoyn About Announce signal, if that 35 field exists, else it shall be calculated by the Translator as follows: 36 37 • If the AllJoyn device supports security, the value of the “piid” property value shall be the 38 peer GUID. 39 • If the AllJoyn device does not support security but the device is being bridged anyway (see 40 section 9.2), the “piid” property value shall be derived from the DeviceId and AppId 41 properties (in the About data), by concatenating the DeviceId value (not including any null 42 termination) and the AppId bytes and using the result as the “name” to be used in the 43 algorithm specified in IETF RFC 4122 section 4.3, with SHA-1 as the hash algorithm, and 44 8f0e4e90-79e5-11e6-bdf4-0800200c9a66 as the name space ID. (This is to address the 45 problem of being able to de-duplicate AllJoyn devices exposed via separate OCF Bridge 46 Devices.)
47 A translator implementation is encouraged to listen for AllJoyn About Announce signals matching 48 any AllJoyn interface name. It can maintain a cache of information it received from these signals,
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 18
1 and use the cache to quickly handle “/oic/res” queries from OCF Clients (without having to wait for 2 Announce signals while handling the queries). 3 4 A translator implementation is encouraged to listen for other signals (including 5 EmitsChangedSignal of properties) only when there is a client subscribed to a corresponding 6 resource on a Virtual AllJoyn Device. 7 8 There are multiple types of AllJoyn interfaces, which shall be handled as follows. 9 • If the AllJoyn interface is in a well-defined set (defined in OCF ASA Mapping or section 10 7.1.1.1 below) of interfaces where standard forms exist on both the AllJoyn and OCF 11 sides, the translator shall either: 12 a. follow the specification for translating that interface specially, or 13 b. not translate the AllJoyn interface. 14 • If the AllJoyn interface is not in the well-defined set, the translator shall either: 15 a. not translate the AllJoyn interface, or 16 b. algorithmically map the AllJoyn interface as specified in section 7.2 to 17 custom/vendor-defined Resource Types by converting the AllJoyn interface 18 name to OCF resource type name(s). 19
20 An AllJoyn interface name shall be converted to a Device Type or a set of one or more OCF 21 Resource Types as follows: 22 1) If the AllJoyn interface has any members, append a suffix “.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 19
1 Observable. The Version property in an AllJoyn interface is always considered “const”, 2 even if not specified in introspection XML. 3 • Resource Types mapping AllJoyn Properties with access “readwrite” shall support the 4 “oic.if.rw” Interface. Resource Types mapping AllJoyn Properties with access “read” shall 5 support the “oic.if.r” Interface. Resource Types supporting both the “oic.if.rw” and “oic.if.r” 6 Interfaces shall choose “oic.if.r” as the default Interface. 7 • Each AllJoyn Method is mapped to a separate Resource Type, where the value of the 8
44 When an algorithmic mapping is used, AllJoyn data types shall be mapped to OCF property types 45 according to Section 7.2. 46 47 If an AllJoyn operation fails, the translator shall send an appropriate OCF error response to the 48 OCF client. If an AllJoyn error name is available, it shall construct an appropriate OCF error 49 message (e.g., diagnostic payload if using CoAP) from the AllJoyn error name and AllJoyn error 50 message (if any), using the form "
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 20
1 is present. If the resulting error name is of the form "<#>" where <#> is an error code without a 2 decimal (e.g., “404"), the error code shall be the error code indicated by the error name. Example: 3 “org.openconnectivity.Error.404" becomes “404", which shall result in an error 4.04 for a CoAP 4 transport.
5 7.1.1.1 Exposing an AllJoyn producer application as a Virtual OCF Server 6 Table 1 shows how OCF Device properties, as specified in Table 20 in the OCF 1.0 Core 7 Specification, shall be derived, typically from fields specified in the AllJoyn About Interface 8 Specification and AllJoyn Configuration Interface Specification. 9 10 Table 1: oic.wk.d resource type definition To OCF OCF OCF Description OCF From AJ Field name AJ Description AJ Mand? Property Propert Mand title y name ? (Device) n Human friendly Y AppName Application name Y Name name (no exact equivalent assigned by the For example, exists) app manufacturer “Bob’s Thermostat” (developer or the OEM). Spec lcv Spec version of the Y (none) Translator should Version core specification this return its own value device is implemented to, The syntax is "core.major.minor”]
Device ID di Unique identifier for Y (none) Use as defined in Device. This value the OCF Security shall be as defined in Specification [OCF Security] for DeviceID. Protocol- piid Unique identifier for Y org.openconnectivity. Peer GUID: The Peer Independe OCF Device (UUID) piid if it exists, else peer GUID is the GUID: nt ID “Peer GUID” (not in only persistent conditional About, but exposed identity for a peer. ly Y by protocol) if Peer GUIDs are authenticated, else used by the DeviceId: Hash(DeviceId,AppId authentication Y ) where the Hash is mechanisms to done by uniquely and AppId: Y concatenating the identify a remote Device Id (not application including any null instance. The peer terminator) and the GUID for a remote AppId and using the peer is only algorithm in available if the IETF RFC 4122 remote peer has section 4.3, with been authenticated. SHA-1. DeviceId: Device This means that the identifier set by value of di may platform-specific change if the means. resource is read both before and after AppId: A 128-bit authentication, in globally unique order to mitigate identifier for the privacy concerns application. The discussed in RFC AppId shall be a 6973. universally unique identifier as specified in IETF RFC 4122. Data Model dmv Spec version(s) of the Y Comma separated list This specification N, but Version vertical specifications of the Version assumes that the required this device data property values of value of the by IRB for
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 21
model is implemented each interface listed Version property is all to. The syntax is a in the the same as the standard comma separated list objectDescription value of the interfaces, of argument of the "org.gtk.GDBus.Sin and "
Note that AllJoyn specifies that the default value is 1 if the "org.gtk.GDBus.Sin ce" annotation is absent. Localized ld Detailed description N Description Detailed Y Description of the Device, in one description s or more languages. expressed in This property is an language tags as in array of objects RFC 5646. where each object has a ‘language’ field (containing an RFC 5646 language tag) and a ‘value’ field containing the device description in the indicated language. Software sv Version of the device N SoftwareVersion Software version of Y Version software. the app. Manufactur dmn Name of N Manufacturer The manufacturer's Y er Name manufacturer of the name of the app. Device, in one or more languages. This property is an array of objects where each object has a ‘language’ field (containing an RFC 5646 language tag) and a ‘value’ field containing the manufacturer name in the indicated language. Model dmno Model number as N ModelNumber The app model Y Number designated by number. manufacturer. 1 2 In addition, any additional vendor-defined fields in the AllJoyn About data shall be mapped to 3 vendor-defined properties in the OCF core resource “/oic/d” (which implements the “oic.wk.d” 4 resource type), with a property name formed by prepending “x.” to the AllJoyn field name. 5 6 Table 2 shows how configurable OCF Device properties, as specified in Table 15 in the OCF 1.0 7 Core Specification, shall be derived: 8 9 Table 2: oic.wk.con resource type definition To OCF OCF OCF Description OCF From AJ Field name AJ Description AJ Property Property Mand? Mand? title name
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 22
(Device) n Human friendly Y AppName Application name Y Name name (no exact equivalent assigned by the For example, exists) app manufacturer “Bob’s (developer or the Thermostat” OEM). Location loc Provides location N org.openconnectivity.loc N information where (if it exists, else property available. shall be absent) Location locn Human friendly N org.openconnectivity.locn N Name name for location (if it exists, else property For example, shall be absent) “Living Room”. Currency c Indicates the N org.openconnectivity.c (if N currency that is it exists, else property used for any shall be absent) monetary transactions Region r Free form text N org.openconnectivity.r (if N Indicating the it exists, else property current region in shall be absent) which the device is located geographically. The free form text shall not start with a quote ("). Localized ln Human-friendly N AppName Application name Y Names name of the assigned by the Device, in one or app manufacturer more languages. (developer or the This property is an OEM). array of objects where each object has a ‘language’ field (containing an RFC 5646 language tag) and a ‘value’ field containing the device name in the indicated language. If this property and the Device Name (n) property are both supported, the Device Name (n) value shall be included in this array. Default dl The default N DefaultLanguage The default Y Language language language supported by the supported by the Device, specified device. Specified as an RFC 5646 as an IETF language tag. By language tag default, clients listed in RFC can treat any 5646. string property as being in this language unless the property specifies otherwise. 1 2 In addition, any additional vendor-defined fields in the AllJoyn Configuration data shall be mapped 3 to vendor-defined properties in the OCF core resource “/oic/con” (which implements the
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 23
1 “oic.wk.con” resource type), with a property name formed by prepending “x.” to the AllJoyn field 2 name. 3 4 Table 3 shows how platform properties, as specified in Table 21 in the OCF 1.0 Core Specification, 5 are derived, typically from fields specified in the AllJoyn About Interface Specification and AllJoyn 6 Configuration Interface Specification. 7 8 Table 3: oic.wk.p Resource Type definition To OCF OCF OCF OCF From AJ Field name AJ AJ Property title Property Description Mand? Description Mand? name Platform ID pi Unique Y DeviceId if it is a UUID, Name of the Y identifier for the else generate a name- device set by physical based UUID from the platform- platform DeviceId using the specific means (UIUID); this DeviceId value (not (such as Linux shall be a UUID including any null and Android). in accordance termination) as the “name” with IETF RFC to be used in the algorithm 4122. It is specified in recommended IETF RFC 4122 section that the UUID 4.3, with SHA-1 as the be created hash algorithm, and using the 8f0e4e90-79e5-11e6-bdf4- random 0800200c9a66 as the generation name space ID. scheme (version 4 UUID) specific in the RFC. Manufacturer mnmn Name of Y Manufacturer The Y Name manufacturer (in DefaultLanguage, manufacturer's (not to exceed truncated to 16 name of the 16 characters) characters) app. Manufacturer mnml URL to N org.openconnectivity.mnml N Details Link manufacturer (if it exists, else property (URL) (not to exceed shall be absent) 32 characters) Model Number mnmo Model number N ModelNumber The app model Y as designated number. by manufacturer Date of mndt Manufacturing N DateOfManufacture Date of N Manufacture date of device manufacture using format YYYY-MM-DD (known as XML DateTime format). Platform mnpv Version of N org.openconnectivity.mnpv N Version platform – (if it exists, else property string (defined shall be absent) by manufacturer) OS Version mnos Version of N org.openconnectivity.mnos N platform (if it exists, else property resident OS – shall be absent) string (defined by manufacturer) Hardware mnhw Version of N HardwareVersion Hardware N Version platform version of the hardware device on which the app is running.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 24
Firmware mnfv Version of N org.openconnectivity.mnfv N version device firmware (if it exists, else property shall be absent) Support URL mnsl URL that points N SupportUrl Support URL N to support (populated by information the from manufacturer) manufacturer SystemTime st Reference time N org.openconnectivity.st (if N for the device it exists, else property shall be absent) Vendor ID vid Vendor defined N DeviceId Name of the Y string for the device set by platform. The platform- string is specific means freeform and up (such as Linux to the vendor and Android). on what text to populate it.
1 2 Table 4 shows how configurable OCF Platform properties, as specified in Table 16 in the OCF 1.0 3 Core Specification, shall be derived: 4 5 Table 4: oic.wk.con.p Resource Type definition To OCF OCF OCF OCF From AJ Field AJ Description AJ Property title Property Description Mand? name Mand? name Platform mnpn Platform N DeviceName Name of the Device Names Identifier device set by name platform- assigned specific means by the (such as Linux user. The and Android). device name appears on the UI as the friendly name of the device. 6 7 In addition, the oic.wk.mnt properties Factory_Reset and Reboot shall be mapped to AllJoyn 8 Configuration methods FactoryReset and Restart, respectively. 9 Exposing OCF resources to AllJoyn consumer applications 10 Unless specified otherwise, each OCF resource shall be mapped to a separate AllJoyn object. 11 12 Each OCF Server shall be exposed as a separate AllJoyn producer application, with its own About 13 data. This allows platform-specific, device-specific, and resource-specific fields to all be 14 preserved across translation. However, this requires that AllJoyn Claiming of such producer 15 applications be solved in a way that does not require user interaction, but this is left as an 16 implementation issue. 17 18 The AllJoyn producer application shall implement the “oic.d.virtual” AllJoyn interface. This allows 19 translators to determine if a device is already being translated when multiple translators are 20 present. The “oic.d.virtual” interface is defined as follows: 21 22
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 25
1 The AllJoyn peer ID shall be the OCF device ID (“di”). 2 3 Unless specified otherwise, the AllJoyn object path on the resource shall be the OCF URI path. 4 The AllJoyn About data shall be populated per Table 5 below. 5 6 A translator implementation is encouraged to maintain a cache of OCF resources to handle 7 WhoImplements queries from the AllJoyn side, and emit an Announce Signal for each OCF Server. 8 Specifically, the translator could always Observe “/oic/res” changes and only Observe other 9 resources when there is a client with a session on a Virtual AllJoyn Device. 10 11 There are multiple types of resources, which shall be handled as follows. 12 • If the Resource Type is in a well-defined set (defined in OCF ASA Mapping or section 13 7.1.2.1 below) of resource types where standard forms exist on both the AllJoyn and OCF 14 sides, the translator shall either: 15 a. follow the specification for translating that resource type specially, or 16 b. not translate the Resource Type. 17 • If the Resource Type is not in the well-defined set (but is not a Device Type), the translator 18 shall either: 19 a. not translate the Resource Type, or 20 b. algorithmically map the Resource Type as specified in section 7.2 to a 21 custom/vendor-defined AllJoyn interface by converting the OCF Resource Type 22 name to an AllJoyn Interface name. 23
24 An OCF Resource Type or Device Type name shall be converted to an AllJoyn interface name as 25 follows: 26 1) Remove the “x.” prefix if present 27 2) For each occurrence of a hyphen (in order from left to right in the string): 28 a. If the hyphen is followed by a letter, replace both characters with a single upper- 29 case version of that letter (e.g., convert “-a” to “A”). 30 b. Else, if the hyphen is followed by another hyphen followed by either a letter or a 31 hyphen, replace two hyphens with a single underscore (e.g., convert “--a" to “_a”). 32 c. Else, convert the hyphen to an underscore (i.e., convert “-” to “_”). 33 34 Some examples are shown in the table below. The first three are unusual OCF names 35 converted (perhaps back) to normal AllJoyn names. The last three are normal OCF names 36 converted to unusual AllJoyn names. (“xn--" is a normal domain name prefix for the Punycode- 37 encoded form of an Internationalized Domain Name, and hence can appear in a normal vendor- 38 specific OCF name.) 39 From OCF name To AllJoyn name x.example.-widget example.Widget x.example.my--widget example.my_widget x.example.-my---widget example.My_Widget x.xn--p1ai.example xn_p1ai.example x.xn--90ae.example xn__90ae.example x.example.my-name-1 example.myName_1 40 41 An OCF Device Type is mapped to an AllJoyn interface with no members. 42 43 Unless specified otherwise, each OCF Resource Type shall be mapped to an AllJoyn interface as 44 follows: 45 • Each OCF property is mapped to an AllJoyn property in that interface.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 26
1 • The EmitsChangedSignal value for each AllJoyn property shall be set to “true” if the 2 resource type supports NOTIFY, or “false” if it does not. (The value is never set to “const” 3 or “invalidates” since those concepts cannot currently be expressed in OCF.) 4 • The “access” attribute for each AllJoyn property shall be “read” if the OCF property is read- 5 only, or “readwrite” if the OCF property is read-write. 6 • If the resource supports DELETE, a Delete() method shall appear in the interface. 7 • If the resource supports CREATE, a Create() method shall appear in the interface, with 8 input arguments of each property of the resource to create. (Such information is not 9 available algorithmically in OIC 1.1, but can be determined in OCF 1.0 via introspection.) 10 If such information is not available, a CreateWithDefaultValues() method shall appear 11 which takes no input arguments. In either case, the output argument shall be an 12 OBJECT_PATH containing the path of the created resource. 13 • If the resource type supports UPDATE, then an AllJoyn property set (i.e., an 14 org.freedesktop.DBus.Properties.Set() method call) shall be mapped to a Partial UPDATE 15 (i.e., POST) with the corresponding OCF property. 16 • If a Resource has a Resource Type “oic.r.alljoynobject”, then instead of separately 17 translating each of the Resources in the collection to its own AllJoyn object, all Resources 18 in the collection shall instead be translated to a single AllJoyn object whose object path is 19 the OCF URI path of the collection.
20 OCF property types shall be mapped to AllJoyn data types according to Section 7.2. 21 22 If an OCF operation fails, the translator shall send an appropriate AllJoyn error response to the 23 AllJoyn consumer. If an error message is present in the OCF response, and the error message 24 (e.g., diagnostic payload if using CoAP) fits the pattern "
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 27
AJ From OCF OCF OCF Description OCF To AJ Field name AJ Description Mand? Property Property Mand? title name If absent, the translator shall return a constant, e.g., empty string
N Platform mnpn Friendly name of the N Names Platform. This property is an array of objects where each object has a Name of the ‘language’ field (containing device set by an RFC 5646 language DeviceName (per platform-specific tag) and a ‘value’ field supported language) means (such as containing the platform Linux and friendly name in the Android). indicated language.
For example, [{“language”:”en”, “value”:”Dave’s Laptop”}] Device identifier Y Platform ID pi Platform Identifier Y DeviceId set by platform- specific means. Y Localized ln Human-friendly name of N (ln), Names, if it or the Device, in one or more Y (n) exists, n languages. This property else is an array of objects (Device) where each object has a Name ‘language’ field (containing Application name an RFC 5646 language assigned by the AppName (per supported tag) and a ‘value’ field app manufacturer language) containing the device (developer or the name in the indicated OEM). language. If this property and the Device Name (n) property are both supported, the Device Name (n) value shall be included in this array. Y Manufacturer dmn Name of manufacturer of the N Name Device, in one or more languages. This property is an array of objects where The Manufacturer (per each object has a ‘language’ manufacturer's supported language) field (containing an RFC 5646 name of the app. language tag) and a ‘value’ field containing the manufacturer name in the indicated language. The app model Y Model dmno Model number as designated N ModelNumber number. Number by manufacturer Y language ln If ln is supported, return N fields of the list of values of the List of supported SupportedLanguages Localized language field of each languages. Names array element, else return empty array Y Localized ld Detailed description of the N Descriptions Device, in one or more Detailed languages. This property description Description (per supported is an array of objects expressed in language) where each object has a language tags as ‘language’ field (containing in RFC 5646.. an RFC 5646 language tag) and a ‘value’ field
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 28
AJ From OCF OCF OCF Description OCF To AJ Field name AJ Description Mand? Property Property Mand? title name containing the device description in the indicated language. Date of N Date of mndt Manufacturing date of device N manufacture Manufacture using format DateOfManufacture YYYY-MM-DD (known as XML DateTime format). Software version Y Software sv Software version of the N SoftwareVersion of the app. Version device. Current version of Y (none) Translator should return its the AllJoyn SDK own value AJSoftwareVersion used by the application. Hardware version N Hardware mnhw Version of platform hardware N of the device on Version HardwareVersion which the app is running. Support URL N Support URL mnsl URL that points to support N SupportUrl (populated by the information from manufacturer). manufacturer N Manufacturer mnml (if it URL to manufacturer (not to N Details Link exists, exceed 32 characters) org.openconnectivity.mnml (URL) else field shall be absent) N Platform mnpv (if it Version of platform – string N Version exists, (defined by manufacturer) org.openconnectivity.mnpv else field shall be absent) N OS Version mnos (if it Version of platform resident N exists, OS – string (defined by org.openconnectivity.mnos else field manufacturer) shall be absent) N Firmware mnfv (if it Version of device firmware N version exists, org.openconnectivity.mnfv else field shall be absent) N SystemTime st (if it Reference time for the device N exists, org.openconnectivity.st else field shall be absent) N Protocol- piid A unique and immutable Y Independent Device identifier. A Client can ID detect that a single Device supports multiple org.openconnectivity.piid communication protocols if it discovers that the Device uses a single Protocol Independent ID value for all the protocols it supports. 1 2 In addition, any additional vendor-defined properties in the OCF core resource “/oic/d” (which 3 implements the “oic.wk.d” resource type) and the OCF core resource “/oic/p” (which implements
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 29
1 the “oic.wk.p” resource type) shall be mapped to vendor-defined fields the AllJoyn About data, with 2 a field name formed by removing the leading “x.” from the property name. 3 4 Table 6 shows how AllJoyn Configuration Interface fields shall be derived, based on properties in 5 “oic.wk.con” or “oic.wk.con.p”. 6 7 Table 6: AllJoyn Configuration Data fields AJ From OCF OCF OCF Description OCF To AJ Field name AJ Description Mand? Property title Property Mand? name N Default dl The default language N Language supported by the Device, specified as an RFC 5646 Default language language tag. By default, DefaultLanguage supported by the clients can treat any string device. property as being in this language unless the property specifies otherwise.
N PlatformNames mnpn Friendly name of the N Platform. This property is an array of objects where each object has a Device name ‘language’ field (containing assigned by the an RFC 5646 language user. The device tag) and a ‘value’ field DeviceName name appears containing the platform on the UI as the friendly name in the friendly name of indicated language. the device.
For example, [{“language”:”en”, “value”:”Dave’s Laptop”}]
N Location loc (if it Provides location N exists, information where org.openconnectivity.loc else field available. shall be absent)
N Location Name locn (if it Human friendly name for N exists, location org.openconnectivity.locn else field For example, “Living shall be Room”. absent) N Currency c (if it Indicates the currency that is N exists, used for any monetary org.openconnectivity.c else field transactions shall be absent)
N Region r (if it Free form text Indicating N exists, the current region in which else field the device is located org.openconnectivity.r shall be geographically. The free absent) form text shall not start with a quote (").
8 9 In addition, the Configuration methods FactoryReset and Restart shall be mapped to “oic.wk.mnt” 10 properties Factory_Reset and Reboot, respectively, and any additional vendor-defined properties 11 in the OCF core resource “/oic/con” (which implements the “oic.wk.con” resource type and 12 optionally the “oic.wk.con.p” resource type) shall be mapped to vendor-defined fields the AllJoyn 13 Configuration data, with a field name formed by removing the leading “x.” from the property name. 14 .
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 30
1 7.2 On-the-Fly Translation from D-Bus and OCF payloads 2 The “dbus1” payload format is specified in the D-Bus Specification and AllJoyn adopted the D-Bus 3 protocol and made it distributed over the network. The modifications done by AllJoyn to the format are all 4 in the header part of the packet, not in the data payload itself, which remains compatible with “dbus1”. Other 5 variants of the protocol that have been proposed by the Linux community (“GVariant” and “kdbus” payloads) 6 contain slight incompatibilities and are not relevant for this discussion.
7 Translation without aid of introspection 8 This section describes how translators shall translate messages between the two payload formats in the 9 absence of introspection metadata from the actual device. This situation arises in the following cases:
10 • Requests to OIC 1.1 devices
11 • Replies from OIC 1.1 devices
12 • Content not described by introspection, such as the inner payload of AllJoyn properties of type 13 “D-Bus VARIANT”.
14 Since introspection is not available, the translator cannot know the rich JSON sub-type, only the underlying 15 CBOR type and from that it can infer the JSON generic type, and hence translation is specified below in 16 terms of those generic types.
17 7.2.1.1 Booleans 18 Boolean conversion is trivial, since both sides support this type.
D-Bus type JSON type “b” – BOOLEAN boolean (true or false)
19 7.2.1.2 Numeric types 20 The translation of numeric types is lossy and that is unavoidable due to the limited expressiveness 21 of the JSON generic types. This can only be solved with introspection.
22 The translation of numeric types is direction-specific.
From D-Bus type To JSON type “y” - BYTE (unsigned 8-bit) number “n” - UINT16 (unsigned 16-bit) “u” - UINT32 (unsigned 32-bit) “t” - UINT64 (unsigned 64-bit)(1) “q” - INT16 (signed 16-bit) “”" - INT32 (signed 32-bit) ”x” - INT64 (signed 64-bit)(1) “d” - DOUBLE (IEEE 754 double precision) 23
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 31
From JSON type To D-Bus type number “d” - DOUBLE(2)
1
2 Notes and rationales:
3 1. D-Bus payloads of types “t” (UINT64) and “x” (INT64) can contain values that cannot be perfectly 4 represented in IEEE 754 double-precision floating point. The RFCs governing JSON do not forbid 5 such numbers but caution that many implementations may not be able to deal with them. 6 Currently, OCF transports its payload using CBOR instead of JSON, which is capable of 7 representing those numbers with fidelity. However, it should be noted that the OCF 1.0 Core 8 Specification does not allow for integral numbers outside the range 2 2 . 53 53 9 2. In order to provide the most predictable result, all translations from OCF− to ≤AllJoyn𝑥𝑥 ≤ produce 10 values of type “d” DOUBLE (IEEE 754 double precision).
11 7.2.1.3 Text strings D-Bus type JSON type “s” - STRING string 12
13 Conversion between D-Bus and JSON strings is simple, as both require their content to be valid Unicode. 14 For example, an implementation can typically do a direct byte copy, as both protocols specify UTF-8 as 15 the encoding of the data, neither constrains the data to a given normalisation format nor specify whether 16 private-use characters or non-characters should be disallowed.
17 Since the length of D-Bus strings is always known, it is recommended translators not use CBOR 18 indeterminate text strings (first byte 0x7f).
19 7.2.1.4 Byte arrays 20 The translation of a byte array is direction-specific.
From D-Bus type To JSON type “ay” - ARRAY of BYTE (base64-encoded) string 21
22 The base64url encoding is specified in IETF RFC 4648 section 5.
23 7.2.1.5 D-Bus Variants D-Bus type JSON type “v” - VARIANT see below 24
25 D-Bus has a type called VARIANT (“v”) that is a wrapper around any other D-Bus type. It’s a way for the 26 type system to perform type-erasure. JSON, on the other hand, is not type-safe, which means that all 27 JSON values are, technically, variants. The conversion for a D-Bus variant to JSON is performed by 28 entering that variant and encoding the type carried inside as per the rules in this document.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 32
1 The algorithm must be recursive, as D-Bus variants are allowed to contain variants themselves.
2 7.2.1.6 D-Bus Object Paths and Signatures 3 The translation of D-Bus object paths and signatures is unidirectional (there is no mapping to them, 4 only from them). In the reverse direction, Section 7.2.1.3 always converts to D-Bus STRING 5 rather than OBJECT_PATH or SIGNATURE since it is assumed that “s” is the most common string 6 type in use.
From D-Bus type To JSON type “o” - OBJECT_PATH string “g” - SIGNATURE 7
8 Both D-Bus object paths and D-Bus type signatures are US-ASCII strings with specific formation rules, 9 found in the D-Bus Specification. They are very seldomly used and are not expected to be found in 10 resources subject to translation without the aid of introspection.
11 7.2.1.7 D-Bus Structures 12 The translation of the following types is direction-specific:
From D-Bus type To JSON type “r” - STRUCT array, length > 0 13
14 D-Bus structures can be interpreted as a fixed-length array containing a pre-determined list of types for 15 each member. This is how such a structure is mapped to JSON: as an array of heterogeneous content, 16 which are the exact members of the D-Bus structure, in the order in which they appear in the structure.
17 7.2.1.8 Arrays 18 The translation of the following types is bidirectional:
D-Bus type JSON type “ay” - ARRAY of BYTE (base64-encoded) string – see Section 7.2.1.4 “ae” - ARRAY of DICT_ENTRY object – see Section 7.2.1.9 19
20 The translation of the following types is direction-specific:
From D-Bus type To JSON type “a” – ARRAY of anything else not specified above array 21
22
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 33
From Condition To D-Bus type JSON type array length=0 “av” – ARRAY of VARIANT array length>0, all elements of “a” – ARRAY same type
array length>0, elements of “r” – STRUCT different types
1
2 Aside from arrays of bytes and arrays of dictionary entries, which are mapped to JSON strings and objects 3 respectively, arrays in JSON cannot be constrained to a single type (i.e., heterogeneous arrays). For that 4 reason, strictly speaking all D-Bus arrays excepting arrays of bytes and arrays of dictionary entries must 5 first be converted to arrays of variant “av” and then that array can be converted to JSON.
6 Conversion of D-Bus arrays of variants uses the conversion of variants as specified above, which simply 7 eliminates the distinction between a variant containing a given value and that value outside a variant. In 8 other words, the elements of a D-Bus array are extracted and sent as elements of the JSON array, as per 9 the other rules of this document.
10 7.2.1.9 Dictionaries / Objects D-Bus type JSON type “a{sv}” - dictionary of STRING to VARIANT object 11
12 The choice of “dictionary of STRING to VARIANT” is made because that is the most common type of 13 dictionary found in payloads and is an almost perfect superset of all possible dictionaries in D-Bus anyway. 14 Moreover, it is able to represent JSON Objects with fidelity, which is the representation that OCF uses in 15 its data models, which in turn means those D-Bus dictionaries will be able to carry with fidelity any OCF 16 JSON Object in current use.
17 D-Bus dictionaries that are not mapping string to variant are first converted to those constraints and then 18 encoded in CBOR.
19 7.2.1.10 Non-translatable types D-Bus Type JSON type “h” – UNIX_FD (Unix file descriptor) null
undefined (not officially valid JSON, but some implementations permit it)
20
21 The above types are not translatable and the translator should drop the incoming message. None of the 22 types above are in current use by either AllJoyn, OIC 1.1, or future OCF 1.0 devices, so the inability to 23 translate them should not be a problem.
24 7.2.1.11 Examples 25
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 34
Source D-Bus JSON Result BOOLEAN(FALSE) false BOOLEAN(TRUE) true VARIANT(BOOLEAN(FALSE)) false VARIANT(BOOLEAN(TRUE)) true BYTE(0) 0.0 BYTE(255) 255.0 INT16(0) 0.0 INT16(-1) -1.0 INT16(-32768) -32768.0 UINT16(0) 0.0 UINT16(65535) 65535.0 INT32(0) 0.0 INT32(-2147483648) -2147483648.0 INT32(2147483647) 2147483647.0 UINT32(0) 0.0 UINT32(4294967295) 4294967295.0 INT64(0) 0.0 INT64(-1) -1.0 UINT64(18446744073709551615) 18446744073709551615.0(1) DOUBLE(0.0) 0.0 DOUBLE(0.5) 0.5 STRING(“”) “” STRING(“Hello”) “Hello” ARRAY
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 35
1 Source JSON D-Bus Result false BOOLEAN(false) true BOOLEAN(true) 0 DOUBLE(0.0) -1 DOUBLE(-1.0) -2147483648 DOUBLE(-2147483648.0) 2147483647 DOUBLE(2147483647.0) 2147483648 DOUBLE(2147483648.0) -2147483649 DOUBLE(-2147483649.0) 9223372036854775808(1) DOUBLE(9223372036854775808.0) 0.0 DOUBLE(0.0) 0.5 DOUBLE(0.5) 0.0f DOUBLE(0.0) 0.5f DOUBLE(0.5) “” STRING(“”) “Hello” STRING(“Hello”) [] ARRAY
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 36
1 Translation with aid of introspection 2 When introspection is available, the translator can use the extra metadata provided by the side offering the 3 service to expose a higher-quality reply to the other side. This chapter details modifications to the translation 4 described in the previous chapter when the metadata is found.
5 Introspection metadata can be used for both translating requests to services and replies from those services. 6 When used to translate requests, the introspection is “constraining”, since the translator must conform 7 exactly to what that service expects. When used to translate replies, the introspection is “relaxing”, but may 8 be used to inform the receiver what other possible values may be encountered in the future.
9 Note that OCF introspection uses JSON types, media attributes, and format attributes, not CBOR encoding. 10 The actual encoding of each JSON type is discussed in Section 12.3 of the OCF 1.0 Core Specification, 11 JSON format attribute values are as defined in JSON Schema Validation, and JSON media attribute 12 values are as defined in JSON Hyper-Schema.
13 7.2.2.1 Translation of the introspection itself 14 Note that both OCF 1.0 and AllJoyn require all services exposed to include introspection metadata, which 15 means the translator will need to translate the introspection information on-the-fly for each OCF resource 16 or AllJoyn producer it finds. The translator shall preserve as much of the original information as can be 17 represented in the translated format. This includes both the information used in machine interactions and 18 the information used in user interactions, such as description and documentation text.
19 7.2.2.2 Variability of introspection data 20 Introspection data is not a constant and the translator may find, upon discovering further services, that the 21 D-Bus interface or OCF Resource Type it had previously encountered is different than previously seen. The 22 translator needs to take care about how the destination side will react to a change in introspection.
23 D-Bus interfaces used by AllJoyn services may be updated to newer versions, which means a given type 24 of service may be offered by two distinct versions of the same interface. Updates to standardised interfaces 25 must follow strict guidelines established by the AllSeen Interface Review Board, mapping each version to 26 a different OCF Resource Type should be possible without much difficulty. However, there’s no guarantee 27 that vendor-specific extensions follow those requirements. Indeed, there’s nothing preventing two revisions 28 of a product to contain completely incompatible interfaces that have the same name and version number.
29 On the opposite direction, the rules are much more lax. Since OCF specifies optional properties to its 30 Resource Types, a simple monotonically-increasing version number like AllJoyn consumer applications 31 expect is not possible.
32 However, it should be noted that services created by the translator by “on-the-fly” translation will only be 33 accessed by generic client applications. Dedicated applications will only use “deep binding” translation.
34 7.2.2.3 Numeric types 35 For numeric values, all D-Bus and JSON numeric types are treated equally as source and may all be 36 translated into any of the other side’s types. When translating a request to a service, the translator need 37 only verify whether there would be loss of information when translating from source to destination. For 38 example, when translating the number 1.5 to either a JSON integer or to one of the D-Bus integral types, 39 there would be loss of information, in which case the translator should refuse the incoming message. 40 Similarly, the value 1,234,567 does not fit the range of a D-Bus byte, 16-bit signed or unsigned integer.
41 When translating the reply from the service, the translator shall use the following rules.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 37
1 The following table indicates how to translate from a JSON type to the corresponding D-Bus type, where 2 the first matching row shall be used. If the JSON schema does not indicate the minimum value of a JSON 3 integer, 0 is the default. If the JSON schema does not indicate the maximum value of a JSON integer, 232 4 – 1 is the default. The resulting AllJoyn introspection XML shall contain “org.alljoyn.Bus.Type.Min” and 5 “org.alljoyn.Bus.Type.Max” annotations whenever the minimum or maximum, respectively, of the JSON 6 value is different from the natural minimum or maximum of the D-Bus type.
From JSON type Condition To D-Bus Type
integer minimum ≥ 0 AND maximum < 28 “y” (BYTE)
minimum ≥ 0 AND maximum < 216 “n” (UINT16)
minimum ≥ -215 AND maximum < 215 “q” (INT16)
minimum ≥ 0 AND maximum < 232 “u” (UINT32)
minimum ≥ -231 AND maximum < 231 “i" (INT32)
minimum ≥ 0 ”t” (UINT64)
“x” (INT64)
Number “d” (DOUBLE)
String pattern = “^0|([1-9][0-9]{0,19})$” “t” (UINT64)
pattern = “^0|(-?[1-9][0-9]{0,18)}$” “x” (INT64)
7
8 The following table indicates how to translate from a D-Bus type to the corresponding JSON type.
From D-Bus type To JSON type Note “y” (BYTE) integer “minimum” and “maximum” in the JSON schema shall be set to the “n” (UINT16) value of the “q” (INT16) “org.alljoyn.Bus.Type.Min” and “org.alljoyn.Bus.Type.Max” “u” (UINT32) (respectively) annotations if “i" (INT32) present, or to the min and max values of the D-Bus type’s range if such annotations are absent. “t” (UINT64) integer if org.alljoyn.Bus.Type.Max ≤ 253, else IETF RFC 7159 section 6 explains string with JSON format attribute “uint64” that higher JSON integers are not interoperable. “x” (INT64) integer (if org.alljoyn.Bus.Type.Min ≥ -253 AND IETF RFC 7159 section 6 explains org.alljoyn.Bus.Type.Max ≤ 253), else string that other JSON integers are not with JSON format attribute “int64” interoperable. “d” (double) number
9
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 38
1 7.2.2.4 Text string and byte arrays D-Bus Type JSON type JSON media attribute, binaryEncoding property “s” – STRING string (none)
“ay” - ARRAY of BYTE string base64
2
3 There’s no difference in the translation of text strings and byte arrays compared to the previous section. 4 This section simply lists the JSON equivalent types for the generated OCF introspection.
5 In addition, the mapping of the following JSON Types is direction-specific:
From JSON Condition To D-Bus Type type String pattern = “^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a- “ay” – ARRAY of BYTE fA-F0-9]{4}-[a-fA-F0-9]{12}$” 6
7 JSON strings with any other format value (e.g., date-time, uri, etc.) or pattern value not shown in this table 8 above shall be treated the same as if the format and pattern attributes were absent, by simply mapping 9 the value to a D-Bus string.
10 7.2.2.5 D-Bus Variants D-Bus Type JSON Type “v” – VARIANT see below 11
12 If the introspection of an AllJoyn producer indicates a value in a request should be a D-Bus VARIANT, the 13 translator should create such a variant and encode the incoming value as the variant’s payload as per the 14 rules in the rest of this document.
15 7.2.2.6 D-Bus Object Paths and Signatures From D-Bus Type To JSON Type “o” - OBJECT_PATH string “g” - SIGNATURE 16
17 If the introspection of an AllJoyn producer indicates a value in a request should be a D-Bus Object Path or 18 D-Bus Signature, the translator should perform a validity check in the incoming CBOR Text String. If the 19 incoming data fails to pass this check, the message should be rejected.
20 7.2.2.7 D-Bus Structures 21 D-Bus structure members are described in the introspection XML with the 22 “org.alljoyn.Bus.Struct.StructureName.Field.fieldName.Type” annotation. The translator shall use 23 the AJSoftwareVersion field of the About data obtained from a bridged AllJoyn producer as follows.
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 39
1 When the version of AllJoyn implemented on the Bridged Device is v16.10.00 or greater and the 2 member annotations are present, the translator shall use a JSON object to represent a structure, 3 mapping each member to the entry with that name. The translator needs to be aware that the 4 incoming CBOR payload may have changed the order of the fields, when compared to the D-Bus 5 structure. When the version of AllJoyn implemented on the Bridged Device is less than v16.10.00, 6 the translator shall follow the rule for translating D-Bus structures without the aid of introspection 7 data. 8 7.2.2.8 Arrays and Dictionaries 9 If the introspection of the AllJoyn interface indicates that the array is neither an ARRAY of BYTE (“ay”) nor 10 an ARRAY of VARIANT (“av”) or that the dictionary is not mapping STRING to VARIANT (“a{sv}”), the 11 translator shall apply the constraining or relaxing rules specified in other sections.
12 Similarly, if the OCF introspection indicates a homogeneous array type, the information about the array’s 13 element type should be used as the D-Bus array type instead of VARIANT (“v”).
14 7.2.2.9 Other JSON format attribute values 15 The JSON format attribute may include other custom attribute types. They are not known at this time, but 16 it is expected that those types be handled by their type and representation alone.
17 7.2.2.10 Examples AllJoyn Source AllJoyn Introspection Translated JSON OCF Introspection Notes Notes Payload UINT32 (0) 0 JSON schema should indicate: type = integer, minimum = 0 maximum = 4294967295 INT64 (0) 0 Since no Min/Max annotations exist in AllJoyn, JSON schema should indicate: type = string pattern = ^0|(-?[1-9][0- 9]{0,18)}$ UINT64 (0) “0” Since no Max annotation exists in AllJoyn, JSON schema should indicate: type = string pattern = ^0|([1-9][0- 9]{0,19})$
STRING(“Hello”) “Hello” JSON schema should indicate: type = string OBJECT_PATH(“/”) “/” JSON schema should indicate: type = string SIGNATURE(“g”) “g” JSON schema should indicate: type = string
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 40
AllJoyn Source AllJoyn Introspection Translated JSON OCF Introspection Notes Notes Payload ARRAY
1
CBOR OCF Introspection Notes Translated AllJoyn AllJoyn Introspection Notes Payload 0 JSON type is “integer” INT32(0) 0 JSON type is “integer” INT64(0) org.alljoyn.Bus.Type.Min = -240 minimum = -240 org.alljoyn.Bus.Type.Max = 240 maximum = 240 0 JSON type is “integer” UINT64(0) org.alljoyn.Bus.Type.Max = 248 minimum = 0 maximum = 248 0.0 JSON type is “float” DOUBLE(0.0) [1] JSON schema indicates: ARRAY
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 41
CBOR OCF Introspection Notes Translated AllJoyn AllJoyn Introspection Notes Payload items = integer element.minimum = 0 element.maximum = 246
1 8 Device Type Definitions
2 The required Resource Types are listed in the table below.
Device Name Device Type (“rt”) Required Required Resource Type Resource (informative) (Normative) name
Bridge oic.d.bridge Secure Mode oic.r.securemode
Virtual Device oic.d.virtual Device oic.wk.d
3 9 Resource Type definitions
4 9.1 List of resource types 5 Table 7 Alphabetical list of resource types
Friendly Name (informative) Resource Type (rt) Section Secure Mode oic.r.securemode 9.2 AllJoyn Object oic.r.alljoynobject 9.3
6
7 9.2 Secure Mode 8 9.2.1 Introduction 9 This resource describes a secure mode on/off feature (on/off).
10 A secureMode value of “true” means that the feature is on, and:
11 • any Bridged Server that cannot be communicated with securely shall not have a 12 corresponding Virtual OCF Server, and
13 • any Bridged Client that cannot be communicated with securely shall not have a 14 corresponding Virtual OCF Client.
15 A secureMode value of “false” means that the feature is off, and:
16 • any Bridged Server can have a corresponding Virtual OCF Server, and
17 • any Bridged Client can have a corresponding Virtual OCF Client.
18 9.2.2 Example URI 19 /example/SecureModeResURI
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 42
1 9.2.3 Resource Type 2 The resource type (rt) is defined as: oic.r.securemode.
3 9.2.4 RAML Definition 4 #%RAML 0.8 5 title: OCFSecureMode 6 version: v1.0.0-20160719 7 traits: 8 - interface : 9 queryParameters: 10 if: 11 enum: ["oic.if.rw", "oic.if.baseline"] 12
13 /example/SecureModeResURI: 14 description: | 15 This resource describes a secure mode on/off feature (on/off). 16 A secureMode value of “true” means that the feature is on, and any Bridged Server that cannot 17 be communicated with securely shall not have a corresponding Virtual OCF Server, and any Bridged 18 Client that cannot be communicated with securely shall not have a corresponding Virtual OCF Client. 19 A secureMode value of “false” means that the feature is off, any Bridged Server can have a 20 corresponding Virtual OCF Server, and any Bridged Client can have a corresponding Virtual OCF 21 Client. 22 23 is : ['interface'] 24 get: 25 responses : 26 200: 27 body: 28 application/json: 29 schema: | 30 { 31 "id": "http://openinterconnect.org/iotdatamodels/schemas/oic.r.securemode.json#", 32 "$schema": "http://json-schema.org/draft-04/schema#", 33 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 34 reserved.", 35 "title": "Secure Mode", 36 "definitions": { 37 "oic.r.securemode": { 38 "type": "object", 39 "properties": { 40 "secureMode": { 41 "type": "boolean", 42 "description": "Status of the Secure Mode" 43 } 44 } 45 } 46 }, 47 "type": "object", 48 "allOf": [ 49 {"$ref": "oic.core.json#/definitions/oic.core"}, 50 {"$ref": "oic.baseResource.json#/definitions/oic.r.baseresource"}, 51 {"$ref": "#/definitions/oic.r.securemode"} 52 ], 53 "required": [ "secureMode" ] 54 } 55 56 example: | 57 { 58 "rt": ["oic.r.securemode"], 59 "id": "unique_example_id", 60 "secureMode": false
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 43
1 } 2 3 post: 4 body: 5 application/json: 6 schema: | 7 { 8 "id": "http://openinterconnect.org/iotdatamodels/schemas/oic.r.securemode.json#", 9 "$schema": "http://json-schema.org/draft-04/schema#", 10 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 11 reserved.", 12 "title": "Secure Mode", 13 "definitions": { 14 "oic.r.securemode": { 15 "type": "object", 16 "properties": { 17 "secureMode": { 18 "type": "boolean", 19 "description": "Status of the Secure Mode" 20 } 21 } 22 } 23 }, 24 "type": "object", 25 "allOf": [ 26 {"$ref": "oic.core.json#/definitions/oic.core"}, 27 {"$ref": "oic.baseResource.json#/definitions/oic.r.baseresource"}, 28 {"$ref": "#/definitions/oic.r.securemode"} 29 ], 30 "required": [ "secureMode" ] 31 } 32 33 example: | 34 { 35 "id": "unique_example_id", 36 "secureMode": true 37 } 38 39 responses : 40 200: 41 body: 42 application/json: 43 schema: | 44 { 45 "id": "http://openinterconnect.org/iotdatamodels/schemas/oic.r.securemode.json#", 46 "$schema": "http://json-schema.org/draft-04/schema#", 47 "description" : "Copyright (c) 2016 Open Connectivity Foundation, Inc. All rights 48 reserved.", 49 "title": "Secure Mode", 50 "definitions": { 51 "oic.r.securemode": { 52 "type": "object", 53 "properties": { 54 "secureMode": { 55 "type": "boolean", 56 "description": "Status of the Secure Mode" 57 } 58 } 59 } 60 }, 61 "type": "object", 62 "allOf": [ 63 {"$ref": "oic.core.json#/definitions/oic.core"}, 64 {"$ref": "oic.baseResource.json#/definitions/oic.r.baseresource"}, 65 {"$ref": "#/definitions/oic.r.securemode"}
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 44
1 ], 2 "required": [ "secureMode" ] 3 } 4 5 example: | 6 { 7 "id": "unique_example_id", 8 "secureMode": true 9 } 10 11 12 9.2.5 Property Definition Property name Value type Mandatory Access mode Description secureMode boolean yes Read Write Status of the Secure Mode 13 9.2.6 CRUDN behaviour Example Resource URI Create Read Update Delete Notify /example/SecureModeResURI get post get 14
15 9.3 AllJoyn Object 16 Introduction 17 This resource is a collection of resources that were all derived from the same AllJoyn object.
18 Example URI 19 /example/AllJoynObjectBaselineResURI
20 Resource Type 21 The resource type (rt) is defined as: oic.r.alljoynobject.
22 RAML Definition 23 #%RAML 0.8 24 title: OCFAllJoynObject 25 version: v1.0.0-20170305 26 traits: 27 - interface-baseline: 28 queryParameters: 29 if: 30 enum: ["oic.if.baseline"] 31 - interface-ll: 32 queryParameters: 33 if: 34 enum: ["oic.if.ll"] 35 36 37 /example/AllJoynObjectBaselineResURI: 38 description: | 39 The resource is a collection of resources that were all derived from the same AllJoyn object. 40 41 is: [ interface-baseline ] 42 43 get: 44 description: | 45 Retrieves the current AllJoyn object information. 46 responses: 47 200: 48 body: 49 application/json: 50 schema: | 51 {
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 45
1 "id": 2 "http://openinterconnect.org/iotdatamodels/schemas/oic.r.alljoynobject.json#", 3 "$schema": "http://json-schema.org/draft-04/schema#", 4 "description" : "Copyright (c) 2017 Open Connectivity Foundation, Inc. All rights 5 reserved.", 6 "title": "AllJoyn Object", 7 "definitions": { 8 "oic.r.alljoynobject": { 9 "type": "object", 10 "allOf": [ 11 { 12 "$ref": "oic.collection-schema.json#/definitions/oic.collection" 13 }, 14 { 15 "rt": { 16 "type": "array", 17 "minItems": 2, 18 "maxItems": 2, 19 "uniqueItems": true, 20 "items": { 21 "enum": ["oic.r.alljoynobject","oic.wk.col"] 22 } 23 } 24 } 25 ] 26 } 27 }, 28 "type": "object", 29 "allOf": [ 30 {"$ref": "oic.core.json#/definitions/oic.core"}, 31 {"$ref": "#/definitions/oic.r.alljoynobject"} 32 ] 33 } 34 example: | 35 { 36 "rt": ["oic.r.alljoynobject","oic.wk.col"], 37 "id": "unique_example_id", 38 "links": [ 39 {"href": "/myRes1URI", "rt": ["x.example.widget.false"], "if": 40 ["oic.if.r","oic.if.rw","oic.if.baseline"]}, 41 {"href": "/myRes2URI", "rt": ["x.example.widget.true"], "if": 42 ["oic.if.r","oic.if.rw","oic.if.baseline"]}, 43 {"href": "/myRes3URI", "rt": ["x.example.widget.method1"], "if": 44 ["oic.if.rw","oic.if.baseline"]}, 45 {"href": "/myRes4URI", "rt": ["x.example.widget.method2"], "if": 46 ["oic.if.rw","oic.if.baseline"]} 47 ] 48 } 49 50 /example/AllJoynObjectLLResURI: 51 description: | 52 The resource is a collection of resources that were all derived from the same AllJoyn object. 53 54 displayName: AllJoyn Object 55 is: [ interface-ll ] 56 57 get: 58 responses: 59 200: 60 body: 61 application/json: 62 schema: | 63 { 64 "id": "http://openinterconnect.org/iotdatamodels/schemas/oic.r.alljoynobject-ll#", 65 "$schema": "http://json-schema.org/draft-04/schema#", 66 "description" : "Copyright (c) 2017 Open Connectivity Foundation, Inc. All rights 67 reserved.", 68 "title": "AllJoyn Object Link List Schema", 69 "definitions": { 70 "oic.r.alljoynobject-ll": { 71 "type": "object",
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 46
1 "allOf": [ 2 { 3 "$ref": "oic.collection.linkslist- 4 schema.json#/definitions/oic.collection.alllinks" 5 } 6 ] 7 } 8 }, 9 "type": "object", 10 "allOf": [ 11 {"$ref": "oic.core.json#/definitions/oic.core"}, 12 {"$ref": "#/definitions/oic.r.alljoynobject-ll"} 13 ] 14 } 15 example: | 16 { 17 "links": [ 18 {"href": "/myRes1URI", "rt": ["x.example.widget.false"], "if": 19 ["oic.if.r","oic.if.rw","oic.if.baseline"]}, 20 {"href": "/myRes2URI", "rt": ["x.example.widget.true"], "if": 21 ["oic.if.r","oic.if.rw","oic.if.baseline"]}, 22 {"href": "/myRes3URI", "rt": ["x.example.widget.method1"], "if": 23 ["oic.if.rw","oic.if.baseline"]}, 24 {"href": "/myRes4URI", "rt": ["x.example.widget.method2"], "if": 25 ["oic.if.rw","oic.if.baseline"]} 26 ] 27 } 28 29 CRUDN behaviour Example Resource URI Create Read Update Delete Notify /example/SecureModeResURI get post get 30
Copyright Open Connectivity Foundation, Inc. © 2017. All rights Reserved. 47