Skip to content

Deployment

Follow this guide to deploy and run the service.

Deploy EdgeX and ONVIF Device Camera Microservice

  1. Navigate to the EdgeX compose-builder directory:

    cd edgex-compose/compose-builder/

  2. Checkout the latest release (main):

    git checkout main

  3. Run Edgex with the ONVIF microservice in secure or non-secure mode.

    Non-secure mode
    make run no-secty ds-onvif-camera
    Secure mode

    Note

    Recommended for secure and production level deployments. 

    make run ds-onvif-camera

    Token Generation (secure mode only)

    Note

    Need to wait for sometime for the services to be fully up before executing the next set of commands. Securely store Consul ACL token and the JWT token generated which are needed to map credentials and execute apis. It is not recommended to store these secrets in cleartext in your machine.

    Note

    The JWT token expires after 119 minutes, and you will need to generate a new one.

    Generate the Consul ACL Token. Use the token generated anywhere you see <consul-token> in the documentation. 

    make get-consul-acl-token
    Example output: 
    12345678-abcd-1234-abcd-123456789abc

    Generate the JWT Token. Use the token generated anywhere you see <jwt-token> in the documentation. 

    make get-token
    Example output: eyJhbGciOiJFUzM4NCIsImtpZCI6IjUyNzM1NWU4LTQ0OWYtNDhhZC05ZGIwLTM4NTJjOTYxMjA4ZiJ9.eyJhdWQiOiJlZGdleCIsImV4cCI6MTY4NDk2MDI0MSwiaWF0IjoxNjg0OTU2NjQxLCJpc3MiOiIvdjEvaWRlbnRpdHkvb2lkYyIsIm5hbWUiOiJlZGdleHVzZXIiLCJuYW1lc3BhY2UiOiJyb290Iiwic3ViIjoiMGRjNThlNDMtNzBlNS1kMzRjLWIxM2QtZTkxNDM2ODQ5NWU0In0.oa8Fac9aXPptVmHVZ2vjymG4pIvF9R9PIzHrT3dAU11fepRi_rm7tSeq_VvBUOFDT_JHwxDngK1VqBVLRoYWtGSA2ewFtFjEJRj-l83Vz33KySy0rHteJIgVFVi1V7q5

    Note

    Secrets such as passwords, certificates, tokens and more in Edgex are stored in a secret store which is implemented using Vault a product of Hashicorp. Vault supports security features allowing for the issuing of consul tokens. JWT token is required for the API Gateway which is a trust boundry for Edgex services. It allows for external clients to be verified when issuing REST requests to the microservices. For more info refer Secure Consul, API Gateway and Edgex Security.

Note

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

  1. Navigate to the EdgeX compose-builder directory:

    cd edgex-compose/compose-builder/

  2. Checkout the latest release (main):

    git checkout main

  3. Run EdgeX:

    make run no-secty

  4. Navigate out of the edgex-compose directory to the device-onvif-camera directory:

    cd device-onvif-camera

  5. Checkout the latest release (main):

    git checkout main

  6. Run the service 

    make run

    [Optional] Run with NATS 
    make run-nats

Verify Service and Device Profiles

  1. 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

  2. Check whether the device service is added to EdgeX:

    Note

    If running in secure mode all the api executions need the JWT token generated previously. E.g. 

    curl --location --request GET 'http://localhost:59881/api/v3/deviceservice/name/device-onvif-camera' \
--header 'Authorization: Bearer <jwt-token>' \
--data-raw ''


    curl -s http://localhost:59881/api/v3/deviceservice/name/device-onvif-camera | jq .
    Good response: 
    {
    "apiVersion" : "v3",
    "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" : "v3",
"message": "fail to query device service by name device-onvif-camer",
"statusCode": 404
}

  3. Check whether the device profile is added:

    curl -s http://localhost:59881/api/v3/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 '.'

Note

Secure mode login to Edgex UI requires the JWT token generated in the above step

Entering the JWT token

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

    EdgeXConsoleDashboard

    Figure 1: EdgeX Console Dashboard

  2. To see Device Services, Devices, or Device Profiles, click on their respective tab:

    EdgeXConsoleDeviceServices

    Figure 2: EdgeX Console Device Service List

    EdgeXConsoleDeviceList

    Figure 3: EdgeX Console Device List

    EdgeXConsoleDeviceProfileList

    Figure 4: EdgeX Console Device Profile List

Additionally, ensure that the service config has been deployed and that Consul is reachable.

Note

If running in secure mode this command needs the Consul ACL token generated previously.

curl -H "X-Consul-Token:<consul-token>" -X GET "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera?keys=true"

