6.3.1. Environment Installation

This section mainly introduces the deployment method for the complete development environment of the X5 algorithm toolchain.

6.3.1.1. Instructions for Using Delivered Packages

Before deploying the environment for using the algorithm toolchain, please download the corresponding version of the Embedded Application Development Sample Package to your Linux development machine, based on the version information found under the ai_toolchain_package directory in the X5 SDK delivery package.

Download the Embedded Application Development Sample Package:

// Example version is V1.2.8; please download the corresponding SDK version according to release_note.txt under the ai_toolchain_package directory in the X5 SDK delivery package

wget -c ftp://oeftp@sdk.d-robotics.cc/runtime_package/Ai_Toolchain_Package-release-v1.23.9-OE-v1.2.8.tar.xz --ftp-password=Oeftp~123$%

Source Code Directory Structure of the Sample Package

Extract the algorithm toolchain SDK source package:

// Example version is V1.2.8; please download the corresponding SDK version according to release_note.txt under the ai_toolchain_package directory in the X5 SDK delivery package

tar -xvf Ai_Toolchain_Package-release-v1.23.9-OE-v1.2.8.tar.xz

The extracted directory structure is as follows:

ai_benchmark: Contains evaluation examples for common classification, detection, and segmentation models, including both performance and accuracy evaluations.
horizon_runtime_sample: Contains on-board examples for fixed-point models.
package: Contains basic libraries and components required for the released packages
1. The board folder contains executables for the target board.
2. The host folder contains environment and tool dependencies for the x86 development environment, as well as the libdnn library and header files related to model inference.

6.3.1.2. Development Machine Deployment

For environment deployment on the development machine, the X5 algorithm toolchain supports Docker-based deployment.

Development Machine Preparation

To use the algorithm toolchain smoothly, the X5 algorithm toolchain recommends that your development machine meets the following requirements:

Hardware/OS	Requirements
CPU	CPU I3 or higher, or equivalent E3/E5 processors
Memory	16GB or higher
GPU (Optional)	CUDA 11.6, driver version Linux: >= 510.39.01* Compatible GPUs include but are not limited to: 1) GeForce RTX 3090 2) GeForce RTX 2080 Ti 3) NVIDIA TITAN V 4) Tesla V100S-PCIE-32GB 5) A100
OS	Ubuntu 20.04

For more information about CUDA and GPU compatibility, please refer to NVIDIA official website.

Using Docker Environment

To help you quickly get started with the algorithm toolchain, X5 provides a Docker image containing the complete development environment, greatly simplifying the deployment process.

Before reading this section, we assume that the basic Docker environment is already installed on your development machine. The required Docker environment for the X5 algorithm toolchain is as follows:

Docker (version 19.03 or higher, version 19.03 recommended), Docker Installation Guide.
NVIDIA Container Toolkit (version 1.13.1–1.13.5, version 1.13.5 recommended), see NVIDIA Container Toolkit Installation Guide.

After completing the Docker environment installation, add non-root users to the Docker group. Use the following commands as a reference:

sudo groupadd docker
sudo gpasswd -a ${USER} docker
sudo service docker restart

The Docker image addresses required in this section are as follows:

The naming convention for the image files is:

CPU version Docker: openexplorer/ai_toolchain_ubuntu_20_x5_cpu:{version}
GPU version Docker: openexplorer/ai_toolchain_ubuntu_20_x5_gpu:{version}

Tips:

When executing commands, replace {version} with the version information obtained from the ai_toolchain_package directory in the X5 SDK delivery package.

The local Docker image package version can be obtained by contacting the technical support team.

The development machine does not necessarily need a GPU card; generally, a CPU-based development machine loading the Docker image is sufficient for model conversion!

Each image file must be pulled before its first use.

Command to pull the image:

docker pull openexplorer/ai_toolchain_ubuntu_20_x5_cpu:v1.2.8

Then run the Docker container using the following commands.

For CPU development machines, run:

// Command to run the Docker image

export version=v1.2.8

export ai_toolchain_package_path=/home/users/xxx/ai_toolchain_package

export dataset_path=/home/users/xxx/data/

docker run -it --rm \
  -v "$ai_toolchain_package_path":/open_explorer \
  -v "$dataset_path":/data \
  openexplorer/ai_toolchain_ubuntu_20_x5_cpu:"${version}"

For GPU development machines, run:

// Command to run the Docker image

export version=v1.2.8

export ai_toolchain_package_path=/home/users/xxx/ai_toolchain_package

export dataset_path=/home/users/xxx/data/

# Manually start the GPU Docker image
docker run -it --rm 
  --gpus all \ # Add this flag to enable GPU resource access when starting the container
  --shm-size=15g \  # Modify shared memory size
  -v "$ai_toolchain_package_path":/open_explorer \
  -v "$dataset_path":/data \
  openexplorer/ai_toolchain_ubuntu_20_x5_gpu:"${version}"

Note:

During the OE Docker image build process, environment variables such as PATH and LD_LIBRARY_PATH are configured. Entering the container without the recommended method (e.g., docker attach) may result in improper loading of environment variables, causing abnormal behavior of tools such as Cmake, GCC, and CUDA.
If you wish to keep the Docker container after exiting, start it manually using docker run -it without the --rm option.
If you want the Docker container to run in the background, add the -d option after docker run -it. After startup, the container will return a container ID. You can re-enter the container using docker exec -it {container ID} /bin/bash.

Tips:

dataset_path refers to the dataset directory. If this directory does not exist, it will cause loading issues. Please create it before running the command.
Public datasets can be downloaded from the following links:

VOC (use VOC2012):

COCO:

ImageNet:

Cityscapes:

CIFAR-10:

