Files
meshcore-open/documentation/troubleshooting.md
T
zjs81 aa00a863c3 Refresh documentation and update Dutch translation
Documentation:
- Correct web transport support: USB via Web Serial in Chrome only; no
  BLE or TCP in the browser.
- Fix region scope semantics, routing modes (Auto/Flood/Manual), the
  156-byte DM limit, repeater CLI framing, the guessed-location algorithm,
  radio stats contents and settings labels.
- Add regions, image messages, radio statistics and troubleshooting guides.
- Restore coding conventions, localization workflow, storage scoping and
  transport entry points to CLAUDE.md/AGENTS.md; align build/CI commands.
- Replace the obsolete docs/BLE_PROTOCOL.md with a pointer to the
  maintained protocol reference.

Dutch (nl):
- Translate the 79 missing strings and correct existing mistranslations,
  typos and grammar (e.g. "Uitzoomen", "Handmatig", "Slowaaks", frequency
  range 150-2500 MHz).
- Use consistent terminology and informal "je" throughout; keep mesh terms
  such as repeater, node, flood, hop and advert in English.

Fixes #538
2026-09-27 13:12:23 -07:00

2.8 KiB
Raw Blame History

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 can retry an unexpected disconnect with exponential backoff; manual disconnects do not trigger reconnect. USB and TCP require reconnection through their connection screens. 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, regions, and radio stats.

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.