Drone.Command (ex_drone v0.2.0)

Command struct and helpers for drone operations.

Every command sent through the ex_drone pipeline is represented as a Drone.Command struct. This provides a unified representation regardless of which adapter handles the command.

Example

cmd = Drone.Command.move(:forward, 100)
cmd.type
#=> :move
cmd.args
#=> [direction: :forward, distance: 100]

Summary

Types

command_type()

Discriminator for the command struct's :type field.

direction()

Horizontal / vertical move direction relative to current yaw.

flip_direction()

Flip direction while flying.

query_type()

Telemetry / status query kind.

rotation()

Yaw rotation direction.

t()

A single drone command.

Functions

emergency()

Creates an emergency motor-stop command.

emergency?(arg1)

Returns whether the command is an emergency stop.

flip(direction)

Creates a flip command.

hover(seconds)

Creates a hover command.

land()

Creates a land command.

move(direction, distance)

Creates a movement command.

movement?(arg1)

Returns whether the command is a movement-class command (:move, :rotate, :flip).

new(type, args \\ [])

Creates a new command struct.

query(type)

Creates a query command.

query?(arg1)

Returns whether the command is a query.

requires_flying?(arg1)

Returns whether the command requires the drone to already be flying.

rotate(direction, degrees)

Creates a rotation command.

safe_to_retry?(arg1)

Returns whether the command is considered safe to auto-retry.

sdk_mode()

Creates an SDK mode activation command (command on Tello).

speed(speed)

Creates a speed setting command.

stop()

Creates a stop command (hover in place / cancel velocity).

takeoff()

Creates a takeoff command.

types()

Returns all valid command type atoms.

Types

command_type()

@type command_type() ::
  :sdk_mode
  | :takeoff
  | :land
  | :emergency
  | :move
  | :rotate
  | :flip
  | :hover
  | :speed
  | :stop
  | :query

Discriminator for the command struct's :type field.

Possible values: :sdk_mode, :takeoff, :land, :emergency, :move, :rotate, :flip, :hover, :speed, :stop, :query.

Example

:takeoff

direction()

@type direction() :: :up | :down | :left | :right | :forward | :back

Horizontal / vertical move direction relative to current yaw.

Possible values: :up, :down, :left, :right, :forward, :back.

Example

:forward

flip_direction()

@type flip_direction() :: :left | :right | :forward | :back

Flip direction while flying.

Possible values: :left, :right, :forward, :back.

Example

:left

query_type()

@type query_type() ::
  :battery | :height | :speed | :time | :wifi | :sdk_version | :serial_number

Telemetry / status query kind.

Possible values: :battery, :height, :speed, :time, :wifi, :sdk_version, :serial_number.

Example

:battery

rotation()

@type rotation() :: :cw | :ccw

Yaw rotation direction.

Possible values: :cw (clockwise), :ccw (counter-clockwise).

Example

:cw

t()

@type t() :: %Drone.Command{
  args: keyword(),
  raw: String.t() | nil,
  type: command_type()
}

A single drone command.

Fields

Field	Type	Required	Meaning
`type`	`command_type/0`	yes	What to execute
`args`	`keyword()`	no (`[]`)	Type-specific args, e.g. `[direction: :up, distance: 40]`
`raw`	`String.t() \| nil`	no	Optional wire string (Tello encoding may fill this)

Examples

%Drone.Command{type: :takeoff, args: [], raw: nil}

%Drone.Command{
  type: :move,
  args: [direction: :forward, distance: 100],
  raw: nil
}

%Drone.Command{type: :query, args: [type: :battery], raw: nil}

Functions

emergency()

@spec emergency() :: t()

Creates an emergency motor-stop command.

Returns

%Drone.Command{type: :emergency}

Example

Drone.Command.emergency()

emergency?(arg1)

@spec emergency?(t()) :: boolean()

Returns whether the command is an emergency stop.

Parameters

command (t/0)

Returns

boolean()

Example

true = Drone.Command.emergency?(Drone.Command.emergency())

flip(direction)

@spec flip(flip_direction()) :: t()

Creates a flip command.

Parameters

