(P78, P80, P90, R50, P58, R30, R50-M, R100) API Programming (V1.2.5)

Application Developer
Guide
(Applicable for P78 P80 P90 R50 P58 R30 R50-M and R100)
VER: V1.2.5
PAX Computer Technology (Shenzhen)Co.,Ltd.

Application Developer Guide (Applicable for P78 P80 P90 R50 P58 R30 R50-M and R100) V1.2.5
Table of Contents
1. GENERAL ................................................................................................................................. 8
1.1 CONTENT DESCRIPTION ......................................................................................................... 8

1.1.1 Compatibility Issues and Instructions................................................................................ 8
1.1.2 Table of Applicable Product Module ................................................................................. 8
1.2 REVISION HISTORY ............................................................................................................... 9
2. DEVELOPMENT PLATFORM .............................................................................................. 13
2.1 SYSTEM REQUIREMENT ....................................................................................................... 13

2.2 SOFTWARE TOOLS ............................................................................................................... 13
2.2.1 Compiling Tools ............................................................................................................. 13
3. DETAILED API DESCRIPTIONS .......................................................................................... 14
3.1 BASIC FUNCTIONS ............................................................................................................... 14

3.1.1 SystemInit ...................................................................................................................... 14
3.1.2 Beep............................................................................................................................... 15
3.1.3 Beef................................................................................................................................ 15
3.1.4 SetTime .......................................................................................................................... 15
3.1.5 GetTime ......................................................................................................................... 16
3.1.6 DelayMs......................................................................................................................... 17
3.1.7 TimerSet ......................................................................................................................... 17
3.1.8 TimerCheck .................................................................................................................... 17
3.1.9 ReadSN .......................................................................................................................... 17
3.1.10 EXReadSN ................................................................................................................. 18
3.1.11 ReadVerInfo ............................................................................................................... 18
3.1.12 GetLastError .............................................................................................................. 19
3.1.13 GetTermInfo ............................................................................................................... 19
3.1.14 EnumFont .................................................................................................................. 22
3.1.15 ScrSelectFont ............................................................................................................. 23
3.1.16 PrnSelectFont ............................................................................................................ 23
3.1.17 LedDisplay ................................................................................................................. 23
3.2 POWER MANAGEMENT FUNCTIONS ...................................................................................... 24
3.2.1 PowerSave ..................................................................................................................... 24
3.2.2 AutoPowerSave .............................................................................................................. 25
3.2.3 BatteryCheck.................................................................................................................. 26
3.2.4 Power Off....................................................................................................................... 27
3.3 KEYBOARD FUNCTIONS ....................................................................................................... 27
3.3.1 kbhit ............................................................................................................................... 27
3.3.2 kbflush ........................................................................................................................... 28
3.3.3 getkey............................................................................................................................. 28
3.3.4 kbmute ........................................................................................................................... 29
3.3.5 kbsound.......................................................................................................................... 29
3.3.6 GetString........................................................................................................................ 30
PAX Computer Technology (Shenzhen)Co.,Ltd. 1/196

3.3.7 GetHzString ................................................................................................................... 31

3.3.8 kblight ............................................................................................................................ 32
3.3.9 SetLightTime .................................................................................................................. 32
3.3.10 SetSlipFW .................................................................................................................. 33
3.4 LCD FUNCTIONS................................................................................................................. 33
3.4.1 ScrCls ............................................................................................................................ 34
3.4.2 ScrClrLine ..................................................................................................................... 34
3.4.3 ScrGray ......................................................................................................................... 34
3.4.4 ScrBackLight.................................................................................................................. 34
3.4.5 ScrGotoxy ...................................................................................................................... 35
3.4.6 ScrFontSet ..................................................................................................................... 35
3.4.7 ScrAttrSet ....................................................................................................................... 36
3.4.8 Lcdprintf ........................................................................................................................ 36
3.4.9 ScrPrint ......................................................................................................................... 36
3.4.10 ScrPlot ....................................................................................................................... 37
3.4.11 ScrDrLogo ................................................................................................................. 37
3.4.12 ScrDrLogoxy .............................................................................................................. 38
3.4.13 ScrRestore .................................................................................................................. 39
3.4.14 ScrSetIcon .................................................................................................................. 39
3.4.15 ScrDrawBox ............................................................................................................... 40
3.4.16 ScrGotoxyEx .............................................................................................................. 40
3.4.17 ScrGetxyEx ................................................................................................................ 41
3.4.18 ScrDrawRect .............................................................................................................. 41
3.4.19 ScrClrRect ................................................................................................................. 41
3.4.20 ScrSpaceSet................................................................................................................ 41
3.4.21 ScrGetLcdSize ............................................................................................................ 42
3.4.22 ScrTextOut ................................................................................................................. 42
3.5 MAGNETIC STRIPE CARD READER FUNCTIONS ..................................................................... 42
3.5.1 MagOpen ....................................................................................................................... 43
3.5.2 MagClose ....................................................................................................................... 43
3.5.3 MagReset ....................................................................................................................... 43
3.5.4 MagSwiped .................................................................................................................... 44
3.5.5 MagRead........................................................................................................................ 44
3.6 IC CARD FUNCTIONS ........................................................................................................... 45
3.6.1 IccInit ............................................................................................................................ 46
3.6.2 IccClose ......................................................................................................................... 48
3.6.3 IccAutoResp ................................................................................................................... 48
3.6.4 IccIsoCommand ............................................................................................................. 49
3.6.5 IccDetect ........................................................................................................................ 50
3.7 CONTACTLESS RF CARD FUNCTIONS ................................................................................... 50
3.7.1 PiccOpen ....................................................................................................................... 54
3.7.2 PiccSetup ....................................................................................................................... 55
3.7.3 PiccDetect...................................................................................................................... 57
3.7.4 PiccIsoCommand ........................................................................................................... 60

3.7.5 PiccRemove.................................................................................................................... 62
3.7.6 PiccClose ....................................................................................................................... 64
3.7.7 M1Authority ................................................................................................................... 66
3.7.8 M1ReadBlock ................................................................................................................. 67
3.7.9 M1WriteBlock ................................................................................................................ 69
3.7.10 M1Operate ................................................................................................................. 71
3.7.11 PiccLight.................................................................................................................... 73
3.7.12 PiccInitFelica............................................................................................................. 74
3.7.13 PiccCmdExchange ..................................................................................................... 75
3.8 PRINTING FUNCTIONS.......................................................................................................... 75
3.8.1 PrnInit ........................................................................................................................... 77
3.8.2 PrnFontSet(P78) ............................................................................................................ 77
3.8.3 PrnFontSet (P80, P90) ................................................................................................... 78
3.8.4 PrnSpaceSet ................................................................................................................... 78
3.8.5 PrnStep .......................................................................................................................... 79
3.8.6 PrnStr ............................................................................................................................ 79
3.8.7 PrnLogo ......................................................................................................................... 80
3.8.8 PrnStart ......................................................................................................................... 81
3.8.9 PrnStatus ....................................................................................................................... 82
3.8.10 PrnLeftIndent ............................................................................................................. 83
3.8.11 PrnGetDotLine ........................................................................................................... 83
3.8.12 PrnSetGray (P80)....................................................................................................... 84
3.8.13 PrnSetGray (P90)....................................................................................................... 84
3.8.14 PrnGetFontDot .......................................................................................................... 85
3.8.15 PrnDoubleWidth......................................................................................................... 85
3.8.16 PrnDoubleHeight ....................................................................................................... 85
3.8.17 PrnAttrSet .................................................................................................................. 86
3.9 ASYNCHRONOUS PORT COMMUNICATION FUNCTIONS........................................................... 86
3.9.1 PortOpen ....................................................................................................................... 86
3.9.2 PortClose ....................................................................................................................... 87
3.9.3 PortSend ........................................................................................................................ 88
3.9.4 PortRecv ........................................................................................................................ 89
3.9.5 PortReset ....................................................................................................................... 89
3.9.6 PortSends....................................................................................................................... 90
3.9.7 PortTxPoolCheck ........................................................................................................... 90
3.9.8 PortRecvs....................................................................................................................... 91
3.10 MODEM COMMUNICATION FUNCTIONS .............................................................................. 92
3.10.1 ModemReset ............................................................................................................... 94
3.10.2 ModemDial ................................................................................................................ 95
3.10.3 ModemCheck ............................................................................................................. 98
3.10.4 ModemTxd ............................................................................................................... 100
3.10.5 ModemRxd ............................................................................................................... 100
3.10.6 ModemAsyncGet ...................................................................................................... 101
3.10.7 OnHook ................................................................................................................... 101

3.10.8 ModemExCommand ................................................................................................. 101

3.10.9 How to Set P80 POS as an External MODEM........................................................... 104
3.11 WIRELESS COMMUNICATION FUNCTIONS ........................................................................... 105
3.11.1 WnetInit ................................................................................................................... 105
3.11.2 WnetCheckSignal ..................................................................................................... 105
3.11.3 WNetCheckSim......................................................................................................... 106
3.11.4 WnetSimPin.............................................................................................................. 107
3.11.5 WnetUidPwd ............................................................................................................ 107
3.11.6 WnetDial .................................................................................................................. 108
3.11.7 WnetCheck ............................................................................................................... 109
3.11.8 WNetTcpConnect ...................................................................................................... 109
3.11.9 WNetTcpTxd ............................................................................................................. 110
3.11.10 WNetTcpRxd..............................................................................................................111
3.11.11 WNetTcpClose ...........................................................................................................111
3.11.12 WNetClose ............................................................................................................... 112
3.11.13 WNetLinkCheck........................................................................................................ 112
3.11.14 WNetTcpCheck ......................................................................................................... 113
3.11.15 WNetReset................................................................................................................ 113
3.11.16 WNetSendCmd ......................................................................................................... 114
3.11.17 WNetMTcpConnect ................................................................................................... 114
3.11.18 WNetMTcpTxd.......................................................................................................... 115
3.11.19 WNetMTcpRxd ......................................................................................................... 116
3.11.20 WNetMTcpClose ....................................................................................................... 117
3.11.21 WNetMTcpCheck ...................................................................................................... 117
3.11.22 WPhoneCall ............................................................................................................. 118
3.11.23 WPhoneHangUp ...................................................................................................... 118
3.11.24 WPhoneStatus .......................................................................................................... 119
3.11.25 WPhoneAnswer ........................................................................................................ 119
3.11.26 WPhoneMicGain ...................................................................................................... 120
3.11.27 WPhoneSpkGain ...................................................................................................... 120
3.11.28 WPhoneSendDTMF .................................................................................................. 121
3.11.29 Notes for Wireless Module ........................................................................................ 121
3.11.30 API Sample of Wireless Module ................................................................................ 121
3.11.31 Wireless Module Phone API Example ....................................................................... 124
3.12 PPP PROTOCOL INTERFACE FUNCTIONS ............................................................................. 126
3.12.1 NpppLogin ............................................................................................................... 127
3.12.2 NpppOpen ................................................................................................................ 129
3.12.3 NpppWrite ................................................................................................................ 130
3.12.4 NpppRead ................................................................................................................ 131
3.12.5 NpppCheck............................................................................................................... 132
3.12.6 NpppClose ............................................................................................................... 134
3.12.7 NpppProcess ............................................................................................................ 135
3.12.8 GsmCallModem ....................................................................................................... 135
3.12.9 GsmCheck ................................................................................................................ 139

3.12.10 GsmOnHook ............................................................................................................ 140

3.12.11 NpppSetAuth ............................................................................................................ 142
3.13 FILE SYSTEM OPERATION .................................................................................................. 142
3.13.1 open ......................................................................................................................... 143
3.13.2 ex_open.................................................................................................................... 144
3.13.3 read ......................................................................................................................... 145
3.13.4 write ........................................................................................................................ 145
3.13.5 close ........................................................................................................................ 145
3.13.6 seek .......................................................................................................................... 146
3.13.7 filesize ...................................................................................................................... 146
3.13.8 remove ..................................................................................................................... 147
3.13.9 freesize ..................................................................................................................... 147
3.13.10 InitFileSys ................................................................................................................ 147
3.13.11 Truncate ................................................................................................................... 147
3.13.12 Fexist ....................................................................................................................... 148
3.13.13 GetFileInfo............................................................................................................... 148
3.13.14 FileToApp ................................................................................................................ 149
3.13.15 FileToParam ............................................................................................................ 149
3.13.16 FileToMonitor .......................................................................................................... 150
3.13.17 ReadFontLib ............................................................................................................ 150
3.13.18 DelAppFile............................................................................................................... 150
3.14 ENVIRONMENT VARIABLES FUNCTIONS .............................................................................. 151
3.14.1 GetEnv ..................................................................................................................... 151
3.14.2 PutEnv ..................................................................................................................... 152
3.15 ENCRYPTION / DECRYPTION FUNCTION .............................................................................. 152
3.15.1 des ........................................................................................................................... 152
3.15.2 Hash ........................................................................................................................ 152
3.15.3 RSARecover ............................................................................................................. 153
3.16 PED FUNCTIONS ............................................................................................................... 153
3.16.1 PEDInputTimeOut .................................................................................................... 154
3.16.2 PEDInput ................................................................................................................. 154
3.16.3 PEDGetPwd ............................................................................................................. 155
3.16.4 PEDGetPwd_3Des ................................................................................................... 156
3.16.5 PEDWriteMKey........................................................................................................ 156
3.16.6 PEDWriteDKey ........................................................................................................ 157
3.16.7 PEDWriteWKey........................................................................................................ 157
3.16.8 PEDDeriveKey ......................................................................................................... 158
3.16.9 PEDDes ................................................................................................................... 159
3.16.10 PEDMac .................................................................................................................. 159
3.16.11 EPSPEDAmount....................................................................................................... 160
3.16.12 EPSPEDLoadTMK ................................................................................................... 161
3.16.13 EPSPEDLoadKey ..................................................................................................... 161
3.16.14 EPSPEDGetMAC1 ................................................................................................... 162
3.16.15 EPSPEDUpdateTPK ................................................................................................ 162

3.16.16 EPSPEDSetMAC2 .................................................................................................... 163

3.16.17 EPSPEDVerifyTMK .................................................................................................. 164
3.16.18 EPSPEDGetPwd ...................................................................................................... 164
3.16.19 PED_PassWordEncrypt ............................................................................................ 165
3.16.20 PED_PassWordInput ................................................................................................ 165
3.16.21 SYLPEDGetPwd ....................................................................................................... 166
3.16.22 SYLPEDVerifyDerive................................................................................................ 167
3.16.23 SYLPEDCalcPinBlock .............................................................................................. 167
3.16.24 SYLPEDLoadTMK ................................................................................................... 168
3.16.25 PEDManage............................................................................................................. 169
3.17 MULTI-APPLICATION MANAGEMENT FUNCTIONS ................................................................ 169
3.17.1 ReadAppInfo ............................................................................................................ 170
3.17.2 ReadAppState ........................................................................................................... 170
3.17.3 SetAppActive ............................................................................................................ 170
3.17.4 RunApp .................................................................................................................... 171
3.17.5 DoEvent ................................................................................................................... 171
3.18 IP OPERATION FUNCTION .................................................................................................. 171
3.18.1 Module Return Code List .......................................................................................... 171
3.18.2 NetSocket ................................................................................................................. 172
3.18.3 NetBind .................................................................................................................... 172
3.18.4 NetConnect .............................................................................................................. 173
3.18.5 NetListen.................................................................................................................. 173
3.18.6 NetAccept ................................................................................................................. 173
3.18.7 NetSend.................................................................................................................... 174
3.18.8 NetSendto................................................................................................................. 174
3.18.9 NetRecv.................................................................................................................... 174
3.18.10 NetRecvfrom............................................................................................................. 175
3.18.11 NetCloseSocket......................................................................................................... 175
3.18.12 Netioctl .................................................................................................................... 176
3.18.13 SockAddrSet ............................................................................................................. 178
3.18.14 SockAddrGet ............................................................................................................ 178
3.18.15 DnsResolve .............................................................................................................. 178
3.18.16 NetPing .................................................................................................................... 179
3.18.17 RouteSetDefault ....................................................................................................... 179
3.18.18 RouteGetDefault....................................................................................................... 179
3.18.19 NetDevGet ............................................................................................................... 179
4. COMPILING AND LINKING ............................................................................................... 181
4.1 GCC INTRODUCTION ......................................................................................................... 181

4.1.1 Basic Usage and Options for GCC................................................................................ 181
4.1.2 GCC Error Message Type and Handling ....................................................................... 183
4.2 COMPILING ....................................................................................................................... 184
4.3 LINKING AND CONVERTING ............................................................................................... 184
4.4 MAKEFILE SAMPLE ........................................................................................................... 184
4.5 LINKING DESCRIPTION FILE EXAMPLE ............................................................................... 187

4.6 PAXPAYPRO APPLICATION DEVELOPMENT SAMPLES .......................................................... 188

4.7 NOTES FOR APPLICATION DEVELOPMENT ........................................................................... 190
4.8 APPLICATION SPACE LIMITATION ....................................................................................... 190
4.8.1 Space Definition ........................................................................................................... 190
4.8.2 Size of Space and Limitation for P80, P78, P90, R50, P58 and R50-M .......................... 190
4.8.3 Size of Space and Limitation for R30 and R100 ............................................................. 191
5. APPENDIX ............................................................................................................................. 192
5.1 DATA STRUCTURE CHECKLIST ........................................................................................... 192

5.1.1 IC Card Structure ......................................................................................................... 192
5.1.2 Modem Dialing Parameter Structure ............................................................................ 192
5.1.3 File Information Structure ............................................................................................ 193
5.1.4 Application Information Structure................................................................................. 193
5.1.5 Magnetic Stripe Card Data Structure ............................................................................ 193
5.1.6 Event Process Structure ................................................................................................ 194
5.1.7 Font Structure .............................................................................................................. 194
5.1.8 IP Module Socket Address Structure.............................................................................. 194
5.2 ABBREVIATION CHECKLIST ............................................................................................... 195
5.3 GLOBAL VARIABLE ........................................................................................................... 195

1. General
1.1 Content Description
Application Developer Guide is the documentation for application development of P80, P90, P78,
R50, P58, R30, R50-M, and R100. All the technical specifications, development descriptions,
differences among P80, P90, P78, R50, P58, R30, R50-M, and R100, API descriptions and
development simulation will be discussed in this manual.
1.1.1 Compatibility Issues and Instructions

Due to module differences among P80, P78, P90, R50, P58, R30, R50-M, and R100, and
differences on the usage of some API, application developers are expected to pay attention to these
differences when using this manual. Moreover, some important descriptions will also be
highlighted with different colors, in order to emphasize the key contents. Other things that
developer should know include:
1. At the beginning of each section of API descriptions chapter, there will be special descriptions
indicating the applicable models. For example, in the section of printer API, there will be red
warning colored descriptions: This API is only applicable for the modules of P80, P78, P90,
and P58, while it is not applicable for R50, R30, R50-M and R100. Because these terminal
types do not contain printer.
2. If the API description is not applicable for some models, there will be red warning colored
description: xxx model does not support this API.
3. Before development, developer should compare and study the differences among different
product modules according to Table of Applicable Product Module.
4. Each API description contains input parameters and output parameters.
1.1.2 Table of Applicable Product Module

Table 1-1 Applicable Product Module
Module Applicable Product
Hardware Software P80 P78 P90 R50 P58 R50-M R30 R100
Module Module
/ Basic Functions
/ Encryption/
Decryption
Functions
Keyboard Keyboard
Functions
LCD LCD Functions
Magnetic Magnetic Card
Card Functions

IC Card IC Card
Reader Functions
Serial Port Asynchronous
Port
Communication
Functions
Printer Printer Functions
MODEN MODEN [For
Communication External
Functions modem]
/ File System
Functions
/ Multi-application [Only
Management for [Only
Functions multi- for
applicati multi-
on R30 applic
monitor] ation
R100
monit
or]
/ Environment
Variable
Functions
PED PED Functions
RF reader Contactless Card
Functions
CDMA,GP Wireless [Use
RS Communication the
Functions interface
that is
compati
ble with
S series]
/ PPP Protocol
Interface
Functions
Note: -Completely Applicable;-Partially Applicable;-Not Applicable
1.2 Revision History
Table 1-2 Application Developer Guide[Applicable for P78P80P90R50] Revision History

Date Version Remark Amender

2008-06-16 V1.0.0 Initial Song Kunxian

2008-07-09 V1.0.1 Add P90 external MODEM module API; Song Kunxian
Separate printer module API (Thermal and
Sprocket)
2008-9-16 V1.0.2 Add the return code list of RF Card Module Song Kunxian
operation function;
Add two parameters into internal data
structure PICC_PARA of RF Card;
Rename ProPay as PaxPayPro.
2008-10-27 V1.0.3 Modify ScrAttrSet instructions; Song Kunxian
Modify IccIsoComand instructions;
Add 32 API of DesFire Card.
2008-11-7 V1.0.4 1.Add the operating instructions about SAM Song Kunxian
card in IccInit;
2. Add the instructions that IccDetect Card
does not support SAM Card;
3.Modify Desfire API instructions
4.Modify R50PortTxPoolCheck instructions
2008-11-28 V1.0.5 The meeting discussed and determined to Song Kunxian
remove 31 API of DesFire card from
monitor to application layer, therefore delete
DesFire card these API and their
instructions. Only retain
PiccDesFire_Exchange.
2009-01-13 V1.0.6 Add R50 terminal model as 0x80 and P50 Song Kunxian
terminal model as 0x81 in P50.
2009-3-10 V1.0.7 Rename PiccDesFire_Exchange of Desfire Song Kunxian
card as PiccCmdExchange;
Add serial port instructions in R50.
2009-5-5 V1.0.8 Add transfer instructions in M1Opreate API Song Kunxian
of RF card.
2009-5-7 V1.0.9 Add the API of P58LCD and Printer; Wan Laimin
Add the instructions of FSK processing API:
not support asynchronous communication
format with modem 7, n, 1.
2009-6-5 V1.1.0 Add DelAppFile function. Saint Shi
2009-6-23 V1.1.1 Add API instructions of R30. Song Kunxian
2009-7-21 V1.1.2 Modify API instructions of R30 according Song Kunxian
to testing department.
2009-08-28 V1.1.3 Modify return code of DelAppFile() Wu Juncheng
2009-09-02 V1.1.4 Add return code instructions of interfaces in Wan Laimin
wireless module.
2009-11-20 V1.1.5 Add the support for HASH and Song Kunxian
RSARecover function of R30.

2010-01-19 V1.1.6 Add the support for FileToAPP, Song Kunxian

FileToMonitor and FileToParam function of
R30 and R50.
2010-02-04 V1.1.7 Add the support for related function of Song Kunxian
R50-M model.
2010-3-3 v1.1.8 Modify the document instructions of R50-M Song Kunxian
wireless module according to S series
development documents and instructions of
FileToMonitor function in R50R30
R50-M.
1. Add the instruction of 3G module in Wang Shangbia
GetTermInfo interface.
2. Modify the space limitation of R30
application program.
1. Add return value 0x02 and its instruction
in PiccInitFelica interface.
2. Update data structure of PICC_PARA
3. Delete return values 0x03 and 0x04 in
2010-6-28 V1.1.9 PiccOpen () interface
4. Add the instruction in PiccClose ()
interface; Add the instructions of sensitivity NingTing
and Felica Card modulation depth
inPiccSetup interface.
5. Add the return value 0xff and its
instruction in return code list of RF card
chapter ; delete "Wrong status code value
and meaning of Desfire card "
2010-8-26 V1.2.0 Add some API of "IP operation function"
Wan Laimin
for P90
2010-11-8 V1.2.1 1. Modify the instructions of
'FileToMonitor'and 'FileToParam';
2. Modify the instruction for P90 in
'communication operation function'; Wu Juncheng
3. Add the instruction "P90 does not
support synchronous "9600" dial-up or
asynchronous dialing"
1. Delete the description "P80 does not
2011-06-08 V1.2.2 support this API" in Tan Jue
PiccCmdExchange();

2. Modify the validity of logo in

PerLeftlndent();
3. Modify the descriptions of P80/P90;
4. Modify the descriptions of PED part;
5. Add return value 0x00 when the mode
is invalid in PEDManage() function;
6. Modify the input parameters and return
code of ScrFontSet();
7. Add the instruction in ScrSetIcon ()
interface;
8. Modify the range of y-coordinate in
ScrDrawBox():0~7;
9. Modify parameters
(pixel_X>=0,pixel_Y>=0) of
ScrGotoxyEx ();
10. Modify the function description of
ScrClrRect();
11. Modify the instruction and the value of
coordinate in ScrTextOut (),
2011-12-15 V1.2.3 1. Modify the return value of GetTime();
2. Add return value 0x0e and the NO.11
USB DEVICE in Asynchronous Port
Communication Functions.
3. Modify the notes of Asynchronous Port Tan Jue
Communication Functions.
4. Add the PortRecvs interface;
5. Update the data structure of PICC
PARA.
2012-07-31 V1.2.4 1. Add function description of R100. Peng Huanjie
2012-09-24 V1.2.5 1. Add instruction in some APIs that P78,
P80 and P90 support the APIs while
using S font. Liu Yanzhi
2. For P78,P80 and P90, ScrTextOut
coordinates support negative.

2. Development Platform
P80, P90, P78, R50, P58, R30, R50-M and R100 require identical development platform.
2.1 System Requirement
IBM or compatible Pentium PC, 64M memory, 200M free disk space, Windows 98 or above
operating system.
2.2 Software Tools
2.2.1 Compiling Tools

Using GCC development tools, GCC compiling and linking tools, please refer to those Linux
related documentation for detail commands and usage (or the compiling and linking samples
showed in this document).

