< All Topics
Print

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.

A diagram of a machine processing process Description automatically generated

NEPI Driver Classes
Driver Class NameDescription
IDX2D and 3D Imaging Sensors
PTXPan & Tilt Actuators
LSXLights and Strobes
RBXRobotic Control Systems
NPXNavigation and Pose Systems
CMXCommunications 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 GroupDescriptionInterface Details
CapabilitiesOutput message with information on supported settings and data interfacesROS Service / HTML JSON
StatusOutput message with group standard status dataROS Topic / HTML JSON
ControlsInputs for supported real-time control actions.ROS Topic / HTML JSON
SettingsInputs for supported hardware level settings updating.ROS Topic / HTML JSON
ConfigurationInputs for saving and resetting driver and hardware.ROS Topic / HTML JSON
DataOutput streams for supported output dataROS Topic / HTML JSON and Video
Data SavingInputs for saving device produced data.ROS Topic / HTML JSON
NavPoseOutput streams for any supported navigation and orientation data sourcesROS 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 GroupAbstraction Methodology
CapabilitiesProvides 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.
StatusProvides 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.
ControlsProvides 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.
DataProvides 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.
NavPoseProvides 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 NameService TypeService FieldService Data Description
capabilities_queryIDXCapabilitiesQuery*has_standby_modeBool (True/False)
adjustable_framerateBool (True/False)
adjustable_contrastBool (True/False)
adjustable_brightnessBool (True/False)
adjustable_thresholdingBool (True/False)
adjustable_rangeBool (True/False)
has_auto_adjustmentBool (True/False)
has_color_2d_imageBool (True/False)
has_bw_2d_imageBool (True/False)
has_depth_mapBool (True/False)
has_depth_imageBool (True/False)
has_pointcloud_imageBool (True/False)
has_pointcloudBool (True/False)
navpose_ capabilities_queryNavPoseCapabilitiesQuery*has_gpsBool (True/False)
has_orientationBool (True/False)
has_headingBool (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 NameMessage TypeMessage FieldMessage Data Description
statusIDXStatus*serial_numstring (if provided by the device)
hw_versionstring (if provided by the device)
sw_versionstring (if provided by the device)
standbyBool (In standby mode)
idx_controlsBool (Enable/disable IDX controls)
autoBool (Enable/disable IDX auto function)
resolution_modeuint8 (1-4 for low-ultra)**
framerate_modeuint8 (1-4 for low-ultra) **
contrastfloat32 (0.0-1.0 percent) **
brightnessfloat32 (0.0-1.0 percent) **
thresholdingfloat32 (0.0-1.0 percent) **
range_window*float32,float32 (0.0-1.0 percent, 0.0-1.0 percent) **
frame_3dstring (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 NameMessage TypeMessage FieldMessage Data Description
reset_controlsEmptyEmptyempty msg
set_auto_adjustBoolBoolbool (enable/disable IDX auto adjustment)
set_framerate_modeUint8Uint8uint8 (1-4 for low-ultra)
set_resolution_modeUint8Uint8uint8 (1-4 for low-ultra)
set_standbyBoolBoolBool (Enter/Exit Mode)
set_brightnessFloat32Float32float32 (0.0-1.0 percent) 
set_contrastFloat32Float32float32 (0.0-1.0 percent) 
set_thresholdingFloat32Float32float32 (0.0-1.0 percent) 
set_range_windowrange_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.

NEPI IDX Data Message Table
ROS Message NameMessage TypeMessage FieldMessage Data Description
color_2d_imageImageImagesensor_msgs/Image Message
bw_2d_imageImageImagesensor_msgs/Image Message
depth_mapImageImagesensor_msgs/Image Message (Each pixel represents a range in millimeters)
depth_imageImageImagesensor_msgs/Image Message
pointcloudPointCloud2PointCloud2sensor_msgs/PointCloud2 Message
pointcloud_imageImageImagesensor_msgs/Image Message
NEPI IDX Data Saving Message Table
ROS Message NameMessage TypeMessage FieldMessage Data Description
save_data_rateSaveDataRate*SaveDataRate*string “DataProductName”,float32 “Rate in Hz” (set to zero to turn saving off for specific data product types)
save_data_prefixStringStringstring  “SubfolderName”, “FilePrefixString”, ” SubFolder/FilePrefix”
save_dataSaveData*SaveData*bool: save_continous, bool: save_raw (save_continous for normal data saving, save_raw for special device driver raw data saving if supported)
snapshot_triggerEmptyEmptysensor_msgs/Empty Message driver saves a single file for any data products that have a rate set > 0

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

NEPI IDX NavPose Message Table
ROS Message NameMessage TypeMessage FieldMessage Data Description
gps_fixNavSatFixNavSatFixsensor_msgs/NavSatFix Message
odomOdometryOdometrynav_msgs/Odometry Message
headingFloat64Float64float64 (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 NameService TypeService FieldService Data Description
capabilities_queryLSXCapabilitiesQuery*has_standby_modeBool (True/False)
has_intensity_controlBool (True/False)
has_hw_strobe_controlBool (True/False)
reports_temperatureBool (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 NameMessage TypeMessage FieldMessage Data Description
statusLSXStatus*serial_numstring (if provided by the device)
hw_versionstring (if provided by the device)
sw_versionstring (if provided by the device)
standbyBool (In standby mode)
intensityfloat32 (0.0-1.0 percent) **
strobeBool (strobe enabled)
temp_cuint8 (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 NameMessage TypeMessage FieldMessage Data Description
set_standbyBoolBoolBool (Enter/Exit Mode)
set_intensityFloat32Float32float32 (0.0-1.0 percent) **
set_strobe_enableBoolBoolBool (Enable/Disable Hardware Strobe Support)

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

NEPI LSX Data Message Table
ROS Message NameMessage TypeMessage FieldMessage Data Description
NONE   
NEPI LSX NavPose Message Table
ROS Message NameMessage TypeMessage FieldMessage 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 NameService TypeService FieldService Data Description
capabilities_queryPTXCapabilitiesQuery*has_standby_modeBool (True/False)
adjustable_speedBool (True/False)
absolute_positioningBool (True/False)
homingBool (True/False)
waypointsBool
(True/False)
navpose_ capabilities_queryNavPoseCapabilitiesQuery*has_gpsBool (True/False)
has_orientationBool (True/False)
has_headingBool (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 NameMessage TypeMessage FieldMessage Data Description
statusPTXStatus*serial_numstring (if provided by the device)
hw_versionstring (if provided by the device)
sw_versionstring (if provided by the device)
standbyBool (In standby mode)
speed_ratiofloat32
reverse_yaw_controlbool
reverse_pitch_controlbool
yaw_home_pos_degfloat32
yaw_goal_degfloat32
yaw_now_degfloat32
yaw_min_hardstop_degfloat32
yaw_max_hardstop_degfloat32
yaw_min_softstop_degfloat32
yaw_max_softstop_degfloat32
pitch_home_pos_degfloat32
pitch_goal_degfloat32
pitch_now_degfloat32
pitch_min_hardstop_degfloat32
pitch_max_hardstop_degfloat32
pitch_min_softstop_degfloat32
pitch_max_softstop_degfloat32
error_msgsstring

* 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 NameMessage TypeMessage FieldMessage Data Description
set_home_positionPanTiltPosition*yaw_degfloat32 (abs pan limit degrees from 0 degrees)
pitch_degfloat32 (abs tilt limit degrees from 0 degrees)
set_home_position_hereEmptyEmptystd_msgs/Empty Message
set_soft_limitsPanTiltPosition*yaw_degfloat32 (+ or – pan home position degrees)
pitch_degfloat32 (+ or – tilt home position degrees)
set_speed_ratioFloat32Float32float32 (0.0-1.0 percent) **
set_waypointAbsolutePanTiltWaypoint*yaw_degfloat32 (+ or – tilt degrees)
pitch_degfloat32 (+ or – tilt degrees)
waypoint_indexuint8 (numerical identifier for waypoint)
set_waypoint_hereUInt8UInt8uint8 (numerical identifier for waypoint)
set_standbyBoolBoolBool (Enter/Exit Mode)
jog_to_positionPanTiltPosition*yaw_degfloat32 (+ or – pan home position degrees)
pitch_degfloat32 (+ or – tilt home position degrees)
jog_to_pitch_ratioFloat32Float32float32 (0.0-1.0 percent) **
jog_to_yaw_ratioFloat32Float32float32 (0.0-1.0 percent) **
go_homeEmptyEmptystd_msgs/Empty Message
stop_movingEmptyEmptystd_msgs/Empty Message
jog_timed_yawSingleAxisTimedMove*directionint8 (+1=positive, -1=negative)
duration_sfloat32 (seconds, -1.0 for infinite duration)
jog_timed_pitchSingleAxisTimedMove*directionint8 (+1=positive, -1=negative)
duration_sfloat32 (seconds, -1.0 for infinite duration)
reverse_yaw_controlBoolBoolBool (Enter/Exit Mode)
reverse_pitch_controlBoolBoolBool (Enter/Exit Mode)
goto_waypointUInt8UInt8uint8 (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 NameMessage TypeMessage FieldMessage Data Description
/joint_statesJointStateJointStatesensor_msgs/JointState Message
NEPI PTX NavPose Message Table
ROS Message NameMessage TypeMessage FieldMessage Data Description
gps_fixNavSatFixNavSatFixsensor_msgs/NavSatFix Message
odomOdometryOdometrynav_msgs/Odometry Message
headingFloat64Float64float64 (Heading in Degrees)

RBX Driver Interface

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 NameService TypeService FieldService Data Description
capabilities_queryRBXCapabilitesQuery*has_standby_modeBool (True/False)
state_optionsString or Strings (String list of supported states enumerated in driver to state change actions)
mode_optionsString or Strings (String list of supported modes enumerated in driver to mode change actions)
action_optionsString or Strings (String list of supported actions enumerated in driver to action process actions)
navpose_ capabilities_queryNavPoseCapabilitiesQuery*has_gpsBool (True/False)
has_orientationBool (True/False)
has_headingBool (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 NameMessage TypeMessage FieldMessage Data Description
statusRBXStatus*serial_numstring (if provided by the device)
hw_versionstring (if provided by the device)
sw_versionstring (if provided by the device)
standbyBool (In standby mode)
control_supportAxisControls* Bools (x,y,z,roll,pitch,yaw, command controls for axis controls set to False will be ignored)
stateunit8 (index to enumerated state options)
modeunit8 (index to enumerated mode options)
process_currentString (Human readable description of any current control process, set to string “None” if no active process)
process_lastString (Human readable description of last control process, set to string “None” if no previous process has happened)
readyBool (Ready/Busy, used to check on ready state, then check for busy on command control action, then check for ready for completion of action)
batteryfloat32 (0.0-1.0 percent) **
move_speedfloat32 (0.0-1.0 percent of max translational speed for translational command control movements) **
rotate_speedfloat32 (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_currentRBXGotoErrors*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_lastBXGotoErrors*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_timeoutInt32 (current command control timeout time in seconds)
cmd_successBool (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_sourceString (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 NameMessage TypeMessage FieldMessage Data Description
set_control_supportAxisControlsBoolsAxisControls* Bools (x,y,z,roll,pitch,yaw, command controls for axis controls set to False will be ignored)
set_cmd_timeoutInt32Int32Int32 (current command control timeout time in seconds)
set_move_speedFloat32Float32float32 (0.0-1.0 percent of max translational speed for translational command control movements) **
set_rotate_speedFloat32Float32float32 (0.0-1.0 percent of max translational speed for rotational command control movements) **
set_error_goalsRBXErrorBounds*RBXErrorBounds*float32s (Abs error bounds for command controls in float32s, [max_distance_error_m, max_rotation_error_deg, max_stabilize_time_s])
set_home_currentEmptyEmptystd_msgs/Empty Message
set_standbyBoolBoolBool (Enter/Exit Mode)
set_stateUint8Uint8unit8 (index to enumerated state options provided in capabilities query)
set_modeUint8Uint8unit8 (index to enumerated mode options provided in capabilities query)
go_actionUint8Uint8unit8 (index to enumerated action options provided in capabilities query)
go_homeEmptyEmptystd_msgs/Empty Message
go_stopEmptyEmptystd_msgs/Empty Message
goto_poserbx_pose_cmd*3 Float32sfloat32s ([ROLL_NED_DEG, PITCH_NED_DEG, YEW_NED_DEGREES], -999 values use current pose values)
goto_positionrbx_position_cmd*4 Float32sfloat32s([X_BODY_METERS, Y_BODY_METERS, Z_BODY_METERS, YAW_BODY_DEGREES]. 0 values are ignored)
goto_locationrbx_location_cmd*4 Float32sfloat32s ([LAT, LONG, ALT_WGS84, YAW_NED_DEGREES], -999 values use current pose values)
set_status_image_sourceStringStringAbsolute 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 NameMessage TypeMessage FieldMessage Data Description
status_imgImageImagesensor_msgs/Image
NEPI RBX NavPose Message Table
ROS Message NameMessage TypeMessage FieldMessage Data Description
gps_fixNavSatFixNavSatFixsensor_msgs/NavSatFix Message
odomOdometryOdometrynav_msgs/Odometry Message
headingFloat64Float64float64 (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 NameService TypeService FieldService Data Description
capabilities_ queryNPXCapabilitiesQuery*has_standby_modeBool (True/False)
has_gpsBool (True/False)
has_orientationBool (True/False)
has_headingBool (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 NameMessage TypeMessage FieldMessage Data Description
statusNPXStatus*serial_numstring (if provided by the device)
hw_versionstring (if provided by the device)
sw_versionstring (if provided by the device)
standbyBool (In standby mode)
update_rateInt32 (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_queryNavPoseCapabilitiesQuery*has_gpsBool (True/False)
has_orientationBool (True/False)
has_headingBool (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 NameMessage TypeMessage FieldMessage Data Description
set_update_rateInt32Int32Int32 (current command control timeout time in seconds)
set_offsetsnpx_offsets*6 Float32sfloat32s([X_BODY_METERS, Y_BODY_METERS, Z_BODY_METERS, ROLL_BODY_DEGREES , PITCH_BODY_DEGREES YAW_BODY_DEGREES])
set_standbyBoolBoolBool (Enter/Exit Mode)
resetEmptyEmptystd_msgs/Empty Message
NEPI NPX Data Message Table
ROS Message NameMessage TypeMessage FieldMessage Data Description
TBD   
NEPI NPX NavPose Message Table
ROS Message NameMessage TypeMessage FieldMessage Data Description
gps_fixNavSatFixNavSatFixsensor_msgs/NavSatFix Message
odomOdometryOdometrynav_msgs/Odometry Message
headingFloat64Float64float64 (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
Table of Contents