feat(adr): fixed mkdocs complaints about references to my other UCRs.

Noted that, for local builds, now also must have pip install mkdocs-macros-plugin>=0.5 mkdocs now reports that Line 267 of some unamed .md file has: INFO - [macros] - ERROR # _Macro Syntax Error_ _Line 267 in Markdown file:_ **expected token ':', got '}'** Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Update based on review comments. In particular, added example and requirements to extend Provisioning for south-bound Device Services. Removed 0004- from the UCR filename. Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Updates based on discussion today, reviewing this UCR. Renamed the UCR for clarity; emphasizing Device Metadata. Dropped minor correction in README.md Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> ci: add retry to mkdocs build stage Signed-off-by: Ernesto Ojeda <ernesto.ojeda@intel.com> feat(microservices): Add NATS MessageBus Overview Lists new options, build flag and simple jetstream example. Links to README for complete option listing. Signed-off-by: Alex Ullrich <alex.ullrich@gmail.com> doc: updated the SDK-Go-API.md document to reflect the new functions of DeviceSDKService wrapper Signed-off-by: Marc-Philippe Fuller <marc-philippe.fuller@intel.com> fix: Remove scheduler unused fields and update data dictionary fix edgexfoundry#787 Signed-off-by: Ginny Guan <ginny@iotechsys.com> fix: Escape unintended macro templates, fail docs build on errors (edgexfoundry#814) * fix: Escape marching Jinja test in CLI docs * feat: Make builds fail on macro errors Signed-off-by: Farshid Tavakolizadeh <farshid.tavakolizadeh@canonical.com> feat: add build and run on ARM32 fixes edgexfoundry#685 Signed-off-by: jpwhitemn <jpwhite_mn@yahoo.com> feat: add arm32 doc to nav bar Signed-off-by: jpwhitemn <jpwhite_mn@yahoo.com> feat: Referencing doc pages with latest alias (edgexfoundry#831) Signed-off-by: Farshid Tavakolizadeh <farshid.tavakolizadeh@canonical.com> Co-authored-by: Mengyi Wang <mengyi.wang@canonical.com> feat: Document Core Metadata Device System Events closes edgexfoundry#829 Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> fix: Rename the existing UCR to not have leading sequence number (edgexfoundry#837) * fix: Rename the existing UCR to not have leading sequence number Also added notes to TOC on naming and order of UCRs and ADRs Signed-off-by: Lenny Goodell <leonard.goodell@intel.com> Co-authored-by: Tom Brennan <ThomasJBrennan@eaton.com> docs: Update MQTT example doc Update MQTT example doc for Levski release Close edgexfoundry#64 Signed-off-by: bruce <weichou1229@gmail.com> feat: document core metadata units of measure capability Signed-off-by: Chris Hung <chris@iotechsys.com> fix: Add kong restart step to use new admin token after re-setup Signed-off-by: Farshid Tavakolizadeh <farshid.tavakolizadeh@canonical.com> fix: Correct spelling of autostart option Signed-off-by: Farshid Tavakolizadeh <farshid.tavakolizadeh@canonical.com> feat: update uom configuration example Signed-off-by: Chris Hung <chris@iotechsys.com> feat(microservices): Reading AES256 Protected Data Add note on decrypting payloads protected with AESProtection. Include python code from TAF as an example. Fixes edgexfoundry#784 Signed-off-by: Alex Ullrich <alex.ullrich@gmail.com> feat: Document Core Metadata Device System Events closes edgexfoundry#829 Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> Co-authored-by: Tom Brennan <ThomasJBrennan@eaton.com> feat: document core metadata units of measure capability Signed-off-by: Chris Hung <chris@iotechsys.com> Co-authored-by: Tom Brennan <ThomasJBrennan@eaton.com> feat: update uom configuration example Signed-off-by: Chris Hung <chris@iotechsys.com> fix: Change snap getting started to use consul management token (edgexfoundry#841) Signed-off-by: Farshid Tavakolizadeh <farshid.tavakolizadeh@canonical.com> docs: add management token (edgexfoundry#844) close #3158 Signed-off-by: Valina Li <valina.li@intel.com> Signed-off-by: Valina Li <valina.li@intel.com> Update docs_src/design/ucr/Provision-Watch-via-Device-Metadata.md Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Co-authored-by: Farshid Tavakolizadeh <email@farshid.ws> Updates per review comments. Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> ci: add retry to mkdocs build stage Signed-off-by: Ernesto Ojeda <ernesto.ojeda@intel.com> feat(microservices): Add NATS MessageBus Overview Lists new options, build flag and simple jetstream example. Links to README for complete option listing. Signed-off-by: Alex Ullrich <alex.ullrich@gmail.com> doc: updated the SDK-Go-API.md document to reflect the new functions of DeviceSDKService wrapper Signed-off-by: Marc-Philippe Fuller <marc-philippe.fuller@intel.com> fix: Remove scheduler unused fields and update data dictionary fix edgexfoundry#787 Signed-off-by: Ginny Guan <ginny@iotechsys.com> fix: Escape unintended macro templates, fail docs build on errors (edgexfoundry#814) * fix: Escape marching Jinja test in CLI docs * feat: Make builds fail on macro errors Signed-off-by: Farshid Tavakolizadeh <farshid.tavakolizadeh@canonical.com> feat: add build and run on ARM32 fixes edgexfoundry#685 Signed-off-by: jpwhitemn <jpwhite_mn@yahoo.com> feat: add arm32 doc to nav bar Signed-off-by: jpwhitemn <jpwhite_mn@yahoo.com> feat: Referencing doc pages with latest alias (edgexfoundry#831) Signed-off-by: Farshid Tavakolizadeh <farshid.tavakolizadeh@canonical.com> Co-authored-by: Mengyi Wang <mengyi.wang@canonical.com> docs: Update MQTT example doc Update MQTT example doc for Levski release Close edgexfoundry#64 Signed-off-by: bruce <weichou1229@gmail.com> feat: document core metadata units of measure capability Signed-off-by: Chris Hung <chris@iotechsys.com> fix: Add kong restart step to use new admin token after re-setup Signed-off-by: Farshid Tavakolizadeh <farshid.tavakolizadeh@canonical.com> fix: Correct spelling of autostart option Signed-off-by: Farshid Tavakolizadeh <farshid.tavakolizadeh@canonical.com> feat: update uom configuration example Signed-off-by: Chris Hung <chris@iotechsys.com> feat(microservices): Reading AES256 Protected Data Add note on decrypting payloads protected with AESProtection. Include python code from TAF as an example. Fixes edgexfoundry#784 Signed-off-by: Alex Ullrich <alex.ullrich@gmail.com> fix: Change snap getting started to use consul management token (edgexfoundry#841) Signed-off-by: Farshid Tavakolizadeh <farshid.tavakolizadeh@canonical.com> docs: add management token (edgexfoundry#844) close #3158 Signed-off-by: Valina Li <valina.li@intel.com> Signed-off-by: Valina Li <valina.li@intel.com> feat: Add documentation of the EdgeX MessageBus closes edgexfoundry#744, edgexfoundry#808 Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> feat: Document NATS MessageBus Option Add notes on NATS MessageBus implementation. Signed-off-by: Alex Ullrich <alex.ullrich@gmail.com> Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> fix: Addressed 1st round of PR feedback Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> Update Ch-Metadata.md and TOC. Restored missing line. Fixing up lousy github signoff snafu: Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> docs: add warning to GettingStartedusingDocker.md Signed-off-by: melody <melody@iotechys.com> fix: Correct relative link to snap configuration (edgexfoundry#852) Signed-off-by: Mengyi Wang <mengyi.wang@canonical.com> fix: Fix broken link to docker compose install Docker seems to be actively updating their Compose documention, so the previous link is no longer valid. Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> feat: Create Record and Replay UCR related to edgexfoundry#471 Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> fix: Renamed UCR without a sequence number Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> feat: Added requirements for capturing of Device/Device profiles Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> fix: Addressed PR feedback, restructured & added new requirments Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> fix: Addressed PR feedback for GZIP and timestamp requirment Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> feat: Changed status to Approved Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> refactor: [main] Rework device service list and add new camera device services closes edgexfoundry#850 Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> feat: Document the SecretProvider API for app and device services closes edgexfoundry#847 Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> fix: Correct typo in CommandClient function description Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> feat: Create UCR for Parent-Child Device Relationships Signed-off-by: Tom Brennan ThomasJBrennan@eaton.com If your build fails due to your commit message not passing the build checks, please review the guidelines here: https://github.com/edgexfoundry/edgex-docs/blob/main/.github/Contributing.md PR Checklist Please check if your PR fulfills the following requirements: Changes have been rendered and validated locally using mkdocs-material (see edgex-docs README) Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Fixed the URL complaint/validation failure and added link to this PR. The failure was probably due to CORS since the previous RFC address is forwarded to this new one. Added another Use Case extension. Updated the README for the "local" process to validate and run the mkdocs server, based on my experience. Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Added a separate UCR (edgexfoundry#3) for "Extending" Device Data, since it may end up related. Removed implementation stuff from edgexfoundry#2, and added requirements, per review comments. Added a Use Case extension for "gateway of gateways". Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Update docs_src/design/ucr/0002-Device-Parent-Child-Relationships.md Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Update docs_src/design/ucr/0002-Device-Parent-Child-Relationships.md Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Update docs_src/design/ucr/0002-Device-Parent-Child-Relationships.md Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Update docs_src/design/ucr/0002-Device-Parent-Child-Relationships.md Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Updates based on review comments. Removed the second UCR from this PR. Renamed to remove the 0002 from the filename. Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> feat: Create System Events ADR closes edgexfoundry#581 Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> feat: Addressed PR feedback from Cloud Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> fix: Corrected the TOC description for the ADR Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> fix: Addressed typos and wording from PR reviews Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> fix: Addressed PR feeback - Changed Publish Topic Prifix to be in configuration - Clarified standard topic level vs addition levels for specific use cases - Fixed typos. Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> fix: Changed to use {PublishTopicPrefix} in topic definition Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> feat: Updated status to approved Signed-off-by: Leonard Goodell <leonard.goodell@intel.com> ci: add retry to mkdocs build stage Signed-off-by: Ernesto Ojeda <ernesto.ojeda@intel.com> Updated based on group discussion of this UCR. Primarily updated the requirements section, absolving core services from entanglements in this feature. Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> Updated per review comment, putting burden on core-metadata to remove child devices when the parent is removed. Reverted extraneous suggestion in README.md Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> One more thing to revert in README.md Signed-off-by: Tom Brennan <ThomasJBrennan@eaton.com> feat: Expand section on Provision Watchers (edgexfoundry#598) (edgexfoundry#865) Signed-off-by: Iain Anderson <iain@iotechsys.com> docs: added usb camera streaming guide Signed-off-by: brianointel <brian.j.osburn@intel.com> docs: pr updates Signed-off-by: brianointel <brian.j.osburn@intel.com> docs: updated to use mplayer Signed-off-by: brianointel <brian.j.osburn@intel.com> Update docs_src/examples/Ch-ExamplesUsbDeviceService.md Co-authored-by: Anthony Casagrande <anthony.j.casagrande@intel.com> Signed-off-by: brianointel <brian.j.osburn@intel.com> docs: pr updates Signed-off-by: brianointel <brian.j.osburn@intel.com> docs: pr updates Signed-off-by: Brian Osburn <brian.j.osburn@intel.com> docs: removed link Signed-off-by: Brian Osburn <brian.j.osburn@intel.com> docs: updated formatting Signed-off-by: Brian Osburn <brian.j.osburn@intel.com> docs: updated wording Signed-off-by: Brian Osburn <brian.j.osburn@intel.com> docs: updated capabilities Signed-off-by: brianointel <brian.j.osburn@intel.com>
TomBrennan-Eaton · Sep 27, 2022 · 2b225c9 · 2b225c9
1 parent edf9854
commit 2b225c9
Show file tree