3. Detailed API Descriptions
Due to module differences among P80, P78, P90, R50, P58, R30 and R100, and differences on
usage of some API, application developers are expected to pay attention to descriptions at the
beginning of each module, and descriptions in API Notes. Moreover, messages will be highlighted
in RED.
In order to simplify API prototype, types of data variable are defined as followed:
#define uchar unsigned char
#define ushort unsigned short
#define uint unsigned int
#define ulong unsigned long
3.1 Basic Functions
All API of this module are partially applicable for P78, P80, P90, R50, R30, R50-M and R100, and
completely applicable for P58.
Module function description: this module is designed to achieve system API operations, which
include initializing system, setting system time, adjusting system volume, using system timer,
obtaining system version, etc.
Internal module data structure: none
3.1.1 SystemInit
Prototype: uchar SystemInit(void);
Function: Initializes the system.
Input none
Parameter:
Output none
Parameter:
0x00 Application runs for the first time
Return:
0xff Application does not run for the first time
This function should be called once at the beginning of main (), it is
Notes:
unnecessary to call it for more than once.
Example: application initialization
void main ( void)
{
If (SystemInit () == 0) // runs for the first time
{
Initialize some application parameters;
}
Other parts of the application;

3.1.2 Beep
Prototype: void Beep(void)
Function: Makes a beep sound using the buzzer
Input None
Parameter:
Output None
Parameter:
Return: None
Notes: None
Example: Beep, 20 ms delay, beep again
Beep ();
DelayMs (20);
Beep ();
3.1.3 Beef
Prototype: void Beef(uchar mode, short DlyTime)
Function: Beeps at specified frequency and lasts for specified time. Stops when any key
pressed.
mode To set frequency; available frequencies(0 - 6)
Input 0 lowest frequency
Parameter: 6 highest frequency
DlyTime lasting time(unit: ms) (0~65535)
Output None
Parameter:
Return: None
When the value of mode is bigger than 6, function will use the value of
Notes:
mode%7 as beep frequency. Applicable for R30 and R100.
Example:
Beef (1,100); /* Beeps at a low frequency for 100 ms */
3.1.4 SetTime
Prototype: uchar SetTime(uchar *time)
Function: Sets up system date and time; weekly day will be calculated and set
automatically.
time Pointer to date and time parameter. Format: YYMMDDhhmmss,
Input
parameter in BCD code, 6 bytes in length.
Parameter:
(valid time range: 1950-1-1 2049-12-31)

Output None
Parameter:
0 Success
Return:
None-zero Invalid date or time
If returned value is non-zero, errors can be traced by following values:
1 Invalid year
2 Invalid month
3 Invalid date
Notes:
4 Invalid hour
5 Invalid minute
6 Invalid second
0xff non-numerical items found in parameter
R30 does not support this API!
3.1.5 GetTime
Prototype: void GetTime(uchar *time)
Function: Gets current system date, time and weekly day.
time pointer to store date and time values in packed BCD code:
str[0] year
str[1] month
Input str[2] day
Parameter: str[3] hour
str[4] minute
str[5] second
str[6] week day
Output None
Parameter:
Return:
Definition of week days:

Notes: 1 Monday, 2 Tuesday 7 Sunday
Example: Example of setting and getting date, time
unsigned char DateTime [7];
memcpy (DateTime, \x01\x08\x08\x08\x56\x42, 6);
SetTime (DateTime);
// Sets system time to 8:56:42, August 8, 2001
// the system will update week day automatically
GetTi me (DateTime) ;
// For display and other purposes after processed.


3.1.6 DelayMs
Prototype: void DelayMs(ushort Ms)
Function: Delays count ms
Input None
Parameter:
Output None
Parameter:
Return: None
Due to delay of command, system timer may be interrupted in the process of
Notes:
delay. Therefore, delay time should not be too long in order to avoid error.
3.1.7 TimerSet
Prototype: void TimerSet(uchar TimerNo, ushort Cnts)
Function: Starts specific timer (unit of timing: 100 ms). The minimum time period is 1
unit; the maximum time period can be 65535 units (=65535*100 ms)
TimerNo Reference number of timer, which is specified by user.
Input
Parameter: Cnts Time in unit(100MS)
Output None
Parameter:
Return: None
There are 5 timers available (No. 0~4). If TimerID is invalid, the system will
Notes:
use TimerID%5 instead, which is the same as TimerCheck ().
3.1.8 TimerCheck
Prototype: ushort TimerCheck(uchar TimerNo)
Function: Checks the current left time of specified timer. (unit = 100 ms)
Input TimerNo Reference number of timer, which is specified by user.
Parameter:
Output None
Parameter:
Return: Time left
Notes: The timer stops when the left time is 0.
Example: Set a 10-second timer or quit the loop when a key is pressed.
Timer Set (0,100);
while (1) {
if (kbhit () ==0) break;
if (! TimerCheck (0)) break;
}
3.1.9 ReadSN
Prototype: void ReadSN(uchar *SerialNo)

Function: Read the serial number of terminal

Input None
Parameter:
Output SerialNo Buffer for storing product serial number. It is required to allocate
Parameter: 32 bytes for the buffer.
Return: None
Serial number is a string ending with \0. The maximum length is up to 32
Notes:
bytes. If SN [0] = \0, it implies there is no serial number.
3.1.10 EXReadSN
Prototype: void EXReadSN(uchar *SN)
Function: Read the extended serial number of terminal (to meet some specific application
requirements)
Input None
Parameter:
Output SN Buffer for storing product serial number. It is required to allocate
Parameter: 32 bytes for the buffer.
Return: None
Extended serial number is a string ending with \0. The maximum length is up
Notes:
to 32 bytes. If SN [0] = \0, it implies there is no serial number.
3.1.11 ReadVerInfo
Prototype: uchar ReadVerInfo(uchar *VerInfo)
Function: Get terminal versions information
Input None
Parameter:
VerInfo VerInfo Address of version information (8 bytes)
VerInfo[0] BOOT version number
VerInfo[1] monitor major version number
VerInfo[2] monitor minor version number
VerInfo[3] main board hardware version number
Output VerInfo [4] port board hardware version number [For P90, this
Parameter: option is reserved.]
VerInfo[5] extended communication board hardware version
VerInfo[6] magnetic reader hardware version
VerInfo[7] RFID hardware version [Applicable for P80, R50,
R30 , and R100; and reserved for P90]
VerInfo[7] Pinpad hard ware version[Applicable for P78]
Return: None
Please refer to internal version number definition section. Version numbers are
Notes:
hexadecimal version.

3.1.12 GetLastError
Prototype: int GetLastError(void)
Get the value of errno. Errno cannot be directly accessed by application. This
Function:
function has to be called in order to get the value of errno.
Input None
Parameter:
Output None
Parameter:
Return: errno
Notes: None
3.1.13 GetTermInfo
Prototype: int GetTermInfo(uchar *out_info)
Get terminal model number and configuration information. Information buffer
Function:
will not be defined less than 30 bytes.
Input None
Parameter:

out_info[0]: Terminal Model Number0x00~0xFF

1:P60-S
2:P70
3:P60-S1
4:P80
5:P78
6:P90
7:S80
8:SP30
9:S60
10:S90
0x80:R50
0x81:P50
0x82:P58
Output
out_info 0x83:R30
Parameter:
0x84:R50-M
out_info[1]: Printer Type
S-- Sprocket Printer T--Thermal Printer
out_info[2]: MODEM module information
0--Do not support MODEM communication module
Others--MODEM module number code:
0x01-TDK 73K222 1200/1200
0x02-TDK 73K224 2400/2400
0x10-Silicon 2414 14.4k/2400
0x20-conexant 81802 33.6k/9600
0x40-conextant 93001-V92 56k/9600
0x41-conextant 93001-V32B 14.4K/9600
out_info[3]: MODEM highest synchronization speed information
1-1200 2-2400 3-9600 4-14400

out_info[4]: MODEM highest asynchronization speed

information
1-1200 2-2400 3-4800 4-7200
5-9600 6-12000 7-14400 8-19200
9-24000 10-26400 11-28800 12-31200
13-33600 14-48000 15-56000
out_info[5]: PCI information
0--Do not support embedded PCI safety module
Others--Support embedded PCI safety module (version
code)
out_info[6]: USB Host (HOST) Information
0--Do not support USB Host interface
Others--USB Host Interface version code (for example,
USB1.1, USB2.0, USB-OTG etc.)
out_info[7]: USB accessories information
0--Do not support accessories connected by USB interface
Others--USB accessories interface version code
out_info[8]: LAN(TCP/IP)module information
0--Do not support TCP/IP module
Others--TCP/IP module version code
out_info[9]: GPRS module information
0--Do not support GPRS module
Others--GPRS module version code
out_info[10]: CDMA module information
0--Do not support CDMA module
Others--CDMA module version code
out_info[11]: Wi-Fi module information
0--Do not support Wi-Fi module
Others--Wi-Fi module version code
out_info[12]: Contactless read module information
0--Do not support contactless read module
1--Contactless read module is RC531 module
2--Contactless read module is PN512 module
out_info[13]:Display font version information
0--No font file;
1--Chinese font;
2--English font[Only for P90]
3--Russian font[Only for P90]
Other-- Version code
out_info[14]:Print fonts version information
0--No font file;
1--Chinese font;
2--English font[Only for P90]
3--Russian font[Only for P90]
Other-- Version code
out_info[15]: Contactless IC card module version information

[Only for R50 and R50-M ]
0--No contactless IC card module ;
1-- Contactless IC card module version information;
out_info[16]: Magnetic card module version information [Only
for R50 and R50-M]
0--No magnetic card module ;
1--Magnetic card module version information;
out_info[17]: SAM card module version information [Only for
R50 and R50-M]
0--No SAM card module ;
1--SAM card module version information;
out_info[18]: Clock module version information [Only for R50
and R50-M]
0--No clock module ;
1--Clock module version information;
out_info[19]: LCD module version information [Only for R50
and R50-M]
0--No LCD module ;
1--LCD module version information;
out_info[20]:3G module version information
0--Not support 3G module;
1--WCDMA module;
2--TD-SCDMA module
3--CDMA2000 module
out_info[21]-[29]: Reserved
Return: The length of valid byte, which contains terminal information.
out_info [15-19] are version information only designed for R50 and R50-M,
Notes:
and also applicable to R30 and R100.
3.1.14 EnumFont
Prototype: int EnumFont (ST_FONT *Fonts, int MaxFontNums);
Function: Enumerate all fonts supported in POS
Fonts Buffer for storing fonts
Parameter: MaxFontNu
The maximum number of fonts in Fonts buffer
ms
Return: >=0 The actual number of fonts that read
It applies to P58.
Notes:
P78, P80 and P90 support this API while using S font.

3.1.15 ScrSelectFont
int ScrSelectFont(ST_FONT *SingleCodeFont, ST_FONT
Prototype:
*MultiCodeFont);
Function: Select display font on LCD
Single code font (for example, English, Russian, etc.),
SingleCodeFont
which can be set NULL
Parameter:
Multiple code font (for example, Chinese, Japanese, etc.),
MultiCodeFont
Specified single code font does is not exit. The select
-1
operation is fail.
Return: Specified multiple code font does is not exit. The select
-2
operation is fail.
0 Success
It applies to P58.
Notes:
3.1.16 PrnSelectFont
int PrnSelectFont(ST_FONT*SingleCodeFont,ST_FONT
Prototype:
*MultiCodeFont);
Function: Select printing font
Single code font (for example, English, Russian, etc.),
SingleCodeFont
Parameter:
Multiple code font (for example, Chinese, Japanese, etc.),
MultiCodeFont
Specified single code font does is not exit. The select
-1
operation is fail.
Return: Specified multiple code font does is not exit. The select
-2
operation is fail.
0 Success
It applies to P58.
Notes:
3.1.17 LedDisplay
Prototype: void LedDisplay(unsigned char type, unsigned char *str);
Function: LED display function
Display type:
0 - Disable display
Input
Type 1 - Display amount
Parameter:
2 - Display balance
other - Reserved

Display string, only support display the numbers "0~9",

Str characters "A~F", sign "-" and decimal point ".". Besides these,
other characters cannot be displayed.
Output
None
Parameter:
Return: None
Used to control the LED display.

Notes:
P80, R50, P78, P58 and R30 do not support this API!
3.2 Power Management Functions
All API of this module are only applicable for P90 and not applicable for P80, R50, P78, P58, R30
R50-M, and R100.
Module function description: this module is designed to achieve power management API
operations, which include entering low power consumption mode, reading system voltage level,
powering off, etc.
3.2.1 PowerSave
Prototype: uint PowerSave(uint Event, uint OverTime)
Function: Enter power-save mode mandatorily.
Event Condition of quitting power-save mode. It is valid if
corresponding bit equals to 1; it is invalid if corresponding bit
equals to 0.
When there is no pre-defined quit condition (for example,
Event=0), then the function will quit at once. When setting
Input several conditions and they have or relation, then quit the
Parameter: function if one condition satisfied.
For unset condition, backend will have no effect on them, and
will not quit this function.
OverTime This parameter is valid when setting timeout condition valid. It
indicates time (ms) of quitting power-save mode mandatorily,
and precision is 10ms.
Output None
Parameter:
Returns to condition causing quit of this function, and bits
Return: corresponding to every condition equal to 1 means the event
happens. Quitting conditions maybe not exclusive, refer to notes.
Application can enter power-save mode through calling this API, and then
does operation according to returned event. Timeout event is a supplement of
Notes:
other events, and its main purpose is to give control back to application when
there is no operation from operator. And it is convenient for application to deal

with timeout event.

Pay attention to that the function only monitors whether there happen
predefined events, it does not judge whether these events can happen. For
example, if COM1 port is not opened, although EVENT_UARTRECV is set,
it will not report error and no event received. The purpose is the independence
and simplicity of function. If the function does many judgments, then
application calling the function will become very complex. It is recommended
to make sure P90 is ready before setting conditions and waits for events
happen. It is advised to make other events parallel with timeout, thus the
function can quit surely.
The following example shows the simplicity of this function.
Set Event conditions and quit event. For Event input, every bit equaling
to means Enable and 0 means Disable. For return value, every bit
equaling to 1 means waken by this event and quit, and 0 means event
corresponding to the bit has not be detected when quit.
#define EVENT_OVERTIME 0X01
#define EVENT_KEYPRESS 0X02
#define EVENT_MAGSWIPED 0X04
#define EVENT_ICCIN 0X08
#define EVENT_UARTRECV 0X10
#define EVENT_WNETRECV 0X20
bit31~bit6 bit5 bit4 bit3 bit2 bit1 bit0
Reserved Wnet Port IC Swipe Key Timeout

received data card card press
data insert
Bit1 means there are key values not read or cleared in key buffer;
Bit2 means swiping card data has not been read or cleared;
Bit3 means IC card is in position (not insert);
Bit4 means there are data in port buffer not read;
Bit5 means there are data in Wnet buffer not dealt.
If certain event has not been dealt, then calling that function again will return
quickly. If user press certain key but application does not get that key value or
clears key buffer, then calling PowerSave (event, 1000) next time will return
within 10ms. Events include key-pressing event.
P80, R50, P78, P58, R30, R50-M, and R100 do not support this API!
For example: 10 seconds timing, quit when key pressed or time is up (compared with checking
timer example)
PowerSave (EVENT_KEYPRESS | EVENT_OVERTIME, 10000);
3.2.2 AutoPowerSave
Prototype: void AutoPowerSave(uchar mode)

Function: Set interactive function auto power-save.

mode 0 = close auto power-save
Input
1 = open auto power-save (default)
Parameter:
Output None
Parameter:
Return: None
Auto power-save function is auto power-save for 10ms when kbhit (),
MagSwiped (), IccDetect () cannot detect key pressed, card swiped and
inserted. Thats to say, these functions auto operation time is 10ms when
detecting no event.
If auto power-save function is closed, then these functions operation time is
about 1us, but cannot use these functions to save power.
In normal interface, operator cannot distinguish delay below 100ms, thus can
open auto power-save function. Operations like communication handshake
have higher time requirement, close auto power-save function at this time to
Notes:
ensure success communication.
It is recommended to set mode to be 1, only when there is strict requirement
for the operation time of events scan functions should mode set to be 0.
Notes: besides in above 3 functions, auto power-save exists in getkey(),
PortRecv(), Beef(), Beep(), DelayMs(), PEDGetPwd_3Des(), PEDGetPwd(),
PrnStart(), GetString(), and GetHzString(), etc. But because implementation of
these functions are compatible and will have no effect on operation result and
time, thus do not provide switch to choose.
P80, R50, P78, P58, R30, R50-M, and R100 do not support this API!
Example: After using auto power-save function, application performs power-save scan of
key-pressing.
while (1) {
if (kbhit () ==0) break;
}
3.2.3 BatteryCheck
Prototype: uchar BatteryCheck(void)
Function: Check battery voltage level
Input
None
Parameter:
Output
None
Parameter:
0 Battery icon twinkling means need charging immediately, with
buzzer prompt and may auto power off quickly.
Return: 1 Battery icon twinkling means need charging immediately. It is
recommended not do any transaction, printing or wireless
communication, and save important data. Prepare to prompt user

charging.
2 Battery icon shows 1 left.
6 Show there is external power supply and in charging process.
Battery icon circulates.
7 Show there is external power supply but charging is
complete.( Or there is only external power supply and no
battery)
Notes: P80, R50, P78, P58, R30, R50-M and R100 do not support this API!
3.2.4 Power Off

Prototype: void PowerOff(void)
Function: Power off
Input
None
Parameter:
Output
None
Parameter:
Return: None
Notes: P80, R50, P78, P58, R30, R50-M and R100 do not support this API!
3.3 Keyboard Functions
All API of this module are completely applicable for P90, partially applicable for P80, P78, R50
and P58, and not applicable for R30, R50-M and R100.
Module function description: this module is designed to achieve keypad API operations, which
include detecting key pressed, controlling press volume, explaining value of pressed key,
multi-functional keypad input function (R50 not applicable), etc.
3.3.1 kbhit
Prototype: uchar kbhit(void)
Function: Check whether there are untaken key values in keyboard buffer
Input None
Parameter:
Output None
Parameter:
0xFF No key pressed
Return:
0x00 Keys pressed (Use getkey() to read it)
Notes: Keyboard has a 32-bytes buffer. Key values can be read by getkey ().

R30, R50-M and R100 do not support this API!
3.3.2 kbflush
Prototype: void kbflush()
Function: Clear all the unread key values in the keyboard buffer.
Input None
Parameter:
Output None
Parameter:
Return: None
Notes: R30, R50-M and R100 do not support this API!
3.3.3 getkey
Prototype: uchar getkey(void)
Get the first key value in keyboard buffer. The read key value will be deleted
Function:
from keyboard buffer. If the buffer is empty, wait until a key is pressed.
Input None
Parameter:
Output None
Parameter:
Key value read. The keyboard has a 32-bytes buffer. New key
Return:
values will be abandoned when the buffer is full.
Following is the key value definition for P80, P78 and P90 (also available in
posapi.h):
Function Keys [No KEYF1~ KEYF6 for P90]:
KEYF1 0x01
KEYF2 0x02
KEYF3 0x03
KEYF4 0x04
KEYF5 0x09
KEYF6 0x0A
Notes:
No feed key for P58
1: KEY1 0x31
2: KEY2 0x32
3: KEY3 0x33
4: KEY4 0x34
5: KEY5 0x35
6: KEY6 0x36
7: KEY7 0x37
8: KEY8 0x38
9: KEY9 0x39

0: KEY0 0x30
Function: KEYFN 0x15

Menu: KEYMENU 0x14
Alpha: KEYALPHA 0x07
: KEYUP 0x05
: KEYDOWN 0x06
Cancel: KEYCANCEL 0x1B
Clear: KEYCLEAR 0x08
Enter: KEYENTER 0x0D
Feed: KEYPRNUP 0x19
(This key always has no return value. Its only valid when setting feed key as a
normal key.)
Following is the key value definition for R50 (also available in posapi.h):
Function Keys: KEYF1 0x01
KEYF2 0x02
KEYF3 0x03
KEYF4 0x04
3.3.4 kbmute
Prototype: void kbmute(uchar flag)
Function: Set whether a beep should be made when a key is pressed
Input flag 0 no beep
Parameter: None-zero beep
Output None
Parameter:
Return: None
3.3.5 kbsound
Prototype: void kbsound(uchar mode, short dlytime)
Switches off the keyboard buzzer or make it beep at specified frequency and
Function:
last for specified time when pressing keys.
Mode: mode 0 Switch off beep (dlytime can be any value)
selection, 0~7 1 The lowest frequency
7 The highest frequency
Input
dlytime: 0xffff Beep when the key is pressed and lasting until it is
Parameter:
lasting time released.
(unit: ms) 0x0000 No beep
(0~65535)

Output None
Parameter:
Return: None
When mode is larger than 7, mode%8 will be used.

Notes:
3.3.6 GetString
Prototype: uchar GetString(uchar *str, uchar mode, uchar minlen, uchar maxlen)
Multifunctional string inputting, with cursor. In number and character input
Function: modes, if str contains valid contents and bit7 is set to 1, they will be displayed
for users editing.
Mode: bit7 1(0) bit7: 1(0) Can (cannot) quit by enter
input mode bit6 1(0) big (small) font
(priority bit5 1(0) Can (cannot) input numbers
sequence: bit4 1(0) Can (cannot) input characters
bit3>bit4>bit5, bit3 1(0) Is (is not) password mode
and mode & bit2 1(0) Left (right) alignment
Input
0x38 should bit1 1(0) Having (not having) radix point
Parameter:
not be 0) bit0 1(0) Normal (reverse) display
Minlen Minimum length of the input string.
Maxlen Maximum length of the input string (128 bytes at most).
str[0] Length of the input string.

str+1 Address of the input string
Output None
Parameter:
0x00 Succeed
0xFE Invalid parameters (including invalid mode, minlen>maxlen,
Return: maxlen=0)
0xFF Operation canceled by user (CANCEL key pressed)
0x0D User quit with enter(ENTER key pressed)
Input STR should not include 0X0A, 0X0D etc non displayable or control
characters. Otherwise the display will be un-readable.
Notes:
The PEDINPUTTIMEOUT API setting will be shared with this API.
R50, R30, R50-M and R100 do not support this API!
Example 1: Input sales amount (display in large font, minimum characters 0, maximum
characters 10):
unsigned char buf [20];
unsigned long amt;
if (! GetString (buf, 0x26, 0, 10)) // correct input, amt is the input amount
{

buf [buf [0] +1] =0;

amt=atol (buf+1);
}
else
{
// user pressed CANCEL key
}
Example 2: Input teller logon password (displayed in large font, minimum characters 4,
maximum characters 6):
unsigned char pwd [10]; // correct teller password string ending with \0
unsigned char buf [10];
if (! GetString (buf, 0X68, 4, 6))

{
buf [buf [0] +1] =0;
if (! strcmp (pwd, buf))
{
// correct password
}
else
{
// wrong password
}
}
else
{
// user pressed CANCEL key
}
3.3.7 GetHzString
Prototype: uchar GetHzString(uchar *outstr, uchar max, ushort TimeOut)
Function: API provides input Chinese word, English word and numbers.
max Maximum input length (maximum value is 128)
Input
Parameter: Timeout Time out setting (=0 implies no timeout, in second)
Output Outstr Return string ended with \0.
Parameter:
0x00 Succeed
0XFD Timeout
Return:
0xFE Invalid parameter value
0xFF User cancel (CANCEL key pressed)

Instructions:
Switching input scheme: pressing FN key can switch among
Pinyin Chinese characters, capital letter, lowercase letter.
Inputting Chinese: under the mode of Pinyin Chinese
characters, press corresponding numeric keys. For example,
inputting , press 14664, and then press ENTER to select
.
Input capital letter and number: under the mode of capital
letter, press numeric keys where letter locates, and press the
Notes:
same numeric key again within 0.8 second. The next available
character will be shown. For instance, press 1 two times, the
character of Q will be shown.
Input lowercase letter and number: under the mode of
lowercase letter, press numeric keys where letter locates, and
press the same numeric key again within 0.8 second. The next
available character will be shown. For instance, press 1 three
times, the character of z will be shown.
R50, R30, R50-M and R100 do not support this API!
3.3.8 kblight
Prototype: void kblight(uchar mode)
Set keypad backlight(turn on automatically when key pressed, card swiped or
Function:
inserted)
mode 0 = turn off backlight temporarily, and turn on when key pressed,
card swiped or inserted( has the same effect with mode 1)
1 = backlight keeps on 1 minute(1 minute later, turns off
Input automatically)
Parameter: 2 = backlight is always on
3= backlight is always off, even if key pressed, card swiped or
inserted
Other values no action.
Output None
Parameter:
Return: None
System defaults to mode=1.
Notes:
P80, P78, R50, P58, R30, R50-M and R100 do not support this API!
3.3.9 SetLightTime
Prototype: void SetLightTime(ushort LightTime)
Function: Set light-time of LCD backlight and keypad backlight.
Input Backlight light-time in seconds, default value is 60 seconds. It is
LightTime
Parameter: invalid when setting to 0, and will keep its original value.

Output
None
Parameter:
Return: None
The value set by the function has effect on timing mode. Time set is valid for
Notes: LCD backlight and keypad backlight.
3.3.10 SetSlipFW
Prototype: void SetSlipFW(unsigned char mode)
Function: Set feeding paper key function
mode 0 = close feeding paper function, when it is pressed down, it is
looked as normal key.
Input
1 =open feeding paper function, paper begins to feed when it is
Parameter:
pressed and no value returned. Kbhit and getkey functions
cannot get key value.(default)
Output None
Parameter:
Return: None
It is recommended to set mode to be 1 in normal use, and 0 when application
Notes: locks the keypad, and mode will become 1 when keypad is unlocked.
3.4 LCD Functions
All API of this module are completely applicable for P58, partially applicable for P90, P80, R50
and P78, and not applicable for R30, R50-M and R100.
Module function description: this module is designed to achieve LCD screen API operations, which
include clearing screen, displaying font, positioning cursor, displaying a dot, drawing box, showing
characterized message on screen, etc.
The LCD display contains 128 x 64 dot-matrixes. The screen is divided into 8 lines (each line takes 8
pixels vertically). Thus the screen can hold 4 x 16 characters in large font (8 x 16 pixels in size), 4 x
8 Chinese characters (16 x 16 pixels in size) or 8 x 21 characters in small font (6 x 8 dots in size).
Each large-font character or Chinese character takes 2 lines vertically; while each small-font
character takes only 1 line.
Hardware or software font library used P80 V1.0 font library [also can use P60V4.0 or P70V1.0
hardware font library] the first 512 bytes of font library are the parameters which contained the font
library version, language type, font size, encoding format etc. Font library is stored in FLASH.
Font format:
small ASCII code (5 x 7), large ASCII code (8 x 16);
Extended single byte code: small size (8 x 8), large size (8 x 16);
Extended double bytes code: selectable font 12 x 12 / 14 x 14 / 16 x 16.

3.4.1 ScrCls
Prototype: void ScrCls(void)
Function: Clears the whole screen
Input None
Parameter:
Output None
Parameter:
Return: None
The cursor will be positioned at the top left corner (0, 0) in the screen.
Notes:
3.4.2 ScrClrLine
Prototype: void ScrClrLine(uchar startline, uchar endline)
Function: Clear one or more specified lines, no action if parameters are invalid
Input startline starting line number (0~7)
Parameter: Endline ending line number (0~7)
Output None
Parameter:
Return: None
The cursor will be positioned at (0, start line) after this function called
startline = 0, endline = 0 clears line 0;
startline = 1, endline = 5 clears line 1 to 5;
Notes: startline = 0, endline = 9 clears line 0 to 7;
if startline>endline or both start line and end line are invalid, nothing will be
cleared.
3.4.3 ScrGray
Prototype: void ScrGray(uchar mode)
Function: Set up the screen contrast
Input mode Contrast level [0~7, 0 darkest, 7 lightest], default to 4. Other
Parameter: values no action.
Output None
Parameter:
Return: None
3.4.4 ScrBackLight
Prototype: void ScrBackLight(uchar mode)
Function: Set up screen backlight(turn on automatically when key-pressing,

card-swiping and card-inserting)

Mode 0 =Turn off backlight temporarily, and turn on when pressing
keys, swiping card of inserting card (the result is the same with
Input
mode 1).
Parameter:
1 = Keep backlight on for 1 minute ( auto-shut-down after 1
minute)
2 = Always on
Other values no action
Output None
Parameter:
Return: None
Default value is mode equal to 1 (mode=1).
Notes:
3.4.5 ScrGotoxy
Prototype: void ScrGotoxy (uchar x,uchar y)
Function: Move cursor to specified position
Input x Horizontal coordinate (0 <= x <= 127)
Parameter: y Vertical coordinate (0 <= y <= 7)
Output None
Parameter:
Return: None
If x or y is out of scope, the corresponding modular result will be used instead.
Notes:
3.4.6 ScrFontSet
Prototype: uchar ScrFontSet(uchar fontsize)
Function: Set up display font
fontsize Font size to be used
0 ASCII mode, ASCII characters in 5 x 7size;
Nonzero CFONT Chinese mode, Chinese character in 16 x 16
Input
sizes, ASCII characters in 8 x 16 sizes.
Parameter:
Other values no action.
Note: P78, P90 only support values 0 and 1, other values are
illegal, and it will directly return.
Output None
Parameter:
Return: Display font before setting
System default font is CFONT, which is Chinese mode.

Notes:

3.4.7 ScrAttrSet
Prototype: uchar ScrAttrSet(uchar Attr)
Function: Set display attribute, plain or reverse
attr attribute value
Input
0 : plain display;
Parameter:
None 0: reverse display
Output None
Parameter:
Return: Display attribute before setting
System attributes defaults to 0, plain display.

Notes:
3.4.8 Lcdprintf
Prototype: int Lcdprintf (const char *fmt...)
Displays formatted string at current cursor position(the same with printf
Function:
function of P70 and P60)
Input None
Parameter:
Output fmt String and format to be displayed
Parameter:
Return: None
This is an ANSI C standard output function, with the following limit:
It supports only one control character \n; others will be displayed as
characters.
If the string cannot be displayed in one line, the display will continue in
the next line.
Notes:
If % will be displayed, it is required to show two %s, which is %%.
All P80P78P90R50 and P58 applications are required to use this API
to replace all the printf() API for LCD display. Otherwise, the application
will be abnormal.
Example: Displaying characters in large, small fonts and Chinese characters.
ScrCls ();
ScrFontSet (ASCII);
Lcdprintf (Pax Technology Ltd.);
ScrGotoxy (0, 2);
ScrFontSet (CFONT);
Lcdprintf (PAX TECHONLOGY CO. LTD \nAugust 2001\n);
getkey ();
3.4.9 ScrPrint
Prototype: void ScrPrint (uchar col, uchar row, char mode, char *str,...)

Function: Displays formatted string at cursor position

col Horizontal coordinate of the starting point(0~127)
Input Row Vertical coordinate (line number) of the starting point(0~7)
Parameter: Mode Font (ASCII[0x00]CFONT[0x01]) and attribute (REVER[0x80]
REVERSE)
Output str Display output string and format
Parameter:
Return: None
While the Mode takes an illegal values, but it still displays normally and big
in the P font.
The specified font, attribute and coordinates are valid only in this function. If
Notes:
%is displayed, then use two %, that is %%. If the value of mode is invalid,
then the default value will be used.
3.4.10 ScrPlot
Prototype: void ScrPlot(uchar X, uchar Y, uchar Color)
Function: Displays a dot at specified position.
X Specified horizontal coordinate in pixel,(0~127)
Input
Y Specified vertical coordinate in pixel, (0~63)
Parameter:
Color Specified action, 1: draw a dot; 0: erase a dot.
Output None
Parameter:
Return: None
No action if coordinates is invalid.
Notes: Color: draw a dot if is none-zero.
3.4.11 ScrDrLogo
Prototype: void ScrDrLogo(uchar *logo)
Function: Put specified bitmap data into display buffer, usually used to display a logo.
Input logo Pointer to the RAM data sent into display buffer
Parameter:
Output None
Parameter:
Return: None
Generating bitmap data:
Draw a logo: use Windows application Start / Programs / Accessories /
Paintbrush to draw a logo and save the file as Monochromatic, bmp
Notes:
format;
Logo size limit: 128 x 64 pixels at most;
Conversion: Use Bitmap Conversion Tool provided by PAX to convert

teh .bmp file into a header file like logo.h (which contains only an array).
Use the generated array as input parameter of this function;
If the bitmap cannot be displayed within one screen, it will be truncated;
Use ScrGotoxy() to set display position before displaying logo;
Bitmap data structure in the header file:
First byte [1Byte]:lines of the bitmap[8 at most];
Size of the first line in bitmap [2Bytes, high byte first];
Bitmap data of the first bitmap line [ height of one bitmap line is 8 pixels];
(Refer to the following description for corresponding relation with screen)
Size of the second line in bitmap[2 Bytes, high byte first];
Bitmap data of the second bitmap line;
Etc...
The relation between bitmap data and screen coordinates:

Assume (x, y) is current cursor position, buff[n] is bitmap data to be
displayed, 0 <= m < n, so:
buff[m].0 - buff[m].7 correspond to (x+m,y) - (x+m,y+7) on screen.
buff[m].0 is the lowest bit of buff[m] and buff[m].7 is the highest bit of
buff[m].
A pixel will be displayed if the corresponding bit is 1; otherwise the pixel will
be erased.
3.4.12 ScrDrLogoxy
Prototype: void ScrDrLogoxy(char x,char y,uchar *logo)
Display the logo in the specified xy co-ordinate. [Automatically trim the
Function:
bitmap to fit the display which can be used to display antimation.]
x Specified x co-ordinate (-128 ~ 127)
Input
y Specified y co-ordinate (-64 ~ 63)
Parameter:
logo Buffer point to the RAM data sent into display buffer
Output None
Parameter:
Return: None
Since the xy co-ordinate can be negative value, specified to display
certain portion of the bitmap easily without updating the bitmaps
content.
Notes: For instance, to display the bottom right hand (32X16 large) portion of a
bitmap (64X32 large) on the top left hand side of the display, the
parameter for x and y should be -32 and -16.

3.4.13 ScrRestore
Prototype: uchar ScrRestore(uchar mode)
Function: Store the current screen buffer or restore the previous stored screen buffer.
Input mode 0: store;
Parameter: >=1: recover
Output None
Parameter:
0x00 Success
Return:
Others Fail (For instance, there is no previous stored screen buffer).
Icon display is not reserved or resumed.
Notes:
R30, R50-M and R100do not support this API!
3.4.14 ScrSetIcon
Prototype: void ScrSetIcon(uchar icon_no,uchar mode)
Function: Display icons on screen
icon no Specified icon number, as following:
#define ICON_PHONE 1 // phone
#define ICON_SIGNAL 2 // wireless signal
#define ICON_PRINTER 3 // printer
icon_no #define ICON_ICCARD 4 // smart card
#define ICON_LOCK 5 // lock
#define ICON_SPEAKER 6 // speaker
#define ICON_UP 7 // up
#define ICON_DOWN 8 // down
mode Assigned action, 1 -- on, 0 -- off
Input
#define CLOSEICON 0 // switch off icons (for all)
Parameter:
#define OPENICON 1 // switch on icons (for printer
// IC card, lock, battery, up //and
down)
Action value should be set as follows to switch on hook- on and
hook-off icon:
#define OFFHOOKICON 1 // hook off
#define ONHOOKICON 2 // hook on
Set action to INITSIGNAL+[0,5] to switch on signal icon
#define INITSIGNAL 1 // initial signal [highest
INITSIGNAL + 5]
Output None
Parameter:
0x00 Success
Return:
Other Fail (For instance, there is no previous stored screen buffer).
There are 8 icons on LCD: phone, signal, printer, IC card, lock, speaker,
Notes:
up, down, indexed to 1~8.

No action if icon number invalid.

[It is recommended to uses signal, up and down icons only, at the application
level.]
(ICON_SPEAKER is a battery option in P58 and P90,but for macroinstruction
is still ICON_SPEAKER )
Example: Switching on down icon:
ScrSetIcon (ICON_DOWN, OPENICON);
Switching off down icon:
ScrSetIcon (ICON_DOWN, CLOSEICON);
Switching on hook-off icon:
ScrSetIcon (ICON_PHONE, OFFHOOKICON);
Switching off hook-off icon:
ScrSetIcon (ICON_PHONE, CLOSEICON);
Switching on signal icon [highest signal]:
ScrSetIcon (ICON_ SIGNAL, INITSIGNAL +5);
Switching off signal icon:
ScrSetIcon (ICON_ SIGNAL, CLOSEICON);
3.4.15 ScrDrawBox
void ScrDrawBox(unsigned char y1,unsigned char x1,unsigned char
Prototype:
y2,unsigned char x2)
Function: Draw box at specific position.
y1 Staring dot vertical coordinate, range: 0~7.
Input x1 Starting dot horizontal coordinate, range: 0~21.
Parameter: y2 Ending dot vertical coordinate, range: 0~7.
x2 Ending dot horizontal coordinate, range: 0~21.
Output None
Parameter:
Return: None
The box is correspondent with 128*64 pixel, horizontal line starting dot is
x1*6+1 and ending dot is x2*6-1, while vertical line starting dot is y1*8+4
Notes: and ending dot is y2*8-4.
x2-x1 must be no less than 5, y2-y1 must be no less than 2.
P78, R30, R50-M and R100 do not support this API!
3.4.16 ScrGotoxyEx
Prototype: void ScrGotoxyEx (int pixel_X, int pixel_Y)
Function: Allocate LCD cursor
pixel_X>=0: horizontal coordinate ,unit in pixel.[0 - 127]
Parameter:
pixel_Y>=0:vertical coordinate ,unit in pixel.[0 - 63]
Return: None

If parameters are invalid, the coordinate value of current cursor will not be
Notes: changed.
Only support P58!
3.4.17 ScrGetxyEx
Prototype: void ScrGetxyEx(int *pixel_X, int *pixel_Y);
Function: Obtain current coordinates of cursor
pixel_X the pixel value of Current X-coordinate of cursor
Parameter:
pixel_Y the pixel value of Current Y-coordinate of cursor
Return: None
It applies to P58.
Notes:
3.4.18 ScrDrawRect
Prototype: void ScrDrawRect(int left, int top, int right, int bottom);
Function: Draw a rectangle
Unit of coordinate parameter: pixel
left:
Parameter: Top:
right:
bottom:
Return: None
It applies to P58.
Notes:
3.4.19 ScrClrRect
Prototype: void ScrClrRect(int left, int top, int right, int bottom);
Function: Clear the display information in rectangle area.
Unit of coordinate parameter: pixel
left:
Parameter: Top:
right:
bottom:
Return: None
It applies to P58.
Notes:
3.4.20 ScrSpaceSet
Prototype: void ScrSpaceSet(int CharSpace, int LineSpace);
Function: Setting display line spacing and char spacing

CharSpace :char spacing(Unit: pixel)

Parameter:
LineSpace :line spacing(Unit: pixel)
Return: None
It applies to P58.
Notes:
3.4.21 ScrGetLcdSize
Prototype: void ScrGetLcdSize(int *width, int *height);
Function: Get size of LCD display screen
Width: maximum display width
Parameter:
Height: maximum display height
Return: None
It applies to P58.
Notes:
3.4.22 ScrTextOut
Prototype: void ScrTextOut(int pixel_X, int pixel_Y, unsigned char *txt);
Function: Output string in specified position
Pixel_X the value of X-coordinate[0-127]
Parameter: Pixel_Ythe value of Y-coordinate[0-63]
Txt The display string
Return: None
It applies to P58.
Notes: For P78, P80 and P90, the coordinates support negative in S font.
X:-127~127 Y:-63~63
If parameter is illegal, the function will return without any action.
3.5 Magnetic Stripe Card Reader Functions
All API of this module are completely applicable for P80, P78, P90 and P58, and not applicable for
R50, R30, R50-M and R100.
Module function description: this module is designed to achieve magnetic stripe card reader API,
and explain interaction between terminal and magnetic stripe card.
Internal module data structure:
typedef struct {
unsigned char RetCode; /* Processing result of Application */
unsigned char track1 [256]; /* Magnetic Track 1 buffer */
} ST_MAGCARD;

3.5.1 MagOpen
Prototype: void MagOpen(void)
Function: Switch on magnetic stripe card reader.
Input None
Parameter:
Output None
Parameter:
Return: None
Magnetic stripe card reader works in interrupt mode. When the magnetic card
reader is on, even if no card-reading function is called, it can still read
Notes: magnetic track data. So it is better to shut down magnetic stripe card reader
when it is not used.
R50, R30, R50-M and R100 do not support this API.
3.5.2 MagClose
Prototype: void MagClose(void)
Function: Switch off magnetic stripe card reader
Input None
Parameter:
Output None
Parameter:
Return: None
Notes: R50, R30, R50-M and R100 do not support this API.
3.5.3 MagReset
Prototype: void MagReset(void)
Function: Reset magnetic stripe card reader, and clears magnetic stripe card buffer
Input None
Parameter:
Output None
Parameter:
Return: None
If magnetic reader is powered on, this function will reset magnetic reader and
clear data within magnetic stripe card buffer; if magnetic reader is not
powered on, it will only clear data within magnetic stripe card buffer. In order
to ensure that data read by magnetic reader are updated data, it is
Notes:
recommended to call this function before continuously check the event of
swiping card, and the purpose is to completely clear all data in magnetic stripe
card buffer.
Example:

unsigned char ucRet, Track2 [80], Track3 [120];
MagOpen ();
ScrGotoxy (0, 6);
printf (Pls swipe card >>>);
MagReset ();
while (MagSwiped ()! =0)
{
if (kbhit () ==0)
{
if (getkey () ==KEYCANCEL)
{
MagClose ();
return USER_CANCEL; // user cancel
}
}
}
3.5.4 MagSwiped
Prototype: uchar MagSwiped(void)
Function: Check whether the card is swiped
Input None
Parameter:
Output None
Parameter:
0x00 Card swiped
Return:
0xff No swiping
This function returns immediately no matter card swiped or not.
Notes:
3.5.5 MagRead
Prototype: uchar MagRead(uchar *Track1, uchar *Track2, uchar *Track3)
Function: Read data of track 1, 2, 3 from magnetic stripe card buffer.
Input None
Parameter:
*Track1 pointer to data of track 1 [buffer size should be 256]
Output
Parameter:
Return: 0x00 Card read error

Others bit0 = 1 Track 1 read correctly

bit1 = 1 Track 2 read correctly
bit2 = 1 Track 3 read correctly
bit4 = 1 Check error in track 1
Also errno variable can be obtained by GetLastError () to determine
whether it is word check error or packet check error. Details as following:
bit0 of errno implies word check error in track 1
bit3 of errno implies packet check error in track 1
bit4 of errno implies packet check error in track 2
Notes: bit5 of errno implies packet check error in track 3
This function works together with MagSwiped function. If a certain tracks
data is not needed, set the corresponding pointer to NULL.
For magcard conforming to ISO7812:
track1 needs 79 bytes
track2 needs 40 bytes
track3 needs 107 bytes.
3.6 IC Card Functions
All API of this module are completely applicable for P80, P90, P78, R50, P58, R50-M and R100,
and not applicable for R30.
Module function description: this module is designed to achieve IC card reader API, and explain
interaction between terminal and IC card.
SEND data structure: APDU_SEND.
typedef struct {
unsigned char Command [4]; /* CLA, INS, P1, P2 */
unsigned short Lc; /* Length of data that send to IC card */
unsigned char DataIn [512]; /* Data that send to IC card */
unsigned short Le; /* Length of data that will return */
} APDU_SEND;
RECEIVE data structure: APDU_RESP.

