NEPI Engine – Customizing the NEPI File System
Introduction
This tutorial will walk you through customization of the NEPI Engine File System that would be useful for NEPI developers.
What you will need:
1) 1x NEPI-enabled device with internet access. This tutorial uses an edge-compute processor box that includes an NVIDIA Jetson Xavier NX embedded GPU with NEPI Engine software installed.
NOTE: See available off-the-shelf NEPI enabled edge-compute options at: https://numurus.com/products-nepi-enabled-hardware/
2) 1x PC with internet access and configured to access the NEPI device’s File System.
NOTE: Instructions for configuration a PC and connecting to a NEPI device’s File System are provided in the NEPI Engine – Getting Started – Accessing the NEPI File System tutorial at: https://nepi.com/nepi-tutorials/
Cloning and Deploying the NEPI File System
Cloning the NEPI Source-Code
!!! This step should be done on your LINUX PC
a) Install Git on your Linux PC in not installed.
NOTE: If you want to see the repo branch name shown in your terminal while working within a github repo, open a termainl on your PC and type the following to edit your PC’s bashrc file:
gedit ~/.bashrc
Then add the following lines to the end of the file.
parse_git_branch() {git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/(\1)/'}export PS1="\u@\h \[\e[32m\]\w \[\e[91m\]\$(parse_git_branch)\[\e[00m\]$ "
Then save the file and refresh your terminal with the latest changes by typing:
source ~/.bashrc
b) Create a user account on github and configure your ssh credentials if not already done following these instructions:
Connecting to GitHub with SSH – GitHub Docs
c) On your Linux PC with Git installed and ssh credentials configured and tested, open a terminal window and enter the following commands to clone the latest nepi_engine_ws and submodule source-code from the development branch:
git clone git@github.com:nepi-engine/nepi_engine_ws.gitcd nepi_engine_wsgit checkout ros1_maingit submodule update --init --recursive
NOTE: If you need the NEPI development branch, replace “ros1_main” with “ros1_develop” in the “git checkout” line below if you want to checkout the development branch.
NOTE: If you need to edit any of the NEPI repo’s submodules, follow the instructions below. Otherwise, jump to the “Deploying NEPI Source-Code to the Device” section below.
a) All of the NEPI source-code is organized into different submodule repos located in the nepi_engine_ws’s “src” folder. From the top level “nepi_engine_ws” folder type :
cd src
Change directories to the submodule you want to work on and checkout the “ros1_main” branch for that repo by typing the following within the submodule folder:
cd <NAME OF SUBMODULE REPO FOLDER YOU WANT TO EDIT>
git checkout ros1_main
b) Make any changes to the source-code you want to make and save the changed files.
Updating NEPI Source-Code
!!! This step should be done on your LINUX PC
If you have already cloned the source-code and just want to update to the latest, follow these instructions
a) Open a terminal on your PC in the nepi_engine_ws top level project folder
b) Type the following:
git pullgit submodule update --init --recursive
Deploying NEPI Source-Code to the Device
!!! This step should be done on your LINUX PC
a) Update your Linux PC’s bashrc file.
The script relies on a collection of environment variables that must be set on your Linux PC. You can find an example set of environment variables and values in the sample_deploy_env_vars.sh script in the same directory, which you can copy and edit for your custom setup and source, or simply add valid definitions for these environment variables directly to your ~/.bashrc.
gedit ~/.bashrc
and add the following lines to the end with <YOUR_NEPI_SSH_KEY_PATH> changed to your key’s path:
# NEPI Engine Deployment Env. Variablesexport NEPI_REMOTE_SETUP=1export NEPI_TARGET_IP=192.168.179.103export NEPI_TARGET_USERNAME=nepiexport NEPI_SSH_KEY=<YOUR_NEPI_SSH_KEY_PATH>export NEPI_TARGET_SRC_DIR=/mnt/nepi_storage/nepi_src
Example:
# NEPI Engine Deployment Env. Variablesexport NEPI_REMOTE_SETUP=1export NEPI_TARGET_IP=192.168.179.103export NEPI_TARGET_USERNAME=nepiexport NEPI_SSH_KEY=~/SSH_Keys/nepi_engine_default_private_ssh_keyexport NEPI_TARGET_SRC_DIR=/mnt/nepi_storage/nepi_src
b) Deploy the source code to the NEPI device using the deploy_nepi_engine_source.sh script in nepi_engine_ws.
./deploy_nepi_engine_source.sh
c) If you have not done so yet, setup an NTP time server on your PC to automatically sync the clock on your NEPI device following the instructions at:
https://nepi.com/nepi-tutorials/nepi-engine-configuring-ntp-time-syncing/
Building the NEPI Source Code on the Device
!!! This step should be done on your NEPI DEVICE
a) Add useful command line shortcuts to your NEPI Device
!!! THESE SHORTCUTS SHOULD ALREADY BE INSTALLED ON MOST PURCHASED NEPI DEVICES. YOU CAN SKIP THIS SECTION IF WORKING WITH A PURCHASED NEPI SYSTEM.
Find the “nepi_device_bash_aliases” and add them to your NEPI device’s bashrc file. From an SSH-connected terminal window type:
nano ~/.bashrc
Then copy the content of the “nepi_device_bash_aliases” file to the end of your devices bashrc file and save the file.
NOTE: For NEPI pre-built images, the following aliases are pre-setup on the systems and located in a “.bash_aliases” file which is a symlink to
/opt/nepi/config/home/nepi/nepi_bash_aliases. If needed, you can edit this file using the following command:
nano ~/.bash_aliases
a) Open an SSH terminal to your NEPI device and run the following commands:
rosstop
nepibld
rosstart
NOTE: The NEPI default sudo password is “nepi”
NOTE: You can also start this process by manually running the “nepi_engine_build_complete.sh” script from the nepi_engine_ws folder on your NEPI devices nepi_storage/source folder. This folder was created during the Deploy process in the previous section. From the SSH connected NEPI terminal, type:
cd /mnt/nepi_storage/src/nepi_engine_ws
./nepi_engine_build_complete
NOTE: If you run into issues building, you may need to delete any old deployed nepi deployments by typing the following and redeploying in the previous section:
sudo rm -r /mnt/nepi_storage/src/nepi_engine_ws
Testing File System Build
Open and refresh the NEPI RUI and test that the system and any expected updates are working
Debugging File System Changes
From your SSH terminal, you can use the bash aliases “rosstop” and “rosstart” listed above to not only stop and restart your NEPI ROS environment to apply any changes, but also see the NEPI ROS messages in real-time to identify any issues with the changes you made.
Updating Python Files with SFTP
While any cpp based file changes will require a full deploy/build to apply, since python files are not compiled, it is sometimes helpful to just replace them on the NEPI file system while debugging an python script.
From a terminal window on your Linux PC opened in the source folder you want to update from, type:
sftpn
then navigate to the appropriate location on your NEPI device’s file system. Most files are located in the following folders:
/opt/nepi/ros/etc/ -> CONTAIN NEPI CONFIG FILES
/opt/nepi/ros/lib/ -> CONTAIN NEPI SCRIPT FILES
/opt/nepi/ros/lib/python3/distro-packages/ -> CONTAIN NEPI SOURCE FILES
/opt/nepi/ros/share -> CONTAINS NEPI ROS LAUNCH FILES
Once you are in the folder with the file(s) you want to update, just type:
put YOUR_FILENAME
NOTE: ON YOUR LINUX PC, you can add a new “sftpnl” function and file system shortcuts that allow you to sftp right into the appropriate folder following these instructions:
a) Add useful command line shortcuts to your Linux PC’s bashrc file
Find the “pc_device_bash_aliases” and add them to your NEPI device’s bashrc file. From an SSH-connected terminal window type:
gedit ~/.bashrc
Then copy the content of the “nepi_device_bashrc_aliases” file to the end of the file.
Save and close the file. Then type the following to resource your bashrc file:
source ~/.bashrc
b) Type sftpnl $FOLDER_SHORTCUT to open sftp to the specified folder shortcut
Example:
sftpnl $NEPI_LIB
then just use the “put” command as you would normally would replace files from your Linux source folder you ran sftpnl in to the NEPI file system’s file.
c) To test your changes, just open a new terminal on your LInux PC and type:
sshn
to create an SSH connection to the NEPI device, then:
rosstop
rosstart
to restart NEPI with your changes and see system messages real-time.
Customizing NEPI System Configuration
While most NEPI Engine settings are configurable through the RUI, API calls, and user c, there are some low-level configuration items like serial number, logos, and SSH keys that require changes at the file system level using SSH access. The following sections assume you have set up and tested your SSH access as described in the “Accessing the NEPI File System” tutorial.
Assuming you have set up an SSH alias as described during the SSH setup process, just open a terminal on your Linux connected PC and type:
sshn
NOTE: Both Linux vi and nano editors are installed in the NEPI file system. While this document uses the vi editor in examples, some might find the nano editor easier to use.
Change Serial Number
If you would like to give your NEPI device a unique serial number and device name, do the following from an SSH connected terminal window:
vi /opt/nepi/sys_env.bash
Then edit the value next to the “DEVICE_SN=” entry.
Change System Base IP Address
While NEPI Engine allows adding additional IP address aliases that make it easy to integrate a NEPI-enabled device into an existing local area network (LAN), the system’s factory base IP address (192.168.179.103) is only changeable through file system configuration editing. If you plan to connect multiple NEPI-enabled devices to the same LAN, you will need to make sure that they each have a unique Base IP Address. Once changed, you will need to remember this address to access your system, so it is recommended that you:
NOTE: use an IP address close to the original one such as (192.168.179.104) making it easier to remember as well as search for the system in a block of IP addresses if you forget the new value
To change your NEPI system’s base IP address, you will need to do the following from a ssh connected terminal window and edit the “address” value in the file:
vi /etc/network/interfaces.d/nepi_static_ip
Change NEPI CONNECT Configuration
If you plan to use your NEPI-enabled device to upload data and download software to a remote server running Numurus’ NEPI Connect software you may need to modify some of you NEPI device’s NEPI Connect configuration files.
1) Check that your NEPI device has a valid NEPI Connect Unique NEPI ID (NUID) and public SSH key in the “NEPI CONNECT” box on the device’s RUI APPLICATIONS/CONNECT tab as shown below.
If your 10 digit NUID is set to “9999999999” and/or the Public SSH Key box is empty, your system has not yet been configured for NEPI Connect communications. If this is the case, use the following instructions to set up the NEPI Connect credentials on your device:
If you need to configure a NEPI NUID and NEPI Connect public SSH key, use the instruction below to create or update them:
a) Run the NEPI Connect identity application
cd /opt/nepi/nepi_link/nepi-bot/devinfo
python3 change_identity.py -n <Your 10 digit NUID>
For security reasons, it is recommended that you use some random number generator to generate a random 10 digit NUID value. For example:
python3 change_identity.py -n 3989789099
b) Press enter twice to skip a passphrase and (optional) press p to display the key in the terminal.
c) After rebooting your NEPI device the new NUID and public SSH key you just created should now be visible in the RUI APPLICATIONS/CONNECT tab.
2) The internet address NEPI devices try to connect to during a NEPI Connect connection process is set in a configuration file on the device’s NEPI file system. The default NEPI Connect server address set on new installation’s is to a Numurus hosted NEPI Connect installation at address nepi.io. If you are connecting to a NEPI Connect installation at another internet location, you will need to use the following instructions to change that location on your device:
a) Open NEPI Engine’s “NEPI bot” config file and edit the NEPI Connect installation location using the following commands:
cd /opt/nepi/nepi_link/nepi-bot/cfg/bot
nano config.json
b) Then edit the “host” address value under the NEPI Link communications type(s) you plan to use.
Example: If you are connecting using an IP communications gateway (Ethernet, WiFi, Cellular…) you would edit the “host” ip location under the “lb_ip” address driver configuration. This could be either an intent domain name like “nepi.io” or a numeric IP address like “44.229.9.192”.
c) After rebooting your NEPI device will use these new NEPI Connect location values.
Configuring NEPI’s ROS Launch File
During the NEPI Engine boot process, all ROS nodes are started from the “nepi_base.launch” file. You can edit this file by typing:
<Your Git Code Folder>/nepi_base_ws/src/nepi_edge_sdk_base/launch
vi nepi_base.launch
Within the file, you can change which nodes are started or not by modifying the “default=” value in that nodes “arg name” line.
You can also add new nodes to launch. The following is an example of adding a new ZED stereo camera node to the launch file.
1) Add the following argument to the list of arguments near the top of the file using the vi insert mode option by pressing “i” and editing the file:
<arg name="run_zed_wrapper_node" default="true" />
2) While still in insert mode, add the following lines before the last </group> message in the file. Ensure that the indentations match other group indentations.
<group if="$(arg run_zed_wrapper_node)" >
<!-- ROS nodes: Launch Zed Camera -->
<include file="$(find zed_wrapper)/launch/zed2.launch"/>
</group>
3) Press “esc” to exit insert mode, then hit the “Shift-:” to enter command mode and type “wq” then hit enter to save and exit.