Skip to content

fix(ble): handle BLEError with user-friendly messages #894

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lexfrei wants to merge 2 commits into
base: master
Choose a base branch
from
+71 −7
Open

fix(ble): handle BLEError with user-friendly messages #894

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
25ffd25
fix(ble): handle BLEError with user-friendly messages
lexfrei Jan 25, 2026
1fc2407
fix(cli): add timeout error handling for serial connections
lexfrei Jan 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 71 additions & 7 deletions meshtastic/__main__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1365,13 +1365,60 @@ def common():
print(f"Found: name='{x.name}' address='{x.address}'")
meshtastic.util.our_exit("BLE scan finished", 0)
elif args.ble:
client = BLEInterface(
args.ble if args.ble != "any" else None,
debugOut=logfile,
noProto=args.noproto,
noNodes=args.no_nodes,
timeout=args.timeout,
)
try:
client = BLEInterface(
args.ble if args.ble != "any" else None,
debugOut=logfile,
noProto=args.noproto,
noNodes=args.no_nodes,
timeout=args.timeout,
)
except BLEInterface.BLEError as e:
msg = str(e)
if "No Meshtastic BLE peripheral" in msg:
meshtastic.util.our_exit(
"BLE device not found.\n\n"
"Possible causes:\n"
" - Bluetooth is disabled on the Meshtastic device\n"
" - Device is in deep sleep mode\n"
" - Device is out of range\n\n"
"Try:\n"
" - Press the reset button on your device\n"
" - Run 'meshtastic --ble-scan' to see available devices",
1,
)
elif "More than one" in msg:
meshtastic.util.our_exit(
"Multiple Meshtastic BLE devices found.\n\n"
"Please specify which device to connect to:\n"
" - Run 'meshtastic --ble-scan' to list devices\n"
" - Use 'meshtastic --ble <name_or_address>' to connect",
1,
)
elif "Error writing BLE" in msg:
meshtastic.util.our_exit(
"Failed to write to BLE device.\n\n"
"Possible causes:\n"
" - Device requires pairing PIN (check device screen)\n"
" - On Linux: user not in 'bluetooth' group\n"
" - Connection was interrupted\n\n"
"Try:\n"
" - Restart Bluetooth on your computer\n"
" - Reset the Meshtastic device",
1,
)
elif "Error reading BLE" in msg:
meshtastic.util.our_exit(
"Failed to read from BLE device.\n\n"
"The device may have disconnected unexpectedly.\n\n"
"Try:\n"
" - Move closer to the device\n"
" - Reset the Meshtastic device\n"
" - Restart Bluetooth on your computer",
1,
)
else:
meshtastic.util.our_exit(f"BLE error: {e}", 1)
elif args.host:
try:
if ":" in args.host:
Expand Down Expand Up @@ -1427,6 +1474,23 @@ def common():
message += " Please close any applications or webpages that may be using the device and try again.\n"
message += f"\nOriginal error: {ex}"
meshtastic.util.our_exit(message)
except MeshInterface.MeshInterfaceError as ex:
msg = str(ex)
if "Timed out" in msg:
meshtastic.util.our_exit(
"Connection timed out.\n\n"
"Possible causes:\n"
" - Device is rebooting\n"
" - Device firmware is updating\n"
" - Serial connection was interrupted\n\n"
"Try:\n"
" - Wait a few seconds and try again\n"
" - Check if device is fully booted (LED patterns)\n"
" - Reconnect the USB cable",
1,
)
else:
meshtastic.util.our_exit(f"Connection error: {ex}", 1)
if client.devPath is None:
try:
client = meshtastic.tcp_interface.TCPInterface(
Expand Down