Drone.Telemetry (ex_drone v0.3.0)

Telemetry event helpers for ex_drone.

Emits standard Elixir :telemetry events for vehicle and swarm lifecycle. Event names follow [:drone, namespace, action].

Attach handlers with :telemetry.attach/4 or :telemetry.attach_many/4.

Vehicle events

[:drone, :connect, :start | :stop | :error]
[:drone, :disconnect]
[:drone, :command, :start | :stop | :error]
[:drone, :safety, :reject | :warning]
[:drone, :telemetry, :update]
[:drone, :emergency]

Swarm events

[:drone, :swarm, :start | :stop]
[:drone, :swarm, :command, :start | :stop | :error]
[:drone, :swarm, :emergency]

Example

:telemetry.attach(
  "drone-logger",
  [:drone, :command, :stop],
  fn _event, measurements, metadata, _config ->
    IO.inspect({measurements.command, metadata.name})
  end,
  nil
)

Summary

Functions

emit_command_error(adapter, name, command_type, reason, duration)

Emits [:drone, :command, :error] when the adapter fails.

emit_command_start(adapter, name, command)

Emits [:drone, :command, :start] after safety approval.

emit_command_stop(adapter, name, command_type, result, duration)

Emits [:drone, :command, :stop] on success.

emit_connect_error(adapter, name, reason)

Emits [:drone, :connect, :error].

emit_connect_start(adapter, name)

Emits [:drone, :connect, :start].

emit_connect_stop(adapter, name, duration)

Emits [:drone, :connect, :stop] after a successful connect.

emit_disconnect(adapter, name)

Emits [:drone, :disconnect].

emit_emergency(adapter, name)

Emits [:drone, :emergency] when an emergency stop is requested.

emit_safety_reject(adapter, name, command_type, reason)

Emits [:drone, :safety, :reject].

emit_safety_warning(adapter, name, command_type, warning)

Emits [:drone, :safety, :warning] when a command is allowed with warnings.

emit_swarm_command_error(swarm, members, command, reason, duration)

Emits [:drone, :swarm, :command, :error] on partial or plan failure.

emit_swarm_command_start(swarm, members, command)

Emits [:drone, :swarm, :command, :start] before a coordinated op.

emit_swarm_command_stop(swarm, members, command, duration)

Emits [:drone, :swarm, :command, :stop] after a successful coordinated op.

emit_swarm_emergency(swarm, members)

Emits [:drone, :swarm, :emergency] when swarm-wide emergency is requested.

emit_swarm_start(swarm, members)

Emits [:drone, :swarm, :start] when a swarm coordinator starts.

emit_swarm_stop(swarm, members, reason \\ :normal)

Emits [:drone, :swarm, :stop] when a swarm coordinator terminates.

emit_telemetry_update(adapter, name, telemetry)

Emits [:drone, :telemetry, :update] with pose / battery measurements.

Functions

emit_command_error(adapter, name, command_type, reason, duration)

@spec emit_command_error(atom(), atom(), atom(), atom(), non_neg_integer()) :: :ok

Emits [:drone, :command, :error] when the adapter fails.

Parameters

adapter (atom())
name (atom())
command_type (atom())
reason (atom() | term())
duration (non_neg_integer())

Returns

:ok

emit_command_start(adapter, name, command)

@spec emit_command_start(atom(), atom(), Drone.Command.t()) :: :ok

Emits [:drone, :command, :start] after safety approval.

Parameters

adapter (atom())
name (atom())
command (Drone.Command.t())

Returns

:ok

emit_command_stop(adapter, name, command_type, result, duration)

@spec emit_command_stop(atom(), atom(), atom(), atom(), non_neg_integer()) :: :ok

Emits [:drone, :command, :stop] on success.

Parameters

adapter (atom())
name (atom())
command_type (atom()) — e.g. :takeoff
result (atom()) — e.g. :ok, :dry_run
duration (non_neg_integer())

Returns

:ok

emit_connect_error(adapter, name, reason)

@spec emit_connect_error(atom(), atom(), term()) :: :ok

Emits [:drone, :connect, :error].

Parameters

adapter (atom())
name (atom())
reason (term())

Returns

:ok

emit_connect_start(adapter, name)

@spec emit_connect_start(atom(), atom()) :: :ok

Emits [:drone, :connect, :start].

Parameters

adapter (atom()) — e.g. :sim, :tello
name (atom()) — vehicle name

Returns

:ok

emit_connect_stop(adapter, name, duration)

@spec emit_connect_stop(atom(), atom(), non_neg_integer()) :: :ok

Emits [:drone, :connect, :stop] after a successful connect.

Parameters

adapter (atom())
name (atom())
duration (non_neg_integer()) — monotonic time units

Returns

:ok

emit_disconnect(adapter, name)

@spec emit_disconnect(atom(), atom()) :: :ok

Emits [:drone, :disconnect].

Parameters

adapter (atom())
name (atom())

Returns

:ok

emit_emergency(adapter, name)

@spec emit_emergency(atom(), atom()) :: :ok

Emits [:drone, :emergency] when an emergency stop is requested.

Parameters

adapter (atom())
name (atom())

Returns

:ok

emit_safety_reject(adapter, name, command_type, reason)

@spec emit_safety_reject(atom(), atom(), atom(), atom()) :: :ok

Emits [:drone, :safety, :reject].

Parameters

adapter (atom())
name (atom())
command_type (atom())
reason (atom()) — e.g. :max_altitude, :low_battery

Returns

:ok

emit_safety_warning(adapter, name, command_type, warning)

@spec emit_safety_warning(atom(), atom(), atom(), atom()) :: :ok

Emits [:drone, :safety, :warning] when a command is allowed with warnings.

Parameters

adapter (atom())
name (atom())
command_type (atom())
warning (atom()) — e.g. :no_prop_guards

Returns

:ok

emit_swarm_command_error(swarm, members, command, reason, duration)

@spec emit_swarm_command_error(
  atom() | nil,
  [atom()],
  atom(),
  term(),
  non_neg_integer()
) :: :ok

Emits [:drone, :swarm, :command, :error] on partial or plan failure.

Parameters

swarm (atom() | nil)
members ([atom()])
command (atom())
reason (term()) — e.g. :partial, :separation_violation
duration (non_neg_integer())

Returns

:ok

emit_swarm_command_start(swarm, members, command)

@spec emit_swarm_command_start(atom() | nil, [atom()], atom()) :: :ok

Emits [:drone, :swarm, :command, :start] before a coordinated op.

Parameters

swarm (atom() | nil)
members ([atom()])
command (atom()) — e.g. :takeoff, :land, :run, :connect_sdk

Returns

:ok

emit_swarm_command_stop(swarm, members, command, duration)

@spec emit_swarm_command_stop(atom() | nil, [atom()], atom(), non_neg_integer()) ::
  :ok

Emits [:drone, :swarm, :command, :stop] after a successful coordinated op.

Parameters

swarm (atom() | nil)
members ([atom()])
command (atom())
duration (non_neg_integer())

Returns

:ok

emit_swarm_emergency(swarm, members)

@spec emit_swarm_emergency(atom() | nil, [atom()]) :: :ok

Emits [:drone, :swarm, :emergency] when swarm-wide emergency is requested.

Parameters

swarm (atom() | nil)
members ([atom()])

Returns

:ok

emit_swarm_start(swarm, members)

@spec emit_swarm_start(atom() | nil, [atom()]) :: :ok

Emits [:drone, :swarm, :start] when a swarm coordinator starts.

Parameters

swarm (atom() | nil) — registered swarm name, or nil if anonymous
members ([atom()]) — ordered member drone names

Returns

:ok

Example

Drone.Telemetry.emit_swarm_start(:advisors, [:good, :bad])

emit_swarm_stop(swarm, members, reason \\ :normal)

@spec emit_swarm_stop(atom() | nil, [atom()], term()) :: :ok

Emits [:drone, :swarm, :stop] when a swarm coordinator terminates.

Parameters

swarm (atom() | nil)
members ([atom()])
reason (term(), optional) — OTP terminate reason (:normal, :shutdown, crash reason, etc.)

Returns

:ok

emit_telemetry_update(adapter, name, telemetry)

@spec emit_telemetry_update(atom(), atom(), map()) :: :ok

Emits [:drone, :telemetry, :update] with pose / battery measurements.

Parameters

adapter (atom())
name (atom())
telemetry (map()) — typically includes :x, :y, :z, :yaw, :battery

Returns

:ok