Topics

[Edgex-tsc-device-services] Device Service and Device Service SDK requirements

espy
 

On 08/23/2017 11:40 AM, James.White2@... wrote:

[...]

On the EdgeX Wiki, we have taken the step to outline the requirements of the device service (generically without regard to protocol, sensor, device, etc.) – and by defacto extension – define the requirements of what the SDK puts in device service scaffolding code it produces.
Please see the requirements document at the bottom of the page here:https://wiki.edgexfoundry.org/display/FA/Architecture--Device+Services+Microservices. <https://wiki.edgexfoundry.org/display/FA/Architecture--Device+Services+Microservices>
Your feedback and questions on these requirements are greatly appreciated.Next steps will be to add design diagrams and explanation around these requirements that connect to the SDK/Device Service code to the requirements and help to outline improvements we can make to SDK for ease of use and simplicity.
Jim --

Here's my feedback on the requirements.

Regards,
/tony


== Collect and Send reading data ==

1) Maybe re-title: "Collect & Forward Device Readings"

2) Here's a slight re-wording of the first two sentences:

"Communicate data read from devices and sensors to Core Data. ...such as a device asynchronously pushing new readings to the device service,..."

3) "op state" --> "operational state"

4) "Collection of data may have to update reading cache when new data is fetched or received (see Get Command requirement below)"

- missing trailing "."
- The next section says implementing a cache is optional, so does this need to be mentioned in requirements for data collection? It's more a statement about what the service would need to do if it opted to provide a cache vs. a requirement for data collection. If you keep this, please re-word, as it's not obvious at first what it means.
- also "see Get Command..." should be "see Get Commands...".

== Receive and respond to Get Commands ==

1) Suggestion "Handle requests" --> "Handle GET requests"

2) This doesn't make sense:

"Optionally, the successful handling of data a Get request that physically interacts with the sensor/device may be used to update the device's op state (see below for requirement)."

How about?

"Optionally, a Get request that triggers a successful reading from a sensor/device can result in the device's operational state being updated (see Report on operational device/sensor status )."

3) "Note, a command handled by the device service does not always trigger a single request to a device/sensor. Depending on the device/sensor and mediating software, a single Get command can result in multiple requests to the underlying devices/sensors or even multiple requests to a single device/sensor."

This doesn't seem to be a requirement, but instead is commentary on the fact that device services can implement aggregation of devices and/or trigger multiple readings based on a single external command.

== Receive and act on Put Commands =

1) Title: "act on" --> "respond" (implies acting)

2) Suggestion: "Handle requests" --> "Handle PUT requests"

3) "The difference between a Get and Put is that a Get must respond with some data."

But a GET can response with an HTTP error response, in which case it shouldn't be providing data right? Note - I filed a bug about stack traces being returned by the metadata service [1], which I think is a side-effect of the current Spring Framework's usage in EdgeX.

4) "Optionally, the successful handling of data a Get request that physically interacts with the sensor/device may be used to update the device's op state (see below for requirement). "

Copy & paste error? This is the same as the from the previous section.

5) Same comment as in the previous section regarding the multiplexing of commands, or triggering of repeated device interactions by a single external PUT request. Also, if this is kept, perhaps an example would help?

== Data Transformation ==

1) "In all communications with the device/sensors, the device service shall offer a specifiable transformation of the device/sernsor information so as to offer the information to the rest of EdgeX in a normalized EdgeX anticipated manner."

How 'bout:

"A device service must implement data transformation logic that converts data readings from devices/sensors to a normalized EdgeX Foundry specific schema before being forwarded to Core Data."

== Optionally discover new devices ==

1) "When it does so, it can establish and associate the devices to itself in Core Metadata."

How about:

"When a new device is discovered, a device service can trigger a connection to the device, and if successful, register the device with Core Metadata."

2) Do we want to say anything about a device service being able to white or black list devices?

3) Should the device service be required to notify some core service if the device requires some kind of authentication/authorization (eg. a PIN that might be store in Core Config)?

4) Does EdgeX allow devices to initiate a connection?

== Disconnect the device ==

1) Does disconnecting a device prevent it from re-connecting?

== Report on operational device/sensor status ==

1) "It may be accomplished by catching any problems when reporting data or reacting to commands."

Does this mean if an error is caught it triggers a notification of change in operational status? Or does it just mean that the operational status of a device can be updated when error occurs?

Does EdgeX define the operational states? If so, what are they?

