Skip to content

[PARENT] [ALIGNMENT]: Connect to a node from a QR code or NFC tag #177

Open
3 of 4 issues completed
Open

Description

@jamesarich

Decision

A node's connect code, printed as a QR code or written to an NFC tag, carries one link, and every client that can open it handles it the same way:

meshtastic://meshtastic/connections?address=<address>&pin=<PIN>

The address is a BLE node (xAA:BB:CC:DD:EE:FF) or a TCP node (t192.168.1.20:4403). Opening the link shows a "Connect to this device?" prompt with the address and, for a BLE link that has one, the pairing PIN. The user confirms, and the app connects, copying the PIN and pairing first when there is one.

The custom scheme is the only canonical form. Firmware, device-ui and provisioning tools emit meshtastic://. A client that already accepts https://meshtastic.org/connections may keep doing so, but nothing should produce it.

Context

A manufacturer or an event can ship a node with a code that goes from camera to connected without typing a PIN.

A printed label needs FIXED_PIN. The on-screen frame also covers RANDOM_PIN, which is picked once when Bluetooth starts; that path is untested on hardware. In NO_PIN the link carries no pin.

Android and Apple both open meshtastic://meshtastic/...; Apple also keeps routing meshtastic:///.... The custom scheme does nothing when the app is not installed. There is no web fallback: https://meshtastic.org/connections returns 404 and is not in the site's app-site-association.

CoreBluetooth and Web Bluetooth hide a peripheral's hardware address. A browser cannot open a raw TCP socket, so the web client reaches a networked node through the node's HTTP server.

Required Client Behavior

  1. Accept the link with an address and an optional pin, from the camera, an NFC tag, a browser or another app, and from the app's own QR scanner where it has one. Parameter order does not matter.
  2. address is x followed by a BLE address in AA:BB:CC:DD:EE:FF form, or t followed by a host and optional port, defaulting to 4403. A platform that has the transport also accepts s followed by a serial port, and n alone, which asks to disconnect. A serial port names something local to one machine, so nothing shared should produce an s link. Demo transports are accepted only in debug builds. A link with any other prefix or a malformed address opens the Connect screen without connecting.
  3. Accept pin only when it is six ASCII digits from 100000 to 999999 on a BLE address. Firmware stores the PIN as a number, so a leading zero can't survive, and it draws random PINs from the same range. Ignore any other value, including one with a leading zero, and let pairing ask as usual.
  4. Always ask before connecting, since any web page or app can fire this link. The prompt shows the address, and the PIN when there is one; a disconnect link asks the same way. Declining leaves the current connection as it was.
  5. On confirm, copy the PIN to the clipboard, marked sensitive where the platform supports it, then start pairing. Where the platform lets the app answer the PIN request, answer it. Otherwise the system dialog asks and the user pastes.
  6. A client that cannot address a BLE peripheral by hardware address still shows the prompt and copies the PIN, then opens its device picker and lets the user choose.
  7. The web client opens a t link in its HTTP connect flow with the host filled in, ignoring the port.
  8. A link that arrives before onboarding or Bluetooth permission is complete is held and shown once the app can act on it, not dropped.
  9. Firmware and device-ui show a BLE code only while Bluetooth is enabled and the BLE address is known. They do not print the PIN as text next to it.
  10. Provisioning tools write the meshtastic:// form, and pick a PIN from 100000 to 999999.

Acceptance Criteria

  • A FIXED_PIN label and a RANDOM_PIN on-screen code, scanned with the phone camera, reach the confirm prompt on Android and Apple with the right PIN.
  • The same link written to an NFC tag reaches the prompt on Android.
  • Confirming pairs and connects without typing the PIN where the platform allows it, and with one paste where it does not.
  • A TCP link connects on Android and Apple, and opens the HTTP connect flow on Web.
  • A bad PIN, including one with a leading zero, a malformed address or an unknown prefix never connects.
  • Declining the prompt leaves the current connection untouched.
  • A link received on first launch survives onboarding and permission grants.
  • UI evidence covers the prompt with and without a PIN, in light and dark appearances.
  • Hardware evidence covers at least one ESP32 and one nRF52 node.

Questions still to resolve

  1. How should a client without hardware addresses pick out the linked node? The advertised name ends in two bytes of the base MAC, which on ESP32 is not the BLE address. A node number in the link, or the BLE address in advertising data, would give a stable key and let the prompt name the node.
  2. Does iOS open a meshtastic:// link from an NFC tag read in the background, or only through the app's own NFC reader?
  3. Should a node on Wi-Fi or Ethernet show a TCP code on its screen? Nothing emits one yet.

Platform Tracking

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions