@spec auto_update_contacts?(mc()) :: boolean()

Whether contacts are refreshed automatically on adverts and path updates.

@spec child_spec(keyword()) :: Supervisor.child_spec()

Child specification for supervision trees. Restarts only after abnormal exits (a disconnect/1 is final).

@spec connect(mc()) :: {:ok, Meshcore.Event.t()} | {:error, term()}

Connects (when started with connect: false) and runs the app-start handshake. Returns {:ok, self_info_event} or {:error, reason}.

@spec connected?(mc()) :: boolean()

Whether the transport is connected.

@spec contacts(mc()) :: %{required(String.t()) => map()}

The known contacts, %{public_key_hex => contact}.

@spec contacts_dirty?(mc()) :: boolean()

true when a push notification suggests the contact list is out of date.

@spec create_ble(keyword()) :: {:ok, pid()} | {:error, term()}

Connects over BLE and performs the handshake.

BLE needs a platform adapter (see Meshcore.Transport.BLE.Adapter), passed as :adapter. Options: :adapter (required), :address (BLE address or part of the advertised name; nil scans for a MeshCore* device), :pin (pair after connecting), :adapter_opts, plus the options of create_tcp/3.

@spec create_serial(String.t(), keyword()) :: {:ok, pid()} | {:error, term()}

Connects over a serial port and performs the handshake.

Requires the optional :circuits_uart dependency. If the device does not answer, the connection is retried once with the DTR line inverted (some boards reset on DTR).

Options: :baudrate (default 115200), :dtr (true), :rts (false), :cx_delay (ms, 100), plus the options of create_tcp/3.

@spec create_tcp(String.t() | :inet.ip_address(), :inet.port_number(), keyword()) ::
  {:ok, pid()} | {:error, term()}

Connects over TCP and performs the handshake.

Returns {:ok, mc} or {:error, reason}. The connection process is started under Meshcore.ConnectionSupervisor and is not restarted when it crashes – use child_spec/1 for that.

Options: :debug, :only_error, :default_timeout, :auto_reconnect, :max_reconnect_attempts (see start_link/1), :connect_timeout.

@spec default_timeout(mc()) :: pos_integer()

Default command timeout in milliseconds.

@spec disconnect(mc()) :: :ok

Disconnects from the device and stops the connection process, emitting a :disconnected event (reason: "manual_disconnect") first.

@spec ensure_contacts(mc(), boolean()) :: boolean()

Loads the contact list if it is empty – or, with follow set, if it is marked dirty – and returns whether a refresh was requested.

@spec flush_pending_contacts(mc()) :: :ok

Forgets all pending contacts.

@spec get_contact_by_key_prefix(mc(), String.t()) :: map() | nil

Finds a contact by (case-insensitive, possibly partial) hex public key prefix.

@spec get_contact_by_name(mc(), String.t()) :: map() | nil

Finds a contact by (case-insensitive) advertised name.

@spec pending_contacts(mc()) :: %{required(String.t()) => map()}

Contacts advertised but not added (manual-add mode), %{public_key_hex => contact}.

@spec pop_pending_contact(mc(), String.t()) :: map() | nil

Removes and returns a pending contact by full hex public key.

@spec self_info(mc()) :: map()

The device's :self_info payload (empty map before the handshake).

@spec set_auto_update_contacts(mc(), boolean()) :: :ok

Enables or disables automatic contact refresh.

@spec set_decrypt_channel_logs(mc(), boolean()) :: :ok

Enables decryption of group-channel packets seen in the RX log. Needed to annotate :channel_msg_recv events with :path, :snr, :rssi and :recv_time.

@spec set_default_timeout(mc(), pos_integer()) :: :ok

Sets the default command timeout in milliseconds.

@spec start_auto_message_fetching(mc()) :: :ok

Starts pulling queued messages whenever the device announces them (:messages_waiting), and once immediately. The messages show up as :contact_msg_recv / :channel_msg_recv events for subscribers.

@spec start_link(keyword()) :: GenServer.on_start()

Starts a connection process, linked to the caller – the supervised variant of the create_* functions.

Unlike create_tcp/3 and friends it does not block on the device: with connect: true (default) it connects in the background, retrying according to :auto_reconnect. Use connect/1 to wait for the handshake.

Options:

• :transport (required) – {module, options} implementing Meshcore.Transport
• :name – register the process under this name
• :connect – connect right after starting (default true)
• :auto_reconnect – reconnect with exponential backoff (1s, 2s, 4s, 8s…) after the link is lost (default false)
• :max_reconnect_attempts – default 3
• :default_timeout – command timeout in ms (default 15_000)
• :debug / :only_error – raise or lower the log level of this connection (equivalent to Python's flags)

@spec stop(mc()) :: :ok

Synchronously stops the connection process without emitting events.

@spec stop_auto_message_fetching(mc()) :: :ok

Stops automatic message fetching.

@spec subscribe(
  mc(),
  Meshcore.Event.type() | [Meshcore.Event.type()] | nil | :all,
  keyword()
) ::
  {:ok, Meshcore.Subscription.t()}

Subscribes a process to events.

type is an event type (Meshcore.Event.type/0), a list of types, or nil / :all for everything. Matching events are sent to the subscriber as {:meshcore, ref, %Meshcore.Event{}}, ref being subscription.ref.

Options:

• :attribute_filters – map (or keyword list) of attributes the event must carry, e.g. %{channel_idx: 1} or %{pubkey_prefix: "a1b2c3d4e5f6"}
• :pid – the subscriber (default: the calling process)

Subscriptions end when the subscriber exits or on unsubscribe/1.

@spec time(mc()) :: non_neg_integer()

The last device time seen in a :current_time event (0 if never).

@spec unsubscribe(Meshcore.Subscription.t()) :: :ok

Cancels a subscription. Messages already in the mailbox stay there.

@spec wait_for_event(mc(), Meshcore.Event.type() | [Meshcore.Event.type()], keyword()) ::
  {:ok, Meshcore.Event.t()} | {:error, :timeout | :disconnected}

Waits for an event of type (or any of a list of types) matching :attribute_filters.

Returns {:ok, event} or {:error, :timeout}. Options: :attribute_filters, :timeout (ms, default: the connection's default timeout).