2) "However the DS determines the admin or op state, it must push this update in status to Core Metadata."

This should just mention operational state, no admin state. It sounds like this clarifies my earlier question in the previous section. If the operational state of a device changes, the device service must update Core Metadata. Is there any notification to Core Data if a device becomes no longer operational?

== Set the admin status of devices/sensors ==

1) Can a device service cache readings while it's locked?

2) Can new devices be connected when locked?

3) If devices operational states change while locked are notifications dropped?

== Report its own operational status ==

1) What are the values for a device service's operational status?

2) Does this mean a device service is responsible for pinging (ie. some form of watchdog timer) the metadata service *and* the config/registry service?

3) Do any of the SDK generated device services implement this requirement currently?

== Receive Metadata updates ==

1) "For example, if an application such as an EdgeX user interface requests removing a device from the system by request through Metadata, this request is relayed and handled via metadata callback by the device service"

- missing "."
- This seems odd to me, I'd expect that a UI would request that a device be removed directly via the device service, or indirectly through Core Command?
- Is this requirement implemented in any of the existing DSes?

== Receive configuration updates ==

1) Are the properties covered by the config/registry service documented anywhere, so that this document can reference?

== Device Service startup (first time) ==

1) "A device service must register itself with EdgeX config/registry micro service."

Is this requirement enforced today in any of the device services? I thought this was currently under control of the @EnableDiscoveryClient annotation which is commented out by default in the DS SDK.

2) Regarding getting config data from the registry. Based on the tech talk last week, this hasn't been implemented yet, correct?

3) "It may optionally discover and/or otherwise statically establish and associated devices to itself in Core Metadata."

Suggestion:

"It also can register devices with Core Metadata from a white-list and/or optionally run an initial discovery process for devices."

4) "See initialization requirements for other work at startup."

I don't see any initialization requirements in this document.

== Device Service startup (non-first time) ==

1) This should probably be changed to TBD based on current discussions. ;)-

[1] https://github.com/edgexfoundry/core-metadata/issues/7

James.White2@...
 

Thanks for these Tony. We'll make some edits, revise and provide another version for review. Also, hope to have some of the design docs done by next week when you return.
Jim
________________________________________
From: espy <espy@...>
Sent: Saturday, August 26, 2017 8:06 PM
To: White2, James; edgex-tsc-device-services@...
Cc: edgex-devel@...
Subject: Re: [Edgex-tsc-device-services] Device Service and Device Service SDK requirements

On 08/23/2017 11:40 AM, James.White2@... wrote:

[...]

On the EdgeX Wiki, we have taken the step to outline the requirements of
the device service (generically without regard to protocol, sensor,
device, etc.) – and by defacto extension – define the requirements of
what the SDK puts in device service scaffolding code it produces.


Please see the requirements document at the bottom of the page
here:https://wiki.edgexfoundry.org/display/FA/Architecture--Device+Services+Microservices.
<https://wiki.edgexfoundry.org/display/FA/Architecture--Device+Services+Microservices>


Your feedback and questions on these requirements are greatly
appreciated.Next steps will be to add design diagrams and explanation
around these requirements that connect to the SDK/Device Service code to
the requirements and help to outline improvements we can make to SDK for
ease of use and simplicity.
Jim --

Here's my feedback on the requirements.

Regards,
/tony


== Collect and Send reading data ==

1) Maybe re-title: "Collect & Forward Device Readings"

2) Here's a slight re-wording of the first two sentences:

"Communicate data read from devices and sensors to Core Data. ...such
as a device asynchronously pushing new readings to the device service,..."

3) "op state" --> "operational state"

4) "Collection of data may have to update reading cache when new data is
fetched or received (see Get Command requirement below)"

- missing trailing "."
- The next section says implementing a cache is optional, so does this
need to be mentioned in requirements for data collection? It's more a
statement about what the service would need to do if it opted to provide
a cache vs. a requirement for data collection. If you keep this, please
re-word, as it's not obvious at first what it means.
- also "see Get Command..." should be "see Get Commands...".

== Receive and respond to Get Commands ==

1) Suggestion "Handle requests" --> "Handle GET requests"

2) This doesn't make sense:

"Optionally, the successful handling of data a Get request that
physically interacts with the sensor/device may be used to update the
device's op state (see below for requirement)."

How about?

"Optionally, a Get request that triggers a successful reading from a
sensor/device can result in the device's operational state being updated
(see Report on operational device/sensor status )."

