gRPC Control Message Service

Control Messages are a low-level mechanism for sending data from the cloud to an individual robot, using a push message paradigm. The Robot Automation Control Message protocol runs on the control-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 control 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 conker 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 teleop-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 conker 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 conker 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 teleop-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	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 on the robot.
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.

Sending Controls

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

There are multiple control methods exposed by the service, which differ with regard to whether are unary or stream based, and whether they return an ack to confirm successful delivery, however they all operate in the same manner: the call takes a ControlMessage object to be delivered:

Field	Type	Description
destination	string	The topic URL to where the message should be delivered; the choice of robot is determined by the Call Context. For example: "/ros/cmd_vel"
payload	byte[]	Byte array containing the JSON object which should be delivered.
txid	string	A unique string identifier which allows an ack confirming delivery to be returned.
meta	map<string, string>	String key value pairs containing any additional meta-data which may be required. For instance, ROS destinations need to document the ROS message type as the key "ros.type".

In the case of requests which should return an ack, the ack contains:

Field	Type	Description
success	bool	Whether or not the control message was successfully delivered.
state	string	The state which the ack relates to: for example, control message may fail to be delivered due to a network problem, or might get all the way to the agent but contain a malformed payload. Successful end-to-end deliveries will report success from the stage "final".
message	string	Status or error message.
txid	string	A unique string identified which allows the ack to be matched against the ControlMessage which it relates to.
seq	uint32	A monotonically increasing number used internally.