Hardware Driver Interface System

Introduction

NEPI Engine’s hardware driver interface system provides plug-and-play interfacing with a growing list of supported sensors, lights, actuators, navigation, communication, and robotic control system hardware from a variety of manufactures. NEPI hardware drivers provide a hardware abstraction layer that allows downstream applications to work with any supported hardware system without any modifications to the application layer code or processes.

Driver System Overview

NEPI hardware drivers are organized into functional driver classes (i.e. imaging sensors, navigation sensors, lights, pan and tilt, robotic control systems…). Each driver group driver class provides standardized data and control interfaces appropriate for each class.

NEPI Driver Classes

Driver Class Name	Description
IDX	2D and 3D Imaging Sensors
PTX	Pan & Tilt Actuators
LSX	Lights and Strobes
RBX	Robotic Control Systems
NPX	Navigation and Pose Systems
CMX	Communications Hardware

To see a list of supported hardware interfaces and tested devices for each driver class, set the NEPI Engine “Hardware Driver Support” tables at: https://nepi.com/documentation/nepi-engine-hardware-driver-support-tables/ Each NEX driver class is comprised of the six interface groups listed in the table below.

NEPI Driver Interface Groups

NEX Interface Group	Description	Interface Details
Capabilities	Output message with information on supported settings and data interfaces	ROS Service / HTML JSON
Status	Output message with group standard status data	ROS Topic / HTML JSON
Controls	Inputs for supported real-time control actions.	ROS Topic / HTML JSON
Data	Output streams for supported output data	ROS Topic / HTML JSON and Video
NavPose	Output streams for any supported navigation and orientation data sources	ROS Topic / HTML JSON

NEPI driver interfaces are native ROS with Websocket interfacing supported through a ROS to Websocket bridge. This document only covers ROS interfaces for each driver class and group. For more detailed information on NEPI’s ROS and HTML interface system, see the NEPI Engine “API Manual” available at: https://nepi.com/documentation/nepi-engine-api-manual/ NEPI custom ROS interface message and service types, shown with an * in the interface tables presented in this document are available in the “msg” and “srv” subfolders of the “nepi_ros_interfaces” GitHub repository located at: numurus-nepi/nepi_ros_interfaces: NEPI ROS custom message and service definitions and utilities (github.com) Developers wanting to modify or create custom NEPI Engine drivers are encouraged to access the source code for existing drivers as a starting point for creating custom solutions. For more information on creating and compiling new NEPI drivers, see the NEPI Engine “Customizing the NEPI File System” tutorial available at: https://nepi.com/nepi-tutorials/nepi-engine-customizing-the-nepi-file-system/ NOTE: While adding custom interface components is encouraged as needed to support a particular project, it is recommended that the base driver class’s interface standards are maintained unmodified to ensure downstream application interfacing compatibility, and that any custom interfaces required for an application are added to the base standard interface set.

Driver Abstraction

In addition to abstracting manufacture specific hardware protocol interfaces, wherever possible, NEPI drivers apply hardware abstraction to individual interface components so that downstream applications and control systems don’t need to know specifics about hardware parameter values. The table below describes some of the common abstraction techniques used across the family of NEPI driver classes by driver interface group.

NEPI Driver Interface Groups

Interface Group	Abstraction Methodology
Capabilities	Provides a common set of device support capabilities for all devices of a specific driver class, which allow downstream interfaces to query and automate control and interface options.
Status	Provides a common set of device status parameters for all devices of a specific driver class, which allow downstream interfaces to automate status use and display options.
Controls	Provides a common set of device controls for all devices of a specific driver class, which allow downstream interfaces to automate device control without detailed knowledge of the device’s underlying control interfaces or parameter values.
Data	Provides a common set of device data output types for all devices of a specific driver class, which allow downstream interfaces to automate data use and display options.
NavPose	Provides a common set of device navigation and orientation output types for all devices of a specific driver class, which allow downstream interfaces to automate data use and configuration options.

NOTE: Not all driver class implementations provide all ROS topics and services defined in each interface group. The response to the capabilities_query for each NEPI driver node provides explicit details about which controls and data are supported by the node. In addition to the capabilities response, supported features can be determined by examining the node’s subset of advertised control and data topics.

