# `MAVLink2.Mission`
[🔗](https://github.com/isaiahdw/mavlink2/blob/v0.1.0/lib/mavlink2/mission.ex#L1)

MAVLink's mission protocol: upload, download and clear a mission, geofence
or rally point list.

    items = [
      [command: :mav_cmd_nav_takeoff, frame: :mav_frame_global_relative_alt, z: 20.0],
      [command: :mav_cmd_nav_waypoint, frame: :mav_frame_global_relative_alt,
       x: 473_977_420, y: 85_455_940, z: 30.0, autocontinue: 1]
    ]

    MAVLink2.Mission.upload(link, {1, 1}, items)
    #=> {:ok, opaque_id}

The link's dialect must have the messages (`common.xml` does). `target`
is `{sysid, compid}`.

An item has `MISSION_ITEM_INT`'s fields other than the target, `seq` and
`mission_type`: `:frame` (a `MAV_FRAME` atom or value), `:command` (a
`MAV_CMD` atom or value), `:current`, `:autocontinue`, `:param1`..`:param4`,
`:x`, `:y` (integers: degrees × 10^7 for a global frame, metres × 10^4
for a local one) and `:z`; each defaults to 0. The `_INT` global frames
are superseded by their plain counterparts (`:mav_frame_global_relative_alt`
for `:mav_frame_global_relative_alt_int`), which mean the same here.

Uploading sends `MISSION_COUNT` and then each item the target asks for,
by `MISSION_REQUEST_INT` or the deprecated `MISSION_REQUEST` (answered
with `MISSION_ITEM_INT` either way), until its `MISSION_ACK`. Downloading
asks for the count and then each item by `MISSION_REQUEST_INT`, accepts
the deprecated `MISSION_ITEM` in reply (its float positions scaled to
integers), and acks the whole. When the target goes quiet, the last
message is sent again, up to `:retries` times in a row; after that the
operation is cancelled with a `MISSION_ACK` of
`MAV_MISSION_OPERATION_CANCELLED` and returns `{:error, :timeout}`.

`upload/4` returns `{:ok, opaque_id}` and `download/3` `{:ok, items,
opaque_id}`: the plan's id from the target's `MISSION_ACK` or
`MISSION_COUNT`, to compare with `MISSION_CURRENT` later, or `nil` for a
dialect or target without it.

Options:

| | |
| --- | --- |
| `:mission_type` | a `MAV_MISSION_TYPE` atom or value (default `:mav_mission_type_mission`) |
| `:timeout` | ms to wait for the target before sending again (default 1500) |
| `:item_timeout` | the same, for a plan item (default 250) |
| `:retries` | times in a row to send again (default 5) |

A refusal is `{:error, {:mission_result, result}}`, with `result` the
`MAV_MISSION_RESULT` entry atom (`:mav_mission_no_space`, ...).

# `item`

```elixir
@type item() :: keyword() | map()
```

# `clear`

```elixir
@spec clear(GenServer.server(), MAVLink2.target(), keyword()) ::
  :ok | {:error, term()}
```

Clears the target's list of that mission type.

# `download`

```elixir
@spec download(GenServer.server(), MAVLink2.target(), keyword()) ::
  {:ok, [map()], non_neg_integer() | nil} | {:error, term()}
```

Downloads the target's list of that mission type.

# `upload`

```elixir
@spec upload(GenServer.server(), MAVLink2.target(), [item()], keyword()) ::
  {:ok, non_neg_integer() | nil} | {:error, term()}
```

Uploads `items`, replacing the target's list of that mission type.

---

*Consult [api-reference.md](api-reference.md) for complete listing*