Service Usage Instructions

Camera Microservice 0.1.2

Camera Microservice will capture from external MIPI cameras and generate an RTSP stream for each of them. The service support any number of cameras, the hardware will limit this amount.

By default the service will not start capturing from any camera, you need to give the service the camera(s) configuration through a file when starting the service or the through the server with the configuration request. In both cases, the configuration is defined in JSON format as follows:

{
    "camera0": {
        "index": 0,
        "resolution": {
            "width": 1920,
            "height": 1080
        },
        "streaming": {
            "port": 6060,
            "mapping": "stream0",
            "bitrate": 2000,
            "uri": "rtsp://127.0.0.1:6060/stream0"
        }
    },
    "camera1": {
        "index": 2,
        "resolution": {
            "width": 1920,
            "height": 1080
        },
        "streaming": {
            "port": 6061,
            "mapping": "stream1",
            "bitrate": 2000,
            "uri": "rtsp://127.0.0.1:6061/stream1"
        }
    }
}

This configuration allows to include any number of cameras using this format. The identifies camera0, camera1, cameraN can be any name selected by the user.

Configuration entries:

index: This value corresponds to the camera device index under /dev. For example, an index of 0 will refer to the device /dev/video0.
resolution
- width: Specifies the width of the video frame to capture, in pixels.
- height: Specifies the height of the video frame to capture in pixels.
streaming
- port: Defines the network port on which the video rtsp stream will be available.
- mapping: Indicates the network mapping for the stream.
- bitrate: Sets the encoding bitrate in bits per second (bps).
- uri: RTSP URI of the camera.

Note: The uri entry is included in the retrieved configuration. However, when setting the configuration, this entry is optional. If provided during configuration, it will be ignored, as the service handles this internally.

Running the service

The project is configured (via setup.py) to install the service with the name camera. So to install it run:

pip install .

Then you will have the service with the following options:

usage: camera [-h] [--config_file CONFIG_FILE] [--port PORT] [--host HOST]

options:
  -h, --help            show this help message and exit
  --config_file CONFIG_FILE
                        JSON file with cameras configuration
  --port PORT           Port for server
  --host HOST           Server ip address

To start the service in address 127.0.0.1 and port 5050 just run:

camera

If you want to serve in a different port or address, use the –port and –host options.

Camera Microservice Docker

Before starting with docker support make sure you have nvidia runtime in your system. Follow these instructions to have docker up and runing in your Jetson Board.

Build the container

We can build this microservice container using the Dockerfile in the docker directory. This includes a base NVIDA image and the dependencies to run the camera microservice application.

First, we need to prepare the context directory for this build, please create a directory and include all the needed repositories (listed below). The Dockerfile will look for all the source code in the context directory and copy them to the container.

camera-context/
├── camera
├── cuda-undistort
├── gst-cuda
├── gst-rtsp-sink
└── rrms-utils

To build the Docker image with a gst-rtspsink eval, it will be necessary to clone a repository using git, for that we share the ssh-agent to Docker, use these commands to enable the ssh-agent:

eval $(ssh-agent)
ssh-add ~/.ssh/id_rsa

Verify that after the previous commands the $SSH_AUTH_SOCK variable is available:

echo $SSH_AUTH_SOCK

# Output
/tmp/ssh-XXXXDmihix/agent.2499

Then build the Docker image running the following command from the folder contaning the Dockerfile and context directory:

sudo docker build \
--ssh default=$SSH_AUTH_SOCK \
--network=host \
-f Dockerfile \
-t ridgerun/camera-service:latest \
camera-context/

Change camera-context to your context’s path and the tag (-t) to the name you want to give to your image.

Note: This command builds the image by default with full functionality for RidgeRun products. To enable evaluation mode, use the build argument ENABLE_EVAL, EVAL_MODE, EVAL_ITER, and EVAL_PERIOD. You can do this by executing the following command:

sudo docker build \
--build-arg ENABLE_EVAL=true \
--build-arg EVAL_MODE=iter \
--build-arg EVAL_ITER=9000 \
--build-arg EVAL_PERIOD=30 \
--ssh default=$SSH_AUTH_SOCK \
--network=host \
-f Dockerfile \
-t ridgerun/camera-service:latest \
camera-context/

EVAL_MODE options are iter and time. EVAL_ITER is the number of runs of the evaluation (used with the iter mode). EVAL_PERIOD is the number of days of the evaluation (used with the time mode).

Launch the container

The container can be launched by running the following command:

sudo docker run \
--runtime nvidia \
-it \
--network host \
--privileged \
-v /tmp/argus_socket:/tmp/argus_socket \
-v /dev/:/dev/ \
--name camera-service \
ridgerun/camera-service:latest

You can modify the name you want to give to your container with the option –name.

Here we are creating a container called camera-service that will start the camera-service application in the default address and port and using the default output resolution, and with no initial configuration. We need to start the pipeline by adding the configuration via request.

To start the service with an initial configuration file, or a different address or port has to be used, you can do it by running:

sudo docker run \
--runtime nvidia \
-it \
--network host \
--privileged \
-v /tmp/argus_socket:/tmp/argus_socket \
-v /dev/:/dev/ \
-v <configuration file path on host>:/init_config.json \
--name camera-service \
ridgerun/camera-service:latest \
--config_file /init_config.json --host=<host to be used> --port=<port to be used>