Overview

ROS driver for all of Microstrain's current G and C series products.

Supported Devices

3DM-GQ7, 3DM-CV7, 3DM-GX5-45, 3DM-GX5-25, 3DM-GX5-15

Resources

Getting Started with GQ7

Installation

Buildfarm

This package is being built and distributed by the ROS build farm. If you do not need to modify the source, it is recommended to install directly from the buildfarm by running the following commands where ROS_DISTRO is the version of ROS you are using such as melodic or noetic:

Driver:

sudo apt-get update && sudo apt-get install ros-ROS_DISTRO-microstrain-inertial-driver

Docker

The microstrain_inertial_driver is distributed as a docker image. More information on how to use the image can be found on DockerHub.

Source

For more info on source code and how to build from source, visit the Source section of our README.md on our microstrain_inertial GitHub page.

For more information on the ROS distros and platforms we support, please see our index.ros.org page.

Usage

Configure Parameters

This node uses a params.yml file for ease of configuration. This file contains all available parameters for the node, so please refer to that file for more information on the available parameters and how to use them.

Override Parameters for ROS

1. Copy and paste the line(s) you desire to change from params.yml into a new .yml file. We will call it /home/user/my_params.yml for this example. This new .yml file will override the default params.yml and if there are multiple lines of the same parameter, the last instance of the parameter will take precedence.

2. Launch the driver and specify the new params file:

roslaunch microstrain_inertial_driver microstrain.launch params_file:=/home/user/my_params.yml

Override Parameters for ROS2

1. Copy the file empty.yml to a new .yml file. For this example we will call the new file /home/user/my_params.yml. This new .yml file will override the default params.yml and if there are multiple lines of the same parameter, the last instance of the parameter will take precedence.

2. Copy and paste the line(s) you desire to change from params.yml into /home/user/my_params.yml.

3. Launch the driver and specify the new params file:

ros2 launch microstrain_inertial_driver microstrain_launch.py params_file:=/home/user/my_params.yml

Messages Publishing

See below for a mapping between the ROS topics and messages to the MIP messages that populate them

Standard ROS Messages

The following topics contain standard ROS messages often used by other nodes. Sensor data is often massaged or converted to be fit into what the ROS standards dictate. This is not always the case, so please refer to the documentation for each topic to see how the data might be different than expected.

• /imu/data sensor_msgs/Imu

  • orientation -> Complementary Filter Quaternion (0x80, 0x0A)

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

  • angular_velocity -> Scaled Gyro (0x80, 0x05)

    • The default behavior is to report these measurements in the sensor's vehicle frame, but if use_enu_frame is true, this will be reported in ROS's vehicle frame

  • linear_acceleration -> Scaled Accel(0x80, 0x04)

    • The x,y,z values reported by the device are in Gs, but are converted to m/s^2 for ROS.

    • The default behavior is to report these measurements in the sensor's vehicle frame, but if use_enu_frame is true, this will be reported in ROS's vehicle frame

• mag sensor_msgs/MagneticField

  • magnetic_field -> Scaled Mag (0x80, 0x06)

    • The default behavior is to report these measurements in the sensor's vehicle frame, but if use_enu_frame is true, this will be reported in ROS's vehicle frame

• gnss1/time_ref sensor_msgs/TimeReference -> GPS Timestamp (0x91, 0xD3)

• gnss1/fix sensor_msgs/NavSatFix -> GNSS LLH Position (0x91, 0x03)

• gnss1/odom nav_msgs/Odometry

  • pose -> GNSS LLH Position (0x91, 0x03)

    • It is nonstandard to store LLH position in an odometry message. This message is kept for backwards compatibility, but may be removed in a future release
    • The covariance is not actually covariance by ROS standards for this message and is actually just uncertainty reported by the device

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

  • twist -> NED Velocity (0x91, 0x05)

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

• gnss2/time_ref sensor_msgs/TimeReference -> GPS Timestamp (0x92, 0xD3)

• gnss2/fix sensor_msgs/NavSatFix -> GNSS LLH Position (0x92, 0x03)

• gnss2/odom nav_msgs/Odometry

  • pose -> GNSS LLH Position (0x92, 0x03)

    • It is nonstandard to store LLH position in an odometry message. This message is kept for backwards compatibility, but may be removed in a future release
    • The covariance is not actually covariance by ROS standards for this message and is actually just uncertainty reported by the device

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

  • twist -> NED Velocity (0x92, 0x05)

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

• nav/filtered_imu/data sensor_msgs/Imu

  • orientation -> Attitude Quaternion (0x82, 0x03)

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

  • orientation_covariance -> Euler Angles Uncertainty (0x82, 0x0A)

  • angular_velocity -> Compensated Angular Rate (0x82, 0x0E)

    • The default behavior is to report these measurements in the sensor's vehicle frame, but if use_enu_frame is true, this will be reported in ROS's vehicle frame

  • linear_acceleration -> Compensated Acceleration (0x82, 0x1C) or Linear Acceleration (0x82, 0x0D) if filter_use_compensated_accel is false

    • The default behavior is to report these measurements in the sensor's vehicle frame, but if use_enu_frame is true, this will be reported in ROS's vehicle frame