IDX Driver Interface

The IDX driver abstraction layer provides plug and play integration and common API interface for all connected 2D and 3D imaging devices, regardless of their native software interface, making downstream edge-processing applications easy to build, maintain, and reuse across all types of imaging sensor devices.

NEPI IDX Capabilities Services Table

ROS Service Name	Service Type	Service Field	Service Data Description
capabilities_query	IDXCapabilitiesQuery*	has_standby_mode	Bool (True/False)
		adjustable_framerate	Bool (True/False)
		adjustable_contrast	Bool (True/False)
		adjustable_brightness	Bool (True/False)
		adjustable_thresholding	Bool (True/False)
		adjustable_range	Bool (True/False)
		has_color_2d_image	Bool (True/False)
		has_bw_2d_image	Bool (True/False)
		has_depth_map	Bool (True/False)
		has_depth_image	Bool (True/False)
		has_pointcloud_image	Bool (True/False)
		has_pointcloud	Bool (True/False)
navpose_ capabilities_query	NavPoseCapabilitiesQuery*	has_gps	Bool (True/False)
		has_orientation	Bool (True/False)
		has_heading	Bool (True/False)

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document.

NEPI IDX Status Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
status	IDXStatus*	serial_num	string (if provided by the device)
		hw_version	string (if provided by the device)
		sw_version	string (if provided by the device)
		standby	Bool (In standby mode)
		resolution_mode	uint8 (1-4 for low-ultra)**
		framerate_mode	uint8 (1-4 for low-ultra) **
		contrast	float32 (0.0-1.0 percent) **
		brightness	float32 (0.0-1.0 percent) **
		thresholding	float32 (0.0-1.0 percent) **
		range_window*	float32,float32 (0.0-1.0 percent, 0.0-1.0 percent) **
		frame_3d	string (3D transfer frame name)

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document. ** abstracted values mapped to hardware specific values in driver.

NEPI IDX Control Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
set_framerate_mode	Uint8	Uint8	uint8 (1-4 for low-ultra)**
set_resolution_mode	Uint8	Uint8	uint8 (1-4 for low-ultra)**
set_standby	Bool	Bool	Bool (Enter/Exit Mode)
set_brightness	Float32	Float32	float32 (0.0-1.0 percent) **
set_contrast	Float32	Float32	float32 (0.0-1.0 percent) **
set_thresholding	Float32	Float32	float32 (0.0-1.0 percent) **
set_range_window	range_window*	range_window*	float32,float32 (0.0-1.0 percent, 0.0-1.0 percent) **

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document. ** abstracted values mapped to hardware specific values in driver.

NEPI IDX Data Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
color_2d_image	Image	Image	sensor_msgs/Image Message
bw_2d_image	Image	Image	sensor_msgs/Image Message
depth_map	Image	Image	sensor_msgs/Image Message (Each pixel represents a range in millimeters)
depth_image	Image	Image	sensor_msgs/Image Message
pointcloud	PointCloud2	PointCloud2	sensor_msgs/PointCloud2 Message
pointcloud_image	Image	Image	sensor_msgs/Image Message

NEPI IDX NavPose Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
gps_fix	NavSatFix	NavSatFix	sensor_msgs/NavSatFix Message
odom	Odometry	Odometry	nav_msgs/Odometry Message
heading	Float64	Float64	float64 (Heading in Degrees)

LSX Driver Interfacing

The LSX driver abstraction layer provides plug and play integration and common API interface for all connected light and strobe illumination devices, regardless of their native software interface, making downstream edge-processing applications easy to build, maintain, and reuse across all types of illumination devices.

NEPI LSX Capabilities Services Table

ROS Service Name	Service Type	Service Field	Service Data Description
capabilities_query	LSXCapabilitiesQuery*	has_standby_mode	Bool (True/False)
		has_intensity_control	Bool (True/False)
		has_hw_strobe_control	Bool (True/False)
		reports_temperature	Bool (True/False)

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document.

NEPI LSX Status Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
status	LSXStatus*	serial_num	string (if provided by the device)
		hw_version	string (if provided by the device)
		sw_version	string (if provided by the device)
		standby	Bool (In standby mode)
		intensity	float32 (0.0-1.0 percent) **
		strobe	Bool (strobe enabled)
		temp_c	uint8 (temp in degrees C)

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document.

