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 core 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 can forward UAV state data via UDP to RflySim3D for 3D visualization rendering. 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 the module outputs flight state data from all UAVs back to the Simulink-side control algorithms. In real-flight scenarios, when RealflyMode is enabled, the module can 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 configuration rules 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; the IP address of the host running CopterSim can be customized.
3. Port Rules: Base port is 15500 + 2 * CopterID; each drone's port increments by 2 with increasing CopterID, and the same port is used for both receiving and transmitting.

4. Supports three MAVLink modes: Mavlink_Full, Mavlink_Simple, and Mavlink_Real; different modes correspond 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 module, outputting a state bus containing information such as position, mode, and battery level
RflySwarmJoystick	Provides joystick control input for multi-UAV swarm simulation, usable in conjunction with this module
RflySimVehicleBusCreator	Generates a UAV control bus conforming to the RflySim platform specification, which can serve as input to this module
UAVWaypointFollower	Multi-UAV waypoint tracking controller; its output control commands can be connected to this module for transmission to UAVs

Usage Examples

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

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

Please view Readme.pdf at the above path for complete example instructions and operational steps.

Notes and Frequently Asked Questions

• Initialization Order: In simulation scenarios, CopterSim and the corresponding flight controller simulation program must be started first, followed by the Simulink simulation; otherwise, the module cannot establish a UDP connection and will lose state data. In real-flight scenarios, ensure all UAVs are powered on, connected to the network, and have static IPs configured before starting the Simulink simulation.
• Sample Time Matching: The recommended module operating frequency is 30 Hz. Set the module sample time to 1/30, or set the sample time to -1 and configure the Simulink global simulation frequency to 30 Hz. If the model contains multiple tasks with different frequencies, the input and output data of this module must be synchronously sampled; otherwise, a Simulink rate detection error will be triggered.
• CopterID Configuration Rules: For both simulation and real-flight scenarios, non-consecutive UAV IDs must be input as a vector sorted in ascending order, e.g., [1 3 5]. Do not input out of order or with duplicates, as this will cause IP and port matching errors and prevent communication.
• RealflyMode Configuration Verification: Do not check RealflyMode in software-in-the-loop simulation scenarios; it must be checked in real-flight scenarios. This option directly changes the IP and port allocation rules; incorrect selection will lead to communication failure.
• Real-Flight IP and Port Rules: In real-flight mode, if UAV IPs and ports follow a contiguous rule, all UAVs must be pre-configured with the base IP incremented by 1 and the base port incremented by 1. For non-consecutive numbering, ensure the input CopterID list corresponds one-to-one in order with the IP list; otherwise, control signals will be misaligned.
• Output Data Usage: The module's raw output is a 28-dimensional MAVLink decoded vector. It must be parsed using the real_data_decoder module before use. After parsing, the output is in bus format, allowing direct extraction of required state data such as position, attitude, mode, and battery level via the Simulink bus selector tool.
• Firewall and Network Restrictions: In cross-host simulation or real-flight scenarios, disable the firewall on both the host and UAV sides, or add rules to allow UDP communication ports; otherwise, data will be blocked and cannot be received.
• UDP Mode Selection: It is recommended to uniformly use the Mavlink_Real mode to adapt to RflySim swarm communication. Different modes have different packet lengths; incorrect selection will cause decoding failure and abnormal state output.
• GPS Origin Setting: If global GPS coordinates are required, set the correct GPS origin parameters according to the actual takeoff site; otherwise, the global position output will have deviations. In simulation scenarios, the default value is sufficient.

Changelog

• v4.10 (2024-05-03): Initial version release, supporting multi-UAV MAVLink UDP communication in both simulation and real-flight modes, supporting non-consecutive UAV ID configuration, and providing three MAVLink communication mode options.