Skip to content

Latest commit

 

History

History
285 lines (201 loc) · 11.5 KB

README.md

File metadata and controls

285 lines (201 loc) · 11.5 KB
Raw

MAVROS

MAVLink extendable communication node for ROS with proxy for Ground Control Station (e.g. QGroundControl).

ROS API documentation moved to wiki.ros.org.

Features

  • Communication with autopilot via serial port, UDP or TCP (e.g. PX4 Pro or ArduPilot)
  • Internal proxy for Ground Control Station (serial, UDP, TCP)
  • Plugin system for ROS-MAVLink translation
  • Parameter manipulation tool
  • Waypoint manipulation tool
  • PX4Flow support (by mavros_extras)
  • OFFBOARD mode support
  • Geographic coordinates conversions.

Limitations

Only for Linux. Depends on Boost library, GCC 4.8+ (C++11 support). Catkin build system required.

This package are dependent on ros-*-mavlink build from mavlink-gbp-release. It exists in ROS package index and usually updates each month.

Connection URL

Connection defined by URL, you can use any supported type for FCU and GCS.

Supported schemas:

  • Serial: /path/to/serial/device[:baudrate]
  • Serial: serial:///path/to/serial/device[:baudrate][?ids=sysid,compid]
  • Serial with hardware flow control: serial-hwfc:///path/to/serial/device[:baudrate][?ids=sysid,compid]
  • UDP: udp://[bind_host][:port]@[remote_host[:port]][/?ids=sysid,compid]
  • UDP broadcast until GCS discovery: udp-b://[bind_host][:port]@[:port][/?ids=sysid,compid]
  • UDP broadcast (permanent): udp-pb://[bind_host][:port]@[:port][/?ids=sysid,compid]
  • TCP client: tcp://[server_host][:port][/?ids=sysid,compid]
  • TCP server: tcp-l://[bind_host][:port][/?ids=sysid,compid]

Note:

  • Ids from URL overrides value given by system_id & component_id parameters.
  • bind_host - default 0.0.0.0 - i.e. IP4 ANY
  • UDP default ports: 14555 @ 14550
  • UDP remote address updated every time with incoming packet on bind port.
  • TCP default port: 5760

Coordinate frames

MAVROS does translate Aerospace NED frames, used in FCUs to ROS ENU frames and vice-versa. For translate airframe related data we simply apply rotation 180° about ROLL (X) axis. For local we apply 180° about ROLL (X) and 90° about YAW (Z) axes. Please read documents from issue #473 for additional information.

All the conversions are handled in src/lib/ftf_frame_conversions.cpp and src/lib/ftf_quaternion_utils.cpp and tested in test/test_frame_conversions.cpp and test/test_quaternion_utils.cpp respectively.

Related issues: #49 (outdated), #216 (outdated), #317 (outdated), #319 (outdated), #321 (outdated), #473. Documents: Frame Conversions, Mavlink coordinate frames.

MAVROS also allows conversion of geodetic and geocentric coordinates through GeographicLib given that:

  • geographic_msgs and NatSatFix.msg require the LLA fields to be filled in WGS-84 datum, meaning that the altitude should be the height above the WGS-84 ellipsoid. For that, a conversion from the height above the geoid (AMSL, considering the egm96 geoid model) to height above the WGS-84 ellipsoid, and vice-versa, is available and used in several plugins;
  • According to ROS REP 105, the earth frame should be propagated in ECEF (Earth-Centered, Earth-Fixed) local coordinates. For that, the functionalities of GeographicLib are used in order to allow conversion from geodetic coordinates to geocentric coordinates;
  • The translation from GPS coordinates to local geocentric coordinates require the definition of a local origin on the map frame, in ECEF, and calculate the offset to it in ENU. All the conversions are supported by GeographicLib classes and methods and implemented in the global_position plugin.

Programs

mavros_node -- main communication node

Main node. Allow disable GCS proxy by setting empty URL.

Run example (autopilot connected via USB at 921600 baud, GCS running on the host with IP 172.16.254.1):

rosrun mavros mavros_node _fcu_url:=/dev/ttyACM0:921600 _gcs_url:=udp://@172.16.254.1

gcs_bridge -- additional proxy

Allows you to add a channel for GCS. For example if you need to connect one GCS for HIL and the second on the tablet.

Example (SITL & QGroundControl):

rosrun mavros mavros_node _gcs_url:='udp://:14556@172.16.254.129:14551' &
rosrun mavros gcs_bridge _gcs_url:='udp://@172.16.254.129'

Launch Files

Launch files are provided for use with common FCUs, in particular Pixhawk:

  • px4.launch -- for use with the PX4 Autopilot (for VTOL, multicopters and planes)
  • apm.launch -- for use with APM flight stacks (e.g., all versions of ArduPlane, ArduCopter, etc)

Examples:

roslaunch mavros px4.launch
roslaunch mavros apm.launch fcu_url:=tcp://localhost gcs_url:=udp://@

Installation

Required dependencies

Most of the ROS dependencies are supported and installed by rosdep, including external libraries as Eigen and Boost.

GeographicLib can be installed by apt-get and it is already included on the rosdep of MAVROS package. It is also possible to compile it and install it from src but be advised to have the proper install directories the same as the ones of the apt-get install, in order to make sure that the FindGeographicLib.cmake finds the required shared libraries (libGeographic.so).

Since GeographicLib requires certain datasets (mainly the geoid dataset) so to fulfill certain calculations, these need to be installed manually by the user using geographiclib-tools, which can be installed by apt-get in Debian systems. For a quicker procedure, just run the available script in the "mavros/scripts" folder, install_geographiclib_datasets.sh.

Note that if you are using an older MAVROS release source install and want to update to a new one, remember to run rosdep update before running rosdep install --from-paths ${ROS_WORKSPACE} --ignore-src --rosdistro=${ROSDISTRO}, with ROS_WORKSPACE your src folder of catkin workspace. This will allow updating the rosdep list and install the required dependencies when issuing rosdep install.

‼️ The geoid dataset is mandatory to allow the conversion between heights in order to respect ROS msg API. Not having the dataset available will shutdown the mavros_node ‼️

❗Run install_geographiclib_datasets.sh to install all datasets or geographiclib-datasets-download egm96_5 (Debian 7, Ubuntu 14.04, 14.10), geographiclib-get-geoids egm96-5 (Debian 8, Fedora 22, Ubuntu 15.04 or later) to install the geoid dataset only:heavy_exclamation_mark:

Binary installation (deb)

ROS repository has binary packages for Ubuntu x86, amd64 (x86_64) and armhf (ARMv7). Kinetic also support Debian Jessie amd64 and arm64 (ARMv8).

Just use apt-get for installation:

sudo apt-get install ros-kinetic-mavros ros-kinetic-mavros-extras

Then install GeographicLib datasets by running the install_geographiclib_datasets.sh script:

wget https://raw.githubusercontent.com/mavlink/mavros/master/mavros/scripts/install_geographiclib_datasets.sh
./install_geographiclib_datasets.sh

Source installation

Use wstool utility for retrieving sources and catkin tool for build.

NOTE: The source installation instructions are for the ROS Kinetic release.

sudo apt-get install python-catkin-tools python-rosinstall-generator -y
# For Noetic use that:
# sudo apt install python3-catkin-tools python3-rosinstall-generator python3-osrf-pycommon -y

# 1. Create the workspace: unneeded if you already has workspace
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws
catkin init
wstool init src

# 2. Install MAVLink
#    we use the Kinetic reference for all ROS distros as it's not distro-specific and up to date
rosinstall_generator --rosdistro kinetic mavlink | tee /tmp/mavros.rosinstall

# 3. Install MAVROS: get source (upstream - released)
rosinstall_generator --upstream mavros | tee -a /tmp/mavros.rosinstall
# alternative: latest source
# rosinstall_generator --upstream-development mavros | tee -a /tmp/mavros.rosinstall
# For fetching all the dependencies into your catkin_ws, just add '--deps' to the above scripts
# ex: rosinstall_generator --upstream mavros --deps | tee -a /tmp/mavros.rosinstall

# 4. Create workspace & deps
wstool merge -t src /tmp/mavros.rosinstall
wstool update -t src -j4
rosdep install --from-paths src --ignore-src -y

# 5. Install GeographicLib datasets:
./src/mavros/mavros/scripts/install_geographiclib_datasets.sh

# 6. Build source
catkin build

# 7. Make sure that you use setup.bash or setup.zsh from workspace.
#    Else rosrun can't find nodes from this workspace.
source devel/setup.bash

Build error. if you has error with missing mavlink* then you need fresh mavlink package. You may update from ros-shadow-fixed (binary installation) or redo script steps 2 & 4.

Note. Since MAVLink 2.0 merged (0.18) all dialects supported by same binary. Unfortunately overlap of v1.0 message ID's not fully handled, first loaded message forbid further changes. Load order always:

  1. common
  2. ardupilotmega
  3. alphabetical ordered list
  4. ...

Note: MAVLINK_DIALECT not used anymore.

Troubleshooting

Error: serial0: receive: End of file

This issue should have been solve in mavros v0.23.2, it was found to be a Boost.ASIO error and should be fix in release > v1.12.0 ( >Boost 1.66).

Contributing

See CONTRIBUTING.md.

Glossary

  • GCS — Ground Control Station
  • FCU — Flight Control Unit (aka FC)
  • OBC — OnBoard Computer (your odroid or raspberry)

Links

  • MAVLink -- The communication protocol for Drones, used by flight controllers, ground control stations, and peripherals
  • mavlink_ros -- original ROS node (few messages, no proxy)
  • Pixhawk -- Open Standards for drone hardware
  • PX4 Autopilot -- Flight Controller with support for most vehicle types and hardened/tested MAVROS support
  • ArduPilot -- tested autopilot APM:Plane (default command set)
  • QGroundControl -- Ground Control Station for MAVLink autopilots, with tested support for Android, iOS, Mac OS, Linux, and Windows
  • mavros_extras -- extra plugins & node for mavros