NEPI Engine – Software File System
Introduction
This document describes NEPI Engine’s Root File System (rootfs) structure at a conceptual and instructional level. This document also describes the procedure used to update and customize the NEPI software on the edge device. It is intended for NEPI developers and integrators; specifically, those working on NEPI system customization and porting to new hardware stacks.
Architecture
NEPI Engine installs on top of the base operating system and software provided by edge-compute board and chip manufacturers creating a feature-rich environment for edge-AI and robotic automation development.
Installation Options
NEPI Software can be installed directly on the device’s operating system or as a container running in the device’s operating system. While the container installation option provides a straightforward process and superior porting flexibility, NEPI installed directly on the device’s OS provides additional clock, network, Wi-Fi, security, and software management features.
Container Installation
When NEPI Engine software is installed as a container, the installation includes two components that include an the Root File System partition, then mounts/connects to a User Storage partition with Samba network drive sharing support.
Container Installation File System Partition Table
| Partition Name | Description |
| Root File System | NEPI complete file system |
| User Storage | Network shared partition for user data and software |
Device Installation
When NEPI Engine software is installed directly on the device’s OS, the installation includes four components that include an Init File System that manages NEPI core boot processes and mounts/connects to one of the Root File System partitions (A or B), then mounts/connects to a User Storage partition with Samba network drive sharing support. Only one of the Root File System partitions is mounted and active at any given time, allowing NEPI’s software management system to provide updating, backup, and cloning services on the inactive Root File System partition.
Device Installation File System Partition Table
| Partition Name | Description |
| Init File System | NEPI boot file system. Connects to FS A or B on startup |
| Root File System A | Default active NEPI file system |
| Root File System B | Default inactive NEPI file system |
| User Storage | Network shared partition for user data and software |
Operation
The NEPI on-device filesystems are structured to satisfy the following requirements across a wide swath of hardware architectures:
– Provide for arbitrarily large rootfs partitions by employing external media rootfs support when necessary, eliminating limitations imposed by small embedded storage
– Provide for easy over-the-air rootfs updates as complete system images
– Provide for redundant A/B rootfs with individual automatic fallback for a rootfs that fails to load properly
– Provide for easy on-device archiving of complete rootfs images for backup and mirroring to additional NEPI devices
While many hardware vendors provide product-specific software to achieve some or all of these requirements, NEPI takes a hardware-agnostic approach to maintain a consistent user experience across all NEPI-enabled hardware.
The NEPI rootfs structure involves 3 separate rootfs structures deployed to a device at any given time:
1) INIT rootfs: A bare-bones filesystem that is loaded first (somewhat akin to an initramfs, but consisting of a full O/S installation)
a) Primary responsibility is to check for existence of and hand over control to one of the “Main” rootfs according to user-specified configuration
b) In the event that the current configured Main rootfs fails to load properly, fallback to the backup rootfs after a configurable number of failed boot-up attempts
c) In the event that neither Main rootfs is bootable, provide users a minimal but usable workable system for additional debugging
d) Typical installation: < 8GB.
2) Main rootfs A: A complete NEPI system residing on a partition on user-configurable embedded or external storage media
a) Runs the full NEPI on-device software stack
b) Includes software provisions for over-the-air updates
c) Typical installation: 16-32GB
3) Main rootfs B: A second complete NEPI system residing on a partition on user-configurable embedded or external storage media; not necessarily the same media as Main rootfs A
a) Runs the full NEPI on-device software stack; not necessarily the same version or configuration as Main rootfs B
b) Includes software provisions for over-the-air updates
c) Typical installation: 16-32GB
Active and Inactive Main rootfs
At any given time one of the Main rootfs A/B is considered active and the other is considered inactive. The A and B designation is independent of the notion of active and inactive; A and B represent specific physical media partitions (typically fixed for the life of the device), while Active and Inactive represent a current configuration and routinely switch between A and B over the lifetime of the device as part of normal software updates.
The Init rootfs holds the config file that determines which of A or B is active at any given time. This config. file is stored on the Init rootfs at
/opt/nepi/nepi_rootfs_ab_custom_env.sh
At boot time, the Init rootfs reads nepi_rootfs_ab_custom_env.sh to determine which of A or B to mount and hand over control to.
The Init rootfs may automatically edit the nepi_rootfs_ab_custom_env.sh to swap Active and Inactive when boot failure for the current Active rootfs is detected over a consecutive (configurable) number of boot cycles. Under normal circumstances, users need only edit this file once during initial system bring-up.
Besides providing a fallback in case of failure, the Inactive rootfs plays two other significant roles:
– NEPI full system archive always archives the Inactive rootfs
– NEPI full system update always updates the Inactive rootfs, then automatically switches role of Active and Inactive for the next boot cycle
These are each required due to limitations in interacting at a binary image level with a running rootfs. Only the inactive rootfs can be reliably archived or overwritten while the system is running. In practice, this means that it is sometimes necessary for a user to swap the Active and Inactive rootfs configuration before performing an archive or update, depending on the desired end-state of the device. For example, to archive the current Active rootfs requires first making it the Inactive rootfs and rebooting, so that the desired file system is archived. Following that, another swap must occur to restore back to the desired Active rootfs. The NEPI RUI and ROS API provides an easy way to execute this swap.
Boot Sequence
The NEPI boot sequence is as shown in the following flowchart:
Figure 1- NEPI Boot-up Flowchart
Note that at this time there is no automatic reboot as part of the boot-up sequence. In each case the user must perform a soft reboot or power cycle.
Source-Code Components
A NEPI-enabled device provides the complete NEPI Engine suite of tools and applications. Most of these components can be enabled and disabled during installation, through system configuration, and many can also be started and stopped at run-time as needed. This section provides an overview of NEPI Engine’s software components and source-code repositories.
NOTE: The source-code for each of these software components is available in the NEPI Engine GitHub repo.
Top-Level Repository
The entire NEPI software source code, including the nepi engine system, nepi applications, ai frameworks, drivers, and build scripts, is available in the top-level “nepi_engine_ws” repository.
| Repo Name | Description |
| nepi_engine_ws | Superproject for primary NEPI Engine SDK, including the base nepi_engine repo along with sensor and motion control drivers, ai frameworks, applications, and deploy/build utilities. |
Core Submodule Repositories
While most of the top-level repositories are self-contained, the “nepi_base_ws” repository contains the bulk of NEPI Engine’s capabilities organized in a number of functional submodule repositories describe in the table below.
nepi_base_ws Submodule Repositories
| Submodule Repo Name | Description |
| nepi_3rd_party | Collection of 3rd party components used by the NEPI software system. |
| nepi_eninge | This repository contains the foundational NEPI engine software stack, including the NEPI SDK, manager nodes, ros interface messages, and the Resident User Interface (RUI) system, along with environment setup components. This repo is run-time dependent on the nepi_3rd_party installed software. Together, these two repos provide the full NEPI engine software system. The components in the nepi_ai_frameworks, nepi_apps, and nepi_drivers repos run-time managed by NEPI engine. |
| nepi_ai_frameworks | Collection of run-time selectable AI processing frameworks that provide a common interface to NEPI’s AI model management system through a set of abstracted interface functions. |
| nepi_apps | Collection of NEPI applications that expand the capabilities and features of the base NEPI software environment. |
| nepi_drivers | Collection of run-time configurable hardware drivers for sensors, actuators, lights, robots and other peripheral hardware that provide a common interface to NEPI’s NEX hardware management system through a set of abstracted interface functions. |
Building Source-Code
See the tutorials in the NEPI Engine – NEPI Customization section at:
Installing Pre-Built Containers
Numurus offers NEPI-ready software containers for both cuda supported and non-cuda platforms. For instructions on downloading and installing NEPI Engine pre-built containers, see the NEPI Engine – Pre-Built Container Download and Installation instructions available at:
Installing From Pre-Built Images
Numurus offers NEPI-ready software images for some of the leading edge-compute solutions on the market to further accelerate our customers’ journey and get them up and running in the least amount of time.
For instructions on downloading and installing NEPI Engine from pre-built images for supported hardware, see the NEPI Engine – Pre-Built Image Download and Installation instructions available at:
https://nepi.com/documentation/nepi-engine-pre-built-image-download-and-installation/