feat: structured BLE connection error handling - #67
Open
cinderblock wants to merge 1 commit into
Open
Conversation
Add custom exception hierarchy to distinguish between three failure modes: - DeviceNotFoundError: device not in range or powered off - ConnectionFailedError: device found but busy (another client connected) - EncryptionHandshakeError: connected but ECDH failed (likely a bug — message directs users to open a GitHub issue) Each exception carries an actionable message explaining what went wrong and what the user should do about it. Also reduces establish_connection max_attempts from 10 to 3 to fail faster when the device is busy instead of wasting 60+ seconds retrying. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
DeviceNotFoundError,ConnectionFailedError,EncryptionHandshakeError(all extendBluettiBluetoothError)return Noneerror handling inDeviceReader,DeviceWriter, andDeviceRecognizerwith stage-specific exceptions carrying actionable messagesestablish_connectionmax_attempts from 10 to 3 so busy-device detection fails in ~10s instead of 60+Why
When BLE communication fails, the library returns
Nonewith a vague "Timeout" log. Users (especially via Home Assistant) can't tell if the device is:DeviceNotFoundError: "Move closer to the device and ensure it is turned on."ConnectionFailedError: "Another Bluetooth client (such as the Bluetti app) may already be connected."EncryptionHandshakeError: "This may indicate a library bug. Please open an issue."Each case now raises a typed exception with a clear, actionable message. Callers can catch
BluettiBluetoothErrorfor uniform handling or catch specific subclasses.Changes
bluetooth/exceptions.pybluetooth/device_reader.pybluetooth/device_writer.pybluetooth/device_recognizer.pyDeviceNotFoundError, continues on othersbluetooth/__init__.py__init__.pyTest plan
BluettiBluetoothError🤖 Generated with Claude Code