typedef struct {
unsigned short LenOut; /* Actual length of data that return from IC card */
unsigned char DataOut [512]; /* Pointer of data that will return from IC card*/
unsigned char SWA; /* IC card status 1 */
unsigned char SWB; /* IC card status 2 */
} APDU_RESP;

3.6.1 IccInit
Prototype: uchar IccInit(uchar slot, uchar *ATR)
Function: Reset IC card and return resetting answer content of the card.
slot slot - card channel number should be initialized
EMV contact card : 0x00-0x05
Input
ISO contact card: 0x80-0x85
Parameter:
Department of Construction City Card: 0x40-0x45
Support PPS protocol: slot = slot | 0x20
ATR Answer To Reset information of the card. (32 + 1 bytes at most in
Output
size)
Parameter:
Its content is length(1 byte) +reset answer content
0x00 Successful initialization
0x02 Card removed
Return: 0x04 Channel number error
0x06 Protocol error
Others Communication failure
If IC card support PSS protocol, communication speed between terminal
and IC card will be greatly improved by the protocol.
The size of ATR of different IC cards is different. Please refer to related
card materials to allocate enough space (33 bytes at most).
IC card slot channel descriptions:
0: half-inserted full-size card slot (user card)
1: full-inserted full-size card slot (merchant card)[P90 , R50 and R50-M
do not have this slot]
2-5: SAM card slots [P90 has slot 2 and 3; R50 has slot 2,3 and 4]
Note:
1) For different types of machines, the number and type of the card slot
may have the differences. For specific card slot number, please refer to
the operation manual of the model that used or consult a professional.
Notes: 2) It is according to the specific card type to determine whether PPS
protocol is supported or not.
3) For the operation of SAM card, the terminal can only guarantee that
only one card is valid at a time. For operating more than one SAM card,
the card must be initialized one after another, meanwhile, according to
the following initializing process: Initialization (IccInit) -Operation
(IccIsoCommand) - IccClose (IccClose).
For example, the SAM card with 2 channel and 3 channel, the procedure is as
follows
IccInit( 0x82 );
IccIsoCommand( 0x82, ... );
IccClose( 0x82 );
...
IccInit( 0x83 );

IccIsoCommand( 0x83, ... );

IccClose( 0x83 );
IC card will accept commands only after completed IccInit.

Detailed IC card command operations return code are as follows. For
card reset, detailed error codes of T=0 command exchange and T=1 card
command exchange can be dealt as 0XFF error code (communication
failure).
0x00 Succeed
0x01 Odd/even error
0x02 No card
0x03 Other error
0x04 Card channel error
0x05 Data length error
0x06 Protocol error
0x07 Not initialized
0xFF Communication error
Card reset detailed error code

0x31 TS error
0x32 Reset verify (TCK) error
0x33 Reset wait timeout
0x34 TA1 error
0x35 TA2 error
0x36 TA3 error
0x37 TB1 error
0x38 TB2 error
0x39 TB3 error
0x3A TC1 error
0x3B TC2 error
0x3C TC3 error
0x3D TD1 error
0x3E TD2 error
0x3F ATR data length error
T=0 card communication error detailed code

0x41 Wait card response timeout
0x42 Re-send error
0x43 Re-receive error
0x44 Character odd/even error
0x45 Status byte is invalid

T=1 card communication error detailed code

0x11 BWT error
0x12 CWT error
0x13 ABORT communication error
0x14 EDC error
0x15 Sync. communication error
0x16 EGT error
0x17 BGT error
0x18 NAD error
0x19 PCB error
0x1A LEN error
0x1B IFSC error
0x1C IFSD error
0x1D Re-receive/re-send error character group error
0x1E Character odd/even error
0x1F Invalid character group
3.6.2 IccClose
Prototype: void IccClose(uchar slot)
Close specified contact IC card (or SAM card) slot, and switch off IC card
Function:
power.
slot slot card channel
EMV contact card: 0x00-0x05
Input
Parameter:
Support PPS protocol: 0x20-0x25
Output None
Parameter:
Return: 0x00 Card swiped
Other invalid values no action.
Notes:
3.6.3 IccAutoResp
Prototype: void IccAutoResp(uchar slot, char autoresp)
Set up whether IccIsoCommand () sends GetRespond instruction
Function:
automatically.


Input ISO contact card: 0x80-0x85
Parameter: Department of Construction City Card: 0x40-0x45
autoresp flag: 1 = auto-send ; 0 = do not send
Output None
Parameter:
Return: None
The system defaults to auto-send GET RESPONSE instruction.
Notes:
3.6.4 IccIsoCommand
uchar IccIsoCommand(uchar slot, APDU_SEND *ApduSend,
Prototype:
APDU_RESP *ApduRecv)
IC card operation function. This function supports IC card universal interface
Function:
protocol (T=0 and T=1)
slot slot card channel:
Input
Parameter:
Output None
Parameter:
0x00 Succeed
0x01 Communication timeout
0x02 Card removed during transaction
0x03 Parity error
Return: 0x04 Slot selection error
0x05 Data sent too long ( LC )
0x06 Card protocol error (not T=0 or T=1)
0x07 Card reset fail
0xff Cannot establish communication or no power.
APDU_SEND structure:
struct{
unsigned char Command[4];
unsigned int Lc;
unsigned char DataIn[512];
Notes:
unsigned int Le;
};
Command [] = {CLA, INS, P1, P2}.
Lc = length DataIn
DataIn = pointer of data to be sent to IC card

Le = length of expected return data
APDU_RESP structure:
struct{
unsigned int LenOut;
unsigned char DataOut[512];
unsigned char SWA;
unsigned char SWB;
};
LenOut = Actual length of the returned data from IC card
DataOut = Pointer to the returned data from IC card
SWA = Status byte 1
SWB = Status byte 2
3.6.5 IccDetect
Prototype: uchar IccDetect(uchar slot)
Check whether card is inserted in specified slot. In-place check will take place
Function:
for No.0-1 slot. Power-on and resetting will take place for No. 2-5 slots.
EMV contact card: 0x00
Input
ISO contact card: 0x80
Parameter:
Department of Construction City Card: 0x40
Support PPS protocol: 0x20
Output None
Parameter:
0x00 Card-inserted
Return:
0xff No card
Regardless card inserted in slot or not, this interface returns immediately.
Calling this interface to determine whether there is inserted card even or not.
Notes:
Note: this interface only support user card state detection.
3.7 Contactless RF Card Functions
All API of this module are completely applicable for R50, R30, R50-M and R100; partially
applicable for P80 (PiccLight function and related functions not applicable); not applicable for P78,
P90 and P58.
Module function description: this module is designed to achieve contactless RF card reader API,
and explain interaction between terminal and contactless RF card.
typedef struct

{
uchar drv_ver [5]; // The version information of Drivers, for example: 1.01A can only
be read.
uchar drv_date [12]; // The date information of driver, for example:2006.08.25; Read only.
uchar a_conduct_w; // The output conductance of A card is write enable
//1 allow, others do not allow
uchar a_conduct_val; // The A card control variable of output conductance, valid range is
//between 0-63. If variable is bigger than 63, it will be considered as 63. Default values will
//be 63. If a_conduct_w=1, it will be valid; if a_conduct_w is not equal to 1, it will not
//change output power of Type A card. Therefore, it can adjust the maximum sensing
//distance.
uchar m_conduct_w; // The output conductance of M1 card is write enable
uchar m_conduct_val; // The M1 card control variable of output conductance, valid range is
//be 1. If m_conduct_w=1, it will be valid; if m_conduct_w is not equal to 1, it will not
//change output power of M1 card. Therefore, it can adjust the maximum sensing distance.
uchar b_modulate_w; // The modulation index of B card is written enable
///1 allow, others do not allow
uchar b_modulate_val; // The B card control variable of modulation index, valid range is
//be 4. If b_conduct_w=1, it will be valid; if b_conduct_w is not equal to 1, it will not //change
the modulation index, which is used for driving type B card. Therefore, it can adjust //the
maximum sensing distance.
uchar wait_retry_limit_w; // Written enable for S (WTX) response to sending times
// 1 allow, others do not allow (only applicable to P80)
ushort wait_retry_limit_val; // The most repeat times of S (WTX) response
//the default value is 3;
uchar card_buffer_w; // Receiving buffer of card is written enable:
ushort card_buffer_val; // Receiving buffer parameter of card (Unit: byte). Valid range is
//between 1-256. When over 256, it will use 256; if it is 0, it will not be written in.
//Card receiving buffer size determines whether terminal will be required to send divided
//packet, and decide the maximum size of packet, when terminal sends a command string to
//card. If the size of awaiting command string is bigger than the size of card receiving buffer, it
//is needed to divide packet into smaller ones, and send one by one.
//During the process of executing PiccDetect ( ), parameters of card receiving buffer size will
//be reported to terminal by card. Therefore, the value is not needed to be changed. For non
//standard card, it maybe require to re-set the value of parameter, in order to ensure effective
//transmission.
uchar card_type_check_w; // Card type check is allow to write
//1 allow, others do not allow. The value is unreadable
uchar card_type_check_val; // 0--Check card type, other--do not check card type;
//The default value is 0

uchar card_RxThreshold_w; // Receiver sensitivity of the card is allow to write

//1 allow, others do not allow. The value is unreadable.
uchar card_RxThreshold_val; // Receiver sensitivity of the card
uchar f_modulate_w; // Felica modulation depth allow to write
//1 allow, others do not allow. The value is unreadable
uchar f_modulate_val; //felica modulation depth
uchar reserved[88]; // Reserved byte, for future expansion. All clear when writing.
} PICC_PARA;
typedef struct
{
unsigned char drv_ver [5]; // The version information of Driver, for example: 1.01A can
only be read.
unsigned char drv_date [12]; // The date information of driver, for example:2006.08.25;
Read only.
unsigned char a_conduct_w; // The output conductance of A card is write enable:
unsigned char a_conduct_val; // The A card control variable of output conductance, valid
range is between 0-63. If variable is bigger than 63, it will be considered as 63.
// If a_conduct_w=1, it will be valid; if a_conduct_w is not equal to 1, it will not change
output power of Type A card. Therefore, it can adjust the maximum sensing distance.
unsigned char m_conduct_w; // The output conductance of M1 card is write enable:
unsigned char m_conduct_val; // The M1 card control variable of output conductance, valid
// If m_conduct_w=1, it will be valid; if m_conduct_w is not equal to 1, it will not change
output power of M1 card. Therefore, it can adjust the maximum sensing distance.
unsigned char b_modulate_w; // The modulation index of B card is written enable
unsigned char b_modulate_val; // The B card control variable of modulation index valid
range is //between 0-63. If variable is bigger than 63, it will be considered as 63.
// If b_conduct_w=1, it will be valid; if b_conduct_w is not equal to 1, it will not change the
modulation index, which is used for driving type B card. Therefore, it can adjust the maximum
sensing distance.
unsigned char card_buffer_w; // Receiving buffer of card is written enable:
unsigned short card_buffer_val; // Receiving buffer parameter of card (Unit: byte). Valid
range is between 1-256.
//If value is bigger than 256, it will write as 256; if value is 0, it will not write.
//Card receiving buffer size determines whether terminal will be required to send divided
packet, and decide the maximum size of packet, when terminal sends a command string to
card. If the size of awaiting command string is bigger than the size of card receiving buffer, it
is needed to divide packet into smaller ones, and send one by one.
// During the process of executing PiccDetect ( ), parameters of card receiving buffer size will
be reported to terminal by card. Therefore, the value is not needed to be changed. For

non-standard card, it maybe require to re-set the value of parameter, in order to ensure
effective transmission.
unsigned char wait_retry_limit_w; // Written enable for S (WTX) response to sending times
// 1 allow, others do not allow (Be not allowed temporarily)
unsigned short wait_retry_limit_val; // The most repeat times of S (WTX) response the
default value is 3(Be not allowed temporarily);
// 20080617
unsigned char card_type_check_w; // Card type check is allow to write
//1 allow, others do not allow. Mainly used to avoid problems which may cause by
irregular card
unsigned char card_type_check_val; //0--Check card type, otherdo not check card type;
//The default value is 0.
//2009-10-30
unsigned char card_RxThreshold_w; // Receiver sensitivity of the card is allow to write
//1 allow, others do not allow, mainly used to avoid problems which may cause by
irregular card
unsigned char card_RxThreshold_val; // When antenna parameter has 5 bytes, it can receive
sensitivity for Type A and B card. If it has 7 bytes, only just received sensitivity for Type B
card.
//2009-11-20
unsigned char f_modulate_w; // felica modulation depth allow to write
unsigned char f_modulate_val; // felica modulation index
//add by wls 2011.05.17
unsigned char a_modulate_w; // The modulation index of A card is written enable
unsigned char a_modulate_val; // The A card control variable of modulation index, valid
//add by wls 2011.05.17
unsigned char a_card_RxThreshold_w; // Receiver sensitivity of the A card is allow to
write :1-allow,Others do not allow
unsigned char a_card_RxThreshold_val; // Receiver sensitivity of the A card
//add by liubo 2011.10.25, aim at the antenna gain of A, B and C card
unsigned char a_card_antenna_gain_w;

unsigned char a_card_antenna_gain_val;
unsigned char b_card_antenna_gain_w;

unsigned char b_card_antenna_gain_val;
unsigned char f_card_antenna_gain_w;

unsigned char f_card_antenna_gain_val;
//added by liubo 2011.10.25, aim at the Felica receiving sensitivity

unsigned char f_card_RxThreshold_w;

unsigned char f_card_RxThreshold_val;

unsigned char reserved [76]; // Reserved byte, which is used for future extension. It will be
clear to 0 if write operation is needed.
} PICC_PARA;
Note: This structure only applies to the Enhanced Edition of R50, and other machines still use
the original structure.
Return code list of module operation function:
Return code Description
0x01 Parameter error
0x02 RF module not opened
0x13 Card is inactive
0x14 Multi card conflict
0x15 Timeout
0x16 Protocol error
0x17 Communication transmission error
0x18 M1 card verification error
0x19 Section not verification
0x1A Data format error, or file size error in DesFire card operation.
0x1B Card still in the sensing area.
0x1C Card status error(for example, A/B Card calls the interface of M1 Card, or M1
card calls PiccIsoCommand interface)
0x1F Response data in DesFire card error
0x21 Lack of application buffer space in DesFire card operation
0x25 The response data in card is not the same with DES calculation results
0x26 Operation is not allowed. For example, the selected file is not record file, you
cannot do the operation of read record.
0xff Interface chip does not existed or abnormal.
Other Depend on the API function.
3.7.1 PiccOpen
Prototype: uchar PiccOpen(void)
Check whether initialization status is normal after contactless module is
Function:
powered on and reset.
Input None
Parameter:
Output None
Parameter:
0x00 Success
Return: Others Abnormal errors, possible value is 1-4. 1 and 2 represent timeout
error; 3 and 4 represent initialization error.
Notes: When POS is turned on, contactless card module will be in the mode

of default power-off, and will not work. It is needed to call this

function every time before contactless card transaction will be made.
If there is contactless card within the sensing area, calling this
function will also reset the contactless card.
If this function is not being called, it will fail to call other
contactless card functions other than PiccClose ( ).
When contactless module is not installed or not working properly,
calling this function will result in failure.
P78, P90 and P58 do not support this API!
Example:
char tmpc;

tmpc=PiccOpen( );
if (tmpc) return 1;

3.7.2 PiccSetup
Prototype: uchar PiccSetup (uchar mode, PICC_PARA *picc_para)
Write specified parameters, in order to adapt to more specific application
Function:
environment; or read current parameter setting.
mode Indicate parameter setting mode: r or R, means read; w or
Input
W, means write.
Parameter:
picc_para Pointer to the structure of parameter setting
Output None
Parameter:
0 Success
1 Parameter Error (invalid mode parameter)
Return:
2 Module not opened yet
Others Abnormal error, currently no other values
This interface can only be successfully called after interface
PiccOpen() and before PiccDetect()
After PiccOpen ( ) is being called, parameters will be reset to default
values.
Description of main parameters for structure PICC_PARA:
1. Every settable parameter is composed of"xx_w" and "xx_val". For
example: "m_conduct_w" and "m_conduct_val"; "xx_w" is used to indicate
Notes:
whether "xx_val" is allowed to write to. Only when "xx_w = 1", then "xx_val"can
allowed to configure.
2."xx_w" is application control information which is read-forbidden.
3. Parameter a_conduct_val, m_conduct_val and b_modulate_val are used
to modulate RF module which is related to reading distance and reading
performance. Normally, they are unnecessary to be configured; Please
inquire PAX technical support staff before reconfiguration.

4. Parameter card_buffer_val is used to modify the maximum length of

the receivable frame. Sometimes, the maximum length of the response
frame, which is returned to terminal by card, is non-standard, that may
result in card incorrectly processing relatively large data frame. In this
situation, errors can be avoided by reconfiguring this parameter.
5. Parameter wait_retry_limit_val is used to limit the resent times of
terminal frame data, only support for P80. For other type, the value of
wait_retry_limit_val is 0, which means not limit the resent times.
6. Parameter card_type_check_val is used to determine the card type
check follows either Type A criterion or MifareOne criterion. Some cards
may return non-standard card type values (return A to M card) to the
terminal. In default case, card type will be checked.
7. Parameter card_RxThreshold_val is used to set the card receiving
sensitivity, which is related to reading performance. Normally, they are
unnecessary to be configured; Please inquire PAX technical support staff
before reconfiguration.
8. Parameter f_modulate_val is used to configure Felica card modulate
depth which is related to reading distance and reading performance.
Normally, they are unnecessary to be configured; Please inquire PAX
technical support staff before reconfiguration.
Example 1: Change default parameter setting (only change B type card adjustment index)
char tmpc;
PICC_PARA picc_para;

tmpc=PiccOpen ();
if (tmpc) return 1;
memset (&picc_para, 0x00, sizeof (PICC_PARA));

picc_para.b_modulate_w=1;
picc_para.b_modulate_val=3;
picc_para.card_buffer_w=1;
picc_para.card_buffer_val=64;
tmpc=PiccSetup (w, &picc_para);
if (tmpc) return 2;

Example 2: Read current parameter setting content

char tmpc;
PICC_PARA picc_para;

tmpc=PiccOpen ();
if (tmpc) return 1;

tmpc=PiccSetup (r, &picc_para);

if (tmpc) return 2;

3.7.3 PiccDetect
uchar PiccDetect(uchar Mode, char *CardType, uchar *SerialInfo, uchar
Prototype:
*CID, uchar *Other)
Search for PICC card according to specific mode; if card is found, select and
Function:
activate it.
Mode 0 Search for type A card one time, then search for type B
(Used to card one time; it is not allowed that there is more than
specified one card within the sensing area. (including both type
card A card and type B card)
searching This mode is compliant with the PICC card searching
mode.) mode designed by VISA WAVE, Master PayPass and
CUP.
a or Search for type A card one time. It is not allowed that
Input
A there is more than one type A card within the sensing
Parameter:
area.
b or Search for type B card one time. It is not allowed that
B there is more than one type B card within the sensing
area.
mor Search for type M1 card one time. It is not allowed
M that there is more than one type M1 card within the
sensing area.
Others Reserved
CardType Point to byte buffer, which stores type of card.
Currently, it will return one byte of type value:
A Find type A card
B Find type B card
Output
M Find type M1 card
Parameter:
If CardType is set as NULL, type of card will not be output.
If card found, Mode=0 can return A or B; if Mode=a or A,
it will only return A; if Mode=b or B, it will only return
B; If Mode=m or M, it will only return M

SerialInfo Point to the first address of buffer, which stores card SN

information
The information includes length of Serial Number and content of
Serial Number.
Serial Number for both type B card and M1 card is 4 bytes;
Serial Number for type A is usually 4 bytes, sometime is 7 bytes
or 10 bytes.
The byte of SerialInfo [0] indicates length of Serial Number;
SerialInfo [1~9] stores Serial Number (left alignment). If it is
needed to read Serial Number and the card is type A card, the
byte of length must be used.
If SerialInfo is set as NULL, Serial Number will not be output.
Otherwise, it has to be allocated at least 11 bytes.
CID Point to the buffer which stores logic channel index of card. The
channel number will be assigned and specialized by driver, and
the value will be in the range of 0~14.
According to ISO14443, maximum 15 cards could be in the
detect area and operate by turns.
Currently, just allow one, so CID [0] always be 0x00. Therefore,
for other CID values (0~14), it will also be considered as 0x00.
If the CID does not need to send out, please set it as NULL.

Other Point to the buffer which stores detailed error code, response
information of card.
Other[0]: Length of following byte
Other [1-2]: Returned detailed error code (lower byte comes
first); due to completed process of searching card, the returned
value can be used to find abnormal error.
Other [3]:
For type A card, return: ATQA [2] + SAK1 + [SAK2] + [SAK3]
+ ATS_Len + ATS; the length of ATQA is 2 bytes; the length of
SAK is 1 byte. Based on the length of card Serial Number, there
should contain information of SAK2 and SAK3, which are one
byte long respectively. The length of ATS_Len is 1 byte. The
length of ATS is determined by ATS_Len.
For type B card, ATQB (Answer To Request B) of card will be
returned. Its length is 12 bytes.
For M1 card, return: ATQA[2] + SAK1
For detailed information of ATS, ATQB and ATQA, please refer
to ISO14443-3 and ISO14443-4.
Other [299]: The ending bytes are reserved, for future use.
Currently, it will only output 0x00.
If it is required to output the information, the size of buffer which
Other points to should be at least 300 bytes.
If it is not required to output the information, Other should be set
as NULL.
0 Success
1 Error parameter (invalid mode )
2 module not opened yet
3 The module cannot find the card(there is no designated type card
in the working area)
Return:
4 There are too many cards in the working area (communication
collision)
6 Protocol error (returned data from card is illegal)
Other Abnormal error, please refer to the description of RF module
return code.
The function will return error and exit if the module does not find the
designated type of card within the sensing area. Application will
control and accomplish continuous searching.
From physical level point of view, type A card and M1 card are the
same. Meanwhile, type A card can exist in both link layer and
Notes:
transport layer; M1 card can only exist in link layer.
When application is searching for type A card, it will still report error
if type A card not found but M1 card found; when application is
searching for M1 card, it will report error if M1 card not found but
type A card found.

The designated type of card within the sensing area can be activated
by calling this function. Afterwards, the card will remain in the status
of activation. If the card is active, calling this function again will
return failure, and the status of the card will be turned to waiting.
Example: Search for type A and type B card
char tmpc;

tmpc=PiccOpen ();
if (tmpc) return 1;
ScrPrint (0, 2, 1, PLS WAVE CARD);

while (1)
{
tmpc=PiccDetect (0, NULL, NULL, NULL, NULL);
if (! tmpc) break; //Card has been detected successfully
if (tmpc! =3)
{
ScrPrint (0, 2, 1, FAILED TO DETECT CARD: %02X, tmpc);
Beep ();
DelayMs (500);
ScrClrLine (2, 3);
}
If (! kbhit () && getkey () = =KEYCANCEL) return 2;
}//while (1), card detect loop

3.7.4 PiccIsoCommand
uchar PiccIsoCommand(uchar cid,APDU_SEND
Prototype:
*ApduSend,APDU_RESP *ApduRecv)
Send APDU format data to card and receive response from card on the
Function:
designated slot.
cid Designated logic slot; the slot is obtained from parameter (CID)
Input of PiccDetect (). The value of slot will be in the range of 0~14.
Parameter: Currently, all values between 1~14 will also considered as 0.
*ApduSend Point to structure of APDU_SEND
Output *ApduRecv Point to structure of APDU_RESP
Parameter:
0 Success
1 Error parameter (invalid mode)
Return:
3 Corresponding card not activated

4 Transmission error (over repeat limit)

5 Protocol error (returned data from card is illegal)
Others Communication error, please refer to the description of RF
module return code.
Data structure of APDU_SEND and APDU_RESP are the same as IC
card functions please refer to the section of IC card read and write
functions for more details.
This function only can be successful after interface PiccDetect ( ) has
Notes: been successfully called. Otherwise, calling this function will result
in failure.
ApduSend->Lc should not be bigger than 255. Otherwise, it will
return parameter error.
Example:
char tmpc;
APDU_SEND as;
APDU_RESP ar;

tmpc=PiccOpen ();
if (tmpc) return 1;