NEPI LSX Control Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
set_standby	Bool	Bool	Bool (Enter/Exit Mode)
set_intensity	Float32	Float32	float32 (0.0-1.0 percent) **
set_strobe_enable	Bool	Bool	Bool (Enable/Disable Hardware Strobe Support)

** abstracted values mapped to hardware specific values in driver.

NEPI LSX Data Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
NONE

NEPI LSX NavPose Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
NONE

PTX Driver Interface

The PTX driver abstraction layer provides plug and play integration and common API interface for all connected pan and tilt actuator systems, regardless of their native interface, making setup, control, feedback, and automation processes easy to build, maintain, and reuse across all types of solution platforms.

NEPI PTX Capabilities Services Table

ROS Service Name	Service Type	Service Field	Service Data Description
capabilities_query	PTXCapabilitiesQuery*	has_standby_mode	Bool (True/False)
		adjustable_speed	Bool (True/False)
		absolute_positioning	Bool (True/False)
		homing	Bool (True/False)
		waypoints	Bool (True/False)
navpose_ capabilities_query	NavPoseCapabilitiesQuery*	has_gps	Bool (True/False)
		has_orientation	Bool (True/False)
		has_heading	Bool (True/False)

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document.

NEPI PTX Status Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
status	PTXStatus*	serial_num	string (if provided by the device)
		hw_version	string (if provided by the device)
		sw_version	string (if provided by the device)
		standby	Bool (In standby mode)
		speed_ratio	float32
		reverse_yaw_control	bool
		reverse_pitch_control	bool
		yaw_home_pos_deg	float32
		yaw_goal_deg	float32
		yaw_now_deg	float32
		yaw_min_hardstop_deg	float32
		yaw_max_hardstop_deg	float32
		yaw_min_softstop_deg	float32
		yaw_max_softstop_deg	float32
		pitch_home_pos_deg	float32
		pitch_goal_deg	float32
		pitch_now_deg	float32
		pitch_min_hardstop_deg	float32
		pitch_max_hardstop_deg	float32
		pitch_min_softstop_deg	float32
		pitch_max_softstop_deg	float32
		error_msgs	string

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document. abstracted values mapped to hardware specific values in driver.

NEPI PTX Control Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
set_home_position	PanTiltPosition*	yaw_deg	float32 (abs pan limit degrees from 0 degrees)
		pitch_deg	float32 (abs tilt limit degrees from 0 degrees)
set_home_position_here	Empty	Empty	std_msgs/Empty Message
set_soft_limits	PanTiltPosition*	yaw_deg	float32 (+ or – pan home position degrees)
		pitch_deg	float32 (+ or – tilt home position degrees)
set_speed_ratio	Float32	Float32	float32 (0.0-1.0 percent) **
set_waypoint	AbsolutePanTiltWaypoint*	yaw_deg	float32 (+ or – tilt degrees)
		pitch_deg	float32 (+ or – tilt degrees)
		waypoint_index	uint8 (numerical identifier for waypoint)
set_waypoint_here	UInt8	UInt8	uint8 (numerical identifier for waypoint)
set_standby	Bool	Bool	Bool (Enter/Exit Mode)
jog_to_position	PanTiltPosition*	yaw_deg	float32 (+ or – pan home position degrees)
		pitch_deg	float32 (+ or – tilt home position degrees)
jog_to_pitch_ratio	Float32	Float32	float32 (0.0-1.0 percent) **
jog_to_yaw_ratio	Float32	Float32	float32 (0.0-1.0 percent) **
go_home	Empty	Empty	std_msgs/Empty Message
stop_moving	Empty	Empty	std_msgs/Empty Message
jog_timed_yaw	SingleAxisTimedMove*	direction	int8 (+1=positive, -1=negative)
		duration_s	float32 (seconds, -1.0 for infinite duration)
jog_timed_pitch	SingleAxisTimedMove*	direction	int8 (+1=positive, -1=negative)
		duration_s	float32 (seconds, -1.0 for infinite duration)
