MAVLink driver for the REXYGEN system
(the MAVLinkDrv module)
User guide
Plzeň (Pilsen), Czech Republic
2020-09-03
Contents
1.1 Introduction
1.2 Basic concepts
1.2.1 Driver configuration
1.2.2 Receiving messages
1.2.3 Sending messages
1.3 Installation of driver on target device
1.3.1 Target device with OS Windows
1.3.2 Target device with OS linux
2 Integrating driver into the project
2.1 Přidání MAVLinkDrv ovladače
3 Licensing
Chapter 1
MAVLink for REXYGEN system
1.1 Introduction
This manual describes MAVLinkDrv - the driver for MAVLink communication within the REXYGEN system. The driver was developed by REX Controls.
The driver integrates the MAVLink communication protocol into the control algorithm in the REXYGEN system. It also allows routing of the mavlink protocol over UDP, TCP, or serial link. Such a functionality is performed, for example, by a mavlink-router on Intel Aero or MAVROS in the ROS system.
1.2 Basic concepts
The basic concept of the driver is simple: upon every tick of the driver, incoming packets are processed and routed in the context of the driver thread to corresponding function blocks. The processing of outgoing packets is performed from the context of execution of the respective blocks. If the application uses the routing function, all communication in the system is done with the driver’s granularity. It is recommended to set the executive period to 1-5ms for correct function of the application as a “Companion computer”.
All the functionality of the driver is accessed via function blocks of the RECV and SEND type. One RECV block (named MAV_RECV_<command>) and one SEND block (named MAV_SEND_<command>) are defined for each message.
No synchronization between blocks and the executive part of the driver is performed in the current version. Therefore, all receive blocks must be placed in tasks linked to the appropriate driver (ie using the IOTASK block). All higher logic is recommended to be implemented in subsystems.
The driver supports messages with scalar types. Character fields are converted to STRING of the appropriate length. Arrays of other types are converted to scalar numbered inputs/outputs. Blocks with non-character fields longer than 8 are not supported.
The documentation for MAVLink messages is available at
https://mavlink.io/en/messages/common.html
1.2.1 Driver configuration
The driver configuration is stored in a .rio file in the JSON format. Configuration dialog is not available in current version. Configuration is used to define system ID and router settings. All other functionality is defined within function blocks. The following block shows a simple driver configuration.
"SystemID" : 200,
"ComponentID" : 1,
"Endpoints" : [
{
"Type": "Serial",
"Device": "/dev/ttyS1",
"BaudRate": 921600
},
{
"Type": "UDP",
"Mode": "listen",
"Address": "192.168.1.100",
"Port": 14550
"BindAddress": "0.0.0.0",
"BindPort": 14550
},
{
"Type": "TCP",
"Mode": "connect",
"Address": "192.168.1.200",
"Port": 15550
}
]
}
Main attributes
- System ID – defines application System ID,
- Component ID – defines application Component ID,
- Endpoints – defines the list of communication channels. The driver automatically routes packets between these channels. Supported channels are Serial, UDP a TCP.
Serial endpoint attributes
- Device – serial device pathname,
- BaudRate – serial device baud rate.
UDP endpoint attributes
- Mode – possible options: listen – listening on local port or connect – connecting to remote device. In listen mode, messages are received from all devices with any IP and port. In connect mode, only data from the device is received that is specified by Address and Port.
- Address – IP address of the remote device. If not specified or set to 0.0.0.0 in listen mode, the driver will send data to the first connected device.
- Port – The IP address of the remote device. If not specified or set to 0.0.0.0 in listen mode, the driver will send data to the first connected device.
- BindAddress – IP address of the local interface where communication will take place. It may be omitted or set to 0.0.0.0, in which case all local interfaces will be used.
- BindPort – Local interface port. It can be omitted or set to 0, in which case the appropriate local port is selected by the operating system.
For UDP endpoints, we recommend using only the listen mode, because the connect mode can cause problems if the opposite device is unavailable or closes the connection. In listen mode, it is also possible to operate communication via broadcast. For broadcasting, the local interface must be selected by setting the appropriate IP address using the BindAddress and BindPort parameters, and the Address parameter set the local broadcast address (eg 192.168.1.255).
TCP endpoint attributes
- Mode – possible options: listen – listening on local port or connect – connecting to remote device.
- Address – IP address of a local interface (0.0.0.0 for all) or IP address of a remote device ,
- Port – local port for listening or remote device port.
1.2.2 Receiving messages
Messages are received using MAV_RECV_<command> blocks. The basic interface of the block is as follows:
- INHIBIT – input, BOOL. Specifies whether to forward the received message. This must be set in advance, ie it is not possible to decide on routing based on message content.
- VALID – output, BOOL. Indicates the validity of the output data. Set to TRUE in case of valid data received before timeout elapsed (see the TimoutMS parameter).
- ACT – output, BOOL. Set to TRUE only in the first tick after receiving new data.
- Sequence – output, INT. Sequence number from the header of the last received message frame - see the MAVLink documentation.
- Timestamp – output, INT. Timestamp of the last received data in the internal REXYGENformat, ie nanoseconds.
- SrcSystemID – parameter, SHORT. Specifies source node system ID (1 for UAV).
- SrcComponentID – parameter, SHORT. Specifies source node component ID (1 pro UAV).
- TgtSystemID – parameter, SHORT. Specifies target node system ID (-1 for not set or not included in the message, -2 for algorithm ID - see SystemID in driver configuration).
- TgtComponentID – parameter, SHORT. Specifies target node component ID (-1 for not set or not included in the message, -2 for algorithm ID - see ComponentID in driver configuration).
- TimeoutMS – parameter, LONG. maximum time between messages. If new data is not received in this interval, VALID is set to false. If set to 0, the timeout is not defined.
Other outputs are defined by the respective message and contain data from the last received message.
1.2.3 Sending messages
Messages are received using MAV_SEND_<command> blocks. The basic interface of the block is as follows:
- RUN – input, BOOL. Data is sent in a tick if this input is set to True.
- SENT – output, BOOL. Set to True if the RUN input is set and the data has been sent successfully.
- TgtSystemID – parameter, SHORT. Specifies the system ID of the destination node (it can be -1, ie “all” if it is not part of the message).
- TgtComponentD – parameter, SHORT. Specifies the component ID of the destination node (it can be -1, ie “uv” if it is not part of the message).
The other inputs are defined by the respective message and contain data for transmission.
1.3 Installation of driver on target device
1.3.1 Target device with OS Windows
A driver for the development tools (host) is included in the installer. The driver is not supported on a Windows target device.
1.3.2 Target device with OS linux
If the RexCore runtime software is installed on the target device, then it must be installed as described in Getting Started with the Control REXYGEN [1] The installation includes all available drivers, including MAVLinkDrv.
Following command may be used from the terminal to install the driver separately:
sudo apt-get install rex-mavlinkdrvt
Chapter 2
Integrating driver into the project
The driver is loaded into the project when the driver is added to the master file and the inputs and outputs are connected to the control algorithm and connected with the EXEC function block.
2.1 Přidání MAVLinkDrv ovladače
Two blocks has to be added to the main file to load the driver. The first of the blocks is of the MODULE type and must be connected to the Modules output of the EXEC block. The block has to be renamed to code MAVLinkDrv.
The second block is of the TIODRV type and must be linked to the Drivers output of the EXEC block in the main project file. The name of this block (MAV) must also be a prefix of all input and output signals provided by the driver followed by two underscores.
These parameters of the IODRV block have to be set:
- module – name of the module to which the driver is connected, in this case MAVLinkDrv - it is necessary to preserve the capitalization!
- classname – driver class, in this case MAVLinkDrv,
- cfgname – name of driver configuration file, např. mavlink.rio,
- factor – defines the triggering period of the driver by multiplying the tick parameter of the EXEC block.
The above parameters of the IODRV block are configured in the REXYGEN Studio program.
Chapter 3
Licensing
Several parts of the driver are based on the mavlink-router code available at https://github.com/intel/mavlink-router. The code is licensed by Apache License Version 2.0.
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by
Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is
granting the License.
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are
controlled by, or are under common control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the direction or management of such
entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this
License.
"Source" form shall mean the preferred form for making modifications, including but not limited to
software source code, documentation source, and configuration files.
"Object" form shall mean any form resulting from mechanical transformation or translation of a
Source form, including but not limited to compiled object code, generated documentation, and
conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or Object form, made available under
the License, as indicated by a copyright notice that is included in or attached to the work (an
example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or
derived from) the Work and for which the editorial revisions, annotations, elaborations, or other
modifications represent, as a whole, an original work of authorship. For the purposes of this
License, Derivative Works shall not include works that remain separable from, or merely link (or
bind by name) to the interfaces of, the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including the original version of the Work and
any modifications or additions to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal
Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition,
"submitted" means any form of electronic, verbal, or written communication sent to the Licensor or
its representatives, including but not limited to communication on electronic mailing lists, source
code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor
for the purpose of discussing and improving the Work, but excluding communication that is
conspicuously marked or otherwise designated in writing by the copyright owner as "Not a
Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a
Contribution has been received by Licensor and subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of this License, each
Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly
perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor
hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made, use, offer to sell, sell,
import, and otherwise transfer the Work, where such license applies only to those patent claims
licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by
combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If
You institute patent litigation against any entity (including a cross-claim or counterclaim in a
lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses granted to You under this License for
that Work shall terminate as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof
in any medium, with or without modifications, and in Source or Object form, provided that You meet
the following conditions:
You must give any other recipients of the Work or Derivative Works a copy of this License; and
You must cause any modified files to carry prominent notices stating that You changed the files; and
You must retain, in the Source form of any Derivative Works that You distribute, all copyright,
patent, trademark, and attribution notices from the Source form of the Work, excluding those
notices that do not pertain to any part of the Derivative Works; and
If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works
that You distribute must include a readable copy of the attribution notices contained within such
NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at
least one of the following places: within a NOTICE text file distributed as part of the Derivative
Works; within the Source form or documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and wherever such third-party notices
normally appear. The contents of the NOTICE file are for informational purposes only and do not
modify the License. You may add Your own attribution notices within Derivative Works that You
distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such
additional attribution notices cannot be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or
different license terms and conditions for use, reproduction, or distribution of Your
modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and
distribution of the Work otherwise complies with the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution
intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms
and conditions of this License, without any additional terms or conditions. Notwithstanding the
above, nothing herein shall supersede or modify the terms of any separate license agreement you may
have executed with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade names, trademarks, service
marks, or product names of the Licensor, except as required for reasonable and customary use in
describing the origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor
provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any
warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing
the Work and assume any risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory, whether in tort (including
negligence), contract, or otherwise, unless required by applicable law (such as deliberate and
grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for
damages, including any direct, indirect, special, incidental, or consequential damages of any
character arising as a result of this License or out of the use or inability to use the Work
(including but not limited to damages for loss of goodwill, work stoppage, computer failure or
malfunction, or any and all other commercial damages or losses), even if such Contributor has been
advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works
thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this License. However, in accepting
such obligations, You may act only on Your own behalf and on Your sole responsibility, not on
behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each
Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by
reason of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
Bibliography
Documentation reference number: 12481
2020 © REX Controls s.r.o., www.rexygen.com