RflyUdpMavlink Module Documentation

Toolbox: RflySim Swarm

Introduction

One-sentence description: Implements MAVLink data transmission and reception over UDP protocol, supporting simultaneous simulation or real-flight control of multiple UAVs; it serves as the core communication module connecting MATLAB/Simulink with underlying flight controllers and visualization in RflySim swarm development.

This module is a foundational component of the RflySim Swarm toolchain, responsible for MAVLink protocol data exchange between user-defined control algorithms in Simulink and the underlying flight controller (either simulated PX4 or real PX4 hardware). It supports both multi-UAV software-in-the-loop (SITL) simulation and multi-UAV real-flight control. In simulation scenarios, the module establishes UDP communication following RflySim platform defaults, interfacing with CopterSim simulation models and PX4 software flight controllers. Simultaneously, it forwards UAV state data via UDP to RflySim3D for 3D visualization. Control commands generated by user-developed swarm control algorithms are encapsulated into MAVLink packets by this module and sent to each UAV’s flight controller, while flight state data from all UAVs is output back to the Simulink-side control algorithms. In real-flight scenarios, enabling RealflyMode allows the module to directly communicate with multiple physical UAVs’ PX4 flight controllers over the local network, based on configured static IP addresses and port rules, thereby enabling Simulink-side algorithms to directly control real UAV swarms.

The raw state data output by this module must be parsed using the real_data_decoder module before use. After parsing, it yields various state information such as UAV position, attitude, flight mode, and battery level, enabling users to quickly extract required data for developing swarm control algorithms. It also supports flexible configuration of both continuously and non-continuously numbered UAV swarms, accommodating diverse simulation and real-flight scenario requirements.

Port Descriptions

Input Ports (Inputs)

Port Name	Data Type	Dimension	Description
ActuatorOutputs	double	N×1	Control output signals for N UAVs; total length is 16*CopterNum, with each UAV corresponding to a 16-dimensional actuator control signal

When configured for N UAVs, the input is a concatenated 1D signal whose dimension dynamically scales with the number of UAVs.

Output Ports (Outputs)

Port Name	Data Type	Dimension	Description
VehicleStates	double	N×28	State feedback data for N UAVs; each UAV corresponds to 28-dimensional state information, requiring use with the real_data_decoder module for parsing

The output is a concatenation of state data from N UAVs, with dimension dynamically scaling according to the configured number of UAVs.

Parameter Configuration (Parameters)

The Mask dialog box, opened by double-clicking the module, allows configuration of the following parameters:

Parameter Name	Type	Default Value	Available Values/Range	Description
Vehicle number or CopterID list	double vector	1	Any vector of positive integers	UAV ID list; vector length indicates the number of UAVs, and vector elements specify each UAV’s CopterID
Sample Time	double	1/30	>0 or -1	Module sample time; set to -1 to inherit the global simulation sample rate
RealflyMode	bool	false	true/false	Enables real-flight mode; when checked, real-flight IP/port configuration rules are applied
Target IP Address	string	127.0.0.1	Valid IPv4 address string	Target IP address of the host running CopterSim in simulation mode
GPS Orin	double vector	[0 0 0]	Any 3D vector	Global coordinate system GPS origin; format: [latitude (°), longitude (°), altitude (m)]
Udp Mode	enum	Mavlink_Real	Mavlink_Full / Mavlink_Simple / Mavlink_Real	MAVLink communication mode; different modes correspond to different packet sizes
Base IP Address	string	192.168.151.101	Valid IPv4 address string; multiple IPs separated by commas for non-consecutive UAVs	Base IP address for UAVs in real-flight mode; for consecutive IPs, the address increments based on the UAV ID
Base Udp Port	int	15501	1024~65535	Base UDP port for UAVs in real-flight mode; port increments based on UAV ID

Parameter Setting Notes

Vehicle number or CopterID list

Specifies the number and IDs of UAVs controlled by this module: when UAV IDs are consecutive, it can be abbreviated as [1:5] to indicate control of UAVs numbered 1 through 5; for non-consecutive IDs, directly specify the ID vector, e.g., [1 3 5 7]. The vector length equals the total number of controlled UAVs.

Sample Time

Recommended setting is 1/30, corresponding to a 30 Hz communication and control frequency. Alternatively, set to -1 to inherit the global simulation sample rate of the Simulink model. If the model contains tasks operating at different frequencies, explicitly setting this module’s sample time is recommended to avoid Simulink errors.

RealflyMode

Do not check this option during software-in-the-loop simulation; it must be checked when controlling real UAVs in flight. When checked, the module switches to real-flight mode IP and port configuration rules.

Udp Mode

The three communication modes differ in payload size: Mavlink_Full transmits full flight controller data packets, Mavlink_Simple transmits only core state information, and Mavlink_Real matches the data packet format of real PX4 flight controllers. For real-flight scenarios, Mavlink_Real is recommended.

Simulation Mode Configuration (RealflyMode unchecked)

In simulation mode, the default IP is 127.0.0.1, indicating connection to CopterSim running on the local machine. Ports automatically increment according to the rule: the port number for the N-th UAV is 15500 + CopterID. Manual configuration is unnecessary. The GPS origin only needs modification when using global GPS coordinates; otherwise, the default value suffices.