while (1)
{
if (tmpc! =3)
{
Beep ();
DelayMs (500);
ScrClrLine (2, 3);
}
ScrPrint (0, 2, 0x01, "SELECT PPSE...");

as.Command [0] =0x00;
as.Command [1] =0xa4;
as.Command [2] =0x04; //0x00--HANDLE,0x04-FNAME
as.Lc=14; //2 for HANDLE, 14 for FNAME
as.Le=256;

memcpy (as.DataIn,"\x3f\x00", 2);

strcpy (as.DataIn,"1PAY.SYS.DDF01"); //as card
//strcpy (as.DataIn,"2PAY.SYS.DDF01"); //as standard
memset (ar.DataOut, 0x00, 512);
tmpc = PiccIsoCommand (0, &as, &ar);

if (tmpc)
{
ScrPrint (0, 2, 1,FAILED TO SELECT PPSE: %02X, tmpc);
return 3;
}

3.7.5 PiccRemove
Prototype: uchar PiccRemove(uchar mode, char cid)
Send command of power-off to card based on specified mode; or send
Function: power-off command as well as additional command to check whether the card
has been removed from sensing area.
mode h or H HALT. The function will exit after the card sends
(specified the command of power-off. The process will not
mode) check whether the card is removed or not.
r or R The process of removing card (PayPass
compliance) includes: sending stop command to
Input
card, sending activation command to card for 3
Parameter:
times, and then exit. After the process finished, it
is possible to check whether the card has been
removed from sensing area.
cid Designated logic slot returned from card by calling PiccDetect
( ). Currently, all values between 1~14 will also considered as 0.
Output None
Parameter:
0 Success (R mode means card has been removed; H mode
means communication success.)
1 Error parameter (invalid mode or cid>14)
Return:
4 Transmission error (only valid in H mode)
5 Protocol error (only valid in H mode)
6 card has not been removed from sensing area yet (data link no
error, only valid in R mode)
Others Abnormal error, please refer to the description of RF module
return code.
Notes: If removing the card away from the sensing area is not important after

transaction, it is recommended to use Hmode to call this function. If

removing the card away from the sensing area is required in order to
void duplicated transaction, it is recommended to use R mode to call
this function. Moreover, if function returns that card has not been
removed yet, or report error and terminate transaction, application
should call this function repeatedly.
In R mode, if returned error message indicates that card is not
activated, the reason may be due to calling PiccDetect ()
unsuccessful or serious error happened during the process of calling
PiccIsoCommand (). If serious error incurred and card is being
stopped, it can be considered as card removed.
Example:
char tmpc;
APDU_SEND as;
APDU_RESP ar;

tmpc=PiccOpen ();
if (tmpc) return 1;

while (1)
{
if (tmpc! =3)
{
Beep ();
DelayMs (500);
ScrClrLine (2, 3);
}
ScrPrint (0, 2, 0x01,"SELECT PPSE...");

as.Le=256;



if (tmpc)
{
return 3;
}
while (2)
{
tmpc=PiccRemove (R, 0);
if (! tmpc) break;
if (tmpc>3)
{
Beep ( );
ScrPrint (0, 2, 1,PLS REMOVE CARD);
DelayMs (500);
}
else
{
ScrPrint (0, 2, 1,FAILED TO REMOVE: %02X, tmpc);
getkey ();
return 4;
}
}//while (2), card remove loop

3.7.6 PiccClose
Prototype: void PiccClose(void);
Function: Close contactless module and set it as power-off status
Input None
Parameter:
Output None
Parameter:
Return: None
After the function is being called, contactless module will be set to power-off
status, and module will not transmit carrier wave any more. Moreover, calling
Notes:
other functions except PiccOpen ( ) will all result in failure.
Advice: Calling this function to close contactless module after the end of

transaction, and calling PiccOpen () function to reopen contactless module

before the next transaction.
Example:
char tmpc;
APDU_SEND as;
APDU_RESP ar;

tmpc=PiccOpen ();
if (tmpc) return 1;
ScrPrint (0,2,1, PLS WAVE CARD);

while (1)
{
if (tmpc! =3)
{
Beep ();
DelayMs (500);
ScrClrLine (2, 3);
}
ScrPrint (0, 2, and 0x01, SELECT PPSE...");

as.Le=256;

if (tmpc)
{
return 3;

while (2)
{
if (! tmpc) break;
if (tmpc>=3)
{
Beep ( );
DelayMs (500);
}
3.7.7 M1Authority
uchar M1Authority(uchar Type, uchar BlkNo, uchar *Pwd, uchar
Prototype:
*SerialNo)
Validate A password or B password, which are required for reading or writing
Function:
the corresponding block data during the process of accessing M1 card.
Type A or a Password type is A
B or b Password type is B
BlkNo Block number. For M1 card with 1K memory, its valid range is
Input 0~63.
Parameter: Pwd Input parameter. Point to password buffer.
SerialNo Input parameter, the address of buffer to store serial number of
card, it should point to the address of Serial number part of
SerialInfo after running PiccDetect(), namely SerialInfo+1
Output None
Parameter:
0 Success
1 Error parameter (invalid Type value or empty pointer)
Return:
Others Validation error (card removed or incorrect password), please
refer to the description of RF module return code.
M1 card memory contains many sections, and each section is made
up of four blocks. The last block of each section is control block,
which stores password A, password B and read and write control
Notes: information. The length of password A or B is 6 bytes. The length of
block is 16 bytes. Therefore, M1 card is not as secure as CPU card,
since there are only 6 bytes of space to store password for protecting
4 blocks.

The function can only be called after PiccDetect () has been

successfully called.
It will be disabled if there is invalid block number or incorrect
password. The card has to be activated by starting searching process
again.
Example: Validate password A (to read block number 4)
char tmpc, BlkNo, SerialInfo [11], PwdA [6], PwdB [6];

tmpc=PiccOpen ();
if (tmpc) return 1;
ScrPrint (0, 2, 1, PLS WAVE M1 CARD);

while (1)
{
//--to detect a M1 card
tmpc=PiccDetect (M, NULL, SerialInfo, NULL, NULL);
if (tmpc! =3)
{
Beep ();
DelayMs (500);
ScrClrLine (2, 3);
}
ScrPrint (0, 2, 0x01,"AUTH PASSWORD A...");

BlkNo=4;
Memcpy (PwdA,\xff\xff\xff\xff\xff\xff, 6);
tmpc = M1Authority (A, BlkNo, PwdA, SerialInfo+1);
if (tmpc)
{
ScrPrint (0, 2, 1,FAILED TO AUTH A: %02X, tmpc);
return 3;
}

3.7.8 M1ReadBlock
Prototype: uchar M1ReadBlock(uchar BlkNo, uchar *BlkValue);
Function: Read the content of designated block of M1 card (16 bytes).

Input BlkNo Input parameter for specific block number. For M1 card with 1K
Parameter: memory, its valid range will be 0~63.
Output BlkValue Output parameter, point to the first address of buffer, which stores
Parameter: block contents. The length of the buffer is at least 16 bytes.
0 Success
1 Error parameter (empty pointer)
Return:
4 Cannot meet the accessing requirement (password not
authorized)
Others Read error (card removed or card stopped); please refer to the
description of RF module return code.
If the requirement of accessing cannot be met, card will be stopped
whenever read action is performed. The card has to be activated by
starting searching process again.
The M1 card electronic purse is stored in a specific block with unique
format. The balance can be obtained from this block. Following
shows the format of the electronic purse:
BALANCE[4] + ^balance[4] + BALANCE[4] +BLK_NO+
^blk_no+BLK_NO+ ^blk_no
Notes:
BALANCE [4] 4 bytes balance (low byte comes first). It will be
saved two times within the block.
^balance[4] get the value of per byte of balance in reverse
BLK_NO The block number where stores electronic purse. Its valid
value is from 0 to 63 for M1 card with 1K memory. It is saved two
times within block.
^blk_no reverse code of block number which stores electronic
purse. It is saved twice within block.
Example: Validate password A, read the contents of block 4
char tmpc, BlkNo, SerialInfo[11], PwdA[6], PwdB[6], tmps[16];

tmpc=PiccOpen ();
if (tmpc) return 1;

while (1)
{
if (tmpc! =3)
{


Beep ();
DelayMs (500);
ScrClrLine (2, 3);
}
ScrPrint (0, 2, 0x01,"AUTH PASSWORD A...");

BlkNo=4;
memcpy (PwdA,\xff\xff\xff\xff\xff\xff, 6);
tmpc = M1Authority (A, BlkNo, PwdA, SerialInfo+1);
if (tmpc)
{
ScrPrint (0, 2, 1,FAILED TO AUTH A: %02X, tmpc);
return 3;
}
ScrPrint (0, 2, 0x01,"READ BLK %d... BlkNo);

tmpc= M1ReadBlock (BlkNo, tmps);
if (tmpc)
{
ScrPrint (0, 2, 1,FAILED TO READ: %02X, tmpc);
return 4;
}

3.7.9 M1WriteBlock
Prototype: uchar M1WriteBlock (uchar BlkNo, uchar *BlkValue);
Function: Write data to designated block (16 bytes)
Input BlkNo Input parameter for specific block number. For M1 card with 1K
Parameter: memory, its valid range will be 0~63.
Output BlkValue Output parameter, point to the first address of buffer, which
Parameter: stores block contents.
0 Success
Return: 1 Error parameter (empty pointer)
authorized)
Others Write error (card removed or card stopped); please refer to the
description of RF module return code.

If the write requirement is met (password authorized), calling this

function can write M1 cardholder information (such as card number)
to specified block, or write electronic purse initialization value, or
other information.
For some other personalized features, calling this function can
upgrade control block. It is required to ensure that the meanings of 4
Notes: bytes control bits and its check bit are compliant with relevant
requirements. For structure and meanings of control block, please
refer to other documentation on M1 card.
If the requirement of accessing cannot be achieved, card will be
stopped whenever write action is performed. The card has to be
activated by starting searching process again.
Example: Validate password B, write the data of electronic purse to block 4

tmpc=PiccOpen ();
if (tmpc) return 1;

while (1)
{
if (tmpc! =3)
{
Beep ();
DelayMs (500);
ScrClrLine (2, 3);
}
ScrPrint (0, 2, 0x01,"AUTH PASSWORD B...");

BlkNo=4;
Memcpy (PwdB,\xff\xff\xff\xff\xff\xff, 6);
tmpc = M1Authority (B, BlkNo, PwdB, SerialInfo+1);
if (tmpc)
{
ScrPrint (0, 2, 1,FAILED TO AUTH B: %02X, tmpc);
return 3;

ScrPrint (0, 2, 0x01,"WRITE BLK %d... BlkNo);

//--to construct a purse with initial balance 1
memcpy (tmps,"\x01\x00\x00\x00, 4);
tmps [4] =~tmps [0];
memcpy (tmps+8, tmps, 4);
tmps [12] =tmps [14] =BlkNo;
tmps [13] =tmps [15] =~BlkNo;
tmpc= M1WriteBlock (BlkNo, tmps);

if (tmpc)
{
ScrPrint (0, 2, 1,FAILED TO WRITE: %02X, tmpc);
return 4;
}

3.7.10 M1Operate
uchar M1Operate(uchar Type, uchar BlkNo, uchar *Value, uchar
Prototype:
UpdateBlkNo);
Credit or debit the electronic purse on M1 card, and update master purse or
Function:
backup purse.
Type + Credit , plus sign
(Operation Debit, subtraction sign
type)
> Save as/Backup operation, greater than sign
BlkNo Input parameter for specific block number. For M1 card with 1K
memory, its valid range will be 0~63.
Input Value Point to the first address of buffer, which stores credit or debit
Parameter: value. Value is 4 bytes, and lower byte comes first. Not allowed
NULL.
UpdateBlk Input parameter for specific block number, which stores final
No result. M1 card contains two electronic purses, which are master
and backup purse respectively, in order to recover the data after
abrupt power-off. The operation result of mast purse will be
written to backup purse.
Output None
Parameter:
0 Success
Return:
1 Error parameter (invalid Type value, or empty pointer)


authorized or invalid electronic purse structure)
Others Operation error (card removed or card stopped), please refer to
the description of RF module return code.
If the accessing requirement cannot meet, card will be stopped whenever credit
or debit or save as action is performed. The card has to be activated by starting
searching process again.
Notes:
Parameter Value does not have actual meaning when perform the save as
operation.
Example: Validate password B, credit master purse of block 4, and the result will be stored in
backup purse (block 5). Remove card and close module.
ulong amount;

tmpc=PiccOpen ();
if (tmpc) return 1;

while (1)
{
if (tmpc! =3)
{
Beep ();
DelayMs (500);
ScrClrLine (2, 3);
}
ScrPrint (0, 2, 0x01,"AUTH PASSWORD B...");

BlkNo=4;
memcpy (PwdB,\xff\xff\xff\xff\xff\xff, 6);
tmpc = M1Authority (B, BlkNo, PwdB, SerialInfo+1);
if (tmpc)
{
ScrPrint (0, 2, 1,FAILED TO AUTH B: %02X, tmpc);

return 3;
}
ScrPrint (0, 2, 0x01,"ADD VALUE TO BLK %d... BlkNo+1);

Amount=100;
tmps [0] =amount&0xff;
tmps [1] = (amount>>8) &0xff;
tmpc= M1Operate (+, BlkNo, tmps, BlkNo+1);
if (tmpc)
{
ScrPrint (0, 2, 1,FAILED TO ADD VALUE: %02X, tmpc);
return 4;
}

while (2)
{
if (! tmpc) break;
if (tmpc>=3)
{
Beep ( );
DelayMs (500);
}
else
{
ScrPrint (0, 2, 1,FAILED TO REMOVE: %02X, tmpc);
getkey ();
return 4;
}
}//while (2), card remove loop
PiccClose ( );
return 0;
3.7.11 PiccLight
Prototype: void PiccLight(uchar ucLedIndex, uchar ucOnOff);
Function: Control 4 LEDs of RF module.
Input ucLedIndex LED index, each bit represents one type of color.
Parameter: ucOnOff Status of LED. 0 means off; others mean on.
Output None
Parameter:

Return: None
Values of ucLedIndex represent:
BIT0:red
BIT1:green
BIT2:yellow
BIT3:blue
Notes:
BIT4~BIT7 reserved
#define PICC_LED_RED 0x01
#define PICC_LED_GREEN 0x02
#define PICC_LED_YELLOW 0x04
#define PICC_LED_BLUE 0x08
P78, P90, P80 and P58 do not support this API!
3.7.12 PiccInitFelica
Prototype: uchar PiccInitFelica(uchar ucRate, uchar ucPol);
Function: Initialize FeliCa.
ucRate Setting the communication speed with card: 0-212Kbps,

1-424Kbps
Input
Setting the FeliCa modulation:
Parameter:
ucPol 0 Positive
1 Negative
Output
None
Parameter:
0x00 Successful
0x02 Module not opened yet
Return:
0x26 The interface chip does not support FeliCa operation
0xff The interface chip does not exist or abnormal.
ucRate (communication speed) depends on the communication speed with the
card. The default value of ucPol (modulation) is Positive.
ret=PiccOpen();//Open RF Card
memset(cmd,0,sizeof(cmd));
memset(Resp,0,sizeof(Resp));
//Package command
cmd[0]=0x06;
cmd[1]=0x00;
Notes: cmd[2]=0xFF;
cmd[3]=0xFF;
cmd[4]=0x01;
cmd[5]=0x00;
slen=6;
PiccInitFelica(0, 0);// With 212Kbps speed and positive modulation

memset(Resp,0,sizeof(Resp));
rlen=0;
ret=PiccCmdExchange(slen,cmd,&rlen,Resp);
if(ret==0x15)// No exist card or timeout

{
continue;
}
else
{
if(ret==0 && rlen>0)
{
ScrPrint (0, 0, 0x01, READ CARD OK! ");
for(i=0;i<rlen-1;i++)
ScrPrint((i%8)*15,i/8+2,0,"%02X",Resp[i]);
Beep();
DelayMs(3000);
}
}
P78, P80, P90, P58 and R30 do not support this API!
3.7.13 PiccCmdExchange
uchar PiccCmdExchange(uint uiSendLen, uchar* paucInData, uint*
Prototype:
puiRecLen, uchar* paucOutData)
APDU data interactive with the card. The terminal sends data that in paucInData
Function:
to card and receive the response.
Input uiSendLen The length of command data to be sent
Parameter: paucInData Command data to be sent
Output puiRecLen The length of command data that received
Parameter: paucOutData Command data that received
0x00 Successful
Return:
Other Refer to return code list
Notes: P78, P90 and P58 do not support this API!
3.8 Printing Functions
All API of this module are completely applicable for P58, partially applicable for P80, P90 and P78;
not applicable for R50, R30, R50-M and R100.
Module function description: this module is designed to achieve printing API, which include setting
font, feeding paper, printing LOGO, checking printing status, setting boundaries, etc.
P78 uses sprocket printer; P80, P90, P58 use thermal printer.
P78 printing method: After calling the printer initialization API, the printer is required to set up
printing control. Then using the printer related API to format the printing content. Afterwards, call
the start printing API to perform printing action, and then return printing status after printing
process is completed. The printing status can be obtained via the check printer status API.
Printer Default Setting:
Space length between characters is 0; space length between rows is 2.
Left indent is 0.
Default font is small font.
Printer Characteristic:
Contains 9 printer pinheads, which can print characters with sizes of 6x8, 8x16, 16x16,

7x9. Based on maximum 180 pixels per line, 11 Chinese characters with size of 16x16
can be printed on one line; 22 ASCII characters with size of 8x16 can be printed on one
line; 30 small ASCII characters with size of 6x8 can be printed on one line.
Maximum 33 lines of small characters can be printed on one page, or 19 lines of Chinese
characters/33 lines of Korean characters.
If Korean font library is used, 40 small characters can be printed on one line, or 20 small
Korean characters/big characters, or 10 big Korean characters.
For printing LOGO, the width of the logo should not be larger than 180 pixels.
Otherwise, those out of bound content will be truncated.
If there is error in the data packet, the valid data content will be printed, the invalid
content will be printed with ().
Automatic line feed: If the printed line is larger than 180 pixels, then those un-printed
part will be printed in the next line, or in the next page.
Contains feed paper key and withdraw pay key, which are designed to install paper easily.
When both feed paper key and withdraw key are press at the same time, paper will be fed
to the proper position right under the cutter.
P80 and P90 printing method: After calling the printer initialization API, the printer is required to
set up printing control. Then using the printer related API to format the printing content. Afterwards,
call the start printing API which will transmit all the printer control codes and printing content to
the printer. The printing status can be obtained via the check printer status API.
Printer Default Setting:
Character space is 0; line space is also 0.
Default font size for thermal printer is 12x24 for ASCII and 24x24 for Chinese
characters.
If new font is used, it is necessary to set character space as 2, and line space as 8 in
application.
Printer Characteristic:
Printing Bitmap Buffer: 500K bytes long, which is about 200 lines of 24x24 Chinese
characters.
Standard Font Size [Width X Height]: 8X16 ASCII, 16X16 Chinese fonts, 12x24 ASCII
and 24x24 Chinese fonts.
Enlargeable Font Size: Each standard font could be enlarged 100% vertically,
horizontally or both. That meant each standard font could be enlarged in three sizes as the
following:
8x16 ASCII fonts: 8x32, 16x16, 16x32;
12x24 ASCII fonts: 12x48, 24x24, 24x48;
16x16 Chinese fonts: 16x32, 32x16, 32x32;
24x24 Chinese fonts: 24x48, 48x24, 48x48;
Error Handling: If there is error in the data packet, the valid data content will be printed,
the invalid content will be printed with ().
According to the above definition, each line can print up to 24 16x16 Chinese characters.
48 8x16 ASCII characters. 32 12x24 ASCII characters or 16 24x24 Chinese characters.
For printing LOGO, the width of the logo should not be larger than 384 pixels.

Otherwise, those out of bound content will be truncated.

Automatic line feed: If the printed line is larger than 384 pixels, then those un-printed
part will be printed in the next line.
Support manual line feed feature.
Internal module data structure: None
3.8.1 PrnInit
Prototype: uchar PrnInit(void)
Function: Printing Initialization
Input None
Parameter:
Output None
Parameter:
0x00 Success
Return:
Others Other errors
P78 Sprocket Printer P80P90 Thermal Printer
The printer should be initialized The printer should be initialized
before each printer session: before each printer session:
The initialization must be The initialization must be
successful successful
Printer default settings are Printer default settings are
restored during initialization restored during initialization
Default settings for ASCII and
Notes:
Extended code are small font
Default setting for space length
between characters is 0; Default
setting for space length between rows
is 2.
Default setting for printer left
indent is 0.
3.8.2 PrnFontSet(P78)
Prototype: void PrnFontSet (uchar Ascii, uchar CFont)
Function: Set printing font
Ascii Font setting for ASCII
0 Small font[8x8]
1 Big font[8x16]
Input Other Do not change original value
Parameter: CFont Font setting for extended code
0 Small font[8x8]
1 Big font[8x1616x16]
Other Do not change original value

Output None
Parameter:
Return: None
Settings will be valid until they are set again or PrnInit() is called.
For some characters, such as Chinese characters, it will print big font no
Notes:
matter what value Cfont is.
3.8.3 PrnFontSet (P80, P90)

Prototype: void PrnFontSet(uchar Ascii, uchar CFont)
Function: Set printing font.
Ascii Font setting for ASCII
0 8x16 font[default]
1 12x24 font [default]
Input Other Do not change original value
Parameter: CFont Font setting for extended code characters
Other Do not change original value
Output None
Parameter:
Return: None
Settings will be valid until they are set again or PrnInit() is called.
The default font size for ASCII code is 12x24 and default font size for
extended code is 24x24.
Notes:
If there is one or two illegal value, this API will not perform any actions
and return immediately.
3.8.4 PrnSpaceSet
Prototype: void PrnSpaceSet(uchar x, uchar y)
Function: Set up printing character, line spaces
Input x Character space [that is x*8 pixels]
Parameter: y Line space[pixels]
Output None
Parameter:
Return: None

Notes: Settings will be valid until they are Settings will be valid until they are
set again or PrnInit() is called; set again or PrnInit() is called;
Printing character space defaults to Printing character space defaults to

0. 0.
Printing line space defaults to 2. If Printing line space defaults to 0.
less than 2, it will automatically set to The maximum line space can be
2. 255.
The maximum line space can be The maximum character space can
255. be 255.
The maximum character space can
be 60.
3.8.5 PrnStep
Prototype: void PrnStep(short pixel)
Feeds printing paper pixel pixels forward. (Thermal printer can feed forward /
Function:
backward)
Input pixel Number of pixels
Parameter:
Output None
Parameter:
Return: None
If the pixel value is positive value, paper will feed forward; if value is negative,
paper will feed backward. Therefore, it is possible to print bitmap on printed
characters.
Notes: If printing images on characters is required, PrnStep () must be recalled after
icons are printed. Printing pointer is needed to point to the end of character.
Otherwise, character will be truncated after bitmap is printed.
3.8.6 PrnStr
Prototype: uchar PrnStr (char *str,...)
Function: Prints formatted string
Input str pointer to the formatted string
Parameter:
Output None
Parameter:
0x00 String successfully formatted
Return:
0xfe Printing buffer overflow or function buffer overflow

1)Support argument list 1)Support argument list
Notes: 2)Support \n (newline) and \f (new 2)Support \n (newline) and \f (new
page) control characters page) control characters
3) If the printing data package is too 3) If the printing data package is too
long, the printing characters will long, the printing characters will

be truncated. be truncated.
4) If the string is longer than the 4) If the string is longer than the
current printing line, it will current printing line, it will
continue to print on the next line. continue to print on the next line.
5) During printing, it is required to 5) Maximum buffer size of function is
add 2 % to strings, which is 2048 bytes.
%%.
6) When current page is full, it will
automatically continue on the next
page.
7) Maximum buffer size of function is
2048 bytes.
3.8.7 PrnLogo
Prototype: uchar PrnLogo(uchar *logo)
Function: Print bitmap
Input logo Pointer to the bitmap
Parameter:
Output None
Parameter:
0x00 success
Return:
0xfe Print buffer overflow

Bitmap data are generated as Bitmap data are generated as
the following: the following:
Draw a bitmap (usually a Draw a bitmap (usually a logo):
logo): use paintbrush use paintbrush program under
program under Windows to Windows to draw a bitmap and
draw a bitmap and save it as save it as monochromatic, bmp
monochromatic, bmp format file.
format file.
Notes:
Use Bitmap Converter Use Bitmap Converter provided
provided by PAX to convert by PAX to convert the .bmp file
the .bmp file into a header into a header file, for instance,
file, for instance, Logo.h Logo.h header file. (If more than
header file. (only contains one one .bmp files are selected, then
array) multiple character arrays (with the
Printing bitmap size limit: up corresponding bmp file name) will
to 180 pixels in width and no be defined in the generated header
limit in height. file.
Use the generated array as the Printing bitmap size limit: up to

input parameter of this function. 384 pixels in width and no limit in

If the bitmap width is larger height.
than the limit of the printer, then it Use the generated array as the
will be sliced on the right side. input parameter of this function.
If the data packet is too long, If the bitmap width is larger
this function will truncate the than the limit of the printer, then it
LOGO message. will be sliced on the right side.
Before displaying LOGO, If the data packet is too long,
function PrnLeftIndent() can be this function will truncate the
used to set the place where LOGO LOGO message.
should be printed. Notes:
After displaying LOGO, it is Description of the array in the
required to use PrnLeftIndent () to header file:
get back to the original position First byte [1 byte]: lines of the
before printing. bitmap;
Notes: Size of the first bitmap line in byte
Description of the array in the [2 Bytes, high byte first];
header file: Bitmap data of the first bitmap line
First byte [1 byte]: lines of the [one line of the bitmap is 8 pixels in
bitmap; height];
Size of the first bitmap line in byte Size of the second bitmap line in
[2 Bytes, high byte first]; byte [2 Bytes, high byte first];
Bitmap data of the first bitmap line Bitmap data of the second bitmap
[ one line of the bitmap is 8 pixels line;
in height]; Etc...
Size of the second bitmap line in
byte [2 Bytes, high byte first];
Bitmap data of the second bitmap
line;
Etc...
3.8.8 PrnStart
Prototype: uchar PrnStart(void)
Function: Transmit data to base station and starting printing
Input None
Parameter:
Output None
Parameter:
0x00 Printing success
0x01 Printer busy
Return:
0x02 Out of paper
0x03 Invalid data packet

0x04 Printer error

0x08 Printer over heat
0xf0 Print process not complete
0xfc Printer without font library
Other Other errors

After calling this API, the After calling this API, the printer
printer will perform the printing will perform the printing task and
task and return after completed return after completed the whole
the whole printing task. printing task.
After completed the whole After completed the whole
printing task, this API will return printing task, this API will return the
the printer status in return value. printer status in return value.
Therefore, the check printer Therefore, the check printer status
Notes: status is not required. is not required.
If the printing process is
completed, recalling this If the printing process is
function will reprint the slip completed, recalling this function
again. will reprint the slip again.
If it is required to inquire
current printer status, please call
printer status inquiry function.
Application will control
printing the icon of printer.
3.8.9 PrnStatus
Prototype: uchar PrnStatus(void)
Function: Inquire current printer status
Input None
Parameter:
Output None
Parameter:
0x00 Success
0x01 Printer occupied
0x02 Out of paper
0x03 Invalid data packet
Return:
0x04 Printer error
0x08 Printer overheat
0xf0 Printing process not complete
0xfc Printer without font library


If status is Printer Busy, None
function will continue inquiring;
Notes: If status is Printing Completed,
task is finished.
If status are others, function will
report errors and return.
3.8.10 PrnLeftIndent
Prototype: void PrnLeftIndent(ushort Indent)
Function: Set left boundary
Indent Setting the left boundary of printing area. It can be used for
Input
printing logos on the right side of the receipt, so that application
Parameter:
can save spaces to store bitmap. X. :(0 -336)
Output None
Parameter:
Return: None

If status is Printer Busy, Default boundary is 0. This
function will continue inquiring; function is valid for LOGO printing
Notes: If status is Printing Completed, function.
task is finished.
If status are others, function will
report errors and return.
3.8.11 PrnGetDotLine
Prototype: int PrnGetDotLine(void)
Get the number of currently printed dotted lines that are already printed, and it
Function:
could be used for alignment
Input None
Parameter:
Output None
Parameter:
The number of dotted lines that have already printed (output to
Return:
the printer buffer).
The versions of P80 monitor V2.1 and posapi.a (v12) or higher would be
Notes: applicable.
P78, R50, R30, R50-M and R100 do not support this API.

Example:
PrnInit ();
PrnSpaceSet (2, 6);
PrnStr (test \n); // ocuppies 24 dotted lines
x= PrnGetDotLine ();
So, X will be: 24+6=30 // 6 is the line space
3.8.12 PrnSetGray (P80)

Prototype: void PrnSetGray(int Level)
Function: Set printing gray level
Level Level =0 reserved
Level =1 default gray level, normal printing
Level =2 reserved
Level =3 dual levels thermal paper printing
Input Level >3 reserved
Parameter: Level =[50~500] Gray level would be set by percentage of
the default (Level=3). For example, 50
means that gray level is to be set by 50% of
level 3, and 100-500 is actually level =3.
other values reserved and cannot be changed
Output None
Parameter:
Return: None
When Level =3, the gray level would be 2.5-3 times darker than Level =1.
Notes:
3.8.13 PrnSetGray (P90)

Prototype: void PrnSetGray(int Level)
Function: Set printing gray level
Level Level =0 reserved
Level =1 default gray level, normal printing
Level =2 reserved
Level =3 dual levels thermal paper printing
Level =4 dual levels thermal paper printing, gray
Input level higher than level 3
Parameter: Level =[50~500] Gray level would be set by percentage of
the default. For example, 50 means that
gray level is to be set by 50% of the default
and 500 is actually 500% of the default
level.
other values reserved and cannot be changed

Output None
Parameter:
Return: None
Level =3, gray color will be darker 2.5 3 times than Level=1
Level =4, gray color will be darker 3.5 4 times than Level=1
When Level=50~500, gray level would be set by percentage of the default. For
Notes: example, Level=50 means that gray level is to be set by 50% of default gray
level, Level =100 is actually the default gray level. If Level is set to 300, it is
equal to Level=3, which means 3 times of default gray level.
3.8.14 PrnGetFontDot
Prototype: int PrnGetFontDot(int FontSize, uchar *str, uchar *OutDot)
Function: Get dot matrix information of the particular character
FontSize 0 Small font size(8x16 or 16x16)
Input 1 Big font size(12x24 of 24x24)
Parameter: str Point to the particular character, whose dot matrix information is
needed
OutDot(ret Return memory size that the dot matrix occupies:
urn dot Size Space occupation
Output matrix 8x16 16 bytes
Parameter: information 16x16 32 bytes
) 12x24 48 bytes
24x24 72 bytes
Return: None
<0 not installed printing fonts yet
1 read successfully
Notes:
It will only be used in some cases that have specific requirements
3.8.15 PrnDoubleWidth
Prototype: void PrnDoubleWidth(int AscDoubleWidth, int LocalDoubleWidth);
Function: Set printing font width, can realize printing with double width
AscDoubleWidth Single code font(1:Double Width, 0:Normal Width)
Parameter:
LocalDoubleWidth Multiple code font(1:Double Width, 0:Normal Width)
Return: None
Notes:
P80 and P90 support this API while using S font.
3.8.16 PrnDoubleHeight
Prototype: void PrnDoubleHeight(int AscDoubleHeight, int LocalDoubleHeight);
Function: Set printing font height, can realize printing with double height

AscDoubleHeight Single code font(1:Double height,0:Normal height)

Parameter:
LocalDoubleHeight Multiple code font(1:Double height, 0:Normal height)
Return: None
Notes:
3.8.17 PrnAttrSet
Prototype: void PrnAttrSet(int Reverse);
Function: Set reverse print, the default value is normal print
Parameter: Reverse (1: reverse , 0: normal)
Return: None
Notes:
3.9 Asynchronous Port Communication Functions
All API of this module are completely applicable for P80, P78, P90, P58, R30, R50-M and R100.
Meanwhile, R50 with previous hardware versions (V04 and before it) contains only one serial port
(COM1), and R50 with later hardware versions (V09 and after it) contains two serial ports
(COM1&COM2). COM1 is used for program downloading and communication and COM2 is used
for communication with external RF module.
P90 contains only one serial port COM1. When P90 is using external modem, it cannot operation
with COM1, otherwise the Modem will disconnect.
Module function description: this module is designed to achieve serial communication API, which
include opening serial port, sending data to serial port, receiving data from serial port, etc.
3.9.1 PortOpen
Prototype: uchar PortOpen(uchar channel, uchar *para)
Function: Open specified communication port
Channel Communication port index
(channel 0 COM1
number) 1 COM2
Input
2 -> LANPORT
Parameter:
3 PINPAD
4 MODEM (for system internal use)
11P USB DEV

Para For example: 9600, 8, n, 1 means: baud rate: 9600, 8 data

(parameter digits, no parity, 1 stop bit.
string for
opening Baud rate: one of 600,1200,2400,4800,9600,14400,
communicatio 19200,28800,57600,115200,230400
n port) Data bits: 7 or 8[R30 only support 8 data bits]
Parity: o-odd; e-even; n-none
Stop bit: 1 or 2[R30 only support 1 stop bits]
When the Port Number is P USB DEV, it neednt pay more
attention on this function.
Output None
Parameter:
0x00 Opening succeed
0x02 Invalid channel index
Return: 0x05 Unknown physical port
0xf0 Modem channel is engaged (for channel=MODEM)
0xfe Invalid communication parameters
P78 and P80 have three physical ports. The first physical port is reserved to
COM1. The second and third physical ports can be dynamically allocated to the
different logical channels. If the second and third physical ports are engaged by
two different logical channels, opening other logical channels will return failure
(0x05).
P90 has three physical ports. The first physical port is reserved to COM1. The
second one is reserved; the third one is reserved for wireless communication
module.
P58 has three physical ports. The first physical port is reserved for MODEM.
Notes: The second one is reserved for COM1; the third one is reserved for
PINPAD.(PINPAD port cannot open as the 7,E,1format)
R50 with previous hardware versions (V04 and before it) contains only one
serial port (COM1), and R50 with later hardware versions (V09 and after it)
contains two serial ports (COM1&COM2).
R30 and R100 only has one physical ports, and its logic port number is COM1
(0).
R50-M has three physical ports. The first physical port is reserved for program
download communication. The second one is reserved for 2.4G module, GPRS.
An enhanced version of R50 has a COM1 serial port and a USB DEVICE.
3.9.2 PortClose
Prototype: uchar PortClose(uchar channel)
Function: Shut down specified communication port


(channel 0 COM1
number) 1 COM2
Input
2 LANPORT
Parameter:
3 PINPAD
11P USB DEV
Output None
Parameter:
0x00 Closing succeed
Return: 0x03 Channel not opened / not connected to any physical port
0x0e Channel closed(only for the P USB DEV)
0xff transmit data timeout
- If there are data in the transmit buffer as closing, the closing operation will
be performed after transmitted all data.
- After closing the channel, the session between the physical port and the
logical channel will not be removed. This session will be removed if there is
Notes: another PortOpen () operation.
- The lower level operation always can close the port successfully. That
meant the un-successful return of this API does not provide any concrete
implication. For instance, if there is a timeout for transmitting data, then
the channel will still be closed.
3.9.3 PortSend
Prototype: uchar PortSend(uchar channel, uchar ch)
Function: Send a byte to specified communication port
(channel 0 COM1
number) 1 COM2
Input 2 -> LANPORT
Parameter: 3 PINPAD
11P USB DEV
ch data to transmit (1 byte long)
Output None
Parameter:
0x00 Success
Return:
0x03 Channel not opened / not connected to any physical port


0x04 Transmit buffer abnormal (data full status > 500ms)
Transmit and receive buffer is 8K bytes long.
Notes: R50 does not have sending buffer, and the sending data size depends on the
needs of application. The sending buffer of enhanced R50 is 16K.
3.9.4 PortRecv
Prototype: uchar PortRecv(uchar channel, uchar *ch, ushort ms)
Function: Receive a byte from specified communication port.
(channel 0 COM1
number) 1 COM2
2 LANPORT
Input 3 PINPAD
Parameter: 4 MODEM (for system internal use)
11P USB DEV
ms Receiving timeout limit (ms)
ch Pointer to received data
Output None
Parameter:
0x00 Success
0x03 Channel not opened / not connected to any physical port
Return:
0xff Received fail (timeout)
If the ms value is 0 and the receive buffer is empty, then this API will return
Notes:
receive fail (0xff).
3.9.5 PortReset
Prototype: uchar PortReset(uchar channel)
Function: Reset serial port and clear all data in receiving buffer.
(channel 0 COM1
number) 1 COM2
Input
2 LANPORT
Parameter:
3 PINPAD
11P USB DEV
Output None
Parameter:

0x00 success
Return: 0x03 Channel not open / not connected to any physical port
Notes: This API will not clear data in transmitting buffer.
3.9.6 PortSends
Prototype: uchar PortSends(uchar channel, char *str,ushort str_len)
Function: Send a string to specified communication port with specified length.
(channel 0 COM1
number) 1 COM2
2 LANPORT
Input 3 PINPAD
Parameter: 4 MODEM (for system internal use)
11P USB DEV
str Pointer of data string to be transmit
str_len Length of data string
Output None
Parameter:
0x00 Success
0x03 Channel not open / not connected to any physical port
Return:
0x04 data length too long (may caused buffer overflow)
The transmit buffer is 8K bytes long. The sending buffer of enhanced R50 is
Notes: 16K.This API could be used to replace the PortSend () API, which can only send
one byte of data at a time.
3.9.7 PortTxPoolCheck
Prototype: uchar PortTxPoolCheck(uchar channel)
Check whether there are data required to transmit in specified communication
Function:
port sending buffer


(channel 0 COM1
number) 1 COM2
Input
2 LANPORT
Parameter:
3 PINPAD
11P USB DEV
Output None
Parameter:
0x00 Sending buffer is empty
0x01 Sending buffer is not empty( there are data required to transmit)
Return: 0x02 Invalid channel number
0x03 Channel not open / not connected to any physical port
The return values of PortTxPoolCheck in R50 (prior hardware version V09) and
Notes:
R30 are always 0.
3.9.8 PortRecvs
int PortRecvs(uchar channel, char *pszBuf, ushort usRcvLen, ushort
Prototype:
usTimeOut)
Function: Receive a string to specified communication port with specified length.
Channel(channel Communication port index
number) 0 COM1
11 P_USB_DEV
Input pszBuf Buffer of data string to be received
Parameter:
usRcvLen Length of data string
usTimeOut Unit of timeout is MS.
Output None
Parameter:
>=0 Success, return to the number of sending data.
-2 Invalid channel index
Return: -3 Channel not open
-0xff Timeout
-0x0e Channel closed(only for the P USB DEV)
It only works with the enhanced R50; The receiving buffer of COM1 is 16K bytes
Notes: long. The sending USB DEVICE is 64K.This API could be used to replace the
PortRecv ( ) API, which can only receive one byte of data at a time.

3.10 MODEM Communication Functions
All API of this module are completely applicable for P80, P78, P58, R50 with external MODEM
(hardware version V09 and after it) and P90 with external MODEM, and not applicable for R50
(prior hardware version V09), R30, R50-M and R100.
Module function description: this module is designed to achieve MODEM communication API,
which include MODEM communication method, MODEM dialing, MODEM receiving/sending,
etc.
Internal module data structure as follows:
typedef struct {
unsigned char DP;
unsigned char CHDT;
unsigned char DT1;
unsigned char DT2;
unsigned char HT;
unsigned char WT;
unsigned char SSETUP;
unsigned char DTIMES;
unsigned char TimeOut; // (unit = 10 seconds, 0 no timeout)
unsigned char AsMode;
} COMM_PARA;
Set values to this structure before dialing up. Structure defined as follows:
Table 3-1 Descriptions for COMM_PARA Structure Variables
0x00 Tone dialing
0x01 Pulse dialing type 1(pulse rate 10/s; break ratio
1.6:1;number-to-number interval >=500ms)
DP
0x02 Pulse dialing type 2 (pulse rate 10/s; break ratio 2:1;number-to-number
interval >=600ms)
Other Reserve for future use
D0 = 0 Check for dialing tone
D0 = 1 Do not check for dialing tone
D1 = 0 Only allow dialing, disabled wait for call / phone ringing
D1 = 1 Allow wait for call / phone ringing.
D2 = 0 Check attached phone set occupied status (dialing or not manual dialing
mode)
D2 =1 Not check attached phone set occupied status (dialing or not manual
CHDT
dialing mode)
D5 = 0 Using AT status interface during wait for call mode.
D5 = 1 Using PAX remote download interface during wait for call mode.
D6 = 0 Using the lower 3 bits value of SSETUP for timeout value
D6 = 1 Double the lower 3 bits value of SSETUP for timeout value
D7 = 0 Using standard ITU V.22bis for async. 2400bps connection.
D7= 1 Using non-standard Fast Connection for async. 2400bps connection.

Other Reserved for future use

DT1 Waiting time from hook-off to dialing (unit = 100ms, minimum and default = 20,
valid range is 20 - 255). If dialing tone is detected, exit waiting.
Waiting time of , when dialing from exterior line (unit = 100ms). This value
DT2 should be set according to real situations. It is better to leave manual setting
interface in applications. [Valid range 0 255]
HT Lasting time of a single number in tone dialing (unit: 1ms, value: 50~255)
WT Pausing time between two numbers in tone dialing (unit: 10ms, value: 5~25)
Communication byte setting
D7: Sync / Async selection
0 Sync
1 Async
D6D5: Baud rate setting
00 1200
01 2400
10 9600
11 14400
D4D2: Line scheme (response checking mode)
10 BELL (Only applicable for 1200BPS)
SSETUP
11 CCITT
0X CCITT
D2D1D0: Response waiting timeout limit (0~7)
000 5s
001 8s
010 11s
011 14s
100 17s
101 20s
110 23s
111 26s
Number of dialing loops (0 will be turned into 1); a loop is finished after all the
DTIMES
numbers in the dialing string are dialed. [Valid range 1~255]
MODEM will hang up if no application data transfer occurs in specified time
TimeOut period. The unit is 10 seconds. 0 means no timeout. Maximum 65, it represents
650s.
Asynchronous Communication (the higher 4 bits), character format (the lower 4
bit)
D3D2D1D0:
0 8,n,1
AsMode 1 8,e,1
2 8,o,1
Note: All the terminal types with conexant modem do not support this
format, except P60S1 and P70.
4 7,e,1

5 7,o,1
8 FSK Using B202communication protocol
9 FSK Using V23C communication protocol
Note: If want to use function 8 and 9 ,the highest bit of SSETUP must be
1(asynchronous)
D7D6D5D4:
0 Use SSETUPs D6D5 value

1 1200 bps
2 2400 bps
3 4800 bps
4 7200 bps
5 9600 bps
6 12000 bps
7 14400 bps
8 19200 bps
9 24000 bps
10 26400 bps
11 28800 bps
12 31200 bps
13 33600 bps
14 48000 bps
15 56000 bps
For asynchronous communication, both SSETUP and AsMode contain the
baudrate value. If the hi-nibble of the AsMode is non zero value, AsModes
baudrate value will be used. For synchronous communication, only SSETUPs
baudrate value will be used (if 14400BPS is set, driver will automatically adjust to
Notes:
1200BPS). The driver will based on the embedded MODEM supported maximum
baudrate to adjust the required speed.
R50(prior hardware version V09), R30R50-M and R100 does not contain
MODEM module, so do not support such a structure.
3.10.1 ModemReset
Prototype: uchar ModemReset(void)
Function: Clear asynchronous communication receiving buffer
Input None
Parameter:
Output None
Parameter:
0x00 Success
Return:
Others Failure
This function clears current receiving buffer in asynchronous communication.
Notes:
R50 (prior hardware version V09), R30, R50-M and R100 do not support this

API.
3.10.2 ModemDial
Prototype: uchar ModemDial(COMM_PARA *MPara, uchar *TelNo, uchar mode)
Set MODEM parameters and dial. While waiting for dialing result (mode=1), it
Function:
can be cancelled by pressing CANCEL key.
mode 0 Return immediately (used in pre-dial)
(Immediate 1 Wait for dialing result
return flag)
Input TelNo Telephone number
Parameter: mPara Modem dialing parameters, default parameters are used when
mParam == NULL
Dailing mode defaults to: synchronous, 1200, DTMF, CCITT
("\x00\x00\x14\x0a\x46\x08\x02\x01\x06\x00")
Output None
Parameter:
0x00 Success
0x03 Telephone line unconnected or occupied (line voltage is not 0,
but too low)
0x33 Telephone line unconnected (line voltage is 0)
0x83: Bypass phone and telephone line is ready (only applicable for
switching to voice mode after dialing)
0x04 Carrier wave lost (Sync. linking failed)
0x05 No response
0x06: Have started dialing (only applicable for switching to voice
Return:
mode after dialing)
0x0a Dialing
0x0b Regular hang-up and free
0x0c Data receiving request declined (receiving buffer empty)
0x0d Called line busy
0xf0 No communication port available (both physical ports are not
available)
0xfd CANCEL key pressed ( MODEM will stop dialing)
Others Abnormal errors
Code meaning in the telephone numbers:
0-9,*, #,A~D Telephone number
, Dialing time prolonging
; Transfer next telephone number
Notes:
. Telephone number transfer over
.. Extended code for terminate code which is used for switching from
dialing mode to manual receiving call mode.
This function can also be used to set MODEM to the mode of being called.

The phone icon is controlled by application. During connection, it will display

hang-up status icon; after connected, or during the switching time for another
dial, it will display in-use icon.
After connected, speaker icon will flash certain times, which indicates actual
connecting speed. The value of times and speed will be according to higher 4
bits of AsMode.
R50 (prior hardware version V09),R30R50-M and R100 do not support this
API.
P90 do not support synchronous "9600" dialing or asynchronous dialing.
Example: Normal dialing procedure:
unsigned char ucRet;
OnHook ();
CommPara. DP=0x00;
CommPara. CHDT=0x00;
CommPara. DT1=0x05;
CommPara. DT2=0x05;
CommPara. HT=0x64;
CommPara. WT=0x06;
CommPara. SSETUP=0x03;
CommPara. DTIMES=0x02;
while (1)
{
ucRet=ModemDial (&CommPara,3546393. 1);
if (ucRet == 0xfd) return USER_CANCEL // user cancel
if (ucRet == 0) break; // connected
if (ucRet==0x03)
{
// line not ready
}
if (ucRet==0x0d)
{
// phone occupied
}
// other error handles
}
Using the following command for dialing with default value, initialization of CommPara can be
omitted.
ucRet=ModemDial (NULL,3546393. 1);
Wait for call mode:
OnHook ();
CommPara. CHDT=0x02; // set for wait for call

CommPara. SSETUP=0x83; // async.

CommPara. AsMode=0x50; //9600BPS, 8N1
ModemDial (&CommPara,. 1);

FSK dialing procedure
OnHook ();
CommPara.DP = 0;
CommPara.CHDT = 0; // Choose 0 or 1 based on actual needs
CommPara.DT1 = 20;
CommPara.DT2 = 10;
CommPara.HT = 70;
CommPara.WT = 5;
CommPara.SSETUP = 0x87;
CommPara.DTIMES = 1;
CommPara.TimeOut = 6;
CommPara.AsMode = 0x08;
//Choose 0x08 or 0x09 based on actual needs
//Choose 0x08 for B202, Choose 0x09 for V23C
while (1)
{
ucRet=ModemDial (&CommPara, 3546393., 1);
if (ucRet == 0xfd) return USER_CANCEL // User cancel
if (ucRet == 0) break; //connected
if (ucRet==0x03)
{
//line not ready
}
if (ucRet==0x0d)
{
//phone occupied
}
//other error handles
}
FSK cannot use default parameter directly.
Wait for call mode of FSK:
OnHook ();
CommPara. CHDT=0x02; // set for wait for call

CommPara. SSETUP=0x87; //async
CommPara. AsMode=0x08;

//Choose 0x08 or 0x09 based on actual needs

//Choose 0x08 for B202, choose 0x09 for V23C
ModemDial (&CommPara, ., 1);
3.10.3 ModemCheck
Prototype: uchar ModemCheck(void)
Function: Check MODEM and telephone line status. It returns immediately.
Input None
Parameter:
Output None
Parameter:
0x00 Success
0x01 Transmit buffer full
0x02 Bypass phone busy
0x03 Telephone line unconnected or occupied (line voltage is not 0,
but too low)
0x33 Telephone line unconnected (line voltage is 0)
0x83 Bypass phone and telephone line is ready (only applicable for
switching to voice mode after dialing)
0x04 Carrier wave lost
0x05 No response
Return:
0x06 Have started dialing (only applicable for switching to voice mode
after dialing)
0x08 Receiving buffer not empty (remote data received)
0x09 Transmit buffer is full and receiving buffer is not empty
0x0a Dialing
0x0b Regular hang-up and free
0x0d Line busy
0xf0 No communication port available (both physical ports are not
available)
Others Abnormal errors
Use this function to check whether connection is established after pre-dialing.
This function is called inside data sending / receiving functions to check the
status of line and data buffers.
Abnormal Errors: Those error codes are used to provide an effective way for
the developer to maintain and support the system. Those abnormal errors
rarely take place. The application does not require knowing the root cause and
Notes:
just needs to display in the console.
During Dialing Process: The abnormal errors range is from 0xD0 to 0xFF for
sync. /async dialing connection fail, from 0x10 to 0x13 for sync. Handshaking
fail. Please refer to the following for those frequent abnormal errors during
dialing process:
D0 cannot send the first AT command to the modem or there is no response

from the modem. The root cause maybe related to the hardware interface with
modem or the modem module. If the modem initialization process fails during
power up, then this abnormal error code will return during dialing.
E8 modem module returns no dialing tone. The root cause maybe related to
the modem module hardware or there is no telephone line.
EF modem module returns dialing abnormal error. The root cause maybe
related to the hardware failure or the telephone line is a digital line.
During Sync. Communication: The abnormal errors range is from 0x14 to

0x19 for non-recovery error or retry error, from 0x41 to 0x4A for transmit
failure or too many retries. Please refer to the following for those frequent
abnormal errors during sync. communication:
15 telephone line unplugged during sync. communication.
19 sync. Data transmission fails. The root cause maybe related to the hardware
failure of the CTS flow control signal.
API.
Example: Pre-dialing and online transaction
OnHook ();
ucRet=ModemDial (NULL,9, 3546393. 0);
/* Enter sales amount, PIN etc */
while (1)
{
ucRet=ModemCheck ();
if (ucRet == 0) break; // Connected
if (ucRet == 0x0a) continue; // Dialing
if (kbhit () ==0)
{
if (getkey () ==KEYCANCEL) return USER_CANCEL // user cancel
}
if (ucRet==0x03)
{
// telephone line not connected
}
if (ucRet==0x0d)
{
// telephone line occupied
}
// other error handling
}

3.10.4 ModemTxd
Prototype: uchar ModemTxd(uchar *SendData, ushort len)
Function: Use MODEM to send data packet
Input len Length of sending data packet
Parameter:
Output SendData Pointer to sending data packet
Parameter:
0xfe Invalid len value (len=0 or len>2048)
Return: For other values, please refer to ModemCheck ().
Transmitting maximum 2048 characters in one API call.
Notes: R50 (prior hardware version V09), R30, R50-M and R100 do not support this
API.
3.10.5 ModemRxd
Prototype: uchar ModemRxd(uchar *RecvData, ushort *len)
Function: Receive returning data from MODEM
RecvData Pointer to receiving data packet (buffer size can be allocated
Input according to real situations)
Parameter: len Length of receiving data packet
Output None
Parameter:
Return: Please refer to ModemCheck()
Receiving maximum 2048 characters in one API call.
API.
Example: Sending / receiving data through MODEM
unsigned char buff [512];
unsigned int len;
// sending data
while (1)
{
ucRet=ModemTxd (buff, 100);
if (ucRet == 0) break // successfully sent
// sending data error
return 0xff;
}
// receiving data
while (1)
{
ucRet=ModemRxd (buff, Len);

if (ucRet == 0) break // successfully received

if (ucRet==0x0c) continue; /* continuing to receive*/
// receiving data error
return 0xff;
}
Onhook ();
// handle received data
3.10.6 ModemAsyncGet
Prototype: uchar ModemAsyncGet(uchar *ch)
Receives returning data one byte at a time during asynchronous communication.
Function:
This function returns immediately.
Input ch Pointer to received data
Parameter:
Output None
Parameter:
Return: Please refer to ModemCheck()
ch is valid only when this function returns 0x00.
API.
3.10.7 OnHook
Prototype: uchar OnHook(void)
Function: Hang up MODEM or stop dialing.
Input None
Parameter:
Output None
Parameter:
0x00 Hang-up success
Return:
Others Hang-up fail
If re-dial is required after hang up, suggest waiting for about 3 seconds before
re-dial because the telephone exchange may require time for switching from
Notes: hang up status to dialing tone status.
API.
3.10.8 ModemExCommand
ushort ModemExCommand(uchar *CmdStr, uchar *RespData,
Prototype:
ushort *Dlen, ushort Timeout10ms)
Additional MODEM command interface, only support some of the parameters.
Function:
(such as dialing voltage level, additional connections)

CmdStr additional command string ending with \0, the first two bytes
are AT or WT=
AT means: When MODEM is going to dial, this command
will be sent to the MODEM chip for its executing AFTER
all other internal setting had been sent to chip and before
the modem sending the phone number. The max length of
command string is 100 bytes (excluding the \0).
WT= is used for setting connection timeout. If this
command is called, the setting will overwrite and replace
existing connection timeout settings of
Input COMM_PARA.SSETUP and COMM_PARA.CHDT. If
Parameter: this command is not called, connection timeout settings of
COMM_PARA.SSETUP and COMM_PARA.CHDT will
still be valid. This command starts from version 82D.
Connection timeout value will be followed the command
head, unit in second, and valid range is 5~255.
RespData Point to output response buffer. Currently it will not output
response.
Dlen Length pointer of output response. Currently it will not output
response.
Timeout10 Response timeout time if there is output response, unit in 10 ms.
ms NOT used yet.
Output None
Parameter:
0:Success
1: ModemExCommand. This function is continuously called more than 100
Return: times, maybe cause the buffer overflow.
2: Length of CmdStr is too long (more than 100 bytes).
3:Unsupported command string(the first two bytes are not AT)
If redialing starts right away after hang-up, driver will automatically wait for 3
seconds and then redial, so that PABX finishes hang-up action and send dial
tone again.
Extra setting command strings are all AT command strings supported by
chip. Application will call command strings based on its requirement (such
as adjusting dialing voltage). If there are no extra settings, driver will use
default values. For more details about AT commands, please refer to
Notes: MODEM manual or other relevant recommendations.
When extra command strings are not supported by chip; MODEM dial will
fail.
Currently, function should be called during the time after hang-up and
before dialing again, and it is only valid for the process of dialing and
communication. If dialing or communication is terminated, the settings will
be invalid. If it is being called during dialing or communication, the
process of dialing or communication will be terminated. Afterwards,

settings of function will be saved for next dialing. At any time once
OnHook () is being called, any settings of ModemExCommand ( ) before
OnHook () will be cleared.
When settings of command string are valid, function can be called
continuously for 100 times. If there exist another same settings, the later
settings will be valid.
If function is being called, its setting parameters will be saved in the buffer
of driver. It becomes valid once ModemDial ( ) is called.
R50 (prior hardware version V09),R30, R50-M and R100 do not support this
API
Example:
ushort dn, rn, tmpu,
COMM_PARA modem_config;

OnHook ();
tmpu=ModemExCommand (ATS91=10, pool, &rn, 0); // Set dialing

voltage= -10dB
if (tmpu) return 1;
tmpu=ModemExCommand (ATS0=0, pool, &rn, 0); // Set MODEM as caller

if (tmpu) return 2;
tmpu=ModemExCommand (WT=100, NULL, NULL, 0); // Set connection

timeout time as 100 seconds
if (tmpu) return 3;
tmpc=ModemDial (&modem_config, 8712, 1);

if (tmpc) return 4;
dn=100;
memset (pool, 0x55, dn);
tmpc=ModemTxd (pool, dn);
if (tmpc) return 5;
while (1)
{
tmpc=ModemRxd (tmps, &rn);
if (! tmpc) break;
if (tmpc! =0x01 && tmpc! =0x0c) return 6;
}
OnHook ();


return 0;
3.10.9 How to Set P80 POS as an External MODEM

After setting P80 POS as an external MODEM, P80 internal MODEM can be accessed by standard
software (such as HyperTerm), and P80 is acting as an external MODEM as a whole. Therefore,
setting result of ModemExCommand ( ) can be verified.
When standard software is being used, notice that it is required to close software and hardware
flow control.
Code example of setting:
char tmpc, cc;
ushort dn, rn,

OnHook ();
tmpc=PortOpen (COM1,115200, 8, n, 1); // COM1 is used for external

access
if (tmpc) return 1;
tmpc=PortOpen (MODEM,115200, 8, n, 1);

if (tmpc) return 2;
while (1)
{
tmpc=PortRecv (COM1, &cc, 0);
if (! tmpc) PortSend (MODEM, cc);
tmpc=PortRecv (MODEM, &cc, 0);

if (! tmpc) PortSend (COM1, cc);
if (! kbhit () && getkey () ==KEYCANCEL) break; // abort the external access

mode
}
PortClose (COM1);
PortClose (MODEM);
return 0;
In HyperTerm, using ATS91? command can check setting result of previous ModemExCommand
(ATS0=0, pool, &rn, 0).

3.11 Wireless Communication Functions
All API of this module are completely apply to P90, apply partly to P80, and not suitable to P78
R50P58R30R100.Because R50-M is using S series wireless communication interface, please
refer to S series wireless communication module for R50-M.
Specification of this module: The module is API to realize the relevant operating of wireless
module (CDMA, GPRS).It describes the mode of wireless communication module and then gives
several suggestions.
Data Structure for module: None.
3.11.1 WnetInit
Prototype: uchar WNetInit(void)
Initialize variables, checking whether the pluggable communication module is
ready for accepting AT commands and checking communication module type
Function:
(CDMA / GPRS). Before using the pluggable communication module, the
application requires to call this API to ensure the module is ready.
Input None
Parameters:
Output None
Parameters:
RET_OK 0X00 Success
RET_NOBOARD 0X17 No pluggable module card detected
(temporary remove this return value)
RET_RSPERR 0X03 Module returns ERROR
Return:
RET_NORSP 0X02 No response returns from module
RET_PORTERR 0XFD Port error
RET_PORTINUSE 0XFE Port engaged
RET_ABNORMAL 0XFF Abnormal error
If the return value is RET_RSPERR, then it may be caused by not detected
SIM/UIM card.
Notes:
P78, R50, P58, R30 and R100 do not support this API.
R50-M please refer to S series wireless communication module.
3.11.2 WnetCheckSignal
Prototype: uchar WNetCheckSignal(uchar *pSignalLevel)
Check the network signal. If this API returns RET_OK, then based on the
Function: returned pSignalLevel value to check the network signal level. Normally, use
this API before dialing operation.

pSignalLevel Signal Level

0x05(99 or 0): No signal
0x04(1~7): Very weak signal
Input
0x03(8~13): Weak signal
Parameters:
0x02(14~19): Normal
0x01(20~25): Good signal
0x00(26~31): Very good signal
Output None
Parameters:
RET_OK 0X00 Success
Return: RET_UNKNOWNTYPE 0X18 Unknown type, maybe not initialized
During modules starting up state, the signal is quite weak or no signal at all.
Normally, CDMA module requires 3 4 seconds to be stabilized and GPRS
Notes: module requires 5 6 seconds.
3.11.3 WNetCheckSim
Prototype: uchar WNetCheckSim(void)
Check SIM card status. Call this API before perform dialing process to ensure
Function:
the SIM card is in operation mode.
Input None
Parameters:
Output None
Parameters:
RET_OK 0X00 Success
RET_NOSIM 0X04 SIM card is not in the slot / not detected
RET_NEEDPIN 0X05 Require PIN
RET_NEEDPUK 0X06 Required PUK code
Return:
RET_UNKNOWNTYPE 0X18 Unknown type, maybe not initialized
SIM/UIM card does not support hot swapping. If the API returns
Notes: RET_NOSIM, then power down the terminal, insert the SIM card and power up
the terminal again.

3.11.4 WnetSimPin
Prototype: uchar WNetSimPin(uchar *pin)
Enter SIM card PIN. If the WNetCheckSim () API return RET_NEEDPIN,
Function:
then call this API.
Input pin PIN (4 8 characters)
Parameters:
Output None
Parameters:
RET_OK 0X00 Success
RET_PARAMERR 0X0B Parameter error( PIN length error)
RET_NOSIM 0X04 IM card is not in the slot / not detected
RET_NEEDPUK 0X06 Required PUK code
RET_SIMBLOCKED 0X07 SIM card locked
RET_PINERR 0X09 PIN error
Return:
Notes:
3.11.5 WnetUidPwd
Prototype: uchar WNetUidPwd(uchar *Uid, uchar *Pwd)
Setting up user id and password. The user id and password should set up before
Function:
dialing.
Uid User id (less than 64 bytes long)
Input
Parameters: Pwd Password (less than 16 bytes long)
Output None
Parameters:

RET_OK 0X00 Success

RET_PARAMERR 0X0B Parameter error(user id/password length
error)
Return: RET_NORSP 0X02 No response returns from module
Notes: After module initialization, requiring to setup user id and password before dialing.
3.11.6 WnetDial
Prototype: uchar WNetDial(uchar *DialNum, uchar * reserved1, uchar * reserved2)
Check dialing status (succeed or fail). The API should be used after calling the
Function:
WNetDial () API (or WNetLinkCheck () API) which returned RET_OK.
DialNum Dailing number (CDMA is #777, GPRS is cmnet)
Input reserved1 Reserved

Parameters:
Reserved2 Reserved
Output None
Parameters:
RET_OK 0X00 Dail request accepted
RET_NOSIM 0X04 SIM card not exist
RET_LINKCLOSED 0X0E No Carrier
RET_PARAMERR 0X0B Parameter error()
RET_SIMERR 0X08 SIM CARD ERROR
RET_SNLTOOWEAK 0X0D Signal too weak
Return: RET_DETTACHED 0X15 Module cannot find network
As for the present GPRS and CDMA, the probability of failure of the first
dialing is relatively large after POS getting electricity, even if waiting for 20
seconds. In order to resolve this, the application can re-dial after the first dial is
Notes:
failure within 60 second of starting up.
R50-M please refers to S series wireless communication module.

3.11.7 WnetCheck
Prototype: uchar WNetCheck(void)
Check dialing status (success or fail). The API should be used after calling the
Function: WNetDial () API which returned RET_OK returns. The application requires to
implement its own time delay for checking the status.
Input None
Parameters:
Output None
Parameters:
RET_NOTDIALING 0X0A Module is not under dialing state
RET_LINKOPENED 0X0F Dialing connection success
RET_LINKCLOSED 0X0E Dialing connection fail (maybe Signal too
weak)
Return:
For the module MG815 of ZET, it supports 5 multi-connections.
For the module G20/G24 of Motorola, it supports 2 multi-connections.
Notes: For other modules, they support 5 multi-connections.
3.11.8 WNetTcpConnect
Prototype: uchar WNetTcpConnect(uchar *DestIP, uchar *DestPort)
Function: Connects with the specified IP address and port number
DestIP IP address (*.*.*.*, where 0*255)
Input
Parameters: DestPort Port number ( 0*65535)
Output None
Parameters:
RET_TCPOPENED 0X12 TCP session succeed
RET_TCPCLOSED 0X11 TCP session fail
RET_PARAMERR 0X0B Parameter error(IP address or port number
error)
RET_LINKCLOSED 0X0E Link is closed, required to re-dial again.
RET_LINKOPENING 0X10 Module is dialing
Return:

Notes: For CDMA module, if the connection is timeout, then the application will
use the WNetTcpCheck () API to check the TCP connection status. If the
return value is RET_TCPCLOSED, then the application will call the
WNetTcpConnect () again. If the return value is RET_TCPOPENING,
which implies the module is trying to open a socket requiring long time to
complete the process, then the application may call the WNetTcpClose()
and then call WNetTcpConnect() to re-open TCP socket.
For GPRS module, if the connection is timeout, then the application will
call WNetReset () to restart the module and then call re-dial and open TCP
socket again. (During GPRS module connection timeout, if calling
WNetTcpCheck (), the return value will be RET_TCPOPENED. But this
is only a false connection and the module does not open the socket
successfully. Besides, this false connection cannot be closed with
WNetTcpClose (). In order to reduce the waiting time delay, the application
can reset the module)
Please check the target host is ready for connection if the connection failure
persistent.
3.11.9 WNetTcpTxd
Prototype: uchar WNetTcpTxd(uchar *TxData, ushort txlen)
Function: Transmits those data with specified length via the TCP mode.
TxData Transmit data
Input txlen Length of the transmit data
Parameters: (CDMA maximum packet size is 1024 bytes)
(GPRS maximum packet size is 1370 bytes)
Output None
Parameters:
RET_OK 0X00 Succeed
error)
RET_TCPCLOSED 0X11 TCP is disconnected
Return: RET_TCPOPENING 0X13 Connecting TCP session
Notes: Before transmitting data, dial link should be set up beforehand and open TCP

Socket. If the connection is not always successful, please first inspect the target
host whether can connect.
3.11.10 WNetTcpRxd
Prototype: uchar WNetTcpRxd(uchar *RxData, ushort *prxlen, ushort ms)
Function: The received data length will store in *prxlen and received data in RxData.
RxData Received data
Input prxlen Length of the received data

Parameters:
ms Timeout time
Output None
Parameters:
Return: RET_OK 0X00 Received data succeed
RET_TCPCLOSED 0X11 protocol stack error, TCP closed
Notes: P78, R50, P58, R30 and R100 do not support this API.
3.11.11 WNetTcpClose
Prototype: uchar WNetTcpClose(void)
Function: Close the opened TCP socket
Input None
Parameters:
Output None
Parameters:
RET_TCPCLOSED 0X11 TCP is disconnected
Notes: If return RET_TCPCLOSED, it means TCP connection is closed; if return

RET_OK, it means TCP connection is not be closed, it only sends disconnection

order to module (this is required by application).
3.11.12 WNetClose
Prototype: uchar WNetClose(void)
Function: Closes the dialing connection
Input None
Parameters:
Output None
Parameters:
RET_LINKCLOSED 0X0E Link is closed
Return: RET_UNKNOWNTYPE 0X18 Unknown type, maybe not initialized
If return RET_TCPCLOSED, it means TCP connection is closed; if return

Notes: order to module (this is required by application).
3.11.13 WNetLinkCheck
Prototype: uchar WNetLinkCheck(void)
Checks dialing connection status (connected, disconnected or dialing) and this
Function:
API can be called in any time.
Input None
Parameters:
Output None
Parameters:
RET_LINKOPENED 0X0F Link is connected
RET_LINKCLOSED 0X0E Link is closed

If return RET_TCPCLOSED, it means TCP connection is closed; if return

Notes: order to module (this is required by application).
3.11.14 WNetTcpCheck
Prototype: uchar WNetTcpCheck(void)
Function: Check TCP connection status and this API can be called in any time.
Input None
Parameters:
Output None
Parameters:
RET_TCPOPENED 0X12 TCP session connected
RET_TCPCLOSED 0X11 TCP session closed
RET_TCPOPENING 0X13 Connecting TCP session
RET_RSPERR 0X03 If the module returns ERROR and the
dialing session is closed, and then this API will return RET_RSPERR.
Return:
GPRS module does no support RET_TCPOPENING return value.
3.11.15 WNetReset
Prototype: uchar WNetReset(void)
Reset the module and required to call WNetInit () after completed the reset
Function:
operation.
Input None
Parameters:
Output None
Parameters:
RET_OK 0X00 Success
Return: RET_PORTINUSE 0XFE Port engaged
Reset function always happens in abnormal error occurs.

GPRS module should be reset before connection when TCP Socket timeout.
Notes:

3.11.16 WNetSendCmd
Prototype: uchar WNetSendCmd(uchar *cmd, uchar *rsp, ushort rsplen, ushort ms)
Function: Application can transmit AT commands to wireless module directly.
cmd AT command (ended with \r).
rsp Wireless module return value

Input
rsplen Length of the return value (Note: When using GMR, GMI, GMM
Parameters:
or CGMR, CGMI, CGMM, the length of the return value without
the limitations of rsplen) As the receiving buffer of rsp, the buffer
space must more than 100 bytes.
ms Timeout for the wireless module return response.
Output None
Parameters:
Return: RET_OK 0X00 Succeed
RET_PARAMERR 0X0B Parameter error
3.11.17 WNetMTcpConnect
Prototype: uchar WNetMTcpConnect(int *psocket, uchar *DestIP, uchar *DestPort)
Build TCP connection with specific destination address and destination port, and
Function:
return socket connection handle.
Psocket socket connection handle
Input DestIP IP address (*.*.*.*, 0*255)

Parameters:
DestPort port number (0*65535)
Output None
Parameters:

Return: RET_TCPOPENED 0X12 TCP connection is built

RET_TCPCLOSED 0X11 TCP connection is failed
error)
RET_LINKCLOSED 0X0E network connection fails, and re-dial is
needed
RET_LINKOPENING 0X10 module is dialing
Notes: For ZTE CDMA module MG815, there will be maximum FIVE
multi-connection supported;
For Motorola module G20/G24, there will be maximum TWO multi-connection
supported;
3.11.18 WNetMTcpTxd
Prototype: uchar WNetMTcpTxd(int socket, uchar *TxData, ushort txlen)
Transmit specific length of data by TCP connection (via the specific socket
Function:
connection )
Socket socket that uses in the transmission
Input TxData data that needs to be sent

Parameters:
txlen data length (maximum 1024 bytes for one CDMA transmission;
and maximum 1370 bytes for one GPRS transmission)
Output None
Parameters:

RET_OK 0X00 data successfully sent.

error)
needed
RET_TCPCLOSED 0X11 TCP connection lost
Return:
RET_TCPOPENING 0X13 module is opening up TCP connection
Before data transmission, dial is to be successfully connected, and
multi-connection TCP Socket is opened.
Notes:
3.11.19 WNetMTcpRxd
uchar WNetMTcpRxd(int socket, uchar *RxData, ushort maxlen, ushort
Prototype:
*prxlen, ushort ms)
Data is transmitted by socket, and if data is successfully received, the length of
Function:
data will be stored in *prxlen; data will be stored in RxData.
Socket socket connection number
maxlen maximum length of buffer

Input
Parameters: prxlen length of data that received
ms overtime limit
Output RxData data that received

Parameters:
RET_OK 0X00 data successfully received
Return: RET_PORTERR 0XFD Port error
RET_TCPCLOSED 0X11 protocol stack error, TCP closed
Notes:

3.11.20 WNetMTcpClose
Prototype: uchar WNetMTcpClose(int socket)
Function: Close the opened TCP Socket (multi-connection)
Input Socket socket connection handle
Parameters:
Output None
Parameters:
RET_OK 0x00 the request of close accepted
needed
RET_PARAMERR 0X0B Parameter error, error occur while the value
of socket is outside the range from 2 to 4
Notes:
3.11.21 WNetMTcpCheck
Prototype: uchar WNetMTcpCheck(int socket)
Function: Check TCP connection status, and it can be called at any time
Input Socket socket connection handle
Parameters:
Output None
Parameters:
RET_TCPOPENED 0X12 TCP connection is built
RET_TCPOPENING 0X13 TCP connection is being setup
RET_RSPERR 0X03 If the module returns ERROR and the
dialing session is closed, and then this API will return RET_RSPERR.
RET_NORSP 0X02 Module timeout and no response, but
Return: telephone call can still connect.
RET_PARAMERR 0X0B Parameter error, error occur while the value
of socket is outside the range from 2 to 4

GPRS module does no support RET_TCPOPENING return value.

3.11.22 WPhoneCall
Prototype: uchar WPhoneCall(uchar *PhoneNum)
Function: Makes phone call actively.
Input Telephone number of other side, in string form ended
PhoneNum
Parameters: with 0x00, length range [1, 50].
Output
None
Parameters:
RET_OK Succeed
RET_PARAMERR Parameter error, telephone number length is invalid.
RET_RSPERR Module returns ERROR
RET_NORSP Module timeout and no response, but telephone call
can still connect.
RET_PORTERR Port error
RET_PORTINUSE Port engaged
RET_ABNORMAL Abnormal error
Return: RET_UNKNOWNTYP Unknown type, maybe not initialized
E
RET_SIMERR SIM card error or require PIN code
RET_SNLTOOWEAK Signal too weak
RET_DETTACHED Module cannot find network
RET_DIALING Dial fails, another dial is processing.
RET_BUSY Dial fails, in connection status.
RET_RING Dial fails; module receives calling information while
not processes.
Dial success means sending telephone number to network is validated, and it
does not mean the other side picks up the phone.
Notes: Do not support multi-side communication function.
There should be more than 1 second span between two calls.
P80, P78, R50, P58, R30, R50-M and R100 do not support this API.
3.11.23 WPhoneHangUp
Prototype: uchar WPhoneHangUp(void)
Function: Phone hang-up actively. All kinds of calling can be hung up.
Input
None
Parameters:
Output
None
Parameters:
Return: RET_OK Succeed


RET_NORSP No response returns from module
RET_UNKNOWNTYP Unknown type, maybe not initialized
E
There should be more than 1 second span between two calls.
Notes:
3.11.24 WPhoneStatus
Prototype: uchar WPhoneStatus(void)
Function: Checks phone line status
Input
None
Parameters:
Output
None
Parameters:
RET_OK No action of phone channel(able to call)
Return:
RET_UNKNOWNTYP Unknown type, maybe not initialized
E
RET_DIALING A dial is processing.
RET_BUSY In phone connection process.
RET_RING Module receives dialing information, and waits for
connection or hang-up.
This function is used for checking phone and connection status.
Notes:
3.11.25 WPhoneAnswer
Prototype: uchar WPhoneAnswer(void)
Function: Answers the phone
Input
None
Parameters:
Output
None
Parameters:
RET_OK Succeed
Return: RET_RSPERR Module returns ERROR or not calling mode.


RET_UNKNOWNTYPE Unknown type, maybe not initialized
Notes: P80, P78, R50, P58, R30, R50-M and R100 do not support this API.
3.11.26 WPhoneMicGain
Prototype: uchar WPhoneMicGain(uchar Level)
Function: Adjust mic sound level
Mic sound level, range [0, 3]. The bigger the value is,
Input
Level the higher the sound is. Value exceeds range is dealt
Parameters:
as the maximum value.
Output
None
Parameters:
RET_OK Succeed
Return: RET_PORTERR Port error
3.11.27 WPhoneSpkGain
Prototype: uchar WPhoneSpkGain(uchar Level)
Function: Adjust earphone sound level
Earphone sound level, range [0, 4]. The bigger the
Input
Level value is, the higher the sound is. Value exceeds range
Parameters:
is dealt as the maximum value.
Output
None
Parameters:
RET_OK Succeed
Return: RET_PORTERR Port error

3.11.28 WPhoneSendDTMF
Prototype: uchar WPhoneSendDTMF(uchar DTMFNum, ushort DurationMs)
Function: Sends DTMF signal during phone.
DTMF signal sent, whose range is 0~9,
DTMFNum
A~D,*,#;
Input
Time span for sending DTMF in ms. Range [0,
Parameters:
DurationMs 60000], and recommended value is 100ms. It is
strongly recommended to not change this value.
Output
None
Parameters:
RET_OK Succeed
RET_PARAMERR Parameters error, no DTMF signal.
RET_RSPERR Module returns ERROR or not in phone status.
Return:
Only one DTMF signal can be sent once. If several signals need sending, call this
function circularly.
Notes:
This function can be used for user sound hint calling, such as telephone charge.
3.11.29 Notes for Wireless Module

After sending data, only receive return value operation can be done, do not implement other
wireless module API (including phone function), otherwise, received data may lose.
Considering delay identity, receive timeout should be set more than 60 seconds. If only small part
(about 2%) timeout error is permitted, then timeout should be more than 30 seconds.
The maximum received data package of GPRS (G20) is 1372 bytes, and for CDMA (MG815), it is
536 bytes. If application receives the maximum length, it should decide according to other
conditions (for example, information inside package) whether enough length has been received. If
it is not enough, call receiving data function again till enough length has been received. Because
connect packages is several dependent data package receive, so each time should set the same
timeout. No other wireless modules API can operate during receive data continuously.
In order to increase transaction success rate, it should retry dialing three times, tcp links three
times.
3.11.30 API Sample of Wireless Module

The following is a sample of showing how to set common interfaces. Meanwhile, it differs from
case to case in practice, and developers are advised to use above function tables as reference.
// initialization
WNetInit ();

// detect SIM card

WNetCheckSim ();
// detec signal
WNetCheckSignal (&SignalLevel);
// set user password
WNetUidPwd ("uid", "pwd");
// dial, TCP connection, data transmit, data receive, close TCP connection, close dialing
//1.dial
WNetSendCmd ("at+gmi\r", rsp, 50, 2000);
if (ucRet == RET_OK)
{
if (strstr ((char *) rsp, "ZTEiT MODEM"))
WNetType = WNET_CDMA;
else if (strstr ((char *) rsp, "Motorola"))
WNetType = WNET_GPRS;
else
{
Lcdprintf ("module type error");
getkey ();
return;
}
}
else
{
Lcdprintf ("abnormal error");
getkey ();
return;
}
if (WNetType == WNET_CDMA)
ucRet = WNetDial ("#777", "", "");
else if (WNetType == WNET_GPRS)
ucRet = WNetDial ("cmnet", "", "");
else
{
Lcdprintf ("Module type error");
getkey ();
return;
}
for (i=0; i<30; i++) //30 is the dialing time, which is adjustable for
//real cases. 30 is recommended, since it might take 6 seconds for CDMA, and 3 //seconds for
GPRS.
{
Lcdprintf ("%d", i); //show the number of trials, which is equal to time(s)
ucRet = WNetCheck ();

if (ucRet == RET_LINKOPENED)
break;
if (ucRet == RET_NORSP)
{
DelayMs (1000); //other delay method can be applied as well
continue;
}
switch (ucRet)
{
case RET_NOTDIALING:
Lcdprintf ("module not in dialing mode");
break;
case RET_LINKCLOSED:
Lcdprintf ("dial failure");
break;
case RET_PORTERR:
Lcdprintf ("serial port error");
break;
case RET_ABNORMAL:
Lcdprintf ("abnormal error");
break;
default:
Lcdprintf ("default");
break;
}
getkey (); return;
}
if (i==30)
{
Lcdprintf ("dial timeout");
getkey (); return;
}
ScrSetIcon (1, 1);
//2.TCP connection
ucRet = WNetTcpConnect ("218.17.93.165", "60180");
//3.Data transmit
WNetTcpTxd
("0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz012345678
9ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123", 128);
//4.Data receive
WNetTcpRxd (RxData, &rxlen, 8000);
if (ucRet! = RET_OK) {
getkey (); return;
}

//5.Close TCP connection

ucRet = WNetTcpClose ();
if (ucRet! = RET_TCPCLOSED)
{ getkey (); return;
}
//6.Close dialing
ucRet = WNetClose ();
if (ucRet! = RET_LINKCLOSED)
}
ScrSetIcon (1, 0);
}
void ResetModule (void)

{
int i;
ucRet = WNetReset ();
if (ucRet != RET_OK)
}
DelayMs (3000);
WNetInit ();
}
3.11.31 Wireless Module Phone API Example

This example shows use of common interface only for reference. In actual development, refer to
above API according to the specified environment and deal with different return values.
This example simulates a simple phone application, which has functions like ringing, connecting,
and hang-up, dialing DTMF input (for charging or choosing according to sound hint). This is for
demonstration only.
//initialize first
WNetInit ();
//check SIM card
WNetCheckSim ();
//check signal
WNetCheckSignal (&SignalLevel);
void TestWPhoneSimulate (void)

{
uchar ret, status;
uchar CallNow=2;
uint ret_event;
uchar PhoneNum [100];

ScrCls ();
ScrPrint (0, 0, 0x80, Simulate Phone App );
ScrSetIcon (1, CallNow);
memset (PhoneNum, 0, sizeof (PhoneNum));
while (1)
{
status = WPhoneStatus ();
if (status == RET_RING)
{
Beep_Prompt ();
ScrPrint (0, 7, 0x00, "Ring... ");
}
else if (status == RET_BUSY)
{
CallNow = 1;
ScrPrint (0, 7, 0x00, "In Use ");
}
else if (status == RET_OK)
{
CallNow = 2;
ScrPrint (0, 7, 0x00, "Ready ");
}
else if (status == RET_DIALING)
{
ScrPrint (0, 7, 0x00, "Dialing ");
}
ret = 0;
ret_event= PowerSave (EVENT_OVERTIME | EVENT_KEYPRESS, 100);
if (ret_event & EVENT_KEYPRESS)
{
ret = getkey ();
}
if (ret == KEYUP) ret = '*';
if (ret == KEYDOWN) ret = '#';
if (ret == KEYCLEAR) memset (PhoneNum, 0, sizeof (PhoneNum));
if (ret == KEYCANCEL)
{
if (status == RET_OK) return; // return
else
{


WPhoneHangUp ();
}
}
if (ret == KEYENTER)
{
if (status == RET_RING)
{
WPhoneAnswer ();
}
if (status == RET_OK)
{
ScrPrint (0, 6, 0x00, "Dial...");
WPhoneCall (PhoneNum);
}
}
if (ret=='*' || ret=='#' || (ret>='0' && ret<='9'))
{
PhoneNum [strlen (PhoneNum)] = ret;
if (status == RET_BUSY)
WPhoneSendDTMF (ret, 100);
}
ScrClrLine (2, 6);
ScrPrint (0, 2, 0x00, "%s", PhoneNum);
}
}
3.12 PPP Protocol Interface Functions
All API of this module are completely apply to P80, apply partly to P78 and P90, and not suitable
to R50, P58, R30, R50-M and R100.
Specification of this module: The module is the API to realize the relevant operating of PPP
protocol.
PPP protocol is a popular and general name; actually it means the TCP/IP cluster based on PPP link
layer protocol.
The PPP link layer of P78 is carried out on physical dialing line. The process of calling application
is to call MODEM dialing interface to set up asynchronous physical link, and then to call a group
of PPP added functions to exchange data with remote.
Presently, the PPP of P78 is carried out in block pattern, and the operation of unblock pattern is
retained in the interface.
Through parameter setting, local can work in client pattern (common application), and in server
pattern (special application).
Local does not provide the operations of PING remote, while support the operation of remote PING

local.
The definition of that structure is:
1) typedef struct
{
uchar connected; //whether the appointed link handle is connected, 1-yes, 0-no
uchar remote_closed; //whether the remote of appointed link is closed, 1-yes, 0-no
uchar has_data_in; //whether the receiving buffer of the appointed link has data, 1-yes,
0-no
uchar outbuf_emptied; //whether the receiving buffer of the appointed link is null, 1-yes,
0-no
ushort left_outbuf_count; //the maximum bytes that can be sent
uchar remote_addr [4]; //remote IP address
uchar reserved1 [30]; //Reserve field 1
int link_state; //link state:
// -23-link disconnected,-24-not logged in, 0-normal
uchar local_addr [4]; //local IP address
uchar dns1_addr [4]; //the IP address of DNS1
uchar dns2_addr [4]; //the IP address of DNS2
uchar gateway_addr [4]; //the IP address of gateway
uchar subnet_mask [4]; //subnet mask
uchar reserved2 [30]; //Reserve field 2
} PPP_NET_INFO;
2) typedef struct
{
uchar IsSync; // 0- asynchronization connection, 1- synchronization connection
uchar ConnectTimeout; //connection timeout, 0-default value is 45 seconds
uchar SpeedType; //0-maximum GSM default speed, for G20/G24 maximum speed is
9600 bps
//1-1200, 2-2400, 3-4800, 4-7200, 5-9600, 6-12000, 7-14400, //8-19200, 9-24000,
10-26400, 11-28800, 12-31200, 13-33600,//14-48000, 15-56000bps,
0xff- Automatic Baud Rate
uchar AsyncFormat; // 0-8N1, 1-8E1, 2-8O1, 3-N71, 4-7E1, 5-7O1
uchar IdleTimeout; //idle time until hang up: 10 seconds, 0 means //never hang up
uchar DialTimes; // length of dial time, 0- default value is 1
uchar DisableXonXoff; // XonXoff flow-control software, 0-enable, //1-prohibit
uchar ServiceType; // service type: 0-PPP, 1-asynchronization, other //values reserved
uchar Reserved [50]; // reserved, all will be filled with 0
} GSM_CALL;
3.12.1 NpppLogin
Prototype: int NpppLogin(char *user_name,char *user_password)
Initialize parameters of PPP link and internet; switch from MODEM data
Function:
channel to PPP channel, and set up PPP link; set up LCP link and submit

username and password, and do IPCP interactive communication.

user_name Input users name, no more than 32bytes
Input
Parameters: user_password Input users password, no more than 32bytes
Output None
Parameters:
1- Success
1-255Dialing failure, the same with ModemDial
300Initialization failure of PPP internet.
400Initialization failure of PPP port.
490-- Users name is more than 32 bytes.
491-- Users password is more than 32 bytes.
501MODEM is in the idling status of no link.
502-- MODEM is in the synchronous status.
503Prompt overtime when receive username input(the time length is 10
seconds)
504-- After receiving the prompt of inputting username, the line is
disconnected
505-- Prompt overtime when receive password input (the time length is 3
seconds).
506-- After receiving the prompt of inputting password, the line is
disconnected
Return:
507Channel switch abnormal error
-23Link is disconnected.
-27LCP link connection failure (LCP: Link Control Protocol)
-28Username/password authentication failure.
-29IPCP interactive communication error (IPCP: IP Control Protocol)
OthersAbnormal errors
From V81K Version of P80, deleting the following return code caused by
the change of login mode:
//503--Prompt overtime when receive username input(the time length is 18
seconds)
//504--After receiving the prompt of inputting username, the line is
disconnected
//505--Prompt overtime when receive password input (the time length is 3
seconds)
//506--After receiving the prompt of inputting password, the line is
disconnected
Call this function right after the dialing function. If it is pre-dial, wait for
connection in this function and then carry out logging in operation.
After calling this function successfully, calling data sending function
Notes:
ModemTxd ( ) will not succeed, but calling data receiving function
ModemRxd ( ) can monitor (not capture) line data.
R50, P58, R30, R50-M and R100 do not support this API.

Example:
char tmpc;
int tmpd;

memset (&modem_config, 0x00, sizeof (modem_config));
modem_config.SSETUP=0x87; //Async connection and 26s connection
timeout
modem_config.AsMode=0xd0;//Expect 33.6kbps connection speed
tmpc=ModemDial (&modem_config, 9, 96169, 1);

if (tmpc) return 1;
tmpd=NpppLogin (96169, 96169);

if (tmpd) return 2;

3.12.2 NpppOpen
int NpppOpen(uchar *remote_addr,ushort remote_port, ushort
Prototype:
local_port,uchar mode)
Function: Set up a TCP/IP or UDP/IP link with remote in client or server pattern
remote_addr Appoint remote IP address or name; if used as server, than set
*, means can support the link request from any clients.
remote_port Appoint remote port number; the port number is used by TCP
protocol layer; if used as server, than set 0
Input local_port Appoint local port number
Parameters: mode Appoint link pattern, and always set 0. Indicate block pattern,
TCP/IP protocol cluster
D00:block pattern,1:unblock pattern
D2D100:TCP/IP,01:UDP/IP,others:reserved
Other bitsreserved, it should be set 0
Output None
Parameters:
>=0 Succeed; the link handle is returned, and is used in the following
data accessing operation
Return: -12 Operation overtime
-23 Link is disconnected
Others<0 Opening failure
Once log in succeed, this function can be called.
This function can be called with different parameters, and set up many (no
more than 50) links, which are independent with each other
Notes:
Accordingly, the link which calling this function can be closed by
PppClose ().

Example 1: Common usage, used as client

char tmpc;
int tmpd, hd;

if (tmpc) return 1;

if (tmpd) return 2;
hd=NpppOpen (192.128.0.125, 2005, 100, 0);

if (hd<0) return 3;

Example 2: Special usage, used as server

char tmpc;
int tmpd, hd;

if (tmpc) return 1;
tmpd=PppLogin (96169, 96169);

if (tmpd) return 2;
hd=PppOpen (*, 0, 100, 0);

if (hd<0) return 3;

3.12.3 NpppWrite
Prototype: int NpppWrite(int connect_handle, uchar *buf, ushort len)
Function: Send an appointed length of data block on the appointed link to remote
connect_handle Appoint an existing link handle
Input buf Point to the head of data block pending to deliver

Parameters:
len Appoint the byte number of data block pending to deliver
Output None
Parameters:
>0 Succeed; the actual byte number sent successfully this time is returned
=0 Sending failure
Others<0 Sending error

Only if the appointed link handle is valid presently (already set up and not be
closed), calling this function can succeed.
The most data block sent once is 1518 bytes; if the data block is too big, it
Notes: should be divided into several data blocks less than 1518, and then sent one by
one. Before sending, the sending buffer should be checked all along, and begin
sending after it is empty
Example:
char tmpc, pool [2000];
int tmpd, hd;
ushort dn;

if (tmpc) return 1;

if (tmpd) return 2;
hd=NpppOpen (192.128.0.125, 2005, 100, 0);

if (hd<0) return 3;
dn=1000;
tmpd=NpppWrite (hd, pool, dn);
if (tmpd! =dn) return 4;
3.12.4 NpppRead
Prototype: int NpppRead(int connect_handle,uchar *out_data,ushort len)
Receive an appointed most length of data block on the appointed link from
Function:
remote
connect_handle Appoint an existing link handle
Input
Parameters: len Appoint the byte number of data block pending to receive.
Output out_data Point to the head of a data buffer, used to output data pending
Parameters: to receive
>0 Succeed; the actual byte number received successfully this time is returned
=0 Receiving buffer is empty
Others<0 Receiving error
Only if the appointed link handle is valid presently (already set up and not
Notes: be closed), calling this function can succeed.
The most data block received once is 1518 bytes; if the data block is bigger

than this or the remote not send data continuously, then this function should
be called several times, and the data block should be joined in turn
Example:
char tmpc, pool [2000], tmps [2000];
int tmpd, hd;
ushort dn, rn;

if (tmpc) return 1;

if (tmpd) return 2;
hd=NpppOpen( 192.128.0.125, 2005, 100, 0);

if (hd<0) return 3;
dn=1000;
while (1)
{
tmpd=NpppRead (hd, tmps, sizeof (tmps));
if (tmpd<0) return 5;
if (tmpd>0) break;
}
rn=tmpd;

3.12.5 NpppCheck
Prototype: void NpppCheck(int connect_handle,PPP_NET_INFO *pi)
Function: Read relative node address, subnet mask , and appointed link status
Input connect_handle Appoint a link handle
Parameters:
Output pi Point to a structure buffer PPP_NET_INFO, used to output
Parameters: present status of current network and link
Return: None
If not log in or the connection is closed, only link_state of the returning

information is valid.
Notes:
If the link handle is invalid at present (not set up or is closed), only the
fields after link_state (including field link_state) of the returning

information are valid.

be closed), calling this function can return the current status of the link.
That is, only when connected=1, the fields in this structure (except reserve
fields) is valid.
Example:
int tmpd, hd;
ushort dn, rn, i;
PPP_NET_INFO pi;

if (tmpc) return 1;

if (tmpd) return 2;
NpppCheck (-1, &pi); // Read relative node address, subnet mask
hd=NpppOpen (192.128.0.125, 2005, 100, 0);

if (hd<0) return 3;
dn=1000;
i=0;
while (1)
{
NpppCheck (hd, &pi); // Read link and buffer status
if (pi.has_data_in)
{
tmpd=NpppRead (hd, tmps+i, 1);
if (tmpd! =1) return 5;
i++;
if (i>=dn) break;
}
}
rn=tmpd;


3.12.6 NpppClose
Prototype: int NpppClose(int connect_handle)
Function: Close the appointed link
Input connect_handle Appoint an existing link handle
Parameters:
Output None
Parameters:
0 Succeed
-12 Operation overtime
Return:
-24 Not log in or initialize.
-25 Not opened link number
Others<0 Fail
be closed), calling this function can succeed.
After the appointed link is closed, calling the function (read, write and
check status) will fail.
The link is closed, while PPP link will be still in the opening status.
Notes:
For all the existing links, after visiting, it is recommended to close these
links one by one by calling the function continuously, and then close
physical line through hanging up, in order not to trap remote in abnormal
status.
Example:
char tmpc, pool[2000], tmps[2000];
int tmpd, hd;
ushort dn, rn,

if (tmpc) return 1;
if (tmpd) return 2;
hd=NpppOpen (192.128.0.125, 2005, 100, 0);
if (hd<0) return 3;
dn=1000;
while (1)
{
if (tmpd<0) return 5;
if (tmpd>0) break;
}

rn=tmpd;
NpppClose (hd);
OnHook ();
return 0;
3.12.7 NpppProcess
Prototype: void NpppProcess(void)
Used in unblock pattern, carry out data package disposing process of every
Function: protocol layer, including correlative operations of unpacking, encapsulation and
package delivery.
Input None
Parameters:
Output None
Parameters:
Return: None
If use block pattern to operate, then do not need to pay attention to and call
this function.
In current PPP implementation, besides physical layer use interruption,
Notes: other layer protocols all adopt polling pattern. So if operate in unblock
pattern, in order to maintain good running of every protocol layer, this
polling function have to be called frequently.
3.12.8 GsmCallModem
int GsmCallModem(GSM_CALL *CallPara, uchar *TelNo, uchar
Prototype:
*ErrMsg)
Function: exchange data in remote modem loop for GSM module

CallPara call input parameters GSM_CALL

If pointer *CallPara is NULL, it means that all variables of
the pointer will become 0.
ConnectTimeout variables are only used for defining
connection timeout, which do not include the detection time
of module initialization and module registration. Variables
are usually less than 200 ms. The function only supports
MOTOROLA G20 or G24 GSM module, and it can be used
for 9600bps or 4800bps connection speed.
SpeedType variables indicate the connection speed for GSM
Input
module and remote modem. Current values of 0, 6, and 7
Parameters:
within the module are valid, and other invalid values would
be default set to 7.
In GSM PPP communication, ServiceType variables are set
to 0. When it is used in GSM remote modem
asynchronization communication, and PortSends () and
PortRecv () directly communicate with the data between
GSM module and remote modem, ServiceType will be set to
1.
AsyncFormat variables currently only support 0, for
instance, 8N1 format.
TelNo Represent telephone number, and TelNo will be pointed to
the string ended with \0.
The string can store multiple telephone numbers, and every
two numbers will be separated by ;. For example,
12345678; 87654321.
Furthermore, the string cannot be an empty string.

ErrMsg Output parameter that shows error message. The pointer

could be NULL, which means there will be no error
message; or at least 50 bytes buffer.
At the time of dialing and connecting, GSM logo will flash at
constant speed. When the connection is built, buzzer logo
will flash several times to indicate the connection speed.
SpeedType field is used for current connection. For example,
flashing for four times means that the connection speed is
4800bps, and five times represent 9600 bps.
Output If GSM connection is built after calling the function for the
Parameters: first time, it will return connection failure and disconnect
current connection.
If the PPP connection has been set up for any channel, such
as modem channel, the call from other channel (GSM
channel) will fail.
When the function is being executed, users can press
Cancel key to cancel the process of calling the function.
After dialing and connection setup, LANPORT channel will
be occupied, unless GsmOnHook( ) is being called to release
the resources.
0Connectiong is successfully built
1Pointer TelNo NULL, or pointer TelNo pointing to an empty string
2GSM connected
3PPP connection is occupied by other connections
4fail to open ports, two physical ports are probably occupied by other
resources
5GSM module initialization failed;
10No SIM card
11SIM card PIN needed
Return:
12SIM card PUK needed, SIM can be used again until it is unlocked;
32Network registration aborted;
33Network registration denied;
34Cannot register
39Network registration retry limit exceeded
50Cancel key abnormal
51No carrier wave, probably invalid code
52Busy
OthersReserved
GSM_CALL is defined as follow:
typedef struct
{
Notes:
uchar IsSync; // 0- asynchronization connection, 1- synchronization
//connection
uchar ConnectTimeout;// connection timeout, 0- default value is 45 //seconds

uchar SpeedType;//0- maximum GSM default speed, for G20/G24 //maximum

speed is 9600 bps
//1-1200, 2-2400, 3-4800, 4-7200, 5-9600, 6-12000, 7-14400, //8-19200,
9-24000, 10-26400, 11-28800, 12-31200, 13-33600, //14-48000, 15-56000 bps,
0xff- Automatic Baud Rate
uchar AsyncFormat; // 0-8N1, 1-8E1, 2-8O1, 3-N71, 4-7E1, 5-7O1
uchar IdleTimeout;// idle time until hang up: 10 seconds, 0 means never
hang-up
uchar DialTimes; // length of dial time,0- default value is 1
uchar DisableXonXoff;// XonXoff flow-control software, 0-enable,
//1-prohibit
uchar ServiceType; // service type:0-PPP,1-asynchronization,other values
reserved
uchar Reserved [50]; // reserved, all will be filled with 0.
}GSM_CALL;
P78, R50, P58, R30, R50-M and R100 do not support this API.
Example:
int tmpd, hd;
ushort dn, rn,
GSM_CALL cfg;

memset (&cfg, 0x00, sizeof (cfg));
cfg.ConnectTimeout=60;//set a timeout longer than default value
cfg.ServiceType=0;//Select PPP service based on GSM link
tmpd=GsmCallModem (&cfg, 96169, tmps);

if (tmpd)
{
ScrPrint (0, 4, 0,GSM CALL FAILED: %d, tmpd);
ScrPrint (0, 5, 0,%s, tmps);
DelayMs (3000);
return 1;
}

if (tmpd) return 2;
hd=NpppOpen (219.134.185.73, 2000, 3000, 0);

if (hd<0) return 3;
dn=1000;


if (tmpd<=0) return 5;
rn=tmpd;
NpppClose (hd);
GsmOnHook ( );
return 0;
3.12.9 GsmCheck
Prototype: int GsmCheck(void);
Function: Detect data connection status between remote modem and GSM module.
Input None
Parameters:
Output None
Parameters:
0 - GSM module is currently connected as remote object;
Return: 0x0b - GSM module is not currently connected as remote object;
Other values reserved.
No input parameters;
The status may not be available after connection between GSM module and
remote modem is built, since the remote will hang-up; or signal will be
lost. Driver will automatically detect connection events online;
Notes: It is not necessary to use this function in PPP communication application;
The function can detect current connection status before sending or
receiving data, when it is used for direct communication with port, in GSM
communication
Example:
int tmpd, hd;
ushort dn, rn,
GSM_CALL cfg;

cfg.ServiceType=1;//Select generic asynchronous communication service
based on GSM link
cfg.DisableXonXoff=1;//disable XON/XOFF software flow control between
the driver and
//GSM module


if (tmpd)
{
ScrPrint (0, 5, 0,%s, tmps);
DelayMs (3000);
return 1;
}
//--to send 1000 bytes

tmpd=GsmCheck ();
if (tmpd ==0x0b) return 2; //link is broken
dn=1000;
tmpc=PortSends (LANPORT, pool, dn);
if (tmpc) return 3;
//--to receive 1000 bytes

rn=0;
while (1)
{
tmpd=GsmCheck ();
if (tmpd ==0x0b) return 4; //link is broken
tmpc=PortRecv (LANPORT, tmps+rn, 0);

if (! tmpc)
{
rn++;
If (rn>=dn) break;
}
}
GsmOnHook ( );
return 0;
3.12.10 GsmOnHook
Prototype: int GsmOnHook(void);
Disconnect the exchange loop between GSM module and remote modem, and
Function: then close physical ports that are occupied by GSM module. Set the modem
channels for PPP connection.
Input None
Parameters:

Output None
Parameters:
0 successfully disconnect GSM module and remote modem via hang-up
command;
Return: 1 fail to open GSM channel; disconnected by hardware reset;
2 fail to use hang-up command; disconnected by hardware reset;
Others reserved.
No input parameters
The function has to be called at least one time after the conversation is
finished; otherwise, GSM module and remote modem will still be
connected and occupy the resources.
Notes:
It will still successfully disconnect and release, even the return is not 0. The
return cannot be ignored, no matter what kinds of errors exist in the
hang-up.
Example:
int tmpd, hd;
ushort dn, rn,
GSM_CALL cfg;

cfg.ServiceType=0;//Select PPP service based on GSM link

if (tmpd)
{
ScrPrint (0,5,0,%s, tmps);
DelayMs(3000);
return 1;
}
tmpd=NpppLogin(96169, 96169);
if(tmpd)return 2;
hd=NpppOpen( 219.134.185.73,2000,3000,0);
if(hd<0)return 3;
dn=1000;
memset(pool,0x55,dn);
tmpd=NpppWrite(hd, pool, dn);
if(tmpd!=dn)return 4;

tmpd=NpppRead(hd,tmps,sizeof(tmps));
if(tmpd<=0)return 5;
rn=tmpd;
NpppClose(hd);
GsmOnHook();//disconnects and releases the LANPORT channel

return 0;
3.12.11 NpppSetAuth
Prototype: int NpppSetAuth(ulong authent)
Function: Set the PPP login types
authent the PPP login types
There are four login types as follow:
Input #define PPP_ALG_PAP 0x1 /* PAP */
Parameters: #define PPP_ALG_CHAP 0x2 /* CHAP */
#define PPP_ALG_MSCHAPV1 0x4 /* MS-CHAPV1 */
#define PPP_ALG_MSCHAPV2 0x8 /* MS-CHAPV2 */
Output None
Parameters:
0 - successfully
Return:
Others parameters errors
Example:
NpppSetAuth (PPP_ALG_PAP | PPP_ALG_CHAP);
3.13 File System Operation
All API of this module are completely applied to P80, P90 and P58, apply partly to R50, P78,
R50-M, R30 and R100.
Specification of this module: The module is API to realize the relevant operating of file system,
which mainly includes establishing, reading, writing and deleting a document, changing document
and gaining document size and information.
P80 and R50 uses file system to manage memory. Parameter files, transaction logs and blacklist can
be stored in the files system. A system parameter file (SysPara) used to store system environment
variables is reserved for the system and can only be accessed by monitor. P80s file system is
(29+32)*64 k bytes in size and supports up to 256 files (0~255), including system files. System
files are: system parameter file, font files.
P80 and R50 support multi-application. Applications can access their own files only. Each
application has its own parameter file EnvFile.
When a file operation fails (returned -1), specific error reason can be obtained from global variable

errno read by GetLastError (), as the following:
Table 3-2 errno macro definition of error message code

Macro definition Value Notes
#define FILE_EXIST 1 File existed already
#define FILE_NOEXIST 2 File does not exist
#define MEM_OVERFLOW 3
#define TOO_MANY_FILES 4 Too many files
#define INVALID_HANDLE 5 Invalid file handle
#define INVALID_MODE 6
#define FILE_NOT_OPENED 8
#define FILE_OPENED 9
#define END_OVERFLOW 10
#define TOP_OVERFLOW 11
#define NO_PERMISSION 12
#define FS_CORRUPT 13
#define O_RDWR 0x01
#define O_CREATE 0x02
#define O_TRUNC 0x04
#define SEEK_CUR 0
#define SEEK_SET 1
#define SEEK_END 2
Data Structure for module:

typedef struct
{
unsigned char fid; /* File id */
unsigned char attr; /* File attribute */
unsigned char type; /* File type*/
char name [17]; /* File name */
unsigned long length; /* Length of the file */
} FILE_INFO;
3.13.1 open
Prototype: int open(char *filename, uchar mode)
Function: Opens current applications files
filename File name, up to 16 characters, ending with \x00; first 16
Input characters are used if filename is longer than 16.
Parameters: mode O_RDWR read / write
O_CREATE create a new file
Output None
Parameters:

>=0: Success, returns handle number (0 255)

-1: Failure, error code in errno
INVALID_MODE Mode is not O_RDWR or O_CREATE
FILE_NOEXIST File not found
Return: FILE_EXIST Attempt to open existing file with O_CREATE mode
MEM_OVERFLOW Insufficient memory
TOO_MANY_FILES Too many file handles, more than 255, unable to create
new file
FILE_OPENED File opened already

If mode is set to O_CREATE | O_RDWR, the file will be opened in O_RDWR
Notes: if it exists or created if it does not exist. Opened file can be re-opened, and file
pointer will move to the file head every time.
3.13.2 ex_open
Prototype: int ex_open(char *filename, uchar mode, char* attr)
Accesses application managers files, application manager can also use it to
Function: access plain applications files. A plain application cannot access other plain
applications files.
filename File name, up to 16 characters, ending with \x00, first 16 will
be used if filename is longer than 16.
mode Open mode
Input
O_RDWR Open for reading/writing
Parameters:
O_CREATE Open a new file
Attr Set attr [0] to 0x00 to access application managers files; set it
to AppNum to access corresponding applications files.
Output None
Parameters:
Return: Same as open function
Using O_CREATE can only create files of current application.
attr[0] - File owner, att[1] File type
File owner values:
0xFF monitor
0x00 application manager
01 application 1
02 application 2
Notes:

23 application 23
File Type:
Type File Type
0 Application Manager
1 Application
2 Font File

3 Library
4 Users File
System parameter file (constant file
5
name: SysPara)
6 Application parameter file
R30 and R100 do not support this API.
3.13.3 read
Prototype: int read(int fid, uchar *dat, int len)
Function: Reading File
Input fid File handle index, up to 255 (0 255)
Parameters: len Length of data to read.
Output dat Data buffer. Application is responsible for allocating space for
Parameters: it.
>=0: Read success, returns length of data read
-1: Failure; error code in errno(Reference to errno macro definition of error
Return: message code)
FILE_NOT_OPENED File not open
INVALID_FIELID Invalid file handle
Notes: None
3.13.4 write
Prototype: int write(int fid, uchar *dat, int len)
Function: Writing file
fid File handle index, up to 256 (0 255)
Input
len Length of data to be written.
Parameters:
dat Data buffer for writing
Output None
Parameters:
>=0: Write succeed, returns length of data written
message code)
Return:
FILE_NOT_OPENED File not open
MEM_OVERFLOW Insufficient memory or too many
Notes: None
3.13.5 close
Prototype: int close(int fid)
Function: Closing file

Input fid File handle index, up to 255 (0 255)

Parameters:
Output None
Parameters:
0: Successfully closed
Return:
message code)
Notes: None
3.13.6 seek
Prototype: int seek(int fid, long offset, uchar fromwhere)
Function: Moving File Pointer
fromwhere It can be SEEK_CUR, SEEK_SET or SEEK_END.

Input SEEK_CUR means from the current file pointer; SEEK_SET
Parameters: means from the beginning of the file; SEEK_END means from
the end of the file
offset The offset from the position specified by fromwhere to the
target position in bytes (singed value)
Output None
Parameters:
0: Success
-1: Failure; error code in errno
Return:
FILE_NOT_OPENED File not opened
END_OVERFLOW File end surpassed
TOP_OVERFLOW File head surpassed
Notes: None
3.13.7 filesize
Prototype: long filesize(char *filename)
Function: Getting File Size
Input filename Filename, up to 16 characters, ended with \x00, first 16
Parameters: characters will be used if the filename is longer than 16.
Output None
Parameters:
>=0:File size (in byte)
-1: Failure, error number in errno(Reference to errno macro definition of error
Return:
message code)
FILE_NOEXIST File does not exist

Notes: None
3.13.8 remove
Prototype: int remove(const char *filename)
Function: Deleting File
Output None
Parameters:
0:succeed
-1:fail, error code in errno(Reference to errno macro definition of error message
Return: code)
FILE_OPENED File opened already
FILE_NOEXIST File does not exist
Notes: None
3.13.9 freesize
Prototype: long freesize(void)
Function: Getting size of available filesystem space
Input None
Parameters:
Output None
Parameters:
Return: Size of the available file system space in bytes
Notes: None
3.13.10 InitFileSys
Prototype: void InitFileSys(void)
File system initialization kept for system and unnecessary to call in P70-S
Function:
applications.
Input None
Parameters:
Output None
Parameters:
Return: None
Notes: R50, R30, R50-M and R100 do not support this API.
3.13.11 Truncate
Prototype: int Truncate(int fid, int len)

Function: Truncating File

Input
Parameters: len File size (in bytes) after truncated
Output None
Parameters:
0:succeed
-1:fail, error code in errno(Reference to errno macro definition of error message
code)
NO_FILESYS File system not constructed
Return:
INVALID_FILEID Invalid file handle
FILE_NOT_OPENED File not opened
TOP_OVERFLOW Length is less than 0
END_OVERFLOW Length surpasses file size
This function truncates a file into length of len; the part from len to the end
Notes:
of the original file will be discarded.
3.13.12 Fexist
Prototype: int fexist(char *filename)
Function: Checking whether file exists
Output None
Parameters:
-1: Specified file not found in current application
Return:
other(0-255): File handle
Notes: None
3.13.13 GetFileInfo
Prototype: int GetFileInfo(FILE_INFO* finfo[])
Function: Getting information of all files
Input None
Parameters:
finfo The buffer for returned file information. Enough space (sizeof
Output
(FILE_INFO)256=7680 bytes) should be allocated so that
Parameters:
information of maximum files can be held.
>0:Number of files returned
-1:Failure, error number in errno(Reference to errno macro definition of error
Return:
message code)
NO_FILESYS File system not constructed
Notes: None

3.13.14 FileToApp
Prototype: int FileToApp(BYTE *strFileName)
Convert a normal application file to a application in the POS, the original file
Function:
will not be deleted
Input strFileName The file name need to be converted. The file must be the type
Parameters: of "bin".
Output None
Parameters:
0: OK, succeed.
-1: the pointer of file name (strFileName) is NULL or invalid.
-2 : Read file strFileName error
-3 : Seek file strFileName error
-4 : Open file strFileName error
Return:
-5: This file is not Application File.
-6: No space to save the application file.
-7: Create application file error.
-8: Open application file error.
-9: Seek application file error.
Notes: None
3.13.15 FileToParam
int FileToParam(uchar *strSrcFileName, uchar *strAppName, int
Prototype:
mode)
Function: Convert file to data or parameter file of a appointed appl.
strSrcFileNam The name of the file which need to be converted.
e
strAppName The app name which the output file is belong to after the
Input conversion.
Parameters: mode mode
=1 convert to a parameter file
=2 convert to a data file
=else other error.
Output None
Parameters:
0: successful
-1 : file pointer strFileName is null
-2 : file pointer strAppName is null
-3 : Parameters mode error
Return:
-4 : file strFileName open error
-5 : application strAppName is not exist
-6 : Create temporary file error
-7: Create parameters/data file error.

If mode=1, the name of the file that need to convert in parameter

Notes:
strSrcFileName must be "EnvFile".
3.13.16 FileToMonitor
Prototype: int FileToMonitor(BYTE *strFileName)
Convert data file into monitor program, and previous monitor program will be
overwritten. It shows that do not turn off when the file is being converted;
Function:
and user will be confirmed to turn off when the process is finished. The original
data file will not be erased even it has been successfully converted.
Input strFileName File name, which will be converted
Parameters:
Output None
Parameters:
0: successful
-1: file pointer strFileName is null
-2 : read error
-3 : file strFileName location error
Return: -4 : file strFileName open error
-5 : file strFileName is not monitorable file
-6: monitor program cannot be written into flash, probably flash is defective.
-7 : file strFileName is too big to be converted into monitor program
-8 : cannot meet safety standard
Successful execution of this function will not return. After restart, the system
Notes:
will run the new monitor.
3.13.17 ReadFontLib
Prototype: int ReadFontLib(ulong Offset, char *FontData, int ReadLen)
Function: Read the font data from the font file.
Offset Position of the font file.
Input
Parameters: ReadLen Length in bytes of reading.
Output FontData output buffer

Parameters:
0: Success.
Return:
-1 : No font
The font data output should be processed by application level.
Notes:
P78, R30 and R100 do not support this API.
3.13.18 DelAppFile
Prototype: int DelAppFile(uchar *AppName);
Delete an application of the terminal and the parameter file and user file that
Function:
belong to this application.

Input AppName The deleted application name, case-sensitive. The maximum

Parameters: size is 32 byte and ends with 0x00.
Output None
Parameters:
0: Success.
Return: -1:Parameter error
-2:Can not find this application
The application name is the same with AppInfo of application program project.
And is case-sensitive.
If the deleted application is the current application, this application cannot be
Notes:
loaded after restart.
P80 has supported this API.
3.14 Environment Variables Functions
All API of this module are completely applied to P80, P90, P78, R50, P58, R50-M and R30.
Specification of this module: The module is API to realize the relevant operating of environment
variables, which mainly includes reading and writing environment variables.
In P80, P90, P78, R50 and R50-M system, special parameter variable files are used to store
application variables. Predefined variable can be accessed by two functions in applications.
Environment variables are stored in a file named EnvFile. Every application has its own EnvFile,
and each application can access its own environment file. For the convenience of using
environment variables, two functions are provided to handle environment variables directly instead
of the file.
The content of the environment variable file is organized by records. Each record contains a
parameter name (8 bytes) ending with a \0 and a parameter value (120 bytes) ending with a \0.
3.14.1 GetEnv
Prototype: uchar GetEnv(char *name, uchar *value)
Function: Getting an environment variable
Input name Buffer pointer to get parameter name, 7 bytes at most; first 7
Parameters: bytes are used if longer.
value Buffer pointer to get parameter value, space assigned by
Output
caller. The buffer size must be no less than the length of
Parameters:
variable value.
0 - succeed
Return:
1 - Parameter name not found
Notes: None

3.14.2 PutEnv
Prototype: uchar PutEnv(char *name, uchar *value)
Function: None
name Buffer pointer to get parameter name, 7 bytes at most; first 7
Input bytes are used if longer.
Parameters: value Parameter value, space assigned by caller.
Output None
Parameters:
0 - succeed
Return: 1 - invalid parameters
2 - insufficient space
If the environment variable exists already, it will be overwritten. Value of
Notes:
parameter name should not be NULL or .
3.15 Encryption / Decryption Function
All API of this module are completely applied to P80, P90, P78, R50, P58 and R50-M, and apply
partly to R30 and R100.
Specification of this module: The module is API to realize the relevant operating of encryption and
decryption, which mainly includes DES, HASH and RSA encryption algorithm
3.15.1 des
Prototype: void des(uchar *input, uchar *output, char *deskey, int mode)
Function: DES encryption / decryption of 8 bytes
Input 8 bytes of input data.
Input
deskey 8 bytes of des key
Parameters:
mode 0-decryption ; 1-encryption
Output output 8 bytes of output data.
Parameters:
Return: None
Notes: This function performs encryption / decryption operation according to mode.
3.15.2 Hash
Prototype: void Hash(uchar* DataIn, uint DataInLen, uchar* DataOut)
Function: Outputs 20 bytes of hash result from a string of any length.
Input DataIn Pointer to the input buffer.
Parameters: DataInLen Length of the input data buffer(unit byte)
Output DataOut Pointer to the output data buffer
Parameters:

Return: None
This function uses safe Hash algorithm SHA-1 (ISO/IEC 10118-3 or FIPS
Notes: 180-1).
R30 and R100 do not support this API
3.15.3 RSARecover
int RSARecover(uchar *pbyModule, uint dwModuleLen, uchar
Prototype: *pbyExp, uint dwExpLen, uchar *pbyDataIn, uchar
*pbyDataOut)
Function: Performs RSA encryption operation
pbyModule Pointer to RSA module buffer.
dwModuleLen Module length (in unsigned char, values range from 1 to
256).
Input
pbyExp Pointer to the exponent buffer in RSA operation.
Parameters:
dwExpLen Exponent length (in unsigned char)
pbyDataIn Pointer to input data buffer, length is the same with
module length.
Output pbyDataOut Pointer to output data buffer, length is the same with
Parameters: module length.
0: succeed
-1:Input parameter error, pointer is NULL, error;
-2:dwModuleLen or dwExpLen is zero, error;
Return:
-3:dwModuleLen or dwExpLen is too big, error
-4:pbyDataIn is no less than pbyModule, error;
-5: dwExpLen is more than dwModuleLen, error.
This function performs RSA encryption / decryption operations; encryption and
decryption are performed by selecting different keys. If (Modul, Exp) is private
key, it encrypts; if public key is used, it decrypts. All data in the above
mentioned buffers are high-byte first and counted by unsigned char (8 bits).
Notes:
This function can perform RSA operation with data length less than 2048 bits.
DataIn must less than Module (namely satisfying memcmp (DataIn, Module,
ModulLen) <0), otherwise cant gain correct result.
R30 and R100 do not support this API
3.16 PED Functions
All API of this module are completely apply to P80, P58, apply partly to P90, and not suitable to
P78, R50, R30, R50-M, R100.
Specification of this module: The module is API to realize the relevant operating of PED.
Memory of PED storing keys can be divided into main key area, DES key area, working key
area, in which:
There are 800 bytes in main key area, which can store 100 DES or 50 3DES(16 bytes) or

33 3DES(24 bytes) main keys;

There are 800 bytes in working key area, which can store 100 DES or 50 3DES(16 bytes)
or 33 3DES(24 bytes) working keys;
There are 800 bytes in DES key area, which can store 100 DES or 50 3DES (16 bytes) or
33 3DES (24 bytes) working keys.
Key ID is the index of PED storing main keys or working keys.
Key ID has one to one mapping relation with actual physical storage. For example, keyed
is main key, then 8 bytes after keyid=1 corresponding main key area are storing area, 8 bytes
after keyid=2 corresponding main key area are storing area,, and 8 bytes after keyid=100
corresponding main key area are storing area. It is the same with working keys and DES keys.
For example, 8 bytes after keyid=1 corresponding main key area are storing area, 8 bytes after
keyid=2 corresponding main key area are storing area, , and 8 bytes after keyid=100
corresponding main key area are storing area. Other index values are invalid.
Note:
Keys in PED are stored in SRAM, and application layer cannot visit the area. Before the
monitor renewing, it will delete PED keys automatically for keys security protection.
Regulation about all the input port in PED: application layer clears LCD first and displays
prompting information, and then calls SCRGOTOXY function to set lines and alignment
manner of input character (when X<64, left-alignment, otherwise, right-alignment);if there is
timeout limit, calling input operation timeout setting first, and calling corresponding input
interface function at last.
3.16.1 PEDInputTimeOut
Prototype: void PEDInputTimeOut(ulong timeoutsec)
Function: Sets input operation(like amount, PIN, character) timeout time(unit:second)
Input timeoutsec =0: no timeout
Parameters: >0: timeout time(unit: second)
Output None
Parameters:
Return: None
System defaults to no timeout.
Setting this function will have effect on GETSTRING interface at the same
Notes:
time
3.16.2 PEDInput
Prototype: uchar PEDInput(uchar *str, uchar min, uchar max, uchar mode)
Output string whose length is no less than min and no more than max on PED
Function:
LCD
min Must input length
Input
max Maximum input length [maximum 40]
Parameters:
mode =1 only display * when inputting

=0 input and display the character when inputting

Output str Output string, ended with \0 [output data]
Parameters:
0x00 Correct
0x03 Invalid mode
0x05 String input length range invalid
Return:
0x06 Operator[or user] cancels input
0x07 Input timeout
0xce PED locked
Can be used to input plaintext PIN, and displaying symbol is *
Because there is an unsafe question in that interface, so it will be cancelled in
Notes:
the future.
P78, R50, R30, R50-M and R100 do not support this API!
3.16.3 PEDGetPwd
uchar PEDGetPwd(uchar PinKeyID, uchar min, uchar max, uchar
Prototype:
*cardno, uchar *pin, uchar TwiceInput)
Function: Input password whose length is [min,max] on the PED LCD
TwiceInput =0 PED prompts inputting the password once
=1[none-0] PED prompts inputting the password twice
PinKeyID Count working key of PIN
Input
min Password input minimum length [0=<min<=14]
Parameters:
max Password input maximum length [0=<max<=14 &&
max>=min]
cardno 16-bit card number after removing [ASCII code]
Output pin Encrypted password [output data]
Parameters:
0x00 Correct
0x02 Key index invalid
0x03 Invalid mode
Return: 0x06 Operator[or user] cancels input
0x07 Input timeout
0x09 Two passwords not the same
0x0a User not input password(input password length is 0)
0x0b Appointed key not existed
0xce PED locked

When TwiceInput=0, this function makes user input account password.

After inputting password and pressing confirmation, keypad will encrypt
key in ANSI X9.8 standard and PIN key appointed by PinKeyID.
When TwiceInput=1, this function makes user input account password.
After inputting password and pressing confirmation, user should input
password again. If they are the same, then keypad will encrypt key in
ANSI X9.8 standard and PIN key appointed by PinKeyID, or it will
prompt error.
Notes:
If min=0 and there is no any input, press confirm on PED, and the
function will return 0x00.
Prompt information on LCD is decided by application layer. This function
only gets current line values of the cursor, and displays(take up 2 lines).
Before using this function, call ScrGotoxy(x, y) to set input character
taking up line number.
Card number length must reach 16 bits.
3.16.4 PEDGetPwd_3Des
uchar PEDGetPwd_3Des(uchar PinKeyID, uchar min, uchar max, uchar
Prototype:
*cardno, uchar *bPinLen, uchar *pin)
Function: Input password whose length is [min,max] using 3 DES encryption
PinKeyID count working key of PIN(working keys area)
Input min password input minimum length [0=<min<=14]
Parameters: max password input maximum length [0=<max<=14 && max>=min]
cardno 16-bit card number after removing(ASCII code)
Output bPinLen password length[output data, min=<bPinLen <=max]
Parameters: pin encrypted password[output data]
0x00 correct
0x03 Invalid mode
Return: 0x07 Input timeout
0x09 Two passwords not the same
0x0b Appointed key not existed
0xce PED locked
0xff Key in memory verification error
Notes: P78, R50, R30, R50-M and R100 do not support this API!
3.16.5 PEDWriteMKey
Prototype: uchar PEDWriteMKey(uchar KeyID, uchar mode, uchar *Key)

Function: Store Key[plaintext] in the master keys area appointed by KeyID

KeyID Storing main keys index [ 1 100]
mode =0x01 DES key [8bytes]
Input
=0x03 3DES key [16bytes]
Parameters:
=0x07 3DES key [24bytes]
Key Key value
Output None
Parameters:
0x00 Correct
Return: 0x03 Invalid mode
0xce PED locked
0xf0 Verify keys error (write failed)
3.16.6 PEDWriteDKey
Prototype: uchar PEDWriteDKey(uchar DESKeyID, uchar mode, uchar *Key)
Function: Store Key[plaintext] in the DES keys area appointed by DESKeyID
DESKeyID Storing main keys index [1 100]
mode =0x01 DES key [8 bytes]
Input
=0x03 3DES key [16 bytes]
Parameters:
=0x07 3DES key [24 bytes]
Key Key value
Output None
Parameters:
0x00 correct
0xce PED locked
3.16.7 PEDWriteWKey
uchar PEDWriteWKey(uchar MKeyID, uchar WKeyID, uchar mode,
Prototype:
uchar *Key)
Use main key or working key appointed by MKeyID to do decryption in mode
Function: to working key appointed by MKeyID, and store result in working keys area
appointed by WKeyID
MKeyID: Main keys index [ 1 100 or 0]
Input
WKeyID: Storing working keys index [1 100 ]
Parameters:
Mode =0x01 DES encryption
=0x03 3DES(16 bytes) encryption


=0x81 DES decryption
=0x83 3DES(16 bytes) decryption
Key Key value
Output None
Parameters:
0x00 Correct
0x03 Invalid mode
Return:
0x0b Appointed keys not exist
0xce PED locked
MkeyID=0, do not encrypt/decrypt Key. Store Key into position appointed
Notes: by WKeyID directly
3.16.8 PEDDeriveKey
uchar PEDDeriveKey(uchar MKeyID, uchar WKeyID1, uchar WKeyID2,
Prototype:
uchar mode)
Use main key or working key appointed by [MKeyID&0x7F] to do derivation
Function: in mode to working key appointed by WKeyID1, and store result in working
keys area appointed by WKeyID2
MKeyID Main key or working key index [1 100] does or operation
with symbol bit, and symbol bit is distinguished by the highest
bit of MKeyID. That is:
If MKeyID =index, then use main key to derive
If MKeyID =index|0x80, then use working key to derive
WKeyID1 Working key needs derived index(1 100)
Input
WKeyID2 Storing working key index(1 100)
Parameters:
mode =0x01 DES encryption
=0x81 DES decryption
Output None
Parameters:
0x00 Correct
Return:
0x03 Invalid mode
0xce PED locked

When using the work Key to do derivation, do not support 3des algorithm.
Notes:
3.16.9 PEDDes
uchar PEDDes(uchar DESKeyID, uchar mode, uchar *datain, uchar
Prototype:
*dataout)
Use DES key appointed by DESKeyID to do encryption/decryption in mode to
Function:
datain, and store the result in dataout
DESKeyID: Working keys index [1 100]
mode =0x01 DES encryption
Input =0x07 3DES(24 bytes) encryption
Parameters: =0x81 DES decryption
datain Data needs encrypting [input data]
Output dataout result [output data]
Parameters:
0x00 Correct
0xce PED locked
3.16.10 PEDMac
uchar PEDMac(uchar WKeyID, uchar mode, uchar *datain, ushort inLen,
Prototype:
uchar *macout, uchar flag)
Use working key appointed by WKeyID to do MAC operation to datain, and
Function:
store the result in macout.
WKeyID: Working key index (1 100)
datain Data package requires MAC operation [input]
inLen Length of MAC operation data package [inLen <2048]
mode MAC algorithm:
Input
0x01 DES encryption
Parameters:
0x03 3DES(16 bytes) encryption
flag 0x00 algorithm 1
None 0 algorithm 2
Output macout MAC output(8 bytes) [output]
Parameters:
Return: 0x00 Correct

0x01 Data package length invalid

0x03 Invalid mode
0xce PED locked
0x0c Key in memory verification error
Divide message data into several 8-byte BLOCK, and the last BLOCK
having less than 8 bytes can add 0x00.
Algorithm 1: Does DES/3DES encryption with MAC key to BLOCK1,
the result do Xor operation with BLOCK2, and then using MAC key to do
Notes: DES/3DES encryption. An 8-byte encrypting result will be gotten.
Algorithm 2: do Xor operation between BLOCK1 and BLOCK2, and the
result do Xor operation with BLOCK3, and so on. At last get 8-byte
result, then using MAC key to do DES/3DES encryption.
3.16.11 EPSPEDAmount
uchar EPSPEDAmount(uchar point_mode, uchar prompt_mode, uchar
Prototype:
min, uchar max, uchar *Amt)
Function: [EPS special function] Input amount
min The minimum length of string [If it is 0 and does not have any
input, please entry "ENTER" key and return.]
max The maximum length of string [max<=14&&max>=min]
Input point_mode 0X00:Two digits after the decimal point;
Parameters: 0X01:Three digits after the decimal point;
0X02:No decimal point;
prompt_mode This parameter is temporarily disabled [Due to no prompt, it
can be any value].
Output Amt The amount
Parameters:
0x00 Correct
0x02 No key index input Parameters
0x03 Invalid mode
Return: 0x05 String input length range invalid
0x07 Input timeout
0xce PED locked

When min=0 and entry "ENTER" key without any input, the return
amount is follow:
When Point_mode=0x00,the content in Amt is0.00
Notes:
When Point_mode=0x01,the content in Amt is0.000
When Point_mode=0x02,the content in Amt is0
P78, P90, R50, R30, R50-M and R100 do not support this API!
3.16.12 EPSPEDLoadTMK
uchar EPSPEDLoadTMK(uchar WkeyID1, uchar *TmpKey, uchar
Prototype:
*KTMK, uchar *ReferCode)
[EPS special function] POS generates TmpKey, uploads it to host and gets
KTMK and ReferCode. Use temporary key to decrypt KTMK and the result is
TMK, which should be consistent with odd Parity.
Function:
TMK encrypts "\x12\x34\x56\x78\x90\x12\x34\x56", and result should be the
same with encrypting reference value; at last, write TMK into working key area
appointed by (WkeyID1).
WkeyID1 The position number that TMK will write into (1100)
TmpKey POS generates temporary KEY[8 Bytes],
Input
KTMK Get decrypted message [8 Bytes] from host.
Parameters:
ReferCode Return value [8 Bytes] of host using KTMK to encrypt
"\x12\x34\x56\x78\x90\x12\x34\x56".
Output None
Parameters:
0x00 Correct
0x0d Odd parity error
Return:
0x0e TMK error
0xce PED locked
0x0b The key that point to does not exist.
The TMK, TPK and MAK are stored in working key area, thus we should be
pay attention on this situation when arrange the key number, in order to avoid
Notes:
that some key will be replaced by other key.
3.16.13 EPSPEDLoadKey
uchar EPSPEDLoadKey(uchar WKeyID1, uchar WKeyID2, uchar
Prototype:
*KKEY)
[EPS special function] Using TMK in WkeyID1 to decrypt the new cipher
text that download from the host, the plain text must be consistent with odd
parity, then write it to WkeyID2. There are two cases, which are as follows:
Function:
1.Update TMK [When WkeyID1 equal to WkeyID2]: Download key "KKEY",
use plain text TMK to decrypt KKEY and get the plain text TMK2, which is
consistent with odd parity, and write TMK2 to WkeyID2, that means replace

TMK1.
2. Download TPK [When WkeyID1 unequal to WkeyID2]: Download key
"KKEY", use plain text TMK to decrypt KKEY and get the plain text
TPK, which is consistent with odd parity, and write TPK to WkeyID2.
WkeyID1 The position number of the TMK that used to decrypt or be
Input updated (1~100)
Parameters: WkeyID2 The position number of the key that need to load(1~100)
KKEY The cipher text that download from host[8 Bytes]
Output None
Parameters:
0x00 Correct
Return: 0x0d Odd parity error
0xce PED locked
Notes:
that some key will be replaced by other key.
3.16.14 EPSPEDGetMAC1
Prototype: uchar EPSPEDGetMAC1(uchar MKeyID, uchar *Random)
[EPS special function] Using TMK in MkeyID to encrypt Random [8bytes,
Function: consistent with odd parity, using as "output MAK"], which is sent by POS, and
storing the result in Random [8bytes].
MkeyID The position number that used to encrypt TMK (1100).
Input
Random Random number [Input data] or the return encryption result
Parameters:
[Output data] [8bytes].
Output Random Random number [Input data] or the return encryption result
Parameters: [Output data] [8bytes].
0x00 Correct
0xce PED locked
Notes: P78, P90, R50, R30, R50-M and R100 do not support this API!
3.16.15 EPSPEDUpdateTPK
uchar EPSPEDUpdateTPK(uchar WKeyID1,uchar WKeyID2, uchar
Prototype:
*pin_block, uchar *ISN, uchar *new_TPK)
[EPS special function] When the encrypt data packet uploads to the host, if the
Function:
TPK in host has been changed or need to recalculate pin block, it will call this

function. The detailed process is as followed:

1.When WkeyID1 equal to WkeyID2 [ WKeyID1 is the position number of
TPK ], PED uses original TPK to decrypt pin_block according to X3.92 and
get the plain text PIN, then uses original TPKISN to encrypt plain text PIN
according to X3.92, and return new pin_blockPED.
[Note: Due to no change TPK, parameter new_TPK can be filled without any
data]
2.When WkeyID1 not equal to WkeyID2 [ WKeyID1 is the position number of
TMK, WKeyID2 is the position number of TPK ], PED uses original TPK to
decrypt pin_block according to X3.92 and gets the plain text PIN, then uses
TMK to decrypt new_TPK and gets plain text TPK[consistent with odd
parity] to replace original TPK. At last, uses TPK, ISN to encrypt plain text
PIN according to X3.92, and return new pin_block.
WKeyID1 The position number of TMK / TPK (1100)
WKeyID2 The position number of TPK(1100)
Input pin_block PIN encrypted packet [8bytes]. It also returns the updated
Parameters: encrypted packet. [Input, output data].
ISN The transaction serial number [ASCII code with 6bytes]
new_TPK The updated TPK cipher text [8bytes]
Output pin_block PIN encrypted packet [8bytes].It also returns the updated
Parameters: encrypted packet. [Input, output data].
0x00 Correct
0xce PED locked
Notes:
that original key will be replaced by other key.
3.16.16 EPSPEDSetMAC2
uchar EPSPEDSetMAC2(uchar WKeyID1, uchar WKeyID2, uchar
Prototype:
*MAC2, uchar *rsp_data, uchar rsp_data_len, uchar *rsp_MAC)
[EPS special function] If MAC2 ["Enter MAK"] in the host has been changed,
this interface should be called first when the host returns the data. The detailed
process is as followed:
Using TMK in WKeyID1 to decrypt the new downloaded cipher text
Function:
MAC2.Then using plain text MAC2, which should be consistent with odd
parity, to do MAC operation with the new downloaded data rsp_data. The first 4
byte of result should be equal with the downloaded data rsp_MAC. At last,
write the plain text MAC2 into WKeyID2.
Input WKeyID1 The position number of TMK (1100)

Parameters: WKeyID2 The position number of MAC(1~100)

MAC2 The new downloaded cipher text MAC2 [8bytes]
rsp_data The downloaded data [rsp_data_len Bytes]
rsp_data_len The length of rsp_data[rsp_data_len<=233]
rsp_MAC The downloaded data that use for comparison [8 byte, ASCII
String].
Output None
Parameters:
0x00 Correct
0x01 The length of data packet invalid
0x0f "Enter MAC" error
0xce PED locked
If want to use this function, the length of Mac data packet should not
exceed 233 bytes when using interface PEDMac ().
The TMK, TPK and MAK are stored in working key area, thus we should
be pay attention on this situation when arrange the key number, in order to
Notes: avoid that original key will be replaced by other key.
After download the data that use for comparison, it needs to transform the
first 4 bytes to ASCII string and copy the 8 bytes ASCII string to
parameter rsp_MAC.
3.16.17 EPSPEDVerifyTMK
Prototype: uchar EPSPEDVerifyTMK(uchar MKeyID, uchar *VerifyData)
[EPS special function] Use TMK to encrypt "\x12\x34\x56\x78\x90\x12\x34\
Function:
x56" and return the result.
Input MkeyID The position number of TMK (1100)
Parameters:
Output VerifyData The result after encrypt (8byte)
Parameters:
0x00 Correct
Return:
0xce PED locked
3.16.18 EPSPEDGetPwd
uchar EPSPEDGetPwd(uchar PinKeyID, uchar min, uchar max, uchar
Prototype:
*ISN, uchar *pin)

Function: [EPS special function] Enter password with length[min,max]

PinKeyID Calculate the working key of PIN (1~100)
min The minimum length of the password [0=<min<=6]
Input
max The maximum length of the password [0=<max<=6&&min<=
Parameters:
max]
ISN Transaction serial number ISN [6 Bytes, ASCII string].
Output pin The encrypted password [Output data,8bytes]
Parameters:
0x00 Correct
Return:
0x07 Input timeout
0xce PED locked
3.16.19 PED_PassWordEncrypt
uchar PED_PassWordEncrypt(uchar deskeyid,uchar *oldpin,uchar
Prototype:
*despin)
[EPS special function] Use the DES key DESKEYID specified and the fixed
Function:
key in PED to encrypt OLDPIN and store the result in DESPIN.
Input deskyid DES key index number in PED
Parameters: oldpin The unencrypted PWD string (ASCII, length<=16)
Output
despin The encrypted PWD string(8 bytes)
Parameters:
02 Key index error
Return: 05 Parameter (PWD string) invalid
00 Success
EPS application must forbidden obtaining the unencrypted data through
key enter when LCD display the sensitive character or graphic character
(PIN, PASSWORD).
This interface can enter and modify user management key when uses
Notes: coordinated with the following input interface.
This interface will compare the data that obtain from encrypting
initialization management key in plain text with the data that obtain from
input interface.
3.16.20 PED_PassWordInput
Prototype: Uchar PED_PassWordInput(uchar deskeyid,uchar min,uchar max,uchar

*inpin)
[EPS special function]Use the DES key DESKEYID specified and the fixed
Function:
key in PED to encrypt the entered PWD and store the result in INPIN.
deskeyid DES key index number in PED
Input min The minimum length of pwd.
Parameters: max The maximum length of pwd.
Output inpin The encrypted PWD string(8 bytes)

Parameters:
02 Key index error
05 Parameter invalid
0A input password length is 0
Return:
06 Operator cancels input
07 Input timeout
00 Success
3.16.21 SYLPEDGetPwd
uchar SYLPEDGetPwd(uchar PinKeyID, uchar min, uchar max, uchar
Prototype:
*bPinLen, uchar *pin_block)
Function: [SYL special function] input password whose length is [min,max] on PED
PinKeyID Count working key of PIN (1100)
Input
min Password input minimum length [0=<min<=6]
Parameters:
max Password input maximum length [0=<max<=6&&min<=max]
Output bPinLen Password length [output data, 0=<bPinLen <=6].
Parameters: pin_block Encrypted PIN output [output data, 8bytes]
0x00 Correct
Return: 0x06 Operator[or user] cancel input
0x07 Input timeout
0xce PED locked
Algorithm defined by SYL: password length is no longer than 6Bytes, and
PIN_BLOCK format is FFFFFFFFFFPPPPPP. Password is
right-alignment, if its length is 0, then uses 6 0 to fill, otherwise use Fto
fill. Transform PIN_BLOCK into BCD code and then use PIN to encrypt,
Notes:
and the result is stored in pin_block;
This function will return the password length for applications to control
conveniently the illegal password length.

3.16.22 SYLPEDVerifyDerive
uchar SYLPEDVerifyDerive(uchar MKeyID, uchar WKeyID, uchar
Prototype:
*new_WKey, uchar *KeyCv, uchar mode)
[SYL special function] use main key appointed by MKeyID to encrypt/decrypt
new_WKey in mode get new key. Use this key to DES encryption for the
Function: \x00\x00\x00\x00\x00\x00\x00\x00, and compare the result with key
verifying data. If the same, then write new keys into working keys area
appointed by WkeyID.
MKeyID Store main keys index (1100)
WKeyID Derived key storing index (1100)
new_WKey Verify and derive keys [8Bytes, cryptograph]
KeyCv Key verify data [8Bytes]
mode Encryption/decryption mode:
Input
0x01 DES encryption
Parameters:
0x81 DES decryption
0x83 3DES(16 bytes) decryption
0x87 3DES(24 bytes) decryption
Output None
Parameters:
0x00 Correct
0x03 Invalid mode
Return:
0x11 Key verification illegal
0xce PED locked
3.16.23 SYLPEDCalcPinBlock
uchar SYLPEDCalcPinBlock(uchar MKeyID, uchar PinKeyID, uchar
Prototype:
*pin_block, uchar *new_TPK, uchar mode)
[SYL special function] use working key appointed by PinKeyID to decrypt
pin_block, and then use main key to encrypt/decrypt new_TPK in mode using
Function:
main key appointed by MKeyID and get new key. Use this key to encrypt
pin_block.
MKeyID Store TMK index
Input PinKeyID Store TPK index
Parameters: pin_block PIN encrypted data [8Bytes,cryptograph]
new_TPK New PIN key[8Bytes,cryptograph]

mode Encrypting mode:

0x01 DES encryption
0x81 DES decryption
Output None
Parameters:
0x00 Correct
0xce PED locked
3.16.24 SYLPEDLoadTMK
uchar SYLPEDLoadTMK(uchar MkeyID1, uchar *TmpKey, uchar
Prototype:
*KTMK, uchar *ReferCode)
[SYL special function] POS generates TmpKey, uploads it to host and gets
KTMK and ReferCode. Use fixed key [inside P90 and not published at
present] to decrypt temporary KEY, and then using decrypting result as key to
decrypt KTM again to get TMK; TMK encrypts
Function:
"\x12\x34\x56\x78\x90\x12\x34\x56", and result should be the same with
encrypting reference value; at last, if the highest bit of MkeyID1 is 0, then
write TMK into main key area appointed by (MkeyID1&0x7F), otherwise
write TMK into working key area appointed by (MkeyID1&0x7F).
MkeyID1 Main keys or working keys index (1-100) makes or operation
with symbol bit, and symbol bit is distinguished by the highest
bit of MkeyID1, that is:
MkeyID1 equals to (index), then it is main key;
Input MkeyID1equals to (index|0x80), then it is working key.
Parameters: TmpKey POS generates temporary KEY [8 Bytes]; it must be used after
decryption.
KTMK Get decrypted message [8 Bytes] from host.
ReferCode Return value [8 Bytes] of host using KTMK to encrypt
"\x12\x34\x56\x78\x90\x12\x34\x56".
Output None
Parameters:
0x00 Correct
Return: 0x02 Key index invalid
0x0e TMK error
Other
values
Main keys are written in the main key area, which is used to download main
Notes: keys of P80 remotely.

3.16.25 PEDManage
Prototype: uchar PEDManage(uchar mode, uchar *pwdcode)
Other function management functions of PED mainly include: verifying super
Function: management keys, verifying unlock keys, locking and unlocking keypad,
editing super management keys group, and editing unlock keys.
mode 0 Verify super management keys, in which pwdcode is
8-byte verifying value; if verifying succeeds, then
system will unlock keypad icon automatically and update
super keys and unlock keys.
1 Verify unlock keys, in which pwdcode is an 8-byte
verifying value; if verifying succeeds, then system will
unlock keypad icon automatically and update unlock
Input
keys.
Parameters:
2 lock keypad operation
0x80 Edit super management keys, in which PWDCODE is
made up of new management keys (8 bytes).
0x81 Edit unlock keys, in which PWDCODE is made up of
new management keys (8 bytes).
pwdcode Depend on the value of mode
Output None
Parameters:
0x00 Succeed/The value of mode is illegal.
Return: 0xf0 Verify keys error
0xf1 Edit privilege error( should verify keys correctly beforehand)
3.17 Multi-application Management Functions
All API of this module are completely applied to P80, P78, P90, R50, P58 and R50-M. R30
monitor has two types: one supports single application and the other supports multi-application.
R100 only support to multi-application. All the API in this module is only apply to R30 and R100
that supports multi-application.
Specification of this module: The module is API to realize the multi-application management.
P80P78P90R50 supports multi-application, thus an application manager is needed. The
application manager is an application itself. The only special point is that the application manager
is assigned index 0 and can access files of the other plain applications [index 1~23] and it can call
and run other applications. Functions related to application manager are described in this section.
Application manager should be developed according to specific application requirements.
Data Structure for module:
typedef struct
{
unsigned char AppName [32]; /* Application name*/

unsigned char AID [16]; /* Application ID*/

unsigned char AppVer [16]; /* Application Version*/
unsigned char AppProvider [32]; /* Application Provider*/
unsigned char Descript [64]; /* Application description */
unsigned char DownloadTime [14]; /* Application DownloadTime */
unsigned long MainAddress; /* Main function address main ()*/
unsigned long EventAddress; /* Event address event_main ()*/
unsigned char AppNum; /* Application Number */
unsigned char RFU [73]; /* Reserved */
} APPINFO;
3.17.1 ReadAppInfo
Prototype: int ReadAppInfo(uchar AppNo, APPINFO* ai)
Function: None
Input AppNo: Handle of application to be inquired (0-23).
Parameters: AppInfo: Pointer to returned information.
Output None
Parameters:
0 Success
Return:
-1 Fail
This function gets information of specified application. Each application
program has to define the global variable const APPINFO AppInfo in source
Notes:
code. And the AppInfo can be accessed directly in the application. To get the
other applications information, should use this API function.
3.17.2 ReadAppState
Prototype: unsigned char ReadAppState(uchar AppNo)
Function: None
Input AppNo: Handle of application to be inquired 0~23
Parameters:
Output None
Parameters:
Bit 0: 0--No application 1--Application exists
Bit 1: 0Unactivated 1--Activated
Return:
Bit 2: 0--Never run before 1--Has run for at least once.
0xff: Failure in getting application status
Notes: This function gets status information of specified application
3.17.3 SetAppActive
Prototype: int SetAppActive(uchar AppNo, uchar flag)
Function: None

AppNo: Handle of application to be inquired (0~23)

Input
Parameters: flag: 0 --Inactivated application
1 --Activate application
0 Success
Return:
-1 Failure
Notes: Only application is existing, then the activation status can be set.
3.17.4 RunApp
Prototype: int RunApp(uchar AppNo)
Function: None
Input AppNo: Handle of application to be switched to (1~23)
Parameters:
Output None
Parameters:
Return: Switched applications return value.
Notes: From current operation environment switch to the specified application.
3.17.5 DoEvent
Prototype: int DoEvent(uchar AppNo, ST_EVENT _MSG *param)

Function: None
Input AppNo: The application serial number (1~23)
Parameters: param: Event handling parameter.
Output None
Parameters:
Return: Result of event handling is determined by the application
Turn to event handling program of a specific application. If the application
Notes: does not need to handle any event, a NULL event handler is required to be
defined.
3.18 IP Operation Function
3.18.1 Module Return Code List

Value Macro Description
0 NET_OK No error
-1 NET_ERR_MEM Out of memory
-2 NET_ERR_BUF Buffer error
-3 NET_ERR_ABRT Try to establish connection fail.
-4 NET_ERR_RST Link is reset(Receive Reset)
-5 NET_ERR_CLSD Link off

-6 NET_ERR_CONN Link has not established.

-7 NET_ERR_VAL Variable error
-8 NET_ERR_ARG Parameter error
-9 NET_ERR_RTE Route error
-10 NET_ERR_USE Address or port already in use
-11 NET_ERR_IF Underlying hardware error
-12 NET_ERR_ISCONN Link already been established.
-13 NET_ERR_TIMEOUT Timeout.
-14 NET_ERR_AGAIN Resource does not exist. Please try
again.
-15 NET_ERR_EXIST Already exist.
-16 NET_ERR_SYS System does not support.
-17 NET_ERR_PASSWD Wrong password
-18 NET_ERR_MODEM Dial fail.
-19 NET_ERR_LINKDOWN Link disconnected, please dial again.
-20 NET_ERR_LOGOUT Logout
-21 NET_ERR_PPP PPP disconnected.
-22 NET_ERR_STR String too long.
-23 NET_ERR_DNS DNS cannot be resolved
-24 NET_ERR_INIT Initialization not successful.
-30 NET_ERR_SERV PPPoE Server cannot be found.
3.18.2 NetSocket
Prototype: int NetSocket(int domain, int type, int protocol)
Function: Create net socket, as create a connection handle
domain Fixed value:NET_AF_INET
type NET_SOCK_STREAM or NET_SOCK_DGRAM;
Parameters: NET_SOCK_STREAM means use TCP;
NET_SOCK_DGRAM means use UDP
protocol Fixed value: 0
Success return >=0, the value is the socket you created.

Return:
Fail return<0, the value is error code.
Notes: Only Support P90
3.18.3 NetBind
Prototype: int NetBind(int socket, struct net sockaddr *addr, socklen_t addrlen)
Function: Bind IP address or port number
socket Socket
addr Address, including IP address and port.
Parameters:
Suggest using the system interface SockAddrSet to initialize.
This field is not allowed NULL.

addrlen The value is fixed as sizeof(struct net_sockaddr)
Success return 0;
Return:
1 This interface can either bind the IP address or not. If not bind IP address,
use 0 to represent.
Notes:
2 This interface always works with interface NetListen.
3 Only Support P90
3.18.4 NetConnect
Prototype: int NetConnect(int socket, struct net_sockaddr *addr, socklen_t addrlen)
Function: Use as client, start to connect server.
socket Socket
addr Server address information, including IP address and port.
Parameters:
addrlen The value is fixed as sizeof(struct net_sockaddr)
Success return 0;
Return:
3.18.5 NetListen
Prototype: int NetListen(int socket, int backlog)
Function: Use as server and start to listen
socket Socket
Parameters: backlog The length of the queue for waiting connection, the value must
<=5
Success return 0;
Return:
3.18.6 NetAccept
Prototype: int NetAccept(int socket, struct net_sockaddr *addr, socklen_t *addrlen)
Function: Receive the connection from client.
socket Socket
addr Server address information, including IP address and port. Please

refer to Appendix 5.1.8 for the structure definition.
Suggest using the system interface SockAddrSet to extract IP
Parameters: address information and Port information.
addrlen Point to the space for storing address length, the address length is
fixed as sizeof (struct net_sockaddr).

Success return >=0, indicate the socket that connect to client successful. Then can
Return: use this socket to communicate with client.
3.18.7 NetSend
Prototype: int NetSend(int socket, void *buf, int size, int flags)
Function: Send data
socket Socket
buf Buffer
Parameters:
size Data length, the value must be <=10240(10K)
flags The current value is 0
Successfully return the send data length.
Return:
Fail return<0
Only use when socket type is NET_SOCK_STREAM.
Notes:
Only Support P90
3.18.8 NetSendto
int NetSendto(int socket, void *buf, int size, int flags, struct net_sockaddr
Prototype:
*addr, socklen_t addrlen)
Function: Send data
socket Socket handle
buf Buffer.
size Data length. For UDP protocol, the value must <=1024(1K)
flags The current value is 0

Parameters:
addr Address information, including IP address and Port. Please refer to
Appendix 5.1.8 for structure definition.
addrlen Fixed as sizeof(struct net_sockaddr)
Success return the send data length ;

Return:
Only use when socket type is NET_SOCK_DGRAM.
Notes:
Only Support P90
3.18.9 NetRecv
Prototype: int NetRecv(int socket, void *buf, int size, int flags)
Function: Receive data
Parameters: socket Socket

buf Buffer
size Length of the buffer.
Success return the received data length ;;

Return:
Only use when socket type is NET_SOCK_STREAM.
Notes:
Only Support P90
3.18.10 NetRecvfrom
int NetRecvfrom(int socket, void *buf, int size, int flags, struct sockaddr
Prototype:
*addr, socklen_t *addrlen)
Function: Receive data
socket Socket
buf Buffer
size Length of the buffer.
flag 0
addr Address and port information of data.

Parameters:
Please refer to Appendix 5.1.8 for the structure definition.
Suggest using the system interface SockAddrGet to extract IP
address information and Port information.
addrlen Point to the space for storing address length, the address length is
fixed as sizeof (struct net_sockaddr).
Success return the received data length ;
Return:
3.18.11 NetCloseSocket
Prototype: int NetCloseSocket (int socket)
Function: Close socket
Parameters: socket Socket handle
Success return 0;
Return:
Fail return <0
The handle, which is created by NetScoket, it must be closed by calling
Notes: NetCloseSocket, otherwise, it will lead to the failure of socket created.
Only Support P90

3.18.12 Netioctl
Prototype: int Netioctl(int socket, int cmd, int arg)
Function: Set and get the information of socket;
socket Socket
cmd Operation command, the supported as follow:
1. CMD_IO_SET:Set I/O mode(Block mode and asynchronous
mode);
2. CMD_IO_GET:Get I/O mode;
3. CMD_TO_SET: Set timeout. when the I/O mode is block,
the default timeout is 2 seconds;
4. CMD_TO_GET:Get timeout;
5. CMD_IF_SET: Socket binds the network interface. When
socket is as server, this command is invalid.
6. CMD_IF_GET: Get the network interface that binds the
network. When socket is as server, this command is invalid.
7. CMD_EVENT_GET: Get socket even. This command only
valid for NET_SOCK_STREAM. The possible event is as
Parameters:
follow:
SOCK_EVENT_READ:readable data;
SOCK_EVENT_WRITE:be able to send data;
SOCK_EVENT_CONN:connect has succeeded;
SOCK_EVENT_NETACCEPT:new connection;
8. CMD_BUF_GET:Read the buffer, this command is used to
get the system information of protocol, and only valid for
NET_SOCK_STREAM;
9. CMD_FD_GET: Get the idle handle number, and the
application can know whether there is handle reveal or not.
10. CMD_KEEPALIVE_SET: Set KeepAlive function of sock.
This command only valid for NET_SOCK_STREAM;
11. CMD_KEEPALIVE_GET Get KeepAlive of sock, and this
command only valid for NET_SOCK_STREAM;

arg The meaning of this value is depend on different command:

1. cmd=CMD_IO_SET, arg=1 means asynchronous mode,
arg=0 means block mode;
2. cmd=CMD_IO_GET, arg is meaningless;
3. cmd=CMD_TO_SET, arg>0 means the waiting time (unit:
ms) , arg<=0 means waiting indefinitely;
4. cmd=CMD_TO_GET, arg is meaningless;
5. cmd=CMD_IF_SET, arg means interface index of network
device, arg=0 means Ethernet card, arg=10 means PPP link;
6. cmd=CMD_IF_GET, arg is meaningless;
7. cmd=CMD_EVENT_GET, arg=0 means obtain even,
arg=SOCK_EVENT_READ means the length of current
readable data, arg=SOCK_EVENT_WRITE means the
length of current send data, arg=SOCK_EVENT_ERR
means get the error code, arg=SOCK_EVENT_ACCEPT
means the number of waiting for connection;
8. cmd=CMD_BUF_GET, arg = TCP_SND_BUF_MAX means
the maximum space that can send, arg=
TCP_RCV_BUF_MAX means the maximum space that can
receive, arg= TCP_SND_BUF_AVAIL means the current
valid send space.
9. cmd=CMD_KEEPALIVE_SET, arg>0 means the maximum
waiting time (unit: ms) for receiving message, after that, it
will execute keepalive function and the protocol stack will
automatically open keepalive function. The system default
value of arg is no less than 5000;arg<=0 means close
keepalive function;
10. cmd=CMD_KEEPALIVE_GET, arg is meaningless.
Success return >=0;Fail return <0 and the value is error code; When it is success,
the meaning of return value is depend on the command:
1. cmd=CMD_IO_SET, successfully return 0;
2. cmd=CMD_IO_GET, return 1 means asynchronous mode, return 0 means
block mode;
3. cmd=CMD_TO_SET, successfully return 0;
4. cmd=CMD_TO_GET, return 0 means waiting indefinitely, return >0 means
the waiting time (unit:ms);
Return:
5. cmd=CMD_IF_SET, success return 0;
6. cmd=CMD_IF_GET, return interface index of network device;
7. cmd=CMD_EVENT_GET, the return value depends on the value of
arg:when arg=0 return NetSocket event;
8. cmd=CMD_BUF_GET, the return value depends on the value of arg;
9. cmd=CMD_KEEPALIVE_SET, success return 0,fail return <0;
10. cmd=CMD_KEEPALIVE_GET, return 0 means keepalive is closed,
return>0 means the time start to execute keepalive.

3.18.13 SockAddrSet
Prototype: int SockAddrSet(struct net_sockaddr *addr, char *ip_str, short port)
Function: Encapsulate the socket address information.
addr The socket address information, output parameter;
ip_str IP address string, such as192.168.0.5,input parameter;
Parameters: If it is NULL, means the address is 0;
The address string cannot be 255.255.255.255;
port Port Number, for example, the port number of ftp is 21;
Return: Success return 0,Fail return <0

3.18.14 SockAddrGet
Prototype: int SockAddrGet(struct sockaddr *addr, char *ip_str, short *port)
Function: Get the IP address and port information in socket address information
addr The socket address information, input parameter;
ip_str IP address string, such as 192.168.1.5,output parameter;
Parameters:
The maximum length of string is 15 characters;
port Port number, for example, the port number of ftp is 21. Output
parameter.
Return: Success return 0, fail return <0
3.18.15 DnsResolve
Prototype: int DnsResolve(char *name, char *result, int len)
Function: Domain name resolution;
name The domain name string, such as www.sina.com.cn.
No more than 255 characters.
Parameters: result The result;
result is IP address string;
len The valid length of result, this value must be greater than 20
Return: Success return 0, fail return <0


3.18.16 NetPing
Prototype: int NetPing(char *dst_ip_str, long timeout, int size)
Function: Ping external machine
dst_ip_str IP address string of destination host, such as 192.128.0.111
The maximum length of string is 15 characters;
Parameters: timeout Timeout, unit:ms
size Data length of the load,<=1024
>=0:Success,the time consumed

Return:
<0: Fail, error code.
3.18.17 RouteSetDefault
Prototype: int RouteSetDefault(int ifIndex)
Function: Set default route
ifIndex Index number of network devices
0:Ethernet card
Parameters: 1:PPPoE
10:Modem PPP link
11:Wireless(GPRS/CDMA)PPP link
Return: Success return 0,Fail return <0
1. Set default route only valid for the new connection to be established, invalid
for the connection already exist.
Notes:
2. Set default route invalid for the passive connection (use as server).
Only Support P90
3.18.18 RouteGetDefault
Prototype: int RouteGetDefault(void)
Function: Get default route
Parameters:
>=0:Index number of network device,0 means Ethernet device, 10 means
Return: modem PPP Link;
<0:Error code;
If user does not specify, the strategy of default route using is as follow:
If PPPoE is enable, prefer using it, otherwise, prefer using Ethernet device. If
Notes:
Ethernet device is disable, then using modem PPP link.
Only Support P90
3.18.19 NetDevGet
int NetDevGet(int Dev,char *HostIp,char *Mask, char *Gateway, char
Prototype:
*Dns)

Function: Read IP configuration information of Network device

Dev Network device number (Decimal)
0:Ethernet device
10:Modem PPP
11:Wireless module (GPRS/CDMA)
HostIp IP address information;
The space assigned by application is not less than 20 bytes.
If the application is not need this information, just set to NULL.
Mask Mask information.
Parameters:
GateWay Gateway address.
Dns DNS server address;
=0:read success, the content of HostIp, Mask, GateWay and Dns is valid;
Return:
<0:error code;

4. Compiling and Linking
The section of compiling and linking will provide instructions on using compiling tools, creating
makefile, using ProPay development tool, advices on application development, etc. Development
process and development environment will be explained in details and it maybe helpful for
application developer in application developing as well as testing.
4.1 GCC Introduction
GCC (GNU C Compiler) is one of the most powerful and efficient cross platform compiler from
GNU. GCC is super compiler can generate executable target file in different hardware platforms
and compiling speed is 20% to 30% faster than other compilers in average.
GCC compiler can compile C and C++ source code files to object code files, then link and generate
to executable target file. If the target file name is not provided, then the GCC will generate a default
target file, a.out. Under Linux environment, there is no any restriction for executable filename by
the filename extension. The system uses the files attribute to classify that file which is executable
or not. The GCC uses the filename extension to distinguish those input file types and please refer to
the following for some GCC filename extension rules.
Table 4-1 GCC compatible file suffix
.c C source code file
.a Library file formed by compiled files
.C C++ source code file
.cc or .cxx
.h Header file
.i Pre-processing C source code file
.ii Pre-processing C++ source code file
.m Objective-C source code file
.o Compiled files
.s Assembler source code files
.S Pre-processing assembler source code files
4.1.1 Basic Usage and Options for GCC

During using the gcc complier, we have to provide a list of required options and filename. The
gcc compiler has about hundreds options (refer to the GCC related document for detail). Most of
those options are not applicable to us. The following describes the basic usage and some common
options.
The basic usage of gcc: gcc [options] [filenames]
The [options] are the compiler acceptable arguments and the [filenames] are those related files
names.

-c Compiling only and not for linking / executing. The compiler will
accept the .c source file and form the .o target file. Usually, for
compiling function source file.
-o output_filename Specified target filename as output_filename and this filename should
not be same as the source filename. The gcc will use default target
filename, a.out, if this option is omitted.
-g Generate debugging information. This information is stored in the
object file and copied from there to the final executable file by the
linker, where it can be read by the debugger. You must use the g
switch if you plan on using the debugger.
-O Optimization. Using this switch, the compiler will optimize the source
code and final executable file maybe more efficient. But the compiling
time will be longer.
-O3 Extensive optimization for compiling, of course the compiling process
will be slower.
-Idirname Add the directory dirname to the head of the list of directories to be
searched for header files, using for pre-processor process. There are
two types of include header files declaration in C source code files:
A) #include <myinc.h>
B) #include mnyinc.h
For Type A, pre-processor will search those header file under system
defined searching path (for instance /usr/include). For Type B,
pre-processor will search those header file under the current working
directory. This option is used to direct the compiler to search those
header files in dirname if those header files are not found under current
directory. During application development, if those source code files
include header files in different directories, then this options is required
to be added.
-Ldirname Add directory dirname to the list of directories for searching library files
when linking. Under default status, the linker, ld, will search the
default directory (for instance /usr/lib) for library files. This option
directs the linker to search the L specified directory first and then
search the default directory. If there are different libraries located in
different directories, then this option needs to be added in corresponding
ordering.
-lname Search the library named libname.a when linking. This library file
should be either under the system searching path or specified by the L
option. For instance, -lm implies the library named libm.a.
The above section describes the basic usage and commonly used options of the GCC and please
refer the Linux system document for detail.

4.1.2 GCC Error Message Type and Handling

If there is any error detected during compiling or linking process, then the GCC will stop the
process and the final executable file will not be generated. The GCC will display some error
messages for ease the error finding process. We have to examine those error messages one by one
and modify the source code files accordingly, to ensure those source code files can be compiled and
linked successfully. Normally, the GCC reports four major types of error message. We describe
those error message types and handling methods as following:
Type 1: C Syntax Error

Error Message: File source.c in line n has syntax error. This type of error message implies that there
is a C programming syntax error and required to check the line n or lines before line n of the source
code file. Sometimes, required to check those included header files too. Usually, the GCC will
generate a lot of error messages just for a simple C programming syntax error. If required, please
refer to the C programming guide for reference.
Type 2: Header File Error
Error Message: Cannot find header file. This type of error message implies that there is problem
with the included header file in the source code file. The root cause maybe incorrect header
filename or cannot find the header file in the searching directories. Or there is mis-use of ( ) or (<
>) in including the header file.
Type 3: Library File Error
Error Message: linker cannot find the specified library file. For instance: ld: -lm: No such file or
directory. This type of error takes place during linking library process. The root cause maybe
incorrect library filename, the specified library directory incorrect, etc. Use the find command to
search those library files in those possible directories. Modify the source code file and the compiler
options after found the correct library filename and located directory.
Type 4: Undefined Symbol Error
Error Message: Undefined symbol. This type of error takes place during linking process and there
are two possible causes. 1. The user defined function / variable cannot be compiled or linked, or the
function / variable did not define at all. This required the developer to modify the source code files
to define the required function / variable. 2. The undefined symbol is a standard library function
and the source code required this library function. During the linking process, this library file is not
included or this library filename is mistyped. Under this condition, the ar command can check the
required function embedded under which library file. Obtained the correct library filename, modify
the GCC option l and L to include this library file.
Removing compiling and linking errors is the most basic and simple requirement for application
development and is only the beginning. This type of errors only implies the mis-use of C
programming language and it should be quite easy to resolve. For developing an application,
completed the compiling and linking process only indicates the beginning of the whole
development phase. The applications runtime error implies the defect of the application design or
the mis-understanding of the system requirement. More in-depth testing, enhancement and
modifications may require. A complicated application usually requires more times of compiling,
linking, testing and modification.

4.2 Compiling
Compiling tools are arm-elf-gcc.exe and arm-elf-as.exe.

arm-elf-gcc.exe compiles c source program. arm-elf-as.exe compiles assembly source program. For
example:
arm-elf-as init.s -o init.o
arm-elf-gcc -O3 I..\gcc\build\include -I..\myproj\inc -mlittle-endian -mcpu=arm9 c main.c -o
main.o
-c means only generating target code and not for linking; -o specifies target filename; -O3 means
extensive optimization for compiling, and the coder will be shorter and have high speed; -gdwarf
generates debugging information; -mlittle-endian means small rear storing format, that is, lower
bytes are in lower addresses, which is the same with PC (opposite with P70 and P60-S1);
-mcpu=arm9 sets CPU type;I appoints library and user head file searching route. If the item has
many files, then makefile file should be made. About makefile content, please refer to
corresponding information.
4.3 Linking and Converting
GCC linker tool, arm-elf-ld.exe, can link those generate object files and library file to the machine
code file based on the absolute address, which is specified in the ldscript file. The linker, arm-elf-ld,
generated machine code file (ELF) can be converted to downloadable file (BIN) by using the tool,
elftobin.exe. For P80 and R50, please use the following two options for converting two types of
applications:
Normal Application: PAX-P80OrR50-SAPP
Application Manager: PAX- P80OrR50-MAPP
Example:
elftobin postest.elf postest.bin PAX-P80-SAPP
arm-elf-ld -Tldscript -L$(GCCLIB) -L$(GCCLIBELF) -L$(P80LIBDIR) -o
$(NAME).elf $(OBJ) lp80api -lc lgcc
where T option specified the linker script file, ldscript. L option specified the library searching
path. o option specified the output file format. $(OBJ) specified all the required object file
with .o file extension to be linked. l specified the linked library (notes: if required to linked
libp80api.a, libc.a, libgcc.a, then removes the wording lib or .a. For instance lp80api lc
lgcc)
Please refer to the makefile file for detail example.
Remarks: During application development, specified those absolute address in the linker script file
(ldscript, please refer to the example) and link the init.o file with the application.
4.4 Makefile Sample
P80 is used in the following sample:

path=c: \windows;c:\windows\system32;d:\pax\p80\gcc\build\bin
NAME = p80_edc
GCCDIR = d:\pax\p80\gcc\build
GCCBIN = $(GCCDIR)\bin
GCCLIB = $(GCCDIR)\lib
GCCLIBELF = $(GCCDIR)\libelf
GCCINC = $(GCCDIR)\include
LOCSRC = .\source
LOCOBJ = .\obj
LOCINC = $(GCCINC)
LIB = $(GCCLIB)\libc.a
P80INC = d:\pax\p80\inc
P80LIBDIR = d:\pax\p80\lib
P80LIB = p80api
#P80INIT = $(P80LIBDIR)\p80_init.o
P80SCRIPT = $(P80LIBDIR)\ldscript
ASM = $(GCCDIR)\BIN\arm-elf-as -gdwarf2

GCC = $(GCCDIR)\BIN\arm-elf-gcc -O3 -gdwarf -I$(GCCINC) -I$(P80INC)
-mlittle-endian -mcpu=arm9 -c
LINK = $(GCCDIR)\BIN\arm-elf-ld -T$(P80SCRIPT) -L$(GCCLIB)
-L$(GCCLIBELF) -L$(P80LIBDIR)
CCFLAG = -O3 -gdwarf -mlittle-endian -mcpu=arm9
OBJECTS=$(LOCOBJ)\p80_init.o \
$(LOCOBJ)\main.o \
$(LOCOBJ)\acqset.o \
$(LOCOBJ)\adjust.o \
$(LOCOBJ)\api.o \
$(LOCOBJ)\authsale.o \
$(LOCOBJ)\balance.o \
$(LOCOBJ)\card.o \
$(LOCOBJ)\chkoptn.o \
$(LOCOBJ)\cnname.o \
$(LOCOBJ)\com.o \
$(LOCOBJ)\comset.o \
$(LOCOBJ)\const.o \
$(LOCOBJ)\data.o \

$(LOCOBJ)\datacal.o \
$(LOCOBJ)\disp.o \
$(LOCOBJ)\disp1.o \
$(LOCOBJ)\ecr.o \
$(LOCOBJ)\edc.o \
$(LOCOBJ)\file.o \
$(LOCOBJ)\fun.o \
$(LOCOBJ)\init.o \
$(LOCOBJ)\initedc.o \
$(LOCOBJ)\instal.o \
$(LOCOBJ)\iso8583.o \
$(LOCOBJ)\keybd.o \
$(LOCOBJ)\logon.o \
$(LOCOBJ)\mc.o \
$(LOCOBJ)\offline.o \
$(LOCOBJ)\offsale.o \
$(LOCOBJ)\other.o \
$(LOCOBJ)\password.o \
$(LOCOBJ)\preauth.o \
$(LOCOBJ)\print.o \
$(LOCOBJ)\refund.o \
$(LOCOBJ)\reversal.o \
$(LOCOBJ)\sale.o \
$(LOCOBJ)\select.o \
$(LOCOBJ)\settle.o \
$(LOCOBJ)\specfun.o \
$(LOCOBJ)\svc.o \
$(LOCOBJ)\sys.o \
$(LOCOBJ)\tools.o \
$(LOCOBJ)\void.o
# ADS-ROM version
$(NAME).elf: $(OBJECTS)
$(LINK) -o $(NAME).elf $(OBJECTS) -l$(P80LIB) -lc -lgcc
# elftobin $(NAME).elf $(NAME).bin PAX-P80-SAPP
elf2bin $(NAME).elf $(NAME).bin s
# C files
{$(LOCSRC)}.C{$(LOCOBJ)}.o:
$(GCC) $(LOCSRC)\$(@B).c -o $(LOCOBJ)\$(@B).o
# ASM file
$(LOCOBJ)\p80_init.o: $(LOCSRC)\p80_init.s

$(ASM) $(LOCSRC)\p80_init.s -o $(LOCOBJ)\p80_init.o
default: $(OBJECTS)
clean:
del *.db
del *.blk
del *.db2
del *.out.
4.5 Linking Description File Example
P80 is used in the following sample:

Following is the normal application linking description file:
SECTIONS
{
. = 0x00300000;
.text : { *(.text) }
Image_RO_Limit = .;
Image_RW_Base = .;
.data : { *(.data) }
.rodata : { *(.rodata) }
Image_ZI_Base = .;
.bss : { *(.bss) }
Image_ZI_Limit = .;
__bss_start__ = .;
__bss_end__ = .;
__EH_FRAME_BEGIN__ = .;
__EH_FRAME_END__ = .;
PROVIDE (__stack = .);
end = .;
_end = .;
.debug_info 0 : { *(.debug_info) }
.debug_line 0 : { *(.debug_line) }
.debug_abbrev 0 : { *(.debug_abbrev)}
.debug_frame 0 : { *(.debug_frame) }
}
Following is the application manager linking description file:
SECTIONS
{
. = 0x00200000;
.text : { *(.text) }
Image_RO_Limit = .;

Image_RW_Base = .;
.data : { *(.data) }
.rodata : { *(.rodata) }
Image_ZI_Base = .;
.bss : { *(.bss) }
Image_ZI_Limit = .;
__bss_start__ = .;
__bss_end__ = .;
__EH_FRAME_BEGIN__ = .;
__EH_FRAME_END__ = .;
PROVIDE (__stack = .);
end = .;
_end = .;
.debug_info 0 : { *(.debug_info) }
.debug_line 0 : { *(.debug_line) }
.debug_abbrev 0 : { *(.debug_abbrev)}
.debug_frame 0 : { *(.debug_frame) }
}
4.6 PAXPayPro Application Development Samples
PAXPayPro provides a development environment for POS application simulation. By using ProPay
application is not needed to be downloaded to POS, it simulates the actual environment and
combines VC testing functions for debugging the application. The efficiency of development can
be greatly improved by the SDK. Moreover, system has been integrated with GCC compiler and
download tool. The application can be downloaded to POS right away as long as the target code
has been successfully complied and simulated. Following shows the steps on creating an
application with PAXPayPro. For more details about instruction on PAXPayPro, please refer to the
help document after installing PAXPayPro.
1. Install PAXPayPro and create POS application on Appwizard. Following is the Appwizard
interface:

Fig. 4-1 App wizard Interface
2. Click New button on the App wizard interface and enter into new application
interface as follows:
Fig. 4-2 Creating New Application
3. Input project name (Project name). Project name can only contain letters, numbers,
or underscore, and it follows the file naming rules of windows.
4. Select project folder (Location)

5. Input project description (Description). When App wizard opens an existing project,
the description will be shown, so that user can easily manage different development
projects.
6. Select template.
7. User can select an empty template or Hello World template. If empty template is
selected, an empty project will also be created, and user can add other project files. If
Hello World template is selected, it will generate a project with main.c file, and
output of Hello World can be shown.
8. Application is built.
4.7 Notes for Application Development
1. Require to add INIT.S file during linking process. INIT.S file is under SRC directory of
POSTTEST sample project, and add INIT.O file on the top of other target files.
2. Cannot use .C file extension to replace .c file extension. Otherwise .C files will be handled
as .CPP files and compiling error will take place.
3. If thermal printer is used, it is required to install P70T printer font library. Otherwise, printer
will report error.
4. If it is required to use internal PED, it is necessary to replace PP wording to PED
wording for external PINPAD API.
4.8 Application Space Limitation
The allocation scheme of application space is same for all P80, P78, P90, R50 and P58. And the
allocation of R30 is less than other type due to the SDRAM in R30 and R100 are only 2M.
4.8.1 Space Definition

Coding Space: include application coding and constant data.
Variable Space: include global variables and global static variables, which are defined by the key
word static.
Stack Space: include all local variables and the occupied space which is used for transferring
function parameters.
4.8.2 Size of Space and Limitation for P80, P78, P90, R50, P58 and R50-M
1) Standard application and multi-application management will use the same user stack space. The
size of the space is not defined, and it will be affected by the size of standard coding space and size
of variable space (inverse proportion).
2) Multi-application management: the total space for coding and variable is 1M bytes. If coding
space is 256K bytes, the rest of 768K bytes will all be variable space.
3) Standard application: the total space for coding space, variable space and user stack space will
be 3M bytes. If coding space is 512K bytes, and variable space is 1M bytes, the rest of 1.5M bytes
will all be stack space.

4) Size of space is dynamically allocated by complier and linker
4.8.3 Size of Space and Limitation for R30 and R100

According to support single application or support multi-application, R30 software architectures
can be divided into two kinds.
Support single application:
1) The size of user stack space is not defined, and it will be affected by the size of standard coding
space and size of variable space (inverse proportion).
2) The total space for coding space, variable space and user stack space will be 1.5M bytes. If
coding space is 512K bytes, and variable space is 512K bytes, the rest of 512K bytes will all be
stack space.
Support multi-application:
1) Standard application and multi-application management will use the same user stack space. The
size of the space is not defined, and it will be affected by the size of standard coding space and size
of variable space (inverse proportion).
2) Multi-application management: the total space for coding and variable is 1M bytes. If coding
space is 256K bytes, the rest of 768K bytes will all be variable space.
3) Standard application: the total space for coding space, variable space and user stack space will
be 3M bytes. If coding space is 512K bytes, and variable space is 1M bytes, the rest of 1.5M bytes
will all be stack space.

5. Appendix
5.1 Data Structure Checklist
This section provides data structure which will be used in application development. If there are
some descriptions highlighted in RED at the beginning of the data structure, it means that following
data structure will only be application for some product. If there is no description highlighted in
RED, it means that following data structure will be application for all products.
5.1.1 IC Card Structure
Command data structure: APDU_SEND

typedef struct{
unsigned char Command [4]; /* CLA, INS, P1, P2 */
unsigned short Lc; /* length of data to be sent to IC card */
unsigned char DataIn [512]; /* data to be sent to IC card */
unsigned short Le; /* length of data that return from IC card */
} APDU_SEND;
Response data structure: APDU_RESP

typedef struct {
unsigned short LenOut; /* length of data that return from IC card */
unsigned char DataOut [512]; /* buffer pointer of data that return from IC card */
unsigned char SWA; /* IC card command processing status 1 */
unsigned char SWB; /* IC card command processing status 1 */
} APDU_RESP;
5.1.2 Modem Dialing Parameter Structure
Applicable for P80, P78, P58 and P90 with external MODEM; NOT applicable for R50, R30,
R50-M and R100.
typedef struct {
unsigned char DP; /* Set tone/pulse dialing mode */
unsigned char CHDT; /* If check dialing tone */
unsigned char DT1; /* waiting time from hook off to dialing (unit: 100ms) */
unsigned char DT2; /* waiting time of , when dialing external line (unit:
100ms) */
unsigned char HT; /* lasting time of a single number in tone dialing (unit: 1ms) */
unsigned char WT; /* Pausing time between two numbers in tone dialing
(unit: 10ms) */
unsigned char SSETUP; /* Communication byte setting (including sync/async,
baud rate, line, timeout, etc.) */

unsigned char DTIMES; /* Re-dial times, larger or equal 1*/

unsigned char TimeOut; /* MODEM will hang up if no application data transfer
occurs in specified time period. The unit is 10 seconds. 0 means no timeout.*/
unsigned char AsMode; /* Asynchronous communication (asynchronous
communication valid) */
} COMM_PARA;
5.1.3 File Information Structure

typedef struct
{
unsigned char fid; /* file handle */
unsigned char attr; /* file attribution */
unsigned char type; /* file type */
char name [17]; /* file name */
unsigned long length; /* file length */
} FILE_INFO;
5.1.4 Application Information Structure

typedef struct {
unsigned char AppName [32]; /* application name */
unsigned char AID [16]; /* application identification */
unsigned char AppVer [16]; /* application version */
unsigned char AppProvider [32]; /* application provider */
unsigned char Descript [64]; /* description of application */
unsigned char DownloadTime [14]; /* application download time, will be set during
downloading */
unsigned long MainAddress; /* entrance address of main function main ()*/
unsigned long EventAddress; /* entrance address of event handling event_main
()*/
unsigned char AppNum; /* application handle, will be set during
downloading */
unsigned char RFU [73]; /* reserved */
} APPINFO;
5.1.5 Magnetic Stripe Card Data Structure

It applies to P80, P78, P90 and P58, but does not apply to R50, R30, R50-M and R100.
typedef struct{
unsigned char RetCode; /* magstripe read status */
unsigned char track1[256]; /* data buffer of track 1 */
}ST_MAGCARD;

5.1.6 Event Process Structure

It applies to P80, P78, P90 and P58, but does not apply to R50, R30, R50-M and R100.
typedef struct{
int MsgType; // event type(magcard,IC card, key down or other //event
defined by user)
ST_MAGCARD MagMsg; // magcard data
unsigned char KeyValue; // value of pressed key
unsigned char IccSlot; // IC card slot number
void *UserMsg; // event information of user defined
}ST_EVENT_MSG;
Defined event type:
#define MAGCARD_MSG 0x01 magnetic card event
#define ICCARD_MSG 0x02 IC card event
#define KEYBOARD_MSG 0x03 key pressing event
#define USER_MSG 0x04 user defined event
5.1.7 Font Structure

It applies to P58, but does not apply to P80, P78, P90, R50, R30, R50-M and R100.
typedef struct{
int CharSet; // charset
int Width; // char width
int Height; // char height
int Bold; // bold
int Italic; // italic
}ST_FONT;
5.1.8 IP Module Socket Address Structure

struct sockaddr_in
{
char sin_len;
char sin_family;
short sin_port;
struct in_addr sin_addr;
char sin_zero[8];
};
struct sockaddr
{
char sa_len;
char sa_family;
char sa_data[14];
};

5.2 Abbreviation Checklist
This section provides descriptions of abbreviations and professional terms, which are used in this
manual.
Table 5-1 Abbreviation Checklist
Name Description
ATR Parameter which is returned from IC card reset response. It includes
type of protocol and transmission speed.
PED PinPad
LCD LCD display screen
5.3 Global Variable
Table 5-2 Descriptions for Global Variable

Variable Description
int errno; Error number, read by GetLastError()
const APPINFO AppInfo; Application information. Each application must declare such a global
variable and give it initial value. The variable can be accessed directly
in the current application.

(P78, P80, P90, R50, P58, R30, R50-M, R100) API Programming (V1.2.5)

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

(P78, P80, P90, R50, P58, R30, R50-M, R100) API Programming (V1.2.5)

Uploaded by

Copyright:

Available Formats

Application Developer

PAX Computer Technology (Shenzhen)Co.,Ltd.

1.1 CONTENT DESCRIPTION ......................................................................................................... 8

2. DEVELOPMENT PLATFORM .............................................................................................. 13

2.1 SYSTEM REQUIREMENT ....................................................................................................... 13

3. DETAILED API DESCRIPTIONS .......................................................................................... 14

3.1 BASIC FUNCTIONS ............................................................................................................... 14

PAX Computer Technology (Shenzhen)Co.,Ltd. 1/196

3.3.7 GetHzString ................................................................................................................... 31

PAX Computer Technology (Shenzhen)Co.,Ltd. 2/196

PAX Computer Technology (Shenzhen)Co.,Ltd. 3/196

3.10.8 ModemExCommand ................................................................................................. 101

PAX Computer Technology (Shenzhen)Co.,Ltd. 4/196

3.12.10 GsmOnHook ............................................................................................................ 140

PAX Computer Technology (Shenzhen)Co.,Ltd. 5/196

3.16.16 EPSPEDSetMAC2 .................................................................................................... 163

4. COMPILING AND LINKING ............................................................................................... 181

4.1 GCC INTRODUCTION ......................................................................................................... 181

PAX Computer Technology (Shenzhen)Co.,Ltd. 6/196

4.6 PAXPAYPRO APPLICATION DEVELOPMENT SAMPLES .......................................................... 188

5. APPENDIX ............................................................................................................................. 192

5.1 DATA STRUCTURE CHECKLIST ........................................................................................... 192

PAX Computer Technology (Shenzhen)Co.,Ltd. 7/196

1.1 Content Description

1.1.1 Compatibility Issues and Instructions

1.1.2 Table of Applicable Product Module

PAX Computer Technology (Shenzhen)Co.,Ltd. 8/196

1.2 Revision History

Table 1-2 Application Developer Guide[Applicable for P78P80P90R50] Revision History

PAX Computer Technology (Shenzhen)Co.,Ltd. 9/196

2008-06-16 V1.0.0 Initial Song Kunxian

PAX Computer Technology (Shenzhen)Co.,Ltd. 10/196

2010-01-19 V1.1.6 Add the support for FileToAPP, Song Kunxian

PAX Computer Technology (Shenzhen)Co.,Ltd. 11/196

2. Modify the validity of logo in

PAX Computer Technology (Shenzhen)Co.,Ltd. 12/196

2.1 System Requirement

2.2 Software Tools

2.2.1 Compiling Tools

PAX Computer Technology (Shenzhen)Co.,Ltd. 13/196

3. Detailed API Descriptions

3.1 Basic Functions

PAX Computer Technology (Shenzhen)Co.,Ltd. 14/196

Prototype: void Beep(void)

Function: Makes a beep sound using the buzzer

PAX Computer Technology (Shenzhen)Co.,Ltd. 15/196

Definition of week days:

PAX Computer Technology (Shenzhen)Co.,Ltd. 16/196

PAX Computer Technology (Shenzhen)Co.,Ltd. 17/196

Function: Read the serial number of terminal

PAX Computer Technology (Shenzhen)Co.,Ltd. 18/196

PAX Computer Technology (Shenzhen)Co.,Ltd. 19/196

out_info[0]: Terminal Model Number0x00~0xFF

PAX Computer Technology (Shenzhen)Co.,Ltd. 20/196

out_info[4]: MODEM highest asynchronization speed

out_info[15]: Contactless IC card module version information

PAX Computer Technology (Shenzhen)Co.,Ltd. 22/196

PAX Computer Technology (Shenzhen)Co.,Ltd. 23/196

Display string, only support display the numbers "0~9",

Used to control the LED display.

3.2 Power Management Functions

PAX Computer Technology (Shenzhen)Co.,Ltd. 24/196