• nav/odom nav_msgs/Odometry

  • pose.pose -> LLH Position (0x82, 0x01)

    • It is nonstandard to store LLH position in an odometry message. This message is kept for backwards compatibility, but may be removed in a future release

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

  • pose.covariance -> LLH Position Uncertainty (0x82, 0x08) for position. Euler Angles Uncertainty (0x82, 0x0A) for orientation.

    • The covariance sent to ROS is the squared value of the uncertainty reported by the device. To find the uncertainty, take the square root of the covariance value you are interested in

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

  • orientation -> Attitude Quaternion (0x82, 0x03)

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

  • twist.twist.linear -> NED Velocity (0x82, 0x02)

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

    • If filter_vel_in_vehicle_frame is true, this velocity will be rotated based on the orientation to be in the vehicle frame

  • twist.covariance -> NED Velocity Uncertainty (0x82, 0x09)

    • The covariance sent to ROS is the squared value of the uncertainty reported by the device. To find the uncertainty, take the square root of the covariance value you are interested in

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

  • twist.twist.angular -> Compensated Angular Rate (0x82, 0x0E)

    • The default behavior is to report these measurements in the sensor's vehicle frame, but if use_enu_frame is true, this will be reported in ROS's vehicle frame

• nav/relative_pos/odom nav_msgs/Odometry

  • pose.pose -> NED Relative Position (0x82, 0x42)

    • The default behavior is to report these measurements in the NED frame, but if use_enu_frame is true, this will be reported in the ENU frame

  • Remaining fields are an exact copy of the nav/odom topic

MIP Messages

The following topics contain messages that are more or less an exact pass through to a MIP data field that does not fit into a standard ROS message

• gps_corr microstrain_inertial_msgs/GPSCorrelationTimestampStamped -> GPS Timestamp (0x80, 0x12)

• imu/overrange_status microstrain_inertial_msgs/ImuOverrangeStatus -> Overrange Status (0x80, 0x18)

• gnss1/aiding_status microstrain_inertial_msgs/GNSSAidingStatus -> GNSS Position Aiding Status (0x82, 0x43)

• gnss1/fix_info microstrain_inertial_msgs/GNSSFixInfo -> Fix Info (0x91, 0x0B)

• gnss1/sbas_info microstrain_inertial_msgs/GNSSSbasInfo -> SBAS Info (0x91, 0x12)

• gnss1/rf_error_detection microstrain_inertial_msgs/GNSSRfErrorDetection -> RF Error Detection (0x91, 0x14)

• gnss2/aiding_status microstrain_inertial_msgs/GNSSAidingStatus -> GNSS Position Aiding Status (0x82, 0x43)

• gnss2/fix_info microstrain_inertial_msgs/GNSSFixInfo -> Fix Info (0x92, 0x0B)

• gnss2/sbas_info microstrain_inertial_msgs/GNSSSbasInfo -> SBAS Info (0x92, 0x12)

• gnss2/rf_error_detection microstrain_inertial_msgs/GNSSRfErrorDetection -> RF Error Detection (0x92, 0x14)

• rtk/status microstrain_inertial_msgs/RTKStatus -> RTK Correction Status (0x93, 0x31) (for old RTK dongles)

• rtk/status_v1 microstrain_inertial_msgs/RTKStatusV1 -> RTK Correction Status (0x93, 0x31)

• nav/status microstrain_inertial_msgs/FilterStatus -> Status (0x82, 0x10)

• nav/heading microstrain_inertial_msgs/FilterHeading -> Euler Angles (0x82, 0x05

• nav/heading_state microstrain_inertial_msgs/FilterHeadingState -> Filter Heading Update State (0x82, 0x14)

• nav/dual_antenna_status microstrain_inertial_msgs/GNSSDualAntennaStatus -> GNSS Dual Antenna Status (0x82, 0x49)

• nav/aiding_summary microstrain_inertial_msgs/FilterAidingMeasurementSummary -> Aiding Measurement Summary (0x82, 0x46)

Other Messages

The following topics do not fall into any of the above categories and are likely addons to the device not specifically from the MIP protocol

• nmea/sentence nmea_msgs/Sentence

  • GGA NMEA sentences may be published from the aux port of a GQ7 if it is connected and the following configuration is set:

       aux_port: '/dev/ttyACM1'  # The serial port that the aux port is connected on
       rtk_dongle_enable: True  # Enable the handshake on the aux port to enable NMEA streaming
       publish_nmea: True  # Enable the publishing of NMEA messages

  • Several types of NMEA sentences may be published from the main port of the GQ7 if publish_nmea is true, and this section of config is configured to stream NMEA.

Services

• get_basic_status std_srvs/Trigger

• get_diagnostic_report std_srvs/Trigger

• device_report std_srvs/Trigger

• set_tare_orientation microstrain_inertial_msgs/SetTareOrientation

• set_complementary_filter microstrain_inertial_msgs/SetComplementaryFilter

• get_complementary_filter microstrain_inertial_msgs/GetComplementaryFilter

• set_sensor2vehicle_rotation microstrain_inertial_msgs/SetSensor2VehicleRotation

• get_sensor2vehicle_rotation microstrain_inertial_msgs/GetSensor2VehicleRotation

• set_sensor2vehicle_offset microstrain_inertial_msgs/SetSensor2VehicleOffset

• get_sensor2vehicle_offset microstrain_inertial_msgs/GetSensor2VehicleOffset

• get_sensor2vehicle_transformation microstrain_inertial_msgs/GetSensor2VehicleTransformation

• set_accel_bias microstrain_inertial_msgs/SetAccelBias

• get_accel_bias microstrain_inertial_msgs/GetAccelBias

• set_gyro_bias microstrain_inertial_msgs/SetGyroBias

• get_gyro_bias microstrain_inertial_msgs/GetGyroBias

• gyro_bias_capture std_srvs/Trigger

• set_hard_iron_values microstrain_inertial_msgs/SetHardIronValues

• get_hard_iron_values microstrain_inertial_msgs/GetHardIronValues

• set_soft_iron_matrix microstrain_inertial_msgs/SetSoftIronMatrix

• get_soft_iron_matrix microstrain_inertial_msgs/GetSoftIronMatrix

• set_coning_sculling_comp microstrain_inertial_msgs/SetConingScullingComp

• get_coning_sculling_comp microstrain_inertial_msgs/GetConingScullingComp

• reset_kf std_srvs/Empty

• set_estimation_control_flags microstrain_inertial_msgs/SetEstimationControlFlags

• get_estimation_control_flags microstrain_inertial_msgs/GetEstimationControlFlags

• init_filter_heading microstrain_inertial_msgs/InitFilterHeading

• set_heading_source microstrain_inertial_msgs/SetHeadingSource

• get_heading_source microstrain_inertial_msgs/GetHeadingSource

• commanded_vel_zupt std_srvs/Trigger

• commanded_ang_rate_zupt std_srvs/Trigger

• set_accel_noise microstrain_inertial_msgs/SetAccelNoise

• get_accel_noise microstrain_inertial_msgs/GetAccelNoise

• set_gyro_noise microstrain_inertial_msgs/SetGyroNoise

• get_gyro_noise microstrain_inertial_msgs/GetGyroNoise

• set_mag_noise microstrain_inertial_msgs/SetMagNoise

• get_mag_noise microstrain_inertial_msgs/GetMagNoise

• set_accel_bias_model microstrain_inertial_msgs/SetAccelBiasModel

• get_accel_bias_model microstrain_inertial_msgs/GetAccelBiasModel

• set_gyro_bias_model microstrain_inertial_msgs/SetGyroBiasModel

• get_gyro_bias_model microstrain_inertial_msgs/GetGyroBiasModel

• set_mag_adaptive_vals microstrain_inertial_msgs/SetMagAdaptiveVals

• get_mag_adaptive_vals microstrain_inertial_msgs/GetMagAdaptiveVals

• set_mag_dip_adaptive_vals microstrain_inertial_msgs/SetMagDipAdaptiveVals

• get_mag_dip_adaptive_vals microstrain_inertial_msgs/GetMagDipAdaptiveVals

• set_gravity_adaptive_vals microstrain_inertial_msgs/SetGravityAdaptiveVals

• get_gravity_adaptive_vals microstrain_inertial_msgs/GetGravityAdaptiveVals

• set_zero_angle_update_threshold microstrain_inertial_msgs/SetZeroAngleUpdateThreshold

• get_zero_angle_update_threshold microstrain_inertial_msgs/GetZeroAngleUpdateThreshold

• set_zero_velocity_update_threshold microstrain_inertial_msgs/SetZeroVelocityUpdateThreshold

• get_zero_velocity_update_threshold microstrain_inertial_msgs/GetZeroVelocityUpdateThreshold

• set_reference_position microstrain_inertial_msgs/SetReferencePosition

• get_reference_position microstrain_inertial_msgs/GetReferencePosition

• set_dynamics_mode microstrain_inertial_msgs/SetDynamicsMode

• get_dynamics_mode microstrain_inertial_msgs/GetDynamicsMode

• device_settings microstrain_inertial_msgs/DeviceSettings

• external_heading microstrain_inertial_msgs/ExternalHeadingUpdate

• set_relative_position_reference microstrain_inertial_msgs/SetRelativePositionReference

• set_filter_speed_lever_arm microstrain_inertial_msgs/SetFilterSpeedLeverArm