gRPC Telemetry Message Service

Telemetry Messages are the primary mechanism for getting data from your robot into the cloud, and use a publish/subscribe paradigm. The Robot Automation Telemetry Message protocol runs on the telemetry-gateway service.

Protocol and Server Selection

You can request the protocol file from DroneDeploy support team. Refer to the gRPC documentation regarding how to use the gRPC tools to compile this protocol file into usable library code in your preferred language.

The telemetry message service which this protocol allows access to is provided by a gRPC server: there are two server implementations which you may be using:

• The telemetry-gateway cloud server, a part of the Robot Automation cloud platform (api2.rocos.io:443 for most regions, and used for regular cloud platform connectivity).
• An instance of the telemetry-gateway agent plugin being hosted by an agent on one of your robots (use for situations where your robots need to operate in an internet denied environment).

Setting Up a Connection

The telemetry-gateway server will only accept incoming gRPC connections which use some specific parameters, provided by way of Dial Options, Call Options, and Call Context Meta-data:

Keep-alive Parameters

Ensure that you Dial the connection using compatible keep-alive options, or the server may hang up unexpectedly:

PermitWithoutStream: true
Time:                5 sec
Timeout:             5 sec

Credentials and Authentication

If you are connecting to the telemetry-gateway cloud server, you must use a gRPC connection with a secure channel. A default set of TLS/SSL transport credentials must be provided as a Dial Option.

If you are connecting to a local telemetry-gateway instance, you should instead use the gRPC Insecure transport Dial Option.

You will need to include an appropriate JWT authentication token as a Call Option each time you make a request to the server (which you can do using the PerRPCCredentials option). Alternatively, this can be provided as a Meta-data field in the Call Context.

Context

Each request to the server must be accompanied with appropriate meta-data:

Field	Type	Description
r-cs	string	Optional for receiver methods, mandatory for sender methods. The robot callsign of the robot this request relates to.
r-p	string	The project ID of the project containing the robot in question.
authorization	string	JWT_token for authentication, found inside the agent.json configuration file.
grpc-timeout	int	Optional. This value can be used to set a deadline for the gRPC request to be completed within, after which the request will be aborted.

Receiving Telemetry

After ensuring the connection parameters are correct, you should be able to dial the telemetry-gateway server and create a new client stub TelemetryGatewayClient, upon which you can perform service requests.

First of all, you will need to call RegisterReceiver(). This takes an empty stub, and returns a stream of telemetry message objects which each include a JSON payload. The first object which is returned will contain a JSON payload which provides you a 'subscription ID' for this stream. You should record this ID as you will need to in order to subscribe to telemetry on this stream.

Regardless of any other telemetry being conveyed, the server will send an empty message object once every five seconds, so that you determine that the stream is still operating normally. You must continuously read from the incoming stream to ensure these objects are reliably received, otherwise the server will close the connection.

In order to receive actual telemetry on the stream, you should call RequestTelemetry(). This takes a TelemetryRequest structure; this structure contains a subscription ID, and an TelemetryAction to perform: you should use the subscription ID which you recorded from the incoming telemetry stream, and construct an appropriate action as follows:

Field	Value	Description
operation	"subscribe"	Subscribe to the specified topic.
	"unsubscribe"	Unsubscribe from the specified topic.
	"subscriptions"	Receive a list of current subscriptions in the returned ack.
callsigns		A list of robot callsigns to which the operation should be applied.
sources		A list of source/topic names to which the operation should be applied.

The returned Ack object will indicate the result of the operation.

Note

It's perfectly cromulent to subscribe to a source/topic which does not exist; if you subscribe to a topic which the robot is not currently being published by the robot, then the subscription will simply result in no messages being received until such a time as the robot begins to publish a message with that name.

There are two important sources which can be subscribed to:

/rocos/agent/telemetry/sources - When you subscribe to this topic, the robot will respond by sending a message which lists the available sources for each plugin of the agent, along with the JSON schema which describes the format of data for that source. Subscribing to this topic invokes some special behaviour: unlike all other topics, after the source data has been send once, the topic is unsubscribed automatically.

Warning

On Agent v1.4.0+, the source /rocos/agent/telemetry/sources no longer exists. To discover available telemetry message topics on such agents, you should instead use Services: specifically the getTelemetry() service call.

/rocos/agent/telemetry/heartbeat - This is the topic which is used to determine when a particular robot agent is online or not; receiving this message is what causes the green 'online' indicator to appear in the Robot Automation portal. You should also subscribe to this message to monitor the health of your connection to the robot.

When you no longer want to receive telemetry, you may simply close the incoming message stream (or end its context in the case of languages which support this). Any subscriptions still remaining at this point are automatically unsubscribed.

Additionally, once you have at least one source subscribed in a stream, if you send an "unsubscribe" command that would remove the last subscribed source in the stream, then the server will automatically close the stream remotely. To prevent this from happening, you should always remain subscribed to the heartbeat topic for the duration of receiving telemetry.