Example output: 

["edgex/v3/device-onvif-camera/AppCustom/BaseNotificationURL", "edgex/v3/device-onvif-camera/AppCustom/CheckStatusInterval",
  "edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/NoAuth", ... , "edgex/v3/device-onvif-camera/Writable/InsecureSecrets/credentials001/SecretData/username", "edgex/v3/device-onvif-camera/Writable/InsecureSecrets/credentials001/SecretName",
  "edgex/v3/device-onvif-camera/Writable/LogLevel"]

Manage Devices

Follow these instructions to add and update devices manually.

Curl Commands

Add Device

Warning

Be careful when storing any potentially important information in cleartext on files in your computer. This includes information such as your camera IP and MAC addresses.

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

    Note

    If running in secure mode the commands might need the JWT or consul token generated previously.

    curl -X POST -H 'Content-Type: application/json'  \
http://localhost:59881/api/v3/device \
-d '[
         {
            "apiVersion" : "v3",
            "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" : "v3","statusCode":201,"id":"fb5fb7f2-768b-4298-a916-d4779523c6b5"}]

  2. Update credentials in Secret Store.

    Note

    If running in secure mode all the api executions need the JWT token generated previously.

    Enter your chosen username, password, and authentication mode and credentials name and then execute the command to create the secrets.

    Note

    The options for authentication mode are: usernametoken, digest, or both

    curl --data '{
            "apiVersion" : "v3",
            "secretName": "<creds-name>",
            "secretData":[
                {
                    "key":"username",
                    "value":"<username>"
                },
                {
                    "key":"password",
                    "value":"<password>"
                },
                {
                    "key":"mode",
                    "value":"<auth-mode>"
                }
            ]
        }' --header 'Authorization:Bearer <jwt-token>' -X POST "http://localhost:59984/api/v3/secret"
    Example output: 
    {"apiVersion":"v3","statusCode":201}

    Enter your chosen username, password, and authentication mode and credentials name and then execute the command to create the secrets.

    Note

    The options for authentication mode are: usernametoken, digest, or both

    curl --data '{
            "apiVersion" : "v3",
            "secretName": "<creds-name>",
            "secretData":[
                {
                    "key":"username",
                    "value":"<username>"
                },
                {
                    "key":"password",
                    "value":"<password>"
                },
                {
                    "key":"mode",
                    "value":"<auth-mode>"
                }
            ]
        }' -X POST "http://localhost:59984/api/v3/secret"

    Example output: 

    {"apiVersion":"v3","statusCode":201}

  3. Map credentials to devices.

    a. Enter your mac-address(es) and then execute the command to add the mac address(es) to the mapping.

    Note

    If you want to map multiple mac addresses, enter a comma separated list in the command

    curl --data '<mac-address>' -H "X-Consul-Token:<consul-token>" -X PUT "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/<creds-name>"
    Example output: 
    true

    b. Check the status of the credentials map. 

    curl -H "X-Consul-Token:<consul-token>" -X GET "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap?keys=true" | jq .
    Example output: 
    [
"edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/NoAuth",
"edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/credentials001",
"edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/credentials002"
]

    c. Check the mac addresses mapped to a specific credenential name. Insert the credential name in the command to see the mac addresses associated with it. 

    curl -H "X-Consul-Token:<consul-token>" -X GET "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/<creds-name>?raw=true"
    Example output: 
    11:22:33:44:55:66

    a. Enter your mac-address(es) and then execute the command to add the mac address(es) to the mapping.

    Note

    If you want to map multiple mac addresses, enter a comma separated list in the command

    curl --data '<mac-address>' -X PUT "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/<creds-name>"

    Example output: 

    true

    b. Check the status of the credentials map. 

    curl -X GET "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap?keys=true" | jq .
    Example output: 
    [
"edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/NoAuth",
"edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/credentials001",
"edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/credentials002"
]

    c. Check the mac addresses mapped to a specific credenential name. Insert the credential name in the command to see the mac addresses associated with it. 

    curl -X GET "http://localhost:8500/v1/kv/edgex/v3/device-onvif-camera/AppCustom/CredentialsMap/<creds-name>?raw=true"
    Example response: 
    11:22:33:44:55:66

    Note

    The helper scripts may also be used, but they have been deprecated.

  4. Verify device(s) have been successfully added to core-metadata.

    curl -s http://localhost:59881/api/v3/device/all | jq -r '"deviceName: " + '.devices[].name''

    Example output: 

    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/v3/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.

  1. Navigate to the edgex-compose/compose-builder directory.
  2. Run this command 
    make down
  3. 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