read.pudn.comread.pudn.com/downloads205/doc/964397/mc998 api reference documen…read.pudn.com

MC-998TM

MC-998 Hand-Held Smart Card Read/Write Device (RWD) API Reference Documentation V3.4 - 1 -

MC-998 Hand-Held Smart Card Read/Write Device (RWD) API Reference Documentation

Version 3.4 Oct 2002

MC-998TM


REVISION HISTORY

Version Number Date Description Author

1.0 October 25, 2000 Initial release Hwang Toung

2.0 December 5, 2001 Second edition, changes are marked with a bold black line to the left.

Hwang Toung

3.2 April 1, 2002 Third edition, changes are marked with a bold blue line to the left.

Hwang Toung

3.3 May 24, 2002 Support for AT45D041; Database definitions revised

Hwang Toung

3.4 Oct 10, 2002 Support for AT88SC1604 Hwang Toung

MC-998TM


Contents

CHAPTER 1................................................................................................................................................10

INTRODUCTION ......................................................................................................................................10

1.1 OVERVIEW OF THE MC-998........................................................................................................... 11

CHAPTER 2................................................................................................................................................12

MC-998 API ROUTINES...........................................................................................................................12

2.1 SYSTEM MESSAGE.........................................................................................................................13 2.1.1 System Message Word ...........................................................................................................13 2.1.2 System Message Inquiring ....................................................................................................14

2.1.2.1 sys_msg ( ) ...................................................................................................................14 2.1.2.2 System Message Mask Setting .....................................................................................15

2.2 KEYBOARD....................................................................................................................................16 2.2.1 Keyboard Unit Initialization .................................................................................................16 2.2.2 Keyboard Reading.................................................................................................................17

2.2.2.1 FIFO Mode Reading.....................................................................................................17 2.2.2.2 One-key Mode Reading ...............................................................................................18 2.2.2.3 Key Matrix Map Reading.............................................................................................18 2.2.2.4 Key Auto Beep and Auto EL Masking ........................................................................19

2.3 BUZZER .........................................................................................................................................20 2.4 BACKLIGHT ...................................................................................................................................21

2.4.1 Switching...............................................................................................................................21 2.4.2 Backlight Auto Off Time Setting............................................................................................21

2.5 BATTERY CHECK ...........................................................................................................................22 2.6 REAL TIME CLOCK ........................................................................................................................23

2.6.1 Time Structure .......................................................................................................................23 2.6.2 Date Structure .......................................................................................................................23 2.6.3 Time Reading ........................................................................................................................24 2.6.4 Time Setting...........................................................................................................................24 2.6.5 Date Reading ........................................................................................................................25 2.6.6 Date Setting...........................................................................................................................25 2.6.7 Alarm Time Reading..............................................................................................................26 2.6.8 Alarm Time Setting................................................................................................................26 2.6.9 Alarm Clock On/Off Setting ..................................................................................................27 2.6.10 Alarm Clock On/Off Reading ................................................................................................27

2.7 IC CARD INTERFACE .....................................................................................................................28 2.7.1 Data Structures .....................................................................................................................28

2.7.1.1 ATR Data......................................................................................................................28 2.7.1.2 I2C Serial Data..............................................................................................................29

MC-998TM


2.7.2 Common Card Routines ........................................................................................................30 2.7.2.1 Card Interface Initialization .........................................................................................30 2.7.2.2 Card Interface Power On..............................................................................................31 2.7.2.3 Selecting Card Socket ................................................................................................31 2.7.2.4 Getting ATR .................................................................................................................32 2.7.2.5 Get Current Socket Number .........................................................................................33 2.7.2.6 Deactivating Current Card Socket................................................................................33 2.7.2.7 Deactivating All Cards/Turning off Card Interface Unit..............................................34 2.7.2.8 Socket 2 Status .............................................................................................................34

2.7.3 Synchronous Card Routines ..................................................................................................35 2.7.3.1 Direct Pin Controls.......................................................................................................35

2.7.3.1.1 RST Pin.......................................................................................................................35 2.7.3.1.2 C6 Pin..........................................................................................................................35 2.7.3.1.3 C3/C4/C7/C8 Pins.......................................................................................................35

2.7.3.2 I2C Serial Communication ...........................................................................................36 2.7.4 Asynchronous Card Routines ................................................................................................36

2.7.4.1 T = 0 Protocol...............................................................................................................36 2.7.4.2 T = 1 Protocol...............................................................................................................38

2.8 UART PERIPHERALS .....................................................................................................................39 2.8.1 Data Structures .....................................................................................................................39

2.8.1.1 UART Status ................................................................................................................39 2.8.1.2 Fcntl Word....................................................................................................................40

2.8.2 Initialization of UART...........................................................................................................41 2.8.3 Reading UART ......................................................................................................................43 2.8.4 Writing UART........................................................................................................................43 2.8.5 Device Control of UART .......................................................................................................44 2.8.6 Status Reading ......................................................................................................................45

2.9 USER TIMER ..................................................................................................................................45 2.9.1 Set User Timer.......................................................................................................................45 2.9.2 Read User Timer ...................................................................................................................46 2.9.3 Register User Timer Callback Routine .................................................................................46

2.10 DISPLAY.........................................................................................................................................47 2.10.1 Initialization..........................................................................................................................47 2.10.2 Character Displaying............................................................................................................48

2.10.2.1 Font setting...................................................................................................................48 2.10.2.2 Character Displaying....................................................................................................49 2.10.2.3 Clear Screen .................................................................................................................49 2.10.2.4 Cursor Setting...............................................................................................................50

2.10.3 Graphic Displaying...............................................................................................................50 2.10.3.1 Clear Graphic Windows ...............................................................................................50 2.10.3.2 Pixel Based Graphics ...................................................................................................51

2.10.3.2.1 Pixel Reading ............................................................................................................51 2.10.3.2.2 Pixel Writing .............................................................................................................52

2.10.3.3 Bitmap Based Graphics................................................................................................53

MC-998TM


2.10.3.3.1 Bitmap Structure .......................................................................................................53 2.10.3.3.2 Get Bitmap ................................................................................................................53 2.10.3.3.3 Put Bitmap ................................................................................................................54 2.10.3.3.4 Bitmap Put Mode Setting ..........................................................................................55

2.10.4 Icons......................................................................................................................................56 2.10.4.1 Customized Icon Setting ..............................................................................................56 2.10.4.2 Set Icons .......................................................................................................................57 2.10.4.3 Read Icon Settings........................................................................................................57 2.10.4.4 7-SEG Display In Icon Area ........................................................................................57

2.10.5 LCD Contrast Controlling ....................................................................................................58 2.10.5.1 Read Contrast Setting...................................................................................................58 2.10.5.2 Change Contrast ...........................................................................................................58

2.11 RF INFORMATION ..........................................................................................................................59 2.11.1 Data Structures .....................................................................................................................59

2.11.1.1 Status Byte ...................................................................................................................59 2.11.1.2 Subsystem Configuration Byte.....................................................................................60 2.11.1.3 Message Data Buffer ....................................................................................................60

2.11.2 Initialization..........................................................................................................................61 2.11.3 Message Reading ..................................................................................................................62 2.11.4 Status Reading ......................................................................................................................62 2.11.5 Configuration Reading..........................................................................................................63 2.11.6 Register RF Information Callback Routine...........................................................................63 2.11.7 Set Receiving Method............................................................................................................64

2.12 DOWNLOAD...................................................................................................................................64 2.13 FLASH MEMORY.............................................................................................................................65

2.13.1 Erasing Block........................................................................................................................65 2.13.2 Writing Data..........................................................................................................................65

2.14 MISCELLANEOUS...........................................................................................................................66 2.14.1 Getting Current OS Version Information ..............................................................................67 2.14.2 Delay 1 Microsecond (mS)....................................................................................................68

CHAPTER 3................................................................................................................................................69

DATABASE SUBROUTINES....................................................................................................................69

3.1 OVERVIEW OF MC-998 DATABASE................................................................................................70 3.2 DATABASE PARAMETERS ...............................................................................................................70 3.3 CHECK DATABASES .......................................................................................................................71 3.4 FORMATTING A NEW DATABASE...................................................................................................73 3.5 LOW LEVEL FORMATTING .............................................................................................................74 3.6 ERASING A DATABASE ..................................................................................................................74 3.7 CHECK DATABASE CAPACITY........................................................................................................75 3.8 COUNT THE RECORDS USED IN A DATABASE ...............................................................................76 3.9 JUMP TO A RECORD ......................................................................................................................76 3.10 ADDING A RECORD.......................................................................................................................77 3.11 DELETING A RECORD....................................................................................................................78

MC-998TM


3.12 FINDING A RECORD ......................................................................................................................79 3.13 CRC CHECK OF A RECORD...........................................................................................................81 3.14 CRC CALCULATOR........................................................................................................................81 3.15 GLOBAL VARIABLES USED ............................................................................................................82

CHAPTER 4................................................................................................................................................83

MEMORY CARD ACCESSING DRIVERS............................................................................................83

4.1 OVERVIEW OF MEMORY CARD ACCESSING DRIVERS....................................................................84 4.2 CHECK TYPE OF MEMORY CARD...................................................................................................84 4.3 AT24C01A/02 FUNCTIONS ...........................................................................................................85

4.3.1 Read_AT24C01A( ) ...............................................................................................................85 4.3.2 Write_AT24C01A( )...............................................................................................................86 4.3.3 Write_AT24C01A_Page( ) ....................................................................................................87

4.4 AT24C04/08/16 FUNCTIONS..........................................................................................................88 4.4.1 Read_AT24C16( )..................................................................................................................88 4.4.2 Write_AT24C16_Byte( ) ........................................................................................................89 4.4.3 Write_AT24C16_Page( ) .......................................................................................................90

4.5 AT24C32/64 FUNCTIONS...............................................................................................................91 4.5.1 Read_AT24C64( )..................................................................................................................91 4.5.2 Write_AT24C64_Byte( ) ........................................................................................................92 4.5.3 Write_AT24C64_Page( ) .......................................................................................................93

4.6 AT24C128/256 FUNCTIONS...........................................................................................................94 4.6.1 Read_AT24C256( )................................................................................................................94 4.6.2 Write_AT24C256_Byte( ) ......................................................................................................95 4.6.3 Write_AT24C256_Page( ) .....................................................................................................96

4.7 4442 FUNCTIONS ...........................................................................................................................97 4.7.1 Read_4442_NO_PB( ) ..........................................................................................................97 4.7.2 Read_4442_PB( )..................................................................................................................98 4.7.3 Write_4442( ) ........................................................................................................................98 4.7.4 Verify_4442_PSC( )...............................................................................................................99 4.7.5 Read_4442_SM( ) ...............................................................................................................100 4.7.6 Write_4442_SM( ) ...............................................................................................................101

4.8 4428 FUNCTIONS .........................................................................................................................102 4.8.1 Read_4428_With_PB( ).......................................................................................................102 4.8.2 Read_4428_NO_PB............................................................................................................103 4.8.3 Write_4428( ) ......................................................................................................................104 4.8.4 Verify_4428_PSC( ).............................................................................................................105 4.8.5 Read_4428_SM( ) ...............................................................................................................105

4.9 AT88SC101/102 FUNCTIONS.......................................................................................................106 4.9.1 Read_102_Bit( ) ..................................................................................................................106 4.9.2 Write_102_Bit( )..................................................................................................................107 4.9.3 Read_102_Byte( )................................................................................................................108 4.9.4 Write_102_Byte( ) ...............................................................................................................109 4.9.5 Read_102_Word( ) .............................................................................................................. 110

MC-998TM


4.9.6 Write_102_Word( ) ...............................................................................................................111 4.9.7 Erase_102_Word( ) ..............................................................................................................111 4.9.8 Verify_102_SC( ) ................................................................................................................. 112 4.9.9 Erase_102_AZ1( ) ............................................................................................................... 113 4.9.10 Erase_102_AZ2( ) ............................................................................................................... 114 4.9.11 Fuse_High_102( ) ............................................................................................................... 114 4.9.12 Fuse_Low_102( ) ................................................................................................................ 115 4.9.13 Erase_102_AZ2_EC( )........................................................................................................ 116 4.9.14 Blow_Manufacturer_Fuse_102( ) ....................................................................................... 116 4.9.15 Blow_EC2EN_Fuse_102( )................................................................................................. 116 4.9.16 Blow_Issuer_Fuse_102( ) ................................................................................................... 116

4.10 AT88SC1604 FUNCTIONS............................................................................................................ 116 4.10.1 Read_1604_Bit( ) ................................................................................................................ 116 4.10.2 Write_1604_Byte( ) ............................................................................................................. 117 4.10.3 Write_1604_Array( ) ........................................................................................................... 118 4.10.4 Erase_1604_Byte( )............................................................................................................. 119 4.10.5 Erase_1604_Array( ) ..........................................................................................................120 4.10.6 Verify_1604_SC( ) ...............................................................................................................120 4.10.7 Verify_1604_SCx.................................................................................................................121 4.10.8 Verify_1604U_SCx..............................................................................................................122 4.10.9 Verify_1604_EZx.................................................................................................................122 4.10.10 Verify_1604U_EZx..........................................................................................................123 4.10.11 Fuse_High_1604( ) .............................................................................................................123 4.10.12 Fuse_Low_1604( ) ..........................................................................................................124 4.10.13 Blow_Issuer_Fuse_1604( ) .............................................................................................125

4.11 AT88SC1608 FUNCTIONS ...........................................................................................................125 4.11.1 Select_1608_User_Zone( )..................................................................................................125 4.11.2 Read_1608_User_Zone( ) ...................................................................................................125 4.11.3 Write_1608_User_Zone( )...................................................................................................126 4.11.4 Read_1608_Configuration( ) ..............................................................................................127 4.11.5 Write_1608_Configuration( )..............................................................................................127 4.11.6 Read_1608_Fuses( ) ...........................................................................................................128 4.11.7 Write_1608_Fuses( ) ...........................................................................................................129 4.11.8 Verify_1608_Password( ) ....................................................................................................130 4.11.9 Init_1608_Authentication( ) ................................................................................................130 4.11.10 Verify_1608_Authentication( ) ............................................................................................131

4.12 AT45D041...................................................................................................................................131 4.12.1 Main Memory Page Read ...................................................................................................132 4.12.2 Buffer Read .........................................................................................................................132 4.12.3 Main Memory Page To Buffer Transfer ..............................................................................133 4.12.4 Main Memory Page To Buffer Compare .............................................................................133 4.12.5 Buffer Write .........................................................................................................................133 4.12.6 Buffer To Main Memory Page Program With Built-in Erase ..............................................134 4.12.7 Buffer To Main Memory Page Program Without Built-in Erase .........................................134

MC-998TM


4.12.8 Main Memory Page Program Through Buffer ....................................................................135 4.12.9 Auto Page Rewrite Through Buffer .....................................................................................136 4.12.10 Status Register Read .......................................................................................................137 4.11.11 Card Reset ..............................................................................................................................137

CHAPTER 5..............................................................................................................................................138

CONSOLE DRIVERS..............................................................................................................................138

5.1 OVERVIEW OF CONSOLE DRIVERS...............................................................................................139 5.1.1 What Is It?...........................................................................................................................139 5.1.2 Why? ...................................................................................................................................139 5.1.3 What Exactly Does It Do?...................................................................................................139

5.2 CONSOLE OUTPUT .......................................................................................................................139 5.2.1 Console: English or Chinese...............................................................................................139 5.2.2 Coordinate Systems.............................................................................................................140 5.2.3 Start It Up ...........................................................................................................................140 5.2.4 Print Something ..................................................................................................................141

5.2.4.1 puts( ) .........................................................................................................................141 5.2.4.2 printf() ........................................................................................................................141

5.2.5 No CR/LF............................................................................................................................141 5.2.6 Where To Print ....................................................................................................................141 5.2.7 Wipe Them out of My Screen...............................................................................................142 5.2.8 Changing Faces ..................................................................................................................142

5.3 CONSOLE INPUT ..........................................................................................................................142 5.3.1 What Can We Get From The Console .................................................................................142

5.3.1.1 Keys ...........................................................................................................................142 5.3.1.2 Jog dial .......................................................................................................................142 5.3.1.3 Card Activities ...........................................................................................................143 5.3.1.4 Invisible Power Key? .................................................................................................143

5.3.2 How To Get Them................................................................................................................143 5.3.2.1 getch() ........................................................................................................................143 5.3.2.2 getchx() ......................................................................................................................143

5.3.3 Some Handy Macros ...........................................................................................................143 5.4 SOME INPUT TOOLS.....................................................................................................................144

5.4.1 Numeric Input .....................................................................................................................144 5.4.1.1 Date ............................................................................................................................144 5.4.1.2 Time ...........................................................................................................................144 5.4.1.3 Show Me The Money.................................................................................................145

5.4.2 More Than Numeric ............................................................................................................145 5.4.2.1 Screen Layout.............................................................................................................146 5.4.2.2 Numbers, By Default..................................................................................................146 5.4.2.3 English With Punctuation...........................................................................................146 5.4.2.4 Nihao..........................................................................................................................146 5.4.2.5 Tools...........................................................................................................................147

5.5 FOR THOSE WHO WANT TO DO MORE........................................................................................147

MC-998TM


5.5.1 Sleep Or Not?......................................................................................................................147 5.5.2 Hold On For A Minute ........................................................................................................147 5.5.3 Bilingual?............................................................................................................................148 5.5.4 Alkaline, Dry, NiCd, Li-ion .................................................................................................148

5.6 INSIDE LOOK ...............................................................................................................................148 5.6.1 Header File .........................................................................................................................148 5.6.2 Constants.............................................................................................................................149

5.6.2.1 The Keys ....................................................................................................................149 5.6.2.2 The Jog dial ................................................................................................................149 5.6.2.3 Invalid Key.................................................................................................................149 5.6.2.4 Card Activities ...........................................................................................................150 5.6.2.5 Console Language Setting..........................................................................................150 5.6.2.6 Battery Check Setting.................................................................................................150 5.6.2.7 Return Codes For Numeric Input Tools .....................................................................150 5.6.2.8 Input Mode For Date Input Tools...............................................................................150 5.6.2.9 Return Codes For String Input Tools..........................................................................151 5.6.2.10 Hint Property For String Input Tools..........................................................................151

5.6.3 Variables .............................................................................................................................151 5.6.3.1 Language Selection ....................................................................................................151 5.6.3.2 Inverted Display Control ............................................................................................152 5.6.3.3 Screen Saving Timer Timeout Setting........................................................................152 5.6.3.4 System Power-saving Mode Selection .......................................................................152

5.6.4 Functions/Macros ...............................................................................................................153 5.6.4.1 init_console( ).............................................................................................................153 5.6.4.2 clear_console( ) ..........................................................................................................154 5.6.4.3 change_console_language( ) ......................................................................................154 5.6.4.4 set_console_english( ) / set_console_chinese( ).........................................................155 5.6.4.5 move_cursor( ) ...........................................................................................................156 5.6.4.6 set_inversed_disp( ) / set_normal_disp( ) ..................................................................156 5.6.4.7 printf( ) .......................................................................................................................157 5.6.4.8 puts( ) .........................................................................................................................158 5.6.4.9 getch( ) / getchx( ) ......................................................................................................158 5.6.4.10 is_card_activity( ) / is_jogdialer( ) / is_key_valid( ) ..................................................160 5.6.4.11 gets_dialog_ch( ) / gets_dialog_alpha( ) ....................................................................161 5.6.4.12 get_numeric( ) ............................................................................................................162 5.6.4.13 gets_time( ).................................................................................................................163 5.6.4.14 gets_date( ) .................................................................................................................164 5.6.4.15 refresh_batt_symbol( ) ...............................................................................................165

MC-998TM


Chapter 1 Introduction

MC-998TM


Introduction 1

1.1 Overview of the MC-998 MC-998 is an advanced handheld battery powered smartcard read/write device (RWD). It features: ! A Motorola 32-bit Dragonball CPU ! 1~4M bytes of FLASH memory and 128~512k bytes of SRAM. ! Standard input device consists of a 16-key keyboard and a jog dialer, ! Standard output device is a 128x64 dot matrix LCD panel with several icons. ! An RS-232 serial port and an IR port are default for serial communications, ! Up to 3 card slots could be used (depending on card types). ! An optional modem unit could be used as another serial communication device. ! An optional RF unit could be used to receive paging information.

Software developers could write the standard C/C++ programs to make best use of these functions through calling the MC-998 Application Programming Interface (API) routines. In the next 5 chapters, the details of every API routine will be introduced and some example programs will be given to help the software developers to understand easily. The APIs are all included in a library called libm998.a (in the GNU system library directory). All these APIs are declared in the <api.h> file which is in the GNU system include directory, please include this file by adding this statement to your program:

#include <api.h>

MC-998TM


Chapter 2 MC-998 API Routines

MC-998TM


MC-998 API Routines 2

2.1 System Message

2.1.1 System Message Word

typ_msg_word union is the description of the return value of sys_msg(). typedef union { struct { unsigned int n_a_15 : 1; unsigned int n_a_14 : 1; unsigned int alarm_clock : 1; unsigned int comm_err : 1; unsigned int comm_sb_empty : 1; unsigned int comm_data : 1; unsigned int n_a_9 : 1; unsigned int n_a_8 : 1; unsigned int RF_on_air : 1; unsigned int RF_new : 1; unsigned int time_out : 1; unsigned int card_gone : 1; unsigned int card_insert : 1; unsigned int key_available : 1; unsigned int key_up : 1; unsigned int key_down : 1; } bits; unsigned short s_word; } typ_msg_word; Members

Bits

Message word interpreted as bit fields, all the n_a_* fields represent the n/a bits. alarm_clock set if alarm clock event occurred comm_err set if UART communication error occurred comm_sb_empty set if UART send buffer empty comm_data set if new data exists in UART receiving FIFO RF_on_air set if RF unit has started a receiving process RF_new set if new data exists in RF unit receiving buffer time_out set if a preset timer has expired

MC-998TM


card_gone set if the IC card in socket 2 has been removed card_insert set if an IC card has been inserted into socket 2 key_available set if new data exists in keyboard/jog dial input FIFO

(FIFO mode). key_up set if a key has been released (1-KEY mode) key_down set if a key has been pressed (1-KEY mode)

s_word

message word in raw form 2.1.2 System Message Inquiring

2.1.2.1 sys_msg ( )

sys_msg() is the system message inquiring subroutine, which is supposed to be called in the main loop of message handler. System will enter power-saving mode unless there is unmasked message available. short sys_msg ( unsigned long if_stay_awake ) ; Parameters if_stay_awake

Set the power-saving mode while there is no unmasked message Value Meaning SM_STAY_AWAKE System is frozen but all the peripherals are still

working. SM_GOTO_SLEEP System enters maximum power-saving mode

but some peripherals such as UART, IC card sockets would not work.

Return Values sys_msg

System message word is returned, which could be interpreted by typ_msg_word.

Example

#include “api.h” typ_msg_word smw;

MC-998TM


//……. sm_setting(MSG_KEY_DOWN | MSG_KEY_UP); //here, we use key FIFO mode, so avoid message of 1 key mode //, i.e. mask out key down and key up actions while (1) { /* main loop of message handler */ smw.s_word = sys_msg(SM_GOTO_SLEEP); if (smw.bits.key_available) { /* your key dealers here: */ } if (smw.bits.card_insert) { /* your IC card 2 dealer here */ } } //end of while (1)

2.1.2.2 System Message Mask Setting

sm_setting() sets the message mask so that sys_msg() would not return on unwanted messages. unsigned long sm_setting ( unsigned long msg_msk ) ; Parameters msg_msk

Message mask is set by bit-OR’ing the following masks: Value Meaning if set, message NOT generated on MSK_KEY_DOWN key down (in 1-key mode) MSK_KEY_UP key up (in 1-key mode) MSK_KEY_AVAILABLE key pressed (in FIFO mode) MSK_CARD_INSERT card inserting MSK_CARD_GONE card removing MSK_TIME_OUT SPT Time out MSK_RF_NEW RF new message available MSK_RF_ON_AIR RF on the air

MC-998TM


MSK_COMM_DATA COM port data available MSK_COMM_SB_EMPTY COM sending buffer empty MSK_COMM_ERR COM error occurring MSK_ALARM_CLOCK clock alarm reaching

Return Values:

The same as input value msg_msk. Example

Please refer to section 2.1.2.1

2.2 Keyboard

2.2.1 Keyboard Unit Initialization

The function KEY_init()initializes keyboard interface. void KEY_init(

unsigned long key_flag );

Parameters

key_flag

indicates keyboard operation mode. Set by bit-OR’ing the following flags: Value Meaning KEY_FIFO_MODE keyboard as FIFO mode. Keyboard will send

message when key FIFO is not empty. Any key pressed is put into FIFO so it would not be lost. Should not be used with KEY_1_KEY_MODE.

KEY_1_KEY_MODE keyboard as 1-key mode. Keyboard will send message when a key is pressed or released. Key data should be dealt with soon to prevent it from being overlapped. Should not be used with KEY_FIFO_MODE.

KEY_BEEP_KEY beep when key pressed and hold down. KEY_AUTO_EL_ON automatically turn on backlight when a key is

pressed Return Values

MC-998TM


None.

2.2.2 Keyboard Reading

2.2.2.1 FIFO Mode Reading

Key reading in FIFO mode is implemented by the function KEY_read():

short KEY_read (

void ) ; Parameters

None.

Return Values

Value Meaning –1 FIFO is empty else scan code when data exists in FIFO

Scan code Key name is

0 <POWER/EL> 1 <F3> 2 <F2> 3 <F1> 4 <3> 5 <2> 6 <1> 7 <4> 8 <6> 9 <5> 10 <8> 11 <7> 12 <9> 13 <ENT> 14 <0> 15 <C> 16 Invalid Key pressed 17 <JOG DIALER UP> 18 <JOG DIALER DOWN>

MC-998TM


Remarks

Do not call this function unless FIFO mode is enabled and key_available message received.

2.2.2.2 One-key Mode Reading The following 2 functions are used as key reading in 1-key mode:

short KEY_read_up (

void ) ;

short KEY_read_down (

void ) ;

Parameters

None.

Return Values

Value Meaning –1 no key is pressed or released else scan code when data exists in FIFO

Remarks

Do not call these 2 functions unless 1-key mode is enabled and key_up or key_down message sent. Invoke KEY_read_up() in key_up message dealer and KEY_read_down() in key_down message dealer.

2.2.2.3 Key Matrix Map Reading

The KEY_get_status() function is a low level function to return the key matrix bit map. It could be called anytime to check keyboard status and used only by advanced developers.

short KEY_get_status (

void

MC-998TM


) ; Parameters

None.

Return Values

16-bit key matrix bit map representing 4 x 4 keyboard. Bit Position Key name is

0 <POWER/EL> 1 <F3> 2 <F2> 3 <F1> 4 <3> 5 <2> 6 <1> 7 <4> 8 <6> 9 <5> 10 <8> 11 <7> 12 <9> 13 <ENT> 14 <0> 15 <C>

2.2.2.4 Key Auto Beep and Auto EL Masking

Each of the 16 keys could be masked from auto beeping and auto EL backlight individually, i.e. user could specify which keys will beep or turn on EL backlight when pressed. KEY_mask_set() is used to set these two masks:

void KEY_mask_set (

unsigned long key_mask ) ;

Parameters key_mask

MC-998TM


The 16 MSBs is the mask for beep mask, and the 16 LSBs is the mask for auto EL backlight mask. If any bit in these masks are set (1) the pressing of the corresponding key will trigger beep or EL backlight.

Return Values

None.

KEY_mask_read() is used to get the current setting of these two masks:

unsigned long KEY_mask_read ( void

) ;

Parameters

None.

Return Values

The same as parameter key_mask in KEY_mask_set().

2.3 Buzzer BEEPER_sound() is the buzzer function.

void BEEPER_sound (

unsigned long SREG ) ; Parameters SREG:

Controls buzzer. Only 16 LSBs are used.

Bits 15 14 13 12 11 10 9 8

Name ON D

Bits 7 6 5 4 3 2 1 0

Name N

Value Meaning

MC-998TM


ON 1 to turn on buzzer and 0 to shut it up. D 0~127 to set buzzer output duty cycle to D/255

(0~50%). N set buzzer output frequency to 32768/N Hz.

Return Values

None.

2.4 Backlight

2.4.1 Switching

The EL_setting() function controls backlight.

short EL_setting ( unsigned long ONOFF

);

Parameters ONOFF

Value Meaning EL_ON to turn on backlight. EL_OFF to turn off backlight.

Return Values

The value returned in current version is meaningless, please do not use.

2.4.2 Backlight Auto Off Time Setting

Backlight will be turned off after a certain period of time if no key is pressed. EL_set_time_out() sets this time.

void EL_set_time_out (

unsigned long TOT ) ;

Parameters

MC-998TM


TOT Timeout time for backlight auto off in seconds. Only 8 LSBs are used.

Return Values

None.

2.5 Battery Check

BATT_check_level() performs battery check and returns current battery level.

unsigned short BATT_check_level ( void

) ;

Parameters

None.

Return Values

Current battery level, 0x100 for full scale (3.0 Volts in standard version).

Remarks

1) Return value is not a linear function of battery voltage. Tests should be done to check the return value of certain points. There are some useful data for the standard configured MC-998:

For non-rechargeable Alkaline battery: Value The Battery Voltage is approximately 0xB8 2.2 Volts (Need to change batteries) 0xCC 2.4 Volts 0xE0 2.6 Volts 0xFF 3.0 Volts (Batteries are full)

For rechargeable NiCd/NiH battery: Value The Battery Voltage is approximately 0xA0 2.0 Volts (Need to change batteries) 0xB0 2.1 Volts 0xB8 2.2 Volts 0xCC 2.4 Volts (Batteries are full)

2) Battery checking is a somehow time consuming process. RF information maybe lost in such process.

MC-998TM


3) Developers may use function in console drivers to check battery, please refer to chapter 5 for more information.

2.6 Real Time Clock

2.6.1 Time Structure typ_RTC_time_rec is a union for time accessing. typedef union { struct { unsigned char hour : 8; unsigned char minute : 8; unsigned int second:16; } fields; unsigned long l_word; } typ_RTC_time_rec; Members Fields

Union interpreted as time fields hour hour (0~23) minute minute(0~59) second second(0~59)

l_word Time data in raw form

2.6.2 Date Structure

typ_RTC_date_rec is a union for date accessing.

typedef union { struct { unsigned int year : 16; unsigned char month : 8; unsigned char day : 8; } fields; unsigned long l_word; } typ_RTC_date_rec;

MC-998TM


Members Fields

Union interpreted as date fields year year (1999~2098) month month(1~12) day date(1~31)

l_word Date data in raw form

2.6.3 Time Reading

RTC_read_time() reads RTC time.

unsigned long RTC_read_time ( void ); Parameters

None.

Return Values Raw time data which could be interpreted by typ_RTC_time_rec

2.6.4 Time Setting

RTC_set_time() sets RTC time.

short RTC_set_time ( unsigned long time_rec ) ; Parameters time_rec

Raw time data to set the RTC time to. Macro MAKE_TIME() could be used to simplify time setting.

MC-998TM


Return Values

Value Meaning -1 time_rec is not a valid time. Same as time_rec time successfully set.

Example

#include <api.h> /* Set current time to 15:03:28 */ if (RTC_set_time(MAKE_TIME(15,03,28)) == -1) {

/* Put your error handling code here */

}

2.6.5 Date Reading

RTC_read_date() reads RTC date.

unsigned long RTC_read_date ( void ) ;

Parameters

None.

Return Values

Raw date data which could be interpreted by typ_RTC_date_rec

2.6.6 Date Setting

RTC_set_date() sets RTC date.

short RTC_set_date ( unsigned long date_rec ) ;

MC-998TM


Parameters date_rec

Raw date data to set the RTC date to. Macro MAKE_DATE() could be used to simplify date setting.

Return Values

Value Meaning -1 date_rec is not a valid date Same as date_rec date successfully set.

2.6.7 Alarm Time Reading

RTC_read_alarm() reads RTC alarm time.

unsigned long RTC_read_alarm ( void ) ;

Parameters

None.

Return Values

Raw alarm time data which could be interpreted by typ_RTC_time_rec.

2.6.8 Alarm Time Setting

RTC_set_alarm() sets RTC alarm time

short RTC_set_alarm ( unsigned long time_rec ) ; Parameters time_rec

Raw time data to set the RTC alarm time to. Macro MAKE_TIME() could be used to simplify time setting.

MC-998TM


Return Values

Value Meaning -1 time_rec is not a valid time. Same as time_rec alarm time successfully set.

2.6.9 Alarm Clock On/Off Setting

RTC_alarm_setting() turn alarm clock on/off.

short RTC_alarm_setting ( unsigned long ONOFF ) ;

Parameters

ONOFF

Value Meaning RTC_ALARM_ON to turn on alarm clock. RTC_ALARM_OFF to turn off alarm clock.

Return Values


2.6.10 Alarm Clock On/Off Reading

RTC_get_alarm_setting() reads RTC alarm clock on/off state

short RTC_get_alarm_setting ( void ) ;

Parameters

None.

Return Values

Value Meaning RTC_ALARM_OFF alarm clock is off RTC_ALARM_ON alarm clock is on

MC-998TM


2.7 IC Card Interface IC card interface is a set of low level subroutines, which is used when a new card type is used. It’s recommended that they be not called directly from the application program.

2.7.1 Data Structures

2.7.1.1 ATR Data

typ_Card_ATR_param is ATR command & data buffer for IC card ATR communication. typedef struct { short card_num : 8; short card_type_7 : 1; short card_type_6 : 1; short card_type_5 : 1; short card_type_active_lo : 1; short card_type_3 : 1; short card_type_2 : 1; short card_type_1 : 1; short card_type_async : 1; short ATR_char_cnt : 16; unsigned long ATR_async_freq; unsigned char * ATR_buff; } typ_Card_ATR_param;

Members:

Fields described here except all card_type_x bit fields are n/a.

card_num Card socket number (0 ~ 1) to perform ATR communication. Should be filled before ATR.

Value Meaning 0 stands for socket #1 (i.e. SAM card). 1 stands for socket #2 (i.e. ISO standard

size card socket).

card_type_active_lo Card reset type. Filled by ATR session.

MC-998TM


card_type_async Set if the card is asynchronous. Better be filled before ATR.

ATR_char_cnt Count of ATR data returned.

ATR_async_freq Oscillator frequency to feed into card for asynchronous card. Should be set as one of the following flags before asynchronous card ATR:

Value Meaning CARD_ATR_AFREQ_3571712 set to 3.571712 MHz CARD_ATR_AFREQ_7143424 set to 7.143424 MHz CARD_ATR_AFREQ_8290304 set to 8.290304 MHz

ATR_buffer

pointer to ATR data buffer in which the ATR data will be stored.

2.7.1.2 I2C Serial Data

typ_IIC_param_block is the buffer used for I2C like synchronous card session.

typedef struct { unsigned int delay_unit : 8; unsigned int pin_SCL : 8; unsigned int pin_SDA : 8; unsigned int IIC_flag : 8; unsigned int send_length : 16; unsigned int read_length : 16; unsigned char * send_buffer; unsigned char * read_buffer; } typ_IIC_param_block;

Members: delay_unit

Specify the period of clock pulse. 0 for the fastest.

pin_SCL Clock pin for this session. Should be one of the following pins:

Value Meaning CARD_PIN_C8 C8 pin of card socket CARD_PIN_C4 C4 pin of card socket CARD_PIN_CLK C3 pin of card socket

MC-998TM


CARD_PIN_IO C7 pin of card socket

Pin_SDA Data pin for this session. Should be one of the pins as above.

IIC_flag Detailed description of the I2C like synchronous card session. Set by bit-OR’ing the following flags:

Value Meaning CARD_IIC_LSB_1ST data is LSB first. CARD_IIC_WITH_ACK send and check ACK CARD_IIC_END_NOTACK end w/o sending ACK CARD_IIC_WITH_STOP send STOP condition CARD_IIC_WITH_START send START condition

send_length Length of data to send. For command mostly.

read_length Length of data to read. For data mostly

send_buffer Pointer to buffer storing data to send.

read_buffer Pointer to buffer storing data read. Filled after the session

2.7.2 Common Card Routines 2.7.2.1 Card Interface Initialization

Card_init() is used to initialize card interface. This function should be called once before any operation on card interface and card sockets.

short Card_init ( void ) ; Parameters

None.

Return Values

MC-998TM



2.7.2.2 Card Interface Power On

Card_power_on() is used to power on the entire card interface unit (i.e. the smart card interfacing subsystem), but leave the card sockets un-powered.

short Card_power_on ( void ) ; Parameters

None.

Return Values

The value returned in current version is meaningless, please do not use. Remarks

This function turns on the power of the card interface unit, and the unit will consume the valuable current from the handheld. So it is highly recommended that you call this function only when you need to operate on cards, and deactivate all cards and turn off this unit’s power as soon as you finish the operation. When you finish all operation on cards, you may use Card_deactivate() to deactivate all IC cards AND turn off the power of the card interface unit.

2.7.2.3 Selecting Card Socket At one time, user can operate on only one card, Card_select_sock() selects a card as current operating socket. The following card operations will be carried out on the card selected. The status of the card selected before Card_select_sock() is left unchanged (idle if it’s powered).

short Card_select_sock ( unsigned long socknum ) ;

Parameters

MC-998TM


socknum

socket number to select. Value Meaning

1 selects socket #1 (i.e. SAM card). 2 selects socket #2 (i.e. ISO standard

size card socket). 0 to hang all 2 sockets.

Because the system clock may change during card operations, it’s extremely important for the system to switch back to its normal speed, without losing control of the cards, (please refer to MC-998 Hand-Held Smart Card Read/Write Device (RWD) Software Developer’s Manual).

Return Values


Remarks

Please note that, in this function, the socknum is 1 for socket #1 (i.e. SAM card).and 2 for socket #2 (i.e. ISO standard size card socket).

2.7.2.4 Getting ATR

Card_ATR() activates the designated IC card and waits for its ATR.

short Card_ATR ( typ_Card_ATR_param * pCAP ) ;

Parameters pCAP

Pointer to typ_Card_ATR_param which stored card parameters and ATR data (c.f. typ_Card_ATR_param) Before calling this function, user should fill pCAP with correct values. Please note that the pCAP.card_num is not the same as the socknum in the function Card_select_sock(), the equation is: pCAP.card_num = socknum - 1, i.e. when you use socknum =1 when calling Card_select_sock(), here you should fill pCAP.card_num with 0 when you assign values to pCAP.

