Drone.Mission (ex_drone v0.3.0)

Mission DSL for scripting drone command sequences.

A mission is an ordered list of Drone.Command values that can be built with a pipe-friendly API and executed sequentially against a named drone.

Commands are stored newest-first internally and reversed for execution / inspection via commands/1 and run/2.

Example

mission =
  Drone.Mission.new(name: "square")
  |> Drone.Mission.sdk_mode()
  |> Drone.Mission.takeoff()
  |> Drone.Mission.hover(seconds: 3)
  |> Drone.Mission.move(:up, 40)
  |> Drone.Mission.move(:forward, 100)
  |> Drone.Mission.rotate(:cw, 90)
  |> Drone.Mission.land()

{:ok, results} = Drone.Mission.run(mission, :my_drone)

Summary

Types

t()

A scripted sequence of drone commands.

Functions

commands(mission)

Returns commands in execution order (oldest first).

emergency(mission)

Adds an emergency stop command.

flip(mission, direction)

Adds a flip command.

hover(mission, opts \\ [])

Adds a hover command.

land(mission)

Adds a land command.

length(mission)

Returns the number of commands in the mission.

move(mission, direction, distance)

Adds a movement command.

new(opts \\ [])

Creates a new empty mission.

query(mission, type)

Adds a query command.

rotate(mission, direction, degrees)

Adds a rotation command.

run(mission, drone_name)

Runs a mission against a named drone process.

sdk_mode(mission)

Adds an SDK mode activation command.

speed(mission, speed)

Adds a speed-setting command.

stop(mission)

Adds a stop (hover in place) command.

takeoff(mission)

Adds a takeoff command.

validate_capabilities(mission, caps)

Validates that every command in the mission is supported by capabilities.

Types

t()

@type t() :: %Drone.Mission{commands: [Drone.Command.t()], name: String.t() | nil}

A scripted sequence of drone commands.

Fields

Field	Type	Default	Meaning
`commands`	`[Drone.Command.t()]`	`[]`	Commands in reverse insertion order
`name`	`String.t() \| nil`	`nil`	Optional label for logging / demos

Example

%Drone.Mission{
  name: "hover-demo",
  commands: [
    %Drone.Command{type: :land, args: [], raw: nil},
    %Drone.Command{type: :takeoff, args: [], raw: nil}
  ]
}

Functions

commands(mission)

@spec commands(t()) :: [Drone.Command.t()]

Returns commands in execution order (oldest first).

Parameters

mission (t/0)

Returns

[Drone.Command.t()]

Example

[sdk, takeoff | _] = Drone.Mission.commands(mission)

emergency(mission)

@spec emergency(t()) :: t()

Adds an emergency stop command.

Parameters

mission (t/0)

Returns

Updated t/0.

Example

mission |> Drone.Mission.emergency()

flip(mission, direction)

@spec flip(t(), Drone.Command.flip_direction()) :: t()

Adds a flip command.

Parameters

mission (t/0)
direction (Drone.Command.flip_direction()) — :left | :right | :forward | :back

Returns

Updated t/0.

Example

mission |> Drone.Mission.flip(:left)

hover(mission, opts \\ [])

@spec hover(
  t(),
  keyword()
) :: t()

Adds a hover command.

Parameters

mission (t/0)
opts (keyword()) — :seconds (pos_integer(), default 1)

Returns

Updated t/0.

Example

mission |> Drone.Mission.hover(seconds: 3)

land(mission)

@spec land(t()) :: t()

Adds a land command.

Parameters

mission (t/0)

Returns

Updated t/0.

Example

mission |> Drone.Mission.land()

length(mission)

@spec length(t()) :: non_neg_integer()

Returns the number of commands in the mission.

Parameters

mission (t/0)

Returns

non_neg_integer()

Example

4 = Drone.Mission.length(mission)

move(mission, direction, distance)

@spec move(t(), Drone.Command.direction(), pos_integer()) :: t()

Adds a movement command.

Parameters

mission (t/0)
direction (Drone.Command.direction()) — :up | :down | :left | :right | :forward | :back
distance (pos_integer()) — centimeters (SDK range 20..500)

Returns

Updated t/0.

Example

mission |> Drone.Mission.move(:forward, 100)

new(opts \\ [])

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

Creates a new empty mission.

Parameters

opts (keyword()) — options:
- :name (String.t()) — optional mission label

Returns

%Drone.Mission{}

Examples

Drone.Mission.new()
Drone.Mission.new(name: "patrol-loop")

query(mission, type)

@spec query(t(), Drone.Command.query_type()) :: t()

Adds a query command.

Parameters

mission (t/0)
type (Drone.Command.query_type()) — :battery, :height, :speed, :time, :wifi, :sdk_version, or :serial_number

Returns

Updated t/0.

Example

mission |> Drone.Mission.query(:battery)

rotate(mission, direction, degrees)

@spec rotate(t(), Drone.Command.rotation(), pos_integer()) :: t()

Adds a rotation command.

Parameters

mission (t/0)
direction (Drone.Command.rotation()) — :cw or :ccw
degrees (pos_integer()) — 1..3600

Returns

Updated t/0.

Example

mission |> Drone.Mission.rotate(:cw, 90)

run(mission, drone_name)

@spec run(t(), atom()) :: {:ok, [term()]} | {:error, Drone.Command.t(), term()}

Runs a mission against a named drone process.

Each command is sent sequentially. On the first failure the mission stops.

Parameters

mission (t/0) — mission to execute
drone_name (atom()) — registered vehicle name (e.g. :my_drone)

Returns

{:ok, [term()]} — per-command replies in execution order
{:error, Drone.Command.t(), term()} — failing command and reason (reason may be {:safety, atom()}, :not_in_sdk_mode, etc.)
{:error, command, {:no_process, atom()}} — drone not registered

Example

{:ok, drone} = Drone.connect(:sim, name: :demo)
Drone.connect_sdk(drone)

mission =
  Drone.Mission.new()
  |> Drone.Mission.takeoff()
  |> Drone.Mission.move(:up, 20)
  |> Drone.Mission.land()

{:ok, [_takeoff, _move, _land]} = Drone.Mission.run(mission, :demo)

sdk_mode(mission)

@spec sdk_mode(t()) :: t()

Adds an SDK mode activation command.

Parameters

mission (t/0) — mission to extend

Returns

Updated t/0.

Example

Drone.Mission.new() |> Drone.Mission.sdk_mode()

speed(mission, speed)

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

Adds a speed-setting command.

Parameters

mission (t/0)
speed (pos_integer()) — cm/s (SDK range 10..100)

Returns

Updated t/0.

Example

mission |> Drone.Mission.speed(50)

stop(mission)

@spec stop(t()) :: t()

Adds a stop (hover in place) command.

Parameters

mission (t/0)

Returns

Updated t/0.

Example

mission |> Drone.Mission.stop()

takeoff(mission)

@spec takeoff(t()) :: t()

Adds a takeoff command.

Parameters

mission (t/0)

Returns

Updated t/0.

Example

mission |> Drone.Mission.takeoff()

validate_capabilities(mission, caps)

@spec validate_capabilities(t(), Drone.Adapter.Capabilities.t()) ::
  :ok | {:error, Drone.Command.t(), term()}

Validates that every command in the mission is supported by capabilities.

Fails before takeoff so unsupported missions do not partially execute.