Glossary#

Introduction#

This document describes:

• the process of installing as well as uninstalling the VisionLabs LUNA KIOSK application,
• hardware and software requirements of the equipment.

VisionLabs LUNA KIOSK (hereinafter referred to as System) is a set of libraries that provide the possibility of realizing real-time operation to perform face detection in a frame, check the vitality of a person and transfer data to an external system.

The System is designed for:

• receiving and processing a color video stream from a video recording device,
• checking the image quality,
• selecting the bestshot,
• face detection by machine calculation method on two images,
• checking the presented image by Liveness-algorithms,
• protection against image spoofing by depth map analysis,
• subsequent transfer of the bestshot to device integration systems.

System requirements#

To successfully install and run the system, your hardware must meet the minimum requirements specified below.

Minimum system requirements for x64 architecture#

To run the application on Windows, install the Visual C++ Redistributable package.

Minimum system requirements for ARM architecture#

Supported cameras#

The system is optimized and tested for reliable operation with the following 3D and IR cameras:

• Intel® RealSense™ Depth cameras:
  • D415
  • D435
  • D435j
  • D455
• VLS LUNA CAMERA:
  • VLS LUNA CAMERA 3D / VLS LUNA CAMERA 3D Embedded
  • VLS LUNA CAMERA 2D
• Orbbec cameras:
  • Gemini E
  • Gemini 335

Important: Before using Orbbec cameras with LUNA KIOSK, ensure that the official Orbbec driver is installed on the target system. Without the driver, the camera may not be recognized by the operating system or the SDK. Refer to the Orbbec Developer Portal for the latest driver packages and installation instructions.

Note: For information about VLS LUNA CAMERA 3D / VLS LUNA CAMERA 3D Embedded, please contact your VisionLabs representative.

Connection requirements#

For stable performance, connect all supported cameras using USB 3.0.

Orbbec and Intel RealSense SDK compatibility#

This section provides compatibility information for Orbbec and Intel RealSense SDKs with their respective hardware and operating systems.

Orbbec SDK v.1.10.27#

• Hardware compatibility:
  • Gemini E
  • Gemini 335
• Firmware requirements:
  • Minimum firmware version: 1.6.00
• Operating system support:
  • Windows:
    • Windows 10 or later
    • Architecture: x86 and x64
  • Linux:
    • Architecture: x64 only
    • Recommended distributions:
      • Ubuntu 20.04 LTS
      • Ubuntu 22.04 LTS
      • Ubuntu 24.04 LTS

Orbbec SDK v.2.5.5#

• Hardware compatibility:
  • Gemini E
  • Gemini 335
• Firmware requirements:
  • Minimum firmware version: 1.6.00
• Operating system support:
  • Windows:
    • Windows 10 or later
    • Architecture: x64 only
  • Linux:
    • Architecture: x64 only
    • Recommended distributions:
      • Ubuntu 20.04 LTS
      • Ubuntu 22.04 LTS
      • Ubuntu 24.04 LTS

Intel RealSense SDK v.2.56.5#

• Hardware compatibility:
  • Cameras:
    • Intel RealSense D415
    • Intel RealSense D435i
    • Intel RealSense D435
• Firmware requirements:
  • Minimum firmware version: 5.17.0.10
• Operating system support:
  • Windows:
    • Supported versions:
      • Windows 11
      • Windows 10 (Build 15063 or later)
    • Recommended configurations:
      • Windows 10 RS5 (Redstone 5)
      • Windows 11 KB5030219 (OS Build 22621.2283 or later)
      • Build 17763+ recommended for all installations
  • Linux:
    • Supported distributions:
      • Ubuntu 20.04 LTS
      • Ubuntu 22.04 LTS
      • Ubuntu 24.04 LTS
      • Non-LTS distributions are not supported
    • Kernel versions:
      • 6.[2, 5, 8]
      • 5.[0, 3, 4, 8, 13, 15, 19]