Hide file tree

Showing 38 changed files with 2,087 additions and 311 deletions.
diff --git a/Jenkinsfile b/Jenkinsfile
@@ -23,7 +23,10 @@ pipeline {
                 }
             }
             steps {
-                sh 'mkdocs build'
+                retry(4) {
+                    sh 'mkdocs build'
+                    sh 'sleep 5' // add a little delay to avoid potential rate limiting issues
+                }
 
                 // stash the site contents generated from mkdocs build
                 stash name: 'site-contents', includes: 'docs/**', useDefaultExcludes: false

diff --git a/README.md b/README.md
@@ -33,8 +33,11 @@ In order to render and preview the site locally (without docker) you will need a
 
 1) You will need to install python and pip
 2) After python is installed, you'll need the following python dependencies:
+
 `pip install mkdocs`
 `pip install mkdocs-material==8.2.1`
+
+
 3) Once you have all the pre-reqs installed. You can simply run `mkdocs serve` and view the rendered content locally and makes changes to your documentation and preview them in realtime with a browser at http://0.0.0.0:8001/edgex-docs.
 
 ## Checking for broken links when developing docs

diff --git a/docs/404.html b/docs/404.html
@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<!--
+    This is a special page used by Github Pages when a requested page is not found.
+    The script is misused for redirecting requests that use the "latest" alias to
+    the latest version of a page.
+-->
+<html>
+<head>
+    <title>404 Not Found</title>
+    <script>
+        // redirectToLatest redirects the user agent to the latest version of a 
+        // page by rewriting the path.
+        //
+        // Examples:
+        //   https://docs.edgexfoundry.org/latest is redirected to:
+        //   https://docs.edgexfoundry.org/2.2
+        //
+        //   https://docs.edgexfoundry.org/latest/getting-started/ is redirected to:
+        //   https://docs.edgexfoundry.org/2.2/getting-started/
+        function redirectToLatest()
+        {
+            let req = new XMLHttpRequest();
+            req.open("GET", "/versions.json", false);
+            req.send();
+            if(req.status === 200){
+                let versions = JSON.parse(req.responseText);
+
+                // find the version by alias
+                let res = versions.find(it => {
+                    return it["aliases"].find(alias => {
+                        return alias == "latest";
+                    });
+                });
+
+                if (res && res.version) {
+                    // rewrite the path and replace the alias with version
+                    let pathParts = window.location.pathname.split("/");
+                    pathParts[1] = res.version;
+                    window.location.pathname = pathParts.join("/");
+                } else {
+                    alert("Unable to find version with 'latest' alias.");
+                    return;
+                }
+            } else {
+                alert("Error querying the versions file.");
+                return;
+            }
+        }
+
+        // When the 'latest' alias is in the path, redirect to the actual page
+        // instead of showing the 404 page.
+        if(window.location.pathname.split("/")[1]=="latest"){
+            redirectToLatest();
+        }
+    </script>
+</head>
+<body>
+    <h1>404 Not Found</h1>
+    <p>
+        The requested page was not found.
+    </p>
+    <p>
+        To visit the latest documentation, please visit
+        <a href="https://docs.edgexfoundry.org">https://docs.edgexfoundry.org</a>.
+    </p>
+</body>
+</html>
diff --git a/docs/index.html b/docs/index.html
@@ -1,11 +1,9 @@
 <!DOCTYPE html>
 <html>
 <head>
