Greetings, To go to your original question it really depends on what you want to expose with respect to your particular light device. The only resource a light must expose is oic.r.switch.binary (i.e. you can turn it off and on), everything else is an implementation choice and comes down to how you are representing things and maybe the semantics of what you want to convey (i.e. some devices talk about setting brightness, some talk about ability to dim).
Dimming is a value defined by the range Property (if present), Min and Max can be whatever you like within the bounds of what an 'integer' can represent. If you choose not to expose a range then it defaults to [0,100] and a step of 1. Brightness is a quantized representation (0..100) where 0 is minimum and 100 is maximum (schema enforced). Can you clarify what specifically you'd like to see from a resource definition perspective? Best, Mark. From: Nash, George [mailto:[email protected]] Sent: Monday, December 4, 2017 2:48 PM To: Mark Trayer <[email protected]>; Wouter van der Beek (wovander) <[email protected]>; [email protected] Cc: [email protected] Subject: RE: Questions about brightness and dimming resource types Thanks that answers a lot of questions. Based on your responses, I assume, if you have a Multi-type RT and two of the resources want to set one of the oic.r.baseresource values (two resources want to use "range") then it would not be eligible for Multi-type RT and would have to be represented as a collection. Due to name conflicts making it ineligible for Multi-type RT. > The tooling that creates the Swagger 2.0 files should pull in the Properties > from the 'referenced' ($ref, JSON pointer) resources, thus including what is > in baseresource (and further oic.core which baseresource includes). >From what I have seen the tooling for Swagger 2.0 is not pulling in the >properties from oic.core just oic.r.baseresource. I hope the Smarthome group is able to take a look at oic.r.light.dimming and oic.r.light.brightness. I if they are both supposed to represent a percentage then one is redundant. One should be marked as the preferred resource type for anyone creating a smart light. I think the lighting could benefit from a resource that represents the actual values supported by the light. Enabling light that can represent more or less than a 0 to 100 range. I think using my original interpretation for the difference between brightness and dimming resource could make since. Thanks Mark and Wouter your responses have helped. From: Mark Trayer [mailto:[email protected]] Sent: Monday, December 4, 2017 11:46 AM To: Nash, George <[email protected]<mailto:[email protected]>>; Wouter van der Beek (wovander) <[email protected]<mailto:[email protected]>>; [email protected]<mailto:[email protected]> Cc: [email protected]<mailto:[email protected]> Subject: RE: Questions about brightness and dimming resource types Greetings, You don't need to do anything with the RT in the actual Resource on the wire; as Wouter noted the 'baseresource' is a schema mechanism by which we can define 'properties available to any OCF resource instance' without having to explicitly call them out every time, take a look at any of the schemas in oneIoTa (e.g. Dimming ... https://oneiota.org/revisions/2398) and you can see that an instance of a JSON document that conforms to this is an object that pulls from the baseresource.json definition and the oic.r.light.dimming defined properties. Simply having "rt" of "oic.r.light.dimming" is then sufficient to fully define the applicable schema. Multi-value RT does not apply as you don't expose the two RTs, just the RT of the resource that is building on baseresource (which is all of them in the Resource Type spec). Any Properties that "must" be part of an instance of the Resource on the wire are indicated by use of the 'Required' keyword in the schema for the Resource itself, i.e. an instance of oic.r.light.dimming has to include dimmingSetting and that's it, everything else is up to the needs of the implementation. The way "value" is defined it means that all resources can expose a Property called "value" that can be one of the types listed; it's up to the resource definition itself to override this with specifics should it need to. You don't have to expose it and in the case of 'dimming' doesn't have any real meaning. The tooling that creates the Swagger 2.0 files should pull in the Properties from the 'referenced' ($ref, JSON pointer) resources, thus including what is in baseresource (and further oic.core which baseresource includes). Best, Mark. From: [email protected]<mailto:[email protected]> [mailto:[email protected]] On Behalf Of Nash, George Sent: Monday, December 4, 2017 1:08 PM To: Wouter van der Beek (wovander) <[email protected]<mailto:[email protected]>>; [email protected]<mailto:[email protected]> Cc: [email protected]<mailto:[email protected]> Subject: [OCF smarthome_tg] RE: Questions about brightness and dimming resource types Wouter, Thanks for the response. If you want to include the base properties from the 'oic.baseresource' are you required to include it in "rt" array? Example: { "rt" : ["oic.baseresource", "oic.r.light.dimming"], "if": ["oic.if.baseline"], "id": "unique_example_id", "dimminSetting": 10 "value": 10, "precision": 1, "range": [0.0,100.0] } Based on your response I have a little confusion on what I should be using "oic.baseresource" or "oic.r.baseresource" I can find instances of both on oneIoTa and the OCF Resource Type Specification 1.3 also uses both. It seems to always be oic.baseResoruce.json when referring to the *.json file but oic.r.baseresource everywhere else. Also capitalization is inconsistent sometimes it is baseresource other times it is baseResource. Do you know where in the specifications I can read more about oic.baseresource? The only place I could find anything about it was in the OCF Resource Type Specification 1.3 and all the mentions of it I found assumed it was already understood. What is the value or the "value" property in oic.r.baseresource. It is a union so it can be anything. I would assume it is related to something in the resource it is part of but is there a rule that can be followed when using the "value" property? In addition I will re-ask my question about Multi-value "rt". I didn't see an answer in your response. If oic.r.baseresource is include by default how is it handled for Multi-value "rt" resources? (See section 7.4.4 of the OCF Core Specification v1.3) Wouldn't the oic.r.baseresource automatically force using composite resources where each resource is a link since it makes a union of properties not possible? Thanks for the clarification on the differences between RAML, JSON, and swagger. How does the Swagger file decided to include the properties from oic.r.baseresource? Thanks George Nash From: [email protected]<mailto:[email protected]> [mailto:[email protected]] On Behalf Of Wouter van der Beek (wovander) Sent: Monday, December 4, 2017 5:24 AM To: Nash, George <[email protected]<mailto:[email protected]>>; [email protected]<mailto:[email protected]> Cc: [email protected]<mailto:[email protected]> Subject: [OCF smarthome_tg] RE: Questions about brightness and dimming resource types Hi George, oic.r.baseresource is not a resource, but an mechanism to include the base properties of an resource, as example: { "rt" : ["oic.baseresource"], "if": ["oic.if.baseline"], "id": "unique_example_id", "value": 10.5, "precision": 0.5, "range": [0.0,100.0] } By using the include mechanisms it can be avoided to redefine the properties each time. Note that by looking at the required field in the schema, one can find out if these properties are required on the wire. For clarification the include file should not have been named .r.resource since it is not an resource.. I think the smart home project will clarify whether dimming or brightness should be used for an light device. The intention of both resource types are that they do percentages. The RAML file explains which methods are defined, the json schema defines the payloads per method. The swagger file is an automated generated file from the RAML and json schemas, it conveys the same information but in another format. The swagger format is json based and is also used for introspection files. Hope this helps.. Kind Regards, Wouter From: [email protected]<mailto:[email protected]> [mailto:[email protected]] On Behalf Of Nash, George Sent: 29 November 2017 21:02 To: [email protected]<mailto:[email protected]> Cc: [email protected]<mailto:[email protected]> Subject: [dev] Questions about brightness and dimming resource types Sent to the smarthome task group I have cc'ed the iotivity-dev group since a related question was asked by another developer Fabian a few days ago. As a programming exercise I have been developing a ocf light that is built using only standard interfaces that are defined on oneIoTa.org The brightness resource type has 3 entries on oneIoTa RAML, Swagger, and JSON Schema. oic.r.light.brightness.json<https://oneiota.org/revisions/2399> BrightnessResURI.swagger.json<https://oneiota.org/revisions/2518> brightness.raml<https://oneiota.org/revisions/1746> The dimming resource type also has 3 entries on oneIoTa RAML, Swagger, and JSON Schema. dimming.raml<https://oneiota.org/revisions/1798> DimmingResURI.swagger.json<https://oneiota.org/revisions/2530> oic.r.light.dimming.json<https://oneiota.org/revisions/2398> Which entry should be considered the defacto representation of the resource type? I ask because they don't all match up. In brightness all three list the "brightness" property with a maximum of 100 and minimum of 0. The swagger representation also lists "precision", "range", "step", and "value". These are all properties from oic.r.baseresource. I am confused why these properties are listed in BrightnessResURI.swagger.json? Are we expecting these values to be used in the brightness resource type? My confusion became even greater when I started looking at the dimming resource. In dimming all three list the "dimmingSetting" unlike the brightness there is no min/max value. The dimming.raml representation also shows "step", and "range". The swagger representation lists "dimmingSetting", "precision", "range", "step", and "value". Once again most of the properties are from oic.r.baseresource. What properties are required vs. optional? I could not identify this information from any of the 3 representations. My initial interpretation of this was: - The brightness was always a percentage 0% to 100% brightness. This would make more since if it was a number instead of an integer since in theory you could have 12.5% brightness. Still limiting it to the nearest 1% makes since. - The dimmingSetting was based on the actual values supported by the device. If you have a light with 255 brightness values. Then you would set the "range"=[0, 255]. Or possibly you have a light with 6 brightness settings you could set "range" =[0, 10], "step"=2, this would give you 6 possible values 0,2,4,6,8,10 oic.r.baseresource has led to other questions for me. Is oic.r.baseresource added to all resources by default? Note: I could not find any documentation on the baseresource. The only place it is even mentioned _that I could find_ was in the OCF Resource Type Specification v1.3. Every mention seems to assume that its already known and understood. If it were not for the listing in oneIoTa I don't think I would have known what was in the baseresource. If oic.r.baseresource is include by default how is it handled for Multi-value "rt" resources? (See section 7.4.4 of the OCF Core Specification v1.3) Wouldn't the oic.r.baseresource automatically force using composite resources where each resource is a link since it make a union of properties not possible? Initially I thought that the brightness and dimming resource types could exist in a Multi-value "rt" resource if my initial interpretation was correct one of the properties would have to be given a priority over the other when doing a update since it is possible the update would contain a dimmingSetting that would not work with the brightness on the same device. When I do a find on /oic/res the oic.r.baseresource is not found so it does not appear to be a default resource like many of the security related resources. George Nash
_______________________________________________ iotivity-dev mailing list [email protected] https://lists.iotivity.org/mailman/listinfo/iotivity-dev
