Command Dictionaries

About Command Dictionaries

The TelloCommander API validates all commands entered to ensure that:

• The command is recognised
• The number and type of arguments supplied is correct
• Where appropriate, the value for each argument is within the permitted range for the command

Validation is done against a command dictionary, that is loaded when the an instance of the API is created.

Format

Command dictionaries are stored as content files bundled with the API, named according to the following pattern, where x.x.x.x is the API or dictionary version number:

CommandDictionary-x.x.x.x.xml

As the file extension indicates, they are XML format files with the following structure:

<?xml version="1.0" encoding="utf-8"?>
<CommandDictionary xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <Commands>
    </Commands>
</CommandDictionary>

Command Definitions

The commands node contains 1 or more command definitions:

<CommandDefinition>
    <Name>takeoff</Name>
    <ConnectionType>Any</ConnectionType>
    <ResponseType>OK</ResponseType>
    <IsCustomCommand>false</IsCustomCommand>
    <MockResponse>ok</MockResponse>
    <Arguments />
</CommandDefinition>

Name

The "name" element is the text of the command sent to the drone, in this example the command instructing the drone to take off.

Connection Type

The connection type specifies which type of connection the command is valid for (see the documentation on the demonstration application):

Connection Type	Valid For
Any	All connection types
Mock	Mock connections
Simulator	Simulator connections
Drone	Connections to a real drone

The API uses the connection type to ensure only valid commands are sent to the drone. For example, the "stopsimulator" command (see the documentation on the drone simulator) is only meaningful when connected to the simulator and should not be sent to the real drone.

Response Type

The response type indicates the kind of response the API should expect from a given command:

Response Type	Expected Data
Dictionary	A dictionary of name/value pairs separated by ";" e.g. the results of the acceleration? command from the 1.3.0.0 API
Number	A numeric value, with or without units
Range	A range, with or without units e.g. the results of the temp? command from the 1.3.0.0 API

Response type is not used in the current release of the API but will be used in a future release and must be present for the dictionary to be considered valid.

Is Custom Command

This element is true if the command defines a custom command implemented by the API and false if the command is one of the standard commands the drone can respond to.

Mock Response

This element defines the response that a mock or simulator connection will return for the command.

Arguments

For commands that take one or more arguments, the "Arguments" element contains a list of argument definitions used to validate the values supplied for those arguments when the API validates a command.

Commands With Numeric Arguments

The following is an example of a command that takes a single numeric argument:

<CommandDefinition>
    <Name>up</Name>
    <ConnectionType>Any</ConnectionType>
    <ResponseType>OK</ResponseType>
    <IsCustomCommand>false</IsCustomCommand>
    <MockResponse>ok</MockResponse>
    <Arguments>
        <ArgumentDefinition>
            <Name>distance</Name>
            <ArgumentType>Number</ArgumentType>
            <Required>true</Required>
            <Minimum>20</Minimum>
            <Maximum>500</Maximum>
            <AllowedValues />
        </ArgumentDefinition>
    </Arguments>
</CommandDefinition>

Name

The name of the argument, used primarily when reporting errors to identify the precise location of a validation issue with a command.

Argument Type

The argument type may be one of "String" or "Number".

Required

The "Required" element controls whether or not the argument is deemed to be mandatory or optional when validating a command.

Optional arguments must occur after all of the mandatory ones.

Minimum and Maximum

The minimum and maximum acceptable values for the argument or a "nil" specification:

<Minimum xsi:nil="true" />
<Maximum xsi:nil="true" />

Either or both of the minimum and maximum may be specified as nil, with the following impact on validation of a supplied value for the argument:

Minimum	Maximum	Validation Action
a	b	a <= value <= b
nil	b	value <= b
a	nil	a <= value
nil	nil	value is numeric. No range check is done

Commands With Arguments Having Defined Values

The following is an example of a command that takes a single argument with for which the value must be one of a fixed set of values:

<CommandDefinition>
    <Name>flip</Name>
    <ConnectionType>Any</ConnectionType>
    <ResponseType>OK</ResponseType>
    <IsCustomCommand>false</IsCustomCommand>
    <MockResponse>ok</MockResponse>
    <Arguments>
        <ArgumentDefinition>
            <Name>direction</Name>
            <ArgumentType>String</ArgumentType>
            <Required>true</Required>
            <Minimum xsi:nil="true" />
            <Maximum xsi:nil="true" />
            <AllowedValues>
                <string>l</string>
                <string>r</string>
                <string>b</string>
                <string>f</string>
            </AllowedValues>
        </ArgumentDefinition>
    </Arguments>
</CommandDefinition>

The argument type is specified as a string, the minimum and maximum are specified as nil (or the elements for them are missing) and the "AllowedValues" element defines a set of strings giving the allowed values.

Dictionary Validation

On load, dictionaries are validated against an XML schema held as a content file alongside the dictionary files themselves.