Files
meshcore-open/documentation/troubleshooting.md
T
zjs81 5fb67abdde Merge dev; fix share-location and discovered-contact import/export; update docs
Merge dev (#588 share location, #436 discovered-contact import/export)
into fix/review-fixes-and-issue-batch. Conflicts: keep the node-scan
button alongside dev's import/export menu; take dev's marker label
prompt.

Share location (#588):
- Never share a missing or 0,0 radio position; hide the chat action and
  show "Your radio has no location set"
- Sanitise marker labels ('|' -> '/', newlines -> spaces) on every path
- One shared MarkerLabelDialog owning its controller/focus node, with
  keyboard submit, replacing three copies
- Map pins default to "Point of interest" again; "Share my location"
  uses the node name
- Location shares honour the send cooldown and handle send errors

Discovered-contact import/export (#436):
- Per-entry decoding with imported/skipped/invalid counts; reject keys
  that are not 32 bytes; skip in-file duplicates and the radio's own key
- Strip routing paths on import and stop exporting them; clamp future
  timestamps; enforce the discovered-contact cap; require a connection;
  2 MB file limit
- Export via in-memory XFile (fixes web); pass sharePositionOrigin for
  iPad (also GPX export and image save); macOS user-selected read-write
  entitlement for save dialogs

Docs: cover share location, import/export, node scan, TCP reconnect,
channel auto-resend options, arrival ordering, badge, password length
and image limits.

Translations for all new strings in every locale.
2026-10-11 01:54:07 -07:00

30 lines
3.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Connection and Feature Troubleshooting
## BLE radio not found
Confirm that Bluetooth is enabled, the app has Bluetooth permissions, and the radio is running companion firmware advertising the Nordic UART Service UUID. Custom names are supported. Stop other clients that may already hold the connection, bring the radio closer, and scan again. Older Android systems may require location permission for BLE scanning; the app does not use phone GPS for node locations.
On Linux, check that BlueZ is running and the adapter is enabled. Pairing may fall back to `bluetoothctl`; complete the system pairing prompt when requested. Include the pairing error and app log in a bug report.
## USB connection fails
Use a data-capable cable and a supported companion serial firmware. Close terminal programs or other apps using the port. On Linux, check port ownership and the serial-access group required by your distribution. For missing devices, check drivers and OS enumeration. For permission denied, busy, or detached errors, fix the reported cause and refresh the port list.
## Browser connection fails
Use Chrome (or a Chromium browser that identifies as Chrome) and HTTPS (or an appropriate local development secure context). Allow device access through the browser’s serial port chooser. The web build connects over USB via Web Serial only; BLE scanning is not available in the browser and TCP is not supported on web. Native model inference is unavailable on web.
## Unexpected disconnect
BLE and TCP retry an unexpected disconnect with exponential backoff; manual disconnects do not trigger reconnect. USB requires reconnection through its connection screen. If a TCP companion still drops in the background on Android, allow background activity (App Settings → Notifications → **Background Activity**) and check the phone's Wi-Fi power-saving settings. Navigation returns to the scanner when a connection is lost. If reconnect continues to fail, check power, firmware, adapter state, and competing clients.
## Feature unavailable or no data
Companion stats require firmware code 8+, and image channel data requires code 11+. Image inference also needs an enabled, complete model bundle and adequate memory. A missing incoming region label can mean unknown or unavailable metadata, not an unscoped message. See [images](image-messages.md), [regions](regions.md), and [radio stats](radio-statistics.md).
## Useful bug-report details
Include app version, OS/device, radio board and firmware version, transport, reproduction steps, expected behavior, and the exact error. Where relevant, include entries from the **Companion Debug Log** in Settings (frame traffic for BLE, TCP, and USB) or the **App Debug Log**. The App Debug Log only records after you enable App Settings → Debug → **App Debug Logging**. Inspect logs before sharing: they can contain message content, identifiers, and location data.
Run the relevant automated tests when reporting a source/build failure. Submit reports to the [project issue tracker](https://github.com/zjs81/meshcore-open/issues).