-
-
-via configuration.yaml
- -Define the following configurations in [cmd/res/configuration.yaml](../cmd/res/configuration.yaml) for auto-discovery mechanism: - -```yaml -Device: - # The location of Provision Watcher yaml files to import when using auto-discovery - ProvisionWatchersDir: ./res/provisionwatchers - Discovery: - Enabled: true - Interval: 1h - -# Custom configs -AppCustom: - DefaultSecretName: credentials001 - # Select which discovery mechanism(s) to use - DiscoveryMode: both # netscan, multicast, or both - # The target ethernet interface for multicast discovering - DiscoveryEthernetInterface: eth0 - # List of IPv4 subnets to perform netscan discovery on, in CIDR format (X.X.X.X/Y) - # separated by commas ex: "192.168.1.0/24,10.0.0.0/24" - DiscoverySubnets: "192.168.1.0/24" # Fill in with your actual subnet(s) -``` -
-
-
-### Step 2. Set CredentialsMap
-See [Credentials Guide](credentials.md) for more information.
-
-## Configuration Guide
-### DiscoveryMode
-> For docker, set the env var `APPCUSTOM_DISCOVERYMODE`
-
-`DiscoveryMode` allows you to select which discovery mechanism(s) to use. The three options are: `netscan`, `multicast`, and `both`.
-
-#### netscan
-`netscan` works by sending unicast UDP [WS-Discovery](./ws-discovery.md) probes to a set of
-IP addresses on the CIDR subnet(s) configured via [`DiscoverySubnets`](#DiscoverySubnets).
-
-For example, if the provided CIDR is `10.0.0.0/24`, it will probe the all IP addresses
-from `10.0.0.1` to `10.0.0.254`. This will result in a total of 254 probes on the network.
-
-This method is a little slower and more network-intensive than multicast WS-Discovery, because it has to
-make individual connections. However, it can reach a much wider set of networks and works
-better behind NATs (such as docker networks).
-
-#### multicast
-`multicast` works by sending a single multicast UDP [WS-Discovery](./ws-discovery.md) Probe to the multicast address `239.255.255.250` on port `3702`.
-In certain networks this traffic is blocked, and it is also not forwarded across subnets, so it is not compatible with NATs
-such as docker networks (except in the case of running an Onvif simulator inside the same docker network).
-
-multicast requires some additional configuration. edit the `add-device-onvif-camera.yml` in the `edgex-compose/compose-builder` as follows:
-
-> NOTE: use the instructions below to configure certain environment variables
-```yml
-services:
- device-onvif-camera:
- image: edgexfoundry/device-onvif-camera${ARCH}:0.0.0-dev
- container_name: edgex-device-onvif-camera
- hostname: edgex-device-onvif-camera
- read_only: true
- restart: always
- network_mode: "host"
- environment:
- SERVICE_HOST: 192.168.93.151 # set to internal ip of your machine
- MESSAGEQUEUE_HOST: localhost
- EDGEX_SECURITY_SECRET_STORE: "false"
- REGISTRY_HOST: localhost
- CLIENTS_CORE_DATA_HOST: localhost
- CLIENTS_CORE_METADATA_HOST: localhost
- # Host Network Interface, IP, Subnet
- APPCUSTOM_DISCOVERYETHERNETINTERFACE: wlp1s0 # determine this setting for your machine
- APPCUSTOM_DISCOVERYSUBNETS: 192.168.93.0/24 # determine this setting for your machine
- APPCUSTOM_DISCOVERYMODE: multicast
- depends_on:
- - consul
- - data
- - metadata
- security_opt:
- - no-new-privileges:true
- user: "${EDGEX_USER}:${EDGEX_GROUP}"
- command: --cp=consul.http://localhost:8500
-```
-
-#### both
-This option combines both [netscan](#netscan) and [multicast](#multicast).
-
-### DiscoverySubnets
-> For docker, set the env var `APPCUSTOM_DISCOVERYSUBNETS`
-
-This is the list of IPv4 subnets to perform netscan discovery on, in CIDR format (X.X.X.X/Y)
-separated by commas ex: "192.168.1.0/24,10.0.0.0/24". This value can be configured automatically via
-the [bin/configure-subnets.sh](utility-scripts.md#configure-subnetssh) script.
-
-Also, the following one-line command can determine the subnets of your machine:
-```shell
-ip -4 -o route list scope link | sed -En "s/ dev ($(find /sys/class/net -mindepth 1 -maxdepth 2 -not -lname '*devices/virtual*' -execdir grep -q 'up' "{}/operstate" \; -printf '%f\n' | paste -sd\| -)).+//p" | grep -v "169.254.0.0/16" | sort -u | paste -sd, -
-```
-Example Output: `192.168.1.0/24`
-
-### DiscoveryEthernetInterface
-> For docker, set the env var `APPCUSTOM_DISCOVERYETHERNETINTERFACE`
-
-This is the target Ethernet Interface to use for [multicast](#multicast) discovering. Keep in mind this interface
-is relative to the environment it is being run under. For example, when running in docker, those interfaces
-are different from your host machine's interfaces.
-
-### ProbeAsyncLimit
-> For docker, set the env var `APPCUSTOM_PROBEASYNCLIMIT`
-
-This is the maximum simultaneous network probes when running netscan discovery.
-
-### ProbeTimeoutMillis
-> For docker, set the env var `APPCUSTOM_PROBETIMEOUTMILLIS`
-
-This is the maximum amount of milliseconds to wait for each IP probe before timing out.
-This will also be the minimum time the discovery process can take.
-
-### MaxDiscoverDurationSeconds
-> For docker, set the env var `APPCUSTOM_MAXDISCOVERDURATIONSECONDS`
-
-This is the maximum amount of seconds the discovery process is allowed to run before it will be cancelled.
-It is especially important to have this configured in the case of larger subnets such as /16 and /8.
-
-
-## Adding the Devices to EdgeX
-```mermaid
-sequenceDiagram
- Onvif Device Service->>Onvif Camera: WS-Discovery Probe
- Onvif Camera->>Onvif Device Service: Probe Response
- Onvif Device Service->>Onvif Camera: GetDeviceInformation
- Onvif Camera->>Onvif Device Service: GetDeviceInformation Response
- Onvif Device Service->>Onvif Camera: GetNetworkInterfaces
- Onvif Camera->>Onvif Device Service: GetNetworkInterfaces Response
- Onvif Device Service->>EdgeX Core-Metadata: Create Device
- EdgeX Core-Metadata->>Onvif Device Service: Device Added
-```
-
-## Rediscovery
-The device service is able to rediscover and update devices that have been discovered previously.
-Nothing additional is needed to enable this. It will run whenever the discover call is sent, regardless
-of whether it is a manual or automated call to discover.
-
-The following logic to determine if the device is already registered or not.
-
-```mermaid
-%% Note: The node and edge definitions are split up to make it easier to adjust the
-%% links between the various nodes.
-flowchart TD;
- %% -------- Node Definitions -------- %%
- Multicast[/Devices Discoveredvia Docker / Env Vars
- -Define the following environment variables in `docker-compose.yaml`: -```yaml -device-onvif-camera: - environment: - DEVICE_DISCOVERY_ENABLED: "true" # enable device discovery - DEVICE_DISCOVERY_INTERVAL: "1h" # set to desired interval - - # The target ethernet interface for multicast discovering - APPCUSTOM_DISCOVERYETHERNETINTERFACE: "eth0" - # The Secret Name of the default credentials to use for devices - APPCUSTOM_DEFAULTSECRETNAME: "credentials001" - # Select which discovery mechanism(s) to use - APPCUSTOM_DISCOVERYMODE: "both" # netscan, multicast, or both - # List of IPv4 subnets to perform netscan discovery on, in CIDR format (X.X.X.X/Y) - # separated by commas ex: "192.168.1.0/24,10.0.0.0/24" - APPCUSTOM_DISCOVERYSUBNETS: "192.168.1.0/24" # Fill in with your actual subnet(s) -``` -via Multicast/] - Netscan[/Devices Discovered
via Netscan/] - DupeFilter[Filter Duplicate Devices
based on EndpointRef] - MACMatches{MAC Address
matches existing
device?} - RefMatches{EndpointRef
matches existing
device?} - IPChanged{IP Address
Changed?} - MACChanged{MAC Address
Changed?} - UpdateIP[Update IP Address] - UpdateMAC(Update MAC Address) - RegisterDevice(Register New Device
With EdgeX) - DeviceNotRegistered(Device Not Registered) - PWMatches{Device matches
Provision Watcher?} - - %% -------- Graph Definitions -------- %% - Multicast --> DupeFilter - Netscan --> DupeFilter - DupeFilter --> ForEachDevice - subgraph ForEachDevice[For Each Unique Device] - MACMatches -->|Yes| UpdateDevice - MACMatches -->|No| RefMatches - RefMatches -->|Yes| UpdateDevice - RefMatches -->|No| ForEachPW - - subgraph UpdateDevice[Update Existing Device] - direction TB - IPChanged -->|No| MACChanged - IPChanged -->|Yes| UpdateIP - UpdateIP --> MACChanged - MACChanged -->|Yes| UpdateMAC - end - - subgraph ForEachPW[For Each Provision Watcher] - direction TB - PWMatches -->|Yes| RegisterDevice - end - ForEachPW -->|No Matches| DeviceNotRegistered - end -``` - -## Troubleshooting - -#### netscan discovery was called, but DiscoverySubnets are empty! -This message occurs when you have not configured the `AppCustom.DiscoverySubnets` configuration. -It is required in order to know which subnets to scan for Onvif Cameras. -See [here](#DiscoverySubnets) - -#### route ip+net: no such network interface -This message occurs when you have multicast discovery enabled, but `AppCustom.DiscoveryEthernetInterface` -is configured to a network interface that does not exist. -See [here](#DiscoveryEthernetInterface) diff --git a/doc/control-plane-events.md b/doc/control-plane-events.md deleted file mode 100644 index 4e404f20..00000000 --- a/doc/control-plane-events.md +++ /dev/null @@ -1,7 +0,0 @@ -# Control Plane Events - -## Introduction -Control plane events have been added to enable the device service to emit events onto the message bus when a device has been added, updated, or deleted. - -See: https://docs.edgexfoundry.org/2.3/microservices/core/metadata/Ch-Metadata/#device-system-events - diff --git a/doc/credentials.md b/doc/credentials.md deleted file mode 100644 index 1c483561..00000000 --- a/doc/credentials.md +++ /dev/null @@ -1,241 +0,0 @@ -# Credentials -Camera credentials are stored in the EdgeX Secret Store and referenced by MAC Address. All -devices by default are configured with credentials from `DefaultSecretName` unless configured -as part of a group within `AppCustom.CredentialsMap`. - -Three things must be done in order to add an authenticated camera to EdgeX: -- Add device to EdgeX - - Manually or via auto-discovery -- Add `Credentials` to `Secret Store` - - Manually or via utility scripts -- Map `Credentials` to devices - - Manually or via utility scripts - - Configure as `DefaultSecretName` - -## Terminology / Definitions -- **Secret**: A generic map/object which is stored as multiple key/value pairs in the `Secret Store` under a specific `Secret Name` key. -- **Credentials**: A specific type of `Secret` which contains a mapping of `username`, `password`, and authentication `mode`. -- **Secret Store**: The place EdgeX stores all `Secrets` - - In secure mode this is `Vault` - - In non-secure mode this is the configuration provider (typically `Consul`). - They can be pre-configured via `configuration.yaml`'s `Writable.InsecureSecrets` section. -- **Secret Name**: The name/key of the `Secret` as they are stored in the `Secret Store`. -- **CredentialsMap**: (aka `AppCustom.CredentialsMap`) this contains the mappings between `Secret Name` and - `MAC Address`. Each key in the map is a `Secret Name` which points to `Credentials` in the `Secret Store`. The value - for each key is a comma separated list of `MAC Addresses` which should use those `Credentials`. -- **DefaultSecretName**: The `Secret Name` which points to the `Credentials` to use as the default for all devices - which are not configured in the `CredentialsMap`. -- **NoAuth**: A special `Secret Name` that does not exist in the `Secret Store`. It is pre-configured as `Credentials` - with `Authentication Mode` of `none`. `NoAuth` can be used most places where a `Secret Name` is expected. - -Camera credentials are stored in the EdgeX Secret Store, which is Vault in secure mode, and Consul in non-secure mode. -The term `Secret Name` is often used to refer to the name of the credentials as they are stored in the Secret Store. -Credentials are then mapped to devices either using the `DefaultSecretName` which applies to all devices by default, -or by configuring the `AppCustom.CredentialsMap` which maps one or more MAC Addresses to the desired credentials. - -## Credentials Structure -`Credentials` are `SecretData` comprised of three fields: -- `username`: the admin username for the camera -- `password`: the admin password -- `mode`: the type of Authentication to use - - `usernametoken`: use a username and token based authentication - - `digest`: use a digest based authentication - - `both`: use both `usernametoken` and `digest` - - `none`: do not send any authentication headers - -## Add Credentials to Secret Store -> **Note:** Credentials can be added and modified via [utility scripts](./utility-scripts.md) after the service is running - -### Non-Secure Mode -
-
-
-Helper Scripts
- -See [here](./utility-scripts.md) for the full guide. -
-` with the name of the secret, `` with the username,
-> `` with the password, and `` with the auth mode.
-
-Set SecretName to ``
-```shell
-curl -X PUT --data "" \
- "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/Writable/InsecureSecrets//SecretName"
-```
-
-Set username to ``
-```shell
-curl -X PUT --data "" \
- "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/Writable/InsecureSecrets//SecretData/username"
-```
-
-Set password to ``
-```shell
-curl -X PUT --data "" \
- "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/Writable/InsecureSecrets//SecretData/password"
-```
-
-Set auth mode to ``
-```shell
-curl -X PUT --data "" \
- "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/Writable/InsecureSecrets//SecretData/mode"
-```
-
-
-### Secure Mode
-Manual
- -> **Note:** Replace `
-
-
-Helper Scripts
- -See [here](./utility-scripts.md) for the full guide. -
-` with the name for the new secret, `` with the username,
-> `` with the password, and `` with the authentication mode.
-
-```shell
-curl --location --request POST 'http://localhost:59984/api/v2/secret' \
- --header 'Content-Type: application/json' \
- --data-raw '
-{
- "apiVersion":"v2",
- "name": "",
- "secretData":[
- {
- "key":"username",
- "value":""
- },
- {
- "key":"password",
- "value":""
- },
- {
- "key":"mode",
- "value":""
- }
- ]
-}'
-```
-
-
-## Mapping Credentials to Devices
-> **Note:** Credential mappings can be set via [utility scripts](./utility-scripts.md) after the service is running
-
-The device service supports three types of credential mapping. All three types can be used
-in conjunction with each other.
-
-- `1 to All` - All devices are given the default credentials based on `DefaultSecretName`
-- `1 to Many` - In the `CredentialsMap`, one secret name can be assigned multiple MAC addresses
-- `1 to 1` - In the `CredentialsMap`, assign each secret name 1 MAC Address
-
-### Manual Configuration
-> **Note:** Any key present in `AppCustom.CredentialsMap` must also exist in the secret store!
-```yaml
-# AppCustom.CredentialsMap is a map of SecretName -> Comma separated list of mac addresses.
- # Every SecretName used here must also exist as a valid secret in the Secret Store.
- #
- # Note: Anything not defined here will be assigned the default credentials configured via `DefaultSecretName`.
- #
- # Example: (Single mapping for 1 mac address to 1 credential)
- # credentials001 = "aa:bb:cc:dd:ee:ff"
- #
- # Example: (Multi mapping for 3 mac address to 1 shared credentials)
- # credentials002 = "11:22:33:44:55:66,ff:ee:dd:cc:bb:aa,ab:12:12:34:34:56:56"
- #
- # These mappings can also be referred to as "groups". In the above case, the `credentials001` group has 1 MAC
- # Address, and the `credentials002` group has 3 MAC Addresses.
- #
- # The special group 'NoAuth' defines mac addresses of cameras where no authentication is needed.
- # The 'NoAuth' key does not exist in the SecretStore. It is not required to add MAC Addresses in here,
- # however it avoids sending the default credentials to cameras which do not need it.
- #
- # IMPORTANT: A MAC Address may only exist in one credential group. If a MAC address is defined in more
- # than one group, it is unpredictable which group the MAC will end up in! If you wish to change the group a MAC
- # address belongs to, first remove it from its existing group, and then add it to the new one.
- CredentialsMap:
- NoAuth: ""
- credentials001: "aa:bb:cc:dd:ee:ff"
- credentials002: "11:22:33:44:55:66,ff:ee:dd:cc:bb:aa,ab:12:12:34:34:56:56"
-```
-
-## Credential Lookup
-Here is an in-depth look at the logic behind mapping `Credentials` to Devices.
-
-### During Discovery
-```mermaid
-%% Note: The node and edge definitions are split up to make it easier to adjust the
-%% links between the various nodes.
-flowchart TD;
- %% -------- Node Definitions -------- %%
- DiscoveredDevice[/Discovered Device/]
- UseDefault[Use Default Credentials]
- EndpointRefHasMAC{Does EndpointRefManual
- -Credentials can be added via EdgeX Secrets: - -> **Note:** Replace `contain
MAC Address?} - InNoAuthGroup{MAC Belongs
to NoAuth group?} - AuthModeNone[Set AuthMode to 'none'] - ApplyCreds[Apply Credentials] - InSecretStore{Credentials exist
in SecretStore?} - CreateClient[Create Onvif Client] - GetDeviceInfo[Get Device Information] - GetNetIfaces[Get Network Interfaces] - CreateDevice(Create Device:
<Mfg>-<Model>-<EndpointRef>) - CreateUnknownDevice(Create Device:
unknown_unknown_<EndpointRef>) - - %% -------- Graph Definitions -------- %% - DiscoveredDevice --> ForAllMAC - subgraph ForAllMAC[For all MAC Addresses in CredentialsMap] - EndpointRefHasMAC - end - EndpointRefHasMAC -->|Yes| InNoAuthGroup - EndpointRefHasMAC -- No Matches --> UseDefault - InNoAuthGroup -->|Yes| AuthModeNone - InNoAuthGroup -->|No| InSecretStore - UseDefault --> InSecretStore - AuthModeNone --> CreateClient - InSecretStore -->|Yes| ApplyCreds - InSecretStore -->|No| AuthModeNone - ApplyCreds --> CreateClient - CreateClient --> GetDeviceInfo - GetDeviceInfo -->|Failed| CreateUnknownDevice - GetDeviceInfo -->|Success| GetNetIfaces - GetNetIfaces ----> CreateDevice -``` - -### Connecting to Existing Devices -```mermaid -%% Note: The node and edge definitions are split up to make it easier to adjust the -%% links between the various nodes. -flowchart TD; - %% -------- Node Definitions -------- %% - ExistingDevice[/Existing Device/] - ContainsMAC{Device Metadata contains
MAC Address?} - ValidMAC{Is it a valid
MAC Address?} - InMap{MAC exists in
CredentialsMap?} - InNoAuth{MAC Belongs
to NoAuth group?} - UseDefault[Use Default Credentials] - InSecretStore{Credentials exist
in SecretStore?} - AuthModeNone(Set AuthMode to 'none') - ApplyCreds(Apply Credentials) - CreateClient(Create Onvif Client) - - %% -------- Edge Definitions -------- %% - ExistingDevice --> ContainsMAC - ContainsMAC -->|Yes| ValidMAC - ValidMAC -->|Yes| InMap - ValidMAC -->|No| AuthModeNone - InMap -->|Yes| InNoAuth - InMap -->|No| AuthModeNone - ContainsMAC -->|No| UseDefault - InNoAuth -->|Yes| AuthModeNone - InNoAuth -->|No| InSecretStore - UseDefault --> InSecretStore - InSecretStore -->|Yes| ApplyCreds - InSecretStore -->|No| AuthModeNone - AuthModeNone ----> CreateClient - ApplyCreds ----> CreateClient -``` \ No newline at end of file diff --git a/doc/custom-build.md b/doc/custom-build.md deleted file mode 100644 index 3a2adc2e..00000000 --- a/doc/custom-build.md +++ /dev/null @@ -1,213 +0,0 @@ -# ONVIF Device Service Custom Build Guide - -Follow this guide to make custom configurations and build the device service image from the source. - - -## Table of Contents - [Get the Source Code](#get-the-source-code) - [Configure the Pre-Defined Devices](#configure-the-pre-defined-devices) - [Configure the Device Profiles](#configure-the-device-profiles) - [Configure the Provision Watchers](#configure-the-provision-watchers) - [Build the Docker Image](#build-the-docker-image) - [Additional Configuration](#additional-configuration) - [Next Steps](#next-steps) - - -## Get the Source Code - -1. Clone the device-onvif-camera repository. - - ```bash - git clone https://github.com/edgexfoundry/device-onvif-camera.git - ``` - -2. Navigate into the directory - - ```bash - cd device-onvif-camera - ``` - - -## Configuration - -### Configure the Pre-Defined Devices - -Configuring pre-defined devices will allow the service to automatically provision them into core-metadata. Create a list of devices with the appropriate information as outlined below. - -1. Make a copy of the `camera.yaml.example`: - ```bash - cp ./cmd/res/devices/camera.yaml.example ./cmd/res/devices/camera.yaml - ``` - -1. Open the `cmd/res/devices/camera.yaml` file using your preferred text editor and update the `Address` and `Port` fields to match the IP address of the Camera and port used for ONVIF services: - - ```yaml - deviceList: - - name: Camera001 # Modify as desired - profileName: onvif-camera # Default profile - description: onvif conformant camera # Modify as desired - protocols: - Onvif: - Address: 191.168.86.34 # Set to your camera IP address - Port: '2020' # Set to the port your camera uses - SecretName: credentials001 - CustomMetadata: - CommonName: Outdoor camera - ``` -
- Sample: Snippet from camera.yaml -
- -1. Optionally, modify the `Name` and `Description` fields to more easily identify the camera. The `Name` is the camera name used when using ONVIF Device Service Rest APIs. The `Description` is simply a more detailed explanation of the camera. - -1. You can also optionally configure the `CustomMetadata` with custom fields and values to store any extra information you would like. - -1. To add more pre-defined devices, copy the above configuration and edit to match your extra devices. - - -### Configure the Device Service -1. Open the [configuration.yaml](./cmd/res/configuration.yaml) file using your preferred text editor - -1. Make sure `secret name` is set to match `SecretName` in `camera.yaml`. In the sample below, it is `"credentials001"`. If you have multiple cameras, make sure the secret names match. - -1. Under `secretName`, set `username` and `password` to your camera credentials. If you have multiple cameras copy the `Writable.InsecureSecrets` section and edit to include the new information. - -```yaml -Writable: - LogLevel: INFO - InsecureSecrets: - credentials001: - SecretName: credentials001 - SecretData: - username:- Sample: Snippet from configuration.yaml -
- -### Additional Configuration Options -For optional configurations, see [here.](#additional-configuration) - -## Build the Docker Image - -1. In the `device-onvif-camera` directory, run make docker: - - ```bash - make docker - ``` -
-
-
-1. Verify the ONVIF Device Service Docker image was successfully created:
-
- ```bash
- docker images
- ```
- ```docker
- REPOSITORY TAG IMAGE ID CREATED SIZE
- edgexfoundry-holding/device-onvif-camera 0.0.0-dev 75684e673feb 6 weeks ago 21.3MB
- ```
-
-1. Navigate to `edgex-compose` and enter the `compose-builder` directory.
-
- ```bash
- cd edgex-compose/compose-builder
- ```
-
-1. Update `.env` file to add the registry and image version variable for device-onvif-camera:
-
- Add the following registry and version information:
- ```env
- DEVICE_ONVIFCAM_VERSION=0.0.0-dev
- ```
-
-4. Update the `add-device-onvif-camera.yml` to point to the local image.
-
- ```yml
- services:
- device-onvif-camera:
- image: edgexfoundry/device-onvif-camera:${DEVICE_ONVIFCAM_VERSION}
- ```
-
-## Additional Configuration
-
-Here is some information on how to specially configure parts of the service beyond the provided defaults.
-
-### Configure the Device Profiles
-
-The device profile contains general information about the camera and includes all of the device resources and commands that the device resources can use to manage the cameras. The default [profile](../cmd/res/camera.yaml) contains all possible resources a camera could implement. Enable and disable supported resources in this file, or create an entirely new profile. It is important to set up the device profile to match the capabilities of the camera. Information on the resources supported by specific cameras can be found [here](./ONVIF-protocol.md#tested-onvif-cameras). Learn more about device profiles in EdgeX [here.](https://docs.edgexfoundry.org/1.2/microservices/device/profile/Ch-DeviceProfile/)
-
-```yaml
-name: "onvif-camera" # general information about the profile
-manufacturer: "Generic"
-model: "Generic ONVIF"
-labels:
- - "onvif"
-description: "EdgeX device profile for ONVIF-compliant IP camera."
-
-deviceResources:
- # Network Configuration
- - name: "Hostname" # an example of a resource with get/set values
- isHidden: false
- description: "Camera Hostname"
- attributes:
- service: "Device"
- getFunction: "GetHostname"
- setFunction: "SetHostname"
- properties:
- valueType: "Object"
- readWrite: "RW"
-```
-[Optional] Build with NATS Messaging
- - Currently, the NATS Messaging capability (NATS MessageBus) is opt-in at build time. This means that the published Docker image and Snaps do not include the NATS messaging capability. To build the docker image using NATS, run make docker-nats: - - ```bash - make docker-nats - ``` - - See [Compose Builder](https://github.com/edgexfoundry/edgex-compose/tree/main/compose-builder#gen) `nat-bus` option to generate compose file for NATS and local dev images. - -- Sample: Snippet from camera.yaml -
- - -### Configure the Provision Watchers - -The provision watcher sets up parameters for EdgeX to automatically add devices to core-metadata. They can be configured to look for certain features, as well as block features. The default provision watcher is sufficient unless you plan on having multiple different cameras with different profiles and resources. Learn more about provision watchers [here](https://docs.edgexfoundry.org/2.2/microservices/core/metadata/Ch-Metadata/#provision-watcher). - -```json -{ - "name":"Generic-Onvif-Provision-Watcher", - "identifiers":{ // Use the identifiers to filter through specific features of the protocol - "Address": ".", - "Manufacturer": "Intel", // example of a feature to allow through - "Model": "DFI6256TE" - }, - "blockingIdentifiers":{ - }, - "serviceName": "device-onvif-camera", - "profileName": "onvif-camera", - "adminState":"UNLOCKED" -} -``` -- Sample: Snippet from generic.provision.watcher.yaml -
- -## Next Steps -[Running and Verifying the device service](./running-guide.md) - -## License - -[Apache-1.0](https://github.com/edgexfoundry-holding/device-onvif-camera/blob/main/LICENSE) diff --git a/doc/custom-feature-rebootneeded.md b/doc/custom-feature-rebootneeded.md deleted file mode 100644 index e2bd5b32..00000000 --- a/doc/custom-feature-rebootneeded.md +++ /dev/null @@ -1,93 +0,0 @@ -# The custom feature - RebootNeeded - -## Why need the custom feature RebootNeeded? -Currently, only the SetNetworkInterfaces function returns the **RebootNeeded** value, if RebootNeeded is true, the user need to reboot the camera to apply the config changes. - -Since the Set command can't return the **RebootNeeded** value in command response, the device-onvif-camera will store the value in the memory, then the user can use the custom web service **EdgeX** and function **RebootNeeded** to check the value. - -## How does the RebootNeeded work with EdgeX? - -### 1. Execute Set command to change the networkInterfaces setting: -```shell -curl --request PUT 'http://0.0.0.0:59882/api/v2/device/name/Camera001/NetworkInterfaces' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "NetworkInterfaces": { - "InterfaceToken": "eth0", - "NetworkInterface": { - "Enabled": true, - "IPv4": { - "DHCP": true - } - } - } -}' -``` -### 2. Check the RebootNeeded value: -Using the **RebootNeeded** resource to check whether the camera need to reboot: -```shell -$ curl 'http://0.0.0.0:59882/api/v2/device/name/Camera001/RebootNeeded' | jq . -{ - "apiVersion" : "v2", - "event" : { - "apiVersion" : "v2", - "deviceName" : "Camera001", - "id" : "e370bbb5-55d2-4392-84ca-8d9e7f097dae", - "origin" : 1635750695886624000, - "profileName" : "onvif-camera", - "readings" : [ - { - "deviceName" : "Camera001", - "id" : "abd5c555-ef7d-44a7-9273-c1dbb4d14de2", - "origin" : 1635750695886624000, - "profileName" : "onvif-camera", - "resourceName" : "RebootNeeded", - "value" : "true", - "valueType" : "Bool" - } - ], - "sourceName" : "RebootNeeded" - }, - "statusCode" : 200 -} -``` - -The RebootNeeded is true which indicates the camera should reboot to apply the change. - -### 3. Reboot the camera to apply the change: -```shell -curl --request PUT 'http://0.0.0.0:59882/api/v2/device/name/Camera001/SystemReboot' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "SystemReboot": {} -}' -``` -The SystemReboot command also change the **RebootNeeded** value from `true` to `false`. - -### 4. Check The RebootNeeded value -```shell -$ curl 'http://0.0.0.0:59882/api/v2/device/name/Camera001/RebootNeeded' | jq . -{ - "apiVersion" : "v2", - "event" : { - "apiVersion" : "v2", - "deviceName" : "Camera001", - "id" : "53585696-ec1a-4ac7-9a42-7d480c0a75d9", - "origin" : 1635750854455262000, - "profileName" : "onvif-camera", - "readings" : [ - { - "deviceName" : "Camera001", - "id" : "87819d3a-25d0-4313-b69a-54c4a0c389ed", - "origin" : 1635750854455262000, - "profileName" : "onvif-camera", - "resourceName" : "RebootNeeded", - "value" : "false", - "valueType" : "Bool" - } - ], - "sourceName" : "RebootNeeded" - }, - "statusCode" : 200 -} -``` diff --git a/doc/custom-metadata-feature.md b/doc/custom-metadata-feature.md deleted file mode 100644 index 03d098d7..00000000 --- a/doc/custom-metadata-feature.md +++ /dev/null @@ -1,175 +0,0 @@ -# Custom Metadata - -Custom metadata can be applied and retrieved for each camera added to the service. - -## Usage - -- The `CustomMetadata` map is an element in the `ProtocolProperties` device field. It is initialized to be empty on discovery, so the user can add their desired fields. Otherwise, the user can pre-define this field in a camera.yaml file. - -### Preset Custom Metadata - -If you add pre-defined devices, set up the `CustomMetadata` object as shown in the [camera.yaml.example file](../cmd/res/devices/camera.yaml.example). - -```yaml -deviceList: - - name: Camera001 - profileName: onvif-camera - description: onvif conformant camera - protocols: - ... - CustomMetadata: - Location: Front door - Color: Black and white -``` - -### Set Custom Metadata - -Use the CustomMetadata resource to set the fields of `CustomMetadata`. Choose the key/value pairs to represent your custom fields. - -1. Use this command to put the data in the CustomMetadata field. -```shell -curl --request PUT 'http://0.0.0.0:59882/api/v2/device/name/in Core-Metadata] - SetLastSeen[Set LastSeen = Now] - UpdateMetadata[Update Core-Metadata] - CheckNowUpWithAuth{Status Changed
&&
Status == UpWithAuth?} - DeviceHasMAC{Device Has
MAC Address?} - CreateClient[Create Onvif Client] - GetCapabilities[Device::GetCapabilities] - CheckUpdatedMAC[Check CredentialsMap for
updated MAC Address] - TCPProbe[TCP Probe] - GetDeviceInfo[GetDeviceInformation] - UpdateDeviceInfo[Update Device Information] - UpdateMACAddress[Update MAC Address] - UpdateEndpointRef[Update EndpointRefAddress] - DeviceUnknown{Device Name
begins with
unknown_unknown_?} - RemoveDevice[Remove Device
unknown_unknown_<EndpointRef>] - CreateDevice[Create Device
<Mfg>-<Model>-<EndpointRef>] - - %% -------- Graph Definitions -------- %% - CheckDeviceStatus --> DeviceHasMAC - DeviceHasMAC -->|No| CheckUpdatedMAC - DeviceHasMAC -->|Yes| CreateClient - CheckUpdatedMAC --> CreateClient - - subgraph TestConnection[Test Connection Methods] - CreateClient --> GetCapabilities - GetCapabilities -->|Failed| TCPProbe - GetCapabilities -->|Success| GetDeviceInfo - GetDeviceInfo -->|Success| UpWithAuth - GetDeviceInfo -->|Failed| UpWithoutAuth - TCPProbe -->|Failed| Unreachable - TCPProbe -->|Success| Reachable - end - - UpWithAuth --> SetLastSeen - UpWithoutAuth --> SetLastSeen - Reachable --> SetLastSeen - Unreachable --> UpdateDeviceStatus - UpdateDeviceStatus --> CheckNowUpWithAuth - SetLastSeen --> UpdateDeviceStatus - CheckNowUpWithAuth -->|Yes| RefreshDevice - - subgraph RefreshDevice[Refresh Device] - UpdateDeviceInfo --> UpdateMACAddress - UpdateMACAddress --> UpdateEndpointRef - UpdateEndpointRef --> DeviceUnknown - DeviceUnknown -->|No| UpdateMetadata - DeviceUnknown -->|Yes| RemoveDevice - RemoveDevice --> CreateDevice - end -``` - -## Configuration Options -- Use `EnableStatusCheck` to enable the device status background service. -- `CheckStatusInterval` is the interval at which the service will determine the status of each camera. - -```yaml -# Enable or disable the built in status checking of devices, which runs every CheckStatusInterval. -EnableStatusCheck: true -# The interval in seconds at which the service will check the connection of all known cameras and update the device status -# A longer interval will mean the service will detect changes in status less quickly -# Maximum 300s (5 minutes) -CheckStatusInterval: 30 -``` - -## Automatic Triggers -Currently, there are some actions that will trigger an automatic status check: -- Any modification to the `CredentialsMap` from the config provider (Consul) diff --git a/doc/general-usage.md b/doc/general-usage.md deleted file mode 100644 index 4aace6f8..00000000 --- a/doc/general-usage.md +++ /dev/null @@ -1,312 +0,0 @@ - -# General Usage - -This document will describe how to execute some of the most important types of commands used with the device service. - -## Table of Contents - -[Get the Available Commands](#get-the-available-commands) -[Read a Single Resource](#execute-a-get-command---read-single-resource) -[Read Multiple Resources](#execute-a-get-command---read-multiple-resources) -[Set a Single Resource](#execute-a-set-command---write-single-resource) -[Set Multiple Resources](#execute-a-set-command---write-multiple-resource) -[Execute Commands Requiring Paramters](#execute-command-requiring-parameters) -[Next Steps](#next-steps) - -## Get the Available Commands -1. Check the available commands from core-command service: -```shell -curl http://localhost:59882/api/v2/device/name/Camera001 | jq -``` - -Example Output: - -```json -{ - "apiVersion": "v2", - "statusCode": 200, - "deviceCoreCommand": { - "deviceName": "Camera001", - "profileName": "onvif-camera", - "coreCommands": [ - { - "name": "NetworkDefaultGateway", - "get": true, - "set": true, - "path": "/api/v2/device/name/Camera001/NetworkDefaultGateway", - "url": "http://edgex-core-command:59882", - "parameters": [ - { - "resourceName": "NetworkDefaultGateway", - "valueType": "Object" - } - ] - }, - { - "name": "AddMetadataConfiguration", - "set": true, - "path": "/api/v2/device/name/Camera001/AddMetadataConfiguration", - "url": "http://edgex-core-command:59882", - "parameters": [ - { - "resourceName": "AddMetadataConfiguration", - "valueType": "Object" - } - ] - }, - ] - } -} -``` - ->NOTE: This response has been shortened, most device profiles will have many resources. - -## Execute a Get Command - Read Single Resource - -Example Command: -```shell -curl http://0.0.0.0:59882/api/v2/device/name/Camera001/Hostname | jq -``` -Example Output: - -```json -{ - "apiVersion" : "v2", - "event" : { - "apiVersion" : "v2", - "deviceName" : "Camera001", - "id" : "6b46d058-d8e0-4095-ba80-4a6de1787510", - "origin" : 1635749209227019000, - "profileName" : "onvif-camera", - "readings" : [ - { - "deviceName" : "Camera001", - "id" : "a1b0d809-c88a-4889-920e-8ac64e6aa658", - "objectValue" : { - "HostnameInformation" : { - "FromDHCP" : false, - "Name" : "localhost" - } - }, - "origin" : 1635749209227019000, - "profileName" : "onvif-camera", - "resourceName" : "Hostname", - "valueType" : "Object" - } - ], - "sourceName" : "Hostname" - }, - "statusCode" : 200 -} -``` - -## Execute a Get Command - Read Multiple Resources - -Example Command: -```shell -curl http://0.0.0.0:59882/api/v2/device/name/Camera001/NetworkConfiguration | jq -``` - -Example Output: -```json -{ - "apiVersion" : "v2", - "event" : { - "apiVersion" : "v2", - "sourceName" : "NetworkConfiguration", - "deviceName" : "Camera001", - "id" : "24d5e391-0dcd-48f5-8706-6abb11797d29", - "origin" : 1635868623002677000, - "profileName" : "onvif-camera", - "readings" : [ - { - "deviceName" : "Camera001", - "id" : "87d0bcfd-aecf-4ab7-a871-2b85a3c90f00", - "objectValue" : { - "HostnameInformation" : { - "FromDHCP" : false, - "Name" : "localhost" - } - }, - "origin" : 1635868623002677000, - "profileName" : "onvif-camera", - "resourceName" : "Hostname", - "valueType" : "Object" - }, - { - "deviceName" : "Camera001", - "id" : "edfa8d6f-a96e-49a8-96c9-595905cbe170", - "objectValue" : { - "DNSInformation" : { - "DNSManual" : { - "IPv4Address" : "192.168.12.1", - "Type" : "IPv4" - }, - "FromDHCP" : false - } - }, - "origin" : 1635868623002677000, - "profileName" : "onvif-camera", - "resourceName" : "DNS", - "valueType" : "Object" - }, - ... - ] - }, - "statusCode" : 200 -} -``` - -## Execute a Set Command - Write Single Resource -Example Command: -```shell -curl -X PUT -H 'Content-Type: application/json' 'http://0.0.0.0:59882/api/v2/device/name/Camera001/Hostname' \ - -d '{ - "Hostname": { - "Name": "localhost555" - } - }' -``` - -## Execute a Set Command - Write Multiple Resource -```shell -curl -X PUT -H 'Content-Type: application/json' 'http://0.0.0.0:59882/api/v2/device/name/Camera001/NetworkConfiguration' \ - -d '{ - "Hostname": { - "Name": "localhost" - }, - "DNS": { - "FromDHCP": false, - "DNSManual": { - "Type": "IPv4", - "IPv4Address": "192.168.12.1" - } - }, - "NetworkInterfaces": { - "InterfaceToken": "eth0", - "NetworkInterface": { - "Enabled": true, - "IPv4": { - "DHCP": false - } - } - - }, - "NetworkProtocols": { - "NetworkProtocols": [ - { - "Name": "HTTP", - "Enabled": true, - "Port": 80 - } - ] - }, - "NetworkDefaultGateway": { - "IPv4Address": "192.168.12.1" - } - }' -``` - -## Execute Command Requiring Parameters - -In this example, the GetStreamURI will be used as the example command. Some commands require a URL query to be passed, which is a base 64 encoded json object. The information needed for each command differs on an individual basis. This will walk you through how to get information from the device to pass as one of these queries, and use it appropriately. See the Swagger documentation (not implemented) for more information. - - -1. Get the profile token by executing the `GetProfiles` command: - - ```bash - curl http://0.0.0.0:59882/api/v2/device/name/Camera001/Profiles | jq - ``` - - Example Output: - ```json - { - "apiVersion": "v2", - "statusCode": 200, - "event": { - "apiVersion": "v2", - "id": "172bc5e6-cb6c-4c3d-aeb8-193cb968d304", - "deviceName": "TP-Link-C200-3fa1fe68-b915-4053-a3e1-cc32e5000688", - "profileName": "onvif-camera", - "sourceName": "Profiles", - "origin": 1657128504840230400, - "readings": [ - { - "id": "02e1c0cd-97f3-4846-85bf-dd5eff701e9f", - "origin": 1657128504840230400, - "deviceName": "TP-Link-C200-3fa1fe68-b915-4053-a3e1-cc32e5000688", - "resourceName": "Profiles", - "profileName": "onvif-camera", - "valueType": "Object", - "value": "", - "objectValue": { - "Profiles": [ - { - "Extension": null, - "Fixed": true, - "MetadataConfiguration": null, - "Name": "mainStream", - "PTZConfiguration": null, - "Token": "profile_1", - }, - ]} - }] - }} - ``` ->NOTE: This output has been trimmed to only show a necessary section. - -2. Convert the JSON input to Base64: - - >NOTE: Make sure to change the profile token to the one found in step 1. In this example, it is the string `profile_1`. - - ```json - { - "ProfileToken": "profile_1" - } - ``` - Example Output: - - ```bash - echo -n '{ - "ProfileToken": "profile_1" - }' | base64 - ewogICAgICAiUHJvZmlsZVRva2VuIjogInByb2ZpbGVfMSIKfQ== - ``` - -3. Execute `GetStreamURI` command to get RTSP URI from the ONVIF device. Make sure to put the Base64 JSON data after *?jsonObject=* in the command. - - ```bash - curl http://0.0.0.0:59882/api/v2/device/name/Camera001/StreamUri?jsonObject=ewogICAgICAiUHJvZmlsZVRva2VuIjogInByb2ZpbGVfMSIKfQ== | jq -r '"streamURI: " + '.event.readings[].objectValue.MediaUri.Uri'' - ``` - - Example Output: - - ```bash - streamURI: rtsp://192.168.86.34:554/stream1 - ``` - -4. Stream the RTSP stream: - - Alternatively, ffplay can be used to stream. The command follows this format: - - `ffplay -rtsp_transport tcp rtsp://'
-
-
-Manually Configure the Pre-Defined Devices
- -Configuring pre-defined devices will allow the service to automatically provision them into core-metadata. Create a list of devices with the appropriate information as outlined below. - -1. Navigate to the `device-onvif-camera` directory: - - ```bash - cd device-onvif-camera - ``` - -2. Make a copy of the `camera.yaml.example`: - - ```bash - cp ./cmd/res/devices/camera.yaml.example ./cmd/res/devices/camera.yaml - ``` - -3. Open the `cmd/res/devices/camera.yaml` file using your preferred text editor and update the `Address` and `Port` fields to match the IP address of the Camera and port used for ONVIF services: - - ```yaml - deviceList: - - name: Camera001 # Modify as desired - profileName: onvif-camera # Default profile - description: onvif conformant camera # Modify as desired - protocols: - Onvif: - Address: 191.168.86.34 # Set to your camera IP address - Port: '2020' # Set to the port your camera uses - SecretName: credentials001 - CustomMetadata: - CommonName: Outdoor camera - ``` -- Sample: Snippet from camera.yaml -
- -3. Optionally, modify the `Name` and `Description` fields to more easily identify the camera. The `Name` is the camera name used when using ONVIF Device Service Rest APIs. The `Description` is simply a more detailed explanation of the camera. - -4. You can also optionally configure the `CustomMetadata` with custom fields and values to store any extra information you would like. - -5. To add more pre-defined devices, copy the above configuration and edit to match your extra devices. - -
-
-
-Configure Auto Discovery for ONVIF Devices
- -ONVIF devices support WS-Discovery, which is a mechanism that supports probing a network to find ONVIF capable devices. Refer to [Auto Discovery](../auto-discovery.md) for detailed information on the auto-discovery mechanism. - -> The following one-line command can be used to discover subnets of your current machine: -> ```shell -> ip -4 -o route list scope link | sed -En "s/ dev ($(find /sys/class/net -mindepth 1 -maxdepth 2 -not -lname '*devices/virtual*' -execdir grep -q 'up' "{}/operstate" \; -printf '%f\n' | paste -sd\| -)).+//p" | grep -v "169.254.0.0/16" | sort -u | paste -sd, - -> ``` -> Example Output: `192.168.1.0/24` - -#### 1. Discovery Configuration - -> _See the [Auto Discovery Configuration Guide](../auto-discovery.md#Configuration-Guide) for full details_ -> -
-
-
-via Configuration File
- -1. Navigate to the `device-onvif-camera` directory: - - ```bash - cd device-onvif-camera - ``` - -2. Define the following configurations in [cmd/res/configuration.yaml](../../cmd/res/configuration.yaml) for auto-discovery mechanism: - ```yaml - Device: - # The location of Provision Watcher yaml files to import when using auto-discovery - ProvisionWatchersDir: ./res/provisionwatchers - Discovery: - Enabled: true # enable device discovery - Interval: 1h # set to desired interval - - # Custom configs - AppCustom: - # The Secret Name of the default credentials to use for devices which do not have MAC Addresses defined, or do not - # have credentials defined in the CredentialsMap. The magic value of 'NoAuth' here will cause the devices to default - # to not using any authentication. If authentication is required, it would then need to be manually configured. - DefaultSecretName: credentials001 - # Select which discovery mechanism(s) to use - DiscoveryMode: both # netscan, multicast, or both - # The target ethernet interface for multicast discovering - DiscoveryEthernetInterface: eth0 - # List of IPv4 subnets to perform netscan discovery on, in CIDR format (X.X.X.X/Y) - # separated by commas ex: "192.168.1.0/24,10.0.0.0/24" - DiscoverySubnets: "192.168.1.0/24" # Fill in with your actual subnet(s) - ``` -
-
-
-via Docker environment variables
- -1. Navigate to the EdgeX `compose-builder` directory: - - ```bash - cd edgex-compose/compose-builder/ - ``` - -2. Add the following environment variables in `add-device-onvif-camera.yaml`: - - ```yaml - device-onvif-camera: - environment: - DEVICE_DISCOVERY_ENABLED: "true" # enable device discovery - DEVICE_DISCOVERY_INTERVAL: "1h" # set to desired interval - - # The target ethernet interface for multicast discovering - APPCUSTOM_DISCOVERYETHERNETINTERFACE: "eth0" - # The Secret Name of the default credentials to use for devices - APPCUSTOM_DEFAULTSECRETNAME: "credentials001" - # Select which discovery mechanism(s) to use - APPCUSTOM_DISCOVERYMODE: "both" # netscan, multicast, or both - # List of IPv4 subnets to perform netscan discovery on, in CIDR format (X.X.X.X/Y) - # separated by commas ex: "192.168.1.0/24,10.0.0.0/24" - APPCUSTOM_DISCOVERYSUBNETS: "192.168.1.0/24" # Fill in with your actual subnet(s) - ``` -- -### Configure the Device Service - -1. Navigate to the `device-onvif-camera` directory: - - ```bash - cd device-onvif-camera - ``` - -2. Open the [configuration.yaml](../../cmd/res/configuration.yaml) file using your preferred text editor. - -3. Make sure `SecretName` is set to match `SecretName` in `camera.yaml`. In the sample below, it is `"credentials001"`. If you have multiple cameras, make sure the secret names match. - -4. Under `SecretName`, set `username` and `password` to your camera credentials. If you have multiple cameras copy the `Writable.InsecureSecrets` section and edit to include the new information. - - ```yaml - Writable: - InsecureSecrets: - credentials001: - SecretName: credentials001 - SecretData: - username:
- Sample: Snippet from configuration.yaml -
- - -### Additional Configuration Options -For optional configurations, see [here.](#additional-configuration) - -## Build the Docker Image - -1. In the `device-onvif-camera` directory, run make docker: - - ```bash - make docker - ``` -
-
-
-2. Verify the ONVIF Device Service Docker image was successfully created:
-
- ```bash
- docker images
- ```
- ```docker
- REPOSITORY TAG IMAGE ID CREATED SIZE
- edgexfoundry-holding/device-onvif-camera 0.0.0-dev 75684e673feb 6 weeks ago 21.3MB
- ```
-
-3. Navigate to the EdgeX `compose-builder` directory:
-
- ```bash
- cd edgex-compose/compose-builder/
- ```
-
-4. Update `.env` file to add the registry and image version variable for device-onvif-camera:
-
- Add the following registry and version information:
- ```env
- DEVICE_ONVIFCAM_VERSION=0.0.0-dev
- ```
-
-5. Update the `add-device-onvif-camera.yml` to point to the local image:
-
- ```yml
- services:
- device-onvif-camera:
- image: edgexfoundry/device-onvif-camera:${DEVICE_ONVIFCAM_VERSION}
- ```
-
-## Deploy EdgeX and ONVIF Device Camera Microservice
-
-[Optional] Build with NATS Messaging
- - Currently, the NATS Messaging capability (NATS MessageBus) is opt-in at build time. This means that the published Docker image and Snaps do not include the NATS messaging capability. To build the docker image using NATS, run make docker-nats: - - ```bash - make docker-nats - ``` - - See [Compose Builder](https://github.com/edgexfoundry/edgex-compose/tree/main/compose-builder#gen) `nat-bus` option to generate compose file for NATS and local dev images. - -
-
-
-Run the Service using Docker
- - 1. Navigate to the EdgeX `compose-builder` directory: - - ```bash - cd edgex-compose/compose-builder/ - ``` - - 1. Run EdgeX with the microservice in non-secure mode: - - ```bash - make run no-secty ds-onvif-camera - ``` - - 1. Run EdgeX with the microservice in secure mode: - - ```bash - make run ds-onvif-camera - ``` -
-
- ->**NOTE:** Go version 1.20+ is required to run natively. See [here](https://go.dev/doc/install) for more information. - -
- - 1. Navigate to the EdgeX `compose-builder` directory: - - ```bash - cd edgex-compose/compose-builder/ - ``` - - 1. Run EdgeX: - - ```bash - make run no-secty - ``` - - 1. Navigate out of the `edgex-compose` directory to the `device-onvif-camera` directory: - - ```bash - cd device-onvif-camera - ``` - 1. Run the service - ```bash - make run - ``` - -
-
-## Verify Service and Device Profiles
-
-### Using Command Line
-1. Check the status of the container:
-
- ```bash
- docker ps
- ```
-
- The status column will indicate if the container is running, and how long it has been up.
-
- Example Output:
-
- ```docker
- CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
- 33f9c5ecb70e edgexfoundry/device-onvif-camera:0.0.0-dev "/device-onvif-camer…" 7 weeks ago Up 48 minutes 127.0.0.1:59985->59985/tcp edgex-device-onvif-camera
- ```
-
-2. Check whether the device service is added to EdgeX:
-
- ```bash
- curl -s http://localhost:59881/api/v2/deviceservice/name/device-onvif-camera | jq .
- ```
- Successful:
- ```json
- {
- "apiVersion": "v2",
- "statusCode": 200,
- "service": {
- "created": 1657227634593,
- "modified": 1657291447649,
- "id": "e1883aa7-f440-447f-ad4d-effa2aeb0ade",
- "name": "device-onvif-camera",
- "baseAddress": "http://edgex-device-onvif-camera:59984",
- "adminState": "UNLOCKED"
- }
- }
- ```
- Unsuccessful:
- ```json
- {
- "apiVersion": "v2",
- "message": "fail to query device service by name device-onvif-camer",
- "statusCode": 404
- }
- ```
-
-
-3. Check whether the device profile is added:
-
- ```bash
- curl -s http://localhost:59881/api/v2/deviceprofile/name/onvif-camera | jq -r '"profileName: " + '.profile.name' + "\nstatusCode: " + (.statusCode|tostring)'
-
- ```
- Good response:
- ```bash
- profileName: onvif-camera
- statusCode: 200
- ```
- Bad response:
- ```bash
- profileName:
- statusCode: 404
- ```
- >**NOTE:** The `jq -r` option is used to reduce the size of the displayed response. The entire device profile with all resources can be seen by removing `-r '"profileName: " + '.profile.name' + "\nstatusCode: " + (.statusCode|tostring)', and replacing it with '.'`
-
-### Using EdgeX UI
-1. Visit http://localhost:4000 to go to the dashboard for EdgeX Console GUI:
-
- 
- Run the Service natively
- -- ->**NOTE:** Go version 1.20+ is required to run natively. See [here](https://go.dev/doc/install) for more information. - -
- - 1. Navigate to the EdgeX `compose-builder` directory: - - ```bash - cd edgex-compose/compose-builder/ - ``` - - 1. Run EdgeX: - - ```bash - make run no-secty - ``` - - 1. Navigate out of the `edgex-compose` directory to the `device-onvif-camera` directory: - - ```bash - cd device-onvif-camera - ``` - 1. Run the service - ```bash - make run - ``` - -
-
-
-[Optional] Run with NATS
- - ```bash - make run-nats - ``` - -- Figure 1: EdgeX Console Dashboard -
- -2. To see **Device Services**, **Devices**, or **Device Profiles**, click on their respective tab: - -  -- Figure 2: EdgeX Console Device Service List -
- -  -- Figure 3: EdgeX Console Device List -
- -  -- Figure 4: EdgeX Console Device Profile List -
-## Manage Devices -Follow these instructions to update devices. - -### Curl Commands - -#### Add Device - ->**NOTE:** The scripts used here are from the device-onvif-camera repository. - -
-
-
-Manually
- ->**NOTE:** Only use to manually add new devices that were not configured in the [Manually Configure the Pre-Defined Devices](#configuration) step. - -1. Edit the information to appropriately match the camera. The fields `Address`, `MACAddress` and `Port` should match that of the camera: - - ```bash - curl -X POST -H 'Content-Type: application/json' \ - http://localhost:59881/api/v2/device \ - -d '[ - { - "apiVersion": "v2", - "device": { - "name":"Camera001", - "serviceName": "device-onvif-camera", - "profileName": "onvif-camera", - "description": "My test camera", - "adminState": "UNLOCKED", - "operatingState": "UP", - "protocols": { - "Onvif": { - "Address": "10.0.0.0", - "Port": "10000", - "MACAddress": "aa:bb:cc:11:22:33", - "FriendlyName":"Default Camera" - }, - "CustomMetadata": { - "Location":"Front door" - } - } - } - } - ]' - ``` - - Example Output: - ```bash - [{"apiVersion":"v2","statusCode":201,"id":"fb5fb7f2-768b-4298-a916-d4779523c6b5"}] - ``` -
-
- ->**NOTE:** If auto discovery is required and was not configured with the [Configure Auto Discovery for ONVIF Devices](#configure-devices) steps above, the following steps will enable auto discovery using the `netscan` method _after_ the service has been deployed. - -ONVIF devices support WS-Discovery, which is a mechanism that supports probing a network to find ONVIF capable devices. Refer to [Auto Discovery](../auto-discovery.md) for detailed information on the auto-discovery mechanism. - ->**NOTE:** Ensure that the cameras are all installed and configured before attempting discovery. - -1. Navigate to the `device-onvif-camera` directory. - -2. Set the DiscoverySubnets by running `bin/configure-subnets.sh`. - -Device discovery is triggered by the device service. Once the device service starts, it will discover the Onvif camera(s) at the specified interval. ->**NOTE:** You can also manually trigger discovery using this command: `curl -X POST http://:59984/api/v2/discovery`
-
-
-
-Auto Discovery
- -- ->**NOTE:** If auto discovery is required and was not configured with the [Configure Auto Discovery for ONVIF Devices](#configure-devices) steps above, the following steps will enable auto discovery using the `netscan` method _after_ the service has been deployed. - -ONVIF devices support WS-Discovery, which is a mechanism that supports probing a network to find ONVIF capable devices. Refer to [Auto Discovery](../auto-discovery.md) for detailed information on the auto-discovery mechanism. - ->**NOTE:** Ensure that the cameras are all installed and configured before attempting discovery. - -1. Navigate to the `device-onvif-camera` directory. - -2. Set the DiscoverySubnets by running `bin/configure-subnets.sh`. - -Device discovery is triggered by the device service. Once the device service starts, it will discover the Onvif camera(s) at the specified interval. ->**NOTE:** You can also manually trigger discovery using this command: `curl -X POST http://
- -1. Map credentials using the `map-credentials.sh` script. - a. Navigate to the `device-onvif-camera` directory - b. Run `bin/map-credentials.sh` - c. Select `(Create New)` -  - d. Enter the Secret Name to associate with these credentials -  - e. Enter the username -  - f. Enter the password -  - g. Choose the Authentication Mode -  - h. Assign one or more MAC Addresses to the credential group -  - - >**NOTE:** The MAC address field can be left blank if the SecretName from the "Enter Secret Name ..." step above, is set to the DefaultSecretName (credentials001) from the [cmd/res/configuration.yaml](../../cmd/res/configuration.yaml). - - i. Learn more about updating credentials [here](../utility-scripts.md) - - Successful: - - ```bash - Dependencies Check: Success - Consul Check: ... - curl -X GET http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera?keys=true - Response [200] Success - curl -X GET http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap?keys=true - Response [200] - Secret Name: a - curl -X GET http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/a?raw=true - Response [404] - Failed! curl returned a status code of '404' - Setting InsecureSecret: a/SecretName - curl --data "
- Sample: Snippet from camera.yaml -
- - -### Configure the Provision Watchers - -The provision watcher sets up parameters for EdgeX to automatically add devices to core-metadata. They can be configured to look for certain features, as well as block features. The default provision watcher is sufficient unless you plan on having multiple different cameras with different profiles and resources. Learn more about provision watchers [here](https://docs.edgexfoundry.org/2.2/microservices/core/metadata/Ch-Metadata/#provision-watcher). - -```json -{ - "name":"Generic-Onvif-Provision-Watcher", - "identifiers":{ // Use the identifiers to filter through specific features of the protocol - "Address": ".", - "Manufacturer": "Intel", // example of a feature to allow through - "Model": "DFI6256TE" - }, - "blockingIdentifiers":{ - }, - "serviceName": "device-onvif-camera", - "profileName": "onvif-camera", - "adminState":"UNLOCKED" -} -``` -- Sample: Snippet from generic.provision.watcher.yaml -
- -## Summary and Next Steps -This guide demonstrated how to: - -- deploy EdgeX with the ONVIF Device Service -- use the EdgeX REST APIs and the ONVIF Device Service to acquire the camera's RTSP stream - -### Next Steps - -[Explore how to further use this device service](../general-usage.md) - -Refer to the main [README](../../README.md) to find links to the rest of the documents. - -## References - -- ONVIF Website: http://www.onvif.org -- EdgeX Foundry Project Wiki: https://wiki.edgexfoundry.org/ -- EdgeX Source Code: https://github.com/edgexfoundry -- Edgex Developer Guide: https://docs.edgexfoundry.org/2.1/ -- Docker Repos - - Docker https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository - - Docker Compose https://docs.docker.com/compose/install/#install-compose - -# License - -[Apache-2.0](https://github.com/edgexfoundry-holding/device-onvif-camera/blob/main/LICENSE) diff --git a/doc/guides/SimpleStartupGuide.md b/doc/guides/SimpleStartupGuide.md deleted file mode 100644 index 08c5fe48..00000000 --- a/doc/guides/SimpleStartupGuide.md +++ /dev/null @@ -1,549 +0,0 @@ -# ONVIF Device Service Simple Start Up Guide - -## Contents - -[System Requirements](#system-requirements) -[Dependencies](#dependencies) -[Deploy the Service](#deploy-edgex-and-onvif-device-camera-microservice) -[Verify the Service](#verify-service-and-device-profiles) -[Manage Devices](#manage-devices) -[Execute Example Command](#execute-getstreamuri-command-through-edgex) -[Shutting Down](#shutting-down) - -## System Requirements - -- Intel™ Core® processor -- Ubuntu 20.04.4 LTS -- ONVIF-compliant Camera - ->**NOTE:** The instructions in this guide were developed and tested using Ubuntu 20.04 LTS and the Tapo C200 Pan/Tilt Wi-Fi Camera, referred to throughout this document as the **Tapo C200 Camera**. However, the software may work with other Linux distributions and ONVIF-compliant cameras. Refer to our [list of tested cameras for more information](../ONVIF-protocol.md#tested-onvif-cameras) - -**Time to Complete** - -10-20 minutes - -**Other Requirements** - -You must have administrator (sudo) privileges to execute the user guide commands. - -## How It Works -For an explanation of the architecture, see the [User Guide](../../README.md#how-it-works). - -## Dependencies -The software has dependencies, including Git, Docker, Docker Compose, and assorted tools. Follow the instructions below to install any dependency that is not already installed. - -### Install Git -Install Git from the official repository as documented on the [Git SCM](https://git-scm.com/download/linux) site. - -1. Update installation repositories: - ```bash - sudo apt update - ``` - -2. Add the Git repository: - ```bash - sudo add-apt-repository ppa:git-core/ppa -y - ``` - -3. Install Git: - ```bash - sudo apt install git - ``` - -### Install Docker -Install Docker from the official repository as documented on the [Docker](https://docs.docker.com/engine/install/ubuntu/) site. - -### Verify Docker -To enable running Docker commands without the preface of sudo, add the user to the Docker group. Then run Docker with the `hello-world` test. - -1. Create Docker group: - ```bash - sudo groupadd docker - ``` - >**NOTE:** If the group already exists, `groupadd` outputs a message: **groupadd: group `docker` already exists**. This is OK. - -2. Add User to group: - ```bash - sudo usermod -aG docker $USER - ``` - -3. Restart your computer for the changes to take effect. - -4. To verify the Docker installation, run `hello-world`: - - ```bash - docker run hello-world - ``` - A **Hello from Docker!** greeting indicates successful installation. - - ```bash - Unable to find image 'hello-world:latest' locally - latest: Pulling from library/hello-world - 2db29710123e: Pull complete - Digest: sha256:10d7d58d5ebd2a652f4d93fdd86da8f265f5318c6a73cc5b6a9798ff6d2b2e67 - Status: Downloaded newer image for hello-world:latest - - Hello from Docker! - This message shows that your installation appears to be working correctly. - ... - ``` - -### Install Docker Compose -Install Docker Compose from the official repository as documented on the [Docker Compose](https://docs.docker.com/compose/install/linux/#install-using-the-repository) site. - -### Download EdgeX Compose - 1. Clone the EdgeX compose repository: - - ```bash - git clone https://github.com/edgexfoundry/edgex-compose.git - ``` - 1. Navigate to the `edgex-compose` directory: - - ```bash - cd edgex-compose - ``` - - 1. Checkout the Levski release: - - ```bash - git checkout levski - ``` - - Note: The `levski` branch is the latest stable branch at the time of this update. - - 1. Navigate back to your home directory: - - ```bash - cd ~ - ``` - -### Install Tools -Install the build, media streaming, and parsing tools: - - ```bash - sudo apt install build-essential ffmpeg jq curl - ``` - -### Tool Descriptions -The table below lists command line tools this guide uses to help with EdgeX configuration and device setup. - -| Tool | Description | Note | -| ----------- | ----------- |----------- | -| **curl** | Allows the user to connect to services such as EdgeX. |Use curl to get transfer information either to or from this service. In the tutorial, use `curl` to communicate with the EdgeX API. The call will return a JSON object.| -| **jq** |Parses the JSON object returned from the `curl` requests. |The `jq` command includes parameters that are used to parse and format data. In this tutorial, the `jq` command has been configured to return and format appropriate data for each `curl` command that is piped into it. | -| **base64** | Converts data into the Base64 format.| | - ->Table 1: Command Line Tools - -## Get the Source Code - -Clone the device-onvif-camera repository: - - ```bash - git clone https://github.com/edgexfoundry/device-onvif-camera.git - ``` - -## Deploy EdgeX and ONVIF Device Camera Microservice - -### Run the Service - -
-
-
-Run the Service using Docker
- - 1. Navigate to the EdgeX `compose-builder` directory: - - ```bash - cd edgex-compose/compose-builder/ - ``` - - 2. Run EdgeX with the microservice in non-secure mode: - - ```bash - make run no-secty ds-onvif-camera - ``` - - 3. Run EdgeX with the microservice in secure mode: - - ```bash - make run ds-onvif-camera - ``` -
-
- ->**NOTE:** Go version 1.20+ is required to run natively. - -
- - 1. Navigate to the EdgeX `compose-builder` directory: - - ```bash - cd edgex-compose/compose-builder/ - ``` - - 1. Run EdgeX: - - ```bash - make run no-secty - ``` - - 1. Navigate out of the `edgex-compose` directory to the `device-onvif-camera` directory: - - ```bash - cd device-onvif-camera - ``` - - 1. Run the service: - - ```bash - make run - ``` - -
-
-## Verify Service and Device Profiles
-
-1. Check the status of the container:
-
- ```bash
- docker ps
- ```
-
- The status column will indicate if the container is running and how long it has been up.
-
- Example Output:
-
- ```docker
- CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
- 33f9c5ecb70e edgexfoundry/device-onvif-camera:0.0.0-dev "/device-onvif-camer…" 7 weeks ago Up 48 minutes 127.0.0.1:59985->59985/tcp edgex-device-onvif-camera
- ```
-
-2. Check that the device service is added to EdgeX:
-
- ```bash
- curl -s http://localhost:59881/api/v2/deviceservice/name/device-onvif-camera | jq .
- ```
- Successful:
- ```json
- {
- "apiVersion": "v2",
- "statusCode": 200,
- "service": {
- "created": 1657227634593,
- "modified": 1657291447649,
- "id": "e1883aa7-f440-447f-ad4d-effa2aeb0ade",
- "name": "device-onvif-camera",
- "baseAddress": "http://edgex-device-onvif-camera:59984",
- "adminState": "UNLOCKED"
- }
- }
- ```
- Unsuccessful:
- ```json
- {
- "apiVersion": "v2",
- "message": "fail to query device service by name device-onvif-camer",
- "statusCode": 404
- }
- ```
-
-
-3. Check that the device profile is added:
-
- ```bash
- curl -s http://localhost:59881/api/v2/deviceprofile/name/onvif-camera | jq -r '"profileName: " + '.profile.name' + "\nstatusCode: " + (.statusCode|tostring)'
-
- ```
- Successful:
- ```bash
- profileName: onvif-camera
- statusCode: 200
- ```
- Unsuccessful:
- ```bash
- profileName:
- statusCode: 404
- ```
- >**NOTE:** The `jq -r` option is used to reduce the size of the displayed response. The entire device profile with all resources can be seen by removing `-r '"profileName: " + '.profile.name' + "\nstatusCode: " + (.statusCode|tostring)', and replacing it with '.'`
-
-## Manage Devices
-Follow these instructions to update devices.
-
-### Curl Commands
-
-#### Add Device
-
->**NOTE:** The scripts used here are from the device-onvif-camera repository.
-
-Run the Service natively
- -- ->**NOTE:** Go version 1.20+ is required to run natively. - -
- - 1. Navigate to the EdgeX `compose-builder` directory: - - ```bash - cd edgex-compose/compose-builder/ - ``` - - 1. Run EdgeX: - - ```bash - make run no-secty - ``` - - 1. Navigate out of the `edgex-compose` directory to the `device-onvif-camera` directory: - - ```bash - cd device-onvif-camera - ``` - - 1. Run the service: - - ```bash - make run - ``` - -
-
-
-Manually
- -1. Edit the information to appropriately match the camera. The fields `Address`, `MACAddress` and `Port` should match that of the camera: - - ```bash - curl -X POST -H 'Content-Type: application/json' \ - http://localhost:59881/api/v2/device \ - -d '[ - { - "apiVersion": "v2", - "device": { - "name":"Camera001", - "serviceName": "device-onvif-camera", - "profileName": "onvif-camera", - "description": "My test camera", - "adminState": "UNLOCKED", - "operatingState": "UP", - "protocols": { - "Onvif": { - "Address": "10.0.0.0", - "Port": "10000", - "MACAddress": "aa:bb:cc:11:22:33", - "FriendlyName":"Default Camera" - }, - "CustomMetadata": { - "Location":"Front door" - } - } - } - } - ]' - ``` - - Example Output: - ```bash - [{"apiVersion":"v2","statusCode":201,"id":"fb5fb7f2-768b-4298-a916-d4779523c6b5"}] - ``` -
-
-
- -ONVIF devices support WS-Discovery, which is a mechanism that supports probing a network to find ONVIF capable devices. Refer to [How does WS-Discovery work?](https://github.com/EdgeX-Camera-Management/device-onvif-camera/blob/main/doc/ws-discovery.md) and [Auto Discovery](https://github.com/EdgeX-Camera-Management/device-onvif-camera/blob/main/doc/auto-discovery.md) for more information auto-discovery mechanism. The following steps will enable auto discovery using the `netscan` method _after_ the service has been deployed. - -> **NOTE:** Ensure that the cameras are all installed and configured before attempting discovery. - -1. Navigate to the `device-onvif-camera` directory. - -2. Set the DiscoverySubnets by running `bin/configure-subnets.sh`. - -Device discovery is triggered by the device service. Once the device service starts, it will discover the Onvif camera(s) at the specified interval. -> **Note:** You can also manually trigger discovery using this command: `curl -X POST http://:59984/api/v2/discovery`
-
-
-
-Auto Discovery
- -- -ONVIF devices support WS-Discovery, which is a mechanism that supports probing a network to find ONVIF capable devices. Refer to [How does WS-Discovery work?](https://github.com/EdgeX-Camera-Management/device-onvif-camera/blob/main/doc/ws-discovery.md) and [Auto Discovery](https://github.com/EdgeX-Camera-Management/device-onvif-camera/blob/main/doc/auto-discovery.md) for more information auto-discovery mechanism. The following steps will enable auto discovery using the `netscan` method _after_ the service has been deployed. - -> **NOTE:** Ensure that the cameras are all installed and configured before attempting discovery. - -1. Navigate to the `device-onvif-camera` directory. - -2. Set the DiscoverySubnets by running `bin/configure-subnets.sh`. - -Device discovery is triggered by the device service. Once the device service starts, it will discover the Onvif camera(s) at the specified interval. -> **Note:** You can also manually trigger discovery using this command: `curl -X POST http://
- -1. Map credentials using the `map-credentials.sh` script. - a. Navigate to the `device-onvif-camera` directory - b. Run `bin/map-credentials.sh` - c. Select `(Create New)` -  - d. Enter the Secret Name to associate with these credentials -  - e. Enter the username -  - f. Enter the password -  - g. Choose the Authentication Mode -  - h. Assign one or more MAC Addresses to the credential group -  - - >**NOTE:** The MAC address field can be left blank if the SecretName from the "Enter Secret Name ..." step above, is set to the DefaultSecretName (credentials001) from the [cmd/res/configuration.yaml](../../cmd/res/configuration.yaml). - - i. Learn more about updating credentials [here](../utility-scripts.md) - - Successful: - - ```bash - Dependencies Check: Success - Consul Check: ... - curl -X GET http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera?keys=true - Response [200] Success - curl -X GET http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap?keys=true - Response [200] - Secret Name: a - curl -X GET http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/a?raw=true - Response [404] - Failed! curl returned a status code of '404' - Setting InsecureSecret: a/SecretName - curl --data "
- Figure 5: EdgeX Console Dashboard -
- -2. To get device status information, click on the tabs **Device Services**, **Devices**, or **Device Profiles**: - -  -- Figure 6: EdgeX Console Device Service List -
- -  -- Figure 7: EdgeX Console Device List -
- -  -- Figure 8: EdgeX Console Device Profile List -
- -## Execute GetStreamURI Command through EdgeX - -1. Get the profile token by executing the `GetProfiles` command: - - >**NOTE:** Make sure to replace `Camera001` in all the commands below, with the deviceName returned in the ["Verify device(s) have been successfully added to core-metadata"](#verify-device) step above. - - ```bash - curl -s http://0.0.0.0:59882/api/v2/device/name/Camera001/Profiles | jq -r '"profileToken: " + '.event.readings[].objectValue.Profiles[].Token'' - ``` - Example Output: - - ```bash - profileToken: profile_1 - profileToken: profile_2 - ``` - -2. To get the RTSP URI from the ONVIF device, execute the `GetStreamURI` command, using a profileToken found in [step 1](#step1): - In this example, `profile_1` is the profileToken: - - ```bash - curl -s "http://0.0.0.0:59882/api/v2/device/name/Camera001/StreamUri?jsonObject=$(base64 -w 0 <<< '{ - "StreamSetup" : { - "Stream" : "RTP-Unicast", - "Transport" : { - "Protocol" : "RTSP" - } - }, - "ProfileToken": "profile_1" - }')" | jq -r '"streamURI: " + '.event.readings[].objectValue.MediaUri.Uri'' - ``` - - Example Output: - - ```bash - streamURI: rtsp://192.168.86.34:554/stream1 - ``` - -3. Stream the RTSP stream. - - ffplay can be used to stream. The command follows this format: - - `ffplay -rtsp_transport tcp "rtsp://
-
-
-Run the Service using Docker
- - 1. Navigate to the EdgeX `compose-builder` directory: - - ```bash - cd edgex-compose/compose-builder/ - ``` - - 1. Run EdgeX with the microservice in non-secure mode: - - ```bash - make run no-secty ds-onvif-camera - ``` - - 1. Run EdgeX with the microservice in secure mode: - - ```bash - make run ds-onvif-camera - ``` -
-
-
-## Verify Service and Device Profiles
-
-### Using Command Line
-1. Check the status of the container:
-
- ```bash
- docker ps
- ```
-
- The status column will indicate if the container is running, and how long it has been up.
-
- Example Output:
-
- ```docker
- CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
- 33f9c5ecb70e nexus3.edgexfoundry.org:10004/device-onvif-camera:latest "/device-onvif-camer…" 7 weeks ago Up 48 minutes 127.0.0.1:59985->59985/tcp edgex-device-onvif-camera
- ```
-
-2. Check whether the device service is added to EdgeX:
-
- ```bash
- curl -s http://localhost:59881/api/v2/deviceservice/name/device-onvif-camera | jq .
- ```
- Good response:
- ```json
- {
- "apiVersion": "v2",
- "statusCode": 200,
- "service": {
- "created": 1657227634593,
- "modified": 1657291447649,
- "id": "e1883aa7-f440-447f-ad4d-effa2aeb0ade",
- "name": "device-onvif-camera",
- "baseAddress": "http://edgex-device-onvif-camera:59984",
- "adminState": "UNLOCKED"
- }
- }
- ```
- Bad response:
- ```json
- {
- "apiVersion": "v2",
- "message": "fail to query device service by name device-onvif-camer",
- "statusCode": 404
- }
- ```
-
-
-3. Check whether the device profile is added:
-
- ```bash
- curl -s http://localhost:59881/api/v2/deviceprofile/name/onvif-camera | jq -r '"profileName: " + '.profile.name' + "\nstatusCode: " + (.statusCode|tostring)'
-
- ```
- Good response:
- ```bash
- profileName: onvif-camera
- statusCode: 200
- ```
- Bad response:
- ```bash
- profileName:
- statusCode: 404
- ```
- > note: `jq -r` is used to reduce the size of the displayed response. The entire device profile with all resources can be seen by removing `-r '"profileName: " + '.profile.name' + "\nstatusCode: " + (.statusCode|tostring)', and replacing it with '.'`
-
-### Using EdgeX UI
-1. Visit http://localhost:4000 to go to the dashboard for EdgeX Console GUI:
-
- 
- Run the Service natively
- - >**NOTE:** Go version 1.20+ is required to run natively. See [here](https://go.dev/doc/install) for more information. - - 1. Navigate to the EdgeX `compose-builder` directory: - - ```bash - cd edgex-compose/compose-builder/ - ``` - - 1. Run EdgeX: - - ```bash - make run no-secty - ``` - - 1. Navigate out of the `edgex-compose` directory to the `device-onvif-camera` directory: - - ```bash - cd device-onvif-camera - ``` - - 1. Run the service - ```bash - make run - ``` - -
-
-
-[Optional] Run with NATS
- - ```bash - make run-nats - ``` - -- Figure 1: EdgeX Console Dashboard -
- -2. To see **Device Services**, **Devices**, or **Device Profiles**, click on their respective tab: - -  -- Figure 2: EdgeX Console Device Service List -
- -  -- Figure 3: EdgeX Console Device List -
- -  -- Figure 4: EdgeX Console Device Profile List -
-## Manage Devices -Follow these instructions to update devices. - - -### Curl Commands - -#### Add Device - -1. Edit the information to appropriately match the camera. The fields `Address`, `MACAddress` and `Port` should match that of the camera: - - ```bash - curl -X POST -H 'Content-Type: application/json' \ - http://localhost:59881/api/v2/device \ - -d '[ - { - "apiVersion": "v2", - "device": { - "name":"Camera001", - "serviceName": "device-onvif-camera", - "profileName": "onvif-camera", - "description": "My test camera", - "adminState": "UNLOCKED", - "operatingState": "UP", - "protocols": { - "Onvif": { - "Address": "10.0.0.0", - "Port": "10000", - "MACAddress": "aa:bb:cc:11:22:33", - "FriendlyName":"Default Camera" - }, - "CustomMetadata": { - "Location":"Front door" - } - } - } - } - ]' - ``` - - Example Output: - ```bash - [{"apiVersion":"v2","statusCode":201,"id":"fb5fb7f2-768b-4298-a916-d4779523c6b5"}] - ``` - - Map credentials using the `map-credentials.sh` script. - a. Run `bin/map-credentials.sh` - b. Select `(Create New)` -  - c. Enter the Secret Name to associate with these credentials -  - d. Enter the username -  - e. Enter the password -  - f. Choose the Authentication Mode -  - g. Assign one or more MAC Addresses to the credential group -  - h. Learn more about updating credentials [here](../utility-scripts.md) - - Successful: - - ```bash - Dependencies Check: Success - Consul Check: ... - curl -X GET http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera?keys=true - Response [200] Success - curl -X GET http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap?keys=true - Response [200] - Secret Name: a - curl -X GET http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/a?raw=true - Response [404] - Failed! curl returned a status code of '404' - Setting InsecureSecret: a/SecretName - curl --data "
-
-WS-Discovery is generally faster than netscan becuase it only sends out one broadcast signal. However, it is normally limited by the network segmentation since the multicast packages typically do not traverse routers.
-
-- Find the WS-Discovery programmer guide from https://www.onvif.org/profiles/whitepapers/
-- Wiki page https://en.wikipedia.org/wiki/WS-Discovery
-
-Example:
-1. The client sends Probe message to find Onvif camera on the network.
- ```xml
-
-