Installation on NVidia Jetson devices

SmartFace Platform can be distributed in form of docker images specially built for NVidia Jetson embedded devices with ARM architecture. Currently, we support Jetson Xavier NX and Jetson AGX Xavier. It is not possible to deploy SmartFace on other ARM devices like Raspberry Pi or similar. For successful installation it is required that you have an admin level experience with Linux OS and minimal basic knowledge of docker technology - understanding docker images, docker compose, docker container and docker registry. It is also required that you understand that Jetson processors have ARM architecture instead of regular x86 architecture.

The deployment on Jetson devices allows you to install distributed solution, where you do not need a central powerful machine for processing of all video streams, but rather multiple small and cheaper devices, which will process the video stream closer to the camera. This kind of deployment can be also used for simpler and smaller access control use cases, where seamlessness is not top priority. For example opening doors for your regular customers at gyms and fitness centers.

Prerequisites

There are several requirements on hardware, operating system and other software that is needed for successful installation of SmartFace Platform on NVidia Jetson device.

Required Jetson device

Currently, SmartFace Platform can be distributed as docker images built for NVidia Jetson devices. We have tested the build on Jetson Xavier NX and Jetson AGX Xavier. It is possible that other embedded devices will work as well, but it is currently not supported.

Required OS

It is required to have Ubuntu 18.04 distribution installed on your embedded device. It is required to have device drivers installed and JetPack SDK 4.5.1 installed on your device. JetPack SDK version can vary based on the manufacturer of the Jetson device. This guide describes the deployment on Jetson device distributed directly from NVidia. For more information see Jetson device manufacturers.

Required Docker

SmartFace Platform Jetson devices is distributed in form of docker images, therefore it is required to have Docker installed on your Jetson device. SmartFace Platform requires Docker version 20.10.0 and higher.

It is required to have latest version of NVidia Docker driver installed your Jetson device.

For deployment of SmartFace Platform on Jetson device is used Docker Compose. It is required that you have Docker Compose installed on your device. SmartFace Platform requires Docker Compose version 1.29.0 and higher.

Obtain the SmartFace license

To obtain your license please follow these steps:

  1. Login to container registry on your NVIDIA Jetson device (the credentials are available in our CRM portal):

    docker login registry.gitlab.com -u <username> -p <password> 

  2. Identify hardware ID (HWID) for your machine with command:

    docker run --privileged registry.gitlab.com/innovatrics/smartface/license-manager:3.2.7

    This process work for native Linux. For WSL2 (e.g. Linux containers on Windows) you need a special license for which you need to contact our sales.

  3. Obtain the license for your HWID from our CRM portal for product SmartFace Embdded

    images/download/attachments/124099856/image2021-10-27_15-45-34.png


  4. Download the license file iengine.lic

Deployment

Before you start the deployment you need to manually perform following steps:

  1. Download zip archive file containing docker-compose files, scripts and configuration files for Jetson from our public GitHub repository.

  2. Unzip downloaded files on your Jetson device.

  3. Copy the iengine.lic license file to the directory with docker-compose file and scripts where run.sh script is located.

  4. Login to the container registry using the provided credentials.

    1. Run command: docker login registry.gitlab.com

    2. Enter provided credentials

Now you can run the run-jetson.sh script deploying SmartFace Platform with a default configuration. Once the script is successfully finished all the services should be up and running.

Steps performed by the run-jetson.sh script

