Deployment

Follow this guide to deploy and run the service.

Deploy EdgeX and ONVIF Device Camera Microservice

DockerNative

Navigate to the EdgeX compose-builder directory:
```
cd edgex-compose/compose-builder/
```
Run EdgeX with the microservice in non-secure mode:
```
make run no-secty ds-onvif-camera
```
Run EdgeX with the microservice in secure mode:
```
make run ds-onvif-camera
```

Note

Go version 1.20+ is required to run natively. See here for more information.

Navigate to the EdgeX compose-builder directory:
```
cd edgex-compose/compose-builder/
```
Run EdgeX:
```
make run no-secty
```
Navigate out of the edgex-compose directory to the device-onvif-camera directory:
```
cd device-onvif-camera
```
Run the service
```
make run
```
[Optional] Run with NATS
```
make run-nats
```

Verify Service and Device Profiles

via Command Linevia EdgeX UI

Check the status of the container:

docker ps

The status column will indicate if the container is running, and how long it has been up.

Example Output:

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

Check whether the device service is added to EdgeX:

curl -s http://localhost:59881/api/v2/deviceservice/name/device-onvif-camera | jq .

Good response:

   {
      "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:

{
   "apiVersion": "v2",
   "message": "fail to query device service by name device-onvif-camer",
   "statusCode": 404
}

Check whether the device profile is added:
```
curl -s http://localhost:59881/api/v2/deviceprofile/name/onvif-camera | jq -r '"profileName: " + '.profile.name' + "\nstatusCode: " + (.statusCode|tostring)'
```
Good response:
```
profileName: onvif-camera
statusCode: 200
```
Bad response:
```
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 '.'

Visit http://localhost:4000 to go to the dashboard for EdgeX Console GUI:

Figure 1: EdgeX Console Dashboard
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

Edit the information to appropriately match the camera. The fields Address, MACAddress and Port should match that of the camera:

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:

[{"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 Path 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

Successful:

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 Path: 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/SecretPath
curl --data "<redacted>" -X PUT http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/Writable/InsecureSecrets/a/SecretPath
Response [200] true


Setting InsecureSecret: a/SecretData/username
curl --data "<redacted>" -X PUT http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/Writable/InsecureSecrets/a/SecretData/username
Response [200] true


Setting InsecureSecret: a/SecretData/password
curl --data "<redacted>" -X PUT http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/Writable/InsecureSecrets/a/SecretData/password
Response [200] true


Setting InsecureSecret: a/SecretData/mode
curl --data "usern<redacted>metoken" -X PUT http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/Writable/InsecureSecrets/a/SecretData/mode
Response [200] true


Setting Credentials Map: a = ''
curl -X PUT http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/a
Response [200] true



Secret Path: a
curl -X GET http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/a?raw=true
Response [200] 
Setting Credentials Map: a = '11:22:33:44:55:66'
curl --data "11:22:33:44:55:66" -X PUT http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/a
Response [200] true

Verify device(s) have been succesfully added to core-metadata.
```
curl -s http://localhost:59881/api/v2/device/all | jq -r '"deviceName: " + '.devices[].name''
```
Example Output: bash deviceName: Camera001 deviceName: device-onvif-camera

Note

jq -r is used to reduce the size of the displayed response. The entire device with all information can be seen by removing -r '"deviceName: " + '.devices[].name'', and replacing it with '.'

Update Device

There are multiple commands that can update aspects of the camera entry in meta-data. Refer to the Swagger documentation for Core Metadata for more information. For editing specific fields, see the General Usage tab.

Delete Device

curl -X 'DELETE' \
'http://localhost:59881/api/v2/device/name/<device name>' \
-H 'accept: application/json'

Shutting Down

To stop all EdgeX services (containers), execute the make down command. This will stop all services but not the images and volumes, which still exist.

Navigate to the edgex-compose/compose-builder directory.
Run this command
```
make down
```
To shut down and delete all volumes, run this command
```
make clean
```

Next Steps

Learn how to use the device service>

License

Apache-2.0