Skip to main content

combustion_rust_ble/
error.rs

1//! Error types for the combustion-rust-ble crate.
2
3use thiserror::Error;
4
5/// The main error type for this crate.
6#[derive(Error, Debug)]
7pub enum Error {
8    /// Bluetooth-related error from the underlying BLE library.
9    #[error("Bluetooth error: {0}")]
10    Bluetooth(#[from] btleplug::Error),
11
12    /// Bluetooth is not available or is disabled on this system.
13    #[error("Bluetooth not available or disabled")]
14    BluetoothUnavailable,
15
16    /// The specified probe was not found.
17    #[error("Probe not found: {identifier}")]
18    ProbeNotFound {
19        /// The identifier that was searched for.
20        identifier: String,
21    },
22
23    /// Operation requires a connection but the probe is not connected.
24    #[error("Probe not connected")]
25    NotConnected,
26
27    /// Failed to establish a connection to the probe.
28    #[error("Connection failed: {reason}")]
29    ConnectionFailed {
30        /// Description of why the connection failed.
31        reason: String,
32    },
33
34    /// The connection to the probe was lost.
35    #[error("Connection lost")]
36    ConnectionLost,
37
38    /// The peripheral disconnected during connection setup (e.g. between service discovery
39    /// and characteristic subscription). Cached GATT handles are stale and must be rebuilt
40    /// by a full disconnect + reconnect.
41    ///
42    /// Note: this variant uses `context` (not `reason`) to match the integrator
43    /// usage already in the wild. Stylistic inconsistency with `ConnectionFailed { reason }`
44    /// is accepted as a deliberate trade-off.
45    #[error("Device disconnected during setup: {context}")]
46    DeviceDisconnectedDuringSetup {
47        /// Description of which setup step detected the stale connection.
48        context: String,
49    },
50
51    /// Invalid data was received from the probe.
52    #[error("Invalid data received: {context}")]
53    InvalidData {
54        /// Description of what was invalid about the data.
55        context: String,
56    },
57
58    /// CRC check failed for a UART message.
59    #[error("CRC mismatch: expected {expected:#06x}, got {actual:#06x}")]
60    CrcMismatch {
61        /// The expected CRC value.
62        expected: u16,
63        /// The actual CRC value received.
64        actual: u16,
65    },
66
67    /// A UART message response timed out.
68    #[error("UART message timeout")]
69    Timeout,
70
71    /// The requested operation is not supported.
72    #[error("Operation not supported: {operation}")]
73    NotSupported {
74        /// Description of the unsupported operation.
75        operation: String,
76    },
77
78    /// The probe reported an error.
79    #[error("Probe reported error: {message}")]
80    ProbeError {
81        /// The error message from the probe.
82        message: String,
83    },
84
85    /// The maximum number of probes has been reached.
86    #[error("Maximum probes ({max}) already connected")]
87    MaxProbesReached {
88        /// The maximum number of probes allowed.
89        max: usize,
90    },
91
92    /// An invalid parameter was provided.
93    #[error("Invalid parameter: {name} = {value}")]
94    InvalidParameter {
95        /// The name of the parameter.
96        name: String,
97        /// The invalid value that was provided.
98        value: String,
99    },
100
101    /// An internal error occurred.
102    #[error("Internal error: {0}")]
103    Internal(String),
104
105    /// Characteristic not found on the device.
106    #[error("Characteristic not found: {uuid}")]
107    CharacteristicNotFound {
108        /// The UUID of the characteristic that was not found.
109        uuid: String,
110    },
111
112    /// Service not found on the device.
113    #[error("Service not found: {uuid}")]
114    ServiceNotFound {
115        /// The UUID of the service that was not found.
116        uuid: String,
117    },
118
119    /// The platform reports that a scan is already running on this adapter.
120    ///
121    /// Returned by `start_scanning` when another party (typically the host
122    /// application) owns the adapter scan — on BlueZ this is
123    /// `org.bluez.Error.InProgress`. Fall back to `attach` to consume the existing
124    /// scan instead of owning one.
125    #[error("A scan is already in progress on this adapter; use attach()")]
126    ScanInProgress,
127
128    /// Scanning is already active in a different [`ScanMode`](crate::ScanMode).
129    ///
130    /// Returned when `attach` is called on a manager that owns its scan, or
131    /// `start_scanning` is called on a manager that is attached to the host's scan.
132    /// Stop scanning first, then start in the desired mode.
133    #[error("Scan already active in {current:?} mode; requested {requested:?}")]
134    ScanModeMismatch {
135        /// The mode the scan is currently running in.
136        current: crate::ScanMode,
137        /// The mode that was requested.
138        requested: crate::ScanMode,
139    },
140}
141
142/// A specialized Result type for this crate.
143pub type Result<T> = std::result::Result<T, Error>;