docs: add device profile information #139
Conversation
There was a problem hiding this comment.
@iain-anderson - some good stuff here. Some suggestions based on some prior documentation way back when. Use or lose as you see fit.
| The profile contains various identification information. The `Name` field is required and must be unique in an EdgeX deployment. Other fields are optional and provide additional details: | ||
|
|
||
| * Description | ||
| * Manufacturer |
There was a problem hiding this comment.
Manufacturer and model are, today, relatively arbitrary. We envisioned a time when multiple manufactures (or multiple models by the same manufacturer) followed the same device profile, in which case these additional tags can help users in search for particular device profile.
| * Description | ||
| * Manufacturer | ||
| * Model | ||
| * Labels |
There was a problem hiding this comment.
Labels just provided a way to organize or categorize the various profiles (envisioning a system where EdgeX manages all sorts of devices and the UI in charge needs some better way to organize them).
| DeviceResources | ||
| --------------- | ||
|
|
||
| A deviceResource specifies a value within a device that may be read from or |
There was a problem hiding this comment.
The term value is a bit ambigous here. Should we say "...specifies a sensor value or simply value ..."?
| The device service allows access to deviceResources via its `device` | ||
| REST endpoint. | ||
|
|
||
| The `Attributes` in a deviceResource are the device-service-specific parameters |
There was a problem hiding this comment.
In some of our original documentation we said:
Attributes are typically “inward facing”. That is, attributes are used by the device service and provide details about how the device service can speak to the device to either get or set some of its values. In other words, attributes are detail protocol and/or device specific information and inform the device service how to communication with the sensor to get (or set) the deviceResource (aka the value) of interest.
| whereas a Bluetooth device service could use a UUID to identify a value. | ||
|
|
||
| The `Properties` of a deviceResource describe the value. Each device resource | ||
| is given two properties, `value` and `units`. The following fields are |
There was a problem hiding this comment.
The 'value' property gives more detail about the value collected or set; such as the type of the data collected, whether the value can be read, written or both. The 'units' property gives more detail about the unit of measure associated with the value. The unit of measure can also have a type (although it is most often just a String), a default value, whether the unit can be read, written or both (although it is most often set to read only).
| * offset - a value to be added to a reading before it is returned. | ||
| * mask - a binary mask which will be applied to an integer reading. | ||
| * shift - a number of bits by which an integer reading will be shifted right. | ||
|
|
There was a problem hiding this comment.
As type is the only "required" property, should we indicate that the others are device service specific and what will happen if you provide a property that isn't used by the device service?
There was a problem hiding this comment.
The others are handled within the SDK - they should work for any device service
|
|
||
| DeviceCommands define access to reads and writes for multiple simultaneous | ||
| values. Each named deviceCommand should contain a number of get and/or set | ||
| `resourceOperations`, describing the read or write respectively. |
There was a problem hiding this comment.
think an example would be helpful here (example: a thermostat may provide temp and humidity deviceResources, but a getThermoValues can provide a read of both).
Also, can a device command do both a read and a write simultaneously? Should we specify this is homogeneous (reads or writes)?
| DeviceCommands | ||
| -------------- | ||
|
|
||
| DeviceCommands define access to reads and writes for multiple simultaneous |
There was a problem hiding this comment.
isn't really access to device resources? or at least via device resources. The connection between commands and device resources isn't made.
|
|
||
| The device service allows access to deviceCommands via the `device` REST | ||
| endpoint. If a deviceCommand and deviceResource have the same name, it will be | ||
| the deviceCommand which is available. |
There was a problem hiding this comment.
Interesting... so a deviceResource of the same name is never directly accessible. It is only there to service as an underlying resource to a command?
There was a problem hiding this comment.
TBH I think we should discourage deviceCommands and deviceResources with the same name
| endpoint. If a deviceCommand and deviceResource have the same name, it will be | ||
| the deviceCommand which is available. | ||
|
|
||
| CoreCommands |
There was a problem hiding this comment.
I think it would be helpful to specify where/why there might be a resource operation but not a command.
|
Updated in light of Cloud's and Jim's comments |
| Identification | ||
| -------------- | ||
|
|
||
| The profile contains various identification fields. The `Name` field is required and must be unique in an EdgeX deployment. Other fields are optional - they are not used in EdgeX but may be populated for informational purposes: |
There was a problem hiding this comment.
If the Name field must be unique, we need to define what happens when EdgeX encounters a duplicate name. This way, if someone inadvertently does duplicates a name, the error signature can be easily recognized.
There was a problem hiding this comment.
Are optional fields absolutely not used? By this I mean, these fields in the device profile are never even read by the device service, let alone stored in Core Metadata or in Core Data, and furthermore, are not "visible," e.g. retrievable by some RESTful API somewhere in EdgeX. If that is the case, then these fields should not even be in the document.
Otherwise, we need to be clearer on how they may or may not be populated and how they are visible.
Keep in mind, any data that enters "EdgeX" can and will be used by someone's "EdgeX."
There was a problem hiding this comment.
Clarified that the "optional" fields are not used by device services
| Get | GetCommand | N | At least one of Get and Put must be present | ||
| Put | PutCommand | N | At least one of Get and Put must be present |
There was a problem hiding this comment.
The Notes field disagrees/conflicts with the "Required?" field: "Required?" field states optional, but the Notes fields says that they are required.
|
|
||
| Field Name | Type | Required? | Notes | ||
| :--- | :--- | :--- | :--- | ||
| Name | String | Y | Must be unique in this profile. May have the same name as a DeviceResource but this will make the DeviceResource not accessible individually |
There was a problem hiding this comment.
This is odd behavior which will trip up some users. We need to either explain why one would not want a DeviceResource to be individually accessible or disallow name collisions between ProfileResource and DeviceResource.
There was a problem hiding this comment.
Noted that using the same name is only really useful if you want to apply Mappings on the resource.
|
|
||
| Field Name | Type | Required? | Notes | ||
| :--- | :--- | :--- | :--- | ||
| Path | String | Y | Must be `/api/v1/device/{deviceId}/XXX` where XXX is the name of the command |
There was a problem hiding this comment.
The constraints on XXX spelled out above (e.g. must be a deviceResource or a deviceCommand found within this device profile) should be spelled out here as well.
There was a problem hiding this comment.
Will "XXX" be escaped properly for HTTP or must the name be pre-escaped? e.g. "%20" or " ".
|
|
||
| Field Name | Type | Required? | Notes | ||
| :--- | :--- | :--- | :--- | ||
| Path | String | Y | Must be `/api/v1/device/{deviceId}/XXX` where XXX is the name of the command |
There was a problem hiding this comment.
Same comments about "XXX" as with the GET.
| The device service allows access to deviceResources via its `device` | ||
| REST endpoint. | ||
|
|
||
| The `Attributes` in a deviceResource are the device-service-specific parameters |
There was a problem hiding this comment.
Do we have documentation about the supported/required Attributes for each of the device services we offer? As this is written, I'm left scratching my head wondering what an Attribute is and how to use it.
There was a problem hiding this comment.
We required for new device services that the attributes were documented, see for example https://github.com/edgexfoundry/device-bacnet-c/blob/master/docs/deviceresource_specification.txt
We need to check that all of the existing services have this information
iain-anderson
force-pushed
the
devprofiles
branch
from
daeec55
to
a2364cc
Compare
Signed-off-by: Iain Anderson <iain@iotechsys.com>
Signed-off-by: Iain Anderson <iain@iotechsys.com>
iain-anderson
force-pushed
the
devprofiles
branch
from
e4d11bb
to
b1334da
Compare
Signed-off-by: edgex-jenkins <collab-it+edgex@linuxfoundation.org>
Signed-off-by: Iain Anderson iain@iotechsys.com
PR Checklist
Please check if your PR fulfills the following requirements:
PR Type
What kind of change does this PR introduce?
What is the current behavior?
Issue Number:
What has been updated?
Adds documentation for device profiles. I have removed the block diagram of the profile as it did not seem helpful.
Are there any specific instructions or things that should be known prior to reviewing?
Other information