MC-998TM


Return Values

ATR length. Set as the same as pCAP->ATR_char_cnt.

Remarks

Before calling of this function, please call Card_select_sock() first. Please note that, in this function, the pCAP.card_num is 0 for socket #1 (i.e. SAM card).and 1 for socket #2 (i.e. ISO standard size card socket). Be careful when you assign the pCAP.card_num before calling.

2.7.2.5 Get Current Socket Number

Card_get_curr_sock() gets the number of the socket currently selected.

short Card_get_curr_sock ( void ) ; Parameters

None.

Return Values

Value Meaning 1 socket #1 (i.e. SAM card) is currently

selected. 2 socket #2 (i.e. ISO standard size card

socket) is currently selected. -1 no card socket is selected

2.7.2.6 Deactivating Current Card Socket

Card_deact_curr_sock() is used to power off the selected card socket. Only the selected card socket will be powered off, the others are not affected, while Card_deactivate() will power off all 2 card sockets AND the card interface unit.

short Card_deact_curr_sock ( void

MC-998TM


) ;

Parameters

None.

Return Values

The value returned in current version is meaningless, please do not use. 2.7.2.7 Deactivating All Cards/Turning off Card Interface Unit

Card_deactivate() is used to deactivate all IC cards AND the card interface unit.

short Card_deactivate ( void ) ; Parameters

None.

Return Values


2.7.2.8 Socket 2 Status

Card2_stat() shows if there is card in socket #2 (i.e. ISO standard size card socket)

short Card2_stat ( void ); Parameters

None.

Return Values

Value Meaning Zero no card in socket #2

MC-998TM


None zero card present in socket #2

2.7.3 Synchronous Card Routines

2.7.3.1 Direct Pin Controls

2.7.3.1.1 RST Pin Macro Card_pin_RST_hi sets the RST pin of the IC card in the current activated socket, and macro Card_pin_RST_lo resets it.

2.7.3.1.2 C6 Pin

Macro Card_pin_C6_hi sets the C6 pin of the IC card in the current activated socket, and macro Card_pin_C6_lo resets it.

2.7.3.1.3 C3/C4/C7/C8 Pins Card_pin_session() is used to control/read C3/C4/C7/C8 pins. char Card_pin_session( unsigned long PFLAG ); Parameters PFLAG :

set by bit-OR’ing following flags a) pin flags : one of the following pin specified

Value Meaning CARD_PIN_C8 C8 pin of card socket CARD_PIN_C4 C4 pin of card socket CARD_PIN_CLK C3 pin of card socket CARD_PIN_IO C7 pin of card socket

b) operation flags Value Meaning CARD_PIN_READ read specified pin CARD_PIN_SET write 1 to specified pin CARD_PIN_CLR write 0 to specified pin CARD_PIN_SWITCH_IN switch specified pin to input mode CARD_PIN_SWITCH_OUT : switch specified pin to output mode

MC-998TM


Return Values Valid only when CARD_PIN_READ is specified. Value Meaning 0 specified pin is 0 None zero specified pin is 1

2.7.3.2 I2C Serial Communication

Card_IIC_session() initiates an I2C like communication session.

short Card_IIC_session ( typ_IIC_param_block * pIPB ) ;

Parameters

pIPB

Pointer to typ_IIC_param_block which contains descriptions of the session

Return Values

Value Meaning Zero session ended successfully. None zero abnormal ends. Mostly because of the invalid

ACK bit.

2.7.4 Asynchronous Card Routines

2.7.4.1 T = 0 Protocol

Card_exchange_T0_header() is the T=0 data exchanger. short Card_exchange_T0_header ( unsigned char * pbuff ) ;

Parameters

pbuff

Pointer to buffer that stores conversation flag and T=0 TPDU data when entering the routine, and response data length and data after the routine returns.

MC-998TM


Data buffer

1) TPDU for receiving data

Before calling the routine:

struct { unsigned short is_TPDU_for_receiving; unsigned char CLS; unsigned char INS; unsigned char P1; unsigned char P2; unsigned char Le; unsigned char rec_buff[Le+2]

}

Where is_TPDU_for_receiving is not 0 (indicating receiving mode), Le is the expected length of response data. The buffer should be large enough to hold the data received.

Upon returning of the routine:

struct { unsigned short received_data_length; unsigned char CLS; unsigned char INS; unsigned char P1; unsigned char P2; unsigned char Le_left; unsigned char rec_buff[received_data_length]

}

Where received_data_length is the actual length of the data received, including the SW; if Le_left is not 0, the T=0 data exchanging was not completed. rec_buff holds the data received and SW.

2) TPDU for sending data Before calling the routine:

struct { unsigned short is_TPDU_for_receiving; unsigned char CLS;

MC-998TM


unsigned char INS; unsigned char P1; unsigned char P2; unsigned char Lc; unsigned char send_buff[Lc]; unsigned char rec_buff[2];

}

Where is_TPDU_for_receiving is 0 (indicating transmitting mode), Lc is length of the data to be sent. The buffer should be large enough to hold the data received.

Upon returning of the routine:

struct {

unsigned short received_data_length; unsigned char CLS; unsigned char INS; unsigned char P1; unsigned char P2; unsigned char Lc_left; unsigned char send_buff[Lc]; unsigned char rec_buff[2];

}

where received_data_length is the actual length of the data received, i.e., SW; if Lc_left is not 0, the T=0 data exchanging was not completed. rec_buff holds SW.

Return Values


2.7.4.2 T = 1 Protocol

Card_exchange_T1_frame() is the T=1 frame exchanger.

short Card_exchange_T1_frame (

unsigned char * pbuff ) ;

Parameters pbuff

MC-998TM


Pointer to buffer that stores packet length and T=1 frame data.

Data buffer struct { unsigned short pack_length; unsigned char frame_data[pack_length]; }

After the routine returns, pack_length in data buffer will be set to the length of the response packet, and frame_data will be set to response packet data.

Return Values


2.8 UART Peripherals


2.8.1.1 UART Status

typ_UART_stat_word reflects the detailed status of UART. typedef union { struct { unsigned int in_FIFO_full : 1; unsigned int in_FIFO_half : 1; unsigned int in_data_ready : 1; unsigned int in_old_data : 1; unsigned int in_over_run : 1; unsigned int in_frame_err : 1; unsigned int in_break : 1; unsigned int in_parity_err : 1; unsigned int out_FIFO_empty : 1; unsigned int out_FIFO_half : 1; unsigned int out_FIFO_available : 1; unsigned int out_send_brk : 1; unsigned int out_no_CTS : 1; unsigned int out_busy : 1; unsigned int out_CTS_stat : 1; unsigned int out_CTS_delta : 1; unsigned int n_a_7 : 1; unsigned int n_a_6 : 1;

MC-998TM


unsigned int n_a_5 : 1; unsigned int n_a_4 : 1; unsigned int n_a_3 : 1; unsigned int buff_data_available : 1; unsigned int buff_overflow : 1; unsigned int UART_on : 1; unsigned char n_a;

} bits; unsigned long l_word; } typ_UART_stat_word;

Members Bits

UART status word interpreted as bit fields, all the n_a_* fields represent the n/a bits. All except buff_data_available, buff_overflow and UART_on are low level status indicators and it’s highly recommended that user do not use them. in_FIFO_full set if input FIFO is full in_FIFO_half set if input FIFO reaches half capacity in_data_ready set if input FIFO is not empty in_old_data set if data in FIFO is old (i.e. UART has been in idle

mode for a while) in_over_run set if an overrun error has occurred in_frame_err set if an frame error has occurred in_break set if break condition detected in_parity_err set if parity error has occurred out_FIFO_empty set if output FIFO is empty out_FIFO_half set if output FIFO reaches half capacity out_FIFO_available set if output FIFO is available (not full) out_send_brk set if initiating a break condition out_no_CTS set if CTS is ignored out_busy set if UART is sending a character out_CTS_stat CTS state out_CTS_delta set if CTS state changed buff_data_available set if there is data stored in UART buffer buff_overflow set if UART buffer has overflowed UART_on set if UART is on

l_word UART status word in raw form

2.8.1.2 Fcntl Word

MC-998TM


typ_UART_f_word is the device control word used by function UART_fcntl().

typedef union { struct { unsigned int tx_enable : 1; unsigned int send_brk : 1; unsigned int ignore_cts : 1; unsigned int force_parity_err : 1; unsigned int loop_test : 1; unsigned int n_a_10 : 1; unsigned int rts_auto : 1; unsigned int rts_value : 1; unsigned int rx_polarity : 1; unsigned int tx_polarity : 1; unsigned int n_a_5 : 1; unsigned int n_a_4 : 1; unsigned int n_a_3 : 1; unsigned int n_a_2 : 1; unsigned int n_a_1 : 1; unsigned int n_a_0 : 1; } bits; unsigned short s_word; } typ_UART_f_word;

Members bits

UART device control word interpreted as bit fields, all the n_a_* fields represent the n/a bits. tx_enable set if UART transmission is enabled send_brk set if initiating a break condition ignore_cts set if CTS is ignored force_parity_err set if forcing a parity error loop_test set if UART is in internal loop testing mode rts_auto set if RTS is set automatically rts_value RTS level rx_polarity set if inverse RX polarity is used tx_polarity set if inverse TX polarity is used

s_word

UART status word in raw form

2.8.2 Initialization of UART

MC-998TM


UART_init() is used to turn on/off UART.

short UART_init ( unsigned long uflags ) ;

Parameters uflags

Using UART_OFF as the only parameter will turn off all UART related peripherals including modem, infrared and RS232 interface. UART is turn on by bit-OR’ing UART_xxx_ON and one or more of following flags: a) peripheral flags:

One and only one of following 3 peripherals should be specified Value Meaning UART_232_ON set if RS232 is used for UART UART_IRDA_ON set if infrared interface is used for UART UART_MODEM_ON set if internal modem is used for UART

b) No parity bit is present if none of the 2 flags in this group is specified. Only one of the following 2 flags should be specified Value Meaning UART_ODD_PARITY set if odd parity bit is used UART_EVEN_PARITY set if even parity bit is used

c) UART_2_STOP_BITS specified if 2 stop bits used. 1 stop bit by default. d) UART_8_DATA_BITS specified if 8 data bits used. 7 data bits by default e) Baud rate flags:

One and only one of following flags should be specified to set the baud rate of UART communication: Value Meaning UART_BAUD_115200 sets baud rate to 115,200 bps UART_BAUD_57600 sets baud rate to 57,600 bps UART_BAUD_38400 sets baud rate to 38,400 bps UART_BAUD_28800 sets baud rate to 28,800 bps UART_BAUD_14400 sets baud rate to 14,400 bps UART_BAUD_19200 sets baud rate to 19,200 bps UART_BAUD_9600 sets baud rate to 9,600 bps UART_BAUD_4800 sets baud rate to 4,800 bps UART_BAUD_2400 sets baud rate to 2,400 bps

MC-998TM


UART_BAUD_1200 sets baud rate to 1,200 bps UART_BAUD_600 sets baud rate to 600 bps UART_BAUD_300 sets baud rate to 300 bps

f) None integer pre-scalar setting: Value Meaning UART_NIP_ON internal use only.

Return Values


2.8.3 Reading UART

UART_get_char() is used to read data from UART data buffer. It’s highly recommended that it be called in comm_data message dealer.

short UART_get_char ( void ) ;

Parameters

None. Returned Values

Value Meaning -1 no data available 0x00~0xFF the data received.

2.8.4 Writing UART

UART_send_char() is used to write data to UART output buffer.

short UART_send_char ( unsigned long ch ) ;

Parameters Ch

Data to send.

MC-998TM


NOTE: Only 8 LSBs are used.

Returned Values

Value Meaning 0 data has been successfully sent -1 sending failed. Call UART_stat() to see the

reason why it failed.

2.8.5 Device Control of UART UART_fcntl() is used to perform device control on UART.

unsigned long UART_fcntl ( unsigned long Cword ) ;

Parameters Cword

Set to UART_F_INQ to read current device control setting or set current device control by bit-OR’ing one or more of following flags

Value Meaning a) UART_F_TX_POL set if inverse TX polarity b) UART_F_RX_POL set if inverse RX polarity c) RTS control flags. Only one of 3 flags should be specified

UART_F_RTS_HIGH force RTS high UART_F_RTS_LOW force RTS low UART_F_RTS_AUTO RTS is set automatically

d) UART_F_LOOP_TEST force internal loop back e) UART_F_FORCE_PARITY_ERR force parity bit error (for debugging) f) UART_F_NO_CTS ignore CTS g) UART_F_SEND_BREAK initiates a break condition h) UART_F_TX_ENABLE TX is disabled if not specified

Returned Values

Status word with bit fields described as typ_UART_stat_word.

Example

#include <api.h>

MC-998TM


/* UART_fcntl to ignore CTS pin and all the other fcntl bits unchanged */ void main(void) {

//………… UART_fcntl ( UART_F_INQ) | UART_F_NO_CTS ) ;

} 2.8.6 Status Reading

UART_stat() is used to get UART status.

unsigned long UART_stat ( void ) ; Parameters

None.

Returned Values

Status word with bit fields described as typ_UART_stat_word.

2.9 User Timer

2.9.1 Set User Timer

SPT_set() sets user timer period. A time_out message will be sent when this period of time expires and automatically turn off the timer.

short SPT_set ( unsigned long duration ) ;

Parameters duration:

MC-998TM


Time out duration of user timer in 1/64 second unit. Only 16 LSBs are used.

Return Values


2.9.2 Read User Timer

SPT_read() reads user timer.

short SPT_read ( void ) ; Parameters

None.

Return Values

Time left to time_out event in 1/64 second unit.

2.9.3 Register User Timer Callback Routine SPT_register_call_back() set a callback routine that is called each time a time_out event occurs

short SPT_register_call_back ( void (* CBroutine) (void) ) ; Parameters CBroutine

callback routine name

Return Values


Remarks

MC-998TM


The callback routine is called before the time_out message is sent. It's for advanced programming only!

Example

#include <api.h> /* this example shows how to use user timer callback routine cb_spt will be called for the first time 4 seconds after SPT_set in the main function , and every 1 second after that */ void cb_spt(void) { SPT_set(64); /* reinitialize user timer */ } main ( ) { //………… SPT_register_call_back(cb_spt); SPT_set(256); } //end of main

2.10 Display

2.10.1 Initialization Disp_init() controls the LCD display panel.

short Disp_init ( unsigned long PowerFlag ) ;

Parameters PowerFlag

One of the following flags: Value Meaning DISP_INIT_ON turn on LCD panel. The entire display

panel is accessible. DISP_INIT_OFF turn off LCD panel. The entire display

panel is inaccessible

MC-998TM


DISP_INIT_POWER_SAVE turn off the main display portion of the LCD panel. Only the static icon (bull’s eye) is accessible. Anything written to the panel at this time will be displayed the next time LCD is turned on.

Return Values


2.10.2 Character Displaying

2.10.2.1 Font setting

Disp_set_font_attribute() sets current font and character attribute.

short Disp_set_font_attribute ( unsigned long FA_FLAG ) ;

Parameters FA_FLAG

Set by bit-OR’ing the attribute flag and the font type flag Attribute flag

Value Meaning not specified normal display DISP_FONT_ATTR_INV inverted display

Font type flag set as one of the following fonts Value Meaning DISP_FONT_TYPE_7x9 7x9 ASCII font displayed as 8x16 DISP_FONT_TYPE_16x16_SYMBOL 16x16 Chinese char font , internal code

2121H~297EH DISP_FONT_TYPE_16x16_CCHAR 16x16 Chinese char font , internal code

3021H~777EH DISP_FONT_TYPE_5x7_ENG 5x7 ASCII font displayed as 6x8 DISP_FONT_TYPE_5x7_RUS 5x7 Cyrillic font displayed as 6x8 DISP_FONT_TYPE_Xx8_SPEC Xx8 special symbols DISP_FONT_TYPE_LOGO Xx16 special symbols for logos.

Return Values

MC-998TM



2.10.2.2 Character Displaying

Disp_write_str() and Disp_write_char() are used to display characters on main display using current font and attributes. Cursor is moved to the end of the last written character.

short Disp_write_char ( unsigned long ch ) ; short Disp_wirte_str ( char * dstr ) ;

Parameters ch

character to be displayed. 8 LSBs are valid. Dstr

string to be displayed

Return Values


2.10.2.3 Clear Screen

Macro clr_scr() cleans the matrix display portion of the LCD short clr_scr ( void ) ; Parameters

None.

Return Values

MC-998TM



2.10.2.4 Cursor Setting

Macro goto_xy() controls the cursor.

short goto_xy ( unsigned char x, unsigned char y

) ;

Parameters x

x coordinate of the cursor. Range is 0~127 in pixel.

y y coordinate of the cursor. Range is 0~7 in ASCII line (8-pixels/ASCII line)

Return Values


Remarks

No range check is performed by this macro so the user has to ensure the validity of the parameters. Please note the unit is different for x and y.

2.10.3 Graphic Displaying

2.10.3.1 Clear Graphic Windows

Macro clr_win() is used to clear a graphic window.

short clr_win( unsigned char x1, unsigned char y1,

unsigned char x2, unsigned char y2

) ;

MC-998TM


Parameters (x1, y1) and (x2, y2)

Are coordinates of two diagonal corners of the window to be cleared. Range of x1,x2 is 0~127 in pixel, Range of y1,y2 is 0~63 in pixel.

Return Values


2.10.3.2 Pixel Based Graphics

2.10.3.2.1 Pixel Reading

Macro get_pixel() is used to read pixel.

short get_pixel ( unsigned char x, unsigned char y

) ;

Parameters x

X coordinate of the pixel to be read. Range is 0~127 in pixel

y Y coordinate of the pixel to be read. Range is 0~63 in pixel.

Return Values

Value Meaning 0 the pixel is blank (same as background). 1 the pixel is set (black).

Remarks

No range check is performed by this macro so the user has to ensure the validity of the parameters.

MC-998TM


2.10.3.2.2 Pixel Writing

Macro put_pixel() is used to write pixel.

short put_pixel( unsigned char x, unsigned char y, unsigned char p, unsigned char mode ) ;

Parameters x

X coordinate of the pixel to be read. Range is 0~127 in pixel

y Y coordinate of the pixel to be read. Range is 0~63 in pixel.

p Pixel value to be written

mode One of following flags for putting pixel

Value Meaning DISP_PUT_MODE_PUT just write this pixel DISP_PUT_MODE_OR pixel is written as bit inclusive OR’ing p

and the previous value of this location. DISP_PUT_MODE_XOR pixel is written as bit exclusive OR’ing p

and the previous value of this location. DISP_PUT_MODE_AND pixel is written as bit AND’ing p and the

previous value of this location. Return Values


Remarks

No range check is performed by this macro so the user has to ensure the validity of the parameters.

MC-998TM


2.10.3.3 Bitmap Based Graphics

2.10.3.3.1 Bitmap Structure

typ_BMP_rec shows how bitmap is stored in memory. typedef struct { unsigned int X : 8; unsigned int Y : 8; unsigned int width : 8; unsigned int height : 8; unsigned char data; } typ_BMP_rec ;

Members: X,Y

Coordinate of the upper left corner of the bitmap.

width Width of the bitmap. Will be clipped if (X+width) > 127

height Height of the bitmap. Will be clipped if (Y+height) > 63

data

A dummy field denoting the start of bitmap data

2.10.3.3.2 Get Bitmap

Disp_get_bmp() reads a rectangular area of the main display and store it in memory. short Disp_get_bmp ( typ_BMP_rec * pb ) ;

Parameters pb

Pointer to buffer with type typ_BMP_rec. fields X, Y, width and height of *pb should be filled before calling.

Return Values

MC-998TM


Value Meaning

0 successful -1 failed (parameter error)

Example

#include <api.h> /* This demo reads a rectangular area (10,20)-(25,40) into buffer */ unsigned char buffer[1000]; void main(void) {

typ_BMP_rec * pb = (typ_BMP_rec *) buffer ; //……… pb->X = 10; pb->Y = 20; pb->width = 15; pb->height = 20; if ( Disp_get_bmp(pb) ) { /* Your error handling routine */ }

} //end of main

2.10.3.3.3 Put Bitmap

Disp_put_bmp() writes a rectangular area of the main display with data stored in memory. There’re 4 putting modes, which could be specified by Disp_set_bmp_put_mode(). short Disp_put_bmp (

typ_BMP_rec * pb ) ;

Parameters pb

MC-998TM


pointer to buffer with type typ_BMP_rec, fields X, Y should be filled before calling. Return Values

Value Meaning 0 successful -1 failed (parameter error)

Example

#include <api.h> /* This demo writes an arrow to position(0,0) and (15,15)*/ unsigned char buffer[1000]; void main(void) { typ_BMP_rec * pb = (typ_BMP_rec *) buffer; //…….. pb -> X = pb -> Y = 0; pb -> width = 5; pb -> height = 8; buffer[4] = 0x1f; buffer[5] = 0x3e; buffer[6] = 0xfc; buffer[7] = 0xd8; buffer[8] = 0x10; Disp_put_bmp(pb); pb -> X = pb -> Y = 15; Disp_put_bmp(pb); } //end of main

2.10.3.3.4 Bitmap Put Mode Setting

Disp_set_bmp_put_mode() sets bitmap putting mode. short Disp_set_bmp_put_mode ( unsigned long pmode

MC-998TM


) ;

Parameters pmode

One of putting mode that is the same as in put_pixel().

Return Values


2.10.4 Icons

2.10.4.1 Customized Icon Setting

User can control certain icons by obtaining control of them from system. Disp_icon_customize() is such a function. short Disp_icon_customize ( unsigned long icflag ) ;

Parameters icflag

Set by bit-OR’ing the following flags or simply use DISP_ICON_C_NONE to give up all user control.

Value Meaning DISP_ICON_C_CARD_SYMS user can control the card symbols DISP_ICON_C_7SEGS user can control the four 7-SEG display

including the semicolon DISP_ICON_C_SPEAKERS user can control the speaker/speaker

disable symbols DISP_ICON_C_BELL user can control the bell symbol DISP_ICON_C_ANTENNA user can control the antenna symbol DISP_ICON_C_CONNECT user can control the connected symbol DISP_ICON_C_BATTERY user can control the battery level symbols

Return Values


Remarks

MC-998TM


This function is for advanced programming only .

2.10.4.2 Set Icons

Disp_icon_set() is used to set the customized icons. short Disp_icon_set ( unsigned long * piflag ) ;

Parameters piflag

A pointer to a parameter block that is 64 bits long. Each bit stands for a certain segment (even though not all these 64 segments are implemented). A set bit means the corresponding segment is lit up; a cleared bit means it’s not.

Return Values


2.10.4.3 Read Icon Settings

Disp_icon_read() is used to read the current setting of the customized icons. short Disp_icon_read ( unsigned long * piflag ) ;

Parameters piflag

same as in Disp_icon_set().

Return Values


2.10.4.4 7-SEG Display In Icon Area

MC-998TM


User’s controlling directly on the 7-SEG display area is not supported in this version. 2.10.5 LCD Contrast Controlling

2.10.5.1 Read Contrast Setting

Macro get_LCD_contrast() reads current LCD contrast setting. short get_LCD_contrast ( void ) ;

Parameters

None.

Return Values

Value Meaning 0~63 representing current LCD contrast level.

2.10.5.2 Change Contrast

Macro inc_LCD_contrast() and dec_LCD_contrast() are used to change contrast setting. The inc_LCD_contrast() function increase the LCD contrast by 1 while the dec_LCD_contrast() function decrease the contrast by 1. short inc_LCD_contrast ( void ) ; short dec_LCD_contrast ( void ) ; Parameters

None.

Return Values

MC-998TM



2.11 RF Information


2.11.1.1 Status Byte

typ_RFI_stat_flag is the description of the status byte of RF information decoder (i.e. SM8212B from Seiko NPC) returned by RFI_read_status().

typedef union { struct { unsigned int n_a_7 : 1; unsigned int syn_detected : 1; unsigned int idle_mode : 1; unsigned int preamble_mode : 1; unsigned int lock_mode : 1; unsigned int write_mode : 1; unsigned int receiving_mode : 1; unsigned int busy_flag : 1; } bits; unsigned char byte; } typ_RFI_stat_flag;

Members bits

RFI decoder status byte interpreted as bit fields n_a_7 N/A bit syn_detected SYNC word detected idle_mode RFI unit in idle state preamble_mode RFI unit in preamble detecting state lock_mode RFI unit in SYNC lock state write_mode RFI unit is ready to be programmed receiving_mode RFI unit is in data receiving state busy_flag RFI unit is busy with internal affairs, no time for talking

byte

Status byte in raw data form Remarks

MC-998TM


As the RFI message receiving subsystem is of POCSAG protocol, using the SM8212B from Seiko NPC as the POCSAG decoder, so please refer to the POCSAG standard and SM8212B Data Sheet for advanced programming.

2.11.1.2 Subsystem Configuration Byte

typ_RFI_configuration_flag describes the configuration byte of RFI message receiving subsystem. Returned by RFI_read_configuration().

typedef union { struct { unsigned int n_a_7 : 1; unsigned int n_a_6 : 1; unsigned int n_a_5 : 1; unsigned int n_a_4 : 1; unsigned int msg_coming : 1; unsigned int msg_ended : 1; unsigned int word_mode : 1; unsigned int RFI_on : 1; } bits; unsigned char byte ; } typ_RFI_configuration_flag ;

Members bits

RFI subsystem configuration byte interpreted as bit fields. All the n_a_* bits denote n/a bits. msg_coming set if new RFI message is being received msg_ended set if a RFI message receiving session has ended word_mode set if RFI subsystem works in word mode RFI_on set if RFI subsystem is working

byte

configuration byte in raw data form

2.11.1.3 Message Data Buffer typ_RFI_message is the description of the message data returned when RFI unit is working in message mode.

MC-998TM


typedef { unsigned int isAlphanumeric : 1; unsigned int n_a_bits : 2; unsigned int addr : 3; unsigned int func : 2; unsigned char data; } typ_RFI_message Members (please refer to the POCSAG standard) isAlphanumeric

set if current message is alphanumeric.

n_a_bits N/A

addr address on which current message is received

func function code of current message.

data dummy field denoting the start of message data. Data format of message data: typedef { unsigned int err : 1 ; unsigned int data : 7 } typ_RFI_msgdata; err

is set if transmission error occurred when receiving this byte;

data is the data received, which will be 0~15 for numeric message and 0~127 for alphanumeric message

2.11.2 Initialization

RFI_init() is the main switch of the RFI unit.

MC-998TM


unsigned long RFI_init ( unsigned long * pFB ) ;

Parameters pFB

Pointer to RFI decoder parameter data block. If it’s NULL, the RFI unit will be turned off so no RFI message will be received, and the power consumption of the whole system would be reduced significantly (please refer to SM8212B Data Sheet).

Return Values


2.11.3 Message Reading

RFI_read_msg() is the subroutine to read a received RFI message. It’s highly recommended that it be called in RF_new message dealer when RFI unit is in message mode. And it should not be used when RFI unit is working in word mode.

unsigned long RFI_read_msg ( typ_RFI_message * pBuff ) ;

Parameters pBuffer

Pointer to data buffer that the received message will be stored in.

Return Values

Length of received message data.

2.11.4 Status Reading

RFI_read_status() is the subroutine to read the status byte of the RFI information decoder.

unsigned short RFI_read_status ( void ) ;

MC-998TM


Parameters

None. Return Values

RFI decoder status byte which could be interpreted by typ_RFI_stat_flag.

2.11.5 Configuration Reading

RFI_read_configuration() is the subroutine to read the configuration byte of the RFI message receiving subsystem.

unsigned short RFI_read_configuration ( void ) ;

Parameters

None.

Return Values

RFI message receiving subsystem configuration byte that could be interpreted by typ_RFI_configuration_flag.

2.11.6 Register RF Information Callback Routine

RFI_register_call_back() set a callback routine that is called each time a RFI decoder data ready interrupt occurs. It should not be used when RFI unit works in message mode.

void RFI_register_call_back( void (* CBroutine)(unsigned long msgword) ); Parameters CBroutine

Callback routine name. The parameter of this routine is the data word returned by RFI decoder (please refer to SM8212B Data Sheet)

MC-998TM


Return Values

None.

Remarks

Using this function and RFI word mode is not recommended unless the programmer is experienced with pager programming.

2.11.7 Set Receiving Method

RFI_set_msg_level() determines what mode the RFI is working in.

void RFI_set_msg_level ( unsigned long msgmode ) ;

Parameters msgmode

Value Meaning RFI_MSG_LEVEL_MSG for message mode RFI_MSG_LEVEL_WORD for word mode

Return Values

None.

2.12 Download

enter_download_mode() is used to enter download mode.

void enter_download_mode ( void ) ;

Parameters

None.

MC-998TM


Return Values

None.

Note

This is a one-way subroutine that never returns, the only way to exit download mode is to reset the system by pressing reset button or a reset command received from UART.

2.13 Flash memory There are 2 low-level functions to access flash memory. They are for advanced programming only. It’s highly recommended that user should not call these functions directly. Any invalid address accessing will cause unwanted exceptions. Reading of the flash needs no subroutines.

2.13.1 Erasing Block

FLASH_erase_block() erases a 64kbyte block at a given address in flash memory

short FLASH_erase_block ( void * blockaddress ) ;

Parameters blockaddress

Pointer to denote the address of the block to be erased. Recommended to be aligned to 64k boundary.

Return Values

Value Meaning 0x80 successful other values not successful, error occurred

2.13.2 Writing Data

FLASH_write_record() is used to write a record (data with certain length) to a specified flash memory area.

MC-998TM


short FLASH_write_record ( FLASH_wr_param * pfwp ) ;

Parameters pfwp

Pointer to a flash write parameter block which is defined as typedef { void * ptr_buffer; void * ptr_FLASH_addr; unsigned long data_length } FLASH_wr_param Members of FLASH_wr_param: ptr_buffer :

Pointer to the data buffer containing data to write.

ptr_FLASH_addr: Pointer to destination address in flash memory.

data_length : Numbers of data to write, in WORD unit (1 word = 2 bytes).

Return Values

Value Meaning 0x80 successful other values not successful, error occurred

Remarks

data_length is in word unit, for example, if your want to write 9 bytes to FLASH, the data_length should be 5 (words) Data written should not cross the block boundary.

2.14 Miscellaneous

MC-998TM


2.14.1 Getting Current OS Version Information

Check_Version() performs version check, returning all version information about the current OS (Operating System).

void Check_Version ( unsigned char * vbuff ) ;

Parameters vbuff

Pointer to the buffer to store the version data. Version data is 12-byte long: typedef struct { unsigned char v_month; unsigned char v_day; unsigned short v_year; unsigned short v_hour; unsigned char v_min; unsigned char v_sec; unsigned char v_main; unsigned char v_sub; unsigned short v_rel; } typ_version_content ; Members of typ_version_content: v_month, v_day, v_year

last modification date of BIOS;

v_hour, v_min, v_sec last modification time of BIOS;

v_main version number main part;

v_sub version number sub part

v_rel release number

Return Values

MC-998TM


None.

2.14.2 Delay 1 Microsecond (mS)

delay_1ms() is a very essential system delay function. Using this function, users may write any delay function of their own.

void delay_1ms ( void ) ;

Parameters

None. Return Values

None.

Example

/* This example demos how to write function to delays n mS */ // delay n micro seconds subroutine: void delay_n_ms(short mscnt) { for ( ; mscnt > 0; mscnt--) delay_1ms(); }

MC-998TM


Chapter 3 Database Subroutines

MC-998TM


Database Subroutines 3

3.1 Overview of MC-998 Database Mc-998 uses 1M bytes (expandable to 4M bytes) Flash as program storage device, All the OS code occupies about 350K bytes. The space left is for user program and user data, this space is Non-Volatile type media, due to the characteristics of the Flash device, it’s block (64K bytes/block) oriented, not byte oriented, organization, MC-998 provide a way to use this space as a database. Users can create / formatting / erasing a volume and adding / deleting records to this database volume by calling the following APIs. Please note that several functions in the chapter need use pre-defined system global variables as the parameters, Please do it exactly as demanded, otherwise your program won’t work properly. For more about the global variables used in the database, please refer to section 3.15.

3.2 Database Parameters get_db_sys_param() returns the parameters of current flash database system.

void get_db_sys_param ( typ_db_sys_param * pdsp ) ;

Parameters pdsp

Pointer to global variable parameter block dsp into which the returned database parameters will be filled. typ_db_sys_param is defined as :

typedef struct { unsigned long blocks; unsigned long start_addr; unsigned long block_size; } typ_db_sys_param; Members of typ_db_sys_param: blocks

Total blocks of flash memory used for database.

start_addr

MC-998TM


Address of the 1st flash memory block for database

block_size Size of each flash memory block.

Return Values

None.

Remarks

This statement: get_db_sys_param(&dsp) ;

should be place in the initialization routine of the application program should database be used. Please note that dsp is a global system variable, You MUST use it as the parameter here, Do NOT modify dsp before calling. For more about the global variables used in the database, please refer to section 3.15.

3.3 Check Databases DB_check_db() is use to find valid databases in the whole database system.

short DB_check_db ( typ_db_description * fs ) ;

Parameters fs

Array of typ_db_description where parameters of all databases found will be written. You MUST use system defined global variable filesys as the parameter here. see the sample code in the remarks typ_db_description is defined as:

typedef struct { unsigned short db_id; unsigned short block_cnt; unsigned long start_addr; } typ_db_description;

Members of typ_db_description:

MC-998TM


db_id An id number to identify the database type.

block_cnt Max block count number, which is total blocks of flash memory allocated for the database. For example, if a database has 4 blocks, then its block_cnt is 3.

start_addr Block number of the 1st block of the database.

Return Values

Number of the databases found. The return value MUST be assigned to the global variable file_sys_cnt, see the sample code in the remarks.

Remarks

The following codes should be put in the initialization routine of the application program should database be used. get_db_sys_param(&dsp) ;

if (!(file_sys_cnt = DB_check_db(filesys))) { /* format all your databases here */ /* for e.g. */ /* DB_format_db(0, 5, sizeof(MyRec)) */ } else { /* Check if all the databases found is correct */

/* Check their ids, block counts, record sizes, or even the validity of each record */

} /* Do it again if formatting or reformatting occurred */ file_sys_cnt = DB_check_db(filesys); /* The databases are ready after this line */ Please note that file_sys_cnt and filesys are all global system variables, In your program, you MUST use filesys as the parameter, and store return value to

MC-998TM


file_sys_cnt exactly as the sample code here, Do NOT modify these global variables before and after calling. After your calling of DB_format_db() or erase_db_sys(), Please call the DB_check_db() AGAIN as what you see in the sample code. For more about the global variables used in the database, please refer to section 3.15.

3.4 Formatting A New Database DB_format_db() is used for formatting a new database with given id , size and record size.

short DB_format_db ( unsigned short dbid, unsigned char blocknum, unsigned short recsize ); Parameters dbid

Id for the database, which will be the same as db_id in typ_db_description;

blocknum Total blocks of the database, It equals to typ_db_description.block_cnt + 1.

recsize Size of the user record to be stored in the database.

Return Values

Value Meaning 0 successful Non-zero failed, Maybe out of flash memory.

Remarks

Formatting routine should be called only when it’s necessary. Usually it’s called in the initialization routine of the application program when database failure occurred.

MC-998TM


Please also note that the dbid here should be treated as database type ID (like database version etc), it is not the same as the db_index in other database functions. Use db_index wherever it’s expected. The first formatted database’s information is in the structure filesys[0], its db_index is 0, the second formatted database’s information is in the structure filesys[1], its db_index is 1, and so on. Maximum database number in current version is 5, i.e. users should not create more than 5 database files.

3.5 Low Level Formatting erase_db_sys() is the low level formatting subroutine that is ONLY called when the whole database is a mess. All information including database parameters will be lost after this call.

void erase_db_sys ( void ) ; Parameters

None. Return Values

None.

3.6 Erasing A Database DB_erase_filesys() is used to erase all the records in the specified database. Any record stored will be lost. The structure of the database is remained. A new record added with DB_add_record will be the 1st record.

short DB_erase_filesys ( unsigned short db_index ) ;

Parameters db_index

MC-998TM


the database index of the database to be erased

Return Values

Value Meaning 0 successful Non-zero failed,. Check if db_index is out of range.

Remarks

Please note that db_index should be used here, it is not the same as the dbid. The first formatted database’s information is in the structure filesys[0], its db_index is 0, the second formatted database’s information is in the structure filesys[1], its db_index is 1, and so on. Maximum database number in current version is 5, i.e. users should not create more than 5 database files.

3.7 Check Database Capacity

DB_capacity() returns the capacity in records of specified database.

unsigned long DB_capacity ( unsigned short db_index ) ;

Parameters db_index

The database index to be checked.

Return Values

Numbers of records that could be stored in the database.

Remarks Please note that db_index should be used here, it is not the same as the dbid. The first formatted database’s information is in the structure filesys[0], its db_index is 0, the second formatted database’s information is in the structure filesys[1], its db_index is 1, and so on. Maximum database number in current version is 5, i.e. users should not create more than 5 database files.

MC-998TM


3.8 Count The Records Used In A Database

DB_count_records() returns the number of records used (including the deleted ones!) in the specified database.

unsigned long DB_count_records ( unsigned short db_index ) ;

Parameters db_index

The database index to be checked.

Return Values

Numbers of records used in the database.


3.9 Jump To A Record

DB_jump_to_record() returns the data pointer to a certain record in the specified database.

void * DB_jump_to_record ( unsigned short db_index, unsigned long rec_num, char * flag ) ;

Parameters

MC-998TM


db_index

The database index.

rec_num The number of the record to get.

flag Pointer to a byte to that the flags of the record will be written.

Return Values

A pointer (void *) to the data section of the record. It may be cast to any pointer type to make it easier to refer to. *flag will be… If it’s… 0 a normal record; 1 empty; 2 a deleted record.

Remarks


3.10 Adding A Record DB_add_record() adds a record to specified database.

unsigned long DB_add_record (

unsigned short db_index, void * pRec

) ; Parameters db_index

The database index.

MC-998TM


pRec

Pointer to the record to be written. If the size of (*pRec) is larger than the database data record size, data is trimmed to fit in the data record.

Return Values

Value Meaning 0 no space available for the new record

Non-zero succeeded. Then the returned value will be the record number + 1.

3.11 Deleting A Record DB_delete_record() deletes a record in the specified database. The record is marked as ‘deleted’, and it will be invisible to find-record-routines.

void DB_delete_record (

unsigned short db_index, unsigned long r_num

) ;

Parameters db_index

The database index.

r_num The record number of the record to be deleted

Return Values

None. Remarks

Nothing happens if db_index or r_num is out of range. Please note that db_index should be used here, it is not the same as the dbid. The first formatted database’s information is in the structure filesys[0], its db_index is 0, the second formatted database’s information is in the structure filesys[1], its db_index is 1, and so on. Maximum database number in current

MC-998TM


version is 5, i.e. users should not create more than 5 database files.

3.12 Finding A Record Macros DB_find_1st_match(), DB_find_next_match() and DB_find_prev_match() are used to find a record which meets the condition specified in a certain database. DB_find_1st_match() starts from the 1st record, DB_find_next_match() starts from the record following the record found last time., and DB_find_prev_match() searches back from the record previous to the record found last time. Deleted records are invisible to these 3 macros.

short DB_find_1st_match ( unsigned short db_index, short (* match_routine) (void * rec_buffer) ) ; short DB_find_next_match ( unsigned short db_index, short (* match_routine) (void * rec_buffer) ) ; short DB_find_prev_match ( unsigned short db_index, short (* match_routine) (void * rec_buffer) ) ; Parameters db_index

The database index.

match_routine A user defined match routine to check if the data record specified in rec_buffer is a wanted record. It's for advanced programming only! If it’s NULL then any undeleted records will be considered as matched record. This is enough for normal programming.

Return Values

Value Meaning

MC-998TM


0 no matched found Non-zero matched found. The found record number is

then stored in the pre-defined system global variable current_rec_num[db_index]. For more about the global variables used in the database, please refer to section 3.15


Example

/* This example prints the records with odd data as the 1st byte in database 1 */ #define M_VOLUME 1 /* match routine to check records with odd data as the 1st byte */ short my_mr(void * rb) { return (*((char*)rb)) % 2; } void main(void) { //………… if (DB_find_1st_match(M_VOLUME, my_mr)) { do { printf( ”odd found @ %ld\n”, current_rec_num[M_VOLUME]); } while (DB_find_next_match(M_VOLUME, my_mr)); } else puts(“not found”); } //end of main

MC-998TM


3.13 CRC Check of A Record DB_check_record() performs CRC check on a record in the specified database. The most common reason for CRC failure is power loss during a record writing session. Deleted or empty records are considered as ‘good’ records.

short DB_check_record ( unsigned short db_index, unsigned long r_num ) ; Parameters db_index

The database index.

r_num The record number of the record to be checked

Return Values

Value Meaning 0 CRC check failed

Non-zero CRC check succeeded. Remarks


3.14 CRC Calculator CRC_calculate() is a standard 11021 16-bit CRC calculator.

short CRC_calculate (

unsigned short Accum, unsigned short DataIn

) ;

MC-998TM


Parameters Accum

CRC before the 8-bit data is fed;

DataIn 8-bit data fed in to perform CRC calculation.

Return Values

CRC after the calculation.

3.15 Global Variables Used There are several global variables defined in database module. typ_db_sys_param dsp; typ_db_description filesys [MAX_FS_NUMBER]; short file_sys_cnt; unsigned long current_rec_num [MAX_FS_NUMBER];

Descriptions: dsp

Stores the parameters of current flash database,. c.f. get_db_sys_param().

file_sys_cnt Valid databases found in current flash database. c.f. DB_check_db().

filesys Array of database descriptions. C.f. DB_check_db().

current_rec_num Data buffer used in find-record routines. C.f. DB_find_1st_match().

MC-998TM


Chapter 4 Memory Card Accessing Drivers

MC-998TM


Memory Card Accessing Drivers 4

4.1 Overview of Memory Card Accessing Drivers

With the API functions given in Section 2.7, users can control every pin of the memory card. Theoretically, users can read or write almost all kinds of memory card. To help users write their application program quickly, MC-998 API library provides some drivers routines for frequently used memory cards, like AT24C01A etc. These drivers are listed and explained in this chapter. This chapter is newly added into this document in version 2.0.

4.2 Check Type of Memory Card

Check whether the memory card inserted in given socket is the desired type. short MEM_card_ATR_check ( unsigned char Card_Num, unsigned long ATR_word,

unsigned long ATR_mask ) ; Parameters Card_Num

Card socket number to perform type check. Value Meaning

0 checks socket #1 (i.e. SAM card). 1 checks socket #2 (i.e. ISO standard

size card socket).

ATR_word The given ATR word for the given type of memory card. Some frequently used ATR words have been defined in the header file:

ATR_SLE4428 ATR_SLE4442 ATR_AT88SC102_1 ATR_AT88SC1608

MC-998TM


ATR_mask The given ATR mask word for the given type of memory card. Some frequently used masks have been defined in the header file:

ATR_MASK_SLE4428 0 ATR_MASK_SLE4442 0 ATR_MASK_AT88SC1608 0 ATR_MASK_AT88SC102 0x0000FFFF

Return Values

Value Meaning 1 Yes

0 No Remarks

Some memory cards (such as 24C01) do not comply with ISO-7816 memory card ATR standard, so there are no ATR_word and ATR_mask for these cards in the header file, just call this function with ATR_word=0, ATR_mask=0. This function cannot check the type of these cards, it only turns on the power of these cards. User should ignore the return value for these cards after calling this function and read/write directly with those functions listed as following. Please note that the Card_Num is 0 for socket #1 (i.e. SAM card).and 1 for socket #2 (i.e. ISO standard size card socket).

4.3 AT24C01A/02 Functions

4.3.1 Read_AT24C01A( )

Read bytes from 24C01A or AT24C02. short Read_AT24C01A ( unsigned short Address, unsigned short NOB, char * Data ) ; Parameters Address

The start byte address of the read operation. For AT24C01A, the value should be in

MC-998TM


the range of 0 to 0x7F. For AT24C02, the value should be in the range of 0 to 0xFF.

NOB Number of bytes to read.

Data The pointer to the buffer holding the data read back. This buffer is allocated by the caller with the size of NOB bytes. The data is put into this buffer byte by byte.

Return Values

Value Meaning 0 successful

Non-zero error code returned, see error list. Remarks

Before calling this function the caller must guarantee the validity of the parameters, that is Address and NOB must be in the valid range, the size of the Data buffer is big enough to hold the data read back. This function makes no validity check of the parameters so invalid parameter may cause unpredictable results. The data read back with the invalid parameter is meaningless.

See Also

Write_AT24C01A_Byte() Write_AT24C01A_Page()

4.3.2 Write_AT24C01A( )

Write one byte to AT24C01A/02.

short Write_AT24C01A_Byte( unsigned short Address, char Data

) ; Parameters Address

The byte address of the write operation. For AT24C01A, the value of Address must be in the range of 0 to 0x7F. For AT24C02, the value of Address must be in the range of 0 to 0xFF.

MC-998TM


Char Data

The one-byte data to be written to the card.

Return Values


Non-zero error code returned, see error list.

Remarks This function writes only one byte to AT24C01A. The address must be in the range of 0 to 0x7F for AT24C01A or 0 to 0xFF for AT24C02, otherwise the data byte will be written to unpredicted address of the card.

See Also

Write_AT24C01A_Page() 4.3.3 Write_AT24C01A_Page( )

Write bytes to AT24C01A card.

short Write_AT24C01A_Page ( unsigned short Address, unsigned short NOB, char * Data ) ;

Parameters Address

The start byte address of the write operation. For AT24C01A, the Address must be in the range of 0 to 0x7F. For AT24C02, the Address must be in the range of 0 to 0xFF.

NOB The number of bytes to be written to the card. The value must be in the range of 1 to 8.

Data

The pointer to the buffer holding the data byte to be written to the card.

MC-998TM


Return Values



Remarks

This function writes multiple bytes to AT24C01A/02. The Address must be in the range of 0 to 0x7F for AT24C01A and 0 to 0xFF for AT24C02, and Address + NOB must not exceed the boundary of the card, otherwise unpredicted bytes will be written to the card. The page size of AT24C01A/02 is 8 bytes, and partial writes are allowed. NOB must not exceed 8.

See Also

Write_AT24C01A_Byte()

4.4 AT24C04/08/16 functions

4.4.1 Read_AT24C16( )

Read bytes from AT24C04/08/16.

short Read_AT24C16 ( unsigned short Address, unsigned short NOB, char * Data

) ;

Parameters Address

The start byte address of the read operation. For AT24C04, the value must be in the range of 0 to 0x1FF. For AT24C08, the value must be in he range of 0 to 0x3FF. For AT24C16, the value must be in the range of 0 to 0x7FF.

NOB

Number of bytes to read.

Data

MC-998TM


The pointer to the buffer holding the data read back. This buffer is allocated by the caller with the size of NOB bytes. The data is put into this buffer byte by byte.

Return Values



Remarks

Before calling this function the caller must guarantee the validity of the parameters, that is Address and NOB must be in the valid range, the size of the Data buffer is big enough to hold the data read back. This function makes no validity check of the parameters so invalid parameter may cause unpredictable results. The data read back with the invalid parameter is meaningless.

See Also

Write_AT24C16_Byte() Write_AT24C16_Page()

4.4.2 Write_AT24C16_Byte( )

Write one byte to AT24C04/08/16.

short Write_AT24C16_Byte ( unsigned short Address, char Data ) ;

Parameters

Address

The start byte address of the read operation. For AT24C04, the value must be in the range of 0 to 0x1FF. For AT24C08, the value must be in the range of 0 to 0x3FF. For AT24C16, the value must be in the range of 0 to 0x7FF.

Data

The one-byte data to be written to the card. Return Values

MC-998TM




Remarks

This function writes only one byte to AT24C/04/08/16. The Address must be in the range of 0 to 0x1FF for AT24C04 or 0 to 0x3FF for AT24C08 or 0 to 0x7FF for AT24C16, otherwise the data byte will be written to unpredicted address of the card.

See Also

Write_AT24C16_Page()

4.4.3 Write_AT24C16_Page( )

Write bytes to AT24C04/08/16. card.

short Write_AT24C16_Page ( unsigned short Address, unsigned short NOB, char * Data ) ; Parameters Address

The start byte address of the read operation. For AT24C04, the value must be in the range of 0 to 0x1FF. For AT24C08, the value must be in the range of 0 to 0x3FF. For AT24C16, the value must be in the range of 0 to 0x7FF.

NOB

The number of bytes to be written to the card. The value must be in the range of 1 to 32.

Data


Return Values

MC-998TM




Remarks

This function writes multiple bytes to AT24C/04/08/16. The Address must be in the range of 0 to 0x1FF for AT24C04 or 0 to 0x3FF for AT24C08 or 0 to 0x7FF for AT24C16, otherwise the data byte will be written to unpredicted address of the card.

See Also

Write_AT24C16_Byte()

4.5 AT24C32/64 functions

4.5.1 Read_AT24C64( )

Read bytes from AT24C32/64.

short Read_AT24C64 ( unsigned short Address, unsigned short NOB, char * Data );

Parameters Address

The start byte address of the read operation. For AT24C32, the value must be in the range of 0 to 0xFFF. For AT24C64, the value must be in the range of 0 to 0x1FFF.

NOB

Number of bytes to read. Data

the pointer to the buffer holding the data read back. This buffer is allocated by the caller with the size of NOB bytes. The data is put into this buffer byte by byte.

Return Values

MC-998TM




Remarks Before calling this function the caller must guarantee the validity of the parameters, that is Address and NOB must be in the valid range, the size of the Data buffer is big enough to hold the data read back. This function makes no validity check of the parameters so invalid parameter may cause unpredictable results. The data read back with the invalid parameter is meaningless.

See Also



Write one byte to AT24C32/64.

short Write_AT24C64_Byte ( unsigned short Address, char Data ) ;

Parameters Address

The start byte address of the read operation. For AT24C32, the value must be in the range of 0 to 0xFFF. For AT24C64, the value must be in the range of 0 to 0x1FFF.

Data The one-byte data to be written to the card.

Return Values



Remarks

MC-998TM


This function writes only one byte to AT24C32/64. The Address must be in the range of 0 to 0xFFF for AT24C32 or 0 to 0x1FFF for AT24C64, otherwise the data byte will be written to unpredicted address of the card.

See Also

Write_AT24C64_Page()

4.5.3 Write_AT24C64_Page( )

Write bytes to AT24C32/64 card.

short Write_AT24C64_Page ( unsigned short Address, unsigned short NOB, char * Data ) ; Parameters Address

The start byte address of the write operation. For AT24C32, the Address must be in the range of 0 to 0xFFF. For AT24C64, the Address must be in the range of 0 to 0x1FFF.

NOB

The number of bytes to be written to the card. The value must be in the range of 1 to 32.

Data


Return Values



Remarks

This function writes multiple bytes to AT24C32/64. The Address must be in the range of 0 to 0xFFF for AT24C32 and 0 to 0x1FFF for AT24C64, and Address + NOB must not exceed the boundary of the card, otherwise unpredicted bytes will be

MC-998TM


written to the card. The page size of AT24C32/64 is 32 bytes, and partial page write is allowed. NOB must not exceed 32.

See Also


4.6 AT24C128/256 functions

4.6.1 Read_AT24C256( )

Read bytes from AT24C128/256.

short Read_AT24C256 ( unsigned short Address, unsigned short NOB, char * Data ) ;

Parameters

Address

The start byte address of the read operation. For AT24C128, the value must be in the range of 0 to 0x3FFF. For AT24C256, the value must be in the range of 0 to 0x7FFF.

NOB


Data The pointer to the buffer holding the data read back. This buffer is allocated by the caller with the size of NOB bytes. The data is put into this buffer byte by byte.

Return Values



Remarks

Before calling this function the caller must guarantee the validity of the parameters,

MC-998TM


that is Address and NOB must be in the valid range, the size of the Data buffer is big enough to hold the data read back. This function makes no validity check of the parameters so invalid parameter may cause unpredictable results. The data read back with the invalid parameter is meaningless.

See Also



Write one byte to AT24C128/256.

short Write_AT24C256_Byte ( unsigned short Address, char Data ) ; Parameters Address

The start byte address of the read operation. For AT24C128, the value must be in the range of 0 to 0x3FFF. For AT24C256, the value must be in he range of 0 to 0x7FFF.

Data

The one-byte data to be written to the card.

Return Values



Remarks

This function writes only one byte to AT24C128/256. The Address must be in the range of 0 to 0x3FFF for AT24C128 or 0 to 0x7FFF for AT24C256, otherwise the data byte will be written to unpredicted address of the card.

See Also

MC-998TM


Write_AT24C256_Page() 4.6.3 Write_AT24C256_Page( )

Write bytes to AT24C128/256 card.

short Write_AT24C256_Page ( unsigned short Address, unsigned short NOB, char * Data ) ;

Parameters Address

The start byte address of the write operation. For AT24C128, the Address must be in the range of 0 to 0x3FFF. For AT24C256, the Address must be in the range of 0 to 0x7FFF.

NOB

The number of bytes to be written to the card. NOB must be in the range of 1 to 32.

Data The pointer to the buffer holding the data byte to be written to the card.

Return Values



Remarks

This function writes multiple bytes to AT24C128/256. The Address must be in the range of 0 to 3FFFH for AT24C128 and 0 to 7FFFH for AT24C256, and Address + NOB must not exceed the boundary of the card, otherwise unpredicted bytes will be written to the card. The page size of AT24C128/256 is 32 bytes, and partial page write is allowed. NOB must not exceed 32.

See Also


MC-998TM


4.7 4442 functions 4.7.1 Read_4442_NO_PB( )

This function reads data bytes of 4442 card without protection bits.

short Read_4442_NO_PB ( unsigned short StartPos, unsigned short NOB, char * Bfr

) ;

Parameters

StartPos The start offset of the bytes to be read, range: 0 to 0xFF.

NOB

Number of bytes to be read, limited to 16 bytes maximum.

Bfr Pointer to the buffer holding the returned data bytes

Return Values



Remarks

PB denotes Protection Bit. When calling this function the caller must make sure that the parameter is valid: StartPos and NOB are in valid range, Bfr is allocated enough memory by the caller. This function makes no check of the validity of the parameters. Invalid parameters passed to this function may cause unpredictable results.

See Also

Read_4442_With_PB()

MC-998TM


4.7.2 Read_4442_PB( )

Read all the protection bits of 4442.

short Read_4442_PB ( char * PB_Bfr ) ;

Parameters PB_Bfr

The pointer pointing to the 32-byte buffer holding the read back 32 protection-bit bytes associated with the first 32 bytes of 4442.

Return Values



Remarks

This function reads back the 32 protection bits and put them into 32 bytes, one bit in one byte. The 1 byte indicates the corresponding protection bit is written, and the data byte is protected; 0 byte indicates the corresponding protection bit is not written, and the data byte is not protected. Before calling this function, the caller must make sure the parameter is valid. This function make no validity check of the parameter values, so invalid parameter may cause unpredictable results.

See Also

Write_4442_PB()

4.7.3 Write_4442( )

Write 1 byte data to 4442. If required write protection bit.

short Write_4442 ( unsigned short StartPos, char DestByte, char PBSetFlag ) ;

MC-998TM


Parameters StartPos

The byte address to write, ranging 0 to 255

DestByte The data to be written

PBSetFlag The protection bit writing flag, Value Meaning 1 write protection bit 0 do not write protection bit

Return Values



Remarks

Write 1 byte of data to 4442 with the given address. If the PBSetFlag is 1 then write the associated protection bit. If the address is greater than 31 then the PBSetFlag is omitted.

See Also

Write_4442_PB()

4.7.4 Verify_4442_PSC( )

Verify the 3-byte PSC of 4442 short Verify_4442_PSC (

char PSC1, char PSC2, char PSC3

) ; Parameters PSC1, PSC2, PSC3

MC-998TM


The 3 parameter PSC1, PSC2 and PSC3 are the 3-byte PSC to be verified.

Return Values



Remarks

PSC denotes to Programmable Security Code according to the 4442 data sheet. Before any write operation the 3-byte PSC must be verified. NOTE: 3 continual failure of PSC verification will cause the card deadlock.

See Also

Read_4442_SM()

4.7.5 Read_4442_SM( )

Read back the 4-byte Security Memory (SM) of 4442.

short Read_4442_SM ( char * SM_Bfr

) ;

Parameters SM_Bfr

The pointer pointing to the buffer holding the read back 4 bytes SM.

Return Values



Remarks

SM denotes Security Memory. There is a 4-byte SM in 4442, namely Error Counter, PSC1, PSC2, PSC4. This function is to read back this 4-byte SM. The 1st byte is Error Counter, 2nd is PSC1, 3rd is PSC2 and 4th PSC3. Before calling this

MC-998TM


function the caller must make sure the parameters are valid, that is SM_Bfr must be allocated enough size of memory. This function makes no validity check of the parameters so invalid parameter may cause unpredictable results.

See Also

Verify_4442_PSC()

4.7.6 Write_4442_SM( ) Write one byte of data to 4442 SM with the given address.

short Write_4442_SM ( unsigned short SMAddress, char SMByte ) ;

Parameters SMAddress

The address of the data byte to be written, Value Meaning 0 writes Error Counter, 1 writes PSC1, 2 writes PSC2, 3 writes PSC3.

SMByte

The data byte to be written.

Return Values



Remarks

This function writes one byte to 4442 SM. SMAddress ranges from 0 to 3, other value is meaningless and will cause the function do nothing but return immediately.

See Also

MC-998TM


Read_4442_SM()

4.8 4428 functions 4.8.1 Read_4428_With_PB( )

Read data bytes of 4428 and their associated protection bits.

short Read_4428_With_PB( unsigned short StartPos, unsigned short NOB, char * Bfr, char * PB_Bfr ) ;

Parameters

StartPos

The start offset of the bytes to be read, range: 0 to 0x3FF.

NOB Number of bytes to be read, limited to 16 bytes maximum.

Bfr

Pointer to the buffer holding the returned data bytes

PB_Bfr Pointer to the buffer holding the returned protection bits. In this buffer, one byte is corresponding to one protection bit with the same order. A 0 byte denotes the protection bit is 0 which means the data byte is write protected; A 1 byte denotes the data byte is not protected.

Return Values



Remarks

PB denotes Protection Bit. When calling this function the caller must make sure that the parameter is valid: StartPos and NOB are in valid range, Bfr and PB_Bfr

MC-998TM


is allocated enough memory by the caller. This function makes no check of the validity of the parameters. Invalid parameters passed to this function may cause unpredictable results.

See Also

Read_4428_NO_PB()

4.8.2 Read_4428_NO_PB

Read data bytes of 4428 card.

short Read_4428_NO_PB ( unsigned short StartPos, unsigned short NOB, char * Bfr ) ;

Parameters StartPos

The start offset of the bytes to be read, range: 0 to 0x3FF

NOB Number of bytes to be read, limited to 16 bytes maximum.

Bfr

Pointer to the buffer holding the returned data bytes

Return Values



Remarks

PB denotes Protection Bit. When calling this function the caller must make sure that the parameter is valid: StartPos and NOB are in valid range, Bfr is allocated enough memory by the caller. This function makes no check of the validity of the parameters. Invalid parameters passed to this function may cause unpredictable results.

MC-998TM


See Also

Read_4428_With_PB()

4.8.3 Write_4428( ) Write one byte of data and associated protection bit (if required) into 4428.

short Write_4428 ( unsigned short StartPos, char DestByte, char PBSetFlag ) ;

Parameters StartPos

The offset of the byte to be written, range: 0 to 0x3FF.

DestBytethe Value of the byte to be written

PBSetFlag

The protection bit writing flag, Value Meaning 1 write associated protection bit 0 do not write protection bit

Return Values



Remarks

Before calling this function the caller must make sure that the parameters are valid, that is StartPos and NOB are in valid range and Bfr is allocated enough size of memory. This function makes no validity check of the parameter, so invalid parameters may cause unpredictable results.

MC-998TM


4.8.4 Verify_4428_PSC( ) Verify the 2-byte PSC of 4428 short Verify_4428_PSC ( char PSC1, char PSC2 ) ;

Parameters PSC1, PSC2

2 PSC bytes

Return Values



Remarks

According to 4428 data sheet, PSC denotes Programmable Security Code, which is also called password, PIN etc. Before any write operation to the card, the 2-byte PSC must be verified. NOTE: After 8 continual failure of PSC Verification the card becomes deadlock.

See Also

Read_4428_SM()

4.8.5 Read_4428_SM( )

Read the security memory (SM) area of 4428 short Read_4428_SM ( char * SM_Bfr, char * SM_PB_Bfr ) ;

Parameters

MC-998TM


SM_Bfr Pointer to the buffer holding the return 3-byte security memory

SM_PB_Bfr

Pointer to the buffer holding the return 3-byte protection bits of the security memory. Every byte in this buffer corresponds to one protection bit with the same order. A 0 byte denoted the protection bit is written and the associated SM byte is protected, A 1 byte means the protection bit is not written and the SM byte is not protected.

Return Values



Remarks

SM denotes Security Memory. The last 3 bytes in 4428, namely Error Counter, PSC1, PSC2, are called SM. This function is to read back these 3 bytes. The 1st byte read back is Error Counter, then PSC1, then PSC2. Before calling this function the caller must make sure the parameter is valid, that is SM_Bfr and SM_PB_Bfr is allocated enough size of memory. This function makes not validity check of the parameters thus invalid parameter may cause unpredictable results.

See Also

Verify_4428_PSC()

4.9 AT88SC101/102 functions 4.9.1 Read_102_Bit( )

Read data bits of AT88SC102.

short Read_102_Bit (

unsigned short StartBitAddress, unsigned short NOBit, char * Data

);

Parameters

MC-998TM


StartBitAddress Start bit address to be read. The first physical bit in AT88SC102 is addressed 0.

NOBit

Number of bits to be read, limited to 256 bits maximum.

Data The pointer pointing to the buffer holding the data read. This buffer is allocated by the caller. The data bits read is packed bit by bit into bytes, the size of the buffer is (NOB div 8) + 1 bytes.

Return Values



Remarks

Before calling this function the caller must guarantee the validity of the parameters, that is StartBitAddress and NOBit must be in the valid range, Data is allocated enough size of memory. This function assumes the parameters are valid so invalid parameter may cause unpredictable results.

See Also

Write_102_Bit()

4.9.2 Write_102_Bit( )

Write data bits into AT88SC 102 card.

short Write_102_Bit( unsigned short StartBitAddress, unsigned short NOBit, char * Data

) ;

Parameters StartBitAddress

Start bit address. The 1st physical bit in AT88SC102 is addressed 0.

MC-998TM


NOBit The number of bits to be written, limited to 256 bits maximum.

Data The pointer pointing to the buffer holding the data to be written. This buffer is set up by the caller before calling this function.

Return Values



Remarks

Before calling this function the caller must guarantee the validity the parameter, StartBitAddress and NOBit must be in the valid range. This function makes no validity check of the parameters. Invalid parameter may cause unpredictable results.

See Also

Read_102_Bit()

4.9.3 Read_102_Byte( )

Read 1 data byte of AT88SC102.

short Read_102_Byte(

unsigned short ByteAddress, char * Data

) ;

Parameters ByteAddress

The address of the byte to be read.

Data The pointer pointing to the buffer holding the data read back.

Return Values

Value Meaning

MC-998TM


0 successful Non-zero error code returned, see error list.

Remarks

Before calling this function the caller must guarantee the validity of the parameters, the ByteAddress must be in the valid range, Data is defined a pointer to the valid buffer. This function make no validity check of the parameters so invalid parameter may cause unpredictable results. The data read back with invalid parameter is meaningless.

See Also

Write_102_Byte()

4.9.4 Write_102_Byte( ) Write 1 byte data to AT88SC102. short Write_102_Byte (

unsigned short ByteAddress, char Data

) ;


The byte address to be written.

Data The data byte to be written to the card.

Return Values



Remarks

Before calling this function the caller must guarantee the validity of the parameters, ByteAddress must be in the valid range. This function makes no validity check of the parameters so invalid parameter may cause unpredictable results.

MC-998TM


See Also

Read_102_Byte()

4.9.5 Read_102_Word( ) Read 1 word of data from AT88SC102 card. short Read_102_Word (

unsigned short WordAddress, char * Data

) ;

Parameters WordAddress

The word address to be read. The word address is different from the byte address. The start byte address of the card is 0, the start word address is also 0. The byte with a byte address 1 does not have a word address, the byte with a byte address 2 has the word address 1, the byte with a byte address 2n has the word address n, the byte with a byte address 2n+1 does not have a word address.

Data

The pointer of the buffer holding the data read back.

Return Values



Remarks

Before calling this function the caller must guarantee the validity of the parameters: WordAddress is in the valid range, Data points to the valid word buffer. This function make no validity check of the parameters so invalid parameter may cause unpredictable results.

See Also

Write_102_Word()

MC-998TM


4.9.6 Write_102_Word( )

Write 1 word of data to AT88SC102 card. short Write_102_Word ( unsigned short WordAddress, char * Data ) ;


The word address to be written. The word address is different from the byte address. The start byte address of the card is 0, the start word address is also 0. The byte with a byte address 1 does not have a word address, the byte with a byte address 2 has the word address 1, the byte with a byte address 2n has the word address n, the byte with a byte address 2n+1 does not have a word address.

Data The pointer of the buffer holding the data to be written.

Return Values



Remarks

Before calling this function the caller must guarantee the validity of the parameters: WordAddress is in the valid range, Data points to the valid word buffer. This function make no validity check of the parameters so invalid parameter may cause unpredictable results.

See Also

Read_102_Word()

4.9.7 Erase_102_Word( )

Erase one word of AT88SC102 card

MC-998TM


short Erase_102_Word ( unsigned short WordAddress

) ;


The word address to be written. The word address is different from the byte address. The start byte address of the card is 0, the start word address is also 0. The byte with a byte address 1 does not have a word address, the byte with a byte address 2 has the word address 1, the byte with a byte address 2n has the word address n, the byte with a byte address 2n+1 does not have a word address.

Return Values



Remarks

Before calling this function the caller must guarantee the validity of the parameters: WordAddress is in the valid range. This function make no validity check of the parameters so invalid parameter may cause unpredictable results.

See Also

Read_102_Word() Write_102_Word() Erase_102_Word_Array()

4.9.8 Verify_102_SC( )

Verify the Security Code (SC) of AT88SC102 card.

short Verify_102_SC ( char * SCArray ) ;

Parameters SCArray

the pointer of the 2-byte SC buffer to be verified.

MC-998TM


Return Values



Remarks

SC denotes Security Code (Defined in 102 data sheet). Before any operation to the card this 2-byte Security Code must be verified. NOTE: 4 continual failure of the SC verification will cause the card deadlock.

4.9.9 Erase_102_AZ1( )

Erase the AZ1 data zone of AT88SC102 card.

short Erase_102_AZ1 ( char *EZArray

) ;

Parameters EZArray

The pointer to the buffer holding the 6-byte caller supplied erase key EZ1

Return Values



Remarks

Refer to AT88SC102 data sheet for detailed explanation of the AT88SC102 AZ1 data zone and this erase function.

See Also

Erase_102_AZ2()

MC-998TM


4.9.10 Erase_102_AZ2( )

Erase the AZ2 data zone of AT88SC102 card.

short Erase_102_AZ2 ( char * EZArray ) ;

Parameters EZArray

The pointer to the buffer holding the 4-byte caller supplied erase key EZ2

Return Values



Remarks

Refer to AT88SC102 data sheet for detailed explanation of the AT88SC102 AZ2 data zone and this erase function.

See Also

Erase_102_AZ1() 4.9.11 Fuse_High_102( )

Set the AT88SC102 FUS pin to 5V to blow the FUSE2 fuse of AT88SC102. short Fuse_High_102( void ) ;

Parameters

None. Return Values

Value Meaning

MC-998TM



Remarks

Set FUS pin to 5V will blow the FUSE2 fuse in AT88SC102 card. After operation of the card the application must call Fuse_Low_102 to set the FUS pin to 0V in order to operate another card. See AT88SC102 data sheet for detailed explanation of the fuses and their functions.

See Also

Fuse_Low_102()

4.9.12 Fuse_Low_102( )

Set the FUS pin of AT88SC102 to 0V after blow the FUSE2 fuse. short Fuse_Low_102 ( void ) ;

Parameters

None.

Return Values



Remarks

Set FUS pin to 5V will blow the FUSE2 fuse in AT88SC102 card. After operation of the card the application must call Fuse_Low_102() to set the FUS pin to 0V in order to operate another card. See AT88SC102 data sheet for detailed explanation of the fuses and their functions.

See Also

Fuse_High_102()

MC-998TM


4.9.13 Erase_102_AZ2_EC( )

For issuers use only, un-documented in this version, please contact the MC-998 suppliers for details.

4.9.14 Blow_Manufacturer_Fuse_102( )


4.9.15 Blow_EC2EN_Fuse_102( )


4.9.16 Blow_Issuer_Fuse_102( )


4.10 AT88SC1604 functions 4.10.1 Read_1604_Bit( )

Read data bits of AT88SC1604.

short Read_1604_Bit (

unsigned short StartBitAddress, unsigned short NOBit, char * Data

);

Parameters StartBitAddress

Start bit address to be read. The first physical bit in AT88SC1604 is addressed 0.

NOBit Number of bits to be read, limited to 16384 bits maximum.

MC-998TM


Data

The pointer pointing to the buffer holding the data read. This buffer is allocated by the caller. The data bits read is packed bit by bit into bytes, the size of the buffer is (NOB div 8) + 1 bytes.

Return Values



Remarks

Before calling this function the caller must guarantee the validity of the parameters, that is StartBitAddress and NOBit must be in the valid range, Data is allocated enough size of memory. This function assumes the parameters are valid so invalid parameter may cause unpredictable results.

See Also

Write_1604_Byte() Write_1604_Array()

4.10.2 Write_1604_Byte( )

Write 1 byte of data into AT88SC1604 card.

short Write_1604_Byte( unsigned short StartByteAddress, char * Data

) ;

Parameters StartByteAddress

Start byte address. The 1st physical byte in AT88SC1604 is addressed 0.

Data The pointer pointing to the buffer holding the data to be written. The caller sets up this buffer before calling this function.

Return Values

MC-998TM


Value Meaning


Remarks

Before calling this function the caller must guarantee the validity the parameter, StartByteAddress must be in the valid range. This function makes no validity check of the parameters. Invalid parameter may cause unpredictable results. Please note that the write operation only writes ‘0’ on ‘1’, so make sure that the destination has already been erased (to ‘1’s) first.

See Also

Read_1604_Bit() Erase_1604_Byte()

4.10.3 Write_1604_Array( )

Read array of data byte to AT88SC1604.

short Write_1604_Array(

unsigned short ByteAddress, unsigned short ByteCount, char * Data

) ;


The address of the byte to be written.

ByteCount The amount of the bytes to be written.

Data The pointer pointing to the buffer holding the data to write.

Return Values


MC-998TM



Remarks

Before calling this function the caller must guarantee the validity of the parameters, the ByteAddress and ByteCount must be in the valid range, Data is defined a pointer to the valid buffer. This function make no validity check of the parameters so invalid parameter may cause unpredictable results. Please note that the write operation only writes ‘0’ on ‘1’, so make sure that the destination has already been erased (to ‘1’s) first.

See Also

Write_1604_Byte() Erase_1604_Array()

4.10.4 Erase_1604_Byte( ) Erase 1 byte of AT88SC1604, setting the content to all 1s. short Erase_1604_Byte (

unsigned short ByteAddress, ) ;


The byte address to be erased. Return Values



Remarks

Before calling this function the caller must guarantee the validity of the parameters, ByteAddress must be in the valid range. This function makes no validity check of the parameters so invalid parameter may cause unpredictable results.

See Also

MC-998TM


Erase_1604_Array()

4.10.5 Erase_1604_Array( ) Erase designated EEPROM area in AT88SC1604 card. short Erase_1604_Array (

unsigned short ByteAddress, unsigned short ByteCount

) ;


The byte address of the start of the EEPROM area to be erased.

ByteCount The length of the EEPROM area to be erased.

Return Values



Remarks

Before calling this function the caller must guarantee the validity of the parameters: ByteAddress and ByteCount is in the valid range. This function make no validity check of the parameters so invalid parameter may cause unpredictable results.

See Also

Write_1604_Array()

4.10.6 Verify_1604_SC( ) SC (security code) verification of the entire AT88SC1604 card. short Verify_1604_SC ( unsigned char * SCArray ) ;

MC-998TM


Parameters SCArray

the pointer of the 2-byte SC buffer to be verified. Return Values



Remarks

SC denotes Security Code (Defined in 1604 data sheet). Before any operation to the card this 2-byte Security Code must be verified. 8 continual failure of the SC verification will cause the card deadlock.

4.10.7 Verify_1604_SCx

Verify the SCx (security code for application zone x) for AT88SC1604 card. Verify_1604_SC1() works for both evenly segmented type and unevenly segmented type, but the other 3 only work for evenly segmented type. short Verify_1604_SC1 ( unsigned char * SCArray ) ; short Verify_1604_SC2 ( unsigned char * SCArray ) ; short Verify_1604_SC3 ( unsigned char * SCArray ) ; short Verify_1604_SC4 ( unsigned char * SCArray ) ;

Parameters SCArray

the pointer of the 2-byte SCx buffer to be verified. Return Values



Remarks

SCx denotes Security Code for application zone x (Defined in 1604 data sheet).

MC-998TM


8 continual failure of the SCx verification will lock the corresponding SCx forever.

4.10.8 Verify_1604U_SCx

Verify the SCx (security code for application zone x) for application zone 2,3 & 4 of unevenly segmented AT88SC1604 card. short Verify_1604U_SC2 ( unsigned char * SCArray ) ; short Verify_1604U_SC3 ( unsigned char * SCArray ) ; short Verify_1604U_SC4 ( unsigned char * SCArray ) ;

Parameters SCArray

the pointer of the 2-byte SCx buffer to be verified. Return Values

N/A

Remarks

SCx denotes Security Code for application zone x (Defined in 1604 data sheet). There is no attempt counter for application zone 2,3&4 of unevenly segmented 1604 cards.

4.10.9 Verify_1604_EZx

Verify the EZx (erasing password for application zone x) for AT88SC1604 card. Verify_1604_EZ1() works for both evenly segmented type and unevenly segmented type, but the other 3 only work for evenly segmented type. short Verify_1604_EZ1 ( unsigned char * EZArray ) ; short Verify_1604_EZ2 ( unsigned char * EZArray ) ; short Verify_1604_EZ3 ( unsigned char * EZArray ) ; short Verify_1604_EZ4 ( unsigned char * EZArray ) ;

Parameters EZArray

the pointer of the 2-byte EZx buffer to be verified. Return Values



MC-998TM


Remarks

EZx denotes erasing password for application zone x (Defined in 1604 data sheet). 8 continual failure of the EZx verification will lock the corresponding EZx forever.

4.10.10 Verify_1604U_EZx

Verify the EZx (erasing password for application zone x) for application zone 2,3 & 4 of unevenly segmented AT88SC1604 card. short Verify_1604U_EZ2 ( unsigned char * EZArray ) ; short Verify_1604U_EZ3 ( unsigned char * EZArray ) ; short Verify_1604U_EZ4 ( unsigned char * EZArray ) ;

Parameters EZArray

the pointer of the 2-byte EZx buffer to be verified. Return Values



Remarks

EZx denotes erasing password for application zone x (Defined in 1604 data sheet). 8 continual failure of the EZx verification will lock the corresponding EZx forever.

4.10.11 Fuse_High_1604( ) Set the AT88SC1604 FUS pin to 5V to enter security level 1 for cards with issuer fuse not blown. short Fuse_High_1604( void ) ;

Parameters

None.

MC-998TM


Return Values



Remarks

C.f. ATSC1604 manual for the usage of the FUS pin.

See Also

Fuse_Low_1604()

4.10.12 Fuse_Low_1604( )

Set the FUS pin of AT88SC102 to 0V to simulate security level 2 for cards with issuer fuse not blown. short Fuse_Low_1604 ( void ) ;

Parameters

None.

Return Values



Remarks

C.f. ATSC1604 manual for the usage of the FUS pin. See Also

Fuse_High_1604()

MC-998TM


4.10.13 Blow_Issuer_Fuse_1604( )

For issuers use only, un-documented in this version, please contact the MC2002 suppliers for details.

4.11 AT88SC1608 Functions

4.11.1 Select_1608_User_Zone( )

Set the User Zone Address for the following operation.

short Select_1608_User_Zone ( unsigned short ZoneAddr ) ;

Parameters ZoneAddr

The User Zone Address. In the range of 0 to 7.

Remarks

At power on, no access to the user zone is allowed until a Set User Zone Address command is issued. AT88SC1608 has 8 user zones, the zone address must be in the range of 0 to 7.

4.11.2 Read_1608_User_Zone( )

Read data bytes of AT88SC1608 User Zone.

short Read_1608_User_Zone ( unsigned short ByteAddr, unsigned short NOB, char * Data ) ;


The start byte address to be read.

MC-998TM


NOB The number of bytes to be read from AT88SC1608.

Data

The pointer to the buffer holding the data bytes read back.

Remarks

This function reads the data byte of AT88SC1608 card. Before this read function, the caller must issue Password Verification and/or Authentication commands to the card. Also before calling this function, the caller must make sure the parameter is valid. The char Data buffer is allocated by the caller and the buffer size must be bigger than NOB. This function make no validity check of the parameter values, so invalid parameter may cause unpredictable results.

See Also

Write_1608_User_Zone()

4.11.3 Write_1608_User_Zone( )

Write data bytes to AT88SC1608 card.

short Write_1608_User_Zone ( unsigned short ByteAddr, unsigned short NOB, char * Data ) ;

Parameters ByteAddr

The start byte address for the write operation.

NOB The number of byte to be written

Data

The pointer to the buffer holding the bytes to be written to the card

Remarks

This function writes data bytes to the card. Before apply this function, the caller must

MC-998TM


issue Password Verification and/or Authentication Commands to the card.

See Also

Read_1608_User_Zone()

4.11.4 Read_1608_Configuration( )

Read data bytes of AT88SC1608 Configuration Zone.

short Read_1608_Configuration ( unsigned short ByteAddr, unsigned short NOB, char * Data ) ;


The start byte address to be read.

NOB The number of bytes to be read from AT88SC1608.

Data

The pointer to the buffer holding the data bytes read back.

Remarks

This function reads the data bytes of AT88SC1608 Configuration Zone. Before this read function, the caller must issue Password Verification and/or Authentication commands to the card. Also before calling this function, the caller must make sure the parameter is valid. The char Data buffer is allocated by the caller and the buffer size must be bigger than NOB. This function makes no validity check of the parameter values, so invalid parameter may cause unpredictable results.

See Also

Write_1608_Configuration()

4.11.5 Write_1608_Configuration( )

MC-998TM


Write data bytes to AT88SC1608 Configuration Zone.

short Write_1608_Configuration ( unsigned short ByteAddr, unsigned short NOB, char * Data ) ;

Parameters ByteAddr

the start byte address for the write operation.

NOB The number of byte to be written

Data

The pointer to the buffer holding the bytes to be written to the card

Remarks

This function writes data bytes to AT88SC1608 Configuration Zone. Before apply this function, the caller must issue Password Verification and/or Authentication Commands to the card.

See Also

Read_1608_Configuration_Zone()

4.11.6 Read_1608_Fuses( )

Read the fuses of At88SC1608.

short Read_1608_Fuses ( char * Fuses ) ;

Parameters Fuses

The pointer to the byte holding the fuses values read back from the card. Bit 0 = FAB fuse

MC-998TM


Value Meaning 1 not blown 0 blown

Bit 1 = CMA fuse


Bit 2:= PER fuse


Remarks

This function reads back the fuses of AT88SC1608.

See Also

Write_1608_Fuses()

4.11.7 Write_1608_Fuses( )

Write the next fuse of AT88SC1608.

short Write_1608_Fuses ( void ) ; Parameters

None.

Remarks

The fuses are blown sequentially: CMA is blown if FAB is equal to “0”, and PER is blown if CMA is equal to “0”.

See Also

Read_1608_Fuses()

MC-998TM


4.11.8 Verify_1608_Password( )

Verify the read/write password of AT88SC1608 card.

short Verify_1608_Password ( unsigned short ReadWrite, unsigned short SetNumber, char * Password ) ;

Parameters ReadWrite

Value Meaning 1 Read password 0 Write password

SetNumber

Password set number, 0 to 7 for 8 password sets.

Password Pointer to the 3-byte password to be verified

Remarks

This function verifies a Read or Write password. A valid verification of the password erases the attempts counter. After this function the caller must read the attempts counter to see if the password verification if successful.

See Also

Read_1608_Configuration()

4.11.9 Init_1608_Authentication( )

Initialize the authentication process of AT88SC1608 card.

short Init_1608_Authentication ( char * Q0 ) ;

Parameters

MC-998TM


Q0

This is the pointer to the buffer holding the 8-byte host random number.

Remarks

This function sets up the authentication process of the AT88SC1608 card. The caller must generate a random number as the input of this function.

See Also

Verify_1608_Authentication()

4.11.10 Verify_1608_Authentication( )

Execute the 'Verify Authentication’ command of the AT88SC1608 card.

short Verify_1608_Authentication ( char * Q1 ) ;

Parameters Q1

This is the pointer to the buffer holding the 8-byte host challenge. This challenge is computed by the reader.

Remarks

After initializing authentication command, both the reader and the card computed their result of the challenge. The reader must issue this command to let the card authenticate the reader.

See Also

Initialize_1608_Authentication()

4.12 AT45D041 45D041 from Atmel is a huge capacity memory chip based on flash technology. It does not comply with ISO7816-3. Please read the datasheet of AT45D041 carefully before using this driver.

MC-998TM


4.12.1 Main Memory Page Read Card operation: main memory page reading.

int Read_Main_AT45D( int Page, int ByteAddress, int NOB, char *Data );

Parameters

Page Page address of the data to read.

ByteAddress Byte address of the data to read.

NOB Number of bytes to read.

Data Destination data buffer address.

Return Values N/A.

4.12.2 Buffer Read

Card operation: buffer reading. int Read_Buffer_AT45D( int Buffer, int ByteAddress, int NOB, char *Data );

Parameters

Buffer Buffer index of the buffer from which the data would be read.

ByteAddress Byte address of the data to read.

NOB

MC-998TM



Data Destination data buffer address.

Return Values N/A.

4.12.3 Main Memory Page To Buffer Transfer

Card operation: data transfer from main memory page to designated buffer. int Transfer_AT45D( int Page, int Buffer );

Parameters

Page Page address of the data to transfer from, in main memory.

Buffer Buffer index of the buffer to which the data would be transferred

Return Values N/A.

4.12.4 Main Memory Page To Buffer Compare

Card operation: data comparison of main memory page and designated buffer. int Compare_AT45D( int Page, int Buffer );

Parameters

Page Address of the data page to compare, in main memory.

Buffer Buffer index of the data buffer to compare.

Return Values N/A.

4.12.5 Buffer Write

Card operation: buffer writing.

MC-998TM


int Buffer_Write_AT45D( int Buffer, int ByteAddress, int NOB, char *Data );

Parameters

Buffer Buffer index of the buffer to which the data would be written.

ByteAddress Byte address of the data to write.

NOB Number of bytes to write.

Data Source data buffer address.

Return Values N/A.

4.12.6 Buffer To Main Memory Page Program With Built-in Erase

Card operation: main memory page programming with built-in erase, with data stored in designated buffer. int Program_Erase_AT45D( int Buffer, int Page );

Parameters

Buffer Buffer index of the data buffer that stores the data source.

Page Address of the data page that the data should be written, in main memory.

Return Values N/A.

4.12.7 Buffer To Main Memory Page Program Without Built-in Erase

Card operation: main memory page programming without built-in erase, with data stored in

MC-998TM


designated buffer. int Program_No_Erase_AT45D( int Buffer, int Page );

Parameters

Buffer Buffer index of the data buffer that stores the data source.

Page Address of the data page that the data should be written, in main memory.

Return Values N/A.

4.12.8 Main Memory Page Program Through Buffer

Card operation: main memory page programming through designated buffer.

MC-998TM


int Program_Main_AT45D( int Buffer, int Page, int ByteAddress, int NOB, char *Data );

Parameters

Buffer Buffer index of the buffer through which the data would be written.

Page Address of the data page into which the data should be written, in main memory.

ByteAddress Byte address of the data to write, in the main memory page .

NOB Number of bytes to write.

Data Source data buffer address.

Return Values N/A.

4.12.9 Auto Page Rewrite Through Buffer

Card operation: auto page rewriting through designated buffer. int Rewrite_AT45D( int Buffer, int Page );

Parameters

Buffer Buffer index of the data buffer through which the auto rewriting would perform.

Page Address of the data page to be auto rewritten.

Return Values N/A.

MC-998TM


4.12.10 Status Register Read Card operation: card status register reading. unsigned char Read_Status_AT45D( void );

Return Values

The value returned is the status register of the card.

Remarks: This function is quite useful, since the busy indicator and comparison result both reside in the status register. c.f. AT45D041 manual.

4.11.11 Card Reset

Card operation: card resetting.

void Reset_AT45D( void );

Remarks:

Because AT45D041 card is not ISO7816 compatible, the standard ISO7816-3 ATR sequence for asynchronous cards may lead the card into an unknown state. So, please invoke this subroutine right after the ICC_memcard_ATR, before any card accessing.

MC-998TM


Chapter 5 Console Drivers

MC-998TM


Console Drivers 5

5.1 Overview of Console Drivers This chapter is newly added into this document in version 3.0.

5.1.1 What Is It? A console is an interface through which the user may control the system and get to know what's going on inside. And the console IO driver is a basic user interface driver that enables the programmer to handle the user input/output in a more familiar way, the C way.

5.1.2 Why?

It is possible to program without that driver, however: we got Disp_xxx functions to display, and Key_xxx functions to get key input, and sys_msg() and that message loop for flow control. The problem is, it's not what we've been used to. The programmers would spend quite some time adjusting themselves to this style.

5.1.3 What Exactly Does It Do? With this driver, you could use several standard C input/output routines: printf(), getch(), puts(), which are quite familiar, and some useful tools for date/time/numeric input, and more, input dialogs for strings containing letters and Chinese characters. The console will turn the LCD off automatically for powersaving after being idle for a while. and, the driver would get you rid of that message loop that's bothering some programmers, that loop is now packed inside the getch() function, and it's transparent to programmer, yet still, the behavior of that loop remains controllable. That should be enough in most cases. The BIOS functions are still available if you'd like to fine-tune it, and, the source code should be available soon.

5.2 Console Output The display area of MC-998 is a 128x64 dotmatix LCD with only 2 gray levels. that limits the information to display. so before you use that LCD as a console, you have to decide,

5.2.1 Console: English or Chinese

MC-998TM


In this version of console driver, we use 3 types of system fonts in 2 screen modes: 5x7 ASCII English character for English console 7x9 ASCII English and 16x16 GB2312 Chinese character for Chinese console

You can tell that the information displayed in one screen in Chinese console is much less than in English mode. It is possible to switch console mode in the middle of the program, which will generate a screen called mixed console, where both 5x7 English and 7x9 english/16x16 Chinese could be displayed together in one screen. The size of the console screen is 21 character x 8 line in English mode and 8 character x 4 line in Chinese mode. so we have 2 different coordinate systems:

5.2.2 Coordinate Systems For the English screen, we use a 8 row by 21 column system to locate a position. the system font is 5x7, which is actually 6x8, which leads to 21x8 for a 128x64 LCD, with 2 pixel columns left on the right edge of the LCD. For the Chinese screen, we use a 8 row by 16 column system. the system font for non Chinese character is 7x9 which is actually 8x16, occupying 2 rows and 1 column; for Chinese character (16x16), it's 2 rows and 2 column. the reason why we use 8 rows is that it is easier to arrange the screen layout for mixed console and when scattering 3 lines of Chinese character evenly on to the LCD. Home position for all coordinate systems is (0,0), it's upper left corner.

5.2.3 Start It Up Before you can use any console driver functions, there is something you should do first:

a) make sure console.h is in your include path b) make sure libconso.a is in your library path c) make sure libconso.a is accessible from your .ld file:

GROUP(crt0.o -lgcc -lg -lm -lstdcx -lm998 -lmcard -lconso) or, for .ld with customized crt0.o: GROUP(-lgcc -lg -lm -lstdcx -lm998 -lmcard -lconso)

d) include that console.h: #include <console.h> Please note that the console.h has included stdio.h, stdlib.h, string.h and api.h so you don't have to include these headers any more.

e) initialize console with language setting in the initialization portion of your code:

short main(void) { ... init_console( CONSOLE_CHINESE ) ;

MC-998TM


} The screen is cleared after that call, cursor is set home - (0,0).

5.2.4 Print Something After initialization, the console is ready. Console output is quite easy: puts() for string output and printf() for formatted output. they're almost the same as the ones in stdio.h, with some tiny differences. both of them have been written to handle mixed Chinese/ASCII strings, and, they are the only ways to display mixed Chinese/ASCII strings on the console, unless you want to handle them yourselves.

5.2.4.1 puts( ) puts() is used to print a string on the LCD. The font is selected automatically according to current console language setting. The main difference between standard puts() and MC-998 puts() is that we don't add a newline (\n) at the end (because we don't have one).

5.2.4.2 printf() printf() is quite the same as the standard one, so nothing more to say.

5.2.5 No CR/LF There is NO control character in this version of console driver, so please don't print them, no CR/LF(\n,\r), no backspace, no table(\t), etc. Here are the displayable characters :

English mode : 0x20~0x7F Chinese mode : ASCII - 0x20~0xFF (not MS code page 437!)

Chinese - section 0x00~0x09, section 0x10~0x57 Please note that character 0x00~0x1F in Chinese ASCII mode are actually special symbols, please avoid using them.

5.2.6 Where To Print Before writing to screen, you could set the cursor to where you want to display, by calling move_cursor(). The parameters for move_cursor() use current coordinate system, so move_cusor(3,3) will move the cursor to pixel (24,24) in Chinese mode, pixel (18,24) in English mode. In mixed mode, it depends on the current language setting.

MC-998TM


Since we don't have any CR/LF, if you write outside the LCD, they just disappear; if a string is too long for a line, it's clipped.

5.2.7 Wipe Them out of My Screen clear_console() will clear the whole screen, and set the cursor home.

5.2.8 Changing Faces The characters displayed could be inverted (white character on black background). There are 2 ways to do that, though basically they are the same: a) direct assignment:

inversed_disp = 1; b) via a macro:

set_inversed_disp(); All the characters displayed after that would be inverted. set_normal_disp() would set the disp back to normal, while setting inversed_disp to 0 would do the same.

5.3 Console Input The input of console is much more complicated than it seems. In fact, the system stays here most of the time. When program flow is directed here, the console would enter power-saving mode (just how much it could save depends on the console setting, c.f. advanced topics). it wakes up on certain events but only return on a few of them.

5.3.1 What Can We Get From The Console

5.3.1.1 Keys There are 15 keys for console input to capture, only key pressing is accepted:

Key pressed Return Value keys 0~9 as value 0~9, or KEY_0 ~ KEY_9. key C KEY_CLR key => KEY_ENTER key F1,F2,F3 KEY_F1, KEY_F2, KEY_F3

5.3.1.2 Jog dial

2 directions and a pressing is accepted:

MC-998TM


Action Return Value roll up JOG_UP roll down JOG_DOWN press KEY_ENTER

5.3.1.3 Card Activities

2 activities could be recognized:

Action Return Values insert card CARD_INSERT withdraw card CARD_GONE

5.3.1.4 Invisible Power Key?

Yes, the power key. It's invisible to console driver users, pressing it while the LCD is on will turn the LCD off on its releasing, if the key is held down for less than 2 seconds. backlight would be turned off too. pressing it while the LCD is off will turn the LCD on immediately. press and hold it down for over 2 seconds, the backlight would be on. so, in a dark environment, just press and hold it down for over 2 seconds, you could always turn the LCD on along with backlight.

5.3.2 How To Get Them 2 similar macros are used to get console input.

5.3.2.1 getch() getch() is used to get keys & jog dial input.

5.3.2.2 getchx() getchx() gets card activities besides keys & jog dial.

5.3.3 Some Handy Macros Since the return value of getch() & getchx() is kind of tricky, it's useful to have following macros:

is_card_activity(value) 1 if it's card activity is_key_valid(value) 1 if it's a valid key or jog dial action

MC-998TM


is_jogdialer(value) 1 if it's a jog dial action

5.4 Some Input Tools Beside those basic tools for console input/output, we have something more complicated.

5.4.1 Numeric Input One of the most commonly used input of MC-998 is numeric input, i.e., string input that accepts numeric digits only. we got 3 types of numeric input tools. These tools accept input and echo at given location on LCD.

5.4.1.1 Date Date input tools returns a string as "YYYY/MM/DD" or "MM/DD/YYYY". no range check has been performed, so you have to do it yourselves. Input key 0 ~ 9 will append to the tail of the input string if the string is not overlengthed; key C will clear the last digit input, and clearing all the digit will cause the tool to return GETS_ESC; Key => will confirm the input and return GETS_CONFIRM. The char '/' will be skipped when editing the string, but will be included in the string returned. a little '_' will be displayed to indicate current input position. date input tool is gets_date(). e.g. for a Chinese date format input:

Key Input Echo 2,0,0 200_/ / 2 2002/_ / 0 2002/0_/ C 2002/_ / 1 2 1 8 2002/12/18 => "2002/12/18" returned.

5.4.1.2 Time

Time input tools returns a string as "HH:MM". no range check has been performed, so you have to do it yourselves. Input key 0 ~ 9 will append to the tail of the input string if the string is not overlengthed; key C will clear the last digit input, and clearing all the digit will cause the tool to return GETS_ESC; key => will confirm the input and return GETS_CONFIRM. The char ':' will be skipped when editing the string, but will be included in the string returned. a little '_' will be displayed to indicate current input position. time input tool is gets_time().

MC-998TM


e.g. Key Input Echo 0 0_: 2 02:_ 0 02:0_ C 02:_ 1 5 02:15 => "02:15". returned.

5.4.1.3 Show Me The Money

Currency input is a kind of fixed point numeric input. this tool accepts numeric digit and echoes with a given fixed point format. input key 0 ~ 9 will append as the last digit of the fraction part, and the rest digits just shift left, if the length of the integer part does not exceed the given length; key C will clear the last digit input, and the rest digits shift right; key => will confirm the input and return the value as a longint. the caller must know how to interpret this fixed point number. there is no current position indication. there is no way to input the radix point, but you don't have to. fixed point numeric input tool is get_numeric(). e.g., for a currency input with integer part of 3 digits and fraction part of 2 digits:

Key Input Echo 0.00 2 0.02 0 0.20 5 2.05 C 0.20 7 8 8 207.88 => 20788L returned.

5.4.2 More Than Numeric

For more complicated occasions that require alphanumeric or even Chinese character input, dialog based input tools are used. These tools got their individual screens. No pop up windows are implemented because of limited screen size. However, the screen prior to the call would be saved, and will be restored upon tool exit. A string could be a none empty one before it's passed to the tool, so that it could be edited. The string would be completed cleared if the user choose to exit the tool without confirmation, so be wary of that. A hint string could be passed as the title of the dialog. and the format of that hint could be

MC-998TM


controlled via another parameter passed. Numeric input is the default input mode for these 2 tools, and you could switch between input methods during input by key F1. F2 is used for left arrow, and F3 for right arrow. Key C is used as backspace pressing key C on an empty string would exit the tool with GETS_DIALG_CANCEL. Pressing => would exit the tool with GETS_DIALG_CONFIRM.

5.4.2.1 Screen Layout First line, the hint line. you could set the hint as inverted/normal, center aligned/left aligned; Scond line, the input echo line. it shows the current editing string before the cursor. a visible cursor could tell you where you are. the string is shifted left if the string is longer than a line, and a symbol to indicate this situation would be printed on the start of this line. The lower half of the screen is for status and input prompt. a scroll bar would be displayed if more than one candidates are waiting to be selected. Little arrows would be displayed on corresponding end of the bar if it's possible to scroll up/down. there is a small icon in the lower left corner of the screen to indicate current input mode.

5.4.2.2 Numbers, By Default In numeric mode, key 0~9 would append '0'~'9' to the editing string.

5.4.2.3 English With Punctuation In alpha mode, key 0~9 would pop up a selection area on the lower half of the LCD. then, user could use key 1~8 to select from the letter/punctuation listed. if the number of candidates is too large to display in a screen, you could use key F2 & F3 to scroll pages. Key C would clear this selection if it has been popped up, otherwise key C would simply backspace on the editing string. it's not possible to switch input mode with F1 if the selection is popped up.

5.4.2.4 Nihao In Chinese mode, there are 2 stages :

1) key 2~8 would pop up a selection area on the lower half of the LCD. you could go on typing in PINYIN, and all the pinyin that could be represented by this key sequence would be shown for selection. use F2 & F3 to highlight your selection and press => to select it. key C will clear the selection. it is possible to switch input mode with F1 here.

MC-998TM


2) Then, as in alpha mode, all the Chinese characters that are pronounced as that pinyin would be shown. again, you could use 1~8 to select your character if it's there, or F2 & F3 to scroll the page and dig it out. key C will go back to stage 1. it is not possible to switch input mode with F1 here.

5.4.2.5 Tools There are 2 tools for string input. They are basically the same, except that the English tool does not have a Chinese input mode, and the prompt string is in English. English tool: gets_dialog_alpha(). the reason why we call it English tool while the function is named alpha, is that it only support ASCII letters, no Spanish, no French, yet. but it will be improved soon. Chinese tool: gets_dialog_ch(). well actually there is only one input method here-full pinyin.

5.5 For Those Who Want To Do More The topics in this section is closely related to the implementation of the console driver, so you got to know how to tune it if you are not satisfied with the performance.

5.5.1 Sleep Or Not? As we mentioned above, the system would enter power-saving mode while getch()/getchx() is called. There are 2 power-saving modes for MC-998, that we'd like to refer to as sleep mode and nap mode. In sleep mode, the clock of the CPU is stopped, the total current consumption is reduced to minimum. but in this mode, all clock related devices are inaccessible, no UART, no beeper, no card. In nap mode, only the CPU hangs, the clocks goes on. the power consumption is also reduced dramatically, but it's still about 10 times of that in sleep mode. So , it all depends. A global variable named stay_awake controls the power-saving mode. if it's none zero the system would enter nap mode, otherwise, sleep mode.

5.5.2 Hold On For A Minute If the system stays in idle mode (power-saving mode with no input) for a certain time, the

MC-998TM


console driver would also turn off the display to reduce power consumption even more. That timeout timer is set to 30 seconds by default, but it could be changed. A global variable named con_screen_saving_time controls that. but the value to assign is not so straight forward. e.g. you want to set it to 1 minute, that's 60s, you got to set it as 60/2-1 = 29.

5.5.3 Bilingual? It is possible to display in both 5x7 English and 16x16 Chinese. the trick is change language before you print. Because the coordinate systems are different for English and Chinese consoles, it's recommended to move cursor (by calling move_sursor()) to the right position before language switching. There're two ways to change language:

1) set_console_english and set_console_chinese 2) chang_console_language(language_id)

5.5.4 Alkaline, Dry, NiCd, Li-ion

That battery symbol was always one of the stickiest part for MC-998 programmers. now we have a simple solution for that:

refresh_batt_symbol(batt_id); Each time you invoke this routine, the console driver would check the battery and refresh the battery symbol. it takes some time for the detection circuit to recover, so do not call it too frequently. We only got charts for alkaline battery and NiCd battery, so batt_id could only be either BATT_ALKALINE or BATT_NiCd, new charts are coming soon.

5.6 Inside Look You need 2 files to use the console driver:

the header file: console.h the library file: libconso.a

5.6.1 Header File

The header file contains all the constants, variables, function prototypes and macros, you may check them out yourselves. The following headers have been included by console.h, so you don't have to include them again. and, always use console.h as

MC-998TM


the last of your include files: stdio.h stdarg.h stdlib.h api.h string.h

5.6.2 Constants

5.6.2.1 The Keys

Key Name Value key 0 KEY_0 0 key 1 KEY_1 1 key 2 KEY_2 2 key 3 KEY_3 3 key 4 KEY_4 4 key 5 KEY_5 5 key 6 KEY_6 6 key 7 KEY_7 7 key 8 KEY_8 8 key 9 KEY_9 9 key C KEY_CLR 10 key => KEY_ENTER 11 key F1 KEY_F1 12 key F2 KEY_F2 13 key F3 KEY_F3 14

These values mayl be returned by getch() and getchx().

5.6.2.2 The Jog dial

Jog dial Name Value roll up JOG_UP 16 roll down JOG_DOWN 17 press dial KEY_ENTER 11

These values may be returned by getch() and getchx().

5.6.2.3 Invalid Key Non-exist key that could only be returned in case of hardware error.

Key Name Value

MC-998TM


invalid KEY_INVALID 18 The value may be returned by getch() and getchx().

5.6.2.4 Card Activities

Activity Name Value card inserting CARD_INSERT 0x100 card withdrawing CARD_GONE 0x200

These values may be returned by getchx().

5.6.2.5 Console Language Setting

Name Value Meaning CONSOLE_ENGLISH 0 English console CONSOLE_CHINESE 1 Chinese console

These values may be used as parameter for init_console() and change_console_language(). Only one of them could be used. These values could also be used for comparing with con_lang_id.

5.6.2.6 Battery Check Setting

Name Value Meaning BATT_ALKALINE 0 check as alkaline battery BATT_NiCd 1 check as NiCd rechargeable battery

These values may be used as parameter for refresh_batt_symbol().

5.6.2.7 Return Codes For Numeric Input Tools

Name Value Meaning GETS_ESC 0 input canceled GETS_CONFIRM 1 input confirmed

These values may be returned by gets_date() and gets_time().

5.6.2.8 Input Mode For Date Input Tools

Name Value Meaning DATE_YMD 0 Chinese date mode YYYY/MM/DD DATE_MDY 1 US date mode MM/DD/YYYY DATE_DMY 2 European date mode DD/MM/YYYY

MC-998TM


These values may be used as parameter for gets_date(). Only one of them could be used.

5.6.2.9 Return Codes For String Input Tools Name Value Meaning GETS_DIALG_CANCEL 0 input canceled GETS_DIALG_CONFIRM 1 input confirmed GETS_DIALG_ERROR -1 critical error when launching dialog

These values may be returned by gets_dialog_ch() and gets_dialog_alpha(). GETS_DIALG_ERROR is returned only if the system is lack of heap memory when launching the dialog.

5.6.2.10 Hint Property For String Input Tools Name Value Meaning GETS_HINT_CENTER 2 the hint is center aligned GETS_HINT_INVERSED 1 the hint is displayed inverted.

These values may be used as parameter for gets_dialog_ch() and gets_dialog_alpha(). They could be bit-or'ed when using as the hint attribute description.

5.6.3 Variables 5.6.3.1 Language Selection

Declaration

char con_lang_id;

Values

Value Meaning CONSOLE_ENGLISH English console. CONSOLE_CHINESE Chinese console.

Remarks

It only affects the console operations after its setting, including move_cursor() , puts(), etc.

MC-998TM


Macros Related

set_inversed_disp() and set_normal_disp().

5.6.3.2 Inverted Display Control Declaration

char inversed_disp;

Values

Value Meaning 0 normal display, black on white. 1 inverted display, white on black.

Remarks

It only affects the char written after its setting.

Macros Related set_inversed_disp() and set_normal_disp().

5.6.3.3 Screen Saving Timer Timeout Setting Declaration

short con_screen_saving_time;

Values

Timeout timer setting based on a 2 second unit. so a value of n means (n+1)*2 seconds.

Remarks

Default is 14 for 30 seconds. don't set it too small or the user would be busy pressing the power key.

5.6.3.4 System Power-saving Mode Selection

Declaration

MC-998TM


char stay_awake;

Values Value Meaning 0 sleep mode, clock stops while idle. 1 nap mode, clock remains while idle.

Remarks

Go to sleep as much as you can to save your battery. switch to nap mode if only necessary.

5.6.4 Functions/Macros

5.6.4.1 init_console( ) This function initializes the console driver. Declaration

void init_console ( unsigned char lang_id ) ;

Parameters lang_id

Value Meaning CONSOLE_ENGLISH English console. CONSOLE_CHINESE Chinese console. Other values not supported

Return Values

None.

Remarks:

This initialization routine of the console driver should be called as part of the program initialization if you want to use console driver. You don't have to call it twice.

MC-998TM


After invoking init_console(), the console is set as lang_id, screen is cleared, cursor set back home at (0,0), screen saving time set as 30 seconds, power-saving mode set as sleep mode.

5.6.4.2 clear_console( ) This function clears the entire display. Declaration

void clear_console ( void ) ;

Parameters

None.

Return Values

None.

Remarks:

It clears the entire LCD and park the cursor on the upper left corner, which is (0,0);

5.6.4.3 change_console_language( ) change_console_language() is a macro that changes current console language. Declaration

void change_console_language ( short lang_id );

Parameters lang_id

Value Meaning CONSOLE_ENGLISH English console. CONSOLE_CHINESE Chinese console.

MC-998TM


other values not supported Return Values

None. Remarks:

change_console_language() is a macro that sets con_lang_id. See Also

con_lang_id(), set_console_english(), set_console_chinese().

5.6.4.4 set_console_english( ) / set_console_chinese( ) These 2 macros may be used to set current console language. Declaration

void set_console_english ( void ) ; void set_console_chinese ( void ) ;

Parameters

None. Return Values

None.

Remarks:

Their implementations are: #define set_console_english() { con_lang_id = CONSOLE_ENGLISH; }

MC-998TM


#define set_console_chinese() { con_lang_id = CONSOLE_CHINESE; }

5.6.4.5 move_cursor( ) This function moves cursor to a location. Declaration

void move_cursor ( short x, short y

) ; Parameters

x

column of the cursor Range: 0~15 for Chinese console

0~21 for English console y

row cursor, Range: 0~7. Return Values

None.

Remarks This function moves the cursor to a certain location so that next output function could write there. Please be careful of the coordinate systems difference between English and Chinese consoles. There is no range check for parameter x, y.

5.6.4.6 set_inversed_disp( ) / set_normal_disp( ) These 2 macros may be used to set if the characters should be displayed as inverted. Declaration

void set_inversed_disp (

MC-998TM


void ) ; void set_normal_disp ( void ) ;

Parameters

None. Return Values

None.

Remarks:

their implementations are: #define set_inversed_disp() { inversed_disp = 1; } #define set_normal_disp() { inversed_disp = 0; }

5.6.4.7 printf( ) It's a macro that's running just like printf() function of standard C language. Declaration

void printf ( char * fmt,... ) ;

Parameters

c.f. printf() of stdio.h in standard C language.

Return Values

None.

Remarks: That's how it's implemented:

MC-998TM


#define printf my_printf void my_printf(char * fmt, ...) {

va_list ap; va_start(ap, fmt); vsprintf(con_line_buff, fmt, ap); puts(con_line_buff);

}

5.6.4.8 puts( ) It's a macro that's running just like puts() of stdio.h in standard C language. Declaration

void puts ( char * str ) ;

Parameters

c.f. puts() of stdio.h in standard C language. Return Values

None.

Remarks

It's just like the original puts(), with some minor differences: 1) control characters (0x00~0x1F) are printed as internal symbols, so please

avoid them. 2) support for mixed Chinese/Alphanumeric string.

5.6.4.9 getch( ) / getchx( )

getch() is a macro that gets a character from keypad and jog dial. getchx() is a macro that also gets card activities besides keypad and jog dial. Declaration

MC-998TM


short getch ( void ) ; short getchx ( void ) ;

Parameters

None.

Remarks

getch() will lead the system to a powersaving idle mode waiting for key/jog dial input. it will return when valid key pressing or jog dial activity has been captured. getchx() also captures card activity.

Return Values

Value Meaning could be returned by KEY_0 key 0 pressing getch()/getchx() KEY_1 key 1 pressing getch()/getchx() KEY_2 key 2 pressing getch()/getchx() KEY_3 key 3 pressing getch()/getchx() KEY_4 key 4 pressing getch()/getchx() KEY_5 key 5 pressing getch()/getchx() KEY_6 key 6 pressing getch()/getchx() KEY_7 key 7 pressing getch()/getchx() KEY_8 key 8 pressing getch()/getchx() KEY_9 key 9 pressing getch()/getchx() KEY_CLR key C pressing getch()/getchx() KEY_ENTER key => pressing or getch()/getchx() jog dial pressing KEY_F1 key F1 pressing getch()/getchx() KEY_F2 key F2 pressing getch()/getchx() KEY_F3 key F3 pressing getch()/getchx() JOG_UP jog dial roll up getch()/getchx() JOG_DOWN jog dial roll down getch()/getchx() CARD_INSERT card inserted getchx() CARD_GONE card withdrawn getchx()

anything else returned is invalid

MC-998TM


5.6.4.10 is_card_activity( ) / is_jogdialer( ) / is_key_valid( ) These macros are used to classify the return value of getch()/getchx(). Declaration

short is_card_activity ( short ret_code ) ; short is_jogdialer (

short ret_code ) ; short is_key_valid ( short ret_code ) ;

Parameters

It's the value returned by getch()/getchx(). Return Values

Value Meaning For is_card_activity()

1 if CARD_INSERT or CARD_GONE 0 if neither.

For is_jogdialer()

1 if JOG_UP or JOG_DOWN 0 if neither.

For is_key_valid()

1 if KEY_xxx or JOG_xxx 0 if none.

Remarks

After you get something by getch()/getchx(), some tools may be useful to let you know what kind of event it is.

MC-998TM


is_card_activity() is a macro to tell you whether it is a card event; is_jogdialer() is a macro to tell you whether it is a jog dial event; is_key_valid() is a macro to tell you if it's from keypad and jog dial; Please note that a card activity is not a valid key, so, is_key_valid() is 0 while is_card_activity() is 1.

5.6.4.11 gets_dialog_ch( ) / gets_dialog_alpha( )

gets_dialog_ch() reads a string mixed with Chinese/English/number. gets_dialog_alpha() reads a string mixed with English/number. Declaration

short gets_dialog_ch ( char * buff, char * hint, char hint_flag

) ; short gets_dialog_alpha (

char * buff, char * hint, char hint_flag

) ;

Remarks

These functions read a string using a dialog, current screen is saved when entering the dialog, and restored when exiting. Please note that the buff is corrupted no matter whether the input is confirmed or not. These two functions are basically the same except that there is no Chinese input mode in gets_dialog_alpha(). The reason for an individual alphanumeric input dialog is that the Chinese input mode occupies about 60% of the codespace of the gets_dialog_ch(). so, if you don't need Chinese input you don't have to waste your space on that.

Parameters

MC-998TM


buff

Buffer to store the result string. should be large enough to hold as many characters as you could expect the user to input.

hint

The hint string as the title line of the dialog hint_flag

Controls how the title is displayed. it's a bitmapped option list which could be one of following flags or their combination by bit-or'ing some of them:

Value Meaning GETS_HINT_CENTER the hint is center aligned GETS_HINT_INVERSED the hint is displayed inverted.

Return Values

Value Meaning GETS_DIALG_CANCEL input canceled GETS_DIALG_CONFIRM input confirmed GETS_DIALG_ERROR critical error when launching dialog Other value there must have been an error.

5.6.4.12 get_numeric( ) This function reads a fixed point number. Declaration

unsigned long get_numeric ( short x, short y, short short_part, short frac_part

) ;

Parameters x

Column of the echo start position Range: 0~15 for Chinese console mode and 0~21 for English console mode.

y

MC-998TM


row of the echo start position Range: 0~7.

short_part max length of the integer part of the result Range: 0~9.

frac_part length of the decimal fraction part of the result Range: 0~9-short_part

Return Values

It's the fixed point number that user input. Remarks

This function reads a fixed point number from keypad, echoing at given location. the returned value is an unsigned long value, so the programmer must know where the decimal point is. it's recommended not to input value that's larger than an unsigned long. so , we suggest that the sum of short_part and frac_part should be no more than 9.

Example

Get a fixed point number that is less than 10000, with 3 digits of fraction, and echoes at 1st row, 3rd column:

unsigned long result;

result = get_numeric(2, 0, 4, 3); // (2,0) for position, 4,3 for 9999.999 format // if user inputs 1234.567, // the return value would be 1234567.

5.6.4.13 gets_time( ) This function reads a string representing time, in 24hour format. Declaration

short gets_time ( short x,

MC-998TM


short y, char * buff

) ;

Parameters x

column of the echo start position; Range: 0~15 for Chinese console, and

0~21 for English console. y

row of the echo start position; Range: 0~7.

buff

buffer to store the result string. should be large enough to hold 6 characters. Return Values

Value Meaning GETS_ESC input canceled GETS_CONFIRM input confirmed other value there must have been an error.

Remarks

This function reads a time string from keypad, echoing at given location. the colon (':') need not be inputted, but the returned string contains colon at certain position.

Please note that the buff is corrupted no matter whether the input is confirmed or not.

5.6.4.14 gets_date( )

This function reads a string representing date. Declaration

short gets_date ( short x, short y, short datemode,

MC-998TM


char * buff ) ;

Parameters x

Column of the echo start position Range: 0~15 for Chinese console mode and 0~21 for English console mode.

y

row of the echo start position Range: 0~7.

datemode input date format setting:

Value Meaning DATE_YMD Chinese date mode YYYY/MM/DD DATE_MDY US date mode MM/DD/YYYY DATE_DMY European date mode DD/MM/YYYY

buff buffer to store the result string. should be large enough to hold 11 characters.

Return Values

Value Meaning GETS_ESC input canceled GETS_CONFIRM input confirmed other value there must have been an error.

Remarks

read a date string from keypad, echoing at given location. the slash ('/') need not be inputted, but the returned string contains slash at certain positions. please note that buff is corrupted not matter if the input is confirmed.

5.6.4.15 refresh_batt_symbol( ) This function refreshes that battery scale icons on the LCD. Declaration

void refresh_batt_symbol (

MC-998TM


short batt_id ) ;

Parameters batt_id

Right now, there are only two options: Value Meaning BATT_ALKALINE check as alkaline battery, full scale at

3.2V BATT_NiCd check as NiCd rechargeable battery, full

scale at 2.4V

Return Values

None.

Remarks

This function checks the battery level and refreshes the battery scale according to the battery setting. It takes some time for the detection circuit to recover, so do not call it too frequently.

read.pudn.comread.pudn.com/downloads205/doc/964397/mc998 api reference documen…read.pudn.com

Documents