Application Note Application Note

Application Note Application Note

Application Note of NUVOTON 32-bit NuMicro® Family

Application Note

32-bit Cortex™-M0 MCU

NuMicro

®

Family

An Example of CCID (Circuit Card Interface Devices)

AN_1025_EN

- i -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

Table of Contents-

1

2

3

4

5

INTRODUCTION......................................................................................................................... 2

CCID PROGRAM........................................................................................................................ 3

2.1

System Initialization ........................................................................................................ 5

2.2

USB Device Initialization................................................................................................. 5

2.2.1

Endpoint Initialization........................................................................................................5

2.2.2

Descriptor Initialization .....................................................................................................6

2.3

CCID Class Standard Request and Callback Function .................................................. 6

2.3.1

“Get Clock Frequencies” and “Get Data Rates” through Control IN .................................7

2.3.2

“Abort” through Control.....................................................................................................7

2.3.3

Command Message through Bulk OUT............................................................................8

2.3.4

Response Message through Bulk IN ................................................................................9

2.3.5

Card Status through Interrupt IN ....................................................................................10

CUSTOMIZATION .................................................................................................................... 12

3.1

VID (Vendor ID) / PID (Product ID)............................................................................... 12

3.2

Standard Descriptors .................................................................................................... 12

3.2.1

Device descriptor............................................................................................................12

3.2.2

Configuration descriptor .................................................................................................13

3.2.3

String descriptors............................................................................................................15

3.3

Functions ...................................................................................................................... 15

3.3.1

Dispatch Message Function ...........................................................................................15

PROGRAM EXECUTION.......................................................................................................... 18

4.1

Source Directory ........................................................................................................... 18

4.2

Execution Result ........................................................................................................... 19

REVISION HISTORY ................................................................................................................ 20

AN_1025_EN

- 1 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

1 INTRODUCTION

The portable ATM is more popular now. Therefore the smart card reader is more important for user.

Microsoft provides the driver inside the Windows OS, which follow the USB CCID (Circuits Card

Interface Devices) class specification. And the smart card should follow the ISO/IEC 7816 specifications.

Nuvoton provides an example to demonstrate the capability of NuMicro

™ family MCU to be a smart card reader. The following diagram illustrates the environment that runs the Smart Card Reader on a

Nuvoton evaluation board, Nu-EVB.

Windows PC

Nu-EVB

Figure 1-1. An example of HID touch digitizer

The Nu-EVB will be recognized as a smart card reader as soon as it is attached to PC’s USB port. To emulate card reader function, program will return card not present to host. Because no smart card controller function is included, the host will recognize a smart card reader and wait for the card insert.

Nuvoton provides the source code to those users who want to develop a CCID smart card reader. The source code includes data structure of USB descriptors, functions of handling USB handshake protocol. User can customize her smart card device by modifying the source code. For example, USB

Vendor ID/Product ID, or standard descriptors, or device class descriptor. This example doesn’t contain the smart card controller function; instead Nuvoton provides UART library functions and Smart

Card library functions to implement data transfer between smart card and NuMicro

™ MCUs. By using dispatch function included in source code, smart card data could be sent to/ receive from host.

AN_1025_EN

- 2 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

2 CCID PROGRAM

This example emulates a CCID card reader that is waiting for the smart card insert. The system clock,

UART and USB Device are initialized firstly. Once attached to Host, a sequence of USB transfers will be handled properly that it will be recognized as a CCID smart card reader. Host will send commands and get response through USB request. A library function DrvUSB_DispatchEvent() is used to check

USB bus and endpoint status and call corresponding callback function to handle the event. Besides, a user-defined callback function BulkOutData() is used to parse the CCID command. After dispatch the

CCID command, it will respond the message whenever a bulk IN transaction is received from HOST.

START

System Initialization

USB I/F Initialization

NO Get USB status and dispatch events

NO

Is Device attached?

YES

Set up CCID descriptors and Callback functions

Get USB status and dispatch events

Is Device detached?

YES

END

Figure 2-1. Program Control Flow

AN_1025_EN

- 3 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

Figure 2-2. Bulk-OUT/IN Program Control Flow

AN_1025_EN

Figure 2-3. Interrupt-IN Program Control Flow

- 4 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

2.1 System Initialization

At system initialization phase, UART is configured as (115200, 8, n, 1) to be a debug message output interface. And the system clock is set to be 48MHz for running USB device function.

2.2 USB Device Initialization

The USBD initialization enables USB device hardware function and handles the USB events. It will initialize necessary endpoints, descriptors and installed callback functions.

