mavlinkdialect

Parse and store MAVLink dialect XML

Description

The mavlinkdialect object parses and stores message and enum definitions extracted from a MAVLink message definition file (.xml). The message definition files define the messages supported for this specific dialect. The structure of the message definitions is defined by the MAVLink message protocol.

Note

This object requires you to install the UAV Library for Robotics System Toolbox™. To install add-ons, use roboticsAddons and select the desired add-on.

Creation

Syntax

dialect = mavlinkdialect("common.xml")
dialect = mavlinkdialect(dialectXML)
dialect = mavlinkdialect(dialectXML,version)

Description

example

dialect = mavlinkdialect("common.xml") creates a MAVLink dialect using the common.xml file for standard MAVLink messages.

dialect = mavlinkdialect(dialectXML) specifies the XML file for parsing the message definitions. The input sets the DialectXML property.

dialect = mavlinkdialect(dialectXML,version) additionally specifies the MAVLink protocol version. The inputs set the DialectXML and Version properties, respectively.

Properties

expand all

MAVLink dialect name, specified as a string. This name is based on the XML file name.

Example: "ardupilotmega"

Data Types: char | string

MAVLink protocol version, specified as either 1 or 2.

Data Types: double

Object Functions

createcmdCreate MAVLink command message
createmsgCreate MAVLink message
deserializemsgDeserialize MAVLink message from binary buffer
msginfoMessage definition for message ID
enuminfoEnum definition for enum ID
enum2numEnum value for given entry
num2enumEnum entry for given value

Examples

collapse all

This example shows how to parse a MAVLink XML file and create messages and commands from the definitions.

NOTE: This example requires you to install the UAV Library for Robotics System Toolbox®. Call roboticsAddons to open the Add-ons Explorer and install the library.

Parse and store the MAVLink dialect XML. Specify the XML path. The default "common.xml" dialect is provided. This XML file contains all the message and enum definitions.

dialect = mavlinkdialect("common.xml");

Create a MAVLink command from the MAV_CMD enum, which is an enum of MAVLink commands to send to the UAV. Specify the setting as "int" or "long", and the type as an integer or string.

cmdMsg = createcmd(dialect,"long",22)
cmdMsg = struct with fields:
      MsgID: 76
    Payload: [1x1 struct]

Verify the command name using num2enum. Command 22 is a take-off command for the UAV. You can convert back to an ID using enum2num. Your dialect can contain many different enums with different names and IDs.

cmdName = num2enum(dialect,"MAV_CMD",22)
cmdName = 
"MAV_CMD_NAV_TAKEOFF"
cmdID = enum2num(dialect,"MAV_CMD",cmdName)
cmdID = 22

Use enuminfo to view the table of the MAV_CMD enum entires.

info = enuminfo(dialect,"MAV_CMD");
info.Entries{:}
ans=133×3 table
                    Name                     Value                                                                                                                                                                              Description                                                                                                                                                                          
    _____________________________________    _____    _______________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________

    "MAV_CMD_NAV_WAYPOINT"                    16      "Navigate to waypoint."                                                                                                                                                                                                                                                                                                                                        
    "MAV_CMD_NAV_LOITER_UNLIM"                17      "Loiter around this waypoint an unlimited amount of time"                                                                                                                                                                                                                                                                                                      
    "MAV_CMD_NAV_LOITER_TURNS"                18      "Loiter around this waypoint for X turns"                                                                                                                                                                                                                                                                                                                      
    "MAV_CMD_NAV_LOITER_TIME"                 19      "Loiter around this waypoint for X seconds"                                                                                                                                                                                                                                                                                                                    
    "MAV_CMD_NAV_RETURN_TO_LAUNCH"            20      "Return to launch location"                                                                                                                                                                                                                                                                                                                                    
    "MAV_CMD_NAV_LAND"                        21      "Land at location"                                                                                                                                                                                                                                                                                                                                             
    "MAV_CMD_NAV_TAKEOFF"                     22      "Takeoff from ground / hand"                                                                                                                                                                                                                                                                                                                                   
    "MAV_CMD_NAV_LAND_LOCAL"                  23      "Land at local position (local frame only)"                                                                                                                                                                                                                                                                                                                    
    "MAV_CMD_NAV_TAKEOFF_LOCAL"               24      "Takeoff from local position (local frame only)"                                                                                                                                                                                                                                                                                                               
    "MAV_CMD_NAV_FOLLOW"                      25      "Vehicle following, i.e. this waypoint represents the position of a moving vehicle"                                                                                                                                                                                                                                                                            
    "MAV_CMD_NAV_CONTINUE_AND_CHANGE_ALT"     30      "Continue on the current course and climb/descend to specified altitude. When the altitude is reached continue to the next command (i.e., don't proceed to the next command until the desired altitude is reached."                                                                                                                                            
    "MAV_CMD_NAV_LOITER_TO_ALT"               31      "Begin loiter at the specified Latitude and Longitude. If Lat=Lon=0, then loiter at the current position. Don't consider the navigation command complete (don't leave loiter) until the altitude has been reached. Additionally, if the Heading Required parameter is non-zero the aircraft will not leave the loiter until heading toward the next waypoint. "
    "MAV_CMD_DO_FOLLOW"                       32      "Being following a target"                                                                                                                                                                                                                                                                                                                                     
    "MAV_CMD_DO_FOLLOW_REPOSITION"            33      "Reposition the MAV after a follow target command has been sent"                                                                                                                                                                                                                                                                                               
    "MAV_CMD_DO_ORBIT"                        34      "Start orbiting on the circumference of a circle defined by the parameters. Setting any value NaN results in using defaults."                                                                                                                                                                                                                                  
    "MAV_CMD_NAV_ROI"                         80      "Sets the region of interest (ROI) for a sensor set or the vehicle itself. This can then be used by the vehicles control system to control the vehicle attitude and the attitude of various sensors such as cameras."                                                                                                                                          
      ⋮

Query the dialect for a specific message ID. Create a blank MAVLink message using the message ID.

info = msginfo(dialect,"HEARTBEAT")
info=1×4 table
    MessageID    MessageName                                                                                                                                Description                                                                                                                                  Fields   
    _________    ___________    ___________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________    ___________

        0        "HEARTBEAT"    "The heartbeat message shows that a system is present and responding. The type of the MAV and Autopilot hardware allow the receiving system to treat further messages from this system appropriate (e.g. by laying out the user interface based on the autopilot)."    [6x6 table]

msg = createmsg(dialect,info.MessageID);

Introduced in R2019a