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/
Add Useful Command Line Shortcut Aliases
If you would like to set up useful short cut commands for your NEPI device SSH terminal, do the following from an SSH connected terminal window:
nano ~/.bashrc
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. You can edit this file using the following command:
nano ~/.bash_aliases
Then add any aliases to simplify your work. The following aliases and source commands are pre-installed on most NEPI images:
alias rosstop=”sudo systemctl stop roslaunch”
alias rosstart=”sudo /opt/nepi/ros/etc/roslaunch.sh”
alias auto=”cd /mnt/nepi_storage/automation_scripts/”
alias data=”cd /mnt/nepi_storage/data/”
alias ai=”cd /mnt/nepi_storage/ai_models/”
alias src=”cd /mnt/nepi_storage/nepi_src/”
alias nfi=”cd /mnt/nepi_storage/nepi_full_img/”
alias nfia=”cd /mnt/nepi_storage/nepi_full_img_archive/”
alias nuid=”cd /opt/nepi/nepi_link/nepi-bot/devinfo/”
alias connect=”cd /opt/nepi/nepi_link/nepi-bot/lb/data/”
source /opt/nepi/ros/setup.bash
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.
Customizing NEPI File System
Cloning the NEPI Source-Code
a) Install Git on your Linux PC in not installed.
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:
NOTE: Replace “ros1_main” with “ros1_develop” in the “git checkout” line below if you want to checkout 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: all of the NEPI source-code is located in the different submodule repos located in:
/nepi_engine_ws/src/
Editing the NEPI Source-Code
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) Change directories to the submodule you want to work on and checkout the “master ” branch for that repo by typing the following within the submodule folder:
cd src/<NAME OF SUBMODULE REPO FOLDER YOU WANT TO EDIT>
git checkout master
b) Make any changes to the source-code you want to make and save the changed files.
Updating NEPI Source-Code
If you have already cloned the source-code and just want to update to the latest, follow these instrucitons
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
Deploying NEPI Source-Code to the Device
NOTE: The following section assumes your NEPI device’s bash env is configured with the shortcut aliases suggested earlier in this tutorial.
NOTE: You can find more detailed instructions for cloning NEPI Engine GitHub source-code repos, see the NEPI Engine – Software File System manual at:
https://nepi.com/documentation/nepi-engine-nepi-file-system/
a) Change back to the nepi_engine_ws base repo folder.
b) If you have not done so yet, update your PC’s bashrc file with the nepi deployment environment variables.
The script relies on a collection of environment variables that must be set. 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.
sudo vi ~/.bash_aliases
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
c) 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) Sync your NEPI device clock
NOTE: If you don’t have an NTP time server running and updating the NEPI device’s system clock, you can sync the NEPI device’s clock to your connected PC’s clock by selecting the “Sync Clock” button on the NEPI RUI Dashboard tab before stopping the NEPI ROS processes below. If you want to setup an NTP connected server to automate this process, NEPI by default listens for an NTP server configured and running on a connected device with IP address “192.168.179.5”. See the following link for information on setting up an NTP server on your connected PC:
Ubuntu 20.04 NTP server – Linux Tutorials – Learn Linux Configuration
d) 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: If the compile fails to build all components you may need to delete some of the NEPI files on your NEPI device and start the process over using the following commands from an SSH connected terminal:
nepi
cd lib
sudo rm -r nepi*
cd python3/dist-packages/
sudo rm -r nepi*
src
sudo rm -r nepi_engine_ws
If the build was successful with no errors, start the NEPI ROS processes back up and refresh the NEPI RUI in your browsers
Testing 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 changes, but also see the NEPI ROS messages in real-time to identify any issues with the changes you made.