Drone.Vehicle (ex_drone v0.3.0)

Supervised GenServer that manages a single drone connection.

Each Drone.Vehicle process represents one drone. It holds the adapter state, safety policy, and vehicle state. All commands flow through the safety pipeline before reaching the adapter.

Drivers should not call Drone.Vehicle directly. Use the Drone public API module instead.

Examples

# Prefer the public API:
{:ok, drone} = Drone.connect(:sim, name: :alpha)

# Low-level (tests / supervision trees):
{:ok, pid} =
  Drone.Vehicle.start_link(
    name: :alpha,
    adapter: :sim,
    safety: [max_altitude_cm: 200]
  )

Summary

Types

state()

Internal GenServer state for one vehicle process.

Functions

child_spec(init_arg)

Child specification for starting under a supervisor.

start_link(opts)

Starts a vehicle GenServer registered under opts[:name].

via_tuple(name)

Builds a :via tuple for the vehicle registry.

whereis(name)

Looks up a running vehicle pid by name.

Types

state()

@type state() :: %{
  name: atom(),
  adapter_module: module(),
  adapter_state: term(),
  safety_policy: Drone.Safety.Policy.t(),
  vehicle_state: %{
    x: integer(),
    y: integer(),
    z: integer(),
    yaw: integer(),
    battery: integer(),
    speed: integer(),
    flying: boolean(),
    mode: :idle | :sdk_mode | :flying | :emergency,
    last_command: Drone.Command.t() | nil,
    command_history: [Drone.Command.t()]
  }
}

Internal GenServer state for one vehicle process.

Field	Type	Meaning
`:name`	`atom()`	Registry name for this vehicle
`:adapter_module`	`module()`	Resolved `Drone.Adapter` implementation
`:adapter_state`	`term()`	Opaque adapter state
`:safety_policy`	`Drone.Safety.Policy.t()`	Active safety policy
`:vehicle_state`	`map()`	Kinematics + mode used by safety / telemetry

:vehicle_state keys include :x, :y, :z, :yaw (cm / degrees), :battery, :speed, :flying, :mode (:idle \| :sdk_mode \| :flying \| :emergency), :estimator_ready, :telemetry_at, :last_command, and :command_history.

Example

%Drone.Vehicle{
  name: :alpha,
  adapter_module: Drone.Adapters.Sim,
  safety_policy: %Drone.Safety.Policy{max_altitude_cm: 300},
  vehicle_state: %{x: 0, y: 0, z: 50, mode: :flying, flying: true, battery: 98}
}

Functions

child_spec(init_arg)

Child specification for starting under a supervisor.

Restart strategy is :temporary so a crashed vehicle is not restarted automatically by a static supervisor (callers reconnect explicitly).

Parameters

opts (keyword()) — same options as start_link/1

Returns

A child specification map suitable for supervisors.

start_link(opts)

@spec start_link(keyword()) :: GenServer.on_start()

Starts a vehicle GenServer registered under opts[:name].

Parameters

opts (keyword()) — required:
- :name (atom()) — unique vehicle name in Drone.Vehicle.Registry
- :adapter (atom() \| module()) — :sim, :tello, :crazyflie, or a module Optional:
- :safety (keyword()) — passed to Drone.Safety.Policy.new/1
- remaining keys — forwarded to adapter.connect/1

Returns

GenServer.on_start() ({:ok, pid} \| {:error, reason}).

Examples

{:ok, _pid} =
  Drone.Vehicle.start_link(
    name: :cf_1,
    adapter: :crazyflie,
    uri: "mock://ready"
  )

via_tuple(name)

@spec via_tuple(atom()) :: {:via, Registry, {Drone.Vehicle.Registry, atom()}}

Builds a :via tuple for the vehicle registry.

Parameters

name (atom()) — vehicle name

Returns

{:via, Registry, {Drone.Vehicle.Registry, name}}.

Examples

{:via, Registry, {Drone.Vehicle.Registry, :alpha}} =
  Drone.Vehicle.via_tuple(:alpha)

whereis(name)

@spec whereis(atom()) :: pid() | nil

Looks up a running vehicle pid by name.

Parameters

name (atom()) — vehicle name registered at start_link/1

Returns

pid() — when registered
nil — when no process is registered under that name

Examples

pid = Drone.Vehicle.whereis(:alpha)
true = is_pid(pid) or is_nil(pid)