gRPC

Applications can open a stream to the platform via gRPC channels. This is a more convenient and efficient way to create a persistent connection than the REST API.

As shown in the figure below, the GRPC server has two endpoints: one for the drone and one for the client.

+--------+        +-------------+        +-------------+        +------------+        +----------+
|  Drone |<------>|  Drone App  |<------>| GRPC Server |<------>| Client App |<------>|  Client  |
+--------+        +-------------+        +-------------+        +------------+        +----------+

On the left side there is a drone application, which is connected to a physical drone via, e.g., a remote controller. On the right side, instead, there is a client application that is used by a client (e.g., a remote user) to interact with the drone. The GRPC server, thus, is a bridge between a drone and a client.

Drone applications are responsible for sending metrics, media, and flight logs to the GRPC server, which forwards them to the client application. Similarly, client applications send commands for real-time control or predefined flight plans.

API Reference

• Common

• Platform

• Client

• Drone

• Application

Download .proto files from definitions and generate your client for your favorite programming language.

Python Demo

Authentication

Applications need to connect to Dromt’s GRPC server and present a valid client certificate. Drone and Client applications need to connect to different endpoints and use different credentials.

Drone

A drone application needs to connect to drone.grpc.dromt.it:443. A connection identifies a specific drone of the fleet. The web interface provides certificates for each drone, which can be used by the drone application when connecting to the GRPC server.

After connecting to the GRPC server, the drone application needs to register a session using the Register() function in the Streamer service of drone.proto. This function needs a DroneSession object as parameter. By passing an empty DroneSession, the GPRC server will create a new session and return a DroneSession object with the session ID stored in the id field. Optionally, the drone application can also restore an existing session by setting the same ID in DroneSession.

Client

A client application needs to connect to client.grpc.dromt.it:443. A connection identifies a specific user of the web interface, which provides a user certificate downloadable from the menu in the top right corner.

After connecting to the GRPC server, the client application needs to register a session using the Register() function in the Streamer service of client.proto. This function needs a ClientSession object as parameter. By passing an empty ClientSession, the GPRC server will create a new session and return a ClientSession object with the session ID stored in the id field. Optionally, the client application can also restore an existing session by setting the same ID in ClientSession.

Opening a GRPC stream

Drone and client applications communicate with each other by sending DroneData and ClientData objects respectively. This is achieved by calling the Stream() function from the respective Streamer. At the same time, Stream() is used to receive ClientData and DroneData objects, respectively.

See the API reference for more details on these data structures.

Managing media

Our API allows to get media from a connected drone via a DownloadMedia command. This command will attempt at fetching all (or a subset of) media from the drone’s internal memory. Check the specifics of DownloadMedia for more details.

By default, the task of downloading media from the drone is entirely managed by the server, with the client that does not have to perform any additional operations except sending the DownloadMedia command. The media will be later made available in our platform for downloading and/or processing.

However, the client can also manage the media autonomously by setting the upload_to_client boolean to true in DownloadMedia. In this case, our platform will not store nor process the downloaded media. This can be useful if, for example, the client has their own image processing pipeline, or simply because they want to store their media locally. See below for more instructions.

The general flow of the media retrieval from a drone is the following:

1. The client sends a DownloadMedia message to the drone application

2. The drone application sends a MediaUpload message, containing a Request to upload a specific media (e.g., a photo or a video)

3. The server responds with a MediaUploadResponse message, containing a unique ID of the media and an URL

4. The drone application downloads the media from drone and uploads it via a HTTP PUT to the URL received previously

5. The drone application completes the upload by sending a MediaUpload message, containing an appropriate Result

6. If there are other media to upload, go back to point 2

If the client wants to manage the media upload independently (i.e., if upload_to_client in DownloadMedia was set to true), they can do so by providing their own HTTP endpoints. In this case, the client should perform step 3 above in place of the server. Additionally, the MediaUpload response in step 5 will not be processed by the server, but only forwarded to the client.