Skip to content

General Usage

This document will describe how to execute some of the most important types of commands used with the device service.

Start Video Streaming

Unless the device service is configured to stream video from the camera automatically, a StartStreaming command must be sent to the device service.

Note

Streaming credentials for the rtsp stream must be added prior to starting the stream. Please refer to Deployment for additional information.

There are two types of options: - The options that start with Input as a prefix are used for camera configuration, such as specifying the image size and pixel format. - The options that start with Output as a prefix are used for video output configuration, such as specifying aspect ratio and quality.

These options can be passed in through Object value when calling StartStreaming.

Query parameter:
- device name: The name of the camera

Example StartStreaming Command

curl -X PUT -d '{
    "StartStreaming": {
    "InputImageSize": "640x480",
    "OutputVideoQuality": "5"
    }
}' http://localhost:59882/api/v3/device/name/<device name>/StartStreaming

Note

If running in secure mode all the api executions (for this api and subsequent apis) need the JWT token generated previously. E.g. 

curl -X PUT -d '{
    "StartStreaming": {
    "InputImageSize": "640x480",
    "OutputVideoQuality": "5"
    }
}' http://localhost:59882/api/v3/device/name/<device name>/StartStreaming \
--header 'Authorization: Bearer <jwt-token>'

Example output: 

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

Supported Input options:

  • InputFps: Ignore original timestamps and instead generate timestamps assuming constant frame rate fps. (default - same as source)
  • InputImageSize: Specifies the image size of the camera. The format is wxh, for example "640x480". (default - automatically selected by FFmpeg)
  • InputPixelFormat: Set the preferred pixel format (for raw video). (default - automatically selected by FFmpeg)

Supported Output options:

  • OutputFrames: Set the number of video frames to output. (default - no limitation on frames)
  • OutputFps: Duplicate or drop input frames to achieve constant output frame rate fps. (default - same as InputFps)
  • OutputImageSize: Performs image rescaling. The format is wxh, for example "640x480". (default - same as InputImageSize)
  • OutputAspect: Set the video display aspect ratio specified by aspect. For example "4:3", "16:9". (default - same as source)
  • OutputVideoCodec: Set the video codec. For example "mpeg4", "h264". (default - mpeg4)
  • OutputVideoQuality: Use fixed video quality level. Range is a integer number between 1 to 31, with 31 being the worst quality. (default - dynamically set by FFmpeg)

Determine Stream Uri of Camera

The device service provides a way to determine the stream URI of a camera.

Query parameter:
- device name: The name of the camera

Example StreamURI Command

curl -s http://localhost:59882/api/v3/device/name/<device name>/StreamURI | jq -r '"StreamURI: " + '.event.readings[].value''

Example output: 

StreamURI: rtsp://localhost:8554/stream/NexiGo_N930AF_FHD_Webcam__NexiG-20201217010

Play the RTSP stream.

mplayer can be used to stream. The command follows this format: 

mplayer rtsp://'<username>:<password>'@<IP address>:<port>/<streamname>`.

Using the streamURI returned from the previous step, run mplayer:

Example Stream Command

mplayer rtsp://'admin:pass'@localhost:8554/stream/NexiGo_N930AF_FHD_Webcam__NexiG-20201217010

To shut down mplayer, use the ctrl-c command.

Stop Video Streaming

To stop the usb camera from live streaming, use the following command:

Query parameter:
- device name: The name of the camera

Example StopStreaming Command

curl -X PUT -d '{
    "StopStreaming": "true"
}' http://localhost:59882/api/v3/device/name/<device name>/StopStreaming

Example output: 

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

Optional: Shutting Down

To stop all EdgeX services (containers), execute the make down command:

  1. Navigate to the edgex-compose/compose-builder directory.

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

  2. Run this command 

    make down

  3. To shut down and delete all volumes, run this command

    Warning

    This will delete all edgex-related data. 

    make clean

Troubleshooting Guide

StreamingStatus

To verify the usb camera is set to stream video, use the command below 

curl http://localhost:59882/api/v3/device/name/<device name>/StreamingStatus | jq -r '"StreamingStatus: " + (.event.readings[].objectValue.IsStreaming|tostring)'
If the StreamingStatus is false, the camera is not configured to stream video. Please try the Start Video Streaming section again here.

V4L2 error

If you get an error like this: 

.../go4vl@v0.0.2/v4l2/capability.go:48:33: could not determine kind of name for C.V4L2_CAP_IO_MC
.../go4vl@v0.0.2/v4l2/capability.go:46:33: could not determine kind of name for C.V4L2_CAP_META_OUTPUT
You are missing the appropriate kernel headers needed by the github.com/vladimirvivien/go4vl module. One possible solution is to manually download and install a more recent version of the libc-dev for your OS.

In the case of Ubuntu 20.04, one is not available in the normal repositories, so you can get it via these steps: 

wget https://launchpad.net/~canonical-kernel-team/+archive/ubuntu/bootstrap/+build/20950478/+files/linux-libc-dev_5.10.0-14.15_amd64.deb
sudo dpkg -i linux-libc-dev_5.10.0-14.15_amd64.deb