Vision Apps User Guide
Run Instructions

IMPORTANT NOTES

  • Make sure additional components and network proxies are setup as mentioned in Build Environment Setup before proceeding to building PSDKRA
  • Make sure you dont skip any of the steps mentioned below
  • ${PSDKRA_PATH} refers to the path where Processor SDK RTOS Automotive (PSDKRA) is installed
  • ${PSDKLA_PATH} refers to the path where Processor SDK Linux Automotive (PSDKLA) is installed
  • All folders like, pdk, tiovx, vision_apps mentioned in the user guide are relative to ${PSDKRA_PATH} unless explicitly stated otherwise.
  • The build is tested on Ubuntu (x86_64) 18.04 system and may not work on earlier or later Ubuntu systems.
  • 20GB of free space is required to install and build PSDKRA
  • Make sure you have sudo access

Run vision apps on EVM in Linux+RTOS mode (via SD card boot)

Note
make sure vision_apps is built for Linux+RTOS mode as mentioned in Build Instructions

Step 1: Prepare SD card for boot (one time only)

Warning
ALL contents of SD card will be lost when doing these steps.
Note
Run below commands on host PC
There are two versions of the J721e EVM, alpha, beta. The uboot detects the EVM version and chooses the right config for the EVM version.
  • Insert SD card onto your PC SD card slot and format SD card in two partitions,
    • FAT32 partition: for boot loader, 64MB size recommended
    • ext4 partition: for root filesystem, rest of SD card, atleast 16GB SD card recommended.
  • You can use one of two options to format your SD card
    • Option 1: You can use the utility script psdk_rtos_auto/scripts/mk-linux-card.sh to make the partitions
      • Use the command "df -h" to identify the device used by SD card
      • Unmount the SD card before running the script
        • Example, if your SD card is on device /dev/sdb having two partitions, do below to unmount them
          umount /dev/sdb1
          umount /dev/sdb2
        • Run the script as below to partition it, answer "y" to all questions asked when running the script
          cd ${PSDKRA_PATH}
          sudo psdk_rtos_auto/scripts/mk-linux-card.sh /dev/sdb
          Note
          Make sure to give the correct device name to this script, example /dev/sda is typically local harddisk, if you give this by mistake, your whole hard disk will be wiped off !!!
    • Option 2: you can use "gparted" utility (sudo apt install gparted) to use a GUI based interface to create the partitions.
      • Make sure you set the FAT32 partition flags as "boot", "lba"
      • Name the FAT32 partition as "BOOT" and the ext4 partition as "rootfs"
  • After formatting, remove and insert the SD card for the freshly formatted partitions to get auto mounted on the host PC.
  • Copy/untar filesystem and boot files to SD card by executing the script as shown below,
    cd ${PSDKRA_PATH}
    psdk_rtos_auto/scripts/install_to_sd_card.sh
  • DO NOT REMOVE SD card, goto step 2 to complete rest of SD card installation

Step 2: Copy test data to SD card (one time only)

Note
Run below commands on host PC
  • Untar the demo input files located in the file psdk_rtos_auto_ti_data_set_xx_xx_xx_xx.tar.gz to the SD card at below folder. You can find this file at the same location the PSDKRA installer is hosted.

    cd /media/$USER/rootfs/
    mkdir -p opt/vision_apps
    cd opt/vision_apps
    tar --strip-components=1 -xf ${path/to/file}/psdk_rtos_auto_ti_data_set_xx_xx_xx_xx.tar.gz
    sync
    Note
    This test data is required for most of the vision apps demos, so this step is mandatory when running vision apps demos
  • After untar you should see a folder "test_data" in folder opt/vision_apps in the SD card. i.e folder in SD card should look like
    tree -L 1 -d /media/$USER/rootfs/opt/vision_apps/test_data
    /media/$USER/rootfs/opt/vision_apps/test_data
    ├── harriscorners
    ├── output
    ├── psdkra
    └── tivx
  • Untar the demo input files located in the file psdk_rtos_auto_ti_data_set_ptk_xx_xx_xx_xx.tar.gz to the SD card at below folder. You can find this file at the same location the PSDKRA installer is hosted.

    cd /media/$USER/rootfs/
    mkdir -p opt/vision_apps
    cd opt/vision_apps
    tar xf ${path/to/file}/psdk_rtos_auto_ti_data_set_ptk_xx_xx_xx_xx.tar.gz
    sync
    Note
    This test data is required for PTK demos, run_ptk_demos.sh, so this step is mandatory when running PTK demos, otherwise this step can be skipped.
  • After untar you should see a folder "test_data_ptk" in folder opt/vision_apps in the SD card.
  • DO NOT REMOVE SD card, goto step 3 to complete rest of SD card installation