3) "Note, a command handled by the device service does not always
trigger a single request to a device/sensor. Depending on the
device/sensor and mediating software, a single Get command can result
in multiple requests to the underlying devices/sensors or even multiple
requests to a single device/sensor."

This doesn't seem to be a requirement, but instead is commentary on the
fact that device services can implement aggregation of devices and/or
trigger multiple readings based on a single external command.

== Receive and act on Put Commands =

1) Title: "act on" --> "respond" (implies acting)

2) Suggestion: "Handle requests" --> "Handle PUT requests"

3) "The difference between a Get and Put is that a Get must respond with
some data."

But a GET can response with an HTTP error response, in which case it
shouldn't be providing data right? Note - I filed a bug about stack
traces being returned by the metadata service [1], which I think is a
side-effect of the current Spring Framework's usage in EdgeX.

4) "Optionally, the successful handling of data a Get request that
physically interacts with the sensor/device may be used to update the
device's op state (see below for requirement). "

Copy & paste error? This is the same as the from the previous section.

5) Same comment as in the previous section regarding the multiplexing of
commands, or triggering of repeated device interactions by a single
external PUT request. Also, if this is kept, perhaps an example would help?

== Data Transformation ==

1) "In all communications with the device/sensors, the device service
shall offer a specifiable transformation of the device/sernsor
information so as to offer the information to the rest of EdgeX in a
normalized EdgeX anticipated manner."

How 'bout:

"A device service must implement data transformation logic that converts
data readings from devices/sensors to a normalized EdgeX Foundry
specific schema before being forwarded to Core Data."

== Optionally discover new devices ==

1) "When it does so, it can establish and associate the devices to
itself in Core Metadata."

How about:

"When a new device is discovered, a device service can trigger a
connection to the device, and if successful, register the device with
Core Metadata."

2) Do we want to say anything about a device service being able to white
or black list devices?

3) Should the device service be required to notify some core service if
the device requires some kind of authentication/authorization (eg. a PIN
that might be store in Core Config)?

4) Does EdgeX allow devices to initiate a connection?

== Disconnect the device ==

1) Does disconnecting a device prevent it from re-connecting?

== Report on operational device/sensor status ==

1) "It may be accomplished by catching any problems when reporting data
or reacting to commands."

Does this mean if an error is caught it triggers a notification of
change in operational status? Or does it just mean that the operational
status of a device can be updated when error occurs?

Does EdgeX define the operational states? If so, what are they?

2) "However the DS determines the admin or op state, it must push this
update in status to Core Metadata."

This should just mention operational state, no admin state. It sounds
like this clarifies my earlier question in the previous section. If the
operational state of a device changes, the device service must update
Core Metadata. Is there any notification to Core Data if a device
becomes no longer operational?

== Set the admin status of devices/sensors ==

1) Can a device service cache readings while it's locked?

2) Can new devices be connected when locked?

3) If devices operational states change while locked are notifications
dropped?

== Report its own operational status ==

1) What are the values for a device service's operational status?

2) Does this mean a device service is responsible for pinging (ie. some
form of watchdog timer) the metadata service *and* the config/registry
service?

3) Do any of the SDK generated device services implement this
requirement currently?

== Receive Metadata updates ==

1) "For example, if an application such as an EdgeX user interface
requests removing a device from the system by request through Metadata,
this request is relayed and handled via metadata callback by the device
service"

- missing "."
- This seems odd to me, I'd expect that a UI would request that a
device be removed directly via the device service, or indirectly through
Core Command?
- Is this requirement implemented in any of the existing DSes?

== Receive configuration updates ==

1) Are the properties covered by the config/registry service documented
anywhere, so that this document can reference?

== Device Service startup (first time) ==

1) "A device service must register itself with EdgeX config/registry
micro service."

Is this requirement enforced today in any of the device services? I
thought this was currently under control of the @EnableDiscoveryClient
annotation which is commented out by default in the DS SDK.

2) Regarding getting config data from the registry. Based on the tech
talk last week, this hasn't been implemented yet, correct?

3) "It may optionally discover and/or otherwise statically establish and
associated devices to itself in Core Metadata."

Suggestion:

"It also can register devices with Core Metadata from a white-list
and/or optionally run an initial discovery process for devices."

4) "See initialization requirements for other work at startup."

I don't see any initialization requirements in this document.

== Device Service startup (non-first time) ==

1) This should probably be changed to TBD based on current discussions. ;)-

[1] https://github.com/edgexfoundry/core-metadata/issues/7