fix: support special command complete

Command complete may not have status as part of the payload according to
the specification: https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host-controller-interface/host-controller-interface-functional-specification.html#UUID-76d31a33-1a9e-07bc-87c4-8ebffee065fd

This breaks controllers that emit this special command complete event.

Add unit test for external controller

Fixes #59

Author: lulf

Cargo.lock

@@ -5,7 +5,7 @@ edition = "2021"
 license = "MIT OR Apache-2.0"
 name = "bt-hci"
 repository = "https://github.com/embassy-rs/bt-hci"
-version = "0.5.0"
+version = "0.6.0"
 documentation = "https://docs.rs/bt-hci"
 keywords = ["bluetooth", "hci", "BLE"]
 categories = ["embedded", "hardware-support", "no-std"]
@@ -38,3 +38,4 @@ serde = { version = "^1", optional = true, features = [
 
 [dev-dependencies]
 postcard = "1.1"
+futures-test = "0.3"

Cargo.toml

@@ -52,6 +52,9 @@ param!(
 );
 
 impl Opcode {
+    /// Special opcode for command events with no associated command
+    pub const UNSOLICITED: Opcode = Opcode::new(OpcodeGroup(0), 0);
+
     /// Create an `Opcode` with the given OGF and OCF values
     pub const fn new(ogf: OpcodeGroup, ocf: u16) -> Self {
         Self(((ogf.0 as u16) << 10) | ocf)

src/cmd.rs

@@ -13,7 +13,7 @@ use embedded_io::ErrorType;
 use futures_intrusive::sync::LocalSemaphore;
 
 use crate::cmd::{Cmd, CmdReturnBuf};
-use crate::event::{CommandComplete, CommandStatus, EventKind};
+use crate::event::{CommandComplete, CommandCompleteWithStatus, CommandStatus, EventKind};
 use crate::param::{RemainingBytes, Status};
 use crate::transport::Transport;
 use crate::{cmd, data, ControllerToHostPacket, FixedSizeValue, FromHciBytes, FromHciBytesError};
@@ -104,6 +104,10 @@ where
                     ControllerToHostPacket::Event(ref event) => match event.kind {
                         EventKind::CommandComplete => {
                             let e = CommandComplete::from_hci_bytes_complete(event.data)?;
+                            if !e.has_status() {
+                                return Ok(value);
+                            }
+                            let e: CommandCompleteWithStatus = e.try_into()?;
                             self.slots.complete(
                                 e.cmd_opcode,
                                 e.status,
@@ -199,6 +203,10 @@ where
                     ControllerToHostPacket::Event(ref event) => match event.kind {
                         EventKind::CommandComplete => {
                             let e = CommandComplete::from_hci_bytes_complete(event.data)?;
+                            if !e.has_status() {
+                                return Ok(value);
+                            }
+                            let e: CommandCompleteWithStatus = e.try_into()?;
                             self.slots.complete(
                                 e.cmd_opcode,
                                 e.status,
@@ -242,7 +250,7 @@ where
 
         let result = slot.wait().await;
         let return_param_bytes = RemainingBytes::from_hci_bytes_complete(&retval.as_ref()[..result.len]).unwrap();
-        let e = CommandComplete {
+        let e = CommandCompleteWithStatus {
             num_hci_cmd_pkts: 0,
             status: result.status,
             cmd_opcode: C::OPCODE,
@@ -412,3 +420,60 @@ impl<F: FnOnce()> Drop for OnDrop<F> {
         unsafe { self.f.as_ptr().read()() }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    pub struct TestTransport<'d> {
+        pub rx: &'d [u8],
+    }
+
+    #[derive(Clone, Copy, Debug, PartialEq)]
+    pub struct Error;
+
+    impl From<FromHciBytesError> for Error {
+        fn from(_: FromHciBytesError) -> Self {
+            Self
+        }
+    }
+
+    impl ErrorType for TestTransport<'_> {
+        type Error = Error;
+    }
+    impl embedded_io::Error for Error {
+        fn kind(&self) -> embedded_io::ErrorKind {
+            embedded_io::ErrorKind::Other
+        }
+    }
+    impl Transport for TestTransport<'_> {
+        fn read<'a>(&self, rx: &'a mut [u8]) -> impl Future<Output = Result<ControllerToHostPacket<'a>, Self::Error>> {
+            async {
+                let to_read = rx.len().min(self.rx.len());
+
+                rx[..to_read].copy_from_slice(&self.rx[..to_read]);
+                let pkt = ControllerToHostPacket::from_hci_bytes_complete(&rx[..to_read])?;
+                Ok(pkt)
+            }
+        }
+
+        fn write<T: crate::HostToControllerPacket>(&self, _val: &T) -> impl Future<Output = Result<(), Self::Error>> {
+            async { todo!() }
+        }
+    }
+
+    #[futures_test::test]
+    pub async fn test_can_handle_unsolicited_command_complete() {
+        let t = TestTransport {
+            rx: &[
+                4, 0x0e, 3, // header
+                1, 0, 0, // special command
+            ],
+        };
+        let c: ExternalController<_, 10> = ExternalController::new(t);
+
+        let mut rx = [0; 255];
+        let pkt = c.read(&mut rx).await;
+        assert!(pkt.is_ok());
+    }
+}

src/controller.rs

@@ -283,8 +283,7 @@ events! {
     struct CommandComplete<'a>(0x0e) {
         num_hci_cmd_pkts: u8,
         cmd_opcode: Opcode,
-        status: Status, // All return parameters have status as the first field
-        return_param_bytes: RemainingBytes<'a>,
+        bytes: RemainingBytes<'a>,
     }
 
     /// Command Status event [📖](https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host-controller-interface/host-controller-interface-functional-specification.html#UUID-4d87067c-be74-d2ff-d5c4-86416bf7af91)
@@ -736,6 +735,44 @@ impl<'de> ReadHci<'de> for Event<'de> {
 }
 
 impl CommandComplete<'_> {
+    /// Whether or not this event has a status
+    pub fn has_status(&self) -> bool {
+        self.cmd_opcode != Opcode::UNSOLICITED
+    }
+}
+
+impl<'d> TryFrom<CommandComplete<'d>> for CommandCompleteWithStatus<'d> {
+    type Error = FromHciBytesError;
+    fn try_from(e: CommandComplete<'d>) -> Result<CommandCompleteWithStatus<'d>, Self::Error> {
+        if e.cmd_opcode == Opcode::UNSOLICITED {
+            return Err(FromHciBytesError::InvalidSize);
+        }
+        let bytes = e.bytes.into_inner();
+        let (status, remaining) = Status::from_hci_bytes(bytes)?;
+        let return_param_bytes: RemainingBytes<'d> = RemainingBytes::from_hci_bytes_complete(remaining)?;
+        Ok(Self {
+            num_hci_cmd_pkts: e.num_hci_cmd_pkts,
+            cmd_opcode: e.cmd_opcode,
+            status,
+            return_param_bytes,
+        })
+    }
+}
+
+/// Struct representing a command complete event with status
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CommandCompleteWithStatus<'d> {
+    /// Number of packets complete.
+    pub num_hci_cmd_pkts: u8,
+    /// Command opcode.
+    pub cmd_opcode: Opcode,
+    /// Command status.
+    pub status: Status,
+    /// Return parameters
+    pub return_param_bytes: RemainingBytes<'d>,
+}
+
+impl CommandCompleteWithStatus<'_> {
     /// Gets the connection handle associated with the command that has completed.
     ///
     /// For commands that return the connection handle provided as a parameter as
@@ -921,6 +958,7 @@ impl InquiryResultWithRssi<'_> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::cmd::OpcodeGroup;
     use crate::event::le::LeEventPacket;
     use crate::param::*;
 
@@ -1273,4 +1311,36 @@ mod tests {
         assert_eq!(e.handle, ConnHandle::new(1));
         assert!(matches!(e.central_clock_accuracy, ClockAccuracy::Ppm250));
     }
+
+    #[test]
+    fn test_special_command_complete() {
+        let data = [
+            0x0e, 3, // header
+            1, 0, 0, // special command
+        ];
+
+        let event = EventPacket::from_hci_bytes_complete(&data).unwrap();
+        assert!(matches!(event.kind, EventKind::CommandComplete));
+        let event = CommandComplete::from_hci_bytes_complete(event.data).unwrap();
+        assert_eq!(event.cmd_opcode, Opcode::new(OpcodeGroup::new(0), 0));
+    }
+
+    #[test]
+    fn test_normal_command_complete() {
+        let opcode = Opcode::new(OpcodeGroup::LE, 0x000D).to_raw().to_le_bytes();
+        let data = [
+            0x0e, 4, // header
+            1, opcode[0], opcode[1], // special command
+            0,         // success
+        ];
+
+        let event = EventPacket::from_hci_bytes_complete(&data).unwrap();
+        assert!(matches!(event.kind, EventKind::CommandComplete));
+        let event = CommandComplete::from_hci_bytes_complete(event.data).unwrap();
+        assert_eq!(event.cmd_opcode, Opcode::new(OpcodeGroup::LE, 0x000d));
+
+        let event: CommandCompleteWithStatus = event.try_into().unwrap();
+        assert_eq!(event.cmd_opcode, Opcode::new(OpcodeGroup::LE, 0x000d));
+        assert_eq!(Status::SUCCESS, event.status);
+    }
 }

src/event.rs

@@ -62,6 +62,12 @@ impl<'a> FromHciBytes<'a> for RemainingBytes<'a> {
     }
 }
 
+impl<'a> RemainingBytes<'a> {
+    pub(crate) fn into_inner(self) -> &'a [u8] {
+        self.0
+    }
+}
+
 param!(struct BdAddr([u8; 6]));
 
 impl BdAddr {