Migrating from Python

The library mirrors meshcore_py; names translate mechanically.

The five rules

1. mc.commands.foo(args) → Meshcore.Commands.foo(mc, args), with the connection first. Optional/keyword arguments become a keyword list: send_msg(c, "x", timestamp: 1).
2. Results are tagged: result.type == EventType.ERROR ⇒ {:error, %Event{}}; otherwise {:ok, %Event{}}. The event still has .type, .payload, .attributes.
3. Timeouts are milliseconds (timeout=5 ⇒ timeout: 5_000). 0/None for "derive from the device's suggestion" ⇒ omit the option.
4. Dict keys are atoms, lower-case: payload["SNR"] ⇒ payload.snr, "fw ver" ⇒ :fw_ver. Event types are lower-case atoms: EventType.CONTACT_MSG_RECV ⇒ :contact_msg_recv.
5. Callbacks become messages: subscribe(type, async_cb, filters) ⇒ subscribe, then handle {:meshcore, ref, %Event{}}.

Connection

State & helpers

Events

Commands: return values that are not plain events

Python's *_sync helpers return a payload or None; the Elixir ones return {:ok, payload} or {:error, event} (the event tells you why, e.g. reason: :timeout):

Programmer errors (malformed destination, bad key length, payload too short …) raise ArgumentError where Python raised ValueError.

Argument conventions

• Destinations accept a contact map, a hex string or raw bytes. (Python's bytes vs str distinction doesn't exist for Elixir binaries; hex-looking binaries that are long enough are read as hex.)
• Hex or bytes parameters that Python lets you pass as str (send_raw_packet) take raw binaries or {:hex, "…"}.
• Trace path: a comma-separated hex string, or {:raw, binary} for Python's bytes.
• Flood scope: a string name, "*", nil, or {:key, binary} for Python's raw bytes.
• send_advert(flood=True) ⇒ send_advert(mc, true).
• get_contacts(lastmod=…, timeout=…) ⇒ get_contacts(mc, lastmod: …, timeout: …).
• sign(data, chunk_size, timeout) ⇒ sign(mc, data, chunk_size: …, timeout: …).

Payload key differences

• "SNR"/"RSSI" ⇒ :snr/:rssi; "SNR_in" ⇒ :snr_in; "fw ver" ⇒ :fw_ver.
• reason strings that the library generates are atoms: :timeout, :no_event_received, :not_connected, :disconnected, :invalid_frame_length, :path_reset_failed, :invalid_timestamp_format, :invalid_path_format, :data_too_large, …
• DISABLED carries reason: :private_key_export_disabled.
• Contact type, flags, out_path_len (-1 = flood) etc. are unchanged.
• Telemetry LPP entries are %{channel:, type:, value:}; numeric values with scale 1 are integers (Python: floats).

Deliberate differences

• Exponential backoff (1/2/4/8 s) for reconnects, as the Python README documents (the Python code actually sleeps a flat second).
• start_auto_message_fetching drains the whole queue immediately instead of fetching a single message.
• Pending commands fail at once on disconnect instead of waiting for their timeout.
• Concurrent commands are answered in send order rather than "everyone gets the first match".
• Sync requests can't lose a fast response (see Fault tolerance).
• Contact updates (reset_path, update_contact, …) update the client's mirrored list only after the device confirmed them.
• Over-long contact names are truncated to 32 bytes instead of producing a malformed frame.
• Meshcore.disconnect/1 ends the connection process (it is the Python disconnect() that cleans up everything); to connect again start a new connection.

A complete translation

Python:

mc = await MeshCore.create_serial("/dev/ttyUSB0")
await mc.ensure_contacts()
contact = mc.get_contact_by_name("Alice")
result = await mc.commands.send_msg(contact, "hi")
if result.type == EventType.ERROR:
    print(result.payload)
else:
    ack = await mc.wait_for_event(
        EventType.ACK,
        attribute_filters={"code": result.payload["expected_ack"].hex()},
        timeout=30,
    )
await mc.disconnect()

Elixir:

{:ok, mc} = Meshcore.create_serial("/dev/ttyUSB0")
Meshcore.ensure_contacts(mc)
contact = Meshcore.get_contact_by_name(mc, "Alice")

case Meshcore.Commands.send_msg(mc, contact, "hi") do
  {:error, event} ->
    IO.inspect(event.payload)

  {:ok, event} ->
    code = Base.encode16(event.payload.expected_ack, case: :lower)
    Meshcore.wait_for_event(mc, :ack, attribute_filters: %{code: code}, timeout: 30_000)
end

Meshcore.disconnect(mc)

Example index