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>;