Hardware restrictions#

The following Intel chipsets are not supported:

Licensing#

To obtain a license, please contact your VisionLabs representative. The response will include the necessary license activation parameters.

Note: You can use the same license activation data across all supported platforms, including Windows, Ubuntu, Debian, and Armbian. For the license activation process, see the Installation section.

Switching the license type#

You can configure the system to use either FIT or Zeus license by modifying the licenseModel parameter.

To do this, locate the licenseModel parameter in the data/license.conf file and assign one of the following values:

• 1 to use the FIT license.
• 2 to use the Zeus license.

Once configured, save the file and restart the service to initialize the new license type.

Installation#

LUNA KIOSK is distributed in two configurations, differing in how configuration settings are stored:

• On Ubuntu 24.04 x64, Debian 10 x64, and Armbian 23: Configuration files server.conf and rsengine.conf located in the /client directory are used.
• server.conf - Contains server operation and logging settings.
• rsengine.conf - Defines thresholds for Liveness estimations.
• On Windows: Settings are stored in the Windows Registry by default after installation.

Note: The Windows distribution does not include configuration files in the /client folder, as registry-based configuration is recommended. If you require configuration files, please request them from VisionLabs.

Installation on Windows#

RSE Server is installed as a Windows service.

Step 1: License activation#

Before installation, configure the license by editing the data/license.conf file with values provided in your license letter from VisionLabs.

The table below outlines the parameters required for license activation:

Step 2: Preparing for LUNA KIOSK installation#

1. Run InstallService.bat as Administrator from the root of the distribution package.

2. During installation:

3. The service is registered in the Windows Registry.

4. A log directory is created at C:\RSE\logs by default.
   You can adjust logging levels later in the Windows Registry.

Step 3: System configuration#

All system parameters are written to the Windows Registry. The parameters are set to default values and can be customized by an administrator. For a full list of parameters, see Appendix 1.

Step 4: System management#

After the installation is complete, you can manage RSE Sever using the services.msc service manager.

Important: Do not change the location of RSE Server and *.conf files after installation. Otherwise, the system functionality will be impaired.

Delayed service start#

When installing LUNA KIOSK, you can control whether the service will start immediately after installation.

To do this, use the StartService parameter of the installService.bat installation script. The parameter has the following values:

Troubleshoot metadata sampling issues for RealSense camera sensors#

Windows requires a special registry entry for each unique video device to provide metadata. Metadata, or metadata attributes, refer to additional information provided by the librealsense library and are necessary for proper interaction with RealSense camera sensors.

To activate the functionality related to metadata attributes, the realsense_metadata_win10.ps1 file is included with LUNA KIOSK. A script in the file creates and modifies entries in the Windows registry to ensure that the RealSense camera sensors work correctly. For more information on activating metadata, see librealsense library documentation.

Installation on Ubuntu 24.04 x64, Debian 10 x64, and Armbian 23 operating systems#

Prerequisites#

Use Ansible to automate installation on Linux-based systems:

1․ Install Ansible:

apt-get install ansible

2․ Verify the installation:

ansible --version