-  <title>Redirecting</title>
-  <script>
-    window.location.replace("2.2");
-  </script>
+    <meta http-equiv="refresh" content="0; url=/latest">
 </head>
 <body>
+  Redirecting to latest...
 </body>
-</html>
+</html>
diff --git a/docs/versions.json b/docs/versions.json
@@ -4,6 +4,6 @@
   { "version": "1.3", "title": "1.3-Hanoi", "aliases": [] },
   { "version": "2.0", "title": "2.0-Ireland", "aliases": [] },
   { "version": "2.1", "title": "2.1-Jakarta", "aliases": [] },
-  { "version": "2.2", "title": "2.2-Kamakura", "aliases": [] },
+  { "version": "2.2", "title": "2.2-Kamakura", "aliases": ["latest"] },
   { "version": "2.3", "title": "2.3-Levski", "aliases": [] }
 ]
diff --git a/docs_src/design/TOC.md b/docs_src/design/TOC.md
@@ -1,13 +1,16 @@
 # Use Cases and Design Records
 
 ## Use Case Records (UCRs)
+
+!!! note 
+    UCRs are listed in alphabetical order by title.
+
 | Name/Link                                                                 | Short Description                                             |
 |---------------------------------------------------------------------------|---------------------------------------------------------------|
-| [0001 System Events for Devices](./ucr/0001-System-Events-for-Devices.md) | Use Case for System Events for Device add/update/delete |
-| [0002 Device Parent-Child Relationships](./ucr/0002-Device-Parent-Child-Relationships.md) | Use Case for Device Parent-Child Relationships |
-| [0003 Extending Device Data](./ucr/0003-Extending-Device-Data.md) | Use Case for Application Services Extending Device Data |
-| [0004 Provision Watch more Device Properties](./ucr/0004-Provision-Watch-more-Device-Properties.md) | Use Case for Provision Watching via Additional Device Properties  |
-| [0005 Hybrid App-Device Services](./ucr/0005-Hybrid-App-Device-Services.md) | Use Case for describing a hybrid of App and Device Services |
+| [Device Parent-Child Relationships](./ucr/Device-Parent-Child-Relationships.md) | Use Case for Device Parent-Child Relationships |
+| [Provision Watch via Device Metadata](./ucr/Provision-Watch-via-Device-Metadata.md) | Use Case for Provision Watching via Additional Device Metadata |
+| [Record and Replay](./ucr/Record-and-Replay.md)    | Use Case for Recording and Replaying event/readings     |
+| [System Events for Devices](./ucr/System-Events-for-Devices.md) | Use Case for System Events for Device add/update/delete |
 
 ## Architectural Design Records (ADRs)
 