2.2.1 Endpoint Initialization

This example uses five pipes including Control IN / OUT, Bulk IN / OUT and Interrupt IN. The Control pipe is used to handle “Abort”, “Get_Clock_Frequencies”, and “Get_Data_Rates” Class request. The

Bulk Out pipe is used to handle command messages. The Bulk IN pipe is used to send response messages. The Interrupt IN pipe is used to send card status.

The DrvUSB_Open() function is used to initialize endpoints information structures including endpoint number, maximum packet size, endpoint type, etc. The endpoint information structure is saved in a global array sEpDescription[] (defined at Ccid_Sys.c). The following lists the structure content.

S_DRVUSB_EP_CTRL sEpDescription[] =

{

/* EP Id 0, EP Addr 0, input, max packet size = 16 */

{CTRL_EP_NUM | EP_INPUT, CCID_MAX_PACKET_SIZE_CTRL, NULL},

/* EP Id 1, EP Addr 0, output, max packet size = 16 */

{CTRL_EP_NUM | EP_OUTPUT, CCID_MAX_PACKET_SIZE_CTRL, NULL},

/* EP Id 2, EP Addr 2, input, max packet size = 64 */

{CCID_BULK_IN_EP_NUM | EP_INPUT, CCID_MAX_PACKET_SIZE_BULK, NULL},

/* EP Id 3, EP Addr 2, output, max packet size = 64 */

{CCID_BULK_OUT_EP_NUM | EP_OUTPUT, CCID_MAX_PACKET_SIZE_BULK, NULL},

/* EP Id 4, EP Addr 3, input, max packet size = 16 */

{CCID_INT_IN_EP_NUM | EP_INPUT, CCID_MAX_PACKET_SIZE_INT, NULL},

/* EP Id 5, EP Addr n, in/out, max packet size */

{0x00, 0, NULL}

};

In addition to endpoint structures, a set of callback functions are required to process endpoint events.

When DrvUSB_DispatchEvent() function is called, it will check endpoint status and call corresponding callback function to handle USB event. The callback functions are saved in a global array

g_sUsbOps[] (defined at Ccid_Sys.c). The following lists the array content.

S_DRVUSB_EVENT_PROCESS g_sUsbOps[12] =

{

/* ctrl pipe0 (EP address 0) In ACK callback */

/* ctrl pipe0 (EP address 0) Out ACK callback */

AN_1025_EN

- 5 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

/* EP address 1 In ACK callback */

/* EP address 1 Out ACK callback */

/* EP address 2 In ACK callback */

{CCID_BulkInCallback, &g_CCID_sDevice},

/* EP address 2 Out ACK callback */

{CCID_BulkOutCallback, &g_CCID_sDevice},

/* EP address 3 In ACK callback */

{CCID_IntInCallback, &g_CCID_sDevice},

/* EP address 3 Out ACK callback */

/* EP address 4 In ACK callback */

/* EP address 4 Out ACK callback */

/* EP address 5 In ACK callback */

/* EP address 5 Out ACK callback */

};

2.2.2 Descriptor Initialization

The CCID_Init() function (defined at CCID_API.c) is used to setup all descriptors including device, configuration and CCID class device descriptors. The input parameter of CCID_Init() is a user-defined callback function - BulkOutData(). This callback function will be registered to USB device library to handle Bulk OUT command messages.

2.3 CCID Class Standard Request and Callback Function

This example is able to handle three CCID Class standard requests, including “Abort”,

“Get_ClockFrequencies” and “Get_DataRates”. These Class-specific requests allow the host to abort the response portion of a command / response message pair and report a list of selectable clock frequencies and data rates.

Two callback functions, CCID_ClassCtrlAbortRequest() and CCID_ClassCtrlRequest() (defined at

CCID_Sys.c), are used to handle requests from Control IN/OUT pipes. These functions are registered to USB device driver via the following data structure.

S_DRVUSB_CTRL_CALLBACK_ENTRY g_asCtrlCallbackEntry[64] =

{//request type,command,etup ack handler, in ack handler,out ack handler, parameter

{REQ_CLASS, CCID_Abort, CCID_ClassCtrlAbortRequest, 0, 0, &g_CCID_sDevice},

{REQ_CLASS, CCID_GET_CLOCK_FREQUENCIES, CCID_ClassCtrlRequest,

CCID_ClassCtrlRequestIn, 0, &g_CCID_sDevice},

CCID_ClassCtrlRequestIn, 0, &g_CCID_sDevice},

};

AN_1025_EN

- 6 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

For CCID device, host sends class command “Abort” to abort the response portion of a command / response message pair. This may be necessary to recover from error conditions and put the CCID into a state where it can receive a new command message. When a request command is received in an endpoint, its corresponding callback function will be called. The callback function has to prepare the report data that will be sent to host. The following sections describe the callback functions used for different requests.

2.3.1 “Get Clock Frequencies” and “Get Data Rates” through Control IN

When host wants to get clock frequency or data rates, it will use Control IN pipe to get the list report.

Host firstly sends the Setup packet to device. USB device driver will acknowledge the Setup packet and call CCID_ClassCtrlRequest() which is Control IN callback function. The clock frequency or data rate list report data is prepared in the callback function and will be sent to host in next Data Stage.

Transfer from Host to Device

Transfer from Device to Host

Setup Stage

Setup Packet Data Packet Ack Packet

Calling CCID_ClassCtrlRequest()

Data Stage

IN Packet Data Packet

Ack Packet

Status Stage

OUT Packet Data Packet Ack Packet

Figure 2-4. Operation of USB Control IN transfer

2.3.2 “Abort” through Control

For the Abort, it could be sent to device through Control pipe.

When the host wants to abort the message response, it will use Control pipe to send it. Host firstly sends the Setup packet to device. USB device driver will acknowledge the Setup packet by calling

CCID_ClassCtrlAbortRequest() which is Control Out callback function. Then send the abort command to smart card device.

AN_1025_EN

- 7 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

Transfer from Host to Device

Transfer from Device to Host

Setup Stage

Setup Packet Data Packet Ack Packet

Calling CCID_ClassCtrlAbortRequest()

Status Stage

IN Packet Data Packet Ack Packet

Figure 2-5. Operation of USB Control transfer

2.3.3 Command Message through Bulk OUT

Usually, the command message is sent from host through Bulk OUT pipe. Whenever a smart card insert, BulkOutData() callback function should called to get the command from Bulk OUT buffer. USB device driver will parse it and dispatch command as soon as passable.

AN_1025_EN

- 8 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

Bulk OUT

IN Packet Data Packet

Ack Packet

Bulk OUT Buffer

BulkOutData()

Dispatch message

Transfer from Host to Device

Transfer from Device to Host

Figure 2-6. Operation of USB Bulk OUT transfer

2.3.4 Response Message through Bulk IN

After smart card is ready to response the command message, it will send the response message through Bulk IN pipe.

AN_1025_EN

- 9 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

Bulk IN

IN Packet Data Packet Ack Packet

Bulk IN Buffer

Smart Card response

Transfer from Host to Device

Transfer from Device to Host

Figure 2-7. Operation of USB Bulk IN transfer

2.3.5 Card Status through Interrupt IN

Usually, the Input Report data is sent to host through Interrupt IN pipe. Host periodically gets the card status data. Whenever a card inserted / removed happens, the state should be written into Interrupt IN buffer. USB device driver will send it to host as soon as an IN token is received.

AN_1025_EN

- 10 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

Interrupt IN

IN Packet Data Packet Ack Packet

Interrupt IN Buffer

Interrupt-In Message

Smart Card Insert / remove

Transfer from Host to Device

Transfer from Device to Host

Figure 2-8. Operation of USB Interrupt IN transfer

AN_1025_EN

- 11 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

3 CUSTOMIZATION

This example provides a framework of CCID smart card reader. User can change it according to her hardware functions. For example, the device ID, supported CCID commands, class device descriptor and so on. The data structure or function may need to be customized are listed as below.

3.1 VID (Vendor ID) / PID (Product ID)

The default value of VID and PID are 0416H (Nuvoton) and C146h (NuMicro

™ Family) respectively.

User should modify it to fit her product.

Vendor ID

Source CCID_API.c

Type Constant

Name USB_VID

Table 3-1. Vendor ID

Product ID

Source CCID_API.c

Type Constant

Name USB_PID

Table 3-2. Product ID

3.2 Standard Descriptors

The standard descriptors include Device, Configuration and String descriptors that must be supported in each USB device.

3.2.1 Device descriptor

Device descriptor contains the VID/PID and serial number. The serial number is indicated by, gSerialIndex. If the CCID device has a unique serial number, this variable should be set to 03H.

Otherwise, its value should be 00H.

Device Descriptor

Source CCID_API.c

Type const uint8_t

Name gau8DeviceDescriptor

Table 3-3. Device Descriptor

The content of device descriptor is listed at below.

AN_1025_EN

- 12 -

March 10, 2011

Rev. 1.00

An Example of CCID

#define USB_VID

#define USB_PID

#define gSerialIndex

0x0416

0xC143

0x00 // no serial number

//#define gSerialIndex

:

:

:

0x03 // has unique serial number const __align(4) uint8_t gau8DeviceDescriptor[] =

{

LEN_DEVICE,

DESC_DEVICE,

0x10, 0x01, // bcdUSB

Application Note

USB_VID & 0x00FF, (USB_VID & 0xFF00) >> 8, // idVendor

USB_PID & 0x00FF, (USB_PID & 0xFF00) >> 8, // idProduct

0x00, 0x00, // bcdDevice

gSerialIndex,

};

3.2.2 Configuration descriptor

The configuration descriptor describes what endpoints are available. Each endpoint is specified in an endpoint descriptor. This example supports Bulk Out, Bulk IN and Interrupt IN endpoints. User can add other endpoint descriptor if necessary.

Configuration Descriptor

Source CCID_API.c

Type const uint8_t

Name gau8ConfigDescriptor

Table 3-4. Configuration Descriptor

The content of configuration descriptor is listed at below. const __align(4) uint8_t gau8ConfigDescriptor[] =

{

LEN_CONFIG,

DESC_CONFIG,

(LEN_CONFIG+LEN_INTERFACE+LEN_CCID+LEN_ENDPOINT*3) & 0x00FF,

((LEN_CONFIG+LEN_INTERFACE+LEN_CCID+LEN_ENDPOINT*3) & 0xFF00) >> 8,

AN_1025_EN

- 13 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

// Interface descriptor (Interface 0 = Smart Card Reader)

LEN_INTERFACE,

DESC_INTERFACE,

// bLength

// CCID class descriptor

0x36, // bLength: CCID Descriptor size

0x21,

0x10,

0x01,

0x00,

0x07,

// bDescriptorType: CCID specific number

// bcdCCID(LSB): CCID Class Spec release number (1.10)

// bVoltageSupport: 5v, 3v and 1.8v

0x03,0x00,0x00,0x00,

0xA6,0x0E,0x00,0x00,

0x4C,0x1D,0x00,0x00,

0x00,

0x60,0x27,0x00,0x00,

// dwProtocols: supports T=0 and T=1

// dwDefaultClock: 3.75MHz

// dwMaximumClock: 7.5MHz

// bNumClockSupported => no manual setting

// dwDataRate: 10080 bps

0xB4,0xC4,0x04,0x00, // dwMaxDataRate: 312500 bps

0x00, // bNumDataRatesSupported => no manual setting

0xFE,0x00,0x00,0x00, /* dwMaxIFSD: 0 (T=0 only) */

0x00,0x00,0x00,0x00, /* dwSynchProtocols */

0x00,0x00,0x00,0x00, /* dwMechanical: no special characteristics */

0x30,0x00,0x01,0x00, // dwFeatures: clk, baud rate, voltage : automatic

// CCID can set ICC in clock stop mode.

0x0F,0x01,0x00,0x00, /* dwMaxCCIDMessageLength : Maximun block size header*/

/* 261 + 10 */

0x00,0x00,

0x00,

/* wLcdLayout */

/* bPINSupport : no PIN verif and modif */

// Endpoint 1 descriptor (Interrupt in)

LEN_ENDPOINT, // bLength

DESC_ENDPOINT, // bDescriptorType

CCID_INT_IN_EP_NUM | 0x80, // bEndpointAddress

EP_INT, // bmAttributes

CCID_MAX_PACKET_SIZE_INT & 0x00FF, // wMaxPacketSize

(CCID_MAX_PACKET_SIZE_INT & 0xFF00) >> 8,

CCID_DEFAULT_INTERVAL_INT, // bInterval

// Endpoint 2 descriptor (Bulk out)

LEN_ENDPOINT, // bLength

DESC_ENDPOINT, // bDescriptorType

CCID_BULK_OUT_EP_NUM, // bEndpointAddress

AN_1025_EN

- 14 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

EP_BULK, // bmAttributes

CCID_MAX_PACKET_SIZE_BULK & 0x00FF, // wMaxPacketSize

(CCID_MAX_PACKET_SIZE_BULK & 0xFF00) >> 8,

CCID_DEFAULT_INTERVAL_BULK, // bInterval

// Endpoint 2 descriptor (Bulk in)

LEN_ENDPOINT, // bLength

DESC_ENDPOINT, // bDescriptorType

CCID_BULK_IN_EP_NUM | 0x80, // bEndpointAddress

EP_BULK, // bmAttributes

CCID_MAX_PACKET_SIZE_BULK & 0x00FF, // wMaxPacketSize

(CCID_MAX_PACKET_SIZE_BULK & 0xFF00) >> 8,

CCID_DEFAULT_INTERVAL_BULK // bInterval

/* Add others endpoint descriptors */

};