reverse_yaw_control	Bool	Bool	Bool (Enter/Exit Mode)
reverse_pitch_control	Bool	Bool	Bool (Enter/Exit Mode)
goto_waypoint	UInt8	UInt8	uint8 (waypoint identifier)

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document. ** abstracted values mapped to hardware specific values in driver.

NEPI PTX Data Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
/joint_states	JointState	JointState	sensor_msgs/JointState Message

NEPI PTX NavPose Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
gps_fix	NavSatFix	NavSatFix	sensor_msgs/NavSatFix Message
odom	Odometry	Odometry	nav_msgs/Odometry Message
heading	Float64	Float64	float64 (Heading in Degrees)

Robotic Control Systems

The RBX driver abstraction layer provides plug and play integration and common high-level API interface for all connected robotic control systems, regardless of their native software interface, making downstream edge-processing applications easy to build, maintain, and reuse across all types of imaging sensor devices.

NEPI RBX Capabilities Services Table

ROS Service Name	Service Type	Service Field	Service Data Description
capabilities_query	RBXCapabilitesQuery*	has_standby_mode	Bool (True/False)
		state_options	String or Strings (String list of supported states enumerated in driver to state change actions)
		mode_options	String or Strings (String list of supported modes enumerated in driver to mode change actions)
		action_options	String or Strings (String list of supported actions enumerated in driver to action process actions)
navpose_ capabilities_query	NavPoseCapabilitiesQuery*	has_gps	Bool (True/False)
		has_orientation	Bool (True/False)
		has_heading	Bool (True/False)

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document.

NEPI RBX Status Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
status	RBXStatus*	serial_num	string (if provided by the device)
		hw_version	string (if provided by the device)
		sw_version	string (if provided by the device)
		standby	Bool (In standby mode)
		control_support	AxisControls* Bools (x,y,z,roll,pitch,yaw, command controls for axis controls set to False will be ignored)
		state	unit8 (index to enumerated state options)
		mode	unit8 (index to enumerated mode options)
		process_current	String (Human readable description of any current control process, set to string “None” if no active process)
		process_last	String (Human readable description of last control process, set to string “None” if no previous process has happened)
		ready	Bool (Ready/Busy, used to check on ready state, then check for busy on command control action, then check for ready for completion of action)
		battery	float32 (0.0-1.0 percent) **
		move_speed	float32 (0.0-1.0 percent of max translational speed for translational command control movements) **
		rotate_speed	float32 (0.0-1.0 percent of max translational speed for rotational command control movements) **
		error_bounds t	RBXErrorBounds * float32s (Abs error bounds for command controls in float32s, [max_distance_error_m, max_rotation_error_deg, max_stabilize_time_s])
		errors_current	RBXGotoErrors*float32s (Signed error values for current control process in float32s X_Meters, Y_Meters, Z_Meters, Heading_Degrees, Roll_Degrees, Pich_Degrees, Yaw_Degrees]. Updated during active command control action, reset after completion or timeout)
		errors_last	BXGotoErrors*float32s (Signed error values for last control process in float32s X_Meters, Y_Meters, Z_Meters, Heading_Degrees, Roll_Degrees, Pitch_Degrees, Yaw_Degrees]. Updated after completion or timeout of last command control action)
		cmd_timeout	Int32 (current command control timeout time in seconds)
		cmd_success	Bool (Success or failure of last command control accepted to meet movement error goals before cmd_timeout time. Updated after ready status goes from busy to ready value)
		status_image_source	String (base image topic for status overlay image. Accepts full or partical namespace, or “” for empty black background)

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document.

