Deployment

Follow this guide to deploy and run the service.

DockerNative

Navigate to the Edgex compose directory.
```
cd edgex-compose/compose-builder
```
Checkout the latest release (v3.1):
```
git checkout v3.1
```
Run EdgeX with the USB microservice in secure or non-secure mode:

Non-secure mode
```
make run ds-usb-camera no-secty
```
Secure mode

Note

Recommended for secure and production level deployments.
```
make run ds-usb-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.

Navigate to the Edgex compose directory.
```
cd edgex-compose/compose-builder
```
Checkout the latest release (v3.1):
```
git checkout v3.1
```
Run EdgeX:
```
make run no-secty
```
Navigate out of the edgex-compose directory to the device-usb-camera directory:
```
cd device-usb-camera
```
Checkout the latest release (v3.1):
```
git checkout v3.1
```
Build the executable
```
make build
```
[Optional] Build with NATS Messaging
Currently, the NATS Messaging capability (NATS MessageBus) is opt-in at build time. To build using NATS, run make build-nats:
```
make build-nats
```

Deploy the service

cd cmd && EDGEX_SECURITY_SECRET_STORE=false ./device-usb-camera

Verify Service, Device Profiles, and Device

Check the status of the container:

docker ps -f name=device-usb-camera

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
f0a1c646f324   edgexfoundry/device-usb-camera:0.0.0-dev                        "/docker-entrypoint.…"   26 hours ago   Up 20 hours   127.0.0.1:8554->8554/tcp, 127.0.0.1:59983->59983/tcp                         edgex-device-usb-camera                                                                   edgex-device-onvif-camera

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-usb-camera' \
--header 'Authorization: Bearer <jwt-token>' \
--data-raw ''

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

Successful:

{
    "apiVersion" : "v3",
    "statusCode": 200,
    "service": {
        "created": 1658769423192,
        "modified": 1658872893286,
        "id": "04470def-7b5b-4362-9958-bc5ff9f54f1e",
        "name": "device-usb-camera",
        "baseAddress": "http://edgex-device-usb-camera:59983",
        "adminState": "UNLOCKED"
    }
}

Unsuccessful:

{
    "apiVersion" : "v3",
    "message": "fail to query device service by name device-usb-camera",
    "statusCode": 404
}

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: NexiGo_N930AF_FHD_Webcam_NexiG-20201217010
```
Note

The jq -r option 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 '.'

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-usb-camera?keys=true"
```

Add credentials for the rtsp stream.

Note

If you want to disable rtsp authentication entirely, you must build a custom image.

Non-secure ModeSecure Mode

Enter your chosen username and password into this command, and then execute it to set the insecure secrets.

Example credential command

```bash
curl --data '{
    "apiVersion" : "v3",
    "secretName": "rtspauth",
    "secretData":[
        {
            "key":"username",
            "value":"<pick-a-username>"
        },
        {
            "key":"password",
            "value":"<pick-a-secure-password>"
        }
    ]
}' -X POST http://localhost:59983/api/v3/secret
```

Navigate to the edgex-compose/compose-builder directory.
Generate a JWT token
```
make get-token
```
Enter your chosen username and password, and the generated JWT into this command, and then execute it to set the secure secrets.

Example credential command

curl --data '{
    "apiVersion" : "v3",
    "secretName": "rtspauth",
    "secretData":[
        {
            "key":"username",
            "value":"<pick-a-username>"
        },
        {
            "key":"password",
            "value":"<pick-a-secure-password>"
        }
    ]
}' -H Authorization:Bearer "<enter your JWT token here (make get-token)>" -X POST http://localhost:59983/api/v3/secret

Manage Devices

Warning

This section only needs to be performed if discovery is disabled. Discovery is enabled by default.

Devices can either be added to the service by defining them in a static configuration file, discovering devices dynamically, or with the REST API. For this example, the device will be added using the REST API.

Run the following command to determine the Path to the usb camera for video streaming:
```
v4l2-ctl --list-devices
```
The output should look similar to this:
```
NexiGo N930AF FHD Webcam: NexiG (usb-0000:00:14.0-1):
    /dev/video6
    /dev/video7
    /dev/media2
```
For this example, the Path is /dev/video6.

Edit the information to appropriately match the camera. Find more information about the device protocol properties here.

Example Command

curl -X POST -H 'Content-Type: application/json'  \
http://localhost:59881/api/v3/device \
-d '[
    {
    "apiVersion" : "v3",
    "device": {
        "name": "Camera001",
        "serviceName": "device-usb-camera",
        "profileName": "USB-Camera-General",
        "description": "My test camera",
        "adminState": "UNLOCKED",
        "operatingState": "UP",
        "protocols": {
            "USB": {
            "CardName": "NexiGo N930AF FHD Webcam: NexiG",
            "Paths": ["/dev/video6",],
            "AutoStreaming": "false"
            }
        }
    }
    }
]'

Example output:

[{"apiVersion" : "v3","statusCode":201,"id":"fb5fb7f2-768b-4298-a916-d4779523c6b5"}]

Learn how to use the device service>

Deployment

Non-secure mode

Secure mode

Token Generation (secure mode only)

Verify Service, Device Profiles, and Device

Add credentials for the rtsp stream.

Manage Devices