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 |
Settings | Inputs for supported hardware level settings updating. | ROS Topic / HTML JSON |
Configuration | Inputs for saving and resetting driver and hardware. | ROS Topic / HTML JSON |
Data | Output streams for supported output data | ROS Topic / HTML JSON and Video |
Data Saving | Inputs for saving device produced data. | ROS Topic / HTML JSON |
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:
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_auto_adjustment | 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) | ||
idx_controls | Bool (Enable/disable IDX controls) | ||
auto | Bool (Enable/disable IDX auto function) | ||
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 |
reset_controls | Empty | Empty | empty msg |
set_auto_adjust | Bool | Bool | bool (enable/disable IDX auto adjustment) |
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.
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 Data Saving Message Table
ROS Message Name | Message Type | Message Field | Message Data Description |
save_data_rate | SaveDataRate* | SaveDataRate* | string “DataProductName”,float32 “Rate in Hz” (set to zero to turn saving off for specific data product types) |
save_data_prefix | String | String | string “SubfolderName”, “FilePrefixString”, ” SubFolder/FilePrefix” |
save_data | SaveData* | 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_trigger | Empty | Empty | sensor_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 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) |
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 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.