If the installation is successful, the console will display the Ansible version and other information:

  ansible [core 2.12.4]
    config file = /etc/ansible/ansible.cfg
    configured module search path = ['/home/vivek/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
    ansible python module location = /usr/lib/python3/dist-packages/ansible
    ansible collection location = /home/vivek/.ansible/collections:/usr/share/ansible/collections
    executable location = /usr/bin/ansible
    python version = 3.8.10 (default, Mar 15 2022, 12:22:08) [GCC 9.4.0]
    jinja version = 2.10.1
    libyaml = True

Step 1: Pre-action and license activation#

Before running the installation:

1․ Add addresses (ip or hostname) of target devices to the ansible/hosts file to install the distribution. Each line contains one address. For example:

[rse]
12.16.58.33

2․ Adjust the shared variables and license data in the group_vars/all.yml file:

Note: LICENSE_SERVER, LICENSE_EID, LICENSE_PRODUCTID are responsible for licensing and provided by VisionLabs.

Step 2: LUNA KIOSK installation#

The installation location of the system is specified in the RSE_HOME variable.

Navigate to the ansible folder and run:

• For remote hosts:

If the installation is performed on several devices at once (more than one IP address is specified in the host), run the command:

ansible-playbook -I hosts install_rse.yml

During installation, Ansible attempts to connect as the system user (root by default) via the appropriate SSH key pair. If a password is used instead of keys, add the --ask-pass flag to the install command.

• For local installation:

If the installation is performed locally on one device, run the command:

ansible-playbook -i hosts--connection=local--inventory 127.0.0.1, install_rse.yml

Step 3: LUNA KIOSK setup#

When starting the RSE Server, the system uses the settings from the server.conf and rsengine.conf configuration files. For setting descriptions, see Appendix 1.

If you need to change the client configuration settings, make changes in the server.conf and rsengine.conf files and restart the RSE Server.

If the installation is successful, the logs will be written to log files in the default ./logs directory after LUNA KIOSK is launched. To change the location, update the log-path parameter in the server.conf file.

Step 4: LUNA KIOSK management in Linux#

After the installation is complete, manage RSE Sever using the systemctl command line utility.

To start RSE Sever, run the following command:

systemctl start kiosk

To stop the RSE Sever, run the following command:

systemctl stop kiosk

Offline license activation#

Use offline activation when the target device has no internet access. In this scenario:

• The device fingerprint is generated on the offline device.
• The license is activated on an internet-connected device using that fingerprint.

Prerequisites#

Before you start, obtain the license server address and EID from VisionLabs.

Step 1: Generate device fingerprint#

On the offline device where the license will be installed:

1․ Open the license.conf file located in the data directory. 2․ Specify EID and save the file. 3․ Run the FingerprintViewer utility to generate the fingerprint:
- On Linux/Armbian:
1․ Navigate to the extras folder.

2․ Grant access rights to the FingerprintViewer utility:

  ```bash
    chmod +x FingerprintViewer
  ```

3․ Run the utility by specifying the path to the *license.conf* file:

  ```bash
  ./FingerprintViewer ../data/license.conf
  ```

• On Windows:

  Run FingerprintViewer.exe from the root folder of the distribution package.

4․ Copy the displayed fingerprint from the console for use in the next step.

Step 2: Activate license#

On an internet-connected device:

1. Go to the license activation portal (URL obtained from VisionLabs).
2. Log in using your EID.
3. Paste the copied device fingerprint to activate the license.
4. Download the generated license certificate (licenseFile.v2c).
5. Move licenseFile.v2c to the data directory.
6. Rename the file using one of the following methods:
7. Change the Filename parameter in the license.conf file according to the example:
   

   <param name="Filename" type="Value::String" text="licenseFile.v2c"/>
   

8. Rename licenseFile.v2c to license.dat and ensure the Filename parameter in the license.conf file matches the actual name:
   

   <param name="Filename" type="Value::String" text="license.dat"/>
   

Step 3: Deploy license#

Copy the obtained license.dat license key to the data directory.

Deletion#

Uninstall on Windows#

To uninstall RSE Server and logs on Windows OS, run the uninstallService.bat batch file, which is located in the root folder of the distribution.

The uninstallService.bat batch file:

• removes all settings from the registry;
• stops and removes the RSE Server service.

The logs folder is not automatically deleted, it must be deleted manually.

Uninstall on Ubuntu 24.04 x64, Debian 10 x64 and Armbian 23#

Uninstalling RSE Server and logs on Ubuntu 24.04 x64, Debian 10 x64 and Armbian 23 is done manually by the administrator, there is no executable batch file supplied. This requires:

1. Delete data from the RSE_HOME directory;

2. Delete the systemd service file from the /etc/systemd/system/system/kiosk.service directory.