diff --git a/docs_src/design/ucr/0004-Provision-Watch-more-Device-Properties.md b/docs_src/design/ucr/0004-Provision-Watch-more-Device-Properties.md
diff --git a/docs_src/design/ucr/Device-Parent-Child-Relationships.md b/docs_src/design/ucr/Device-Parent-Child-Relationships.md
@@ -0,0 +1,127 @@
+## Device Parent-Child Relationships
+This UCR describes Use Cases for new Device metadata for Parent to Child Relationships for a given Device.
+
+### Submitters
+- Tom Brennan (Eaton)
+
+## Change Log
+- [pending](https://github.com/edgexfoundry/edgex-docs/pull/800) (2022-08-22)
+
+
+### Market Segments
+Any that deploy EdgeX systems to manage multiple devices.
+In particular, Industrial Gateway systems that connect to multiple south-bound devices
+and provide their data to north-bound services.
+
+### Motivation
+It is frequently important to north-bound services to know the parent-child relationships
+of the devices found in an EdgeX system. 
+This information is generally used for either protocol data constructs or for display purposes.
+
+If not know or provided by the south-bound Device Service, this information might be added 
+to the Device instance's metadata by the north-bound or analytics services, or by the user.
+
+It is desirable that the means of conveying this information become standardized for those systems
+which provide and use it, so that application services can rely on it, hence proposing here that there 
+be a common definition and usage of this metadata.
+
+### Target Users
+- Product Developers
+- Device Owner
+- Device User
+- Device Maintainer
+- Cloud User
+- Service Provider
+- Software Integrator
+
+### Description
+Some north-bound protocols and some UI designs present the system devices in a hierarchial manner, 
+where it is necessary to know which devices are parents and which are their children.
+
+These considerations are most important for gateways that are implemented with the EdgeX framework,
+since there are potentially many south-bound devices connected to a system.
+
+Examples are
+* North-bound BACnet Service - where only one "main" device is present at the point of external connection (eg, UDP port 
+0xBAC0) and all other devices must be presented as "virtually routed devices" connected to that main "virtual router" device.
+* Azure IoT Hub - where the normal connection for IoT Plug and Play / Digital Twin is for a single device, and any other devices need to somehow fall under that device (eg, with Device Twin "Modules")
+* UI device presentation - where child devices can be shown grouped under their parent, often rolled up until they are expanded to show their data
+* Multi-tenant deployments of multi-point energy meters - where a main meter has up to 80 Branch Circuit Monitoring (BCM) points connected to it, each BCM modeled as a Device consisting of the same 6 or so energy channels (Device Resources), and each BCM is assigned to a particular tenant. Tenants will be given access to the data from their BCM point(s) but not those of other tenants. A gateway may connect more than one of these multi-point energy meters.
+
+Since there are multiple similar uses for this relationship information on the north side, it is proposed to locate
+this relationship metadata in the Device object as accessed from core-metadata by all services, rather than to 
+locate it in each north-bound service (which would be particularly problematic for the UI, which gets its data through REST APIs).
+
+The south-bound Device Service that creates a Device is ideally the service which establishes this relationship data, though it is possible that it is unaware of the parent-child relationship. It should be permitted, therefore, for this relationship information to also be set by north-bound services (most likely the UI) and simply ignored by the south-bound Device Service.
+
+It is also necessary to indicate which device is the "main" or "publisher" device (ie, the gateway device), 
+as any devices without a configured relationship can be inferred to be children of that device.
+
+It is frequently a pattern in data servers to "walk the device tree", starting with the main device, then 
+recursively processing its direct child devices, and then the child devices (if any) of those devices, until
+all devices have been processed. This is normally part of the initialization of device data for a server,
+since the parent must be processed and initialized before its child devices. Consequently, there is a need
+for a means to answer the question "What are the child devices (if any) of device x.y.z?"; this is commonly done
+either with the device structure listing its children, or by providing a query that can answer this question.
+
+### Extensions to the main Use Case
+1. Some services add "devices" which have no physical counterpart, eg, for an NTP client service where the "device" 
+serves simply as a container for the Resources necessary to configure and report the status of the service.
+In these cases, it would be helpful for the other services if it described itself as something like a "system" device,
+meaning one that doesn't have a physical (south-bound or hardware) counterpart.
+2. Multi-level systems, such as a "gateway of gateways", which aggregate a large number of devices. The parent
+property will be useful for assisting to arrange the devices in a hierarchy that corresponds to their physical hierarchy. 
+In this situation, the parent property of a lower-level gateway will indicate the upper gateway it is connected to.
+
+### Existing solutions
+The Device structure in Eaton's legacy products indicated this parent-child relationship bidirectionally: each device indicated its parent device (if any) with one field, and its child devices (if any) with a list of IDs.
+
+The Device structure in Eaton's cloud solution is a "DeviceTree", which is a recursive, hierarchial structure of the connected devices, starting with the "publisher" device and its first-level child devices.
+
+There is the BACnet "virtual routed devices" model, but I would not recommend it, as it is too convoluted for this  simple relationship.
+
+The existing EdgeX UIs group devices by their Device Service, which is a good approach for simple devices without children of their own, but fails if those devices have child devices too.
+
+### Requirements
+1. Each device instance should have an optional "relationship" metadata property which can be used to indicate which other device is its parent device. 
+2. This relationship property is a "convenience feature" provided by EdgeX, which is *informative* to application services,
+but does not require core EdgeX services to respond to it, or act on it, in any way, 
+other than storing it and making it available.
+3. This property will be kept in the Device structure in core-metadata.
+4. Though it is preferred that the owning Device Service set a device's parent property, this property can also be set
+by users via the core-metadata PATCH devices API. The owning Device Service can ignore this update if it does
+not use the parent property.
+5. The same relationship property, or a similar addition, shall be used to indicate the one "main" device in a system.
+6. It is required that the "main" device be indicated in any multi-device system.
+7. If a device does not indicate which is its parent device, then it shall be inferred that its parent is the main device. (This helps with backwards compatability.)
+8. The same relationship property, or a similar addition, shall be used to indicate when a Device is a "system" Device,
+that is, one without an external physical presence, such as a container for a service's Resources.
+9. These parent-child requirements do not apply for the case of a single device configuration.
+10. Some means shall be provided to answer the question, "What are the child devices (if any) of device x.y.z?".
+11. There can be multiple levels (eg, child devices of a child device).
+12. Each child device can have only have one parent device.
+13. The core-metadata service must remove all of the child devices if a parent device is removed.
+
+Not a requirement: inheritance of device status via the parent-child relationship. Apparently this was a point
+over which past consideration of parent-child relationships in EdgeX foundered, but it seems complicated
+for independent services, and can generally be inferred by other services anyway.
+
+### Other Related Issues
+Use Case for Application Services Extending Device Data [Extending Device Data](https://github.com/edgexfoundry/edgex-docs/pull/845) *later (./Extending-Device-Data.md)* may be related, 
+as, depending on its solution, it may have to indicate a different Device Relationship ("Extends").
+
+### References
+- [Azure IoT Edge Gateways and Child Devices](https://docs.microsoft.com/en-us/azure/iot-edge/how-to-connect-downstream-iot-edge-device?view=iotedge-2020-11&tabs=azure-portal)
+
+- BACnet Virtual Devices: The full BACnet spec is paywalled by ASHRAE. But the relevant snippet
+is from Annex H, section **H.1.1.2 Multiple "Virtual" BACnet Devices in a Single Physical Device**:
+
+> A BACnet device is one that possesses a Device object and communicates using the procedures specified in this
+standard. In some instances, however, it may be desirable to model the activities of a physical building automation 
+and control device through the use of more than one BACnet device. Each such device will be referred to as a virtual 
+BACnet device. This can be accomplished by configuring the physical device to act as a router to one or more virtual 
+BACnet networks. The idea is that each virtual BACnet device is associated with a unique DNET and DADR pair, 
+i.e. a unique BACnet address. The physical device performs exactly as if it were a router between physical BACnet 
+networks.
+
+