From a33f9790b7f47c87e0d3afa28b06c686f1b8ef44 Mon Sep 17 00:00:00 2001 From: Joe Pearson Date: Mon, 6 Apr 2020 08:57:15 -0400 Subject: [PATCH 1/2] added page showing device data fixed broken documentation links add link from page 4 to page 5 Signed-off-by: Joe Pearson --- hub/04-configure-anax.md | 4 +- hub/05-view-device-data.md | 92 ++++++++++++++++++++++++++++++++++++++ hub/README.md | 3 +- 3 files changed, 96 insertions(+), 3 deletions(-) create mode 100644 hub/05-view-device-data.md diff --git a/hub/04-configure-anax.md b/hub/04-configure-anax.md index c73291d..d24b391 100644 --- a/hub/04-configure-anax.md +++ b/hub/04-configure-anax.md @@ -160,6 +160,6 @@ And once the agreement is finalized, you should be able to see the containers ru sudo docker ps ``` ------ +# Next -## The End +[View the Device Data](05-view-device-data.md). diff --git a/hub/05-view-device-data.md b/hub/05-view-device-data.md new file mode 100644 index 0000000..1bc49a4 --- /dev/null +++ b/hub/05-view-device-data.md @@ -0,0 +1,92 @@ + + +# View the Device Data + +Now that EdgeX Foundry is running on your Edge Node and the [Random Integer Device Service](https://docs.edgexfoundry.org/1.2/examples/Ch-ExamplesRandomDeviceService/) is posting a simple random event message every five seconds, let's explore ways to view that data. We'll then modify the interval and range of values and see it change in reponse. + +## Ensure everything is functioning normally + +Let's open a shell to the environment that is running the Horizon Agent (Anax). To confirm that it is the correct location and Horizon is operating properly, check the version: + +``` bash +hzn version +``` + +It should respond with something similar to this: + +``` bash +Horizon CLI version: 2.25.0 +Horizon Agent version: 2.25.0 +``` + +Check to ensure that the `edgex_1.0.1_amd64` Service is running and your Edge Node is properly configured: + +``` bash +hzn node list | jq '.configstate' +``` + +You should see output similar to this: + +``` bash +{ + "state": "configured", + "last_update_time": "2020-04-04 07:37:39 -0700 PDT" +} +``` + +And last, let's ask Docker to show us the running images: + +``` bash +docker ps +``` + +Which should return something like this: + +``` bash +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +4b764ec9140c edgexfoundry/docker-core-metadata-go "/core-metadata --re…" 6 hours ago Up 6 hours 0.0.0.0:48081->48081/tcp, 48082/tcp 1a85b4ce42a70ca27b0d1eee80c154e56ca8dda50f41199ccb4ec5e253a9c1cd-edgex-core-metadata +1c1b59fe238c edgexfoundry/docker-core-data-go "/core-data --regist…" 6 hours ago Up 6 hours 0.0.0.0:5563->5563/tcp, 0.0.0.0:48080->48080/tcp 1a85b4ce42a70ca27b0d1eee80c154e56ca8dda50f41199ccb4ec5e253a9c1cd-edgex-core-data +d88ec30ecb59 edgexfoundry/docker-core-command-go "/core-command --reg…" 6 hours ago Up 6 hours 0.0.0.0:48082->48082/tcp 1a85b4ce42a70ca27b0d1eee80c154e56ca8dda50f41199ccb4ec5e253a9c1cd-edgex-core-command +8803a65bb1de edgexfoundry/docker-support-logging-go "/support-logging --…" 6 hours ago Up 6 hours 0.0.0.0:48061->48061/tcp 1a85b4ce42a70ca27b0d1eee80c154e56ca8dda50f41199ccb4ec5e253a9c1cd-edgex-support-logging +e3c0775618c7 edgexfoundry/docker-edgex-mongo "docker-entrypoint.s…" 6 hours ago Up 6 hours 0.0.0.0:27017->27017/tcp 1a85b4ce42a70ca27b0d1eee80c154e56ca8dda50f41199ccb4ec5e253a9c1cd-edgex-mongo +af4e5e061f49 edgexfoundry/docker-edgex-volume "/bin/sh -c '/usr/bi…" 6 hours ago Up 6 hours 1a85b4ce42a70ca27b0d1eee80c154e56ca8dda50f41199ccb4ec5e253a9c1cd-edgex-files +a9517da05d16 edgexfoundry/docker-device-random-go "/device-random --pr…" 6 hours ago Up 6 hours 0.0.0.0:49988->49988/tcp 1a85b4ce42a70ca27b0d1eee80c154e56ca8dda50f41199ccb4ec5e253a9c1cd-edgex-device-random +``` + +Verify that you see seven images, and that CREATED and STATUS columns show that none of them are restarting. + +## View the data + +According to the documentation, you could request the URL for Core Data, but that will show you all of the events and readings since the Service was started, which could get quite long: + +``` bash +curl --silent http://localhost:48080/api/v1/event | jq +``` + +We can further limit the results with `jq` to show us only the most recent reading: + +``` bash +curl --silent http://localhost:48080/api/v1/event | jq .[0].readings[0].value +``` + +Core Metadata will show us the properties of the Device: + +``` bash +curl --silent http://localhost:48081/api/v1/device | jq .[0].service +``` + +## Modify the Device Settings + +The initial configuration of the Device is specified in the [./hub/res/device-random-config.toml](Device Random Configuration TOML file). Properties within can be divided into those that can be updated without restarting the service (writable) and those that will not take effect until the Service is restarted (read-only). + +### Writable Settings + +The Core Command provides a PUT endpoint that will allow you to modify a Device configuration to alter future reading values. + +### Read-only Settings + +Persisted settings are stored in Consul in a typical EdgeX Foundry installation, and should be modified there. EdgeX provides several methods to update those values. In this case, we are using TOML files to configure services, and thus you will need to update the [./hub/res/device-random-config.toml](Device Random Configuration TOML file) to change those value. A restart of the Service will then be required for the changes to take effect. + +----- + +## The End diff --git a/hub/README.md b/hub/README.md index 809b54e..91c4251 100644 --- a/hub/README.md +++ b/hub/README.md @@ -14,7 +14,7 @@ This is a set of instructions to demonstrate one method for using the [Open Hori ## Background -The EdgeX Foundry instance will contain a [Random Integer Device Service](https://docs.edgexfoundry.org/Ch-ExamplesRandomDeviceService.html) that will post a simple random event message every five seconds. +The EdgeX Foundry instance will contain a [Random Integer Device Service](https://docs.edgexfoundry.org/1.2/examples/Ch-ExamplesRandomDeviceService/) that will post a simple random event message every five seconds. > Caveat Emptor: This document will give you the steps needed to get a small dev instance of the Horizon services running. It will not, and should not, be used to serve edge devices in a production environment. However, it is sufficient to test services. @@ -42,6 +42,7 @@ You will register the device that is running the Agent as an edge node with the 2. [Build and Run](02-build-and-run-horizon.md) the Open Horizon Services 3. [Install the Open Horizon Agent](03-install-agent.md) software 4. [Configure the Agent](04-configure-anax.md) +5. [View the Device Data](05-view-device-data.md) ## FAQ From 5b2e15eb27a5f8eb8cb9cdaa6972c31682465c7f Mon Sep 17 00:00:00 2001 From: Joe Pearson Date: Tue, 7 Apr 2020 14:30:33 -0400 Subject: [PATCH 2/2] Made changes per Booz comments Also added placeholder for next set of instructions. Signed-off-by: Joe Pearson --- hub/05-view-device-data.md | 48 +++++++++++++++++++++++++++++++------- hub/06-add-the-sma.md | 6 +++++ 2 files changed, 46 insertions(+), 8 deletions(-) create mode 100644 hub/06-add-the-sma.md diff --git a/hub/05-view-device-data.md b/hub/05-view-device-data.md index 1bc49a4..2283412 100644 --- a/hub/05-view-device-data.md +++ b/hub/05-view-device-data.md @@ -2,7 +2,7 @@ # View the Device Data -Now that EdgeX Foundry is running on your Edge Node and the [Random Integer Device Service](https://docs.edgexfoundry.org/1.2/examples/Ch-ExamplesRandomDeviceService/) is posting a simple random event message every five seconds, let's explore ways to view that data. We'll then modify the interval and range of values and see it change in reponse. +Now that EdgeX Foundry (EXF) is running on your Edge Node and the [Random Integer Device Service](https://docs.edgexfoundry.org/1.2/examples/Ch-ExamplesRandomDeviceService/) is posting a simple random event message every five seconds, let's explore ways to view that data. We'll then modify the interval and range of values and see it change in reponse. ## Ensure everything is functioning normally @@ -19,7 +19,7 @@ Horizon CLI version: 2.25.0 Horizon Agent version: 2.25.0 ``` -Check to ensure that the `edgex_1.0.1_amd64` Service is running and your Edge Node is properly configured: +Check to ensure that your Edge Node is properly configured: ``` bash hzn node list | jq '.configstate' @@ -34,7 +34,27 @@ You should see output similar to this: } ``` -And last, let's ask Docker to show us the running images: +Then check to ensure that the `com.github.joewxboy.horizon.edgex` Service is running: + +``` bash +hzn service list +``` + +You should see output like this: + +``` json +[ + { + "url": "com.github.joewxboy.horizon.edgex", + "org": "mycluster", + "version": "1.0.1", + "arch": "amd64", + "variables": {} + } +] +``` + +And last, let's ask Docker to show us the running images contained within that Service: ``` bash docker ps @@ -57,7 +77,9 @@ Verify that you see seven images, and that CREATED and STATUS columns show that ## View the data -According to the documentation, you could request the URL for Core Data, but that will show you all of the events and readings since the Service was started, which could get quite long: +Now that you've verified that Open Horizon has deployed EXF, it's time to use EXF to view the events and readings that the Random Integer Device Service is sending. + +According to the EXF documentation, you could request the URL for Core Data, but that will show you all of the events and readings since the Service was started, which could get quite long: ``` bash curl --silent http://localhost:48080/api/v1/event | jq @@ -77,7 +99,7 @@ curl --silent http://localhost:48081/api/v1/device | jq .[0].service ## Modify the Device Settings -The initial configuration of the Device is specified in the [./hub/res/device-random-config.toml](Device Random Configuration TOML file). Properties within can be divided into those that can be updated without restarting the service (writable) and those that will not take effect until the Service is restarted (read-only). +The initial configuration of the Device is specified in the [Device Random Configuration TOML file](./hub/res/device-random-config.toml). Properties within can be divided into those that can be updated without restarting the service (writable) and those that will not take effect until the Service is restarted (read-only). See [Configuration and Registry](https://docs.edgexfoundry.org/1.2/microservices/configuration/Ch-Configuration/#readable-vs-writable-settings) for more information on this topic. ### Writable Settings @@ -85,8 +107,18 @@ The Core Command provides a PUT endpoint that will allow you to modify a Device ### Read-only Settings -Persisted settings are stored in Consul in a typical EdgeX Foundry installation, and should be modified there. EdgeX provides several methods to update those values. In this case, we are using TOML files to configure services, and thus you will need to update the [./hub/res/device-random-config.toml](Device Random Configuration TOML file) to change those value. A restart of the Service will then be required for the changes to take effect. +Persisted settings are stored in Consul in a typical EdgeX Foundry installation, and should be modified there. EdgeX provides several methods to update those values. In this case, we are using TOML files to configure services, and thus you will need to update the [Device Random Configuration TOML file](./hub/res/device-random-config.toml) to change those value. A restart of the Service will then be required for any changes to take effect. + +### Restarting an EXF Service + +If you had the System Management Agent (SMA) installed you could simply POST a restart action to the appropriate endpoint ([restart a service](https://docs.edgexfoundry.org/1.2/microservices/system-management/agent/Ch_SysMgmtAgent/#restart-a-service)) to initiate a graceful restart of that specific micro-service. However, we do not have the SMA in our current example. + +You could use Open Horizon to restart the Service, but that would introduce two complications. First, we populated the configuration from a static, external file. For the settings to persist, we'd need to edit that file before restarting. Second, we defined the EXF orchestration as a single Horizon Service, which means that you'd have to restart the whole instance of seven Docker images. + +Or you could `ssh` to the machine and use the Docker CLI to kill the process and rely on Open Horizon to restart it for you automatically. While this approach works well, it is not graceful, does not solve the persistence issue, and violates the spirit of Open Horizon in that we're attempting to prevent an administrator from needing to log onto individual Devices in the first place. + +Potential ways forward include refactoring the example so that individual EXF micro-services are implemented as individual Open Horizon Services, or adding the SMA to the Open Horizon Service definition. ------ +# Next -## The End +[Add the SMA to the Service Definition](06-add-the-sma.md). diff --git a/hub/06-add-the-sma.md b/hub/06-add-the-sma.md new file mode 100644 index 0000000..1a9f348 --- /dev/null +++ b/hub/06-add-the-sma.md @@ -0,0 +1,6 @@ +# Add the SMA to the Service Definition + + +----- + +## The End