A ROS2 driver which allows an OxTS INS to interact with a wider ROS network. Where ROS is mentioned in this document, this is in reference to ROS2. References to ROS1 will be explicit.
The ROS driver has been built with ROS release Galactic Geochelone.
Dependencies:
- ROS2 (Galactic Geochelone). (See here for an installation guide)
sudo apt install doxygen
pip3 install sphinx breathe sphinx_rtd_theme
To build the driver:
. /opt/ros/galactic/setup.bash # "." and "source" are interchangeable (unix)
mkdir -p ros_ws/src
cd ros_ws/src
git clone https://github.com/OxfordTechnicalSolutions/oxts_ros2_driver
cd oxts
rosdep update
rosdep install --from-path .
cd ../..
colcon build
. install/setup.sh
NOTE: The rosdep install
command may fail, because the modules in this repository are not yet available as packages in any official repositories. This is fine, and error messages mentioning missing packages (oxts
, oxts_driver
and oxts_ins
) can be ignored.
The driver is configured using .yaml files, as is the norm for ROS2 nodes. The default files in this folder contain lists of all configurable parameters for the nodes. These can be deleted to make the file smaller / tidier. Values not in the config file will remain as defaults.
Launch files can be used from /launch. Launch files are created in Python3 for ROS2, so be aware that Python3 will need to be installed on the machine. They can be use like so:
ros2 launch oxts run.py
or, to replay from an ncom file:
ros2 launch oxts run.py ncom:=<path_to_ncom> # absolute or relative
To view the Odometry and Tf data from the INS, use the visualise.py
launch file. This requires RViz to be installed. There is also the option to start publishing before the NCOM has initialised (not recommended) wait_for_init:=false
.
The currently available launch files are as follows:
visualise.py
- Launches the driver, as well asrobot_state_publisher
andrviz2
(the latter can be disabled withuse_rviz:=False
)run.py
- Only launches the driver, withoutrobot_state_publisher
and nouse_rviz
option
You can also override options from the configuration file at the command-line, e.g.:
ros2 launch oxts run.py topic_prefix:=myprefix
Be aware that currently, this only works for some options.
For a basic tutorial on using this driver, see the "getting started" guide.
The publisher node included in this driver opens a socket to receive NCOM messages from an INS. Data from the NCOM messages are then converted into ROS messages and published to ROS topics for consumption in a wider ROS network. Reference frames for each message can be found in headers. Where NCom is typically vehicle frame, ROS messages are output in INS/IMU frame.
NOTE: There are *_rate
parameters in the YAML configuration, which prevent these topics from being published when set to 0. If topics are missing, ensure that rates have been configured for them.
-
ins/debug_string_pos std_msgs/msg/String This message is not useful for general use. It is currently included for debug purposes. It contains a timestamp from NCom (
TimeWeekSecond
) and WGS84 coordinates (Lat
,Lon
,Alt
) in string form, which is output to the console. -
ins/ecef_pos geometry_msgs/msg/PointStamped Contains a timestamped position of the INS in the ECEF reference frame (derived from
Lat
,Lon
andAlt
from NCOM). -
ins/nav_sat_fix sensor_msgs/msg/NavSatFix Contains a WGS84 position of the INS. This differs from standard use of the NavSatFix message in that the position is not taken directly from a GNSS receiver. It is instead taken from the INS output (
Lat
,Lon
andAlt
) and as a result, this message can be output at a higher rate than is typical with GNSS receivers. Covariance is derived fromEastAcc
,NorthAcc
andAltAcc
. -
ins/nav_sat_ref oxts_msgs/msg/NavSatRef Contains the WGS84 reference position currently being used to calculate the local coordinates for ins/odometry. This can either be the:
- LRF in NCOM (
RefLat
,RefLon
,RefAlt
andRefHeading
) - Position (
Lat
,Lon
,Alt
) & heading (Heading
) of the first NCOM packet received - Position of the first NCOM packet received, aligned to ENU.
(Depending on the parameters set in the
.yaml
) - LRF in NCOM (
-
ins/imu sensor_msgs/msg/Imu Contains IMU data from the INS. Orientation is typically taken from magnetometers in this message; here it is taken from INS output. This comprises orientation in ENU frame (
Roll
,Pitch
andHeading
from NCOM), angular rates in the IMU frame (Wx
,Wy
andWz
), and linear accelerations in the IMU frame (Ax
,Ay
andAz
). -
ins/velocity geometry_msgs/msg/TwistStamped Velocity of the INS, in the INS frame. (Linear velocity corresponds to measurements
IsoVoX
,IsoVoY
andIsoVoZ
, while angular velocity isWx
,Wy
andWz
.) -
ins/odometry nav_msgs/msg/Odometry Odometry data from the INS.
- Position: In a local reference frame which, depending on your configuration, is defined either by:
- The LRF in NCom (
RefLat
,RefLon
,RefAlt
andRefHeading
). - The first NCom packet (
Lat
,Lon
,Alt
andHeading
). - The first NCom packet, aligned to ENU.
- The LRF in NCom (
- Orientation: Rotation of the INS relative to the alignment of the LRF (computed from
Roll
,Pitch
andHeading
) - Linear Velocity: In the above reference frame, computed from
IsoVoX
,IsoVoY
andIsoVoZ
. (Does not yet have variances.) - Angular Velocity: In the above reference frame, computed from
Wx
,Wy
andWz
. (Does not yet have variances.)
- Position: In a local reference frame which, depending on your configuration, is defined either by:
-
ins/path nav_msgs/msg/Path Path taken by the INS, this path contains all historical positions and orientations from the ins/odometry topic.
-
ins/time_reference sensor_msgs/msg/TimeReference From
TimeWeekSecond
in the NCOM. -
ins/lever_arm oxts_msgs/msg/LeverArm Lever arm offsets, in (x, y, z) coordinates. (From the
GAPx
,GAPy
andGAPz
NCOM measurements.) The lever arm type is specified bylever_arm_id
in the message. The reference frame will depend on the lever arm type. Currently, onlygap
(IMU to Primary GPS Antenna offset) is broadcast. -
ins/imu_bias oxts_msgs/msg/ImuBias Biases for the accelerometer (
AxBias
,AyBias
,AzBias
) and gyroscope (WxBias
,WyBias
,WzBias
). -
ins/ncom oxts_msgs/msg/Ncom Raw NCOM data, output by the
/oxts_driver
node, to be subsequently split by the/oxts_ins
node into all the messages listed here (besides this one).
* Links are for ROS1 messages, which are largely unchanged, but equivalent documentation for ROS2 doesn't exist yet.
Useful sources of information around frames used for these messages can be found in:
ROS1 and ROS2 are not directly compatible, as a result of breaking changes between the two. As such, ROS2 messages cannot be consumed directly by ROS1 nodes. To get around this, the ROS1 bridge can be used to convert messages and send them on.
Contributions to this project are welcome. Information on making contributions can be found in CONTRIBUTING.md.