From 979f0368811109aa8a7c9049660152840d90c3c5 Mon Sep 17 00:00:00 2001 From: Darryl Mocek Date: Mon, 6 Nov 2023 15:09:22 -0800 Subject: [PATCH 1/8] feat: Add Protocol-specific Attribute Values in Device UCR. Signed-off-by: Darryl Mocek --- .../design/ucr/Protocol-Info-In-Device.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs_src/design/ucr/Protocol-Info-In-Device.md diff --git a/docs_src/design/ucr/Protocol-Info-In-Device.md b/docs_src/design/ucr/Protocol-Info-In-Device.md new file mode 100644 index 0000000000..5aadcb3bda --- /dev/null +++ b/docs_src/design/ucr/Protocol-Info-In-Device.md @@ -0,0 +1,39 @@ +# Use Case Title +Protocol-specific Attribute Values in Device + +## Submitters +Darryl Mocek (Oracle Corporation) + +## Changelog + +## Market Segments +Any segments using EdgeX with device services that contain protocol-specific values in Device Profile attributes. + +## Motivation +The Device Profile describes the device. There are many different manufacturers of the same type of device (e.g. HVAC). The Device Profile of a specific type of device could used be for many or all of the Devices of that type, reducing the need to duplicate a Device Profile just to account for differences in the protocol-specific attribute values. + +## Target Users +Any users that create Device Profiles and Devices that have protocol-specific attribute values. + +## Description +The Device Profile **describes** the device and its attributes, it's type. Different manufacturers can build the same type of device using different protocols and the same device using the same protocol but different configuration (e.g. different Modbus HoldingRegister). For example, two different manufacturers may build an HVAC using ModBus, and another may build an HVAC using SNMP. In the case of two Modbus devices, there will need to be two different Device Profiles, even though the devices are the same and have the same attributes, because the protocol configurations (e.g. HoldingRegister) will conflict. Device Profile + +If the protocol information resides in the Device, which describes a specific (instance of a) device only a single Device Profile is needed as all devices of the same type can use the same Device Profile. This becomes more important as you have more devices, potentially increasing the number and management of Device Profiles when one will do. + +## Existing solutions + + +## Requirements +The requirement is to support the protocol-specific attribute values (e.g. HoldingRegister) in the Device as well as the Device Profile (for backward compatibility). + +- If only the Device contains a protocol-specific attribute, it is used for that device. +- If only the Device Profile contains a protocol-specific attribute, it is used for all Devices that have that Device Profile. +- If both the Device Profile and the Device contain a protocol-specific attribute, the entry in the Device overrides the one in the Device Profile. + +## Related Issues + +## References +- https://github.com/edgexfoundry/device-modbus/blob/master/src/main/resources/MBUS-RTH-LCD.profile.yaml From 62a8d7ab78169d5732e5c23f8ff6562f85515d7c Mon Sep 17 00:00:00 2001 From: Darryl Mocek Date: Mon, 6 Nov 2023 15:20:34 -0800 Subject: [PATCH 2/8] fix: Remove file. Signed-off-by: Darryl Mocek --- .../design/ucr/Protocol-Info-In-Device.md | 39 ------------------- 1 file changed, 39 deletions(-) delete mode 100644 docs_src/design/ucr/Protocol-Info-In-Device.md diff --git a/docs_src/design/ucr/Protocol-Info-In-Device.md b/docs_src/design/ucr/Protocol-Info-In-Device.md deleted file mode 100644 index 5aadcb3bda..0000000000 --- a/docs_src/design/ucr/Protocol-Info-In-Device.md +++ /dev/null @@ -1,39 +0,0 @@ -# Use Case Title -Protocol-specific Attribute Values in Device - -## Submitters -Darryl Mocek (Oracle Corporation) - -## Changelog - -## Market Segments -Any segments using EdgeX with device services that contain protocol-specific values in Device Profile attributes. - -## Motivation -The Device Profile describes the device. There are many different manufacturers of the same type of device (e.g. HVAC). The Device Profile of a specific type of device could used be for many or all of the Devices of that type, reducing the need to duplicate a Device Profile just to account for differences in the protocol-specific attribute values. - -## Target Users -Any users that create Device Profiles and Devices that have protocol-specific attribute values. - -## Description -The Device Profile **describes** the device and its attributes, it's type. Different manufacturers can build the same type of device using different protocols and the same device using the same protocol but different configuration (e.g. different Modbus HoldingRegister). For example, two different manufacturers may build an HVAC using ModBus, and another may build an HVAC using SNMP. In the case of two Modbus devices, there will need to be two different Device Profiles, even though the devices are the same and have the same attributes, because the protocol configurations (e.g. HoldingRegister) will conflict. Device Profile - -If the protocol information resides in the Device, which describes a specific (instance of a) device only a single Device Profile is needed as all devices of the same type can use the same Device Profile. This becomes more important as you have more devices, potentially increasing the number and management of Device Profiles when one will do. - -## Existing solutions - - -## Requirements -The requirement is to support the protocol-specific attribute values (e.g. HoldingRegister) in the Device as well as the Device Profile (for backward compatibility). - -- If only the Device contains a protocol-specific attribute, it is used for that device. -- If only the Device Profile contains a protocol-specific attribute, it is used for all Devices that have that Device Profile. -- If both the Device Profile and the Device contain a protocol-specific attribute, the entry in the Device overrides the one in the Device Profile. - -## Related Issues - -## References -- https://github.com/edgexfoundry/device-modbus/blob/master/src/main/resources/MBUS-RTH-LCD.profile.yaml From a367888889d6f11ca70c3ee29756461b1e2a0bf0 Mon Sep 17 00:00:00 2001 From: Darryl Mocek Date: Mon, 6 Nov 2023 15:21:10 -0800 Subject: [PATCH 3/8] feat: Add Protocol-specific Attribute Values in Device UCR. Signed-off-by: Darryl Mocek --- .../design/ucr/Protocol-Info-In-Device.md | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 docs_src/design/ucr/Protocol-Info-In-Device.md diff --git a/docs_src/design/ucr/Protocol-Info-In-Device.md b/docs_src/design/ucr/Protocol-Info-In-Device.md new file mode 100644 index 0000000000..5aadcb3bda --- /dev/null +++ b/docs_src/design/ucr/Protocol-Info-In-Device.md @@ -0,0 +1,39 @@ +# Use Case Title +Protocol-specific Attribute Values in Device + +## Submitters +Darryl Mocek (Oracle Corporation) + +## Changelog + +## Market Segments +Any segments using EdgeX with device services that contain protocol-specific values in Device Profile attributes. + +## Motivation +The Device Profile describes the device. There are many different manufacturers of the same type of device (e.g. HVAC). The Device Profile of a specific type of device could used be for many or all of the Devices of that type, reducing the need to duplicate a Device Profile just to account for differences in the protocol-specific attribute values. + +## Target Users +Any users that create Device Profiles and Devices that have protocol-specific attribute values. + +## Description +The Device Profile **describes** the device and its attributes, it's type. Different manufacturers can build the same type of device using different protocols and the same device using the same protocol but different configuration (e.g. different Modbus HoldingRegister). For example, two different manufacturers may build an HVAC using ModBus, and another may build an HVAC using SNMP. In the case of two Modbus devices, there will need to be two different Device Profiles, even though the devices are the same and have the same attributes, because the protocol configurations (e.g. HoldingRegister) will conflict. Device Profile + +If the protocol information resides in the Device, which describes a specific (instance of a) device only a single Device Profile is needed as all devices of the same type can use the same Device Profile. This becomes more important as you have more devices, potentially increasing the number and management of Device Profiles when one will do. + +## Existing solutions + + +## Requirements +The requirement is to support the protocol-specific attribute values (e.g. HoldingRegister) in the Device as well as the Device Profile (for backward compatibility). + +- If only the Device contains a protocol-specific attribute, it is used for that device. +- If only the Device Profile contains a protocol-specific attribute, it is used for all Devices that have that Device Profile. +- If both the Device Profile and the Device contain a protocol-specific attribute, the entry in the Device overrides the one in the Device Profile. + +## Related Issues + +## References +- https://github.com/edgexfoundry/device-modbus/blob/master/src/main/resources/MBUS-RTH-LCD.profile.yaml From f175695dd7c292ca9686c143c673d46801489b1f Mon Sep 17 00:00:00 2001 From: Darryl Mocek Date: Mon, 6 Nov 2023 15:21:47 -0800 Subject: [PATCH 4/8] fix: Remove file. Signed-off-by: Darryl Mocek --- .../design/ucr/Protocol-Info-In-Device.md | 39 ------------------- 1 file changed, 39 deletions(-) delete mode 100644 docs_src/design/ucr/Protocol-Info-In-Device.md diff --git a/docs_src/design/ucr/Protocol-Info-In-Device.md b/docs_src/design/ucr/Protocol-Info-In-Device.md deleted file mode 100644 index 5aadcb3bda..0000000000 --- a/docs_src/design/ucr/Protocol-Info-In-Device.md +++ /dev/null @@ -1,39 +0,0 @@ -# Use Case Title -Protocol-specific Attribute Values in Device - -## Submitters -Darryl Mocek (Oracle Corporation) - -## Changelog - -## Market Segments -Any segments using EdgeX with device services that contain protocol-specific values in Device Profile attributes. - -## Motivation -The Device Profile describes the device. There are many different manufacturers of the same type of device (e.g. HVAC). The Device Profile of a specific type of device could used be for many or all of the Devices of that type, reducing the need to duplicate a Device Profile just to account for differences in the protocol-specific attribute values. - -## Target Users -Any users that create Device Profiles and Devices that have protocol-specific attribute values. - -## Description -The Device Profile **describes** the device and its attributes, it's type. Different manufacturers can build the same type of device using different protocols and the same device using the same protocol but different configuration (e.g. different Modbus HoldingRegister). For example, two different manufacturers may build an HVAC using ModBus, and another may build an HVAC using SNMP. In the case of two Modbus devices, there will need to be two different Device Profiles, even though the devices are the same and have the same attributes, because the protocol configurations (e.g. HoldingRegister) will conflict. Device Profile - -If the protocol information resides in the Device, which describes a specific (instance of a) device only a single Device Profile is needed as all devices of the same type can use the same Device Profile. This becomes more important as you have more devices, potentially increasing the number and management of Device Profiles when one will do. - -## Existing solutions - - -## Requirements -The requirement is to support the protocol-specific attribute values (e.g. HoldingRegister) in the Device as well as the Device Profile (for backward compatibility). - -- If only the Device contains a protocol-specific attribute, it is used for that device. -- If only the Device Profile contains a protocol-specific attribute, it is used for all Devices that have that Device Profile. -- If both the Device Profile and the Device contain a protocol-specific attribute, the entry in the Device overrides the one in the Device Profile. - -## Related Issues - -## References -- https://github.com/edgexfoundry/device-modbus/blob/master/src/main/resources/MBUS-RTH-LCD.profile.yaml From 890ceb9f6d47630f71d5c74f00465d112fd88f5b Mon Sep 17 00:00:00 2001 From: Darryl Mocek Date: Tue, 7 Nov 2023 11:40:28 -0800 Subject: [PATCH 5/8] feat: Device Functions Signed-off-by: Darryl Mocek --- docs_src/design/ucr/device-functions.md | 29 +++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs_src/design/ucr/device-functions.md diff --git a/docs_src/design/ucr/device-functions.md b/docs_src/design/ucr/device-functions.md new file mode 100644 index 0000000000..04e34b2aec --- /dev/null +++ b/docs_src/design/ucr/device-functions.md @@ -0,0 +1,29 @@ +# Use Case Title +Device Functions + +## Submitters +Darryl Mocek (Oracle) + +## Changelog + +## Market Segments +Any segments using EdgeX with device services with devices that support device functions. + +## Motivation +Many devices contain functions that can be called, like the ability to reboot a device. EdgeX currently does not support the ability to invoke device functions, making parts of devices inaccessible. + +## Target Users +Any users using EdgeX with device services with devices that support device functions. + +## Description +Some devices support functions, invoking some action on a device, similar to a function in software. These functions unlock important functionality on the device. + +## Existing solutions +EdgeX supports setting attributes on a device. The workaround for calling device functions currently in EdgeX is to configure a device to call a function when setting at attribute, which isn't always feasible. For example, to call a 'reboot' device function on a device, a 'reboot' attribute would have to be created and it would have to be set to a value to invoke the reboot function on the device. + +## Requirements +Each Device should have a function resource and its parameters defined to support calling the device function with appropriate parameters. + +## Related Issues + +## References From 3b752fa54f02b8552614a171600bb6669f58ffc1 Mon Sep 17 00:00:00 2001 From: Darryl Mocek Date: Wed, 6 Dec 2023 15:48:18 -0800 Subject: [PATCH 6/8] fix: Add Device Functions to the table of contents. Signed-off-by: Darryl Mocek --- docs_src/design/TOC.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs_src/design/TOC.md b/docs_src/design/TOC.md index 729c4e133f..eaab389ef2 100644 --- a/docs_src/design/TOC.md +++ b/docs_src/design/TOC.md @@ -7,9 +7,10 @@ | Name/Link | Short Description | |-------------------------------------------------------------------------------------|---------------------------------------------------------------------| -| [Bring Your Own Vault](./ucr/Bring-Your-Own-Vault.md) | Use Case for bringing your own Vault | +| [Bring Your Own Vault](./ucr/Bring-Your-Own-Vault.md) | Use Case for bringing your own Vault | | [Common Configuration](./ucr/Common Configuration.md) | Use Case for having Common configuration used by all EdgeX services | | [Core Data Retention and Persistent Cap](./ucr/Core-Data-Retention.md) | Use Case for capping readings in Core Data | +| [Device Functions](./ucr/device-functions.md) | Use Case for Device Functions | | [Device Parent-Child Relationships](./ucr/Device-Parent-Child-Relationships.md) | Use Case for Device Parent-Child Relationships | | [Extending Device Data](./ucr/Extending-Device-Data.md) | Use Case for Extending of Device Data by Application Services | | [Provision Watch via Device Metadata](./ucr/Provision-Watch-via-Device-Metadata.md) | Use Case for Provision Watching via Additional Device Metadata | From 903f261cbce1398c53635da4789115af8c44932a Mon Sep 17 00:00:00 2001 From: Darryl Mocek Date: Wed, 6 Dec 2023 15:58:52 -0800 Subject: [PATCH 7/8] fix: Rename Device Functions document to conform to naming standard. Signed-off-by: Darryl Mocek --- docs_src/design/ucr/{device-functions.md => Device-Functions.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs_src/design/ucr/{device-functions.md => Device-Functions.md} (100%) diff --git a/docs_src/design/ucr/device-functions.md b/docs_src/design/ucr/Device-Functions.md similarity index 100% rename from docs_src/design/ucr/device-functions.md rename to docs_src/design/ucr/Device-Functions.md From 6aaa815048b5fd465f64436e478f6be48af1df13 Mon Sep 17 00:00:00 2001 From: Darryl Mocek Date: Fri, 8 Dec 2023 10:58:24 -0800 Subject: [PATCH 8/8] fix: Add UCR to TOC. Signed-off-by: Darryl Mocek --- docs_src/design/TOC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs_src/design/TOC.md b/docs_src/design/TOC.md index eaab389ef2..ea5440b551 100644 --- a/docs_src/design/TOC.md +++ b/docs_src/design/TOC.md @@ -10,7 +10,7 @@ | [Bring Your Own Vault](./ucr/Bring-Your-Own-Vault.md) | Use Case for bringing your own Vault | | [Common Configuration](./ucr/Common Configuration.md) | Use Case for having Common configuration used by all EdgeX services | | [Core Data Retention and Persistent Cap](./ucr/Core-Data-Retention.md) | Use Case for capping readings in Core Data | -| [Device Functions](./ucr/device-functions.md) | Use Case for Device Functions | +| [Device Functions](./ucr/Device-Functions.md) | Use Case for Device Functions | | [Device Parent-Child Relationships](./ucr/Device-Parent-Child-Relationships.md) | Use Case for Device Parent-Child Relationships | | [Extending Device Data](./ucr/Extending-Device-Data.md) | Use Case for Extending of Device Data by Application Services | | [Provision Watch via Device Metadata](./ucr/Provision-Watch-via-Device-Metadata.md) | Use Case for Provision Watching via Additional Device Metadata |