When you run the script on a machine with an empty docker engine (no previous images/containers), the script performs following steps:

  1. Checks the presence of iengile.lic file. If not present, the script ends.

  2. Creates a docker network called sf-network. This docker network is used by all other containers created by this script and enables containers to communicate with each other.

  3. Sets up services from sf_dependencies that SmartFace Platform needs to run properly. Docker will check the presence of these images on local docker host. In case the images are not present, images are pulled from the container registry. The download can take up to several minutes.

  4. Docker spawns containers from prerequisites images, for example:

    1. PGSQL database

    2. RabbitMQ

    3. Minio NoSQL database

  5. Parses SmartFace Version and registry information from .env file.

  6. Creates PostgreSQL database named "SmartFace".

  7. Uses sf-admin image to perform database migration - creates required table structure and seeding the database. The image is pulled from the container registry if it is not present on the machine. This step will fail if the docker login was not performed correctly and script ends.

  8. Executes the SmartFace Platform Docker Compose file. This results in SmartFace Platform services to be up and running on the machine. The execution does the following

    1. Pulls SmartFace Platform images from container registry. The download can take up to several minutes.

    2. Builds new SmartFace Platform images that will contain the provided license file. This is done using the license.Dockerfile which just adds a new layer containing the license file to an arbitrary existing image. This step can be replaced by mounting the license file to the containers.

    3. Spawns containers from images, for example:

      1. camera service

      2. detector service

      3. extractor service

    4. Uses the values from .env file to properly configure SmartFace Platform containers so everything works properly. To use this file to configure SmartFace Platform for different deployment than described here see docker documentation.

When the script finishes, SmartFace will be available to use on the Jetson device with all services up and running.

Jetson deployment differences

SmartFace Platform works slightly different on Jetson devices than on regular x86 machines. There are less resources available than on server machines or some of the technology used is not working on ARM devices. Following chapters are describing differences in SmartFace Platform deployed on Jetson device.

HW decoding

SmartFace Platform deployed on Jetson devices is using NVidia hardware-based decoder for video streams decoding. This feature significantly unburdens CPU usage, which can be used for other processing like detection, extraction or matching. When you define the video source string, you can configure HW decoding. For more information read below.

Body parts detection not available

OpenVINO framework is not running on Jetson devices. Body partd detection and pose estimation is therefore not available within SmartFace Platform build for Jetson device.

Video source string definition

When setting up a camera in SmartFace Platform it is required to setup a source, from which the video/stream will be processed. In x86 architecture the video source is set as a string to the rtsp stream available on your network or file path to the location on your disk drive. Unfortunately, in ARM architecture it is necessary to define the whole GStreamer pipeline string as a definition of the video source. The string needs to contain several parameters like the definition of the codec, decoding type, etc. The definition of the string can be different from camera to camera and you need to understand how the pipeline works to concatenate the string. We provide several examples how the string (GStreamer pipeline) can look like:

Original string

Example of the string used as a video source for the video stream for SmartFace Platform deployed on x86 machine:

rtsp://user:password@10.11.12.13:554/onvif/H.264/media.smp

String for RTSP with HW decoding

Example of the string used as a video source for the video stream for SmartFace Platform deployed on ARM device (RTSP stream with HW decoding):

rtspsrc location=rtsp://user:password@10.11.12.13:554/onvif/H.264/media.smp ! rtph264depay ! h264parse ! nvv4l2decoder ! nvvidconv ! video/x-raw, format=(string)BGRx ! videoconvert ! video/x-raw, format=(string)BGR ! appsink

String for RTSP without HW decoding

Example of the string used as a video source for the video stream for SmartFace Platform deployed on ARM device (RTSP stream without HW decoding):

rtspsrc location=rtsp://user:password@10.11.12.13:554/onvif/H.264/media.smp ! rtph264depay ! h264parse ! avdec_h264 ! videoconvert ! appsink

String for video file

Example of the string used as a video source for the video file stored locally for SmartFace Platform deployed on ARM device (video file with HW decoding):

filesrc location=/my video/my_video.mp4 ! qtdemux ! queue ! h264parse ! nvv4l2decoder ! nvvidconv ! video/x-raw, format=(string)BGRx ! videoconvert ! video/x-raw, format=(string)BGR ! appsink

String for video file online

Example of the string used as a video source for the video file stored online for SmartFace Platform deployed on ARM device (video file located online with HW decoding). This can be used for example for video files located in MinioDB:

souphttpsrc location=http://video.company.net/QAVideo/my_video.mp4 ! qtdemux name=demux demux.video_0 ! queue ! h264parse ! nvv4l2decoder ! nvvidconv ! video/x-raw, format=(string)BGRx ! videoconvert ! video/x-raw, format=(string)BGR ! appsink

Postgre SQL

There is no ARM build of MS SQL database for ARM architecture, therefore only Postgre SQL can be deployed on the Jetson device.