# `Meshcore.Event`
[🔗](https://github.com/nyannus/meshcore_ex/blob/v0.1.0/lib/meshcore/event.ex#L1)

An event emitted by a MeshCore device or by the library itself.

Every command returns its result wrapped in an event, mirroring Python's
`Event(type, payload, attributes)`:

    {:ok, %Meshcore.Event{type: :msg_sent, payload: payload}} =
      Meshcore.Commands.send_msg(mc, contact, "hello")

* `:type` – one of `t:type/0` (the Python `EventType` enum, lower-cased).
* `:payload` – the decoded data. Maps use **atom keys**; keys are the Python
  keys lower-cased (`"SNR"` becomes `:snr`, `"fw ver"` becomes `:fw_ver`).
* `:attributes` – the subset of values you can filter subscriptions on
  (see `Meshcore.subscribe/3`).

## Event types

Command responses: `:contacts`, `:self_info`, `:contact_msg_recv`,
`:channel_msg_recv`, `:channel_data_recv`, `:current_time`, `:no_more_msgs`,
`:contact_uri`, `:battery`, `:device_info`, `:msg_sent`, `:new_contact`,
`:next_contact`, `:autoadd_config`, `:advert_path`, `:cli_reply`, `:ok`,
`:error`.

Push notifications: `:advertisement`, `:path_update`, `:ack`,
`:messages_waiting`, `:raw_data`, `:login_success`, `:login_failed`,
`:status_response`, `:log_data`, `:trace_data`, `:rx_log_data`,
`:telemetry_response`, `:binary_response`, `:mma_response`, `:acl_response`,
`:custom_vars`, `:stats_core`, `:stats_radio`, `:stats_packets`,
`:channel_info`, `:path_response`, `:private_key`, `:disabled`,
`:contact_deleted`, `:contacts_full`, `:tuning_params`, `:control_data`,
`:discover_response`, `:neighbours_response`, `:sign_start`, `:signature`,
`:allowed_repeat_freq`, `:default_flood_scope`.

Connection events: `:connected`, `:disconnected`.

# `t`

```elixir
@type t() :: %Meshcore.Event{attributes: map(), payload: any(), type: type()}
```

# `type`

```elixir
@type type() ::
  :contacts
  | :self_info
  | :contact_msg_recv
  | :channel_msg_recv
  | :channel_data_recv
  | :current_time
  | :no_more_msgs
  | :contact_uri
  | :battery
  | :device_info
  | :msg_sent
  | :new_contact
  | :next_contact
  | :autoadd_config
  | :advert_path
  | :cli_reply
  | :advertisement
  | :path_update
  | :ack
  | :messages_waiting
  | :raw_data
  | :login_success
  | :login_failed
  | :status_response
  | :log_data
  | :trace_data
  | :rx_log_data
  | :telemetry_response
  | :binary_response
  | :mma_response
  | :acl_response
  | :custom_vars
  | :stats_core
  | :stats_radio
  | :stats_packets
  | :channel_info
  | :path_response
  | :private_key
  | :disabled
  | :contact_deleted
  | :contacts_full
  | :tuning_params
  | :control_data
  | :discover_response
  | :neighbours_response
  | :sign_start
  | :signature
  | :allowed_repeat_freq
  | :default_flood_scope
  | :ok
  | :error
  | :connected
  | :disconnected
```

# `error`

```elixir
@spec error(any(), map()) :: t()
```

Builds an `:error` event with the given `reason` (stored as `payload.reason`).

    iex> Meshcore.Event.error(:timeout).payload
    %{reason: :timeout}

# `error?`

```elixir
@spec error?(t()) :: boolean()
```

Returns `true` for `:error` events.

An error payload is `%{reason: ...}` (or `%{error_code: ...}` when the
device rejected a command) – not the keys a successful response carries.

# `error_message`

```elixir
@spec error_message(integer()) :: String.t() | nil
```

Maps a device error code to its firmware constant name.

# `match_filters?`

```elixir
@spec match_filters?(t(), map()) :: boolean()
```

Returns `true` if all `filters` equal the corresponding event attributes.

# `new`

```elixir
@spec new(type(), any(), map()) :: t()
```

Builds an event.

    iex> Meshcore.Event.new(:ok, %{})
    %Meshcore.Event{type: :ok, payload: %{}, attributes: %{}}

# `to_result`

```elixir
@spec to_result(t()) :: {:ok, t()} | {:error, t()}
```

Wraps an event as the conventional command result: `{:ok, event}` or
`{:error, event}` for `:error` events.

# `types`

```elixir
@spec types() :: [type()]
```

All known event types.

---

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