Step 3: Copy executable files to SD card (first time and each time you want to run updated applications)

Note
Run below commands on host PC
  • Insert the formatted SD card onto your host PC SD card slot, (if not already inserted).
  • Do below to copy vision apps binaries to SD card
    cd ${PSDKRA_PATH}/vision_apps
    make linux_fs_install_sd
  • This also copies a file uEnv.txt to boot partition to select the .dtbo's which is required to run vision apps demos.
  • Eject and remove SD card from PC and insert in EVM

Step 4: Run on EVM

  • Setup the EVM as shown on this page [HTML]
    • Connect UART/USB cable and setup UART terminal
    • Connect daughter card for camera, display as required
    • Connect power supply
    • Connect HDMI and/or DP display
    • Select SD card boot mode on EVM
    • Insert SD card
  • Power on the EVM
  • First time only: The uboot environment may need to be cleared prior to running with the prebuilt filesystem. The uboot environment can be cleared by first pressing enter to stop the boot process at uboot and come to uboot prompt. The below commands can be entered to clear the uboot environment to default and save the changes.
    env default –a –f
    saveenv
  • Power cycle the EVM
  • You should see bootloader prints on the UART terminal and then bootloader will boot linux kernel and you should see login prompt as below
    j7-evm login:
  • On the EVM, Login using below user id, no password
    root
  • On the EVM, do below steps to init the environment for the demos
    cd /opt/vision_apps
    source ./vision_apps_init.sh
  • Now run one of the below scripts/applications to run the demos
    ./run_app_tidl.sh - Image classification demo (needs display)
    ./run_app_tidl_avp2.sh - Auto valet parking demo (needs display)
    ./run_app_dof.sh - Dense optical flow demo (needs display)
    ./run_app_stereo.sh - Stereo disparity demo (needs display)
    ./run_app_c7x.sh - C7x sample kernel demo
    ./run_app_srv.sh - 3D SRV 4 camera demo (needs display, Fusion1 board, 4x IMX390 camera)
    ./run_app_single_cam.sh - Single camera + VISS + Display demo (needs display, Fusion1 board, 1x IMX390 or compatible camera's)
    ./run_app_multi_cam.sh - Multi (4x) camera + VISS + Display demo (needs display, Fusion1 board, 4x IMX390 or compatible camera's)
    ./vx_app_arm_opengl_mosaic.out - OpenGL + OpenVX test
    ./vx_app_linux_arm_ipc.out - inter processor communication test
    ./vx_app_linux_arm_mem.out - memory allocation test
    ./vx_app_tutorial.out - TI OpenVX tutorial
    ./vx_app_conformance.out - TI OpenVX conformance tests
  • Once the demo runs, you should see output on the display
  • Type 'x' to exit the demo and run another demo
Note
To run run_ptk_demos.sh, one needs to do additional instructions as mentioned in Perception Toolkit (PTK) Demos

Sample logs

  • Sample logs during EVM boot can be found here [TXT]
  • Sample logs during vision_apps_init.sh can be found here [TXT]

Run vision apps on EVM in Linux+RTOS mode (via NFS boot - For Debug only)

Note
make sure vision_apps is built for Linux+RTOS mode as mentioned in Build Instructions
make sure that you have sd card set up at least once as mentioned above
  • Make sure NFS is setup (refer to PSDKLA documentation)
  • Create a target folder for NFS on the host machine (e.g targetnfs) and set environment variable LINUX_SD_FS_ROOT_PATH to point to it
    export LINUX_SD_FS_ROOT_PATH=<path-to-targetnfs>
  • Modify /etc/exports to add this line (change for your nfs target folder):
    <path-to-targetnfs> *(rw,sync,no_root_squash,no_subtree_check)
  • Now run:
    sudo service nfs-kernel-server restart
    cd $LINUX_SD_FS_ROOT_PATH
    sudo tar -xvf ${PSDKRA_PATH}/tisdk-rootfs-image-j7-evm.tar.xz
    sudo chmod -R 777 opt/
    sudo chmod -R 777 lib/
    sudo chmod -R 777 etc/security/
    sudo chmod -R 777 boot/
    cd <path-to-sdk>/vision_apps
  • Insert SD Card (You still need boot partition in SD Card) - but this should be a one time thing)
  • Assuming make sdk has already been run:
    make linux_fs_install_sd
  • Now, remove sd card, insert in the board, power on the board and halt u-boot.
  • Once you get to u-boot prompt, set following environment variables
    setenv serverip <host ip address>
    setenv init_nfs 'run args_all args_nfs; setenv autoload no;dhcp'
    setenv args_nfs 'setenv bootargs console=${console} ${optargs} root=/dev/nfs rw nfsroot=${serverip}:${rootpath},v3 ip=dhcp'
    setenv get_overlay_nfs 'fdt address ${fdtaddr};fdt resize 0x100000;for overlay in $overlay_files;do;nfs ${overlayaddr} ${serverip}:${rootpath}${bootdir}/${overlay} && fdt apply ${overlayaddr};done;'
    setenv get_kern_nfs 'nfs ${loadaddr} ${serverip}:${rootpath}${bootdir}/${bootfile}'
    setenv get_fdt_nfs 'nfs ${fdtaddr} ${serverip}:${rootpath}${bootdir}/${fdtfile}'
  • Change boot_rprocs
    setenv boot_rprocs 'if test ${dorprocboot} -eq 1; then rproc init;run boot_rprocs_mmc;fi;'
  • Change rproc_load_and_boot_one (HACK**)
    setenv rproc_load_and_boot_one 'if nfs $loadaddr ${serverip}:${rootpath}${rproc_fw};then if rproc load ${rproc_id} ${loadaddr} ${filesize}; then rproc start ${rproc_id};fi;fi'
    setenv boot nfs
    saveenv
  • Boot into sdk
    boot
  • To change between nfs and mmc boot:
    • For NFS boot:
      setenv rproc_load_and_boot_one 'if nfs $loadaddr ${serverip}:${rootpath}${rproc_fw};then if rproc load ${rproc_id} ${loadaddr} ${filesize}; then rproc start ${rproc_id};fi;fi'
      setenv boot nfs
    • For MMC boot:
      setenv rproc_load_and_boot_one 'if load mmc ${bootpart} $loadaddr ${rproc_fw}; then if rproc load ${rproc_id} ${loadaddr} ${filesize}; then rproc start ${rproc_id};fi;fi'
      setenv boot mmc

Run vision apps on EVM in QNX+RTOS mode (via SD card boot)

Note
make sure vision_apps is built for QNX+RTOS mode as mentioned in Build Instructions

Step 1: Prepare SD card for boot (one time only)

Warning
ALL contents of SD card will be lost when doing these steps.
Note
Run below commands on host PC
There are two versions of the J721e EVM, alpha, beta. The uboot detects the EVM version and chooses the right config for the EVM version.
  • Insert SD card onto your PC SD card slot and format SD card in two partitions,
    • ext4 partition: for remote core firmwares, 128MB size recommended
    • FAT32 partition: for boot files, QNX filesystem and applications, rest of SD card, atleast 16GB SD card recommended.
  • You can use one of two options to format your SD card
    • Option 1: You can use the utility script psdk_rtos_auto/scripts/mk-qnx-card.sh to make the partitions
      • Use the command "df -h" to identify the device used by SD card
      • Unmount the SD card before running the script
        • Example, if your SD card is on device /dev/sdb having two partitions, do below to unmount them
          umount /dev/sdb1
          umount /dev/sdb2
        • Run the script as below to partition it, answer "y" to all questions asked when running the script
          cd ${PSDKRA_PATH}
          sudo psdk_rtos_auto/scripts/mk-qnx-card.sh --device /dev/sdb
          Note
          Make sure to give the correct device name to this script, example /dev/sda is typically local harddisk, if you give this by mistake, your whole hard disk will be wiped off !!!
    • Option 2: you can use "gparted" utility (sudo apt install gparted) to use a GUI based interface to create the partitions.
      • Make sure you set the FAT32 partition flags as "boot", "lba"
      • Name the FAT32 partition as "boot" and the ext4 partition as "rootfs"
  • After formatting, remove and insert the SD card for the freshly formatted partitions to get auto mounted on the host PC.
  • Copy the QNX filesystem and binaries to SD card by executing the command in vision_apps folder,

    make qnx_fs_create_sd
    Note
    Above command builds the QNX BSP+filesystem and copies it to the SD card
  • DO NOT REMOVE SD card, goto step 2 to complete rest of SD card installation

Step 2: Copy test data to SD card (one time only)

Note
Run below commands on host PC
  • Untar the demo input files located in the file psdk_rtos_auto_ti_data_set_xx_xx_xx_xx.tar.gz to the SD card at below folder. You can find this file at the same location the PSDKRA installer is hosted.

    cd /media/$USER/boot/
    mkdir -p vision_apps
    cd vision_apps
    tar --strip-components=1 -xf ${path/to/file}/psdk_rtos_auto_ti_data_set_xx_xx_xx_xx.tar.gz
    sync
    Note
    This test data is required for most of the vision apps demos, so this step is mandatory when running vision apps demos
  • After untar you should see a folder "test_data" in folder vision_apps in the SD card. i.e folder in SD card should look like
    tree -L 1 -d /media/$USER/boot/vision_apps/test_data
    /media/$USER/boot/vision_apps/test_data
    ├── harriscorners
    ├── output
    ├── psdkra
    └── tivx
  • DO NOT REMOVE SD card, goto step 3 to complete rest of SD card installation

Step 3a: Copy executable files to SD card for boot using SPL+Uboot(first time and each time you want to run updated applications)

Note
Run below commands on host PC
  • Insert the formatted SD card onto your host PC SD card slot, (if not already inserted).
  • Do below to copy the binaries to SD card
    cd ${PSDKRA_PATH}/vision_apps
    make qnx_fs_install_sd
  • Eject and remove SD card from PC and insert in EVM

Step 3b: Copy executable files to SD card for boot using MMCSD+SBL(first time and each time you want to run updated applications)

Note
Run below commands on host PC
  • Do below to build all the SBL and MCUSW bootapp binaries for MMCSD and OSPI boot modes. This typically needs to be done only once, or when the SBL or MCUSW boot app changes.
    make sbl_bootimage
  • Insert the formatted SD card onto your host PC SD card slot, (if not already inserted).
  • Do below to copy the binaries to SD card
    cd ${PSDKRA_PATH}/vision_apps
    make qnx_fs_install_sd_sbl
  • Eject and remove SD card from PC and insert in EVM

Step 3c: Copy executable files to SD card for boot using OSPI+SBL(first time and each time you want to run updated applications)

Note
Run below commands on host PC
  • Do below to build all the SBL and MCUSW bootapp binaries for MMCSD and OSPI boot modes. This typically needs to be done only once, or when the SBL or MCUSW boot app changes.
    make sbl_bootimage
  • Insert the formatted SD card onto your host PC SD card slot, (if not already inserted). This is for copying the vision apps binaries only.
  • To flash boot binaries to the OSPI flash, you need to have Uniflash flashprogrammer installed in the host PC. If you don't have this, install it from [UNIFLASH]
  • Make sure that the MCU UART is connected to the host PC. Note the port name of the second COM PORT of the MCU UART. You can find this using "dmesg | grep ttyUSB" in linux. For example let's assume it was '/dev/ttyUSB1'
  • Edit file vision_apps/makerules/makefile_sbl,mk for below variables based on your system environment
    UNIFLASH_DIR=${HOME}/ti/$(UNIFLASH_VERSION) # this is the default install dir
    UNIFLASH_COM_PORT=/dev/ttyUSB1 # this must be the second MCU_UART port on the EVM
  • Flash boot files, vision_apps binaries for R5F, C6x, C7x and QNX kernel, rootfs to OSPI flash. This also copies QNX A72 applications to SD card.
    Note
    Make sure EVM is in UART boot mode and make sure MCU UART terminal is not open since UNIFLASH needs to use this UART device
    cd ${PSDKRA_PATH}/vision_apps
    make qnx_fs_install_ospi
  • Eject and remove SD card from PC and insert in EVM

Step 4: Run on EVM

  • Setup the EVM as shown on this page [HTML]
    • Connect UART/USB cable and setup UART terminal
    • Connect daughter card for camera, display as required
    • Connect power supply
    • Connect HDMI and/or DP display
    • If you're using SPL+Uboot or SBL-MMCSD boot, select SD card boot mode on EVM. If you're using the SBL-OSPI boot, select the OSPI boot mode on the EVM.
    • Insert SD card
  • Power on the EVM
  • You should see bootloader prints on the UART terminal. This can be the MCU UART terminal if the boot is MMCSD or OSPI based, or the MAIN UART Terminal if SPL+Uboot based.
  • The bootloader will boot QNX kernel and you should see QNX prompt in the first port of MAIN UART as below
    J7EVM@QNX#
  • On the EVM, do below steps to init the environment for the demos
    cd /sd/vision_apps
    . ./vision_apps_init.sh (source)
  • Now run one of the below scripts/applications to run the demos
    ./run_app_tidl.sh - Image classification demo (needs display)
    ./run_app_tidl_avp2.sh - Auto valet parking demo (needs display)
    ./run_app_dof.sh - Dense optical flow demo (needs display)
    ./run_app_c7x.sh - C7x sample kernel demo
    ./run_app_srv.sh - 3D SRV 4 camera demo (needs display, Fusion1 board, 4x IMX390 camera)
    ./run_app_single_cam.sh - Single camera + VISS + Display demo (needs display, Fusion1 board, 1x IMX390 or compatible camera's)
    ./run_app_multi_cam.sh - Multi (4x) camera + VISS + Display demo (needs display, Fusion1 board, 4x IMX390 or compatible camera's)
    ./vx_app_arm_opengl_mosaic.out - OpenGL + OpenVX test
    ./vx_app_linux_arm_ipc.out - inter processor communication test
    ./vx_app_linux_arm_mem.out - memory allocation test
    ./vx_app_tutorial.out - TI OpenVX tutorial
    ./vx_app_conformance.out - TI OpenVX conformance tests
  • Once the demo runs, you should see output on the display
  • Type 'x' to exit the demo and run another demo

Run vision apps on PC in PC emulation mode

Running the TIOVX demos in PC emulation mode

  • Set environment variable below to specify the path of the test data. This is used by both the conformance test and tutorial executables,
    export VX_TEST_DATA_PATH=../../../../../conformance_tests/test_data
  • Do below execute the TIOVX tutorials
    cd tiovx/out/PC/x86_64/LINUX/$PROFILE
    ./vx_tutorial_exe
  • Do below execute the TIOVX conformance tests
    cd tiovx/out/PC/x86_64/LINUX/$PROFILE
    ./vx_conformance_tests_exe
Note
Output .bmp/.png files generated by the tutorial and conformance tests should be present in the folder tiovx/conformance_tests/test_data

Running the vision apps demos in PC emulation mode

  • Most of the demos take a config (.cfg) file as input which is used to specify various inputs and outputs to the demos
    • A sample .cfg file is provide in each respective demo folder (vision_apps/apps/[demo type]_demos/[demo name]/config)
  • TI provides reference test input for the demos
    • Untar the file psdk_rtos_auto_ti_data_set_xx_xx_xx_xx.tar.gz to the folder "/ti/j7presi/workarea"
    • If test data is NOT installed at "/ti/j7presi/workarea", then modify the demo .cfg files to point to the input data
  • To run the demo copy the demo .cfg files to vision_apps/out/PC/x86_64/LINUX/$PROFILE
  • Run the specific demo by using below command
    cd vision_apps/out/PC/x86_64/LINUX/$PROFILE
    <demo executable name> --cfg <cfg file>
  • Refer to detailed demo pages for details on running each individual demo