From 77e124ad1ef2bfae603acddb8d196f8ddf2c1f0e Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Tue, 5 Sep 2023 17:06:37 -0700 Subject: [PATCH 01/11] docs: docs for native remote deployment example added Signed-off-by: preethi-satishcandra --- .../device/remote/Ch-RemoteNonSecure.md | 153 ++++++++++++++++++ .../device/remote/Ch-RemoteSecure.md | 1 + mkdocs.yml | 3 + 3 files changed, 157 insertions(+) create mode 100644 docs_src/microservices/device/remote/Ch-RemoteNonSecure.md create mode 100644 docs_src/microservices/device/remote/Ch-RemoteSecure.md diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md new file mode 100644 index 0000000000..dae1d9534a --- /dev/null +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -0,0 +1,153 @@ +# Non-Secure Mode + +## Remote deployment of device services in non-secure mode +Usually microservices are deployed using multiple nodes for scalability, availability and performance +instead of running all services in one node. + +This page provides an example of remote deployment of `device-usb-camera` service using multiple nodes in non-secure mode. +The deployment can be done by running the service `natively` or by running it in `docker`. + +## Example +This example uses 2 nodes for remote deployment. One node (remote) is used to run all Edgex core services in docker and the other node (host) +for running the device-usb-camera service natively or in docker. Both the nodes are on the same network. +This example can be further expanded to run multiple instances of device-usb-camera service in multiple nodes. + +## Running of the example + +1. Set up the two nodes to be ready for remote deployment. Refer [USB Service Setup](../supported/device-usb-camera/walkthrough/setup.md) + for system requirements and dependencies such as Git, Docker, Docker compose, etc. Additional to this Golang needs to be installed + in the host node where the device-usb-camera service will be built and run natively. + +1. Next step is to install Edgex compose in the remote node which will be used to run all Edgex core services. So clone the `edgex-compose` + repository: + + ```bash + git clone https://github.com/edgexfoundry/edgex-compose.git + ``` + +1. Checkout the required version: + + ```bash + git checkout {{version}} + ``` + +1. Update the `docker-compose-no-secty.yml` file by changing the `host_ip` address of all the Edgex core services to the remote node ip address. + Non-Edgex core services such as device-rest, device-virtual, app-rules-engine, etc. can be removed or commented out if needed. + +1. Run Edgex core services: + + ```bash + make run no-secty + ``` + + 1. Verify the services are up and running: + + ```bash + docker ps + ``` + +1. Follow this guide to run the `device-usb-camera` service in docker or natively. + +=== "Docker" + + Todo + +=== "Native" + + 1. Clone the `device-usb-camera` service repository + + ```bash + git clone https://github.com/edgexfoundry/device-usb-camera.git + ``` + + 1. Checkout the required version + + ```bash + git checkout {{version}} + ``` + + 1. cd into `/cmd/res` directory + + ```bash + cd /cmd/res + ``` + + 1. Modify the `configuration.yml` file in the repo to run natively. Uncomment out the required parts as directed in the file. + Update the yml file with the `Host` and `Remote` node ip addresses.All the + localhosts in the yml file need to be replaced by the applicable host and remote ip addresses. + + 1. cd back into `cmd` directory + + ```bash + cd.. + ``` + + 1. For RTSP streaming get [rtsp-simple-server](https://github.com/bluenviron/mediamtx/releases) binary + and rtsp config yml file and copy them into the `cmd` directory + + 1. Build the service from the `main` directory. + + ```bash + cd .. + make build + ``` + + 1. Run the service + + ```bash + EDGEX_SECURITY_SECRET_STORE=false ./cmd/device-usb-camera -cp=consul.http://:8500 -o + ``` + + !!! note + If multiple instances of the service has to be run then attach `-i` followed by the number of instances desired. E.g: + ```bash + EDGEX_SECURITY_SECRET_STORE=false ./cmd/device-usb-camera -cp=consul.http://:8500 -o -i 2 + ``` + + 1. Make sure the service has no errors and it discovers connected usb devices after some time. + + + 1. Verify device(s) have been successfully added to core-metadata. + + ```bash + curl -s http://:59881/api/v3/device/all | jq -r '"deviceName: " + '.devices[].name'' + ``` + + Example Output: + + ```bash + deviceName: NexiGo_N930AF_FHD_Webcam_NexiG-20201217010 + ``` + + 1. Add credentials for RTSP streaming by referring to [RTSP Stream Credentials](../supported/device-usb-camera/walkthrough/deployment.md#add-credentials-for-the-rtsp-stream). + Make sure to use correct host IP address in the POST request instead of localhost. + + 1. Follow [USB Service API Guide](../supported/device-usb-camera/walkthrough/general-usage.md) to execute APIs such as Streaming. Again make sure to replace localhost with the applicable + host or remote IP addresses. + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs_src/microservices/device/remote/Ch-RemoteSecure.md b/docs_src/microservices/device/remote/Ch-RemoteSecure.md new file mode 100644 index 0000000000..2f0f6a1884 --- /dev/null +++ b/docs_src/microservices/device/remote/Ch-RemoteSecure.md @@ -0,0 +1 @@ +# Secure Mode diff --git a/mkdocs.yml b/mkdocs.yml index 67187d1100..9821de0a30 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -137,6 +137,9 @@ nav: - './microservices/device/supported/device-usb-camera/supplementary-info/advanced-options.md' - Device Virtual: - './microservices/device/supported/device-virtual/Ch-VirtualDevice.md' + - Remote Deployment: + - './microservices/device/remote/Ch-RemoteNonSecure.md' + - './microservices/device/remote/Ch-RemoteSecure.md' - './microservices/device/V3Migration.md' - Application Services: - Introduction: './microservices/application/ApplicationServices.md' From 6c55f4434217396b8522a269f93b5241367763c4 Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Tue, 5 Sep 2023 17:09:31 -0700 Subject: [PATCH 02/11] docs: removed unused lines Signed-off-by: preethi-satishcandra --- .../device/remote/Ch-RemoteNonSecure.md | 22 ------------------- 1 file changed, 22 deletions(-) diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md index dae1d9534a..f767475757 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -129,25 +129,3 @@ This example can be further expanded to run multiple instances of device-usb-cam - - - - - - - - - - - - - - - - - - - - - - From e6184aea8ac5e546da65edef9886c56d8462db99 Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Wed, 6 Sep 2023 09:38:28 -0700 Subject: [PATCH 03/11] docs: added note on ffmpeg version Signed-off-by: preethi-satishcandra --- docs_src/microservices/device/remote/Ch-RemoteNonSecure.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md index f767475757..1cbee58dee 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -122,6 +122,9 @@ This example can be further expanded to run multiple instances of device-usb-cam 1. Add credentials for RTSP streaming by referring to [RTSP Stream Credentials](../supported/device-usb-camera/walkthrough/deployment.md#add-credentials-for-the-rtsp-stream). Make sure to use correct host IP address in the POST request instead of localhost. + !!! note + The node used for rtsp streaming should have FFMPEG version of 5.0 atleast. + 1. Follow [USB Service API Guide](../supported/device-usb-camera/walkthrough/general-usage.md) to execute APIs such as Streaming. Again make sure to replace localhost with the applicable host or remote IP addresses. From 4e3ec62e0eb72e1dd2e0d04e4f0db3af0943305f Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Tue, 19 Sep 2023 15:46:33 -0700 Subject: [PATCH 04/11] docs: updated the overview and setup section Signed-off-by: preethi-satishcandra --- .../device/remote/Ch-RemoteNonSecure.md | 25 +++++++++++-------- .../device/remote/Ch-RemoteSecure.md | 2 +- mkdocs.yml | 4 +-- 3 files changed, 17 insertions(+), 14 deletions(-) diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md index 1cbee58dee..540c0da173 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -1,24 +1,23 @@ -# Non-Secure Mode +# Remote deployment of device services in non-secure mode -## Remote deployment of device services in non-secure mode Usually microservices are deployed using multiple nodes for scalability, availability and performance instead of running all services in one node. -This page provides an example of remote deployment of `device-usb-camera` service using multiple nodes in non-secure mode. +This page provides an example of remote deployment of [device-usb-camera](../services/device-usb-camera/General.md) service using multiple nodes in non-secure mode. The deployment can be done by running the service `natively` or by running it in `docker`. ## Example -This example uses 2 nodes for remote deployment. One node (remote) is used to run all Edgex core services in docker and the other node (host) -for running the device-usb-camera service natively or in docker. Both the nodes are on the same network. -This example can be further expanded to run multiple instances of device-usb-camera service in multiple nodes. +This example uses 2 nodes for remote deployment. One of the nodes (host) is used to run all Edgex core services in docker and the other node (remote) +for running the device-usb-camera service either natively or in docker. Both the nodes are on the same network. +This example can be further extended to run multiple instances of device-usb-camera service in multiple nodes. ## Running of the example -1. Set up the two nodes to be ready for remote deployment. Refer [USB Service Setup](../supported/device-usb-camera/walkthrough/setup.md) +1. Set up the two nodes to be ready for remote deployment. Refer [USB Service Setup](../services/device-usb-camera/walkthrough/setup.md) for system requirements and dependencies such as Git, Docker, Docker compose, etc. Additional to this Golang needs to be installed - in the host node where the device-usb-camera service will be built and run natively. + in the remote node where the device-usb-camera service will be built and run natively. -1. Next step is to install Edgex compose in the remote node which will be used to run all Edgex core services. So clone the `edgex-compose` +1. Next step is to install [Edgex compose](https://github.com/edgexfoundry/edgex-compose) in the host node which will be used to run all Edgex core services. So clone the `edgex-compose` repository: ```bash @@ -28,10 +27,14 @@ This example can be further expanded to run multiple instances of device-usb-cam 1. Checkout the required version: ```bash - git checkout {{version}} + git checkout {{edgexversion}} ``` -1. Update the `docker-compose-no-secty.yml` file by changing the `host_ip` address of all the Edgex core services to the remote node ip address. +1. Update the [docker-compose-no-secty.yml](https://github.com/edgexfoundry/edgex-compose/blob/main/docker-compose-no-secty.yml) file by removing the `host_ip` section of all the Edgex core services. E.g. + ```bash + host_ip: 127.0.0.1 + ``` + The example line provided above should be removed from the services, the host_ip will be provided while running the usb service. Non-Edgex core services such as device-rest, device-virtual, app-rules-engine, etc. can be removed or commented out if needed. 1. Run Edgex core services: diff --git a/docs_src/microservices/device/remote/Ch-RemoteSecure.md b/docs_src/microservices/device/remote/Ch-RemoteSecure.md index 2f0f6a1884..7b983a3d4c 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteSecure.md @@ -1 +1 @@ -# Secure Mode +# Remote deployment of device services in secure mode diff --git a/mkdocs.yml b/mkdocs.yml index 0cafeeb357..e8ac26204c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -111,8 +111,8 @@ nav: - microservices/device/services/device-usb-camera/supplementary-info/advanced-options.md - Device Virtual: microservices/device/services/device-virtual/Ch-VirtualDevice.md - Remote Deployment: - - ./microservices/device/remote/Ch-RemoteNonSecure.md - - ./microservices/device/remote/Ch-RemoteSecure.md + - Non-Secure Mode: microservices/device/remote/Ch-RemoteNonSecure.md + - Secure Mode: microservices/device/remote/Ch-RemoteSecure.md - V3 Migration: microservices/device/V3Migration.md - Application: - Overview: microservices/application/ApplicationServices.md From 669131dd6aa859fc9380f73b2293432a0c887b25 Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Tue, 19 Sep 2023 18:29:08 -0700 Subject: [PATCH 05/11] docs: updated the running guide section and addressed draft code review comments Signed-off-by: preethi-satishcandra --- .../device/remote/Ch-RemoteNonSecure.md | 58 +++++++------------ 1 file changed, 21 insertions(+), 37 deletions(-) diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md index 540c0da173..1885aed4bf 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -4,20 +4,20 @@ Usually microservices are deployed using multiple nodes for scalability, availab instead of running all services in one node. This page provides an example of remote deployment of [device-usb-camera](../services/device-usb-camera/General.md) service using multiple nodes in non-secure mode. -The deployment can be done by running the service `natively` or by running it in `docker`. +The deployment can be done by running the service `natively` or by running it in `Docker`. ## Example -This example uses 2 nodes for remote deployment. One of the nodes (host) is used to run all Edgex core services in docker and the other node (remote) -for running the device-usb-camera service either natively or in docker. Both the nodes are on the same network. +This example uses 2 nodes for remote deployment. One of the nodes (host) is used to run all EdgeX core services in Docker and the other node (remote) +for running the device-usb-camera service either natively or in Docker. Both the nodes are on the same network. This example can be further extended to run multiple instances of device-usb-camera service in multiple nodes. ## Running of the example -1. Set up the two nodes to be ready for remote deployment. Refer [USB Service Setup](../services/device-usb-camera/walkthrough/setup.md) - for system requirements and dependencies such as Git, Docker, Docker compose, etc. Additional to this Golang needs to be installed +1. Set up the two nodes to be ready for remote deployment. Refer to [USB Service Setup](../services/device-usb-camera/walkthrough/setup.md) + for system requirements and dependencies such as Git, Docker, Docker Compose, etc. Additionally Golang needs to be installed in the remote node where the device-usb-camera service will be built and run natively. -1. Next step is to install [Edgex compose](https://github.com/edgexfoundry/edgex-compose) in the host node which will be used to run all Edgex core services. So clone the `edgex-compose` +1. Next step is to install [EdgeX compose](https://github.com/edgexfoundry/edgex-compose) in the host node which will be used to run all EdgeX core services. So clone the `edgex-compose` repository: ```bash @@ -49,7 +49,7 @@ This example can be further extended to run multiple instances of device-usb-cam docker ps ``` -1. Follow this guide to run the `device-usb-camera` service in docker or natively. +1. Follow this guide to run the `device-usb-camera` service in Docker or natively. === "Docker" @@ -57,60 +57,44 @@ This example can be further extended to run multiple instances of device-usb-cam === "Native" - 1. Clone the `device-usb-camera` service repository + 1. Clone the [device-usb-camera](https://github.com/edgexfoundry/device-usb-camera) service repository: ```bash git clone https://github.com/edgexfoundry/device-usb-camera.git ``` - 1. Checkout the required version + 1. Checkout the required version: ```bash - git checkout {{version}} - ``` - - 1. cd into `/cmd/res` directory - - ```bash - cd /cmd/res - ``` - - 1. Modify the `configuration.yml` file in the repo to run natively. Uncomment out the required parts as directed in the file. - Update the yml file with the `Host` and `Remote` node ip addresses.All the - localhosts in the yml file need to be replaced by the applicable host and remote ip addresses. - - 1. cd back into `cmd` directory - - ```bash - cd.. + git checkout {{edgexversion}} ``` 1. For RTSP streaming get [rtsp-simple-server](https://github.com/bluenviron/mediamtx/releases) binary - and rtsp config yml file and copy them into the `cmd` directory + and rtsp config yml file and copy them into the [cmd](https://github.com/edgexfoundry/device-usb-camera/tree/main/cmd) directory. - 1. Build the service from the `main` directory. + 1. Build the service from the `main` directory: ```bash - cd .. make build ``` - 1. Run the service + 1. Run the service. Use appropriate ip addresses for the `rsh` flag parameter. Refer to [Remote Service Hosts](../../configuration/CommonCommandLineOptions.md#remote-service-hosts) + for more info. ```bash - EDGEX_SECURITY_SECRET_STORE=false ./cmd/device-usb-camera -cp=consul.http://:8500 -o + EDGEX_SECURITY_SECRET_STORE=false ./cmd/device-usb-camera -cp -r -rsh=,, ``` !!! note If multiple instances of the service has to be run then attach `-i` followed by the number of instances desired. E.g: ```bash - EDGEX_SECURITY_SECRET_STORE=false ./cmd/device-usb-camera -cp=consul.http://:8500 -o -i 2 + EDGEX_SECURITY_SECRET_STORE=false ./cmd/device-usb-camera -cp -r -rsh=172.26.113.174,172.26.113.150,0.0.0.0 -i 2 ``` 1. Make sure the service has no errors and it discovers connected usb devices after some time. - 1. Verify device(s) have been successfully added to core-metadata. + 1. Verify device(s) have been successfully added to core-metadata (running in host node). ```bash curl -s http://:59881/api/v3/device/all | jq -r '"deviceName: " + '.devices[].name'' @@ -122,13 +106,13 @@ This example can be further extended to run multiple instances of device-usb-cam deviceName: NexiGo_N930AF_FHD_Webcam_NexiG-20201217010 ``` - 1. Add credentials for RTSP streaming by referring to [RTSP Stream Credentials](../supported/device-usb-camera/walkthrough/deployment.md#add-credentials-for-the-rtsp-stream). - Make sure to use correct host IP address in the POST request instead of localhost. + 1. Add credentials for RTSP streaming by referring to [RTSP Stream Credentials](../services/device-usb-camera/walkthrough/deployment.md#add-credentials-for-the-rtsp-stream). + Make sure to replace localhost with the correct host node IP address. !!! note - The node used for rtsp streaming should have FFMPEG version of 5.0 atleast. + The remote node used for rtsp streaming should have FFMPEG version of 5.0 atleast. - 1. Follow [USB Service API Guide](../supported/device-usb-camera/walkthrough/general-usage.md) to execute APIs such as Streaming. Again make sure to replace localhost with the applicable + 1. Follow [USB Service API Guide](../services/device-usb-camera/walkthrough/general-usage.md) to execute APIs such as Streaming. Again make sure to replace localhost with the applicable host or remote IP addresses. From 8176e18fa7ecb11d6720b5befa59507ba7706c3c Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Tue, 19 Sep 2023 20:15:11 -0700 Subject: [PATCH 06/11] docs: small clean up Signed-off-by: preethi-satishcandra --- docs_src/microservices/device/remote/Ch-RemoteNonSecure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md index 1885aed4bf..15bec8ce92 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -107,13 +107,13 @@ This example can be further extended to run multiple instances of device-usb-cam ``` 1. Add credentials for RTSP streaming by referring to [RTSP Stream Credentials](../services/device-usb-camera/walkthrough/deployment.md#add-credentials-for-the-rtsp-stream). - Make sure to replace localhost with the correct host node IP address. + Make sure to replace localhost with the host node IP address. !!! note The remote node used for rtsp streaming should have FFMPEG version of 5.0 atleast. 1. Follow [USB Service API Guide](../services/device-usb-camera/walkthrough/general-usage.md) to execute APIs such as Streaming. Again make sure to replace localhost with the applicable - host or remote IP addresses. + host or remote node IP addresses. From 15df4ff30f5588301f26c973fc94aa39abfd9194 Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Thu, 21 Sep 2023 10:44:51 -0700 Subject: [PATCH 07/11] docs: addressed Lenny's code review comments Signed-off-by: preethi-satishcandra --- docs_src/microservices/device/remote/Ch-RemoteNonSecure.md | 4 ++-- docs_src/microservices/device/remote/Ch-RemoteSecure.md | 2 ++ 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md index 15bec8ce92..50b3b4197d 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -1,7 +1,7 @@ # Remote deployment of device services in non-secure mode -Usually microservices are deployed using multiple nodes for scalability, availability and performance -instead of running all services in one node. +In some use cases, devices are connected to nodes where core EdgeX services are not running. In these cases the appropriate device service +needs to run on the remote nodes where it can connect to the device(s) and communicate to the host node where the rest of the EdgeX services are running. This page provides an example of remote deployment of [device-usb-camera](../services/device-usb-camera/General.md) service using multiple nodes in non-secure mode. The deployment can be done by running the service `natively` or by running it in `Docker`. diff --git a/docs_src/microservices/device/remote/Ch-RemoteSecure.md b/docs_src/microservices/device/remote/Ch-RemoteSecure.md index 7b983a3d4c..78b82f8b59 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteSecure.md @@ -1 +1,3 @@ # Remote deployment of device services in secure mode + +Coming Soon. From 12288971eaaba74a2248bbb87123806077fc86d4 Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Thu, 21 Sep 2023 13:16:38 -0700 Subject: [PATCH 08/11] docs: added docker mode related docs Signed-off-by: preethi-satishcandra --- .../device/remote/Ch-RemoteNonSecure.md | 139 ++++++++++++++---- 1 file changed, 110 insertions(+), 29 deletions(-) diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md index 50b3b4197d..4a304e9bcf 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -15,7 +15,7 @@ This example can be further extended to run multiple instances of device-usb-cam 1. Set up the two nodes to be ready for remote deployment. Refer to [USB Service Setup](../services/device-usb-camera/walkthrough/setup.md) for system requirements and dependencies such as Git, Docker, Docker Compose, etc. Additionally Golang needs to be installed - in the remote node where the device-usb-camera service will be built and run natively. + in the remote node if the device-usb-camera service will be built and run natively. 1. Next step is to install [EdgeX compose](https://github.com/edgexfoundry/edgex-compose) in the host node which will be used to run all EdgeX core services. So clone the `edgex-compose` repository: @@ -49,26 +49,78 @@ This example can be further extended to run multiple instances of device-usb-cam docker ps ``` -1. Follow this guide to run the `device-usb-camera` service in Docker or natively. + 1. Clone the [device-usb-camera](https://github.com/edgexfoundry/device-usb-camera) service repository: + + ```bash + git clone https://github.com/edgexfoundry/device-usb-camera.git + ``` + + 1. Checkout the required version: + + ```bash + git checkout {{edgexversion}} + ``` + + 1. Follow the guide below to build and run the `device-usb-camera` service in Docker or natively. === "Docker" - Todo + 1. Build the service from the `main` directory: -=== "Native" + ```bash + make docker + ``` - 1. Clone the [device-usb-camera](https://github.com/edgexfoundry/device-usb-camera) service repository: + 1. Create `docker-compose.yml` file from anywhere in the remote node to run the device service in Docker. Copy the content below into the compose file and edit with approriate values: ```bash - git clone https://github.com/edgexfoundry/device-usb-camera.git + name: edgex + services: + device-usb-camera: + container_name: edgex-device-usb-camera + device_cgroup_rules: + - c 81:* rw + environment: + EDGEX_SECURITY_SECRET_STORE: "false" + EDGEX_REMOTE_SERVICE_HOSTS: ",," + #E.g.EDGEX_REMOTE_SERVICE_HOSTS: "172.118.1.92,172.118.1.167,0.0.0.0" + hostname: edgex-device-usb-camera + image: + ports: + - "59983:59983" + - "8554:8554" + - "8000:8000" + read_only: true + restart: always + security_opt: + - no-new-privileges:true + user: root:root + volumes: + - type: bind + source: /dev + target: /dev + bind: + create_host_path: true + - type: bind + source: /run/udev + target: /run/udev + read_only: true + bind: + create_host_path: true ``` - - 1. Checkout the required version: + + !!! note + If multiple instances of the service has to be run then add `EDGEX_INSTANCE_NAME` enviroment variable above with a value of number of instances desired. + + 1. Run `docker-compose.yml`: + ```bash - git checkout {{edgexversion}} + docker compose up -d ``` +=== "Native" + 1. For RTSP streaming get [rtsp-simple-server](https://github.com/bluenviron/mediamtx/releases) binary and rtsp config yml file and copy them into the [cmd](https://github.com/edgexfoundry/device-usb-camera/tree/main/cmd) directory. @@ -91,29 +143,58 @@ This example can be further extended to run multiple instances of device-usb-cam EDGEX_SECURITY_SECRET_STORE=false ./cmd/device-usb-camera -cp -r -rsh=172.26.113.174,172.26.113.150,0.0.0.0 -i 2 ``` - 1. Make sure the service has no errors and it discovers connected usb devices after some time. - - - 1. Verify device(s) have been successfully added to core-metadata (running in host node). - - ```bash - curl -s http://:59881/api/v3/device/all | jq -r '"deviceName: " + '.devices[].name'' - ``` - - Example Output: - - ```bash - deviceName: NexiGo_N930AF_FHD_Webcam_NexiG-20201217010 - ``` +## Verify Service, Device(s) and next steps + +1. Make sure the service has no errors and check whether the service is added to Edgex i.e. to core-metadata (running in host node): + + ```bash + curl -s http://:59881/api/{{api_version}}/deviceservice/name/device-usb-camera | jq . + ``` + + Successful: + ```json + { + "apiVersion" : "{{api_version}}", + "statusCode": 200, + "service": { + "created": 1658769423192, + "modified": 1658872893286, + "id": "04470def-7b5b-4362-9958-bc5ff9f54f1e", + "name": "device-usb-camera", + "baseAddress": "http://edgex-device-usb-camera:59983", + "adminState": "UNLOCKED" + } + } + ``` + Unsuccessful: + ```json + { + "apiVersion" : "{{api_version}}", + "message": "fail to query device service by name device-usb-camera", + "statusCode": 404 + } + ``` + +1. Verify device(s) have been successfully added: + + ```bash + curl -s http://:59881/api/{{api_version}}/device/all | jq -r '"deviceName: " + '.devices[].name'' + ``` + + Example Output: + + ```bash + deviceName: NexiGo_N930AF_FHD_Webcam_NexiG-20201217010 + ``` - 1. Add credentials for RTSP streaming by referring to [RTSP Stream Credentials](../services/device-usb-camera/walkthrough/deployment.md#add-credentials-for-the-rtsp-stream). - Make sure to replace localhost with the host node IP address. +1. Add credentials for RTSP streaming by referring to [RTSP Stream Credentials](../services/device-usb-camera/walkthrough/deployment.md#add-credentials-for-the-rtsp-stream). + Make sure to replace localhost with the host node IP address. - !!! note - The remote node used for rtsp streaming should have FFMPEG version of 5.0 atleast. + !!! note + The remote node used for rtsp streaming should have FFMPEG version of 5.0 atleast. - 1. Follow [USB Service API Guide](../services/device-usb-camera/walkthrough/general-usage.md) to execute APIs such as Streaming. Again make sure to replace localhost with the applicable - host or remote node IP addresses. +1. Follow [USB Service API Guide](../services/device-usb-camera/walkthrough/general-usage.md) to execute APIs such as Streaming. Again make sure to replace localhost with the applicable + host or remote node IP addresses. From 3aadfaea9ce3f24bed37b86df5dc75566e3b6111 Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Thu, 21 Sep 2023 15:04:46 -0700 Subject: [PATCH 09/11] docs: addressed Sean's code review comments Signed-off-by: preethi-satishcandra --- .../device/remote/Ch-RemoteNonSecure.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md index 4a304e9bcf..1a4630490b 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -30,14 +30,14 @@ This example can be further extended to run multiple instances of device-usb-cam git checkout {{edgexversion}} ``` -1. Update the [docker-compose-no-secty.yml](https://github.com/edgexfoundry/edgex-compose/blob/main/docker-compose-no-secty.yml) file by removing the `host_ip` section of all the Edgex core services. E.g. +1. Update the [docker-compose-no-secty.yml](https://github.com/edgexfoundry/edgex-compose/blob/main/docker-compose-no-secty.yml) file by removing the `host_ip` section of all the EdgeX core services. E.g. ```bash host_ip: 127.0.0.1 ``` The example line provided above should be removed from the services, the host_ip will be provided while running the usb service. - Non-Edgex core services such as device-rest, device-virtual, app-rules-engine, etc. can be removed or commented out if needed. + Non-EdgeX core services such as device-rest, device-virtual, app-rules-engine, etc. can be removed or commented out if needed. -1. Run Edgex core services: +1. Run EdgeX core services: ```bash make run no-secty @@ -110,7 +110,7 @@ This example can be further extended to run multiple instances of device-usb-cam ``` !!! note - If multiple instances of the service has to be run then add `EDGEX_INSTANCE_NAME` enviroment variable above with a value of number of instances desired. + If multiple instances of the service have to be run, then add `EDGEX_INSTANCE_NAME` environment variable above with a value of number of instances desired. 1. Run `docker-compose.yml`: @@ -138,14 +138,14 @@ This example can be further extended to run multiple instances of device-usb-cam ``` !!! note - If multiple instances of the service has to be run then attach `-i` followed by the number of instances desired. E.g: + If multiple instances of the service have to be run, then attach `-i` followed by the number of instances desired. E.g: ```bash EDGEX_SECURITY_SECRET_STORE=false ./cmd/device-usb-camera -cp -r -rsh=172.26.113.174,172.26.113.150,0.0.0.0 -i 2 ``` ## Verify Service, Device(s) and next steps -1. Make sure the service has no errors and check whether the service is added to Edgex i.e. to core-metadata (running in host node): +1. Make sure the service has no errors and check whether the service is added to EdgeX i.e. to core-metadata (running in host node): ```bash curl -s http://:59881/api/{{api_version}}/deviceservice/name/device-usb-camera | jq . From b8adb845384719caeb70081ce379d6a56a9c08f9 Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Mon, 25 Sep 2023 10:33:56 -0700 Subject: [PATCH 10/11] docs: addressed more of Lenny's code review comments Signed-off-by: preethi-satishcandra --- .../device/remote/Ch-RemoteNonSecure.md | 40 ++++++++----------- .../device/remote/Ch-RemoteSecure.md | 1 - 2 files changed, 17 insertions(+), 24 deletions(-) diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md index 1a4630490b..1235c877d4 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -49,28 +49,10 @@ This example can be further extended to run multiple instances of device-usb-cam docker ps ``` - 1. Clone the [device-usb-camera](https://github.com/edgexfoundry/device-usb-camera) service repository: - - ```bash - git clone https://github.com/edgexfoundry/device-usb-camera.git - ``` - - 1. Checkout the required version: - - ```bash - git checkout {{edgexversion}} - ``` - - 1. Follow the guide below to build and run the `device-usb-camera` service in Docker or natively. + 1. Follow the guide below to run the `device-usb-camera` service in Docker or natively. === "Docker" - 1. Build the service from the `main` directory: - - ```bash - make docker - ``` - 1. Create `docker-compose.yml` file from anywhere in the remote node to run the device service in Docker. Copy the content below into the compose file and edit with approriate values: ```bash @@ -82,10 +64,10 @@ This example can be further extended to run multiple instances of device-usb-cam - c 81:* rw environment: EDGEX_SECURITY_SECRET_STORE: "false" - EDGEX_REMOTE_SERVICE_HOSTS: ",," + EDGEX_REMOTE_SERVICE_HOSTS: ",," #E.g.EDGEX_REMOTE_SERVICE_HOSTS: "172.118.1.92,172.118.1.167,0.0.0.0" hostname: edgex-device-usb-camera - image: + image: ports: - "59983:59983" - "8554:8554" @@ -121,6 +103,18 @@ This example can be further extended to run multiple instances of device-usb-cam === "Native" + 1. Clone the [device-usb-camera](https://github.com/edgexfoundry/device-usb-camera) service repository: + + ```bash + git clone https://github.com/edgexfoundry/device-usb-camera.git + ``` + + 1. Checkout the required version: + + ```bash + git checkout {{edgexversion}} + ``` + 1. For RTSP streaming get [rtsp-simple-server](https://github.com/bluenviron/mediamtx/releases) binary and rtsp config yml file and copy them into the [cmd](https://github.com/edgexfoundry/device-usb-camera/tree/main/cmd) directory. @@ -148,7 +142,7 @@ This example can be further extended to run multiple instances of device-usb-cam 1. Make sure the service has no errors and check whether the service is added to EdgeX i.e. to core-metadata (running in host node): ```bash - curl -s http://:59881/api/{{api_version}}/deviceservice/name/device-usb-camera | jq . + curl -s http://:59881/api/{{api_version}}/deviceservice/name/device-usb-camera | jq . ``` Successful: @@ -178,7 +172,7 @@ This example can be further extended to run multiple instances of device-usb-cam 1. Verify device(s) have been successfully added: ```bash - curl -s http://:59881/api/{{api_version}}/device/all | jq -r '"deviceName: " + '.devices[].name'' + curl -s http://:59881/api/{{api_version}}/device/all | jq -r '"deviceName: " + '.devices[].name'' ``` Example Output: diff --git a/docs_src/microservices/device/remote/Ch-RemoteSecure.md b/docs_src/microservices/device/remote/Ch-RemoteSecure.md index 78b82f8b59..c9eb45381c 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteSecure.md @@ -1,3 +1,2 @@ # Remote deployment of device services in secure mode - Coming Soon. From 76803cc20cebc6b6a09993c5cf72268fb0d376f2 Mon Sep 17 00:00:00 2001 From: preethi-satishcandra Date: Mon, 25 Sep 2023 12:27:18 -0700 Subject: [PATCH 11/11] docs: removed not needed port Signed-off-by: preethi-satishcandra --- docs_src/microservices/device/remote/Ch-RemoteNonSecure.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md index 1235c877d4..6462e92db5 100644 --- a/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md +++ b/docs_src/microservices/device/remote/Ch-RemoteNonSecure.md @@ -71,7 +71,6 @@ This example can be further extended to run multiple instances of device-usb-cam ports: - "59983:59983" - "8554:8554" - - "8000:8000" read_only: true restart: always security_opt: