bluest 0.6.9

A cross-platform Bluetooth Low Energy (BLE) library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237

//! Bluest errors

/// The error type for Bluetooth operations
#[derive(Debug)]
pub struct Error {
    kind: ErrorKind,
    source: Option<Box<dyn std::error::Error + Send + Sync + 'static>>,
    message: String,
}

impl Error {
    pub(crate) fn new<S: ToString>(
        kind: ErrorKind,
        source: Option<Box<dyn std::error::Error + Send + Sync + 'static>>,
        message: S,
    ) -> Self {
        Error {
            kind,
            source,
            message: message.to_string(),
        }
    }

    /// Returns the corresponding [`ErrorKind`] for this error.
    pub fn kind(&self) -> ErrorKind {
        self.kind
    }

    /// Returns the message for this error.
    pub fn message(&self) -> &str {
        &self.message
    }
}

impl std::fmt::Display for Error {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match (self.message.is_empty(), &self.source) {
            (true, None) => write!(f, "{}", &self.kind),
            (false, None) => write!(f, "{}: {}", &self.kind, &self.message),
            (true, Some(err)) => write!(f, "{}: {} ({})", &self.kind, &self.message, err),
            (false, Some(err)) => write!(f, "{}: {}", &self.kind, err),
        }
    }
}

impl std::error::Error for Error {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        self.source.as_ref().map(|x| {
            let x: &(dyn std::error::Error + 'static) = &**x;
            x
        })
    }
}

/// A list of general categories of Bluetooth error.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum ErrorKind {
    /// the Bluetooth adapter is not available
    AdapterUnavailable,
    /// the Bluetooth adapter is already scanning
    AlreadyScanning,
    /// connection failed
    ConnectionFailed,
    /// the Bluetooth device isn't connected
    NotConnected,
    /// the Bluetooth operation is unsupported
    NotSupported,
    /// permission denied
    NotAuthorized,
    /// not ready
    NotReady,
    /// not found
    NotFound,
    /// invalid paramter
    InvalidParameter,
    /// timed out
    Timeout,
    /// protocol error: {0}
    Protocol(AttError),
    /// an internal error has occured
    Internal,
    /// the service changed and is no longer valid
    ServiceChanged,
    /// error
    Other,
}

impl std::fmt::Display for ErrorKind {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ErrorKind::AdapterUnavailable => f.write_str("the Bluetooth adapter is not available"),
            ErrorKind::AlreadyScanning => f.write_str("the Bluetooth adapter is already scanning"),
            ErrorKind::ConnectionFailed => f.write_str("connection failed"),
            ErrorKind::NotConnected => f.write_str("the Bluetooth device isn't connected"),
            ErrorKind::NotSupported => f.write_str("the Bluetooth operation is unsupported"),
            ErrorKind::NotAuthorized => f.write_str("permission denied"),
            ErrorKind::NotReady => f.write_str("not ready"),
            ErrorKind::NotFound => f.write_str("not found"),
            ErrorKind::InvalidParameter => f.write_str("invalid paramter"),
            ErrorKind::Timeout => f.write_str("timed out"),
            ErrorKind::Protocol(err) => write!(f, "protocol error: {}", err),
            ErrorKind::Internal => f.write_str("an internal error has occured"),
            ErrorKind::ServiceChanged => f.write_str("the service changed and is no longer valid"),
            ErrorKind::Other => f.write_str("error"),
        }
    }
}

impl From<ErrorKind> for Error {
    fn from(kind: ErrorKind) -> Self {
        Error {
            kind,
            source: None,
            message: String::new(),
        }
    }
}

/// Bluetooth Attribute Protocol error. See the Bluetooth Core Specification, Vol 3, Part F, §3.4.1.1
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct AttError(u8);

