Drone.Error (ex_drone v0.3.0)

Error types and helpers for ex_drone.

All errors in ex_drone follow explicit tuple conventions:

{:error, reason} for simple errors
{:error, :safety, reason} for safety rejections
{:error, :invalid_command, details} for command validation errors

Examples

{:error, :safety, :low_battery} = Drone.Error.safety(:low_battery)
true = Drone.Error.safety_error?({:error, :safety, :low_battery})
:timeout = Drone.Error.reason({:error, :timeout})

Summary

Types

adapter_reason()

Adapter / link failure reasons commonly returned as {:error, reason}.

command_reason()

Command construction validation reasons in {:error, :invalid_command, reason}.

reason()

Any error reason atom (or opaque term()) found in error tuples.

safety_reason()

Reasons returned inside {:error, :safety, reason} from the safety pipeline.

Functions

adapter(reason)

Creates an adapter error tuple.

adapter_error?(arg1)

Checks if an error is a simple adapter-style {:error, atom()} tuple.

invalid_command(reason)

Creates an invalid command error tuple.

invalid_command_error?(arg1)

Checks if an error is an invalid command error.

reason(arg)

Extracts the reason from any error tuple.

safety(reason)

Creates a safety error tuple.

safety_error?(arg1)

Checks if an error is a safety error.

Types

adapter_reason()

@type adapter_reason() ::
  :timeout
  | :connection_error
  | :command_error
  | :not_in_sdk_mode
  | :not_flying
  | :already_flying
  | :emergency_active
  | :simulated_failure
  | :unsupported_command
  | :estimator_not_ready
  | :telemetry_unavailable
  | :link_lost
  | :usb_backend_unavailable
  | :no_ack
  | :crazyradio_not_found

Adapter / link failure reasons commonly returned as {:error, reason}.

Value	Typical cause
`:timeout`	UDP / IO timeout
`:connection_error` / `:command_error`	Transport or protocol failure
`:simulated_failure`	Sim adapter injected fault
`:unsupported_command`	Adapter does not implement the command
`:link_lost` / `:no_ack`	Crazyradio link failure
`:usb_backend_unavailable`	Missing USB backend for `radio://`
`:crazyradio_not_found`	No matching USB radio
`:estimator_not_ready`	Adapter readiness gate

Examples

:usb_backend_unavailable
:link_lost

command_reason()

@type command_reason() ::
  :invalid_direction
  | :invalid_distance
  | :invalid_rotation
  | :invalid_degrees
  | :invalid_speed
  | :invalid_flip_direction
  | :invalid_query_type

Command construction validation reasons in {:error, :invalid_command, reason}.

Examples

:invalid_direction
:invalid_flip_direction

reason()

@type reason() :: safety_reason() | adapter_reason() | command_reason() | term()

Any error reason atom (or opaque term()) found in error tuples.

Examples

:timeout
:low_battery
{:unsupported_protocol, 99}

safety_reason()

@type safety_reason() ::
  :command_not_allowed
  | :not_in_sdk_mode
  | :not_flying
  | :already_flying
  | :emergency_active
  | :max_altitude
  | :max_distance
  | :low_battery
  | :geofence_violation
  | :dangerous_without_prop_guards
  | :invalid_distance
  | :invalid_degrees
  | :invalid_speed
  | :invalid_seconds
  | :stale_telemetry
  | :estimator_not_ready
  | :telemetry_unavailable

Reasons returned inside {:error, :safety, reason} from the safety pipeline.

Value	Typical cause
`:command_not_allowed`	Command not in the policy allowlist
`:not_in_sdk_mode`	Flight command before SDK mode
`:not_flying` / `:already_flying`	Mode mismatch for takeoff/land/move
`:emergency_active`	Vehicle is in emergency mode
`:max_altitude` / `:max_distance`	Policy ceiling / radius exceeded
`:low_battery`	Battery below hard minimum
`:geofence_violation`	Projected position outside geofence
`:dangerous_without_prop_guards`	Flip without prop guards when required
`:invalid_distance` / `:invalid_degrees` / `:invalid_speed` / `:invalid_seconds`	Arg out of SDK range
`:stale_telemetry`	Telemetry older than policy max age
`:estimator_not_ready`	Crazyflie estimator gate

Examples

:geofence_violation
:estimator_not_ready

Functions

adapter(reason)

@spec adapter(adapter_reason()) :: {:error, adapter_reason()}

Creates an adapter error tuple.

Parameters

reason (adapter_reason/0) — adapter failure reason

Returns

{:error, reason}.

Examples

{:error, :timeout} = Drone.Error.adapter(:timeout)

adapter_error?(arg1)

@spec adapter_error?(term()) :: boolean()

Checks if an error is a simple adapter-style {:error, atom()} tuple.

Parameters

error (term())

Returns

boolean().

Examples

true = Drone.Error.adapter_error?({:error, :link_lost})
false = Drone.Error.adapter_error?({:error, :safety, :low_battery})

invalid_command(reason)

@spec invalid_command(command_reason()) ::
  {:error, :invalid_command, command_reason()}

Creates an invalid command error tuple.

Parameters

reason (command_reason/0) — validation failure

Returns

{:error, :invalid_command, reason}.

Examples

{:error, :invalid_command, :invalid_distance} =
  Drone.Error.invalid_command(:invalid_distance)

invalid_command_error?(arg1)

@spec invalid_command_error?(term()) :: boolean()

Checks if an error is an invalid command error.

Parameters

error (term())

Returns

boolean().

Examples

true =
  Drone.Error.invalid_command_error?(
    {:error, :invalid_command, :invalid_speed}
  )

reason(arg)

@spec reason(
  {:error, atom()}
  | {:error, :safety, atom()}
  | {:error, :invalid_command, atom()}
) ::
  atom()

Extracts the reason from any error tuple.

Parameters

error — {:error, atom()}, {:error, :safety, atom()}, or {:error, :invalid_command, atom()}

Returns

The inner atom() reason.

Examples

:low_battery = Drone.Error.reason({:error, :safety, :low_battery})
:timeout = Drone.Error.reason({:error, :timeout})
:invalid_distance =
  Drone.Error.reason({:error, :invalid_command, :invalid_distance})

safety(reason)

@spec safety(safety_reason()) :: {:error, :safety, safety_reason()}

Creates a safety error tuple.

Parameters

reason (safety_reason/0) — rejection reason

Returns

{:error, :safety, reason}.

Examples

{:error, :safety, :max_altitude} = Drone.Error.safety(:max_altitude)

safety_error?(arg1)

@spec safety_error?(term()) :: boolean()

Checks if an error is a safety error.

Parameters

error (term()) — candidate error tuple or other value

Returns

boolean().

Examples

true = Drone.Error.safety_error?({:error, :safety, :low_battery})
false = Drone.Error.safety_error?({:error, :timeout})