X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/7c5444b89a49df7cb671b0b041567990d2a3012e..23f3c3deee8bd153d59f2ac4e659c71ee75915f7:/Projects/Magstripe/Magstripe.c?ds=sidebyside

diff --git a/Projects/Magstripe/Magstripe.c b/Projects/Magstripe/Magstripe.c
index 871db28c3..95c81f342 100644
--- a/Projects/Magstripe/Magstripe.c
+++ b/Projects/Magstripe/Magstripe.c
@@ -29,20 +29,44 @@
   this software.
 */
  
+/** \file
+ *
+ *  Main source file for the MagStripe reader program. This file contains the main tasks of
+ *  the project and is responsible for the initial application hardware configuration.
+ */
+ 
 #include "Magstripe.h"
 
+/** Bit buffers to hold the read bits for each of the three magnetic card tracks before they are transmitted
+ *  to the host as keyboard presses.
+ */
 BitBuffer_t TrackDataBuffers[3];
 
-USB_ClassInfo_HID_t Keyboard_HID_Interface =
+/** LUFA HID Class driver interface configuration and state information. This structure is
+ *  passed to all HID Class driver functions, so that multiple instances of the same class
+ *  within a device can be differentiated from one another.
+ */
+USB_ClassInfo_HID_Device_t Keyboard_HID_Interface =
 	{
-		.InterfaceNumber         = 0,
-
-		.ReportINEndpointNumber  = KEYBOARD_EPNUM,
-		.ReportINEndpointSize    = KEYBOARD_EPSIZE,
+		.Config =
+			{
+				.InterfaceNumber         = 0,
+
+				.ReportINEndpointNumber  = KEYBOARD_EPNUM,
+				.ReportINEndpointSize    = KEYBOARD_EPSIZE,
+				
+				.ReportINBufferSize      = sizeof(USB_KeyboardReport_Data_t),
+			},
 		
-		.ReportINBufferSize      = sizeof(USB_KeyboardReport_Data_t),
+		.State =
+			{
+				// Leave all state values to their defaults				
+			}
 	};
 
+/** Main program entry point. This routine contains the overall program flow, including initial
+ *  setup of all components and the main program loop.
+ */
 int main(void)
 {
 	SetupHardware();
@@ -55,11 +79,12 @@ int main(void)
 		if (Magstripe_GetStatus() & MAG_CARDPRESENT)
 		  ReadMagstripeData();
 
-		USB_HID_USBTask(&Keyboard_HID_Interface);
+		HID_Device_USBTask(&Keyboard_HID_Interface);
 		USB_USBTask();
 	}
 }
 
+/** Configures the board hardware and chip peripherals for the demo's functionality. */
 void SetupHardware(void)
 {
 	/* Disable watchdog if enabled by bootloader/fuses */
@@ -80,6 +105,9 @@ void SetupHardware(void)
 	TIMSK0 = (1 << OCIE0A);
 }
 
+/** Determines if a card has been inserted, and if so reads in each track's contents into the bit buffers
+ *  until they are read out to the host as a series of keyboard presses.
+ */
 void ReadMagstripeData(void)
 {
 	/* Arrays to hold the buffer pointers, clock and data bit masks for the separate card tracks */
@@ -111,30 +139,41 @@ void ReadMagstripeData(void)
 	}
 }
 
+/** Event handler for the library USB Configuration Changed event. */
 void EVENT_USB_ConfigurationChanged(void)
 {
-	USB_HID_ConfigureEndpoints(&Keyboard_HID_Interface);
+	HID_Device_ConfigureEndpoints(&Keyboard_HID_Interface);
 }
 
+/** Event handler for the library USB Unhandled Control Packet event. */
 void EVENT_USB_UnhandledControlPacket(void)
 {
-	USB_HID_ProcessControlPacket(&Keyboard_HID_Interface);
+	HID_Device_ProcessControlPacket(&Keyboard_HID_Interface);
 }
 
+/** Timer 0 CTC ISR, firing once each millisecond to keep track of elapsed idle time in the HID interface. */
 ISR(TIMER0_COMPA_vect, ISR_BLOCK)
 {
-	if (Keyboard_HID_Interface.IdleMSRemaining)
-	  Keyboard_HID_Interface.IdleMSRemaining--;
+	if (Keyboard_HID_Interface.State.IdleMSRemaining)
+	  Keyboard_HID_Interface.State.IdleMSRemaining--;
 }
 
-uint16_t CALLBACK_USB_HID_CreateNextHIDReport(USB_ClassInfo_HID_t* HIDInterfaceInfo, void* ReportData)
+/** HID Class driver callback function for the creation of a HID report for the host.
+ *
+ *  \param[in] HIDInterfaceInfo  Pointer to the HID interface structure for the HID interface being referenced
+ *  \param[in,out] ReportID      Report ID requested by the host if non-zero, otherwise callback should set to the generated report ID
+ *  \param[out] ReportData       Pointer to the preallocated report buffer where the created report should be stored
+ *
+ *  \return Number of bytes in the created report
+ */
+uint16_t CALLBACK_HID_Device_CreateHIDReport(USB_ClassInfo_HID_Device_t* const HIDInterfaceInfo, uint8_t* const ReportID, void* ReportData)
 {
 	static bool IsKeyReleaseReport;
 	static bool IsNewlineReport;
 
 	BitBuffer_t*               Buffer         = NULL;
 	USB_KeyboardReport_Data_t* KeyboardReport = (USB_KeyboardReport_Data_t*)ReportData;
-		
+	
 	/* Key reports must be interleaved with 0 Key Code reports to release the keys, or repeated keys will be ignored */
 	IsKeyReleaseReport = !IsKeyReleaseReport;	
 
@@ -168,7 +207,15 @@ uint16_t CALLBACK_USB_HID_CreateNextHIDReport(USB_ClassInfo_HID_t* HIDInterfaceI
 	return sizeof(USB_KeyboardReport_Data_t);
 }
 
-void CALLBACK_USB_HID_ProcessReceivedHIDReport(USB_ClassInfo_HID_t* HIDInterfaceInfo, void* ReportData, uint16_t ReportSize)
+/** HID Class driver callback function for the processing of a received HID report from the host.
+ *
+ *  \param[in] HIDInterfaceInfo  Pointer to the HID interface structure for the HID interface being referenced
+ *  \param[in] ReportID          Report ID of the received report from the host
+ *  \param[in] ReportData        Pointer to the report buffer where the received report is stored
+ *  \param[in] ReportSize        Size in bytes of the report received from the host
+ */
+void CALLBACK_HID_Device_ProcessHIDReport(USB_ClassInfo_HID_Device_t* const HIDInterfaceInfo, const uint8_t ReportID,
+                                          const void* ReportData, const uint16_t ReportSize)
 {
 	// Unused (but mandatory for the HID class driver) in this demo, since there are no Host->Device reports
 }