3.2.3 String descriptors

The string descriptors provide device information including vendor name, product name and serial number.

String Descriptors

Source CCID_API.c

Type const uint8_t

Name gau8VendorStringDescriptor gau8ProductStringDescriptor gau8StringSerial

Table 3-5. String Descriptors

3.3 Functions

The function is used to handle the card command / response message.

3.3.1 Dispatch Message Function

The host sent the command to smart card through Bulk OUT pipe. Whenever a command is received,

CCID_DispatchMessage() function should be called to send message to smart card. And the smart card response message will be sent to host after received bulk IN token.

DispatchMessage

Source CCID_API.c

Syntax void CCID_DispatchMessage(void)

AN_1025_EN

- 15 -

March 10, 2011

Rev. 1.00

An Example of CCID

Table 3-10. DispatchMessage Function void CCID_DispatchMessage(void)

{

if(g_CCID_sDevice.isBulkOutReady)

{ switch(UsbMessageBuffer[OFFSET_BMESSAGETYPE])

{

RDR_to_PC_DataBlock(ErrorCode);

break;

RDR_to_PC_SlotStatus(ErrorCode);

break;

RDR_to_PC_SlotStatus(ErrorCode);

break;

RDR_to_PC_DataBlock(ErrorCode);

break;

RDR_to_PC_Parameters(ErrorCode);

break;

RDR_to_PC_Parameters(ErrorCode);

break;

RDR_to_PC_Parameters(ErrorCode);

break;

RDR_to_PC_Escape(ErrorCode);

break;

RDR_to_PC_SlotStatus(ErrorCode);

break;

Application Note

AN_1025_EN

RDR_to_PC_SlotStatus(ErrorCode);

break;

- 16 -

March 10, 2011

Rev. 1.00

default:

CmdNotSupported();

break;

}

UsbBulkInMessage(); g_CCID_sDevice.isBulkOutReady = 0;

}

}

An Example of CCID

Application Note

AN_1025_EN

- 17 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

4 PROGRAM EXECUTION

4.1 Source Directory

This example code is created by using Keil uVision v4.03. A Smpl_CCID project file is saved at the top directory of source code. After open this project file, the following working window will be displayed.

Figure 4-1. Snapshot of Keil uVision Working Window

The project includes the example source files and NuMicro

™ BSP files (CMSIS and device driver files). There’re three example source files.

Smpl_CCID.c

This file contains main() function that does system initialization.

CCID_API.c

This file includes global variables of descriptors, major operating function CCID_MainProcess(), and dispatch message function CCID_DispatchMessage().

CCID_Sys.c

This file includes those functions of setting endpoint, endpoint callback functions and so on.

CCID_if.c

This file includes those functions of card relative setting and so on.

AN_1025_EN

- 18 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

4.2 Execution Result

The program should be run on a Nu-EVB. When the board is attached to Windows PC, it will be recognized as a CCID smart card reader device.

AN_1025_EN

Figure 4-2. Snapshot of Windows Paint

- 19 -

March 10, 2011

Rev. 1.00

An Example of CCID

5 REVISION HISTORY

REV. DATE

1.00 March 10, 2011

Created.

Application Note

DESCRIPTION

AN_1025_EN

- 20 -

March 10, 2011

Rev. 1.00

An Example of CCID

Application Note

Important Notice

Nuvoton Products are neither intended nor warranted for usage in systems or equipment, any malfunction or failure of which may cause loss of human life, bodily injury or severe property damage. Such applications are deemed, “Insecure Usage”.

Insecure usage includes, but is not limited to: equipment for surgical implementation, atomic energy control instruments, airplane or spaceship instruments, the control or operation of dynamic, brake or safety systems designed for vehicular use, traffic signal instruments, all types of safety devices, and other applications intended to support or sustain life.

All Insecure Usage shall be made at customer’s risk, and in the event that third parties lay claims to Nuvoton as a result of customer’s Insecure Usage, customer shall indemnify the damages and liabilities thus incurred by Nuvoton.

AN_1025_EN

- 21 -

March 10, 2011

Rev. 1.00

Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project