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.
The NEPI Engine software is made up of 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.
NEPI 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 |
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 Repositories
NEPI Engine software components and source-code are organized across five top-level repositories described in the table below.
NEPI Top-Level Repositories
| Repo Name | Description |
| nepi_rootfs_tools | Collection of scripts and documentation for preparing a base system. This includes setting up for the NEPI fully redundant system image software update scheme and installing all dependencies (including platform-specific dependencies where applicable). |
| nepi_engine_ws | Superproject for primary NEPI Engine SDK, including sensor and motion control drivers, system configuration tools, ROS nodes and interfaces, and test-and-development utilities. This is the nuts-and-bolts of the NEPI Engine. Most of the operative code is distributed to Git submodules within this top-level repo. |
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_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 run-time selectable applications. |
| 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. |
| nepi_edge_sdk_base | This repository contains foundational NEPI interface classes and libraries used throughout the NEPI software stack. In general, anything that doesn’t serve a very specialized purpose in the NEPI ecosystem is included in this repository. Along with “nepi_ros_interfaces” repository, the present repository can be considered the foundation of the NEPI API interface system, with most other submodules in the ecosystem relying heavily on this one. All startup configuration files including ROS launch files are included in this repository. |
| nepi_managers | This repository contains the base set of NEPI management nodes that are launched during bootup such as network, software, driver, application, and ai framework manager nodes. |
| nepi_ros_interfaces | This repository contains the public API for the NEPI ROS Interface. All NEPI-custom message and service definitions that are exposed to external applications are contained in this repo, along with ROS support files (e.g., rviz-config files). |
| nepi_rui | Node.js project for the browser-based, NEPI-device-hosted Resident User Interface for setup, configuration, and observation of NEPI-enabled devices. |
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.
Installation and Customization
Installing from Source-Code
See the tutorials in the NEPI Engine – NEPI Customization section at:
Installing From Pre-Built Images
While the NEPI Engine software is available in source-code format and pre-installed hardware solutions from both Numurus and its edge-compute hardware partners, Numurus maintains 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/
Updating, Backing Up, and Archiving Images
After initially preparing the device with Init, A, and B images, over-the-air full system rootfs image updates to the NEPI device are possible. NEPI includes a flexible system for updating, backing up, and cloning the NEPI Engine software system. Typical steps for a updating, backing up, and cloning complete system images are provided below. During the NEPI Engine boot process, the NEPI Engine init boot system mounts/connects to one of the two Root File System partitions (A or B) on your NEPI device’s SSD card. 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.
For instructions on updating, backing up, and archive NEPI Engine rootfs software images, see the NEPI Engine – Software Updating, Backup, and Cloning instructions at:
https://nepi.com/documentation/nepi-engine-software-updating-backup-and-cloning/