# 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](../grpc/doc/protocol/common/index.md)
* [Platform](../grpc/doc/protocol/ui/index.md)
* [Client](../grpc/doc/protocol/client/index.md)
* [Drone](../grpc/doc/protocol/drone/index.md)
* [Application](../grpc/doc/protocol/app/index.md)

[Download](https://docs.dromt.it/static/dromt_proto.zip) _.proto_ files from definitions and generate your client for your favorite programming language.

[Python Demo](./example_grpc.md)

## 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](https://stream.dromt.it/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](https://stream.dromt.it/), 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](#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](../grpc/doc/protocol/common/index.md#common-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](../platform/media.md) 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.