FlyingChairs:

KITTI3D:

CULane:

nuScenes:

At this point, you have successfully entered the complete algorithm toolchain development environment via the Docker image. You can verify the setup by entering the command hb_mapper --help to check if help information is displayed normally:

[root@d67382e74eea open_explorer]# hb_mapper --help
Usage: hb_mapper [OPTIONS] COMMAND [ARGS]...

  hb_mapper is an offline model transform tool provided by horizon.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  checker    check whether the model meet the requirements.
  infer      inference and dump output feature as float vector.
  makertbin  transform caffe model to quantization model, generate runtime...

If the hb_mapper tool outputs logs correctly, the environment has been successfully installed. Proceed to the Board Deployment section to install the environment on the development board.

6.3.1.3. Board Deployment

For board deployment, please follow the flashing instructions to update the board image to the latest version. Refer to the Installing the System section for upgrade methods. After the upgrade is complete, copy the relevant supplementary files to the development board.

Some supplementary tools of the algorithm toolchain are not included in the system image. These tools are located in the Ai_Toolchain_Package-release-vX.X.X-OE-vX.X.X/package/ installation package. Navigate to Ai_Toolchain_Package-release-vX.X.X-OE-vX.X.X/package/board and execute the install script. Run the following command:

bash install.sh ${board_ip}

Note:

${board_ip} is the IP address you assigned to the development board. Ensure this IP is accessible from the development machine.
After successful installation, restart the development board. Running hrt_model_exec on the board can verify whether the installation was successful.

6.3.1.4. Version Management Tool Usage Instructions

This section mainly introduces the usage of the ddk_vcs version management tool, helping developers understand the version status of algorithm toolchain dependency packages in the current development environment.

Note: The version management tool is primarily used for debugging when model PTQ conversion fails in a Docker environment. If model conversion works normally, you may skip this section.

The version management tool includes the following functions:

ddk_vcs list;
ddk_vcs install;
ddk_vcs uninstall;
ddk_vcs patch;
ddk_vcs show;

ddk_vcs list

ddk_vcs list displays the list of installed packages.

When executed without parameters, it shows information about currently installed modules. Example usage:

[horizon@gpu-dev067 ai_toolchain]$ ddk_vcs list
Host package version: x5 1.2.8
The following packages versions
Platform         Package        Version MD5
---------------- -------------- ------- --------------
aarch_64         dnn            1.24.5  a4c77552d3
x86_64_gcc11.4.0 dnn_x86        1.24.5  39527daad7
x86_64_gcc11.4.0 horizon-nn     1.1.0   origin:1.1.0
x86_64_gcc11.4.0 horizon-nn-gpu N/A     origin:N/A
x86_64_gcc11.4.0 horizon_tc_ui  1.24.3  origin:1.24.3
x86_64_gcc11.4.0 hbdk           3.49.15 origin:3.49.15

Remarks:

The "origin" information in the last few lines will be updated to the current environment version each time the install script inside the toolchain SDK package is used. Subsequent use of ddk_vcs for installation will not change this, only the "Version" value will be updated.

Using the -p parameter displays the list of installable module versions, which can be installed via ddk_vcs install. Example:

[horizon@gpu-dev004]$ ddk_vcs list -l
Host package version: 1.2.8
The following packages versions
Platform         Local Package         Version MD5
---------------- --------------------- ------- ----------
aarch_64         dnn_1.24.5.tar.gz     1.24.5  a4c77552d3
x86_64_gcc11.4.0 dnn_x86_1.24.5.tar.gz 1.24.5  39527daad7

ddk_vcs install

ddk_vcs install is used to install packages. Users can directly install the corresponding module tar package via ddk_vcs install. The corresponding platform must be specified during installation. Example usage:

[horizon@gpu-dev004]$ ddk_vcs install dnn_1.17.3d.tar.gz -p aarch_64
dnn installed successfully, version: 1.17.3d, platform: aarch_64
[horizon@gpu-dev004]$ ddk_vcs install hbdk-3.44.7-cp38-cp38-linux_x86_64.whl  horizon_nn-0.17.1-cp38-cp38-linux_x86_64.whl
hbdk-3.44.7-cp38-cp38-linux_x86_64.whl installed successfully
horizon_nn-0.17.1-cp38-cp38-linux_x86_64.whl installed successfully

After using ddk_vcs list -l, users can obtain version information of various module packages in their current host package. Then, ddk_vcs install can be used to easily switch between versions. Example:

[horizon@gpu-dev004]$ ddk_vcs install dnn==1.15.2  --platform aarch_64
dnn installed successfully, version: 1.15.2, platform: aarch_64

If the corresponding version is not available locally, you can specify the installation package path for installation.

ddk_vcs uninstall

ddk_vcs uninstall is used to uninstall specified modules. Example usage:

[horizon@gpu-dev004]$ ddk_vcs uninstall dnn --platform aarch_64
Start to uninstall modules, platform: aarch_64
dnn uninstalled successfully, version: 1.17.3d, platform: aarch_64

ddk_vcs patch

Using ddk_vcs patch ddk_patch.tar.gz installs a pre-built patch package. Example usage:

[horizon@gpu-dev004]$ ddk_vcs patch ddk_patch.tar.gz
dnn installed successfully, version: 1.15.2_patch0, platform: aarch64

ddk_vcs show

ddk_vcs show displays information about installed packages. Using ddk_vcs show [module name] shows information for the specified module. Example usage:

[horizon@gpu-dev004]$ ddk_vcs show dnn
Host package version: x5 1.2.8
The following packages versions
Platform Package Version MD5
-------- ------- ------- ----------
aarch_64 dnn     1.24.5  a4c77552d3