This repository contains documentation and tools for getting started with NEPI Engine, a full-featured edge-AI and automation software platform for NVIDIA Jetson and other embedded edge-compute hardware platforms.

Learn more about NEPI Engine

The latest NEPI major software version releases are provided under both commercial and open-source licenses from Numurus.  Version patches provided under NEPI commercial licenses.  While Numurus accepts community contributions to the NEPI Engine open-source project, contributors must submit a signed CLA before contributing code.

The best way to get involved is to contribute to NEPI-Engine source code and documentation. Contributions in the form of pull requests are gladly accepted as long as we have a signed Contributor License Agreement from you or your organization. Just download the relevant agreement and follow the instructions:

• Individual CLA
• Organization CLA

NEPI Engine runs on lots of embedded Linux devices, though certain hardware and O/S configurations are more well-suited than others. In general, NVIDIA Jetson platforms are well tested and supported. The scripts and documentation in this repository are tailored for modern Debian-based Linux distributions (e.g., Ubuntu 18.04+); if that is not your situation, then NEPI may still be appropriate wholly or in part, albeit with additional setup legwork.

Numurus provides commercially licensed pre-built root filesystem images and complete hardware solutions for select platforms -- speed up your development time considerably by exploring one of these options. Or contact us to discuss professional support options for other platforms

The following sections describe the architecture of the NEPI Engine and provide tools and guidance for getting NEPI running on your device.

A NEPI-enabled device provides the complete NEPI Engine suite of tools and applications. Most of these components can be enabled and disabled through system configuration, and many can also be started and stopped at run-time as needed.

NEPI Engine setup and source code is distributed across two top-level repositories:

• nepi_rootfs_tools - Collection of scripts and documentation for preparing a base NEPI Engine root filesystem. This includes setting up for the NEPI fully redundant system image software update scheme and installing all dependencies (including platform-specific dependencies where applicable). Start here if you are bringing up a system from scratch... note that you'll need to switch to the appropriate ROS 1 or ROS 2 branch immediately, as detailed in the default branch README.

• nepi_engine_ws - Superproject for all NEPI Engine source code, including hardware drivers, ROS-based SDK components, user interfaces, and edge-side NEPI Connect components. Source code is organized as a collection of git submodules below this superproject. Building and running this software depends on a properly prepared root filesystem, as covered by nepi_rootfs_tools.

Some other stand-alone repositories may be useful depending on your needs

• nepi_ros_interfaces - Collection of NEPI Engine custom ROS messages and services. Included as part of nepi_engine_ws, but if you are only trying to interact with an existing NEPI Engine system via the ROS interface, this repository can be included in your own workspace, built, and sourced to provide these message and service objects to the rest of your application.

• nepi_sample_auto_scripts - Large and growing collection of NEPI Engine automation scripts that provide useful functionality and examples for the powerful NEPI Engine Automation Manager. Typically these scripts are deployed as-is to the NEPI storage partition (i.e., user partition) and/or used as references when developing new scripts.

The following workflow describes how NEPI Engine is first deployed to a new hardware platform. It assumes

• Your target device has a Debian-based Board Support Package (BSP) and/or Operating System (O/S) available and accessible as a binary image (img.raw, .bin), compressed archive (.tar.gz), etc.
• Your target device has a storage media installed that allows you to add NEPI-specific partitions (typically requires 32GB for each of the NEPI A/B partitions, and ideally a large leftover space to be dedicated to the nepi_storage partition)
• Your target device can be configured for internet access.

Workflow:

1. Install the base Board Support Package (BSP) and/or Operating System (O/S) on the platform according to manufacturers instructions. In some cases, this step is already completed by the manufacturer or reseller and you can skip. A minimal install is typically sufficient, since this BSP will serve only as the NEPI INIT rootfs.

2. Boot, log in, and configure the target device for internet connectivity.

3. Follow the instructions for installing the INIT Rootfs from the nepi_rootfs_tools README.

4. Follow the instructions for installing the Main A/B Rootfs from complete image from the same nepi_rootfs_tools README. For the "complete image," use the same initial BSP ROOTFS image as in step 1 above.

5. At this point, you should have rebooted/power cycled the target device and it should have booted up into a pristine copy of the BSP rootfs mounted from your NEPI_ROOTFS_A partition. You can verify with

   $ df
   

   ensuring that the NEPI_ROOTFS_A device is listed as "Mounted on" /

6. Now begin converting the BSP rootfs into a full-fledged NEPI rootfs by following the instructions for constructing the main a/b rootfs from a base image from the nepi_rootfs_tools README. You should stop after running the setup_nepi__rootfs.sh script and proceed from here to build NEPI s/w from source.

7. At this point you have a rootfs that has all dependencies and build-tools installed to begin building the NEPI Engine software. The nepi_engine_ws provides scripts to deploy source code and build NEPI Engine software directly on the target platform. See the README in that repository nepi_engine_ws

This section details approaches to overcoming some target platform limitations. In most cases these alternatives have been successfully employed by Numurus in porting NEPI to specific platforms.

If you cannot run setup scripts that install NEPI Engine dependencies because the target device has no internet capability, it is often possible to mount the BSP root filesystem on a Linux development host PC using the relevant qemu package to provide an emulator engine and then chroot to the mountpoint and install external dependencies, etc. via the host PC internet connection using the regular nepi_rootfs_tools setup scripts.

Because there is different preparation for the NEPI init and main rootfs, you should maintain a pristine copy of the BSP rootfs at all times and make copies that you modify into. Beware, this approach usually requires considerable disk space on the development machine to maintain the various rootfs images.

In cases where there is a strictly prescribed partition layout for the sole storage device, it is sometimes possible to reconfigure the partition tables such that the BSP deployment process creates the necessary NEPI_ROOTFS_<A,B> and DATA partitions. This is how NEPI is installed on Jetson Orin-NX on the SSD alongside all the BSP partitions. See manufacturer documentation to determine if this is a viable path for your platform.

It is also possible to bypass the NEPI A/B filesystem support and convert the sole BSP rootfs into a NEPI main rootfs by running the appropriate setup_nepi_rootfs.sh script right after deploying the BSP rootfs. Note that this lead to some error messages in NEPI logs and an inability to use the NEPI full system image update capabilities, but generally provides a well-featured NEPI Engine deployment.

This will only impact the way you write the initial contents to the NEPI_ROOTFS_A and NEPI_ROOTFS_B partitions. In general, you'll replace the dd call with a tar -xf call.