Real-Flight Mode Configuration (RealflyMode checked)

Real-flight mode requires all UAVs to be pre-configured with static IPs and ports, following the base value increment rule based on UAV ID: for example, with a base IP of 192.168.151.101 and base port of 15501, a UAV with CopterID 5 will automatically use IP 192.168.151.105 and port 15505. For non-consecutive UAV IDs, multiple IPs can be directly entered, separated by commas, while the corresponding IDs are listed in Vehicle number or CopterID list.

Block Characteristics

Feature	Value
Supported Data Types	double, single
Direct Feedthrough	Yes
Sample Time	Discrete
Code Generation Support	No

Data Communication Protocol

This block communicates using the MAVLink protocol over UDP. Port and IP configurations are categorized based on the operational mode as follows:

1. Non-Real-Flight Mode (Simulation Mode, RealflyMode unchecked)
2. Target IP: Default is 127.0.0.1; configurable to the IP address of the host running CopterSim.
3. Port Rules: Base port is 15500 + 2 * CopterID. Each drone’s port increments by 2 with increasing CopterID; the same port is used for both receiving and transmitting.

4. Supports three MAVLink modes: Mavlink_Full, Mavlink_Simple, and Mavlink_Real, each corresponding to different packet sizes.

5. Real-Flight Mode (RealflyMode checked)

6. IP Rules: Supports both contiguous and non-contiguous IP configurations. The base IP serves as the starting address; under contiguous IP rules, each drone’s IP increments the last octet by 1. For non-contiguous IPs, multiple IPs can be entered, separated by commas.
7. Port Rules: Base port is the configured Base Udp Port. Each drone’s port equals the base port plus (CopterID - Start CopterID), i.e., increments by 1 with increasing CopterID.
8. Communication Content: Transmits UAV control commands and flight status data in MAVLink format.

Related Blocks

Block Name	Description
real_data_decoder	Decodes the 28-dimensional state vector output by this block into a state bus containing information such as position, mode, and battery level.
RflySwarmJoystick	Provides joystick control input for multi-UAV swarm simulation; can be used in conjunction with this block.
RflySimVehicleBusCreator	Generates a UAV control bus compliant with RflySim platform specifications; can serve as input to this block.
UAVWaypointFollower	A multi-UAV waypoint tracking controller whose output control commands can be fed into this block for transmission to the UAVs.

Usage Example

For relevant usage examples, please refer to the following path:

[RflySim installation path]/RflySimAPIs/10.RflySimSwarm/1.BasicExps/e4_RflyUdpSwarmExp/Readme.pdf

Please refer to Readme.pdf in the above path for complete example descriptions and operational procedures.

Notes and Frequently Asked Questions

• Initialization Sequence: In simulation scenarios, CopterSim and the corresponding flight controller simulation must be started first, followed by the Simulink simulation; otherwise, the module will fail to establish UDP connections and lose state data. In real-flight scenarios, ensure all drones have completed power-on, network entry, and static IP configuration before launching the Simulink simulation.
• Sample Time Matching: The recommended module operating frequency is 30 Hz. Set the module’s sample time to 1/30, or set it to -1 and configure the Simulink global simulation frequency to 30 Hz. If the model contains multiple tasks operating at different frequencies, synchronized sampling must be applied to the module’s input and output data; otherwise, Simulink rate-detection errors will be triggered.
• CopterID Configuration Rules: For both simulation and real-flight scenarios, non-consecutive drone IDs must be entered as a vector in ascending order, e.g., [1 3 5]. Disorder or duplication of IDs will cause IP and port mismatching, preventing communication establishment.
• RealflyMode Configuration Verification: In software-in-the-loop (SITL) simulations, RealflyMode must not be enabled. In real-flight scenarios, RealflyMode must be enabled. This option directly affects IP and port allocation rules; incorrect selection will lead to communication failure.
• Real-Flight IP and Port Rules: In real-flight mode, if drone IPs and ports follow a consecutive rule, all drones must be pre-configured to increment the base IP and base port by 1. For non-consecutive numbering, the order of the input CopterID list must strictly correspond to the order of the IP list; otherwise, control signals will be misaligned.
• Output Data Usage: The module’s raw output is a 28-dimensional MAVLink-decoded vector, which must be processed by the real_data_decoder module before use. After decoding, the output is in bus format, allowing direct extraction of required state data (e.g., position, attitude, flight mode, battery level) via Simulink bus selector tools.
• Firewall and Network Restrictions: In cross-host simulations or real-flight scenarios, firewalls on both the host and drone sides must be disabled, or UDP communication ports must be explicitly allowed; otherwise, data reception will be blocked.
• UDP Mode Selection: The Mavlink_Real mode is recommended for RflySim cluster communication. Different modes yield varying packet lengths; incorrect selection will cause decoding failure and abnormal state outputs.
• GPS Origin Setting: If global GPS coordinates are required, the correct GPS origin parameters must be set according to the actual takeoff location; otherwise, global position outputs will be inaccurate. In simulation scenarios, default values can be used.

Changelog

• v4.10 (2024-05-03): Initial release. Supports MAVLink UDP communication for multi-drone systems in both simulation and real-flight modes, allows non-consecutive drone ID configuration, and provides three MAVLink communication mode options.