NEPI RBX Control Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
set_control_support	AxisControls	Bools	AxisControls* Bools (x,y,z,roll,pitch,yaw, command controls for axis controls set to False will be ignored)
set_cmd_timeout	Int32	Int32	Int32 (current command control timeout time in seconds)
set_move_speed	Float32	Float32	float32 (0.0-1.0 percent of max translational speed for translational command control movements) **
set_rotate_speed	Float32	Float32	float32 (0.0-1.0 percent of max translational speed for rotational command control movements) **
set_error_goals	RBXErrorBounds*	RBXErrorBounds*	float32s (Abs error bounds for command controls in float32s, [max_distance_error_m, max_rotation_error_deg, max_stabilize_time_s])
set_home_current	Empty	Empty	std_msgs/Empty Message
set_standby	Bool	Bool	Bool (Enter/Exit Mode)
set_state	Uint8	Uint8	unit8 (index to enumerated state options provided in capabilities query)
set_mode	Uint8	Uint8	unit8 (index to enumerated mode options provided in capabilities query)
go_action	Uint8	Uint8	unit8 (index to enumerated action options provided in capabilities query)
go_home	Empty	Empty	std_msgs/Empty Message
go_stop	Empty	Empty	std_msgs/Empty Message
goto_pose	rbx_pose_cmd*	3 Float32s	float32s ([ROLL_NED_DEG, PITCH_NED_DEG, YEW_NED_DEGREES], -999 values use current pose values)
goto_position	rbx_position_cmd*	4 Float32s	float32s([X_BODY_METERS, Y_BODY_METERS, Z_BODY_METERS, YAW_BODY_DEGREES]. 0 values are ignored)
goto_location	rbx_location_cmd*	4 Float32s	float32s ([LAT, LONG, ALT_WGS84, YAW_NED_DEGREES], -999 values use current pose values)
set_status_image_source	String	String	Absolute or relative namespace of image to overlay status info

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document. ** abstracted values mapped to hardware specific values in driver.

NEPI RBX Data Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
status_img	Image	Image	sensor_msgs/Image

NEPI RBX NavPose Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
gps_fix	NavSatFix	NavSatFix	sensor_msgs/NavSatFix Message
odom	Odometry	Odometry	nav_msgs/Odometry Message
heading	Float64	Float64	float64 (Heading in Degrees)

NPX Driver Interface

The NPX driver abstraction layer provides plug and play integration and common API interface for all connected navigation and positioning systems, regardless of their native interface, making data manipulation, data geo tagging, and automation processes easy to build, maintain, and reuse across all types of solution platforms.

NEPI NPX capabilities Services Table

ROS Service Name	Service Type	Service Field	Service Data Description
capabilities_ query	NPXCapabilitiesQuery*	has_standby_mode	Bool (True/False)
		has_gps	Bool (True/False)
		has_orientation	Bool (True/False)
		has_heading	Bool (True/False)

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document.

NEPI NPX Status Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
status	NPXStatus*	serial_num	string (if provided by the device)
		hw_version	string (if provided by the device)
		sw_version	string (if provided by the device)
		standby	Bool (In standby mode)
		update_rate	Int32 (published update rate in Hz)
		npx_offsets*	float32s([X_BODY_METERS, Y_BODY_METERS, Z_BODY_METERS, ROLL_BODY_DEGREES , PITCH_BODY_DEGREES YAW_BODY_DEGREES])
navpose_ capabilities_query	NavPoseCapabilitiesQuery*	has_gps	Bool (True/False)
		has_orientation	Bool (True/False)
		has_heading	Bool (True/False)

* Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document. * Custom NEPI ROS interface type. See the link to the NEPI interface repo provided earlier in this document.

NEPI NPX Control Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
set_update_rate	Int32	Int32	Int32 (current command control timeout time in seconds)
set_offsets	npx_offsets*	6 Float32s	float32s([X_BODY_METERS, Y_BODY_METERS, Z_BODY_METERS, ROLL_BODY_DEGREES , PITCH_BODY_DEGREES YAW_BODY_DEGREES])
set_standby	Bool	Bool	Bool (Enter/Exit Mode)
reset	Empty	Empty	std_msgs/Empty Message

NEPI NPX Data Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
TBD

NEPI NPX NavPose Message Table

ROS Message Name	Message Type	Message Field	Message Data Description
gps_fix	NavSatFix	NavSatFix	sensor_msgs/NavSatFix Message
odom	Odometry	Odometry	nav_msgs/Odometry Message
heading	Float64	Float64	float64 (Heading in Degrees)

CMX Driver Interface

The CMX driver abstraction layer provides plug and play integration and common API interface for all NEPI Link interface connected communication devices, regardless of their native interface, making two-way data transfer processes, both persistent and non-persistent, between NEPI devices and remote systems easy to build, maintain, and reuse across all types of communications gateways.

In Development