MavDataRec Interface Documentation

Introduction

Overview: This file defines the MavDataRec class, used to record and store MAVLink protocol data generated during drone flight operations.

MAVLink is a lightweight communication protocol widely adopted in the drone industry. During drone simulation and real-world flight missions, a large volume of communication data—including flight states, control commands, and sensor readings—is generated. Such data is crucial for mission reproduction, algorithm debugging, and performance analysis. This module belongs to the formation control module group of RflySimSDK and is designed for drone simulation scenarios within the RflySim platform. It enables users to retain all MAVLink communication data generated during simulation flights, facilitating subsequent offline analysis and algorithm iteration validation.

Quick Start

The following example records three types of messages for drone 1 with an established MAVLink loop, and reads the ring buffer for each message via msgDic.

Reference example: [RflySim installation path]\RflySimAPIs\7.RflySimPHM\0.ApiExps\e11_moder_ver

import time

import MavDataRec
import PX4MavCtrlV4 as PX4MavCtrl


mav = PX4MavCtrl.PX4MavCtrler(1)
mav.InitMavLoop()
time.sleep(0.5)

recorder = MavDataRec.MavDataRec(mav)
recorder.startRecMsg(
    ["SERVO_OUTPUT_RAW", "VIBRATION", "HIGHRES_IMU"],
    [5, 3, 19],
)

time.sleep(10)
for messageName, messages in recorder.msgDic.items():
    print(messageName, "Cache count:", len(messages))

recorder.stopRecMsg()

Environment and Dependencies

• Python Environment: >= 3.8.10
• Dependencies: threading
• Prerequisites: Before calling this interface, RflySimSDK must be initialized and imported.

Core Interface Description

The module MavDataRec.py includes configuration variables, helper functions, and the core business class.

Global Constants and Enumerations

This section lists all globally accessible constants and enumerations defined in the module.

Standalone Constants

None

---

Global/Standalone Functions

None

---

MavDataRec Class

MAVLink message data recorder class, used to record specified types of MAVLink messages in RflySim drone simulations. Supports customizable message types and cache lengths, commonly used in offline flight data analysis and data collection for PHM (Prognostics and Health Management) applications.

__init__(self, mav)

Function Description: Initializes an MAVLink data recording instance and binds it to the MAVLink communication object.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
mav	object	Yes	-	An established MAVLink communication object used to receive drone messages

Return Value (Returns):

• MavDataRec instance object

Exceptions (Raises): None

---

startRecMsg(NameList=['HIGHRES_IMU'], LenList=[10])

Function Description: Starts recording specified MAVLink messages from the provided list, setting the cache length for each message type.
Parameters (Args):

Parameter Name	Type	Required	Default Value	Description
NameList	list[str]	No	['HIGHRES_IMU']	List of MAVLink message names to record; defaults to high-precision IMU messages
LenList	list[int]	No	[10]	Corresponding cache lengths for each message type, i.e., the maximum number of latest messages to store; must match the length of NameList

Return Value (Returns):

• None

Exceptions (Raises): None

---

stopRecMsg()

Function Description: Stops all ongoing MAVLink message recordings and clears all registered recording entries.
Return Value (Returns):

• None

Exceptions (Raises): None

---

getMavMsg()

Function Description: Retrieves all currently cached recorded MAVLink message data.
Return Value (Returns):

• dict: Keys are message names; values are lists of corresponding cached message data

Exceptions (Raises): None

Example:

from RflySimSDK.phm import MavDataRec
# Bind an established MAVLink connection object 'mav'
recorder = MavDataRec(mav)
# Start recording IMU and attitude messages, caching 100 entries each
recorder.startRecMsg(NameList=['HIGHRES_IMU', 'ATTITUDE'], LenList=[100, 100])
# Retrieve recorded data during flight
recorded_data = recorder.getMavMsg()
imu_data = recorded_data['HIGHRES_IMU']
# Stop recording
recorder.stopRecMsg()

---

Advanced Usage Examples

The following example periodically reads the motor, vibration, and IMU caches while the recording thread is running; these data can be passed to a health assessment algorithm for processing.

Reference example: [RflySim installation path]\RflySimAPIs\7.RflySimPHM\0.ApiExps\e11_moder_ver

import time

import MavDataRec
import PX4MavCtrlV4 as PX4MavCtrl


mav = PX4MavCtrl.PX4MavCtrler(1)
mav.InitMavLoop()

recorder = MavDataRec.MavDataRec(mav)
recorder.startRecMsg(
    ["SERVO_OUTPUT_RAW", "VIBRATION", "HIGHRES_IMU"],
    [5, 3, 19],
)

try:
    for _ in range(20):
        motor = list(recorder.msgDic["SERVO_OUTPUT_RAW"])
        vibration = list(recorder.msgDic["VIBRATION"])
        imu = list(recorder.msgDic["HIGHRES_IMU"])
        print(
            "motor:", len(motor),
            "vibration:", len(vibration),
            "imu:", len(imu),
        )
        time.sleep(0.5)
finally:
    recorder.stopRecMsg()

Notes and Pitfall Avoidance Guide

• Duplicate Start Check Before Initialization: Prior to calling startRecMsg(), verify that the current recording task is not already active. Repeated invocation will cause message data to accumulate redundantly in memory, resulting in duplicated segments in the final retrieved data, consuming extra memory and interfering with subsequent analysis.

• Timing Constraint for Message Retrieval: getMavMsg() must be called after startRecMsg() and before stopRecMsg(). Invoking it before the task starts or after it has stopped will return an empty list or only incomplete, partially cached data, preventing acquisition of the complete recorded dataset.

• Resource Conflict Avoidance for Multiple Instances: Creating multiple MavDataRec instances for the same drone and concurrently calling startRecMsg() on them will cause competition for MAVLink port data reads, leading each instance to capture only fragmented, incomplete message subsets. It is recommended to maintain only one active recording instance per drone at any given time.

• Memory Management for Long-Duration Recording: For flight data recordings exceeding 10 minutes, it is advisable to segment the recording process by repeatedly calling startRecMsg() and stopRecMsg() and storing messages in segments. This avoids continuous in-memory caching of all messages, which can cause steadily increasing memory usage, leading to application sluggishness or even out-of-memory errors.

Changelog

• 2024-08-02: chore: Added code comments for HTML-format API generation
• 2024-07-18: fix: Updated API homepage index
• 2023-10-23: feat: Added required interface files