impl AttError {
    /// The operation completed successfully.
    pub const SUCCESS: AttError = AttError(0x00);
    /// The attribute handle given was not valid on this server.
    pub const INVALID_HANDLE: AttError = AttError(0x01);
    /// The attribute cannot be read.
    pub const READ_NOT_PERMITTED: AttError = AttError(0x02);
    /// The attribute cannot be written.
    pub const WRITE_NOT_PERMITTED: AttError = AttError(0x03);
    /// The attribute PDU was invalid.
    pub const INVALID_PDU: AttError = AttError(0x04);
    /// The attribute requires authentication before it can be read or written.
    pub const INSUFFICIENT_AUTHENTICATION: AttError = AttError(0x05);
    /// Attribute server does not support the request received from the client.
    pub const REQUEST_NOT_SUPPORTED: AttError = AttError(0x06);
    /// Offset specified was past the end of the attribute.
    pub const INVALID_OFFSET: AttError = AttError(0x07);
    /// The attribute requires authorization before it can be read or written.
    pub const INSUFFICIENT_AUTHORIZATION: AttError = AttError(0x08);
    /// Too many prepare writes have been queued.
    pub const PREPARE_QUEUE_FULL: AttError = AttError(0x09);
    /// No attribute found within the given attribute handle range.
    pub const ATTRIBUTE_NOT_FOUND: AttError = AttError(0x0a);
    /// The attribute cannot be read or written using the Read Blob Request.
    pub const ATTRIBUTE_NOT_LONG: AttError = AttError(0x0b);
    /// The Encryption Key Size used for encrypting this link is insufficient.
    pub const INSUFFICIENT_ENCRYPTION_KEY_SIZE: AttError = AttError(0x0c);
    /// The attribute value length is invalid for the operation.
    pub const INVALID_ATTRIBUTE_VALUE_LENGTH: AttError = AttError(0x0d);
    /// The attribute request that was requested has encountered an error that was unlikely, and therefore could not be completed as requested.
    pub const UNLIKELY_ERROR: AttError = AttError(0x0e);
    /// The attribute requires encryption before it can be read or written.
    pub const INSUFFICIENT_ENCRYPTION: AttError = AttError(0x0f);
    /// The attribute type is not a supported grouping attribute as defined by a higher layer specification.
    pub const UNSUPPORTED_GROUP_TYPE: AttError = AttError(0x10);
    /// Insufficient Resources to complete the request.
    pub const INSUFFICIENT_RESOURCES: AttError = AttError(0x11);
    /// The server requests the client to rediscover the database.
    pub const DATABASE_OUT_OF_SYNC: AttError = AttError(0x12);
    /// The attribute parameter value was not allowed.
    pub const VALUE_NOT_ALLOWED: AttError = AttError(0x13);
    /// Write Request Rejected
    pub const WRITE_REQUEST_REJECTED: AttError = AttError(0xfc);
    /// Client Characteristic Configuration Descriptor Improperly Configured
    pub const CCCD_IMPROPERLY_CONFIGURED: AttError = AttError(0xfd);
    /// Procedure Already in Progress
    pub const PROCEDURE_ALREADY_IN_PROGRESS: AttError = AttError(0xfe);
    /// Out of Range
    pub const OUT_OF_RANGE: AttError = AttError(0xff);

    /// Converts a [`u8`] value to an [`AttError`].
    pub const fn from_u8(val: u8) -> Self {
        AttError(val)
    }

    /// Converts an [`AttError`] to a [`u8`] value.
    pub const fn as_u8(self) -> u8 {
        self.0
    }

    /// Checks if the error code is in the application error range.
    pub fn is_application(&self) -> bool {
        (0x80..0xa0).contains(&self.0)
    }

    /// Checks if the error code is in the common profile and service range.
    pub fn is_common_profile_or_service(&self) -> bool {
        self.0 >= 0xe0
    }
}

impl std::fmt::Display for AttError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match *self {
            AttError::SUCCESS => f.write_str("The operation completed successfully."),
            AttError::INVALID_HANDLE => f.write_str("The attribute handle given was not valid on this server."),
            AttError::READ_NOT_PERMITTED => f.write_str("The attribute cannot be read."),
            AttError::WRITE_NOT_PERMITTED => f.write_str("The attribute cannot be written."),
            AttError::INVALID_PDU => f.write_str("The attribute PDU was invalid."),
            AttError::INSUFFICIENT_AUTHENTICATION => f.write_str("The attribute requires authentication before it can be read or written."),
            AttError::REQUEST_NOT_SUPPORTED => f.write_str("Attribute server does not support the request received from the client."),
            AttError::INVALID_OFFSET => f.write_str("Offset specified was past the end of the attribute."),
            AttError::INSUFFICIENT_AUTHORIZATION => f.write_str("The attribute requires authorization before it can be read or written."),
            AttError::PREPARE_QUEUE_FULL => f.write_str("Too many prepare writes have been queued."),
            AttError::ATTRIBUTE_NOT_FOUND => f.write_str("No attribute found within the given attribute handle range."),
            AttError::ATTRIBUTE_NOT_LONG => f.write_str("The attribute cannot be read or written using the Read Blob Request."),
            AttError::INSUFFICIENT_ENCRYPTION_KEY_SIZE => f.write_str("The Encryption Key Size used for encrypting this link is insufficient."),
            AttError::INVALID_ATTRIBUTE_VALUE_LENGTH => f.write_str("The attribute value length is invalid for the operation."),
            AttError::UNLIKELY_ERROR => f.write_str("The attribute request that was requested has encountered an error that was unlikely, and therefore could not be completed as requested."),
            AttError::INSUFFICIENT_ENCRYPTION => f.write_str("The attribute requires encryption before it can be read or written."),
            AttError::UNSUPPORTED_GROUP_TYPE => f.write_str("The attribute type is not a supported grouping attribute as defined by a higher layer specification."),
            AttError::INSUFFICIENT_RESOURCES => f.write_str("Insufficient Resources to complete the request."),
            AttError::DATABASE_OUT_OF_SYNC => f.write_str("The server requests the client to rediscover the database."),
            AttError::VALUE_NOT_ALLOWED => f.write_str("The attribute parameter value was not allowed."),
            AttError::WRITE_REQUEST_REJECTED => f.write_str("Write Request Rejected"),
            AttError::CCCD_IMPROPERLY_CONFIGURED => f.write_str("Client Characteristic Configuration Descriptor Improperly Configured"),
            AttError::PROCEDURE_ALREADY_IN_PROGRESS => f.write_str("Procedure Already in Progress"),
            AttError::OUT_OF_RANGE => f.write_str("Out of Range"),
            _ => f.write_str(&format!("Unknown error 0x{:02x}", self.0)),
        }
    }
}

impl From<u8> for AttError {
    fn from(number: u8) -> Self {
        AttError(number)
    }
}

impl From<AttError> for u8 {
    fn from(val: AttError) -> Self {
        val.0
    }
}