Deployment

Follow this guide to deploy and run the service.

DockerNative

Navigate to the Edgex compose directory.

cd ~/edgex/edgex-compose/compose-builder

Checkout the latest release (v3.0):
```
git checkout v3.0
```
Run EdgeX with the USB microservice in secure or non-secure mode:

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

Note

Recommended for secure and production level deployments.
```
make run ds-usb-camera
```

Navigate to the Edgex compose directory.

cd ~/edgex/edgex-compose/compose-builder

Checkout the latest release (v3.0):
```
git checkout v3.0
```
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.0):
```
git checkout v3.0
```
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 that the device service is added to EdgeX:

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

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

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:
```
UVC Camera (012d:0678) (usb-0000:00:14.0-5):
    /dev/video0
    /dev/video1
    /dev/media0
```
For this example, the Path is /dev/video0.
Run the following command to determine the CardName of the usb camera (you have the insert the correct path determined from the previous step into this command):
```
v4l2-ctl --all --device /dev/video0 | grep Name
```
Output should look like:
```
Name             : UVC Camera (012d:0678)
```
Run the following command to determine the SerialNumber of the usb camera (you have the insert the correct path determined from the previous step into this command):
```
v4l2-ctl --all --device /dev/video0 | grep Serial
```
Output should look like:
```
Serial           : 71C0AE6
```

Edit the information to appropriately match the camera. The device's protocol properties contain:

name is the name of the device. For this example, the name is Camera001
Path is a file descriptor of camera created by the OS. Use the Path determined in the previous step.
CardName is the model name of the camera. Use the CardName determined in the previous step.
SerialNumber is the serial number of the camera. Use the SerialNumber determined in the previous step.
AutoStreaming indicates whether the device service should automatically start video streaming for cameras. Default value is false.

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": "UVC Camera (012d:0678)",
            "SerialNumber": "71C0AE6","
            "Path": "/dev/video0",
            "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

Verify Service, Device Profiles, and Device

Add credentials for the rtsp stream.

Manage Devices