Crate bluetooth_hci[−][src]

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 and event_link modules, and merge uart up into host. 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, the event_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
require_len_at_least

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 `Status`.
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 BdAddr in a BdAddrType.