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.

Demos/Host/Incomplete/BluetoothHost/ConfigDescriptor.c

@@ -133,15 +133,30 @@ uint8_t ProcessConfigurationDescriptor(void)
 	return SuccessfulConfigRead;
 }
 
+/** Descriptor comparator function. This comparator function is can be called while processing an attached USB device's
+ *  configuration descriptor, to search for a specific sub descriptor. It can also be used to abort the configuration
+ *  descriptor processing if an incompatible descriptor configuration is found.
+ *
+ *  This comparator searches for the next Endpoint descriptor inside the current interface descriptor, aborting the 
+ *  search if another interface descriptor is found before the required endpoint.
+ *
+ *  \return A value from the DSEARCH_Return_ErrorCodes_t enum
+ */
 uint8_t DComp_NextInterfaceBluetoothDataEndpoint(void* CurrentDescriptor)
 {
-	/* PURPOSE: Find next interface endpoint descriptor before next interface descriptor */
-
+	/* Determine the type of the current descriptor */
 	if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Endpoint)
-	  return DESCRIPTOR_SEARCH_Found;
+	{
+		/* Indicate that the descriptor being searched for has been found */
+		return DESCRIPTOR_SEARCH_Found;
+	}
 	else if (DESCRIPTOR_TYPE(CurrentDescriptor) == DTYPE_Interface)
-	  return DESCRIPTOR_SEARCH_Fail;
+	{
+		/* Indicate that the search has failed prematurely and should be aborted */
+		return DESCRIPTOR_SEARCH_Fail;
+	}
 
+	/* Current descriptor does not match what this comparator is looking for */
 	return DESCRIPTOR_SEARCH_NotFound;
 }
 

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)
 	{

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;
 	}
 

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;