Meshcore.Event (Meshcore v0.1.0)

Copy Markdown View Source

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 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.

Summary

Types

t()
type()

Functions

error(reason, extra \\ %{})

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

error?(event)

Returns true for :error events.

error_message(code)

Maps a device error code to its firmware constant name.

match_filters?(event, filters)

Returns true if all filters equal the corresponding event attributes.

new(type, payload, attributes \\ %{})

Builds an event.

to_result(event)

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

types()

All known event types.

Types

t()

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

type()

@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

Functions

error(reason, extra \\ %{})

@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?(event)

@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(code)

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

Maps a device error code to its firmware constant name.

match_filters?(event, filters)

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

Returns true if all filters equal the corresponding event attributes.

new(type, payload, attributes \\ %{})

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

Builds an event.

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

to_result(event)

@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()

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

All known event types.