Add some more documentation to the half-completed Bluetooth Host demo, fix the OpenChannel() command initialising the channel information structure to the wrong initial state once the CONNECTION REQUEST command has been sent to the remote device.

3 files changed, 50 insertions, 18 deletions

diff --git a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.c b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.c
index 449d57fb2..10560f9c8 100644
--- a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.c
+++ b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothACLPackets.c
@@ -230,7 +230,7 @@ Bluetooth_Channel_t* Bluetooth_OpenChannel(uint16_t PSM)
 	ChannelData->RemoteNumber = 0;

 	ChannelData->PSM          = PSM;

 	ChannelData->LocalMTU     = MAXIMUM_CHANNEL_MTU;

-	ChannelData->State        = Channel_Config_WaitConfig;

+	ChannelData->State        = Channel_WaitConnectRsp;

 	  

 	struct

 	{

@@ -356,7 +356,7 @@ static inline void Bluetooth_Signal_ConnectionResp(BT_ACL_Header_t* ACLPacketHea
 	BT_ACL_DEBUG(2, "-- Source Channel: 0x%04X", ConnectionResponse.SourceChannel);	

 	BT_ACL_DEBUG(2, "-- Destination Channel: 0x%04X", ConnectionResponse.DestinationChannel);	

 

-	Bluetooth_Channel_t* ChannelData = Bluetooth_GetChannelData(ConnectionResponse.DestinationChannel, false);

+	Bluetooth_Channel_t* ChannelData = Bluetooth_GetChannelData(ConnectionResponse.SourceChannel, false);

 

 	if (ChannelData != NULL)

 	{

diff --git a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.c b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.c
index ec1f637d7..d990ba02e 100644
--- a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.c
+++ b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.c
@@ -43,26 +43,46 @@ Bluetooth_Device_t Bluetooth_DeviceConfiguration =
 		Name:    "LUFA Bluetooth Demo"

 	};

 

+/** Bluetooth stack initialization function. This function must be called once to initialize the Bluetooth stack,

+ *  ready for connection to remote devices.

+ *

+ *  \note This function only begins the initialization process; the stack is initialized as the main Bluetooth stack

+ *        management task is repeatedly called. The initialization process ends when the \ref Bluetooth_HCIProcessingState

+ *        global enters the Bluetooth_ProcessEvents state.

+ */

 void Bluetooth_Stack_Init(void)

 {

+	/* Reset the HCI state machine - this will eventually reset the adapter and stack when the Bluetooth stack task is called */

 	Bluetooth_HCIProcessingState = Bluetooth_Init;

 }

 

+/** Bluetooth stack management task. This task must be repeatedly called to maintain the Bluetooth stack and any connection

+ *  to remote Bluetooth devices, including both the HCI control layer and the ACL channel layer.

+ */

 void Bluetooth_Stack_USBTask(void)

 {

 	Bluetooth_HCITask();

 	Bluetooth_ACLTask();

 }

 

+/** Retrieves the channel information structure with the given local or remote channel number from the channel list.

+ *

+ *  \param ChannelNumber          Channel number to search for in the channel list

+ *  \param SearchByRemoteChannel  Indicated whether to search for a channel information structure by the given remote channel

+ *                                or local channel number

+ *

+ *  \return Pointer to the matching channel information structure in the channel table if found, NULL otherwise

+ */

 Bluetooth_Channel_t* Bluetooth_GetChannelData(uint16_t ChannelNumber, bool SearchByRemoteChannel)

 {

 	for (uint8_t i = 0; i < BLUETOOTH_MAX_OPEN_CHANNELS; i++)

 	{

 		Bluetooth_Channel_t* ChannelData = &Bluetooth_Connection.Channels[i];

 	

-		uint16_t CurrentChannelNumber = (SearchByRemoteChannel) ? ChannelData->RemoteNumber : ChannelData->LocalNumber;

+		/* Fetch the channel number that is to be matched against from the current channel information struct */

+		uint16_t SearchChannelNumber = (SearchByRemoteChannel) ? ChannelData->RemoteNumber : ChannelData->LocalNumber;

 	

-		if (CurrentChannelNumber == ChannelNumber)

+		if (SearchChannelNumber == ChannelNumber)

 		  return ChannelData;

 	}

 

diff --git a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.h b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.h
index fa30524a9..4de49b355 100644
--- a/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.h
+++ b/Demos/Host/Incomplete/BluetoothHost/Lib/BluetoothStack.h
@@ -56,28 +56,36 @@
 		#define MAXIMUM_CHANNEL_MTU                      255

 		

 	/* Enums: */

+		/** Enum for the possible states for a bluetooth ACL channel. */

 		enum BT_ChannelStates_t

 		{

-			Channel_Closed                = 0,

-			Channel_WaitConnect           = 1,

-			Channel_WaitConnectRsp        = 2,

-			Channel_Config_WaitConfig     = 3,

-			Channel_Config_WaitSendConfig = 4,

-			Channel_Config_WaitReqResp    = 5,

-			Channel_Config_WaitResp       = 6,

-			Channel_Config_WaitReq        = 7,

-			Channel_Open                  = 8,

-			Channel_WaitDisconnect        = 9,

+			Channel_Closed                = 0, /**< Channel is closed and inactive. No data may be sent or received. */

+			Channel_WaitConnect           = 1, /**< A connection request has been received, but a response has not been sent. */

+			Channel_WaitConnectRsp        = 2, /**< A connection request has been sent, but a response has not been received. */

+			Channel_Config_WaitConfig     = 3, /**< Channel has been connected, but not yet configured on either end. */

+			Channel_Config_WaitSendConfig = 4, /**< Channel configuration has been received and accepted, but not yet sent. */

+			Channel_Config_WaitReqResp    = 5, /**< Channel configuration has been sent but not responded to, and a configuration

+			                                        request from the remote end has not yet been received. */

+			Channel_Config_WaitResp       = 6, /**< Channel configuration has been sent but not accepted, but a configuration request

+			                                        from the remote end has been accepted. */

+			Channel_Config_WaitReq        = 7, /**< Channel configuration has been sent and accepted, but a configuration request

+			                                        from the remote end has not yet been accepted. */

+			Channel_Open                  = 8, /**< Channel is open and ready to send or receive data */

+			Channel_WaitDisconnect        = 9, /**< A disconnection request has been sent, but not yet acknowledged. */

 		};

 

-		enum Endpoint_ControlStream_RW_ErrorCodes_t

+		/** Enum for the possible error codes returned by the \ref Bluetooth_SendPacket() function. */

+		enum BT_SendPacket_ErrorCodes_t

 		{

-			BT_SENDPACKET_NoError            = 0,

-			BT_SENDPACKET_NotConnected       = 1,

-			BT_SENDPACKET_ChannelNotOpen     = 2,

+			BT_SENDPACKET_NoError            = 0, /**< The packet was sent sucessfully. */

+			BT_SENDPACKET_NotConnected       = 1, /**< The bluetooth stack is not currently connected to a remote device. */

+			BT_SENDPACKET_ChannelNotOpen     = 2, /**< The given channel is not currently in the Open state. */

 		};

 

 	/* Type Defines: */

+		/** Type define for a Bluetooth ACL channel information structure. This structure contains all the relevent

+		 *  information on an ACL channel for data transmission and reception by the stack.

+		 */

 		typedef struct

 		{

 			uint8_t  State;

@@ -88,6 +96,9 @@
 			uint16_t RemoteMTU;

 		} Bluetooth_Channel_t;

 

+		/** Type define for a Bluetooth device connection information structure. This structure contains all the

+		 *  information needed to maintain a connection to a remote Bluetooth device via the Bluetooth stack.

+		 */

 		typedef struct

 		{

 			bool                IsConnected;

@@ -97,6 +108,7 @@
 			uint8_t             SignallingIdentifier;

 		} Bluetooth_Connection_t;

 		

+		/** Local Bluetooth device information structure, for the defining of local device characteristics for the Bluetooth stack. */

 		typedef struct

 		{

 			uint32_t Class;