gRPC Command Service

Commands are a high-level abstraction for instructing an individual robot to perform an action, using a request/response message paradigm.

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 command service which this protocol allows access to is provided by a gRPC server: there is one server implementation which you will be using:

• The commands cloud server, named rambo. It's part of the Robot Automation cloud platform (api2.rocos.io:443 for most regions).

Setting Up a Connection

The command 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 rambo 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.

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.

Service Structure

There are two different gRPC services exposed by the rambo proto. One, CommandReceiver is for registering a Command Receiver, which will be the DroneDeploy Agent in most cases. The other, Command, is for calling/invoking a Command from a client; this is the one you will be using.

Creating Command Definitions

The protocol is only able to invoke Commands which the target robot already holds a corresponding Command Definition for. The protocol cannot be used to create or update Command Definitions, so you need to set these up in advance; refer to Commands for details.

Sending/Invoking Commands

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

To instruct a robot to perform a Command, call CallCommand(). You will need to pass this method a CommandRequest structure which specifies the target Robot and Command Definition, as well as the values for parameters to be used in the Command itself:

CommandRequest

Field	Type	Description
txid	string	A globally unique ID which can be used to identify this particular operation, allowing responses to be distinguished. We recommend generating a random byte sequence of no less than 64bits. If you leave this field blank, the server will generate a suitable value itself, but this is not recommended, because it may make it difficult to correctly handle multiple Command responses.
uri	RocosUri	A object encapsulating a data URI which describes the destination where the command should be invoked. For example: {<br/>Project: "MyProject", // The project ID of the project. Callsign: "MyRobot", // The robot's callsign. Component: "command-executor", // Always this. Topic: "MyCommand", // Command ID as defined in portal.<br/>}
parameters	map<string,string>	A set of key:value pairs defining the values of the input parameters accepted by the target Command (per its Command Definition) to be used when executing this command.
resLevel	enum	The level of response which the invoker is expecting from the the execution (this is basically equivalent to verbosity): ALL = 0; Receive transmission acknowledgements, Command return values, and Command result. RETURN_AND_RESULT = 1; Receive Command return values and Command result. RESULT_ONLY = 2; Receive Command result only. NONE = 3; Receive no response at all (fire and forget).
deadlineMs	uint64	The Unix timestamp, in ms, by which time the Command must have completed execution: if this time is reached before the destination robot has received the request, the robot will not begin to execute the Command; if the time is reached while the Command is being executed, the robot will attempt to abort the Command.
context	map	Reserved for future usage.

The CallCommand method returns a stream of ResponseChannelMessage messages back to from the server, which inform the caller about the status of the Command. Each response message may hold one of three possible response types:

CommandResponse

Field	Type	Description
txid	string	The unique transaction id of the corresponding Command request.
ack	Ack	A simple acknowledgement of the Command's progress through routing, delivery and execution.
return	CommandReturn	A message containing data which is being returned by the execution of the Command itself.
result	CommandResult	A single message indicating that the execution of the Command has completed, and the reason the execution ended.

Based on the value of resLevel passed with the request, some of these response messages may not be transmitted.

Command Response Types

Ack

Ack is used to provide simple acknowledgement that the Command request has reached different stages of the routing/delivery/execution pathway, and that execution is ongoing.

Field	Type	Description
stage	enum	Indicates which part of the delivery/execution pipeline is acknowledging the request. AGENT = 0; From the agent itself. CLOUD_GATEWAY = 1; From the cloud gateway server. DEVICE_GATEWAY = 2; Reserved for future use.
status	enum	Indicates the status of the acknowledgement. RECEIVED = 0; The Command has been received and processed. QUEUED = 1; The Command has been queued but is not being executed yet. PROGRESS = 2; Execution of the Command has begun and the Command is in progress; the Agent may send this message multiple times, so as to periodically keep the caller informed that a long running Command is still in progress.
message	string	In the case of PROGRESS messages, the Command may include a brief text string to indicate how it is progressing.

CommandReturn

CommandReturn is used for carrying output data from the Command itself back to the caller. The specific nature of the return message will depend on the Command being called. For a long running Command, there may be multiple return messages.

Field	Type	Description
type	enum	Indicates the type of the command return message. Currently, there is only one type in use: COMMAND_OUTPUT = 0;
message	string	The Command may include a brief text string describing the return value. Note at this time, none of the available Command actions will ever populate this field.
payload	bytes	The returned data output from the Command; this contains the actual output value, generally as marshalled JSON.
meta	map<string,string>	Any message meta-data which accompanies the payload.

CommandResult

CommandResult will be returned when the command execution is completed; a single Command will return result message; there will be no further response message after the result. The result will indicate the reason that the execution is completed:

Field	Type	Description
status	enum	COMPLETE_SUCCESS = 0;Command completed successfully. CANCELLED = 10;Command was cancelled by request from the caller. COMPLETE_ERROR = 11;Command was started, but ended reporting an error. TIMED OUT = 12;Command timed out during delivery or execution. REJECTED_ID = 13;Command was rejected because its command ID was invalid. REJECTED_AUTH = 14; Command was rejected because of an authentication failure. REJECTED_PARAMS = 15;Command was rejected because input params were invalid. REJECTED_NO_RECEIVER = 16; The Command could not be routed to the Robot. FATAL = 17; Some type of unknown internal error.
message	string	If the Command did not complete successfully, then a brief text description of the reason may be provided.

The CallCommand() method will return a stream of responses; the stream will always end with a single CommandResult message, after which the stream will be closed. A typical sequence of responses for a simple Command which executes quickly and returns a single value would be:

Ack from cloud gateway, Ack from agent, Return data, Result.