Repository navigation
Description
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.
- Add DeviceMetadata.ble_address protobufs#1159 adds
DeviceMetadata.ble_address, the address the BLE stack advertises on. On ESP32 it differs fromUser.macaddr. - Report the BLE address in DeviceMetadata.ble_address firmware#12281 fills it on ESP32 and nRF52. It stays empty on nRF54, RP2xx0, STM32WL and native.
- feat(connections): pair with a PIN from a connect link Meshtastic-Android#7856 adds the
pinparameter to the existingconnectionsdeep link, a PIN variant of its confirm prompt, and PIN entry during bonding. - feat(provision): add labeltastic-provision for QR-code pairing labeltastic#25 provisions nodes over USB: it reads
ble_address, setsFIXED_PINwith a random PIN, and prints the link as a QR label. - feat(ui): show the BLE connect link as a QR code firmware#12303 (open) adds a Pair frame to the Base UI screen that shows the link as a QR code while Bluetooth is enabled.
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
- Accept the link with an
addressand an optionalpin, 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. addressisxfollowed by a BLE address inAA:BB:CC:DD:EE:FFform, ortfollowed by a host and optional port, defaulting to 4403. A platform that has the transport also acceptssfollowed by a serial port, andnalone, which asks to disconnect. A serial port names something local to one machine, so nothing shared should produce anslink. Demo transports are accepted only in debug builds. A link with any other prefix or a malformed address opens the Connect screen without connecting.- Accept
pinonly 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. - 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.
- 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.
- 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.
- The web client opens a
tlink in its HTTP connect flow with the host filled in, ignoring the port. - A link that arrives before onboarding or Bluetooth permission is complete is held and shown once the app can act on it, not dropped.
- 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.
- Provisioning tools write the
meshtastic://form, and pick a PIN from 100000 to 999999.
Acceptance Criteria
- A
FIXED_PINlabel and aRANDOM_PINon-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
- 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.
- Does iOS open a
meshtastic://link from an NFC tag read in the background, or only through the app's own NFC reader? - Should a node on Wi-Fi or Ethernet show a TCP code on its screen? Nothing emits one yet.
Platform Tracking
- Android: Connect links: scanner on the Connect screen, NFC tags, address checks Meshtastic-Android#7971, shipped in feat(connections): scan connect codes, read them from NFC, check addresses Meshtastic-Android#7974; leading-zero PINs rejected in Connect link accepts a PIN with a leading zero (design#177) Meshtastic-Android#7977, shipped in fix(connections): reject connect link and settings PINs with a leading zero Meshtastic-Android#8006
- Apple: Open meshtastic://meshtastic connect links Meshtastic-Apple#2955, shipped in Open meshtastic://meshtastic connect links Meshtastic-Apple#2969, leading-zero PINs ignored in Ignore a connect link PIN with a leading zero Meshtastic-Apple#2970. Left unchecked until hardware evidence from a printed label and an on-screen code
- Web: Accept connect links in the connect flow web#1498
- Firmware: feat(ui): show the BLE connect link as a QR code firmware#12303
- Device UI: Show the connect QR code on MUI device-ui#457
- Labeltastic: Default provisioning links to meshtastic:// labeltastic#32
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsIn Progress
Activity
Ignore a connect link PIN with a leading zero (#2970)