Witmotion IMU sensor driver for ROS

|focal-source|focal-amd64|focal-armhf|focal-arm64|dev|doc| |————–|————-|————-|————-|—–|—–| |||||||

witmotion_ros module implements a ROS 1 wrapper for Witmotion IMU driver library. It reads the data from the family of TTL-compatible inertial pose estimation units (IMUs) manufactured by WitMotion Shenzhen Co.,Ltd publishing the information in ROS-native way using sensor_msgs and std_msgs message definition packages. The module is focused on read-only access, so calibration and bias regulation functions are implemented in the underlying library. Port access model is implemented in monopolistic way acccording to UNIX specification, so only one instance of the module can be executed for the dedicated virtual device.

Datasheets and official documentation

The module is developed according to the specifications released by Witmotion, the presented snapshot has download date is 23.02.2022. The official website https://wiki.wit-motion.com is not always accessible, so the PDF snapshots are placed under IPFS web directory.

ROS2 branch

The ROS2 compatible implementation of the driver is WIP under ros2 branch. The initial migration made by @fllay (pull request #12).

Marking ROS2-related issues and pull requests

The contributors are strongly encouraged to mark the names of their ROS2-related issues and pull requests with [ROS2] prefix.

Installation

Prerequisites

The package requires QtSerialPort development package from Qt 5.2+

sudo apt-get install libqt5serialport5-dev

Building

cd catkin_ws
git clone --recursive https://github.com/ElettraSciComp/witmotion_IMU_ros.git src/witmotion_ros
catkin_make

If compilation fails, first check the directory src/witmotion_ros/witmotion-uart-qt. If it is empty, the recursive clone failed, and you should manually clone the underlying library from the repository https://github.com/ElettraSciComp/witmotion_IMU_QT into this directory. IMPORTANT! Please beware of the directory name, the CMakeLists file refers exactly to the name witmotion-uart-qt specified in the target import section.

Usage

roslaunch witmotion_ros witmotion.launch

Configuration

Configuration of the node is done by default via the configuration YAML file config.yml. But it also can be done using roslaunch XML syntax under the node’s internal namespace. The single value measurements, like pressure and temperature, are enabled for the linear calibration because there can be differences in decoding coefficients between the sensors (proven for WT31N and JY901B sensors).

Parameters

• port - the virtual kernel device name for a port, ttyUSB0 by default
• baud_rate - port rate value to be used by the library for opening the port, 9600 baud by default
• polling_interval - the sensor polling interval in milliseconds. If this parameter is omitted, the default value is set up by the library (50 ms).
• timeout_ms - the sensor timeout period in milliseconds. If no data is received from the sensor after this period, then an error is raised and the node terminates. If this parameter is omitted, a default value of 3 times the polling interval is used. If this parameter is zero, the timeout check is disabled.
• restart_service_name - the service name used to restart the sensor connection after an error.
• imu_publisher:
  • topic_name - the topic name for IMU data publisher, imu in the node’s namespace by default
  • frame_id - IMU message header frame ID
  • use_native_orientation - instructs the node to use the native quaternion orientation measurement from the sensor instead of synthesized from Euler angles. NOTE: if this setting is enabled bu the sensor does not produce orientation in the quaternion format, the IMU message will never be published!
  • measurements - every measurement in IMU message data pack can be enabled or disabled. If the measurement is disabled, the corresponding covariance matrix is set to begin from -1 as it is described in the message definition.
    • acceleration
      • enabled
      • covariance - row-major matrix 3x3, all zeros for unknown covariation
    • angular_velocity
      • enabled
      • covariance - row-major matrix 3x3, all zeros for unknown covariation
    • orientation
      • enabled
      • covariance - row-major matrix 3x3, all zeros for unknown covariation
• temperature_publisher
  • enabled - enable or disable temperature measurement extraction
  • topic_name - the topic name for publishing temperature data
  • frame_id - message header frame ID
  • from_message - the message type string to determine from which type of Witmotion measurement message the temperature data should be extracted (please refer to the original documentation for detailed description). The possible values are: acceleration, angular_vel, orientation or magnetometer.
  • variance - the constant variance, if applicable, otherwise 0
  • coefficient - linear calibration multiplier, 1.0 by default
  • addition - linear calibration addendum, 0 by default
• magnetometer_publisher
  • enabled - enable or disable magnetometer measurement extraction
  • topic_name - the topic name for publishing the data
  • frame_id - message header frame ID
  • coefficient - linear calibration multiplier, 1.0 by default
  • addition - linear calibration addendum, 0 by default
  • covariance - row-major matrix 3x3, all zeros for unknown covariation
• barometer_publisher
  • enabled - enable or disable barometer measurement extraction
  • topic_name - the topic name for publishing the data
  • frame_id - message header frame ID
  • coefficient - linear calibration multiplier, 1.0 by default
  • addition - linear calibration addendum, 0 by default
  • variance - the constant variance, if applicable, otherwise 0
• altimeter_publisher
  • enabled - enable or disable altitude measurement extraction
  • topic_name - the topic name for publishing the data
  • coefficient - linear calibration multiplier, 1.0 by default
  • addition - linear calibration addendum, 0 by default
• orientation_publisher
  • enabled - enable or disable orientation measurement extraction
  • topic_name - the topic name for publishing the data
• gps_publisher
  • enabled - enables/disables all GPS receiver measurements extraction
  • navsat_fix_frame_id - frame ID for GPS fixed position publisher
  • navsat_fix_topic_name - topic name for GPS fixed position publisher
  • navsat_altitude_topic_name - topic name for GPS altitude publisher
  • navsat_satellites_topic_name - topic name for GPS active satellites number publisher
  • navsat_variance_topic_name - topic name for GPS diagonal variance publisher
  • ground_speed_topic_name - topic name for GPS ground speed publisher
• rtc_publisher
  • enabled - enables/disables realtime clock information decoder
  • topic_name - topic name for realtime clock publisher
  • presync - instructs the node to perform an attempt to pre-synchronize sensor’s internal realtime clock

Changelog for package witmotion_ros

Forthcoming

• add MultiThreadedExecutor in witmotion_ros_node

1.3.1 (2023-08-08)

• Fixed GPS decoder function in the underlying library (added x10 multiplier in Degrees section)
• Version bump to 1.3.1
• Community-driven test of the library on WTGAHRS1 combined enclosed IMU/GPS sensor module [<https://www.wit-motion.com/inertial-navigation/witmotion-wtgahrs1-10-axis-gps.html>]{.title-ref} by Quing Joe Wong [joewong00]{.title-ref}
• Contributors: Andrey Vukolov, Quing Joe Wong

1.3.0 (2023-06-14)

• Added support for serial port timeout behaviour ([timeout_ms]{.title-ref})
• Updated README.md
• Merged pull request [#27 <https://github.com/ElettraSciComp/witmotion_IMU_ros/pull/27>]{.title-ref} from [gsokoll]{.title-ref}
• Version bump to 1.3.0
• Matched versions for ROS node and underlying library after merging pull request [#7 <https://github.com/ElettraSciComp/witmotion_IMU_QT/pull/7>]{.title-ref}

1.2.28 (2023-03-21)

• Updated online documentation
• Updated CMake build scenario to suppress useless Doxygen warning
• Version bump to 1.2.28
• Matched versions for ROS node and underlying library

1.2.27 (2023-02-27)

• Merged pull request #12 from fllay/main Migration to ROS2 made by \@fllay approved. The information about the existence of the ROS2 branch will be added to README.md
• Added ROS2 branch information to README
• ros2 code Contributors: Andrei Vukolov, Andrey Vukolov, fllay
• Update .gitmodules Updated URLs to proper HTTPS
• Rename the project to witmotion_ros - cancelled
• fixed segmentation fault when Ctrl-C
• fixed polling interval and threading
• Fix link error
• package.xml version bump

0.11.18 (2022-08-26)

• README fix
• Added RTC pre-synchronization
  • Fixed RTC callback crash
  • Implemented ISO8601 date conversion for pre-synchronization
  • Added presync parameter
• Version bump to 0.11.18
  • Fixed RTC unitialized STL pointer
  • Fixed Qt libraries linking
  • Fixed RTC publishing
  • TODO: Implementation of RTC precalibration
• Contributors: Andrey Vukolov

0.8.22 (2022-08-22)

• Added dynamic versioning
  • Added automatic package.xml version generator
  • Added dependency on underlying library's 'version' file

  - Added automatic compatible ROS version string parser (GNU -> ROS)

• Library version bumped to 0.8.22-alpha
• Added convenient defaults for WT901 sensor on 200 Hz
• Library version bump to 0.7.15-alpha
• Version bump to 0.6.14-alpha
• Defaults for WT31N
  • Added default configuration file for WT31N sensor
  • Added example launch file for WT31N sensor
  • Bumped library version
• Added native quaternion support - Added 'use_native_orientation' parameter to IMU message publisher for forced waiting for native quaternion if the sensor provides it
  • Added native quaternion parser to IMU processing routine

  - Library version bump: the controller application for WT901 series sensors is now available

  • Tested on WT901 and JY901B sensors
• IPFS Datasheet directory fix
• Convenient defaults - Convenient defaults for spatial covariances (obtained from tests on spatially fixed WT901 sensor) - Convenient defaults for magnetometer linear calibration (conversion from 10x uTesla to Tesla)
  • Convenient defaults for magnetometer covariance
• Qt namespace workaround
  • Library with fully implemented Qt namespace workaround
  • Closes #9
  • Prevalidation of WT901 controller application
• Snapped to library version 0.3.1-alpha
• Fixed IPFS hash
• Fixed logical error in IMU publisher
• Update README.md Closes #6
• Submodule update
• README update for RTC
• Added RTC publisher support
  • Refers to #3 opened by \@rlabs-oss

  - Implements ROS timestamp publishing based on realtime clock data from Witmotion sensor device

• Readme fix, closes #2 after adding installation guile
• Added installation guidance, minor fixes
• Merge pull request #5 from agtbaskara/fix-missing-std-srvs Merged closing #4
• Add std_srvs dependency
• README to ROS Wiki link
• Merge pull request #1 from zacharykratochvil/main Merge: fixed linking to tf_geometry_msgs package from \@zacharykratochvil
• Merge branch 'main' into main
• Added untested GPS decoder code
  • Added GPS decoder code with covariance dependency
  • Added GPS accuracy message decoder
  • Added GPS ground speed decoder
• fixed linking to tf_geometry_msgs package
• Updated README for last topic addition
• Added Orientation processing and publishing
• Renaming
• Rebase
• LICENSE added
• Initial documentation before migration
• First alpha release
• Contributors: Andrei Vukolov, Andrey Vukolov, agtbaskara, zacharykratochvil