Connecting to Systems (Vehicles)

The MAVSDK allows you to connect to multiple vehicles attached to the local WiFi network and/or via serial ports.

In order to detect vehicles you must first specify the communication ports that the SDK will monitor for new systems. Once monitoring a port, the SDK will automatically detect connected vehicles, add them to its collection, and notify registered users of connection and disconnection events.

Monitoring a Port

Specify the port(s) to watch using one of the (synchronous) connection methods: add_any_connection(), add_udp_connection(), add_tcp_connection() or add_serial_connection(). All the methods are used similarly, and return immediately with a ConnectionResult indicating whether they succeeded.

The add_any_connection() method can be used to set up monitoring for any of the supported port types (while the other methods set up specific connection types). The connection details are specified using the string formats shown below:

The code snippet below shows how to set up monitoring with add_any_connection():

Mavsdk dc;
std::string connection_url="udp://0.0.0.0:14540";
ConnectionResult connection_result = dc.add_any_connection(connection_url);
ASSERT_EQ(connection_result,ConnectionResult::SUCCESS)

The connection string used above (udp://0.0.0.0:14540) is to the standard PX4 broadcast UDP port for off-board APIs (14540). This is the normal/most common way for offboard APIs to connect to PX4 over WiFi.

The SDK also provides the connection_result_str() method, which you can use to create a human-readable string for the ConnectionResult. The code fragment below shows how you might print the string for the preceding code fragment to the console:

std::cout << "Connection string: " << connection_result_str(connection_result) << std::endl;

Register for System-Detection Notifications

The SDK monitors any added communication ports for new systems, which are distinguished by vehicle UUID. Clients can register for notification when new systems are discovered using register_on_discover(), and for systems timing out (no longer connected) using register_on_timeout().

The methods are used in the same way, and invoke a callback function with the UUID of the system that was discovered/disconnected. This UUID can then be used to get a System object for managing the associated vehicle (see Accessing Systems below).

If a system does not have a UUID then Mavsdk will instead use its MAVLink system ID (a number in the range of 1 to 255). On a properly configured MAVLink network this will be unique.

The code fragment below shows how to register a callback (in this case the callback is a lambda function that just prints the UUID value to standard cout).

Mavsdk dc;
... //add ports
dc.register_on_discover([](uint64_t uuid) {
    std::cout << "Discovered system with UUID: " << uuid << std::endl;
});

Iterating all Systems

You can iterate all system UUIDs that have been detected by Mavsdk (since it was started, over all communication ports) using the system_uuids() method. This returns a vector of UUID values, from which you can get System objects that are used to manage vehicles.

The following code fragment shows how to iterate through the UUIDs (in this case, just printing them to standard cout).

//Iterate through detected systems
std::vector<uint64_t> system_vector = dc.system_uuids();
for ( auto i = system_vector.begin(); i != system_vector.end(); i++ ) {
    std::cout << *i << std::endl;
}

The vector contains UUIDs for all systems detected by Mavsdk, including those that may no longer be connected. You can use Mavsdk::is_connected(uint64_t) to determine if the system with a particular UUID is connected or not. If you're only expecting a single connection, then you can use the parameterless is_connected() method.

Accessing Systems

Once Mavsdk has provided you with a vehicle UUID you can use the Mavsdk::system() method to get its associated System object:

Mavsdk dc;
//... 
//Use UUID named uuid to get the associated System
System &system = dc.system(uuid);

If you know that there is only one connected system you can instead call system() without any UUID. This will return the first system detected, or a null System if none have been discovered.

System &system = dc.system()

The System is used by the MAVSDK plugin classes to query and control the vehicle. For more information see Using Plugins (and the other guide topics).