[−][src]Crate bluetooth_hci
A Bluetooth implementation for embedded systems.
This crate is a proof-of-concept implementation of the host (application) side of the
Bluetooth
specification. It is still woefully incomplete, and will undoubtedly be redesigned
completely, and potentially split into multiple crates before being stabilized.
When the documentation refers to a specific section of "the" Bluetooth specification, the same section applies for all supported versions of the specification. If the versions differ, the specific version will also be included in the reference.
Design
Like other core embedded crates (e.g, embedded-hal
), this crate uses traits to be agnostic
about the specific Bluetooth module. It provides a default implementation of the HCI for devices
that implement the core Controller
trait. The traits also make use of the nb
crate to
support different asynchronous or synchronous operation modes.
Commands
The host::Hci
trait defines all of the functions that communicate from the host to the
controller. The host::uart::Hci
trait defines a read function that returns a
host::uart::Packet
, which can contain an Event
, AclData
(TODO), or SyncData
(TODO). Both of these traits have default implementations in terms of the Controller
, so
calling code does not need to implement any commands or event parsing code.
Vendor-specific commands and events
The host::uart::Hci
trait requires specialization for the type of vendor-specific events
(which implement event::VendorEvent
) and vendor-specific errors. Any vendor-specific
extensions will need to convert byte buffers into the appropriate event type (as defined by the
vendor), but will not need to read data using the Controller
. The Bluetooth standard
provides packet length in a common header, so only complete packets will be passed on to the
vendor code for deserialization.
There is not yet support for vendor-specific commands. The vendor crate will have to serialize
the command packets directly and write them to the Controller
.
Reference implementation
The bluenrg
crate provides a sample implementation for STMicro's BlueNRG Bluetooth
controllers.
Ideas for discussion and improvement
-
Add traits to facilitate writing Bluetooth controllers. These controllers would have a host on one side and a link layer on the other. Separate crate? If so, move common definitions (Status codes, opcodes, etc.) to a bluetooth-core crate.
-
Add a helper function for vendor-specific commands. This should take care of creating the header and writing the data to the
Controller
. Vendor code should only be responsible for serializing commands into byte slices. -
Remove the
cmd_link
andevent_link
modules, and mergeuart
up intohost
. The Bluetooth spec made it seem like there were devices that do not include the packet type byte at the beginning of packets, but STMicro's BlueNRG implementation and Nordic's Zephyr implementation both include it. If there is a controller that does not include the packet type, theevent_link
HCI can always be brought back. -
Provide config features for different versions of the Bluetooth Specification.
-
Implement all of the specified functions and events.
-
Provide opt-in config features for certain types of commands and events. For example, BlueNRG devices only implement 40 commands and 14 events, but the spec has around 250 commands and 76 events. It would be nice if unused events could be compiled out. This would be less important for commands, since those functions would simply never be called, and could be removed by the linker. This would entail significant work both on the part of the crate authors and on crate users, who would need to configure the crate appropriately. All combinations of features would also never be tested; there are simply too many, even if we only provide features for the events. On the other hand, those features should not interact, so maybe it would be feasible.
Re-exports
pub use event::Event; |
Modules
event | Bluetooth events and event deserialization. |
host | Host-side interface to the Bluetooth HCI. |
types | Common types for Bluetooth commands and events. |
Macros
require_len | Verifies that the length of the LHS expression is exactly the RHS expression. Fails with a
|
require_len_at_least | Verifies that the length of the LHS expression is greater than or equal to the RHS expression.
Fails with a |
Structs
BdAddr | Newtype for BDADDR. |
BdAddrTypeError | The BD Address type is not recognized. Includes the unrecognized byte. |
ChannelClassification | Channel classifications for the LE Set Host Channel Classification command. |
ConnectionHandle | Newtype for a connection handle. |
LinkLayerFeature | Bitfield for LE Remote Features. |
Opcode | Newtype wrapper for a Bluetooth Opcode. Opcodes are used to indicate which command to send to the Controller as well as which command results are returned by the Command Complete and Command Status events. |
Enums
BadStatusError | Wrapper enum for errors converting a u8 into a |
BdAddrType | Potential values for BDADDR |
Status | List of possible error codes, Bluetooth Spec, Vol 2, Part D, Section 2. |
Traits
Controller | Interface to the Bluetooth controller from the host's perspective. |
Vendor | Trait defining vendor-specific extensions for the Bluetooth Controller. |
Functions
to_bd_addr_type | Wraps a |