direction (flip_direction/0) — :left | :right | :forward | :back

Returns

%Drone.Command{type: :flip, ...}

Example

Drone.Command.flip(:forward)

hover(seconds)

@spec hover(pos_integer()) :: t()

Creates a hover command.

Parameters

seconds (pos_integer()) — hover duration

Returns

%Drone.Command{type: :hover, args: [seconds: seconds]}

Example

Drone.Command.hover(3)

land()

@spec land() :: t()

Creates a land command.

Returns

%Drone.Command{type: :land}

Example

Drone.Command.land()

move(direction, distance)

@spec move(direction(), pos_integer()) :: t()

Creates a movement command.

Parameters

direction (direction/0) — :up | :down | :left | :right | :forward | :back
distance (pos_integer()) — centimeters (validated later as 20..500)

Returns

%Drone.Command{type: :move, args: [direction: ..., distance: ...]}

Example

Drone.Command.move(:forward, 100)

movement?(arg1)

@spec movement?(t()) :: boolean()

Returns whether the command is a movement-class command (:move, :rotate, :flip).

Parameters

command (t/0)

Returns

boolean()

Example

true = Drone.Command.movement?(Drone.Command.move(:up, 40))

new(type, args \\ [])

@spec new(
  command_type(),
  keyword()
) :: t()

Creates a new command struct.

Parameters

type (command_type/0) — command discriminant
args (keyword(), default []) — type-specific arguments

Returns

%Drone.Command{}

Example

Drone.Command.new(:hover, seconds: 2)

query(type)

@spec query(query_type()) :: t()

Creates a query command.

Parameters

type (query_type/0) — :battery, :height, :speed, :time, :wifi, :sdk_version, or :serial_number

Returns

%Drone.Command{type: :query, args: [type: type]}

Example

Drone.Command.query(:battery)

query?(arg1)

@spec query?(t()) :: boolean()

Returns whether the command is a query.

Parameters

command (t/0)

Returns

boolean()

Example

true = Drone.Command.query?(Drone.Command.query(:height))

requires_flying?(arg1)

@spec requires_flying?(t()) :: boolean()

Returns whether the command requires the drone to already be flying.

Parameters

command (t/0)

Returns

boolean()

Example

true = Drone.Command.requires_flying?(Drone.Command.move(:forward, 50))

rotate(direction, degrees)

@spec rotate(rotation(), pos_integer()) :: t()

Creates a rotation command.

Parameters

direction (rotation/0) — :cw or :ccw
degrees (pos_integer()) — 1..3600 (validated in safety)

Returns

%Drone.Command{type: :rotate, ...}

Example

Drone.Command.rotate(:cw, 90)

safe_to_retry?(arg1)

@spec safe_to_retry?(t()) :: boolean()

Returns whether the command is considered safe to auto-retry.

Only queries and SDK-mode activation are retryable by default. Movement commands must never be retried automatically.

Parameters

command (t/0)

Returns

boolean()

Example

true = Drone.Command.safe_to_retry?(Drone.Command.query(:battery))
false = Drone.Command.safe_to_retry?(Drone.Command.move(:forward, 50))

sdk_mode()

@spec sdk_mode() :: t()

Creates an SDK mode activation command (command on Tello).

Returns

%Drone.Command{type: :sdk_mode}

Example

Drone.Command.sdk_mode()

speed(speed)

@spec speed(pos_integer()) :: t()

Creates a speed setting command.

Parameters

speed (pos_integer()) — cm/s (validated as 10..100)

Returns

%Drone.Command{type: :speed, args: [speed: speed]}

Example

Drone.Command.speed(50)

stop()

@spec stop() :: t()

Creates a stop command (hover in place / cancel velocity).

Returns

%Drone.Command{type: :stop}

Example

Drone.Command.stop()

takeoff()

@spec takeoff() :: t()

Creates a takeoff command.

Returns

%Drone.Command{type: :takeoff}

Example

Drone.Command.takeoff()

types()

@spec types() :: [command_type()]

Returns all valid command type atoms.

Returns

[t:command_type/0]

Example

:takeoff in Drone.Command.types()