NEW8210 EFT-POS

APPLICATION DEVELOPMENT
MANUAL

V 0.1.2

Author: Harrison Date: 2013-12-03

Approved: Date:

NEW POS TECHNOLOGY LIMITED

www.newpostech.com
1. Revision History

Date Revision Level Description Modified by

2013-3-13 0.0.1 Create Ryan Huang
2013-4-20 0.0.2 Revision NEW8210 SDK head Harrison Lee
file
2013-4-26 0.0.3 Add GPRS API description Kent Song
2013-4-28 0.0.4 Revision Henry Li
2013-6-7 0.0.5 Add the API of barcode-scan; Alex Chen
Add two system API.
2013-07-17 0.0.6 Add figure 4.5.5 and revised Ryan Huang
some mis-spell.
2013-09-26 0.0.7 Revised the WNET API Kent Song
2013-10-21 0.0.8 Add API for obtain information of Henry Li
battery
Add API for VPDN module
Add API for control the power of
modem
Modify the structure of
ModemDialParms_t
2013-12-03 0.0.9 Add API for extern PINPAD N20 Henry Li
2014-01-02 0.1.0 Add API for wireless module Henry Li
Add description for return value
of ppp module
2014-02-28 0.1.1 Add API for Dual SIM Henry Li
2014-07-31 0.1.2 Fix decription of return value of Henry Li
magstripe_set_trackset,
magstripe_get_trackset.
Delete magstripe_reset

2. General Introduction

NEW8210 is a mobile POS terminal, base on Linux OS by New Pos Technology

Limited, it’s development platform is Linux OS, please download the latest SDK,
firmware, DownloadTool and related documents from the server:
ftp://customer:[email protected]/NEW8210/SDK
 The application develop environment is Linux or Windows.

If you want to develop in Linux system, you should install Linux system in your host
PC by yourself, we don’t offer any Linux OS install programs. We recommend using
RedHat Enterprise Server 6 x86 32bit version to development, and you should download
Linux SDK of NEW8210.

If you want to develop in Windows system, you should download Windows SDK of
NEW8210.

Either you select Windows or Linux platform to development, We recommend use

Eclipse to develop your applications, you can download the Linux/Windows version from
the server: http://www.eclipse.org/downloads/. NEW8210 supports C/C++ development,
temporarily not supports Java development, please download Eclipse IDE for C/C++
Developers version.

3. Function Introduction

4. Development Platform

If you want develop the application on Linux platform, you need to install a 32-bit
Linux system based on x86 platform (our SDK have not been certificated on 64-bit
Linux). You can also develop application on a virtual Linux by running virtual machine on
Windows system, at that time, you can develop application on Windows platform. Due to
we don’t offer SDK on Windows platform, so you can’t develop application on Windows
system directly.

To develop application, we recommend to use Eclipse, it is a multi-platform

development tool based on Java, Eclipse integrates functions of edit, compile, debug,
and etc,. Eclipse has friendly interface, and easy operating. If you know how to write
Makefile well, you also can develop application directly without any development tool.
4.1. Install cross compile toolchain for Linux

The toolchain for NEW8210 is based on ARM cross compile toolchain which has the
version of glibc-2.9 gcc-4.3.4, the toolchain supports compile C,C++,Java,Object
C,Object-C++.It is easy to install, unzip cross compile toolchain which we provide is
enough:

tar jxf glibc-oabi-toolchain-arm-generic.tar.bz2 -C /opt/compiler/

The command above “-C /opt/compiler/” is unzip to /opt folder, you also can unzip
toolchain to anywhere you want, but please ensure that active user have the read and
write rights to the unzip folder.

After unzip to folder, use the command below to test whether the tool chains is
usable:

/opt/compiler/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-gcc -v

If have output information below, the toolchain is available.

Using built-in specs.

Target: arm-unknown-linux-gnu

Configured with: /home/lihua/toolchain/cross/bin/targets/src/gcc-4.3.4/configure --build=i386-build_redhat-linux-gnu

--host=i386-build_redhat-linux-gnu --target=arm-unknown-linux-gnu --prefix=/opt/compiler/glibc-oabi-toolchain-arm-

generic --with-sysroot=/opt/compiler/glibc-oabi-toolchain-arm-generic/arm-unknown-linux-gnu//sys-root --enable-

languages=c,c++,java,objc,obj-c++ --disable-multilib --with-float=soft --with-pkgversion='<[email protected]>'

--enable-__cxa_atexit --with-gmp=/opt/compiler/glibc-oabi-toolchain-arm-generic --with-mpfr=/opt/compiler/glibc-oabi-

toolchain-arm-generic --with-ppl=/opt/compiler/glibc-oabi-toolchain-arm-generic --with-cloog=/opt/compiler/glibc-oabi-

toolchain-arm-generic --with-mpc=/opt/compiler/glibc-oabi-toolchain-arm-generic --with-local-

prefix=/opt/compiler/glibc-oabi-toolchain-arm-generic/arm-unknown-linux-gnu//sys-root --disable-nls --enable-

threads=posix --enable-symvers=gnu --enable-c99 --enable-long-long --enable-target-optspace

Thread model: posix

gcc version 4.3.4 (<[email protected]>)

Because this toolchain uses a high grade version of GCC toolchain, it needs
dynamic library mpfr-2.4.2, if your Linux system haven’t the dynamic library, or haven’t
the enough high grade version of dynamic library, it will report error libmpfr.so when using
this toolchain. Please download mpfr-2.4.2.tar.bz2, compile and install it again, step
below:

Unzip file:

tar jxf mpfr-2.4.2.tar.bz2

Configure and compile:

cd mpfr-2.4.2
./configure –prefix=/usr
make

Install: need root privilege

su
make install
exit
4.2. Install Eclipse for Linux

1. Download Eclipse
The server is: http://www.eclipse.org/downloads/ ， please download Linux file
package have the version of Eclipse IDE for C/C++ Developers.
2. Unzip Eclipse
tar zxf eclipse-cpp-helios-linux-gtk.tar.gz -C /opt
Command above “-C /opt” is unzip to /opt folder, ensure that active user has read
and write rights. Also you can unzip to any other folders.
3. Run Eclipse
Execute “/opt/eclipse/eclipse” to run Eclipse, also you can create an application
launcher to run it.

Click Workbench, go into C/C++ development interface:

4.3. Install cross compile toolchain for Windows

The Windows compile toolchain for NEW8210 is based on ARM cross compile toolchain
which has the version of glibc-2.9 gcc-4.3.4, the toolchain supports compile C,C+
+,Java,Object-C,Object-C++.It is easy to install, unzip cross compile toolchain(glibc-oabi-
toolchain-arm-generic.zip) which we provide to C:\, and set the environment variable
PATH.

Open Control Panel-Performance and Maintenance-System (or right-click on My

Computer and choose "Properties"). In the box that opens, click the "Advanced" tab to
obtain the dialog box shown below. Next, click the button "Environment Variables".
The figure below shows the "Environment Variables" dialog box that opens next. It lists
two kinds of variable- those that apply only to the current user and those that apply to the
whole system. You can simply scroll down the lists to see what is on your system or you
can edit the lists. To create a new variable, use the "New" button. There are also buttons
for editing and for deleting variables.

The box for adding a new user variable is shown below. Generally, this is likely to be a
directory that you use frequently but can be any string of less than 8192 bytes. The
maximum total size for all environment variables, including variable names and the
"equals" sign, is 32767 characters.
The next figure shows a box for editing a variable; in this case it is the PATH variable. Be
sure to remember to separate directory names with a semicolon.

Please add the path of compiler into Variable value:

C:\glibc-oabi-toolchain-arm-generic\bin
Use the command below to test whether the tool chains is usable:
C:\Documents and Settings\Administrator> c:\glibc-oabi-toolchain-arm-generic\bin\arm-unknown-linux-gnu-gcc -v

Using built-in specs.

Target: arm-unknown-linux-gnu

Configured with: /home/Administrator/crosstool/bin/build/src/gcc-4.3.4/configure --build=i686-build_pc-cygwin --host=i686-

build_pc-cygwin --target=arm-unknown-linux-gnu --prefix=/cygdrive/C/glibc-oabi-toolchain-arm-generic --with-

sysroot=/cygdrive/C/glibc-oabi-toolchain-arm-generic/arm-unknown-linux-gnu//sys-root --enable-languages=c,c++,objc,obj-c+

+ --disable-multilib --with-float=soft [email protected] --enable-__cxa_atexit --enable-libmudflap

--enable-libgomp --enable-libssp --with-gmp=/home/Administrator/crosstool/bin/build/arm-unknown-linux-gnu/build/static

--with-mpfr=/home/Administrator/crosstool/bin/build/arm-unknown-linux-gnu/build/static

--enable-threads=posix

--enable-target-optspace --with-local-prefix=/cygdrive/C/glibc-oabi-toolchain-arm-generic/arm-unknown-linux-gnu//sys-root

--disable-nls --enable-symvers=gnu --enable-c99 --enable-long-long

Thread model: posix

gcc version 4.3.4 ([email protected])

4.4. Install Eclipse for Windows

1. Download Eclipse
The server is: http://www.eclipse.org/downloads/ ， please download Windows file
package have the version of Eclipse IDE for C/C++ Developers.
2. Unzip Eclipse
3. Run Eclipse
4.5. Create application project

As below introduce how to create a NEW8210 application program project by C

language, create a C++ language project is similar to C:

4.5.1. Create new project

Choose menu File->New->C Project, or choose toolbar New->C Project, or right click
on Project Explorer windows’s blank, choose New->C Project:
4.5.2. configure application project

Configure application project name at Project Name, choose Hello World ANSI C
Project at Project type, if you chooses Empty Project , it will not generate default
program. We recommend automatic generate program which is contain main
function by Eclipse.Then click Next to go into next configuration.
Click Next again to go into next configuration:

Finally click Finish to complete configuration.

4.5.3. modify/add source code

The main() function which generated automatically by Eclipse is not a standard C

program writing style, we will fix it:
#include <stdio.h>
#include <stdlib.h>

int main(int argc, char *argv[])

{
puts("!!!Hello World!!!"); /* prints !!!Hello World!!! */
return EXIT_SUCCESS;
}
Notice: when run an application on Linux, system can transmit parameters to
application, so we need to modify “int main(void)” to standard “int main(int argc,char
*argc[])”.
If you need to add a new source file to project, or add a new folder, can take the
same method like create a new project:
 Choose New->Source Folder to add a new source folder to project;
Choose New->Source File to add source file to project;
Choose New->Header File to add head file to project;

4.5.4. Compile configure way 1

In default condition, project create by Eclipse use gcc to compile the programs, and
the target is a application run on x86 platform; But our target system is ARM, of course it
can not run on x86 platform, so you need to configure the compile toolchain, cross
compile program which is running on ARM platform.

In Project Explore windows, right click the configured project, choose Properties
Firstly choose Configuration: [All configurations], so the configure below will be
available to both Debug version and Release version.

4.5.4.1. Configure GCC C Compiler

Choose “GCC C Compiler from Tool Settings” tag, modify “Command” on right side to
cross compile toolchain which we provide:
If you use Linux system, it should be:
/opt/compiler/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-gcc
If you use Windows system, it should be:
/cygdrive/c/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-gcc
Assume the Linux toolchain was installed in: /opt/compiler/glibc-oabi-toolchain-arm-
generic
Assume the Windows toolchain was installed in: C:\glibc-oabi-toolchain-arm-generic

Preprocessor Option: Do not need to modify, keep default.

Symbols Option: Here is used to define/undefined some user-defined Macro while
compiling, just like add –Daaaaa -Ubbbbbb while compiling.
Include Option: Here is used to configure head file and its search path while be
compiled, just like add compile parameter –ixxxx.h -Lyyyyy.
Optimization Option: Here is used to configure compile optimized options, in default
condition, choose None(-O0) when compiling Debug version,
choose Optimize most(-O3) when compiling Release version.You
 also can configure other optimized level by yourself: -O0 means
don’t optimize;-O1 means lightweight optimization;-O2 means
moderate optimization;-O3 means highly optimized, -Os means
optimize for space.
Debugging Option: Here is used to set the degree of compiled object code including
debug information .In default condition, choose Maximum(-g3)
when compiling Debug version; choose None when compiling
Release version;-g3 contains a lot of debug information, None
don’t contain any debug information.If you needs to debug, had
better choose –g or –g3; in releasing version, choose None.
Warnings Option: Here is used to configure compile warning option, default option is
All warnings(-Wall).
Miscellaneous Option: Here is used to define compile options for ourselves. For
NEW8210, we recommend set “Other flags” as:
-Wundef -Wstrict-prototypes -Werror-implicit-function-
declaration -Wdeclaration-after-statement -fsigned-char -marm
-mapcs -mno-sched-prolog -mabi=apcs-gnu -mlittle-endian
-mno-thumb-interwork -msoft-float -c

4.5.4.2. Configure GCC C Linker

Choose “GCC C Linker of Tool Settings” tags, modify “Command” on right side to cross
compile toolchain we provided:
If you use Linux system, it should be:
/opt/compiler/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-gcc
If you use Windows system, it should be:
/cygdrive/c/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-gcc
General Option: Here is a general linking option. Choose No shared libraries(-
static) if you need static link program;choose nothing if you need
dynamic link program. Usually, we choose dynamic link program.
Libraries Option: Here is used to configure linking assigned dynamic library and
configure path of search dynamic library, just like option –lxxxxx –
Lxxxxx.For example, if you want to link library directfb.so, just
need to add directfb in Libraries(-l), and add path of dynamic
library in Library search path(-L).
Miscellaneous Option: For NEW8210, we modify Linker flags to:
-marm -mapcs -mno-sched-prolog -mabi=apcs-gnu -mlittle-
endian -mno-thumb-interwork -msoft-float -Wl,-Map,"${PWD}/$
{ProjName}.map"
Shared Library Settings: Options here is available when compiling dynamic library, keep
default option when compiling application program.

4.5.4.3. Configure GCC Assembler

Choose GCC Assembler of Tool Settings tag, modidy cross compile toolchain we
provide in right side’s Command to :

If you use Linux system, it should be:

/opt/compiler/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-gcc
If you use Windows system, it should be:
 /cygdrive/c/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-gcc

Here is used to configure compile options which is used when compiling assembly
file, usually application doesn’t use assembly language, so it is not need to configure.

4.5.5. Compile configure way 2

4.5.5.1. Global setting for all project

In default condition, project create by Eclipse use gcc to compile the programs, and
the target is a application run on x86 platform; But our target system is ARM, of course it
can not run on x86 platform, so you need to configure the compile toolchain, cross
compile program which is running on ARM platform.

We setting the global environment configure in here, to avoid setting every project. Click the
menu “Window”-->select “Preferences” as follow figure:
Click the button “Add...” to add an environment variable “GCCPATH” as follow figure:

Suppose your Linux toolchain install as follow path:

/opt/compiler/glibc-oabi-toolchain-arm-generic
And suppose you Windows toolchain install as follow path:
C:\ glibc-oabi-toolchain-arm-generic\bin\arm-unknown-linux-gnu-gcc

The value of “GCCPATH” macro is:

“/opt/compiler/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-”, show as follow
figure:
4.5.5.2. Current Project compile setting

4.5.5.2.1. Configure GCC C Compiler

Select the “GCC C Compiler” in the tag “Tool Settings”, and change the Command as
follow:
$(GCCPATH)gcc
Preprocessor Option: Do not need to modify, keep default.
Symbols Option: Here is used to define/undefined some user-defined Macro while
compiling, just like add –Daaaaa -Ubbbbbb while compiling.
Include Option: Here is used to configure head file and its search path while be
compiled, just like add compile parameter –ixxxx.h -Lyyyyy.
Optimization Option: Here is used to configure compile optimized options, in default
condition, choose None(-O0) when compiling Debug version,
choose Optimize most(-O3) when compiling Release version.You
also can configure other optimized level by yourself: -O0 means
don’t optimize;-O1 means lightweight optimization;-O2 means
moderate optimization;-O3 means highly optimized, -Os means
optimize for space.
Debugging Option: Here is used to set the degree of compiled object code including
debug information .In default condition, choose Maximum(-g3)
when compiling Debug version; choose None when compiling
Release version;-g3 contains a lot of debug information, None
don’t contain any debug information.If you needs to debug, had
better choose –g or –g3; in releasing version, choose None.
Warnings Option: Here is used to configure compile warning option, default option is
All warnings(-Wall).
Miscellaneous Option: Here is used to define compile options for ourselves. For
NEW8210, we recommend set “Other flags” as:
-Wundef -Wstrict-prototypes -Werror-implicit-function-
declaration -Wdeclaration-after-statement -fsigned-char -marm
-mapcs -mno-sched-prolog -mabi=apcs-gnu -mlittle-endian
-mno-thumb-interwork -msoft-float -c

4.5.5.2.2. Configure GCC C Linker

Choose “GCC C Linker of Tool Settings” tags, modify “Command” on right side to cross
compile toolchain we provided:
$(GCCPATH)gcc

General Option: Here is a general linking option. Choose No shared libraries(-

static) if you need static link program;choose nothing if you need
dynamic link program. Usually, we choose dynamic link program.
Libraries Option: Here is used to configure linking assigned dynamic library and
configure path of search dynamic library, just like option –lxxxxx –
Lxxxxx.For example, if you want to link library directfb.so, just
need to add directfb in Libraries(-l), and add path of dynamic
library in Library search path(-L).
Miscellaneous Option: For NEW8210, we modify Linker flags to:
-marm -mapcs -mno-sched-prolog -mabi=apcs-gnu -mlittle-
endian -mno-thumb-interwork -msoft-float -Wl,-Map,"${PWD}/$
 {ProjName}.map"
Shared Library Settings: Options here is available when compiling dynamic library, keep
default option when compiling application program.

4.5.5.2.3. Configure GCC Assembler

Choose GCC Assembler of Tool Settings tag, modify cross compile toolchain we
provide in right side’s Command to :

$(GCCPATH)gcc

Here is used to configure compile options which is used when compiling assembly
file, usually application doesn’t use assembly language, so it is not need to configure.

4.5.6. Settings of Eclipse in Windows

There are some different settings for Eclipse between Linux and Windows, it due to
the path string in windows may conflict with Makefile. The ‘\’ and ‘:’ in windows path string
will lead eclipse failed to parse makefile, so we need change the ‘\’ and ‘:’ in other way.
The rule of translation below:
1. translate‘\’into‘/’in path string
 2. translate‘DISK-LABEL:\’into‘/cygdrive/ DISK-LABEL/’
for example：
“E:\NEW8210\sdk\include” should translate into
“/cygdrive/e/NEW8210/sdk/include”

“C:\glibc-oabi-toolchain-arm-generic\bin\arm-unknown-linux-gnu-gcc” should
translate into
“/cygdrive/c/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-gcc”

4.5.7. Compile

Use command “Build Project” to compile an application, there are some methods to
execute this command:
 Choose menu Project->Build Project
 Choose project of Project Explorer, right click it, select Build Project command.

 Choose Build button on toolbar

Default compile is Debug version, if you want to compile a Release version, you can
choose Build button on toolbar, then select Release.

If you want to compile again, choose Build Clean command, then choose Build
Project command, output information of compile is located at Console window of IDE
environment:
 If some warnings/errors appear after compiled, the warnings/errors will locate at
Console window, at the same time, there will have obvious warning/error flags on project
of Project Explorer window.

4.5.8. Run program

NEW8210 have an application launcher, user’s application can run by this launcher,
it need developer to write a launch configuration, and add it to current user’s Desktop
folder (always locate at /home/admin/Desktop).

Below is application launcher configure file form:

 Filename is xxxxx.desktop
 Content of file is some record entries.
 Every line of file is a record entry.
 There is 2 typies of record entry, one is section description, another is item
description.
 Section description begins of “[”, and ends of “]”, between “[” and ”]” is key word
of section description.
 Item description is a type of “key word = descripe the content”.
 Now we use an example to declare the format of file. We build a launcher
configuration file, the file is saved as “/home/user0/Desktop/demo.desktop”, and file
content is below:

[Desktop Entry]
Type=Application
Version=0.0.1
Name= Demo program
Comment=NEW8210 Demo program
Icon=/home/user0/NEW8210demo/demo_logo_48.png
Exec=/home/user0/NEW8210demo/demo
Path=/home/user0/NEW8210demo
Terminal=false
 In example above, section descriptor is “Desktop Entry”, it is fixed.
 This file(demo.desktop) describes a application program(Type=Application).
 The application version is “0.0.1”(Version=0.0.1).
 The application displays the name of “demo program”(Name=demo program) on
application manager.
 The application note message is “NEW8210 demo program”(Comment=NEW8210
demo program).
 The application displays an icon of demo_logo_48.png
(Icon=/home/user0/NEW8210demo/demo_logo_48.png) on application manager.
 If user want to execute this application program, user will execute the command:
/home/user0/NEW8210demo/demo(Exec=/home/user0/NEW8210demo/demo);
 The application’s current path is: /home/user0/NEW8210demo
(Path=/home/user0/NEW8210demo).
 The program doesn’t need to execute in Terminal (Terminal = false).

After building an application launcher configuration file, download it to

/home/user0/Desktop folder, now you can see the launcher item in system’s application
manager, and then download the real application and resource files to
/home/user0/NEW8210demo folder which described in launcher configuration file, and
you can startup application by application manager.

Notes: if your application launcher configuration file is built on Windows, please

modify file’s line feed “0d 0a” to “0d”, there haven’t any problems if it built in Linux.
Because of in Windows, line feed is consisted of “0d+0a”(enter+line feed), but on Linux,
only recognizes “0a”, don’t recognizes “0d”, so need to delete “0d” in file, you can use
hex file editor to edit it.

You also can use Console to run application, it can be used just when developing by
developer.
4.6. Debug program

NEW8210 use gdb to debug its program, we had installed gdbserver program on
NEW8210, so debugging program on NEW8210 is very convenient, and can undertake
remote debugging.

Before debugging program, we need compile program to a Debug version, it is due

to need use –g option when compiling, and you had better not use any optimization(use –
O0 option), then the target will contains debug information and can be debugged. The
Release version target always doesn’t use –g option, and use some optimize options
(always –O2 or –O3), so the target can not be debugged.

When debugging, you can use single-step debugging. If you know gdb command
well, you can debug by using gdb command directly, also can use other gdb front-end
tool, like DDD, insight, etc. Now we will introduce some methods about how to debug
program.

4.6.1. Debug by Eclipse

We had introduced how to create a Eclipse C Project above, now, we will modify C
Project source code, add a bug , then finding the bug by Eclipse.

Modify source code to the content below:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

static int bug_in_here(void)

{
int *p;

p = NULL;
*p = 0x12345678;

return *p;
}

int main(int argc, char *argv[])

{
 puts("!!!Hello World!!!\n"); /* prints !!!Hello World!!! */

printf("Call bug function: \n");

bug_in_here();

printf("Program will exit\n");

return EXIT_SUCCESS;
}

After modified, compile application for Debug version, then download to NEW8210,
run it, program exit abnormity. Now we prepare to debug program, use debug method of
gdbserver + gdb, use tcp to remote debugging.

Firstly, you need connect NEW8210 with host PC by ethernet network, you can use
a switch to connect host PC with NEW8210, also can use a network cable to connect
host PC with NEW8210 directly. After connecting, configure developing PC IP and
NEW8210 IP, then they can visit each other, you can use ping command to achieve it.
For example, your host PC’s IP is 192.168.1.100, NEW8210’s IP is 192.168.1.200, then
you execute the command in host PC:

ping 192.168.1.200

If PC receives response, it means that they can visit each other, then you execute
the abnormally program just now on NEW8210, the method for execution is run program
in console. Now introduce about how to enter into NEW8210’s console: use ssh to login
to NEW8210 from host PC, execute command below:

ssh [email protected]
The user name can be: user0 or user1 … or user 15
Enter password: (if you do not know password, please contact us)
After complete, if you can see the command notes, that means it had entered into
console.

Execute program which will be debugged in console:

gdbserver localhost:2331 ./DemoApp

Then, start Debugging in Eclipse, execute menu Run->Debug command or click

Debug button on toolbar, then it will generate a Debug configuration, of course this
configuration can not debug, it need some modification. Then execute Debug
Configurations:
 Choose “Select other…” bottom, then choose GDB(DFS) Remote System Process
Launcher, click OK to confirm:

Configure Debugger, choose Debugger tag, configure GDB debugger to arm-unknown-

linux-gnu-gdb of toolchain:
/opt/compiler/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-gdb

Configure GDB command file to null, just like picture below:

Switch to “Connection” tab page of Debugger, choose TCP of Type option, configure
NEW8210’s IP address to “Host name of IP address”, configure Port number to
2331(when run gdbserver command on NEW8210 above, wo choose gdbserver’s
listening port of 2331, make sure that gdbserver’s listening port is the same as here),
then click Debug button to debug, like picture below:
Now enter into the debug window, click Step Over (F6) to skip this sentence, click Step
into (F5) to enter into function implementation of this sentence, also can configure
breakpoint to debug, we will not introduce these debug methods here.Picture below is the
location when we executing the error language, it will notice error when clicking Step
Over, the problem of program is here:

If the programmer wants to stop debugging, right click DemoApp[C/C++ Application] of

Debug window, and choose “Terminate and Remove”.

4.6.2. Debug through insight debugger

Insight debugger is also a easy used gdb graphical front-end debugging, it also uses
gdb to debug, it has intuitive interface, and easy to use. This tool is a open source tool,
you can download it at http://sourceware.org/insight/downloads.php. If you want to debug
NEW8210 application program, we need to cross compile it. Here we don’t introduce how
to compile this tool, but how to make use of this tool.

Firstly run arm-linux-insight, its interface is below:

Then execute menu File->Open, open DemoApp program we have compiled, then
execute File->Target Settings, configure it like picture below:
Set Connection Target to GDBserver/TCP, set linking Hostname to the same as
NEW8210’s IP address, set linking port to the same as listening port of executing
gdbserver, then click OK.

Execute menu Run->Connect to target, if connect to gdbserver successfully it will notice

linking successfully, then execute Run->Run command to start to debug program, it is the
same as Eclipse, support step debugging, setting breakpoints,viewing variables and etc.
When debugging the code, exception will be happened if the error code is being
executed. Just like picture below:
4.6.3. Find problem by kernel error message

Except of using GDB to debug application program, we also can find out the location
of exception from error message which is printed by kernel. This method needs
developer knows well about assembly language, it is fit to experienced developers.
Picture below is the error message printed by kernel when executing the exception
program:

[ 117.610000] DemoApp: unhandled page fault (11) at 0x00000000, code 0x817

[ 117.610000] pgd = c1068000

[ 117.610000] [00000000] *pgd=21c26031, *pte=00000000, *ppte=00000000

[ 117.620000]

[ 117.620000] Pid: 832, comm: DemoApp

[ 117.620000] CPU: 0 Not tainted (2.6.27.45-NEW8210 #3)

[ 117.620000] PC is at 0x8440
[ 117.620000] LR is at 0x8484
[ 117.620000] pc : [<00008440>] lr : [<00008484>] psr: 60000010

[ 117.620000] sp : be96fb20 ip : be96fb34 fp : be96fb30

[ 117.620000] r10: 40024000 r9 : 00000000 r8 : 00000000

[ 117.620000] r7 : 00000000 r6 : 00008310 r5 : 00000000 r4 : 000084ac

[ 117.620000] r3 : 12345678 r2 : 00000000 r1 : 00000000 r0 : 00000014

[ 117.620000] Flags: nZCv IRQs on FIQs on Mode USER_32 ISA ARM Segment user

[ 117.620000] Control: 0005317f Table: 21068000 DAC: 00000015

[ 117.620000] [<c002cbe4>] (show_regs+0x0/0x4c) from [<c0030dd4>] (__do_user_fault+0x5c/0xa4)

[ 117.620000] r4:c1c88080

[ 117.620000] [<c0030d78>] (__do_user_fault+0x0/0xa4) from [<c0031098>] (do_page_fault+0x200/0x234)

[ 117.620000] r7:c1df7b14 r6:c1c88080 r5:c1e4eba8 r4:00010000

[ 117.620000] [<c0030e98>] (do_page_fault+0x0/0x234) from [<c002b20c>] (do_DataAbort+0x38/0x98)

[ 117.620000] [<c002b1d4>] (do_DataAbort+0x0/0x98) from [<c002bba0>] (ret_from_exception+0x0/0x10)

[ 117.620000] Exception stack(0xc1f1ffb0 to 0xc1f1fff8)

[ 117.620000] ffa0: 00000014 00000000 00000000 12345678

[ 117.620000] ffc0: 000084ac 00000000 00008310 00000000 00000000 00000000 40024000 be96fb30

[ 117.620000] ffe0: be96fb34 be96fb20 00008484 00008440 60000010 ffffffff

These debug message can get by executing dmesg program. Form these error
message, we found that exception happened on USER_32 mode, it is application
program exception, if the mode is not USER_32, then it isn’t an application program
exception; you can also find that error program is DemoApp, the reason of exception
happen is “unhandled page fault(11) at 0x00000000”, PC point to 0x8440 when exception
happening, return address LR point to 0x8484, all the register’s value when exception
happening have been printed(R0～R10、SP、IP、FP、SPSR、LR、PC) , with these
information, we can find the location of error program by disassemble application
information.

To disasembled the program DemoApp, use command below:

/opt/compiler/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-objdump -D
DemoApp > DemoApp.asm

Among command above, “ > DemoApp.asm ” write disasambled content to

DemoApp.asm file, then we open this file, find assembling code when exception
happening :

00008420 <bug_in_here>:
8420: e1a0c00d mov ip, sp
8424: e92dd800 push {fp, ip, lr, pc}
8428: e24cb004 sub fp, ip, #4 ; 0x4
842c: e24dd004 sub sp, sp, #4 ; 0x4
8430: e3a03000 mov r3, #0 ; 0x0
8434: e50b3010 str r3, [fp, #-16]
8438: e51b2010 ldr r2, [fp, #-16]
843c: e59f3010 ldr r3, [pc, #16] ; 8454 <bug_in_here+0x34>
 8440: e5823000 str r3, [r2]
8444: e51b3010 ldr r3, [fp, #-16]
8448: e5933000 ldr r3, [r3]
844c: e1a00003 mov r0, r3
8450: e99da800 ldmib sp, {fp, sp, pc}
8454: 12345678 .word 0x12345678

str r3,[r2] put value of r3 into the unit of r2 pointing to:

8430: e3a03000 mov r3, #0  set R3 to 0

8434: e50b3010 str r3, [fp, #-16]  store R3 in the unit of fp-16 pointing to
8438: e51b2010 ldr r2, [fp, #-16]  set R2 to unit content of fp-16 pointing to
843c: e59f3010 ldr r3, [pc, #16] ;  set R3 to unit content of pc+16 pointing to
8440: e5823000 str r3, [r2]  set unit of R2 pointing to to content of R3
It is clear that the value of R2 is 0 before execute str r3,[r2]; value of r3 is content of
address 8454, it is 0x12345678. After executing str r3,[r2], it is the same as *(uint32_t *)
0 = 0x12345678.

If developers don’t know assemble language well, we can change assemble code to
C code. Just needing to add –S,--source option when disassembling: Intermix source
code with disassembly，command which is to disassembled is below:

/opt/compiler/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-objdump -DS
DemoApp > DemoApp.asm

Now look at disassembler code, it is clear:

00008420 <bug_in_here>:
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

static int bug_in_here(void)

{
8420: e1a0c00d mov ip, sp
8424: e92dd800 push {fp, ip, lr, pc}
8428: e24cb004 sub fp, ip, #4 ; 0x4
842c: e24dd004 sub sp, sp, #4 ; 0x4
int *p;

p = NULL;
8430: e3a03000 mov r3, #0 ; 0x0
8434: e50b3010 str r3, [fp, #-16]
 *p = 0x12345678;
8438: e51b2010 ldr r2, [fp, #-16]
843c: e59f3010 ldr r3, [pc, #16] ; 8454 <bug_in_here+0x34>
8440: e5823000 str r3, [r2]

return *p;
8444: e51b3010 ldr r3, [fp, #-16]
8448: e5933000 ldr r3, [r3]
}
844c: e1a00003 mov r0, r3
8450: e99da800 ldmib sp, {fp, sp, pc}
8454: 12345678 .word 0x12345678

4.6.4. Condition of can not debug

We have introduced 2 debugging methods, they are all debugging by GDB, but there
will have conditions that can not use GDB to debug:

 error code is in a dynamic library

 object program not contains debug message
 object have been optimized
 source code have some files that have the same filename

If object program have been optimized, then source code will not correspond to
debugging location when debugging; if object program do not contains debugging
message, then gdb can’t know the location of source code, and of course can not
correspond to source code to debugging; if error code is in dynamic library, gdb can not
debug in dynamic library, because of dynamic library is dynamic linking, location of
linking is not fixed; if source code have some files that have the same filename, and they
are located in different folder, it may search the wrong source file when debugging.

5. API manual

NEW8210 device name：

Device Device file name Notes
Printer /dev/printer? ?=0,1,2, … ,15
Magnetic stripe /dev/magcard? ?=0,1,2, … ,15
Modem/GPRS/CDMA /dev/ttyS1
Barscanner/External PED /dev/ttyS2
UART /dev/ttyS3
AD /dev/adc
NFC Card /dev/nfc
IC Card /dev/usercard User card
/dev/samcard? ?=1,2,3 SAM card
5.1. System

API functions of this module was defined in the “posapi.h”; “libpos.so” must be used
when linking.

5.1.1. sys_reboot

Prototype： void sys_reboot(void)

Function： Restart system
Parameter None
：
Return： None
Support： NEW8210
Notes： System will turn off all the program, reset and restart

5.1.2. sys_poweroff

Prototype： void sys_poweroff(void)

Function： Power off
Parameter None
：
Return： None
Support： NEW8210
Notes： System will turn off all the program, power off the system

5.1.3. sys_kbd_set

Prototype： int sys_kbd_set(const struct kbdset *pset)

Function： set configuration of current system and key
Parameter pset beep_enable Enable/Disable buzzer when pressing
： （input or not: 1: enable, 0: disable
parameter） beep_freq The frequency of buzzer (unit: Hz)
beep_time Buzzer duration time (unit: ms,
0~100ms)
 backlight After pressing the key, the duration
time that backlight is turned on:
0： no bright backlight
Positive number ： Bright backlight is
turn off automatically when the
number of seconds expires
Negative number ： Backlight always
on
feed_enable Enable/Disable feeding or not when
pressing the feed key:
1: enable, 0: disable
Notice: this parameter was reserved
for future use.
Return： 0 Set OK.
-EINVAL input parameter error
others other error code
Support： NEW8210
Notes：

5.1.4. sys_kbd_get

Prototype： int sys_kbd_get(struct kbdset *pset)

Function： get configuration of current system and key
Parameter pset beep_enable Enable/disable buzzer ringing when
： （output pressing keypad
parameter） 1: enable, 0: disable
beep_freq The frequency of buzzer (unit: Hz)
beep_time Buzzer duration time (unit: ms)
backlight After pressing the key, the time how
long backlight is turned on:
0： no bright backlight
Positive number ： Bright backlight is
turn off automatically when the
number of seconds expires
Negative number ： Backlight always
on
feed_enable Enable/Disable feeding or not when
pressing the feed key:
1: enable, 0: disable
Return： 0 Set OK.
 -EINVAL input parameter error
others other error code
Be NEW8210
Applicable
in：
Notes：

5.1.5. sys_set_time

Prototype： int sys_set_time(const struct tm *tm)

Function： Setup terminal system local date and time
Parameter tm tm_sec second ， scope ： 0 ～ 61 ， allow leap
： second
tm_min minute，scope：0～59
tm_hour hour，scope：0～23
tm_mday day，scope：1～31，day begin from
1
tm_mon month，scope：0～11，month begin
from 0
tm_year year，scope：time offset from 1900
Return： 0 Setting success
-EINVAL Input parameter error
others Other error code
Support： NEW8210
Notes： Call this function to set system’s local time(not UTC time), transition
from local time to UTC time is depended on settings of system time
zone.
Due to the limitation of RTC chip, when set in the time before
1970, it will fail

5.1.6. sys_get_status_bar_height

Prototype int sys_get_status_bar_height(void);

：
Function: Get height of the status bar
Parameter: 无
Return: Return the points of the status bar
 Support: NEW8210
Notes:

5.1.7. sys_delay_to_suspend

Prototype: int sys_delay_to_suspend(void);

Function: Make terminal no suspend in 3 minutes
Parameter: None
Return: 0 Success
Support: NEW8210
Notes:

5.1.8. sys_suspend_now

Prototype: int sys_suspend_now(void)

Function: System suspend immediately
Parameter: None
Return: 0 Success
Support: NEW8210
Notes:

5.1.9. sys_get_sn

Prototype： char *sys_get_sn(char *sn, int nbytes)

Function： Get the device serial number
Parameter sn （output） Save the acquired serial number
： nbytes Maximum bytes number of sn
Return： Got sn, return NULL if it fails

Support： NEW8210
Notes：
5.1.10. beep

Prototype： void beep(unsigned int frequency, unsigned int keepms)

Function： control buzzer rang
Parameter frequency Sound frequencies of buzzer（64～20000Hz）
： keepms Continuous ringing keepms，unit：ms
Return： None

Support： NEW8210
Notes：

5.1.11. sys_backlight_set_time

Prototype： int sys_backlight_set_time(int keep)

Function： set backlight off or on
Parameter keep（unit：second） >0 Backlight is turned off
： automatically when the
number of keep seconds
expires

=0 no backlight
<0 Backlight always on
Return： 0 Set OK
Others Other error code
Support： NEW8210
Notes： Once it is set up, the backlight will run according to the set value. But
after system reset, the set value of backlight will recover to its default
one..

5.1.12. sys_backlight_get_time

Prototype： int sys_backlight_get_time(int *keep)

Function： get settings of current backlight
Parameter keep （ output ， unit ： Configuration of current backlight will
： second） save at this value
Return： 0 Set OK
 -EINVAL Input parameter error, keep is null
others Other error code
Be NEW8210
application
in：
Notes： Once it is set up, the backlight will run according to the set value. But
after system reset, the set value of backlight will recover to its default
one..

5.1.13. sys_get_machine_config

Prototype： int sys_get_machine_config(MachineConfig_t config[], uint32_t nr)

Function： Get local configuration information of module
Parameter config （output） The output of module configuration
： nr Get the expected maximal number of
module information, number of config.
Return： >= 0 The number of real output module
information
-EINVAL input parameter error
others other error code
Support： NEW8210
Notes： This function is used to obtain terminal’s module information, store
getting information in the structure of config, module name is shown:
Module name Module information
Terminal Terminal name（NEW8210）
Printer Printer type（）
Modem maximum rate of
synchronous/asynchronous
communication
PCI None
USB host USB standard
interface（USB2.0）
USB device None
Ethernet None
WIFI None
GPRS None
CDMA None
NFC None
5.1.14. led_get_brightness

Prototype int led_get_brightness(const char *led_name, uint32_t *brightness)

：
Function: Get the brightness of led light
Parameter: led_name led name
brightness Led brightness ， scope ： 0 ～ 255 ， 0
(output parameter) darkest，255 lightest
Return: 0 Set OK
-EINVAL Input parameter error
others Other error code
Be NEW8210
applicable
in:
Notes： LED name definition Corresponding
LED_ARROW_DOWN “down arrow” icon of LCD
LED_ARROW_UP ”up arrow” icon of LCD
LED_BATTERY_SHELL ”battery apperence” icon of LCD
LED_BATTERY_1 ”battery power”icon of LCD
LED_BATTERY_2
LED_BATTERY_3
LED_BATTERY_4
LED_BACKLIGHT LCD backlight
LED_CARD ”card” icon of LCD
LED_LCD_CONTRAST LCD contrast
LED_LOCK ”lock” icon of LCD
LED_POWER_SUPPLY ”power” icon of LCD
LED_MODEM_OFFHOOK ”off-hook” icon of LCD
LED_MODEM_ONHOOK ”on-hook” icon of LCD
LED_MODEM_BASE ”phone” icon of LCD
LED_SIGNAL_STATION ”wireless base station” icon of LCD
LED_SIGNAL_1 ”wireless signal” icon of LCD
LED_SIGNAL_2
LED_SIGNAL_3
LED_SIGNAL_4
LED_ONLINE Modem online LED indicator
LED_TX Modem send data LED indicator
LED_RX Modem receive data LED indicator
5.1.15. led_set_brightness

Prototype： int led_set_brightness(const char *led_name, uint32_t brightness)

Function： set the brightness of led light
Parameter led_name led name
： brightness Led brightness ， range ： 0 ～ 255 ， 0
darkest，255 brightest
Return： 0 Set OK
-EINVAL Input parameter error
Others Other error code
Support： NEW8210
Notes： For definition of led_name, please refer to led_get_brightness
For convenience, define 2 LED lightness:
#define LED_BRIGHTNESS_MIN 0
#define LED_BRIGHTNESS_MAX 255

5.1.16. sys_get_hardware_config

Prototype： int sys_get_hardware_config(const char *module, char type[128], int

*numbers)
Function： Get local configuration information of hardware module
Parameter module （input） The name of hardware module need to be
： obtained.
For details,please refer to the Notes.
type (output) The type of hardware module.
numbers Get the expected maximal numbers of the
hardware module.
Return： 0 Successful.
others Failed, please refer to <errno.h>.
Support： NEW8210
 Notes： Hardware modules(the parameter of module) as shown below:
Hardware module comment
HARDWARE_MACHINE Terminal Name（e.g. NEW8210
HARDWARE_BATTERY Battery
HARDWARE_LCD LCD
HARDWARE_TOUCHSCREEN Touch Screen
HARDWARE_KEYBOARD KeyBoard
HARDWARE_MSR Magnetic Stripe Reader
HARDWARE_PRINTER Printer
HARDWARE_NFC NFC
HARDWARE_TF TransFlash
HARDWARE_IC IC Card Reader
HARDWARE_SAM SAM Slot
HARDWARE_2SIM SIM Slot
HARDWARE_UART UART
HARDWARE_BARSCANNER Barcode Scanner
HARDWARE_WIRELESS Wireless
HARDWARE_MODEM MODEM
HARDWARE_LAN LAN
HARDWARE_WIFI WIFI
HARDWARE_BLUETOOTH BlueTouch
HARDWARE_USBH USB Host
HARDWARE_USBD USB Device
HARDWARE_USBO USB OTG
HARDWARE_GPS GPS
HARDWARE_FINGERPRINT FingerPrinter

5.1.17. sys_software_update

Prototype： int sys_software_update(const char *filename)

Function： Used to update the file of specified path (filename).
Parameter filename（input） The full path name of file that need to be
： updated.
Return： 0 Successful.
others Failed, please refer to <errno.h>.
 Be NEW8210
application
in：
Notes： Calling this function can update the file that is downloaded by TMS
remotely.
The parameter of filename is that downloaded by TMS and stored
temporarily int the POS machine.
The filename includes the firmware and the file packed by
New8210DownloadTool.
If it is a firmware, after calling this function, you must restart the
machine in order to complete the update.
If it is a packed file, call this function and then update is complete
immediately.

5.1.18. sys_battery_info

Prototype： int sys_battery_info(battery_info_t *battery_info)

Function： Obtain the information of battery。
Parameter battery_info status 0-Battery-powered
： (Output) 1-Charging
2-Full charge
3-External-powered
cur_values Current voltage
max_values Maximum voltage
min_values Minimum voltage
percent Percent of battery life
Return： 0 Successful
others Failed, please refer to <errno.h>.
Be NEW8210
application
in：
Notes:
5.2. Key board

Buttons definition of NEW8210 complies with standard PC-101 keyboard, users can get
the same result by operating an external keyboard, or pressing key in NEW8210 directly.
When user pressing an key, system will send the key value of key, and the state value of
this key is state “press down”, after 400ms, system will send key value of this key again,
the state value of the key is also “press down”, And then every 44ms system will send the
key value and “press down” state value , until the key release. System send key value of
the key and state “release”. In other words, as long as key is pressed, system will send
key value and state of the key all the time, until key is released.
The correspondence of NEW8210’s keys and PC-101’s keys is listed as follow:
NEW8210 PC-101 Code Symbol
key key
0 0 KEY_0 0x0B DIKS_0 0x30

1 1 KEY_1 0x02 DIKS_1 0x31

2 2 KEY_2 0x03 DIKS_2 0x32

3 3 KEY_3 0x04 DIKS_3 0x33

4 4 KEY_4 0x05 DIKS_4 0x34

5 5 KEY_5 0x06 DIKS_5 0x35

6 6 KEY_6 0x07 DIKS_6 0x36

7 7 KEY_7 0x08 DIKS_7 0x37

8 8 KEY_8 0x09 DIKS_8 0x38

9 9 KEY_9 0x0A DIKS_9 0x39

CANCEL Esc KEY_ESC 0x01 DIKS_ESCAPE 0x1B

ENTER Enter KEY_ENTER 0x1C DIKS_ENTER 0x0D

↑ ↑ KEY_UP 0x67 DIKS_CURSOR _UP 0xF002

↓ ↓ KEY_DOWN 0x6C DIKS_CURSOR _DOWN 0xF003

CLEAR Backspace KEY_BACKSPACE 0x0E DIKS_BACKSPACE 0x08

FEED PrScrn KEY_SYSRQ 0x63 DIKS_PRINT 0xF009

MENU Left Alt KEY_LEFTALT 0x38 DIKS_ALT 0xF204

FUNC Left Ctrl KEY_LEFTCTRL 0x1D DIKS_CONTROL 0xF202

ALPHA Left Shift KEY_LEFTSHIFT 0x2A DIKS_SHIFT 0xF201

ATM-1 F1 KEY_F1 0x3B DIKS_F1 0xF101

ATM-2 F2 KEY_F2 0x3C DIKS_F2 0xF102

ATM-3 F3 KEY_F3 0x3D DIKS_F3 0xF103

ATM-4 F4 KEY_F4 0x3E DIKS_F4 0xF104

The Power key is not listed here, because NEW8210 application program can’t control
and get this key, while pressing power key for more than 1.5 s, system will be turned off
automatically.
In addition, on default condition it will start printer’s function of “paper skip” when pressing
feed key, application program can get the key value of the key.
5.3. Display

NEW8210 display based on the DirectFB library, the web site is http://www.directfb.org.
API documents link is http://www.directfb.org/docs/DirectFB_Refer _1_4/index.html.

The applications based on DirectFB have its own “Window”, DrectFB manage the
entire display windows, and so that each program is displayed on the LCD does not
interfere with other programs. Besides manage the display windows, DirectFB also
manages the input devices, the event buffer, fonts, graphics, audio/video, providing
users with a unified, friendly programming interface.

NEW8210 can support these fonts:

 TTF/TTC
 OTB(X11 bitmap font)
 BDF(Bitmap Distribution Format)

NEW8210 can support these picture format:

 JPEG
 PNG
 GIF
 BMP

The formats of otb and bdf are point-array font library, the otb format is binary array
library, and the bdf format is text array library, these two formats can be converted to
each other, the file of bdf format is larger than that of otb format. No matter ttf library, or
otb, bdf font library, it is the same interface for external call, the programmer no need to
care for the different. Note: the ttf format is zoomable, but the otb and bdf formats unable
to do so, the size of them are fixed, if a not exist size is selected, it will not work.

5.3.1. DirectFB

5.3.1.1. Layers

It represents a separate image buffer. Most embedded devices have more than one
layer. Hardware using the appropriate alpha value for blending, then display.
5.3.1.2. Surface

A reserved area of memory used to store pixel data. The operation “drawing” and
“blitting” are ultimately act on the surfaces, the memory of surface can be obtained from
video memory, also can be obtained from system memory, which is determined by the
given limit.

5.3.1.3. Primary Surface

It represents a particular layer of special surface of the frame buffer. If the primary
surface is single buffer, any operation on this main surface will be seen on screen.
The relationship between them is some one-to-one or one-to-many:
1 IDirectFB  N Screens
1 Screen  N Layers
1 Layer  1 Primary Surface
1 Layer  N Windows
1 Window  1 Window Surface
1 Surface  N Subsurface
Usually one screen has a display layer, but DFB support each of them have multiple
instances.

5.3.1.4. Layers and Screens

Each screen has one or more layers, typically, a screen only has one layer, but some
system support overlays, due to hardware support one layer display above on other
layers, there can be exist many layers.

5.3.1.5. Screens and Windows

Screen can not create window directly, but you can request a primary layer`s ID, and
request IDirectFB interface for your layer interface, then by this interface, you can create
a window.

5.3.1.6. Surfaces and Windows

Every window associating with a surface, the content drawn to the surface will not
display on the screen immediately, because the window manager will assembles all
surfaces to a main surface – based on the region to be freshened and the sequence of
stack.

5.3.1.7. Surfaces and Layers

Every layer associating with a surface, too. This surface is a direct manifestation to
the layer memory. In exclusive mode, you can only access to this surface, otherwise, you
can only create a window, then draw the surface by window manager.

5.3.2. Program based on DirectFB

A basic application based on DirectFB is as following:

int main(int argc, char *argv[])

{
IDirectFB *dfb
DFBResult ret;

/* Initialize DirectFB including command line parsing. */

ret = DirectFBInit(argc, argv);
if (ret) {
DirectFBError("DirectFBInit() failed", ret);
goto exit_entry;
}

/* Create the super interface. */

ret = DirectFBCreate(&dfb);
if (ret) {
DirectFBError("DirectFBCreate() failed", ret);
goto exit_entry;
}

……

exit_entry:
……
return ret;
}

First you should initialize the DirectFB, by calling the API DicectFBInit(), process the
input parameter, then by calling the API DirectFBCreate() to create a dfb object. Note:
this object should be released by calling API Release() to release the resource occupied
by it.

Above we described the relation about screen, layer, window and surface, they are
seemed complex, you can remember the rule for short: when custom displays, it`s only to
surface,and the drawing operations are also valid only for surface, no matter this surface
is created on layer directly, or got from a created window, or created from another
surface.

There are many methods to get surface, we recommend using the following
procedure:

DirectFBInit

DirectFBCreate(&dfb)

dfb->GetDisplayLayer(&layer)

layer->CreateWindow (&window)

window->GetSurface(&surface)

5.3.3. Load image

Sometimes we need to display a image on LCD, the DirectFB has already provides a
set of APIs, for the programmers, we offer the following code to display a image.

static IDirectFBSurface *load_image(IDirectFB *dfb, const char *filename)

{
IDirectFBImageProvider *provider;
IDirectFBSurface *imgsurf = NULL;
DFBSurfaceDescription dsc;
DFBResult err;
 err = dfb->CreateImageProvider(dfb, filename, &provider);
if (err != DFB_OK) {
fprintf( stderr, "Couldn't load image from file '%s': %s\n",
filename, DirectFBErrorString( err ));
return NULL;
}

provider->GetSurfaceDescription(provider, &dsc);
dsc.flags = DSDESC_WIDTH | DSDESC_HEIGHT | DSDESC_PIXELFORMAT;
dsc.pixelformat = DSPF_ARGB;
if (dfb->CreateSurface(dfb, &dsc, &imgsurf) == DFB_OK)
provider->RenderTo(provider, imgsurf, NULL);

provider->Release(provider);

return imgsurf;
}

The code above used to load a image to a DirectFB`s surface, the image stored in
the surface memory, but it will not display on LCD. To display the image, another
operation is needed: IDirectFBSurface::Blit. To zoom for the image, you can use
IDirectFBSurface::stretchBlit, using the API IDirectFBSurface::TileBlit, you can magnify
the image to the full screen. Note: after these operations, if the surface with the image is
no longer be needed, you should call API Release() to release the resource, otherwise it
will lead to the leakage of memory.

5.3.4. Program linking

Applications based on DirectFB need the following DLLs:

 libz.so
 libfusion.so
 libdirect.so
 libdirectfb.so

When linking, please use command line: “-lz -lfusion -ldirect -ldirectfb”, and use “-L” to
index the path of these library.
5.4. Ped

PED supports Master/Session，fixed，DUKPT key solutions ， keys supports for every

key type：
Key name Number of keys
Master Key 1024
PIN Key 1024
MAC Key 1024
Fixed-PIN Key 1024
Fixed-MAC Key 1024
DUKPT Key 16
Supports online PIN and offline plaintext pin and offline encipher pin.

API functions of this module was defined in the “ped.h”; “libped.so” must be used when
linking.

5.4.1. ped_get_random

Prototype： uint32_t ped_get_random(void)

Function： Get a 32-bit randomness number.
Parameter None
：
Return： An unsigned randomness number (32 bits).
Support： NEW8210
Notes：

5.4.2. ped_get_random_nr

Prototype int ped_get_random_nr(uint32_t bytes, void *data)

：
Function： Get random number from PED
Parameter: bytes Bytes, less than 128kb
data （ output Buffer to receive the random numbers.
）
Return： 0 Success
 -1 Error. The error code please gets from the global
variable errno.
Support: NEW8210
Notes：

5.4.3. ped_set_pin_input_region

Prototype: int ped_set_pin_input_region(int x, int y, int width, int height)

Function: Set the PIN enter window postion
Parameter: x x
y Y
width Width
height Height
Return： 0 success
-1 Error. The error code please gets from the global
variable errno.
Support： NEW8210
Notes：

5.4.4. ped_format

Prototype： int ped_format(void)

Function： Rebuild PED (Or PED format), it will clear all PED key and unlock the
PED (If the PED is in lock status).
Only the root user can rebuild PED when PED was attacked.
Parameter None
：
Return： 0 Success
-1 Error. The error code please gets from the global variable
errno.
Support： NEW8210
Notes：

5.4.5. ped_clear_user_keys

Prototype： int ped_clear_user_keys(void)

Function： Clear current user’s (or current application) PED keys.
 Parameter None
：
Return： 0 Success
-1 Error. The error code please gets from the global
variable errno.
Support： NEW8210
Notes：

5.4.6. ped_delete_key

Prototype： int ped_delete_key(uint32_t KeyType, uint32_t KeyIndex)

Function： Delete one PED key own to the current application.
Parameter KeyType Delete key type.
： Support key type as follow:
KEY_TYPE_MASTK
KEY_TYPE_PINK
KEY_TYPE_MACK
KEY_TYPE_FIXPINK
KEY_TYPE_FIXMACK
KEY_TYPE_DUKPTK
KeyIndex Key index.
1.If the key type is KEY_TYPE_MASTK /
KEY_TYPE_PINK / KEY_TYPE_MACK /
KEY_TYPE_FIXPINK / KEY_TYPE_FIXMACK, the
key index value from 0 to 1023;
2.If the key type is KEY_TYPE_DUKPTKEY, the key
index value from 0 to 15;

Return： 0 Success
-1 Error. The error code please get from the global variable
errno.
Support： NEW8210
Notes：

5.4.7. ped_get_sensitive_timer

Prototype： int ped_get_sensitive_timer(uint32_t SensitiveType)

 Function： Get PED remain sensitive service time
Parameter SensitiveType[i] TYPE_PIN_INTERVAL 0x01 The time interval
： between twice pin
input operation.

Return： >=0 The remain time.

Support： NEW8210
Notes：

5.4.8. ped_set_pin_input_timeout

Prototype： int ped_set_pin_input_timeout(uint32_t timeout)

Function： Set PIN input time out value(unit: second).
Parameter timeout >120 Invalid input value.
： 30~120 Valid input value
0 Set the default timeout value 60 seconds.
<30 Invalid input value.
Return： 0 Success
-1 Error. The error code please get from the global variable
errno.
Support： NEW8210
Notes：

5.4.9. ped_get_dukpt_ksn

Prototype： int ped_get_dukpt_ksn(uint32_t KeyIndex, void *Ksn)

Function： Calculate PIN Block and MAC one time after one time KSN get
Parameter KeyIndex Key Index 0～15
： Ksn(Output) Get 10 bytes of KSN value
Return： 0 Success
-1 Error. The error code please gets from the global variable
errno.
Support： NEW8210
Notes： If continue call ped_get_mac_dukpt() 2 times or continue call
ped_get_pin_dukpt() 2 times, the KSN will change automatically.
5.4.10. ped_write_pin_key

Prototype： int ped_write_pin_key(uint32_t MasterKeyID, uint32_t PinKeyID,

uint32_t PinKeyLen, const void *PinKey)
Function： Write a PIN key into the PED, which encrypted by MasterKeyID, and
without verify code.
Parameter MasterKeyID Master key’s ID, 0...1023.
： PinKeyID The PIN key’s ID, 0...1023.
PinKeyLen Length of PinKey, 16 or 24.
PinKey This parameter will be filled the current PIN key
ciphertext data.
Return： 0 Success
-1 Error. The error code please gets from the global
variable errno.

Support： NEW8210
Notes：

5.4.11. ped_write_pin_key_ex

Prototype： int ped_write_pin_key_ex(uint32_t Mode, uint32_t MasterKeyID,

uint32_t DestKeyID, uint32_t KeyLen, const void *KeyData);
Function： Write PIN Key to PED
Parameter Mode TDEA_DECRYPT Encrypted KeyData
： KEY_VERIFY_NONE No check value
KEY_VERIFY_KVC KVC
KEY_VERIFY_CMAC CMAC
MasterKeyID Master key Index，value 0...1023.
DestKeyID PIN Key index，value 0...1023.
KeyLen KeyData length ， PIN Key data length
+Checkdata length（KVC、CMAC is 4 bytes）
KeyData Plaintext/Encipher PIN Key + Check data
Return： 0 Success
-1 Error. The error code please gets from the global
variable errno.
Support： NEW8210
Notes： The PIN key is encrypted by MasterKey, the ‘Mode’should be
TDEA_DECRYPT arithmetic or with one of
KEY_VERIFY_NONE，KEY_VERIFY_KVC，KEY_VERIFY_CMAC;
 The PIN key cannot be cipher text, so the ‘Mode’should not be
TDEA_NONE;
If with KVC check value, the KeyLen should be 8×n + 4 （n=1: single
DES，n=2: double DES，n=3: trible DES）
If with CMAC check value, then the KeyLen shoule be 32+4 bytes,
the 32 bytes:
typedef struct {
uint16_t KeyLen; /* Key length */
uint8_t Key[24]; /* Key value */
uint8_t Pad[6];
} TDesSecret_t;

5.4.12. ped_write_mac_key

Prototype： int ped_write_mac_key(uint32_t MasterKeyID, uint32_t MacKeyID,

uint32_t MacKeyLen, const void *MacKey);
Function： Write a encipher MAC key to PED, mac key encrypted by the
Masterkey, without check value.
Parameter MasterKeyID Index of Masterkey，Value 0...1023.
： MacKeyID MAC Key Index，Value 0...1023.
MacKeyLen MAC Key length, 16 or 24。
MacKey Encipher Mac key value
Return： 0 Success
-1 Error. The error code please gets from the global variable
errno.
Support： NEW8210
Notes：

5.4.13. ped_write_mac_key_ex

Prototype： int ped_write_mac_key_ex(uint32_t Mode, uint32_t MasterKeyID,

uint32_t DestKeyID, uint32_t KeyLen, const void *KeyData);
Function： Write MAC key to PED
Parameter Mode TDEA_DECRYPT KeyData is encrypted
： KEY_VERIFY_NONE No Check Code
KEY_VERIFY_KVC KVC
KEY_VERIFY_CMAC CMAC
MasterKeyID Master key index，value 0...1023.
DestKeyID MAC key index，value 0...1023.
 KeyLen KeyData Length ， Key data length +Check Code
Length（KVC、CMAC is 4 bytes）
KeyData Plaintext /Encipher Key Value + Check Code
Return： 0 Success
-1 Error. The error code please gets from the global variable
errno.
Support： NEW8210
Notes： The MAC key is encrypted by MasterKey, the ‘Mode’ should be
TDEA_DECRYPT arithmetic or with one of
KEY_VERIFY_NONE，KEY_VERIFY_KVC，KEY_VERIFY_CMAC;
The MAC key cannot be ciphertext, so the ‘Mode’ should not be
TDEA_NONE;
If with KVC check value, the KeyLen should be 8×n + 4 （ n=1:
single DES，n=2: double DES，n=3: trible DES）
If with CMAC check value, then the KeyLen should be 32+4 bytes,
the 32 bytes:
typedef struct {
uint16_t KeyLen; /* Key length */
uint8_t Key[24]; /* Key value */
uint8_t Pad[6];
} TDesSecret_t;

5.4.14. ped_write_master_key

Prototype： int ped_write_master_key(uint32_t Mode, uint32_t MasterKeyID,

uint32_t DestKeyID, uint32_t KeyLen, const void *KeyData)
Function： Write Master key to PED
Parameter Mode TDEA_DECRYPT KeyData is encrypted
： KEY_VERIFY_NONE No check code
KEY_VERIFY_KVC KVC
KEY_VERIFY_CMAC CMAC
MasterKeyID Master key index，value 0...1023.
DestKeyID Master Key Index，Value 0...1023.
KeyLen KeyData Length ， Key data length +Check Code
Length（KVC、CMAC is 4 bytes）
KeyData Plaintext /Encipher Key Value + Check Code
Return： 0 Success
-1 Error. The error code please gets from the global variable
errno.
 Support： NEW8210
Notes： If the MasterKey is encrypted by another MasterKey, then the
‘Mode’ should be TDEA_DECRYPT arithmetic or with one of
KEY_VERIFY_NONE，KEY_VERIFY_KVC，KEY_VERIFY_CMAC;
If the MasterKey is plaintext, then the ‘Mode’ should be
TDEA_NONE;
If with KVC check value, the KeyLen should be 8×n + 4 （n=1:
single DES，n=2: double DES，n=3: trible DES）
If with CMAC check value, then the KeyLen should be 32+4
bytes, the 32 bytes:
typedef struct {
uint16_t KeyLen; /* Key length */
uint8_t Key[24]; /* Key value */
uint8_t Pad[6];
} TDesSecret_t;

5.4.15. ped_inject_pin_key

Prototype： int ped_inject_pin_key(uint32_t PinKeyID, uint32_t PinKeyLen, const

void *PinKey);
Function： Inject Fixed-PIN key to PED
Parameter PinKeyID PIN key Index，Value 0...1023.
： PinKeyLen PIN key length, 16 or 24。
PinKey Plaintext PIN Key
Return： 0 Success
-1 Error. The error code please get from the global variable errno.
Support： NEW8210
Notes：

5.4.16. ped_inject_mac_key

Prototype： int ped_inject_mac_key(uint32_t MacKeyID, uint32_t MacKeyLen,

const void *MacKey);
Function： Inject plaintext Fixed-Mac key
Parameter MacKeyID MAC Key index，value 0...1023.
： MacKeyLen MAC Key Length, 16 or 24。
MacKey Plaintext MAC key value.
 Return： 0 Success
-1 Error. The error code please get from the global variable errno.
Support： NEW8210
Notes：

5.4.17. ped_create_dukpt_key

Prototype： int ped_create_dukpt_key(uint32_t KeyIndex, const void *InitKey,

uint32_t KeyLen, const void *Ksn);
Function： Inject DUKPT key
Parameter KeyIndex DUKPT Index 0～15
： InitKey Initialize key 16 bytes
KeyLen Key length，16
Ksn 10 bytes KSN
Return： 0 Success
-1 Error. The error code please get from the global variable errno.
Support： NEW8210
Notes：

5.4.18. ped_get_pin

Prototype： int ped_get_pin(uint32_t KeyIndex, uint32_t Mode, const char

*ExpectPinLen, const char *CardNo, void *PinBlock)
Function： Let cardholder input PIN and Compute the PIN block.
Parameter KeyIndex PIN key ID, 0…1023.
： ExpectPinLen Allowed PIN entry length character string,
application enumerates all allowed PIN entry
length set and uses comma to separate then. Eg.
Application inputs “0,4,6” and it means application
allow cardholder to input no PIN, or Four digital
key or six digital key. The length of 1,2,3 and
longer than 12 are forbidden.
CardNo 16 bytes card number.
Format 0:
16 bit card number after shift (ASCII, PAN is valid
in CardNo[4]~CardNo[15]).
Format EPS:
10 byte string: the first 4 bytes is ‘1234’, the last 6
 bytes is ISN.
Mode PIN_BLOCK_FORMAT_0
/PIN_BLOCK_FORMAT_EPS
PinBlock The PIN BLOCK result, 8 bytes.
Return： 0 Success
-1 Error. The error code please get from the global variable
errno.
Support： NEW8210
Notes： The default timeout is 120 seconds. If you want to set the timeout
value, please call the API ped_set_pin_input_timeout() to set.
Note: PIN input is sensitive service, if the time between two PIN input
is too fast, the operation will be refused. So you can call
ped_get_sensitive_timer() to get current state, if the return value
large than 0(etc n), it means only after n seconds, you can inpuit PIN
again.

Explain :
(1) ANSI X3.92 standard(Format EPS) as follow:
Data string format:”1234” + ISN [6bytes] + PIN[6bytes];
If PIN not enough 6 bytes, then fill ‘0’ with ahead.
Convert the string to BCD code, and use TPK as the key to TDEA.
(2) ANSI X9.8 standard(Format 0) as follow:
String 1 is “0000” with suffix of card number last 12 charters.
Convert string 1 to BCD bytes.
String 2 is PIN length [ASCII, 2bytes] + PIN [ASCII];
If string 2 not enough 16 bytes, add charter ‘F’ to the tail, and convert string 2 to BCD
bytes.
Use string 1 BCD XOR string 2 BCD then get 8 bytes number K, use TPK as TDEA key
to encrypt K, and then get the PIN_BLOCK.

5.4.19. ped_get_pin_fix

Prototype： int ped_get_pin_fix(uint32_t KeyIndex, const char *ExpectPinLen,

const char *CardNo, uint32_t Mode, void *PinBlock)
Function： Let cardholder input PIN and Compute the PIN block, different from
ped_get_pin, this API use fixed key hierarchy.
Parameter KeyIndex PIN key ID.
： ExpectPinLen Allowed PIN entry length character string,
application enumerates all allowed PIN entry
length set and uses comma to separate then. Eg.
Application inputs “0,4,6” and it means application
allow cardholder to input no PIN, or Four digital
 key or six digital key. The length of 1,2,3 and
longer than 12 are forbidden.
CardNo 16 bytes card number.
Format 0:
16 bit card number after shift (ASCII, PAN is valid
in CardNo[4]~CardNo[15]).
Format EPS:
10 byte string: the first 4 bytes is ‘1234’, the last 6
bytes is ISN.
Mode PIN_BLOCK_FORMAT_0
PIN_BLOCK_FORMAT_EPS
PinBlock The PIN BLOCK result, 8 bytes.
Return： 0 Success
-1 Error. The error code please gets from the global variable
errno.
Support： NEW8210
Notes： Refer to ped_get_pin

5.4.20. ped_get_pin_dukpt

Prototype： int ped_get_pin_dukpt(uint32_t KeyIndex, uint32_t Mode, const char

*ExpectPinLen, const void *CardNo, void *PinBlock)
Function： Let cardholder input PIN and Compute the PIN block.
Parameter KeyIndex DUKPT key ID, from 0 to 15.
： ExpectPinLen Allowed PIN entry length character string,
application enumerates all allowed PIN entry
length set and uses comma to separate then. Eg.
Application inputs “0,4,6” and it means application
allow cardholder to input no PIN, or Four digital
key or six digital key. The length of 1,2,3 and
longer than 12 are forbidden.
CardNo 16 bytes card number.
Format 0:
16 bit card number after shift (ASCII, PAN is valid
in CardNo[4]~CardNo[15]).
Format EPS:
10 byte string: the first 4 bytes is ‘1234’, the last 6
bytes is ISN.
Mode PIN_BLOCK_FORMAT_0
/PIN_BLOCK_FORMAT_EPS
 PinBlock[o] The PIN BLOCK result.
Return： 0 Success
-1 Error. The error code please get from the global variable
errno.
Support： NEW8210
Notes： Refer to ped_get_pin

5.4.21. ped_icc_offline_plain_pin

Prototype： int ped_icc_offline_plain_pin(int iccfd, const char *ExpectPinLen,

const IccOfflinePinApdu_t *icc, uint32_t *rsplen, void *rspdata)
Function： PED prompts cardholder to input PIN. Once PED kernel gets plaintext PIN,
PED kernel transfer it to plaint PIN BLOCK and sends corresponding
command to ICC card in corresponding slot indicated by CardSlot for
offline plaintext authentication.
Parameter iccfd ICC card device ID.
： ExpectPinLen The input PIN max length is 12.
Allowed PIN entry length character string, application
enumerates all allowed PIN entry length set and uses
comma to separate then. Eg. Application inputs “0,4,6”
and it means application allow cardholder to input no
PIN, or Four digital key or six digital key.
icc Check command structure [Input]
Format: CLA＋INS＋P1＋P2＋LC
rsplen rspdata length.
rspdata Card respond code
(Two byte returned code: SWA＋SWA)
Return： 0 Success
-1 Error. The error code please get from the global variable
errno.
Support： NEW8210
Notes： As for the length of PIN entry control, please refer to the description in
online PIN entry.
The format of Plaintext offline PIN block showed following:
C N P P P P P/ P/ P/ P/ P/ P/ P/ P/ F F
F F F F F F F F

Name Value
C Control field 4 bit binary ‘0010’(hex. 2)
N PIN length 4 bit binary from ‘0010’ to ‘1100’ (hex form ‘4’ to
 ‘c’)
P PIN 4 bit binary from ‘0000’ to ‘1001’ (hex form ‘0’ to
‘9’)
P/F PIN/ pad bit Decided by PIN length
F Padding bit 4 bit binary ‘1111’(hex. ‘F’)
Note: PIN input is sensitive service, if the time between two PIN input
is too fast, the operation will be refused. So you can call
ped_get_sensitive_timer() to get current state, if the return value
large than 0(etc n), it means only after n seconds, you can inpuit PIN
again.

typedef struct {
uint32_t modlen; // The module length of PIN encryption public
key,
uint8_t mod[256]; // The module data of PIN encryption public
key,
uint32_t explen; // The exponet length of PIN encryption public
key,
uint8_t exp[4]; // The exponet data of PIN encryption public
key,
uint8_t iccrandom[8]; // The random data from ICC
} RsaPinKey_t;

The structure of IccOfflinePinApdu_t:

typedef struct {
uint8_t cla;
uint8_t ins;
uint8_t p1;
uint8_t p2;
uint8_t leflg;
uint8_t le;
RsaPinKey_t rsakey;
} IccOfflinePinApdu_t;

5.4.22. ped_icc_offline_cipher_pin

Prototype： int ped_icc_offline_cipher_pin(int iccfd, const char *ExpectPinLen,

const IccOfflinePinApdu_t *icc, uint32_t *rsplen, void *rspdata)
Function： PED prompts cardholder to input PIN. Once PED kernel gets plaintext PIN,
PED kernel encrypted it to cipher PIN BLOCK using RsaPinKey according
 to EMV supplied format and sends corresponding command to ICC card in
corresponding slot indicated by CardSlot for offline cipher authentication.
Parameter iccfd [input] ICC card device ID.
： ExpectPinLen The input PIN max length is 12.
Allowed PIN entry length character string, application
enumerates all allowed PIN entry length set and uses
comma to separate then. Eg. Application inputs “0,4,6”
and it means application allow cardholder to input no
PIN, or Four digital key or six digital key.
icc[input] Check command structure
Format: CLA＋INS＋P1＋P2＋LC
Rsplen[output] rspdata length.
Rspdata[output] Card respond code
(Two byte returned code: SWA＋SWA)
Return： 0 Success
-1 Error. The error code please get from the global variable
errno.
Support： NEW8210
Notes： 1. The API can be used in any status whether lock or not.
2. Calling this API needs sensitive service authority (API completes
automatically)
3. encryption Algorithm
PED uses RSA_PINKEY to encrypt the below data structure to generate
Cipher PIN
Field Name length Description Unit
Header 1 0x7F b
PIN BLOCK 8 PINBLOCK b
Random form IC card 8 RSA_PINKEY supplies the data b
from IC card
Padding data NIC– RSA_PINKEY supplies padding b
17 data from application

Note: PIN input is sensitive service, if the time between two PIN input
is too fast, the operation will be refused. So you can call
ped_get_sensitive_timer() to get current state, if the return value
large than 0(etc n), it means only after n seconds, you can inpuit PIN
again.

IccOfflinePinApdu_t : please refer to ped_icc_offline_plain_pin

5.4.23. ped_get_mac

Prototype： int ped_get_mac(uint32_t KeyIndex, uint32_t Mode, uint32_t

DataLen, const void *DataIn, void *MacOut)
Function： Compute the input data’s MAC value.
Parameter KeyIndex MAC key ID.
： DataIn The input data will be computed the MAC value.
DataLen 8/16/24/32/40/48...
Mode MAC_MODE_1
MAC_MODE_2
MAC_MODE_EMV
MAC_MODE_CUP
MacOut The MAC result, 8 bytes.
Return： 0 Success
-1 Error. The error code please get from the global variable
errno.
Support： NEW8210
Notes：
Explain :
Algorithm 1:
When Len = 8, only use data to do one DES/3DES encrypt.
When Len > 8, we use the standard algorithm to encrypt MAC data. The algorithm as follow:
 D1(8bytes) D2(8bytes) D3(8bytes) …… Dn(8bytes)

K1

R1

K2

R1

K3

R3

Kn

Rn

We use first 8 bytes data (D1) as K1, and use the MAC key TDEA encrypt K1 get result R1.
R1 XOR with the second 8 bytes data (D2) then get the result K2. Use the MAC key TDEA
encrypt K2 get result R2…… and so on, the last Rn is the MAC result.

Algorithm 2:
When Len = 8, only use data to do one DES/3DES encrypt.
When Len > 8, we use the standard algorithm to encrypt MAC data. The algorithm as follow:
 D1(8bytes) D2(8bytes) D3(8bytes) …… Dn(8bytes)

K2

K2

K2

Kn

MAC

EMV2000 Algorithm:
EMV2000 Algorithm is very like as Algorithm 1. If MAC key length is 8 bytes, that
EMV2000 Algorithm is same as Algorithm 1; If MAC key length is 16 bytes or 24 bytes, there are
some different, from the step 1 to the step n-1 are use 8bytes MAC key to encrypt data, and the
step n use 16 bytes or 24 bytes MAC key to encrypt data.
China UnionPay algorithm:
 D1(8bytes) D2(8bytes) D3(8bytes) …… Dn(8bytes)

K2

K2

K2

Kn

Convert Kn to 16ASCII char

First 8 char Last 8 char

R1

R2

Convert R2 to 16 ASCII
char

The first 8 char is the result MAC

5.4.24. ped_get_mac_fix

Prototype： int ped_get_mac_fix(uint32_t KeyIndex, uint32_t Mode, uint32_t

DataLen, const void *DataIn, void *MacOut)
Function： Compute the input data’s MAC value.
Parameter KeyIndex MAC key ID.
： DataIn The input data will be computed the MAC value.
DataLen 8/16/24/32/40/48...
Mode MAC_MODE_1
MAC_MODE_2
 MAC_MODE_EMV
MAC_MODE_CUP
MacOut The MAC result, 8 bytes.
Return： 0 Success
-1 Error. The error code please get from the global variable
errno.
Support： NEW8210
Notes：

5.4.25. ped_get_mac_dukpt

Prototype： int ped_get_mac_dukpt(uint32_t KeyIndex, uint32_t Mode, uint32_t

DataLen, const void *DataIn, void *MacBlock)
Function： Compute the input data’s MAC value by using DUKPT key.
Parameter KeyIndex DUKPT key ID, from 0 to 15.
： DataIn The MAC data need to compute MAC value.
DataLen The MAC data length. 8/16/24/32/40/48...
Mode MAC_MODE_1
MAC_MODE_2
MAC_MODE_EMV
MAC_MODE_CUP
MacBlock MAC data compute result, 8 bytes.
Return： 0 Success
-1 Error. The error code please get from the global variable
errno.
Support： NEW8210
Notes：

5.4.26. ped_inject_key_by_root

Prototype： int ped_inject_key_by_root(uint32_t CUID, uint32_t KeyType,

uint32_t KeyIndex, uint32_t KeyLen, const void *PlaintextKey);
Function： Key injection with root authority
Parameter CUID CID + UID
： KeyType Key Type
KeyIndex Key Index
KeyLen Key length
 PlaintextKey Plaintext key value
Return： 0 Success
- Error. The error code please get from the global variable
1 errno.
Support： NEW8210
Notes： Used to inject key, this function can be called by the root user only.

5.4.27. ped_get_config

Prototype： int ped_get_config(PedConfig_t *config)

Function： Get PED terminal system information.
Parameter Config[output] The PedConfig_t structure pointer.
：
Return： 0 Success
-1 Error. Please get the error code from the global
variable errno.
Support： NEW8210
Notes： The structure as follow:
typedef struct
{
char Model[16]; // POS Model
char HwVer[16]; // Hardware version
char SwVer[16]; // Software version
uint32_t Status; // PED status
uint32_t MaxBps; // PED max support bauds.
uint32_t MaxAppNum; // PED max support application number.
uint32_t MasterKeyNum; // Support master key number.
uint32_t PINKeyNum; // Support PIN key number.
uint32_t MACKeyNum; // Support MAC key number.
uint32_t FixPINKeyNum; // Support Fixed PIN key number.
uint32_t FixMACKeyNum; // Support Fixed MAC key number.
uint32_t DukeyKeyNum; // Support DUKPT key number.
uint32_t Ctime; // Key generate time.
uint32_t MagKeyTime; // magnetic strip card key generate time.
uint32_t MagKeyStatus; // magnetic strip card key valid flag.
uint8_t Res[160]; // reserved
}PedConfig_t; // 256 bytes
5.5. N20 external PINPAD

API functions of this module was defined in the “epp.h”; “libepp.so” must be used when
linking.

5.5.1. module macro definition

Please refer to file “epp.h”

#define KEY_TYPE_MASTER 0x01

#define KEY_TYPE_MAC 0x02
#define KEY_TYPE_PIN 0x03
#define KEY_TYPE_DUKPT_MAC 0x04
#define KEY_TYPE_DUKPT_PIN 0x05
#define KEY_TYPE_FIXED_MAC 0x10
#define KEY_TYPE_FIXED_PIN 0x11

#define EPPINFO_PRODUCT_NAME 0x00

#define EPPINFO_HW_VER 0x01
#define EPPINFO_HW_CFG 0x02
#define EPPINFO_EPP_SN 0x03
#define EPPINFO_CPU_ID 0x04
#define EPPINFO_BOOT_VER 0x10
#define EPPINFO_KERNEL_VER 0x11
#define EPPINFO_PROTOCOL_VER 0x20

enum EPP_ERROR_CODE
{
EPP_SUCCESS = 0,
EPP_RECV_PACKET_ERROR=2001,
EPP_PORT_OPEN_ERROR,
EPP_SEND_PACKET_ERROR, // 3
EPP_PACKET_LEN_ERROR,
EPP_RECV_TIMEOUT, // 5
EPP_PACKET_LEN_TOO_LONG,
EPP_CRC_CHECK_ERROR, // 7
EPP_OPEN_FILE_ERROR,
EPP_SEEK_FILE_ERROR, // 9
 EPP_WRITE_FILE_ERROR,
EPP_READ_FILE_ERROR, // 11
EPP_CONFIGURE_INVALID,
EPP_CONFIGURE_MAC_ERROR, // 13
EPP_NO_PIN,
EPP_SEND_CMD_ERROR, // 15
EPP_RECV_CMD_ERROR,
EPP_RECV_RET_ERROR, // 17
EPP_RECV_LEN_ERROR,
EPP_MAC_CHECK_ERROR, // 19
EPP_AUTHEN_FAILED,
EPP_INPUT_PARAM_ERROR, // 21
EPP_USER_PRESS_CANCEL,
EPP_INPUT_CMD_ERROR, // 23
EPP_INPUT_KEY_INDEX_ERROR,
EPP_INPUT_MAC_LEN_ERROR, // 25
EPP_INPUT_MODE_ERROR,
EPP_KEY_TYPE_ERROR, // 27
EPP_KEY_INDEX_ERROR,
EPP_MASTER_KEY_INDEX_ERROR, // 29
EPP_BMP_ERROR,
EPP_PIN_CFG_LANGE_TYPE_ERROR, // 31
EPP_PIN_CFG_SYMBOL_TYPE_ERROR,
EPP_INPUT_DATA_LEN_ERROR, // 33
EPP_SET_PORT_ERROR,
EPP_CFG_ERROR, // 35
EPP_CLOSE_FAILED,
};

enum N20_RETURN_CODE{
RET_ERROR_BASE = 2300,
RET_PASSWORD_ERROR, // 1
RET_BOOT_LEN_ERROR,
RET_BOOT_HASH_ERROR, // 3
RET_BOOT_MAC_ERROR,
RET_NOT_UBSK, // 5
RET_CHECK_UBSK_FAILED,
RET_CHECK_KSK_FAILED, // 7
RET_NOT_LCK,
RET_NOT_AUTH, // 9
RET_NOT_LOGON,
RET_RECV_FAILED, // 11
RET_AUTH_CHECK_FAILED,
 RET_MAC_CHECK_FAILED, // 13
RET_CRC_CHECK_ERROR,
RET_KVC_CHECK_ERROR, // 15
RET_NOT_APP_FREE_SPACE,
RET_APP_NOT_EXIST, // 17
RET_KEY_TYPE_ERROR,
RET_KEY_TYPE_NOT_SUPPORT, // 19
RET_MAC_LEN_ERROR,
RET_MAIN_KEY_INDEX_ERROR, // 21
RET_MAIN_KEY_NOT_EXIST,
RET_KEY_INDEX_ERROR, // 23
RET_KEY_LEN_ERROR,
RET_KEY_BE_USE, // 25
RET_MAIN_KEY_BE_USE, // 26
RET_MAC_ALG_MODE_ERROR,
RET_KEY_GET_ERROR,
RET_KEY_OVER_FLOW, // 29
RET_KEY_SAME_ERROR,
RET_KEY_NOT_EXIST, // 31
RET_KEY_MAC_CHECK_FAILED,
RET_KEY_KSN_LEN_ERROR, // 33
RET_KEY_BDK_LEN_ERROR,
RET_USER_PRESS_CANCEL_EXIT, // 35
RET_USER_INPUT_TIME_OUT,
RET_KSN_LEN_RERROR, // 37
RET_APP_NUM_OVER_FLOW,
RET_RW_LENGTH_ERROR, // 39
RET_PIN_KEY_TIME_LOCK,
RET_MAC_KEY_TIME_LOCK, // 41
RET_SET_PIN_TIME_OUT_ERROR,
RET_WRITE_EEPROM_FAILED, // 43
RET_RECV_LEN_ERROR,
RET_PARAM_ERROR // 45
};

typedef struct {
BYTE AppName[32];
BYTE Lck[16];
BYTE Mtek[24];
BYTE Akdak[16];
BYTE Akuak[16];
BYTE Mdtek[24];
BYTE Mutek[24];
} EppAuthKey_t; // 152 bytes
5.5.2. module structure

typedef struct {
BYTE KeyType; /* key type
0x01：master key；
0x02：MAC key；
0x03：PIN key；
0x10：Fixed MAC key；
0x11：Fixed PIN key； */
BYTE Mode;/*
Bit0~3 TDEA_DECRYPT 0x00 use decryption method to get expressly
target key
TDEA_NONE 0x02 write into expressly target key directly(is
invalid to MAC key and PIN key)
Bit4~7 PARITY_NONE 0x00 no check on the (decrypted) Key express
PARITY_ODD 0x10 odd parity on the (decrypted) key express
PARITY_EVEN 0x20 even parity on the (decrypted) key
express*/
BYTE KeyLen; // length of key, valid values is 8/16/24
BYTE KeyIndex; // Key Index[1,100]
BYTE MasterKeyIndex; /*master key index[1,100], this parameter is valid just when
key type is MAC key or PIN key*/
BYTE KeyData[24]; // content of key
} EppAppKey_t;

typedef struct _EPP_CONFIGURE_ EPP_CFG;

5.5.3. epp_open

Prototype： EPP_CFG *epp_open(const char *filename, int oflag)

Function： Open the N20 EPP device.
Parameter filename N20 device name always will be“/dev/ttyS4”or“/dev/ttyS6”。
： oflag parameter can only be O_RDWR
Return： NULL error return
other EPP port parameter handle
Be NEW7110
applicable
in：
Notes：

5.5.4. epp_close

Prototype： int epp_close(EPP_CFG *cfg)

Function： close opened N20 device
Parameter cfg（input） EPP device handle which is opened by epp_open
：
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes： after close, EPP port parameter handle cfg will be invalid and can not
use again

5.5.5. epp_init

Prototype int epp_init(EPP_CFG *cfg, const EppAuthKey_t *eppkey)

：
Function： Modify current key configure.
1、if use default configure, do not need to call this interface；
2 、 if don’t use default configure, initial configuration each time when
starting device。
Parameter: cfg（input） EPP device handle which is opened by epp_open
eppkey configure key
eppkey-> AppName : application name have max
16bytes
eppkey->Lck ： 16 bytes LCK key
eppkey->MTEK ： 24 bytes MTEK key
eppkey->AKDAK ： 16 bytes AKDAK key
eppkey->AKUAK ： 16 bytes AKUAK key
eppkey->MDTEK ：24 bytes MDTEK key
eppkey->MUTEK ：24 bytes MUTEK key
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.6. epp_download_lck_mtek

Prototype int epp_download_lck_mtek(EPP_CFG *cfg)

：
Function： Inject the LCK and MTEK into the N20 PINPAD. And the N20 EPP will
execute format operation, and then save the LCK and MTEK.
Parameter: cfg（input） EPP device handle which is opened by epp_open
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.7. epp_download_aik

Prototype int epp_download_aik(EPP_CFG *cfg)

：
Function： Save the current AIK to the N20 PINPAD. AIK includes 4 keys of
AppName and AKDAK/AKUAK/MDTEK/MUTEK and etc. All the key of
this application will be cleared.
Parameter: cfg（input） EPP device handle which is opened by epp_open
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.8. epp_download_appkey

Prototype int epp_download_appkey(EPP_CFG *cfg, const EppAppKey_t

： *appkey)
Function： Inject one application key into external N20 PINPAD.
Parameter: cfg（input） EPP device handle which is opened by epp_open
appkey (1)appkey -> KeyType ：key type
0x01 : Master Key;
0x02 : MAC key;
0x03 : PIN key;
0x10 : Fixed MAC key;
0x11 : Fixed PIN key;
(2)appkey -> Mode ：
Bit0~3
TDEA_DECRYPT 0x00 Inject the key Cipher text and
use the master key to decrypt it, thus get the key plain
text and save it.
TDEA_NONE 0x02 Inject the key Plain text.
(Except for MAC key and
PIN key)
Bit4~7
PARITY_NONE 0x00 The key plain text has no parity.
PARITY_ODD 0x10 The key plain text has odder
parity.
PARITY_EVEN 0x20 The key plain text has even
parity.
(3) appkey->KeyLen ：key length, 8/16/24;
(4) appkey-> KeyIndex ：Key index [1,100]；
(5) appkey-> MasterKeyIndex ： Master key index
[1,100], When the key type is not MAC key or PIN key,
this parameter not effective.
(6) appkey-> KeyData[24] ：content of key。
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.9. epp_download_dukpt_key

Prototype： int epp_download_dukpt_key(EPP_CFG *cfg, uint32_t KeyIndex,

const void *pBDK, const void *pKSN, uint32_t KSNLen)
Function： Inject DUKPT key into external N20 PINPAD. Only the DUKPT version
support.
Parameter: cfg （ inp EPP device handle which is opened by epp_open
 ut）
KeyInde Key index, no use currently. Key index just binding to
x application name.
pBDK 16 bytes base deride key input, not divergent BDK
pKSN content of KSN
KSNLen KSN length[1,10]
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.10. epp_get_mac

Prototype： int epp_get_mac(EPP_CFG *cfg, uint32_t KeyType, uint32_t KeyIndex,

uint32_t Mode, const void *pData, size_t DataLen, void *pMacOut)
Function： MAC operation API in external N20 PINPAD。
Parameter: cfg （ input EPP device handle which is opened by epp_open
）
KeyType key type, can get values
KEY_TYPE_MAC（=0x02） /
KEY_TYPE_FIXED_MAC (=0x10) /
KEY_TYPE_DUKPT_MAC (=0x04)。
KeyIndex MAC key index. If the key is MAC or Fixed MAC the key
index value from 1 to 100. If the key is DUKPT MAC, this
parameter has no use.
Mode Algorithm select
0x00 Algorithm 1
0x01 Algorithm 2
0x02 EMV2000 Algorithm
0x03 CUP Algorithm
pData MAC data
DataLen MAC data length, from 1*8 to 253*8 bytes.
Parameter: pMacOu 8 bytes MAC result, If the key type is DUKPT_MAC_KEY,
（output） this parameter will output 8 bytes MAC result and 10 bytes
current KSN.
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
 Notes： See below。
Notes：
Algorithm 1：
If Len = 8, do DES/3DES encryption operation on Data one time.
If Len > 8, do standard MAC encryption operation on data, algorithm as
shown:

8bytes(start) 8bytes 8bytes …… 8bytes(end)

encryption

encryption

encryption

encryption

MAC

First 8 bytes do DES/3DES encryption one time, the result will do xor with
next set of data(8 bytes), and do DES/3DES encryption one time again,…after
the final set of data have done one DES/3DES encryption,get MAC operation
result(8 bytes).
Algorithm 2：
If Len = 8, do DES/3DES encryption operation on Data one time.
If Len > 8, do standard MAC encryption operation on data, algorithm as
shown:
 8bytes(start) 8bytes 8bytes …… 8bytes(end)

encryption

MAC

After xor to all data(every 8 bytes xor one time),finally do an DES/3DES

encryption on xor result,get MAC operate result(8 bytes).
The algorithm found EMV2000：
This algorithm is similar to algorithm1.If key length is 8 bytes, then this algorithm is
the same as algorithm 1; if key length is 16 bytes or 24 bytes, then there will be some
difference, assuming that it total needs n steps of encryption operation, then the
difference is the previous n-1 steps operation is all DES encryption, and the final one is
3DES operation.
China Merchants Bank use this algorithm.
Algorithm which is fit to CUP:
This algorithm is similar to algorithm 2, put the data into 8 bytes a segement,
assuming that it has n segements, then xor all these segements(just like algorithm2),
finally get a 8 bytes data Block8, then change Block8 into 16 ASCII characters
Block16(for example, change 0x6a into 2 characters ‘6’,’A’).
 8bytes(start) 8bytes 8bytes …… 8bytes(end)

Change into 16 ASCII characters

First 8 characters Last 8 characters

encryption

encryption

Change into 16 ASCII characters

first 8 characters is MAC operation result

5.5.11. epp_get_pin

Prototype int epp_get_pin(EPP_CFG *cfg, uint32_t KeyType, uint32_t KeyIndex,

： uint32_t DisplayMode, uint32_t AlgMode, const void *pCardInfo, const
void *pLenInfo, void *pPinBlockOut)
Function： PIN block compute API via into external N20 PINPAD。
Parameter: cfg（input） EPP device handle which is opened by epp_open
KeyType Key type:
KEY_TYPE_PIN /
KEY_TYPE_FIXED_PIN /
KEY_TYPE_DUKPT
KeyIndex Key index.
If the key type is PIN or Fixed PIN, it value is from 1
 to 100.
If the key type is DUKPT PIN, this parameter is no
using.
DisplayMode PIN display attribute.
0 : from left to right;
1 : from right to left;
2 : middle.
AlgMode Algorithm select.
0x00 : means choose “Format0 mode”
algorithm;
0x01 : means choose “Format EMV mode”
algorithm;
0x0a : means choose “Format EPS mode”
alforithm.
pCardInfo Card information
pLenInfo PIN key length enumeration charter, support length
from 0 to 12. We use the ASCII charter ‘0’, ‘1’, ……,
‘9’, ‘a’, ‘b’, ‘c’ to represent 0~12. Such as the string
‘0456a\0\0\0\0\0\0\0\0\0’ means support input PIN
length are 0,4, 5, 6, 10.
pPinBlockOut 8 bytes PIN compute result, 10 bytes is current
（output） KSN,this parameter is valid just to DUKPT.
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes： Notes：
(1) ANSI X3.92 standard is below，Format 0 mode：
Format of data string:”1234”+ISN[6 bytes]+PIN[bytes bits];
If the PIN less than 6 bytes, fill ‘0’ before the PIN;
Change data string above into BCD code, use TPK to do
DES/3DES encryption on BCD code.
ANSI X9.8 standard is follow, Format EPS mode:
String 1: “0000” add last 12 bit of card number;
Change string1 into BCD code;
String 2: PIN length[ASC code, 2 bytes]+PIN[ASC code];
If the string2 is less than 16 bytes,fill ‘F’ after string2, then
change it into BCD code;
Do xor between string1’s BCD code and string2’s BCD code,
use TPK to do DES/3DES encryption on it .
(2) Format EMV mode:
User input PIN characters+number of characters ‘F’,and make
up into a character string of 16 characters, then change the
 string into 8 bytes BCD code, and use TPK to do DES/3DES
encryption on it. On this mode, card information is
meaningless.

5.5.12. epp_get_tdea

Prototype： int epp_get_tdea(EPP_CFG *cfg, uint32_t Mode, uint32_t KeyType,

uint32_t KeyIndex, const void *pDataIn, size_t DataLen, void
*pDataOut)
Function： TDEA algorithm in the external N20 PINPAD.
Parameter: cfg（inp EPP device handle which is opened by epp_open
ut）
Mode algorithm select.
TDEA_ENCRYPT : Encrypt
TDEA_DECRYPT : Decrypt
TDEA_MODE_ECB--- ECB algorithm mode
TDEA_MODE_CBC--- CBC algorithm mode
Please refer to the NEW7110 SDK macro define.
KeyTyp Key type
e 0x01 : Master key;
0x02 : PIN Key;
0x03 : MAC Key;
0x04 : DUKPT MAC Key;
0x05 : DUKPT PIN Key;
0x10 : Fixed MAC Key;
0x11 : Fixed PIN Key.
KeyInde Key index.
x If the key type is Master, MAC, PIN, Fixed MAC or Fixed
PIN, it value is from 1 to 100.
If the key type is DUKPT MAC or DUKPT PIN, this
parameter is no using.
pDataIn Compute data.
DataLe data length, for 1*8 to 12*8.
n
pDataO Compute result, the length is the same as input data.
ut （ out
put）
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.13. epp_set_pin_input_timeout

Prototype： int epp_set_pin_input_timeout(EPP_CFG *cfg, ulong TimeoutMs)

Function： Set PIN input timeout via external N20 PINPAD.
Parameter: cfg （ input EPP device handle which is opened by epp_open
）
TimeoutMs time out, unit ms。
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.14. epp_set_tdes_iv

Prototype： int epp_set_tdes_iv(EPP_CFG *cfg, const void *pIvData)

Function： Set TDES initial vector of into external N20 PINPAD, only effect CBC
algorithm.
Parameter: cfg （ inp EPP device handle which is opened by epp_open
ut）
pIvData 8 bytes input vector.
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes： Call this interface to set initial vector will effect CBC algorithm’s initial
vector that is called by epp_get_tdea(), and it will not effect other
interface, after restart N20, initial vector will recover to 8 zero.

5.5.15. epp_get_rand

Prototype int epp_get_rand(EPP_CFG *cfg, void *pRandBuf, size_t size)

：
Function： Get random number from external N20 PINPAD.
Parameter: cfg EPP device handle which is opened by epp_open
（input）
size output buffer size
pRandBuf save got random number
（output）
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.16. epp_clear_key

Prototype int epp_clear_key(EPP_CFG *cfg, uint32_t KeyType, uint32_t KeyIndex)

：
Function： Clear the desinated key of current application in external N20 PINPAD.
Parameter: cfg（input） EPP device handle which is opened by epp_open
KeyType key type
0x01 : Master key;
0x02 : MAC key;
0x03 : PIN key;
0x10 : Fixed MAC key;
0x11 : Fixed PIN key;
KeyIndex Key index.
If the key type is Master, MAC, PIN, Fixed MAC or
Fixed PIN, it value is from 1 to 100.
If the key type is DUKPT MAC or DUKPT PIN, this
parameter is no using.
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：
5.5.17. epp_clear_appkey

Prototype int epp_clear_appkey(EPP_CFG *cfg)

：
Function： Clear all key of current application in external N20 PINPAD.
Parameter: cfg（input） EPP device handle which is opened by epp_open
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.18. epp_format_ped

Prototype int epp_format_ped(EPP_CFG *cfg)

：
Function： Format the N20 PINPAD, include clear all key and restore the default
configure.
Parameter: cfg（input） EPP device handle which is opened by epp_open
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.19. epp_set_idle_logo

Prototype： int epp_set_idle_logo(EPP_CFG *cfg, const void *pBmpIdleLogoIn)

Function： Update the IDLE LOGO in N20 PINPAD。
Parameter: cfg（input） EPP device handle which is opened by epp_open
pBmpIdleLogo Data content of monochrome BMP file.The N20
In EPP’s LCD resolving is 122*32.
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：
5.5.20. epp_resume_default_idle_logo

Prototype int epp_resume_default_idle_logo(EPP_CFG *cfg)

：
Function： Restore the default IDLE LOGO. in N20 PINPAD
Parameter: cfg（input） EPP device handle which is opened by epp_open
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.21. epp_display_logo

Prototype： int epp_display_logo(EPP_CFG *cfg, uint32_t X, uint32_t Y, const void

*pBmpLogoIn)
Function： display BMP monochrome picture in external N20 PINPAD, the MAX
resolving is 122*32.
Parameter: cfg （ inp EPP device handle which is opened by epp_open
ut）
X start row (Pixel)
Y start line (Pixel)
pBmpLo Data content of comocrome BMP file.
goIn
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.22. epp_display_string

Prototype： int epp_display_string(EPP_CFG *cfg, uint32_t X, uint32_t Y, uint32_t

iMode, const void *str, uint32_t iStrLen)
Function： Display string in N20 PINPAD.
Parameter: cfg（in EPP device handle which is opened by epp_open
put）
 X start row (Pixel)
Y start line (Pixel)
Mode the character size.
ASCII character size:
0x08 : 6*8
0x10 : 8*16
st the display ASCII character
iStrLen the character length
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.23. epp_clear_screen

Prototype： int epp_clear_screen(EPP_CFG *cfg)

Function： Clear screen of external N20 PINPAD
Parameter: cfg EPP device handle which is opened by epp_open
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.24. epp_get_system_info

Prototype： int epp_get_system_info(EPP_CFG *cfg, uint32_t Type, void

*pvInfoOut)
Function： Get N20 PINPAD info. We are normally used this API to check the N20
EPP connect status.
Parameter: cfg （ input EPP device handle which is opened by epp_open
）
Type query type.
0x00 hardware version;
0x01 hardware configure;
0x02 the EPP serial number;
0x03 CPU SN;
 0x10 boot version;
0x11 Kernel version;
0x20 query protocol version.
pvInfoOut return info, the buff no less then 17 bytes.
（output）
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.25. epp_beep

Prototype int epp_beep(EPP_CFG *cfg, uint32_t Frequency, uint32_t TimeMs)

：
Function： Beeper control function of N20 PINPAD.
Parameter: cfg（input） EPP device handle which is opened by epp_open
Frequency frequency control parameter.
(1)if the value is from 0 to 6, then the corresponding
frequency is 1680, 1834, 2020, 2127, 2380, 2700,
2900；
(2)if the value is bigger than 7, then set frequency
according to this value, for example, the value is
1500,then the frequency is 1500.
Notes:this parameter is meaningless to N20, N20 just
supports fixed 2500hz frequency.
TimeMs beep time, unit ms
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.26. epp_light

Prototype int epp_light(EPP_CFG *cfg, uint32_t TimeMs)

：
Function： N20 PINPAD’s LCD back light control.
Parameter: cfg（input） EPP device handle which is opened by epp_open
 TimeMs <0: light all the time；
=0: not light all the time；
>0: light at the specified time
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：

5.5.27. epp_kb_get_string

Prototype int epp_kb_get_string(EPP_CFG *cfg, uint32_t iMode, uint32_t iMinLen,

： uint32_t iMaxlen, uint32_t iTimeOutMs, void *strBuff)
Function： get user keystrokes on the password keyboard of N20 PINPAD
Parameter: cfg（input） EPP device handle which is opened by epp_open
iMode D31 … rev
D9
D8 1（0） yes（no）allow left input and line
display
D7 1（0） yes（no）StrBuf default content
effectively
D6 1（0） big（little）font
D5 1（0） yes（no）input digital
D4 1（0） yes（no）input character
D3 1（0） yes（no）password way
D2 1（0） left（right）aligned input
D1 1（0） yes（no）decimal point
D0 1（0） normal（reverse）display
iMinLen min length
iMaxLen max length
iTimeOutMs timeout time
strBuff（output contnet returned by password keybord, buffer is
） according to max length
Return： please refer to section 4.12.1
Be NEW7110
applicable
in：
Notes：
5.6. Printer

Printer is a character device, using general file operations(open、write、ioctl、close) can

complete operation on printer, for convenience of application developer, we package it
,let operation on printer audio-visually.

Printer module provides blocking and non-blocking operation.

In the blocking mode, when the program writing printed data into the printer, if the
printer internal print buffer is full, then the application writes data to the printer's
operation will block until the printer will have printed some data, there is room for
internal buffer blocked when the operation will be re-awakened, continue to write
data.

In the non-blocking mode, when the program will write the data to be printed in the
printer, if the printer internal print buffer is full, then the application writes data to the
printer’s operation will immediately failure and returns, and without blocking.

Print module just provide the lattice data will be printed to print, as to how to populate
the lattice data, self-completed by the developer, the printer is a shared device,
different applications can open the device and print at the same time, thus may
cause the print data confusion, so the developers should open the device to operate
only when it is need to call, when the operation is complete the device should be
closed immediately.

API functions of this module was defined in the “printer.h”, “posapi.h”; “libpos.so” must be
used when linking.

5.6.1. printer_open

Prototype int printer_open(const char *filename, int oflags)

：
Function： open printer device
Parameter: filename printer device name：“/dev/printer0”,“/dev/printer1”……
oflags Way to open the device:
blocking mode use： O_WRONLY
non-blocking mode use：O_WRONLY | O_NONBLOCK
 Return： >= 0 open device OK, return value is used to operate printer’s
file number
others other error code
Support： NEW8210
Notes： Printer device’s number is up to 16, its device name is
/dev/printer? （ ?=0,1,2,…,15 ） ， in default condition NEW8210
thermal printer device name is/dev/printer0

5.6.2. printer_close

Prototype int printer_close(int fd)

：
Function： close printer device
Parameter fd opened device file number that printer_open function
returns
Return： 0 close printer device success
others other error code
Support： NEW8210
Notes： After calling this function fd will be invalid, before opening printer
device again, can not use this invalid fd to operate printer.

5.6.3. printer_read

Prototype： int printer_read(int fd, void *buf, size_t nbytes)

Function：
Parameter: fd opened device file number that printer_open function returns
buf
nbytes
Return： >= Printer accepted bytes
0
other other error code
Support： NEW8210
Notes：

5.6.4. printer_write

Prototype int printer_write(int fd, const void *buf, size_t nbytes)

 ：
Function： put the data to be printed
Parameter: fd opened device file number that printer_open function
returns
buf point to data buffer to be printed
nbytes the number of printed data’s bytes
Return： >= 0 the direct number of printer device actually accept
others other error code
Support： NEW8210
Notes： After calling this function, the printer will automatically begin to print.
In the blocking mode, the function may block until the printer can
accept data, on no exceptional condition, printer will complete print
submitted data, if an exception occurs(such as printing out of
paper,print head temperature is too high), function will return
immediately.
In the non-blocking mode, the printer will try to accept the data to be
printed, if the printer internal print buffer is full, this function will
immediately return the number of types have been received, in the
case of internal print buffer is full, continue to call this function will
return error(not by the failure of the printer ).
Note that calling this function, the printer may not accept all of the
data one time, so application should loop call printer_write, until all
of data are printed.

5.6.5. printer_get_status

Prototype int printer_get_status(int fd, printer_status_t *status)

：
Function： To get the status of the printer
Parameter: fd opened device file number that printer_open function
returns
status status State is represented by the 32-bit:
PRINTER_STATUS_BUSY bit ： printing
device busy flag.
PRINTER_STATUS_HIGHT_TEMP bit ：
temperature is too high
PRINTER_STATUS_PAPER_LACK bit ：
out of paper
PRINTER_STATUS_FEED bit： feeding
PRINTER_STATUS_PRINT bit ： printing
flag
PRINTER_STATUS_FORCE_FEED bit ：
 force feed flag
PRINTER_STATUS_POWER_ON bit ：
print power on flag
voltage voltage of the current print
temperature temperature of current print head
Return： 0 get status successfully, the returned parameter is
available
others Other error code
Support： NEW8210
Notes： The got status of printer is defined by bit, you should test status-
>status & （ 1<<PRINTER_STATUS_BUSY ） to determine wether
the printer is ldle

5.6.6. printer_get_param

Prototype int printer_get_param(int fd, printer_param_t *param)

：
Function： get the current print parameters
Parameter: fd opened device file number
param ro_width the dot number of each line dot matrix
of printer
ro_bits_per_pixe how many bits to expressed each
l pixel
rw_gray Set print gray, scope: 50~500,
represent that print gray is normal
50%～500%
rw_hi_temp highest work temperature that print
head allowed
rw_lo_temp highest temperature that print head
allowed when printing again after
over-temperature printing
Return： 0 get status successfully, the returned parameter is
available
others Other error code
Support： NEW8210
Notes： When printing , if print head up to the value that rw_hi_temp setted
it will be status of “over-temperature”, print will stop, until
temperature reduce to under rw_lo_temp it will continue to print. If
over-temperature occurs , data that have not been printed will all be
discarded.
5.6.7. printer_set_param

Prototype int printer_set_param(int fd, const printer_param_t *param)

：
Function： set current print parameter
Parameter: fd opened device file number that printer_open function
returns
param ro_width the number of each line dot matrix of
printer
ro_bits_per_pixe how many bits to expressed each
l pixel
rw_gray Set print gray, scope: 50~500,
represent that print gray is normal
50%～500%
rw_hi_temp highest work temperature that print
head allowed
rw_lo_temp highest temperature that print head
allowed when printing again after
printing over-temperature
Return： 0 Set OK
Others Other error code
Support： NEW8210
Notes： In param, parameter begins with “ro_”means that this parameter
can not be set, it will not work after setting up. Parameter begins
with “rw_” means that this parameter can be set.

5.6.8. printer_feed_start

Prototype int printer_feed_start(int fd, uint32_t step)

：
Function： start the printer paper feed function
Parameter: fd opened device file number that printer_open function
returns
step Steps of feeding into the paper
Return： 0 Set OK
others Other error code
Support： NEW8210
Notes： After calling this function, if the printer is idle, then the printer will
begin to feed, there has a largest number of feed steps limit inside
the printer, if setted step is bigger than the step, then it will feed
 according the internal maximum steps.
When feeding ,if developer call printer_feed_stop , printer will stop
feeding.

5.6.9. printer_feed_stop

Prototype int printer_feed_stop(int fd)

：
Function： stop the printer feeding
Parameter: fd opened device file number that printer_open function
returns
Return： 0 Operate OK
others Other error code
Support： NEW8210
Notes： If application developer have called printer_feed_start, then calling
this function will stop the printer to feed; if printer have stopped
feeding, call this function will do no work on the printer.

5.6.10. printer_reset

Prototype int printer_reset(int fd)

：
Function： Reset all status of printer, clear all the printer internal data
Parameter: fd opened device file number that printer_open function
returns
Return： 0 operate success
others Other error code
Support： NEW8210
Notes：

5.6.11. print_surface

Prototype int print_surface (int print_fd, IDirectFBSurface *fb_surface, uint32_t

： print_height)
Function： output the content of fb_surface of printer
Parameter: print_fd opened device file number that printer_open function
returns
fb_surface surface which is to be printed
 print_height print height, calculated by pixel
Return： 0 Operate success
others Other error code
Support： NEW8210
Notes： This function can print content of a surface by printer, the part of
the surface width which is bigger than the printer will be
truncated. If print_height is bigger than fb_surface’s width, then
fb_surface’s height is the biggest corresponding height.
5.7. Magnetic stripe

magnetic stripe reader is a character device, use general file

operations(open、write、ioctl、close) can complete operation on magnetic stripe reader, for
convenience to develop, we package it ,let magnetic card’s operation audio-visually.

Magnetic card module provides blocking and non-blocking operation.

In the blocking mode, when the program calling to read magnetic card data , if the
magnetic stripe reader has no data, then the application will block until user swipes
card, when magnetic card module received data the blocked program will be re-
awakened, application will get data from magnetic card module.

In the non-blocking mode, when the program calling to read magnetic card data , if the
magnetic stripe reader has no data, the application will not be blocked ,calling the
magstripe_read will leads to error and returns immediately.(not the fault of magnetic card
module)

For the convenience of developer, we also provide read and write function with
timeout, if the reader can not read and write data at a set period of time, function will
exit.

API functions of this module was defined in the “magstripe.h”; “libpos.so” must be used
when linking.

5.7.1. magstripe_open

Prototype int magstripe_open(const char *filename, int oflags)

：
Function： open the magnetic stripe reader
Parameter: filename magnetic stripe reader
name：“/dev/magcard0”,“/dev/magcard1”……
oflags Way to open the device:
blocking mode use： O_RDONLY
non-blocking mode use：O_RDONLY | O_NONBLOCK
Return： >= 0 open device OK, return value is used to operate card
decoding device’s file number
others other error code
Support： NEW8210
Notes： The number of magnetic stripe reader is up to 16, its device name
 is /dev/magcard?（?=0,1,2,…,15），in default condition NEW8210
thermal printer device name is /dev/magcard0

5.7.2. magstripe_close

Prototype int magstripe_close(int fd)

：
Function： close magnetic stripe reader
Parameter: fd opened device file number that magstripe_open function
returns
Return： 0 close card decoding device success
others Other error code
Support： NEW8210
Notes： After calling this function, the fd will be invalid, before open
magnetic stripe reader again, this invalid fd can not be used to
operate magnetic stripe reader

5.7.3. magstripe_read

Prototype int magstripe_read(int fd, user_magcard_info_t *cardinfo)

：
Function： Get data of track from magnetic stripe reader
Parameter: fd opened device file number that magstripe_open function
returns
cardinf magcardtrac trackn Track number（0，1，2）
o k o
[0,1,2] status Decoding state：
MAGCARD_DECODE_OK:
success
MAGCARD_DECODE_ERR_RA
W
MAGCARD_DECODE_ERR_LR
C
MAGCARD_DECODE_ERR_OD
D
size number of data bytes of the track
data store the track data
Return： >0 number of data bytes read from magnetic stripe reader
others other error code
Support： NEW8210
 Notes： Output parameter cardinfo data struct is below:
typedef struct magcard_info {
int trackno;
Int status;
Int size;
uint8_t data[244];
} magcard_info_t;
typedef struct user_magcard_info {
magcard_info_t
magcardtrack[MAGCARD_TRACK_NUM];
} user_magcard_info_t ;

5.7.4. magstripe_read_timeout

Prototype int magstripe_read_timeout(int fd, user_magcard_info_t * cardinfo,

： unsigned long ms)
Function： The same as magstripe_read, add timeout function.no matter it is
non-blocking mode or -blocking mode, when the set timeout expires,
the function will exit.
Parameter: fd opened device file number that magstripe_open function
returns
cardinf magcardtrac trackn Track number（0，1，2）
o k o
[0,1,2] status Decoding state：
MAGCARD_DECODE_OK:
success
MAGCARD_DECODE_ERR_RA
W
MAGCARD_DECODE_ERR_LR
C
MAGCARD_DECODE_ERR_OD
D
size number of data bytes of the track
data store data of the track

ms timeout time,unit:ms
Return： >0 number of data bytes from magnetic stripe reader
-ETIME read timeout
others other error code
Support： NEW8210
Notes：
5.7.5. magstripe_write

Prototype int magstripe_write(int fd, const user_magcard_info_t *cardinfo)

：
Function： write track data into magnetic stripe by magnetic stripe reader
Parameter: fd opened device file number that magstripe_open function
returns
cardinfo magcardtrac trackno Track number（0，1，2）
k status ignore
[0,1,2] size number of data bytes of the
track
data store data of the track
Return： >0 number of data bytes of writing into magnetic stripe
reader
others other error code
Support： none
Notes： NEW8210 don’t support this function currently

5.7.6. magstripe_write_timeout

Prototype int magstripe_write_timeout(int fd, const user_magcard_info_t *

： cardinfo, unsigned long ms)
Function： write track data into magnetic card by magnetic stripe reader
Parameter: fd opened device file number that magstripe_open function
returns
cardinfo magcardtrac trackno Track number（0，1，2）
k status ignore
[0,1,2] size number of data bytes of the
track
data store data of the track
ms timeout time,unit:ms
Return： >0 number of data bytes of writing into magnetic stripe
reader
-ETIME read timeout
others other error code
Support： none
Notes： NEW8210 don’t support this function currently
5.7.7. magstripe_get_trackset

Prototype int magstripe_get_trackset(int fd, user_track_info_t *trackinfo)

：
Function： get encoding set of all tracks of current magnetic stripe reader.
Parameter: fd opened device file number that magstripe_open
function returns
tradckinfo bit_pre_code Coding bit length
start_flag Start flag
end_flag End flag
base Base value
Return： >0 success
others other error code
Support： NEW8210
Notes： This function is provided for developers who know well about
magnetic coding standards, if developer don’t know it well, it is not
necessary to call this function.

5.7.8. magstripe_set_trackset

Prototype int magstripe_set_trackset(int fd, const user_track_info_t *trackinfo)

：
Function： set encoding standards of every track of current magnetic stripe
reader
Parameter: fd opened device file number that magstripe_open
function returns
tradckinfo bit_pre_code Coding bit length
start_flag Start flag
end_flag End mark
base Base value
Return： 0 success
others other error code
Support： NEW8210
Notes： This function is provided for developers who know well about
magnetic coding standards, if developer don’t know it well, it is not
necessary to call this function.
5.8. IC card

NEW8210 support one user card slot and three PSAM card slots currently, corresponding
card slot device name are listed as follow:
“/dev/usercard” ----- user card slot
“/dev/samcard1” ------ PSAM1 card slot
“/dev/samcard2” ------ PSAM2 card slot
“/dev/samcard3” ------ PSAM3 card slot
Above them PSAM card slot just supports T=0 、 T=1 asynchronous operation of CPU
card, and user card not only supports T=0、T=1 asynchronous operation of CPU card, but
also supports various synchronization card, such as SLE4428、SLE4442 and AT24 series
memory card.
When developing application, please includes iccard.h 、 sle4442.h 、 sle4428.h and
at24xx.h。
Please link to libiccard.so lib file when compiling.

5.8.1. iccard_open_cardslot

Prototype int iccard_open_cardslot(const char *filename)

：
Function： Open contact IC card device
Parameter: filename Contact IC card device name, value below:
“/dev/usercard” ----- user card slot
“/dev/samcard1” ------ SAM1 card slot
“/dev/samcard2” ------ SAM2 card slot
“/dev/samcard3” ------ SAM3 card slot

Return： >= 0 Open device successfully, return file number of using to

operate contact IC card device
-1 Open IC card slot failure, please get actual error value by
errno
Support： NEW8210
Notes： 1、 NEW8210 supports one user card slot and three SAM card slot
2、 Please refer to iccard.h
5.8.2. iccard_close_cardslot

Prototype int iccard_close_cardslot(int fd)

：
Function： close contact IC card device
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 close contact IC device successfully
-1 Close IC card slot failure, please get actual error value by
errno
Support： NEW8210
Notes： 1、 After calling this function, fb will be invalid, before restart contact
IC card device, programmer can’t use this invalid fa to operate
contact IC card device.
2、 Please refer to iccard.h

5.8.3. iccard_check_card_in_slot

Prototype int iccard_check_card_in_slot(int fd)

：
Function： Check whether there is a IC card in designated contact IC card slot
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 Card Detected
-1 Card absent or other error, please check the mistake by
errno:
ENXIO：Card absent
Other value：other error
Support： NEW8210
Notes： 1、 Only user card supports card in place check, the other three
SAM card slot always regards as card is exist.
2、 Please refer to iccard.h。

5.8.4. iccard_power_up

Prototype int iccard_power_up(int fd, int vcc, int mode, int *len, void *atr)
：
Function： power on and reset asynchronous CPU card of IC card slot when
 contacting
Parameter: fd opened device file number that iccard_open_cardslot
function returns
vcc IC card working voltage, the value is below:
CVCC_1_8_VOLT 1.8v operation
CVCC_3_VOLT 3v operation
CVCC_5_VOLT 5v operation
mode IC card working mode, the value is below:
EMV_MODE ------ EMV working mode
ISO_MODE ----- ISO7816 ， 9600BPS working
mode（supports PPS protocol）
ISO_19200 ------ ISO7816 ， 19200BPS working
mode
ISO_38400 ------ ISO7816 ， 38400BPS working
mode
len （ outp ATR length that IC card returns
ut）
atr（outpu ATR information that IC card returns
t）
Return： 0 power on and reset IC card success
-1 Power on card failure, please get actual error value by
errno
ENXIO ： is not IC card exist in card slot
EINVAL ： input parameter error
ECOMM ： IC card return data parity error or LRC
parity error
EPROTO ： IC card return data does not meet the
EMV standard or ISO7816 standard
ETIME ： timeout and no return
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to iccard.h。

5.8.5. iccard_exchange_apdu

Prototype int iccard_exchange_apdu(int fd, uint32_t sendlen, const void

： *senddata, uint32_t *recvlen, void
*recvdata)
Function： exchange data with asynchronous card of contacting IC card slot
Parameter: fd opened device file number that iccard_open_cardslot
function returns
 sendlen the total length of data to be sent
senddata the data to be sent
recvlen（o length of data that IC card returns
utput）
recvdata the data that IC card returns
（output）
Return： 0 power on and reset IC card success
-1 Exchange data with card error, please get actual error
value by errno
ENXIO ：is not IC card exist in card slot
EINVAL ：input parameter error
ECOMM ： IC card return data parity error or LRC parity
error
EPROTO ： IC card return data does not meet the EMV
standard or ISO7816 standard
ETIME ：timeout and no return
EACCES : do not power on card
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to iccard.h。

5.8.6. iccard_power_down

Prototype int iccard_power_down(int fd)

：
Function： power off IC card of contacting IC card slot
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 power off successfully
-1 power off card failure, please get actual error value by
errno:
ENXIO ：is not IC card exist in card slot
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to iccard.h。
5.9. SLE4428 card module interface

5.9.1. sle4428_open

Prototype int sle4428_open(int fd)

：
Function： active SLE4428 card of IC card slot
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 Active operation success
-1 Active SLE4428 failure,please get actual error value by
errno:
ENXIO ： SLE4428 card is not exist in card slot
EPROTO ：It is not SLE4428 card
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4428.h。

5.9.2. sle4428_close

Prototype int sle4428_close(int fd)

：
Function： power off SLE4428 card
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 power off success
-1 Power off SLE4428 failure, please get actual error code
by errno
Support： NEW8210
Notes： 1、Please refer to sle4428.h。

5.9.3. sle4428_read

Prototype int sle4428_read(int fd,int start_addr,int len,void *data)

：
 Function： read data from SLE4428 card
Parameter: fd opened device file number that iccard_open_cardslot
function returns
start_addr start address
len length of data that will be read.
data （ out data that will be read.
put）
Return： 0 read operate success
-1 Operate failure, please get actual error code by errno:
EINVAL ： input parameter error
ENXIO ： is not exist SLE4428 card in card slot
Other value ：other error code

Support： NEW8210
Notes： 1、Please refer to sle4428.h。

5.9.4. sle4428_read_error_count

Prototype int sle4428_read_error_count (int fd,void *count)

：
Function： read count of SLE4428 consecutive password verification failures
Parameter: fd opened device file number that iccard_open_cardslot
function returns
count （ ou Count of consecutive password verification failures
tput）
Return： 0 read operate success
-1 Operate failure, please get actual error code by errno:
EINVAL ： input parameter error
ENXIO ： is not exist SLE4428 card in card slot
Other value ：other error code
Support： NEW8210
Notes： 1、 When count of consecutive password verification failures is up
to 8, SLE4428 card will be locked card, and can not do write
operation again.
2、 Please refer to sle4428.h。

5.9.5. sle4428_verify_pwd

Prototype int sle4428_verify_pwd(int fd,const void *pwd)

：
 Function： SLE4428 card password verification
Parameter: fd opened device file number that iccard_open_cardslot
function returns
pwd SLE4428 card password, 2 bytes
Return： 0 password verification success
-1 Operate failure, please get actual error code by errno:
EINVAL ： input parameter error
ENXIO ： SLE4428 card does not exist in card slot
EPROTO : password verification failure
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4428.h。

5.9.6. sle4428_change_key

Pototype int sle4428_change_key(int fd,const void *new_pwd)

：
Function： modify SLE4428 card’s password
Parameter: fd opened device file number that iccard_open_cardslot
function returns
new_pwd new SLE4428 card password , 2 bytes
Return： 0 password modify success
-1 Operate failure, please get actual error code by errno:
EINVAL ： input parameter error
ENXIO ： SLE4428 card does not exist in card slot
EPROTO : password modify failure
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4428.h。

5.9.7. sle4428_lock

Pototype int sle4428_lock(int fd)

：
Function： Lock SLE4428 card
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 locked card success
 -1 Operate failure, please get actual error code by errno:
ENXIO ： SLE4428 card does not exist in card slot
EPROTO : lock card failure
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4428.h。

5.9.8. sle4428_read_status

Prototype int sle4428_read_status (int fd,int addr,void *status)

：
Function： read data status of an address of SLE4428 card
Parameter: fd opened device file number that iccard_open_cardslot
function returns
addr data address that will be demanded
status（ou The data status, 0- can not modify 1- can modify
tput）
Return： 0 read data status success
-1 Operate failure, please get actual error code by errno:
ENXIO ：SLE4428 card does not exist in card slot
EINVAL ： input parameter error
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4428.h。

5.9.9. sle4428_write

Prototype int sle4428_write(int fd,int start_addr,int len,const void *data)

：
Function： write data into SLE4428
Parameter: fd opened device file number that iccard_open_cardslot
function returns
start_addr data start address that will be written.
len length of data to be written.
data data that will be written.
Return： 0 write operation success
 -1 Operate failure, please get actual error code by errno:
ENXIO ： SLE4428 card does not exist in card slot
EINVAL ： parameter error
EACCES: can not modify the address’s data
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4428.h。

5.9.10. sle4428_write_protect

Prototype int sle4428_write_protect(int fd,int start_addr,int len,const void

： *data)
Function： write data into SLE4428, while setting data that can not be changed
Parameter: fd opened device file number that iccard_open_cardslot
function returns
start_addr data start address that will be written
len length of data that will be written
data data that will be written
Return： 0 write operation successfully
-1 Operate failure, please get actual error code by errno:
ENXIO ： SLE4428 card does not exist in card slot
EINVAL ： parameter error
EACCES: can not modify the address’s data
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4428.h。

5.9.11. sle4428_check_data

Prototype int sle4428_check_data (int fd,int addr,uint8_t data)

：
Function： compare specified address data of SLE4428 with input data, if they
are all the same, then setting this address to can not be changed
Parameter: fd opened device file number that iccard_open_cardslot
function returns
addr data address that will be compared
data data that will be compared
Return： 0 write success
-1 Operate failure, please get actual error code by errno:
ENXIO ：SLE4428 card does not exist in card slot
EPROTO : modify failure
EACCES: can not modify the address’s data
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4428.h。
5.10. SLE4442 card module interface

5.10.1. sle4442_open

Prototype int sle4442_open(int fd)

：
Function： active SLE4442card of IC card slot
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 Active operation success
-1 Operate failure,please get actual error value by errno:
ENXIO ： SLE4442 card does not exist in card slot
EPROTO ： is not a SLE4442card
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4442.h。

5.10.2. sle4442_close

Prototype int sle4442_close(int fd)

：
Function： power off SLE4442card
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 power off success
-1 Power off failure, please get actual error code by errno
Support： NEW8210
Notes： 1、Please refer to sle4442.h。

5.10.3. sle4442_verify

Prototype int sle4442_verify(int fd,const void* pwd)

：
Function： SLE4442 card password verification
Parameter: fd opened device file number that iccard_open_cardslot
function returns
 pwd SLE4442 card user password, 3 bytes
Return： 0 password verification success
-1 Operate failure, please get actual error code by errno:
EINVAL ： parameter error
EPROTO : password verification failure
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4442.h。

5.10.4. sle4442_read_error_count

Prototype int sle4442_read_error_count(int fd,void *count)

：
Function： read count of SLE4442 consecutive password verification failures
Parameter: fd opened device file number that iccard_open_cardslot
function returns
count （ ou Count of consecutive password verification failures
tput）
Return： 0 read operate success
-1 Operate failure, please get actual error code by errno:
EINVAL ：parameter error
Other value ：other error code
Support： NEW8210
Notes： 1、 。When count of consecutive password verification failures is up
to 3, SLE4442 card will be locked card, and can not do write
operation again.
2、 Please refer to sle4442.h。

5.10.5. sle4442_change_key

Prototype int sle4442_change_key(int fd,const void *new_pwd)

：
Function： modify SLE4442 card’s password
Parameter: fd opened device file number that iccard_open_cardslot
function returns
new_pwd new SLE4442 card password , 3 bytes
Return： 0 password modify success
 -1 Operate failure, please get actual error code by errno:
EINVAL ： parameter error
EPROTO : password modify failure
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4442.h。

5.10.6. sle4442_lock

Prototype int sle4442_lock(int fd)

：
Function： SLE4442 card locked
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 locked card success
-1 Operate failure, please get actual error code by errno:
ENXIO ：SLE4442 card does not exist in card slot
EPROTO : lock card failure
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4442.h。

5.10.7. sle4442_read

Prototype int sle4442_read(int fd,int start_addr,int len,void *data)

：
Function： read data from SLE4442 card
Parameter: fd opened device file number that iccard_open_cardslot
function returns
start_addr start address
len length of data that will be read.
data （ out data that will be read.
put）
Return： 0 read operate success
-1 Operate failure, please get actual error code by errno:
EINVAL ： input parameter error
ENXIO ： SLE4442 card does not exist in card slot
Other value ：other error code
 Support： NEW8210
Notes： 1、Please refer to sle4442.h。

5.10.8. sle4442_write

Prototype int sle4442_write(int fd,int start_addr,int len,const void *data)

：
Function： write data into SLE4442
Parameter: fd opened device file number that iccard_open_cardslot
function returns
start_addr data start address that will be written.
len length of data that will be written.
data data that will be written.
Return： 0 write operation success
-1 Operate failure, please get actual error code by errno:
ENXIO ： SLE4442 card does not exist in card slot
EINVAL ： parameter error
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4442.h。

5.10.9. sle4442_read_status

Prototype int sle4442_read_status(int fd,int addr,void *status)

：
Function： read protect bit information of the designated address of SLE4442
card
Parameter: fd opened device file number that iccard_open_cardslot
function returns
addr data address that will be demanded
status（ou Protect bit information of the address:
tput） 0— be protected ,can not be modified
1— not be protected, can be modified
Return： 0 read operation success
-1 Operate failure, please get actual error code by errno:
ENXIO ： SLE4442 card does not exist in card slot
EINVAL ： parameter error
Other value ：other error code
 Support： NEW8210
Notes： 1、Please refer to sle4442.h。

5.10.10. sle4442_check_data

Prototype int sle4442_check_data (int fd,int addr,uint8_t data)

：
Function： Write data into the designated address of SLE44442’s protect zone,
and set its property to can not be changed
Parameter: fd opened device file number that iccard_open_cardslot
function returns
addr data address that will be written.
data data that will be written.
Return： 0 write operation success
-1 Operate failure, please get actual error code by errno:
ENXIO ：SLE4442 card does not exist in card slot
EPROTO : modify failure
EACCES: can not modify the address’s data
ETIME ： timeout
Other value ：other error code
Support： NEW8210
Notes： 1、Please refer to sle4442.h。
5.11. Contact-less IC card reader module

NEW8210’s contact-less reader module device name is ”/dev/nfc”。

NEW8210 supports TypeA（ISO14443-1、-2、-3、-4）、TypeB（ISO14443-1、-2、-3、-
4）and SonyFeliCa protocol card currently.
Specifically supports mifare Classic(S50/S70) 、 mifare Ultralight 、 mifare DESFire
D40 、mifare DESFire EV1、mifare ProX and etc。
When developing application, please contains iso14443.h、mifone.h、miful.hand desfire.h。
When compiling application, please links to libnfc.so lib file.

5.11.1. ISO14443 protocol command interface

5.11.1.1. mif_open

Prototype int mif_open(const char *filename)

：
Function： open the contact-less reader module
Parameter: filename Contact-less reader name：currently fixed at ”/dev/nfc”
Return： >= 0 open device OK, returned value is used to operate
contact-less reader function’s file number
-1 open failure, please get the actual error code by errno
Support： NEW8210
Notes： 1、Please refer to iso14443.h。

5.11.1.2. mif_close

Prototype int mif_close(int fd)

：
Function： close contact-less reader module
Parameter: fd opened device file number that mif_open function returns
Return： 0 operate success
-1 Close failure, please get the actual error code by errno
Support： NEW8210
Notes： 1、Please refer to iso14443.h。
5.11.1.3. mif_set_timeout

Prototype int mif_set_timeout(const struct mif_timeout *ptime)

：
Function： set corresponding timeout parameter of contact-less reader module
Parameter: ptime structure pointer to timeout parameter
Return： 0 operate OK
-1 Operate failure, please get the actual error code by errno:
EINVAL ： input parameter error
Other value ： other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.4. mif_get_timeout

Prototype int mif_get_timeout(struct mif_timeout *ptime)

：
Function： get corresponding timeout parameter of contact-less reader module
Parameter: ptime structure pointer of current timeout parameter
（output）
Return： 0 operate OK
-1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
Other value ： other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.5. iso14443_delay_etu

Prototype： int iso14443_delay_etu(int fd,uint32_t numofetu);

Function：
Parameter: fd[i] opened device file number that mif_open function returns
numofet
u
Return： 0 Success
 -1 Operate failure, please get the actual error code by errno:
EINVAL ： input parameter error
Other value ： other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.6. iso14443_reset_picc

Prototype： int iso14443_reset_picc(int fd)

Function：
Parameter: fd[i] opened device file number that mif_open function returns

Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
EINVAL ： input parameter error
Other value ： other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.7. mif_select_carrier_type

Prototype int mif_select_carrier_type(int fd, int32_t type)

：
Function： set contact-less reader module carrier modulation type
Parameter: fd opened device file number that mif_open function returns
type Modulation type, exact value is below:
MIF_TYPE_A ------ ISO14443 TypeA modulation
MIF_TYPE_B ------- ISO14443 TypeB modulation
MIF_TYPE_C1 ------ Sony FeliCa slow modulation
(212kbps)
MIF_TYPE_C2 ------ Sony FeliCa high
modulation(424kbps)
Return： 0 Operate OK
-1 Operate failure, please get the actual error code by errno:
EINVAL ： input parameter error
Other value ： other error code
Support： NEW8210
 Notes： Please refer to iso14443.h。

5.11.1.8. iso14443_ReqA

Prototype int iso14443_ReqA(int fd, void *atqa)

：
Function： request idle Type A card in the inductive zone
Parameter: fd opened device file number that mif_open function
returns
atqa（outpu card returned ATQA information,2 bytes
t）
Return： 0 operate OK
-1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card returned data doesn’t comply with
ISO14443 standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
EMULTIHOP ： more than one card exists in
induction zone
other value : other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.9. iso14443_WupA

Prototype int iso14443_ReqA(int fd, void *atqa)

：
Function： wake up TypeA card in IDLE state or HALT state in inductive zone
Parameter fd opened device file number that mif_open function
returns
atqa（outpu ATQA information that card returned, 2 bytes
t）
Return： 0 operate OK
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
EMULTIHOP ： more than one cards exist in
induction zone
other value : other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.10. iso14443_Anticollision

Prototype int iso14443_Anticollision(int fd,uint8_t sel,void *uid)

：
Function： TypeA card anti-conflict management, get UID information of TypeA
card
Parameter: fd opened device file number that mif_open function
returns
sel anti-conflict layer：
0x93 ------ first level
0x95 ------ second level
0x97 ------ third level
uid （ output This level UID information that card returned, 5 types
） ,4 types UID+BCC
Return： 0 operate OK
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card doesn’t fix ISO14443 standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
EMULTIHOP ： more than one card exists in
induction zone
other value : other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.11. iso14443_Select

Prototype int iso14443_Select(int fd,uint8_t sel, const void *uid, uint8_t *sak)
：
Function： Select the TypeA card
Parameter: fd opened device file number that mif_open function
returns
sel Choose layer：
0x93 ------ first level
0x95 ------ second level
0x97 ------ third level
uid this level UID information of card, 4 bytes
sak （ output card returned confirmation, 1 byte
）
Return： 0 operate OK
-1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card doesn’t fix ISO14443 standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
EMULTIHOP ： more than one card exists in
induction zone
other value : other error code
 Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.12. Iso1443_get_typeA_uid

Prototype： int iso14443_get_typeA_uid(int fd, uint8_t *uidlen, void *uid);

Function：
Parameter: fd[i] opened device file number that mif_open function returns

Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
EINVAL ： input parameter error
other value : other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.13. Iso1443_get_cardtype

Prototype： uint8_t iso14443_get_cardtype(void);

Function：
Parameter: 无

Return： 0 Success
- Operate failure, please get the actual error code by errno:
1 EINVAL ： input parameter error
other value : other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.14. iso14443_HaltA

Prototype int iso14443_HaltA(int fd)

：
Function： Make TypeA card dormant, enter HALT state.
Parameter: fd opened device file number that mif_open function
returns
 Return： 0 operate OK
-1 Operate failure, please get the actual error code by
errno:
EIO ： read card chip error
other value : other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.15. iso14443_RATS

Prototype int iso14443_RATS(int fd,uint8_t cid,uint8_t fsdi,uint8_t *atslen,void

： *ats)
Function： execute the command of Request Answer To Select, for TypeA card
Parameter: fd opened device file number that mif_open function
returns
cid logic card number of card
fsdi The maximum frame length coefficient that terminal
can receige, values are as follows:
0 ---- 16bytes
1 ---- 24bytes
2 ---- 32bytes
3 ---- 40bytes
4 ---- 48bytes
5 ---- 64bytes
6 ---- 96bytes
7 ---- 128bytes
8 ---- 256bytes
Other values ---- 256bytes
atslen （ o length of ATS information that info_len returned
utput）
ats （ outp ATS information that info_len returned
ut）
Return： 0 operate OK
 -1 Operate failure, please get the actual error code via
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
EMULTIHOP ： card in induction zone is not a T=CL
card
other value : other error code
Support： NEW8210
Notes： 1、Please refer to iso14443.h。

5.11.1.16. iso14443_PPS

Prototype int iso14443_PPS(int fd,uint8_t cid,uint8_t br)

：
Function： protocol and parameter select command, TypeA
Parameter: fd opened device file number that mif_open function
returns
cid logic card number of card
br Bound rate parameter of terminal and card, values are
as follows:
the high 4 bits is bound rate of terminal to card
the low 4 bits is bound rate of card to terminal
0 ---- 106kbps
1 ---- 212kbps
2 ---- 424kbps
3 ---- 848kbps
Return： 0 operate OK
 -1 Operate error, please get the actual error code by errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card doesn’t fix ISO14443 standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
EMULTIHOP ： card in induction zone is not a T=CL
card
other value : other error code
Support： NEW8210
Notes： 1、Please refer to iso14443.h。

5.11.1.17. iso14443_ReqB

Prototype int iso14443_ReqB(int fd,uint8_t afi,uint8_t slotnum,uint8_t

： *lenofatqb, void *atqb)
Function： requese IDLE TypeB card in inductive zone
Parameter: fd opened device file number that mif_open function
returns
afi application identifier,0x00 means all applications
slotnum number of slots that card supports:
1 ---- 1 slot
1 ---- 2 slots
2 ---- 4 slots
3 ---- 8 slots
4 ---- 16 slots
lenofatqb information length of ATQB
（output）
atqb （ out atqb information
put）
Return： 0 operate OK
 -1
Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
other value : other error code
Support： NEW8210
Notes： 1、Please refer to iso14443.h。

5.11.1.18. iso14443_WupB

Prototype int iso14443_WupB(int fd,uint8_t afi,uint8_t slotnum,uint8_t

： *lenofatqb, void *atqb)
Function： wake up IDLE state of HALT state Type B card in inductive zone
Parameter: fd opened device file number that mif_open function
returns
afi application identifier,0x00 means all applications
slotnum number of slots that card supports:
0---- 1 slot
1 ---- 2 slots
2 ---- 4 slots
3 ---- 8 slots
4 ---- 16 slots
lenofatqb information length of ATQB
（output）
atqb （ out atqb information
put）
Return： 0 operate OK
 -1 Operate error, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
other value : other error code
Support： NEW8210
Notes： 1、Please refer to iso14443.h。

5.11.1.19. iso14443_SlotMarker

Prototype int iso14443_SlotMarker(int fd,uint8_t slot,uint8_t *lenofatqb,void

： *atqb)
Function： request card information of specified time slot
Parameter: fd opened device file number that mif_open function
returns
slot time slot parameter，0~15
lenofatqb information length of ATQB
（output）
atqb （ out atqb information
put）
Return： 0 operate OK
-1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
other value : other error code
Support： NEW8210
Notes： 1、Please refer to iso14443.h。
5.11.1.20. iso14443_AttriB

Prototype int iso14443_AttriB(int fd,uint8_t cid,uint8_t fsdi,const void

： *uid,uint8_t br,uint8_t *len,void *info)
Function： choose TypeB card
Parameter: fd opened device file number that mif_open function
returns
cid logic card number of card
fsdi The maximum frame length coefficient that terminal can
receive, values are as follows:
0 ---- 16bytes
1 ---- 24bytes
2 ---- 32bytes
3 ---- 40bytes
4 ---- 48bytes
5 ---- 64bytes
6 ---- 96bytes
7 ---- 128bytes
8 ---- 256bytes
Other value ---- 256bytes
uid UID information of TypeB card, 4 bytes
br Bound rate parameter of terminal and card, values are
as follows:
the high 4 bits is bound rate of terminal to card
the low 4 bits is bound rate of card to terminal
0 ---- 106kbps
1 ---- 212kbps
2 ---- 424kbps
3 ---- 848kbps
info_len When it is used as input parameter, info_len means
（input/ length of Higher-layer INF information of ArttriB
output） command
When is used to output, info_lens returns card’s
response data length
info （ inp When is used to input, info means Higher-layer INF
ut/ information of ArttriB command
output） When is used to output, info returns card’s response
data
Return： 0 operate OK
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
other value : other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.21. iso14443_HaltB

Prototype int iso14443_HaltB(int fd,const void *uid)

：
Function： Make TypeB card dormant, enter HALT state.
Parameter: fd opened device file number that mif_open function
returns
uid UID information of TypeB card, 4 bytes
Return： 0 operate OK
-1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
other value : other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.22. iso14443_tcl_poll

Prototype int iso14443_tcl_poll(int fd,int mode,uint8_t *cardinfo_len,void

 ： *cardinfo)
Function： polling inductive area if there exists T=CL protocol card, is there
have , choose it
Parameter: fd opened device file number that mif_open function
returns
mode Polling mode , values are as follow:
0 ------ just polling card of IDLE state
1 ------ polling card of IDLE state and HALT state
cardinfo_len length of information that card returns
（output）
cardinfo（ou card returned data
tput）
Return： 0 operate OK
-1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
ENODATA ： card in induction zone is not a T=CL
card
EMULTIHOP ： multiple cards in inductive zone
other value : other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.23. iso14443_tcl_active

Prototype int iso14443_tcl_active(int fd, uint8_t cid, uint8_t br,uint8_t

： fsdi,uint8_t *info_len, void *info)
Function： active T=CL card in inductive zone
Parameter: fd opened device file number that mif_open function
returns
cid logic card number of card
br Bound rate parameter of terminal and card, values are
as follows:
the high 4 bits is bound rate of terminal to card
 the low 4 bits is bound rate of card to terminal
0 ---- 106kbps
1 ---- 212kbps
2 ---- 424kbps
3 ---- 848kbps
fsdi The maximum frame length coefficient that terminal can
receige, values are as follows:
0 ---- 16bytes
1 ---- 24bytes
2 ---- 32bytes
3 ---- 40bytes
4 ---- 48bytes
5 ---- 64bytes
6 ---- 96bytes
7 ---- 128bytes
8 ---- 256bytes
Other value ---- 256bytes
info_len TypeA card:
（input/ Length of ATS information that info_len returns
output） TypeB card:
When is used to input, info_len means length of Higher-
layer INF information of ArttriB command
When is used to output, info_lens returns card’s
response data length
info （ inp TypeA card:
ut/ ATS information that info_len returns
output） TypeB card:
When is used to input, info means Higher-layer INF
information of ArttriB command
When is used to output, info returns card’s response
data
Return： 0 operate OK
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
EACCES ： card in induction zone is not a T=CL card
other value : other error code
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.24. iso14443_tcl_exchange

Prototype int iso14443_tcl_exchange(int fd,uint32_t sendlen, const void*

： senddata,uint32_t *recvlen,void *recvdata)
Function： exchange data with card by T=CL protocol
Parameter: fd opened device file number that mif_open function
returns
sendlen length of data that terminal sends
senddata data that terminal sends
recvlen（o length of data that terminal received
utput）
recvdata data that terminal received
（output）
Return： 0 operate OK
-1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
EACCES ： card in induction zone is not a T=CL card
other value : other error code
Support： NEW8210
 Notes： Please refer to iso14443.h。

5.11.1.25. iso14443_tcl_deactive

Prototype int iso14443_tcl_deactive(int fd)

：
Function： close T=CL protocol channel, reset T=CL card
Parameter: fd opened device file number that mif_open function returns
Return： 0 operate OK
-1 Operate failure, please get the actual error code by errno
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.26. iso14443_no_tcl_exchange

Prototyep int iso14443_no_tcl_exchange(int fd,uint32_t sendlen, const void*

： senddata, uint32_t *recvlen,void *recvdata
,uint32_t timeout)
Function： Data exchange between terminal and card, not T=CL protocol
Parameter: fd opened device file number that mif_open function
returns
sendlen length of data that terminal sends
senddata data that terminal sends
recvlen（o length of data that terminal received
utput）
recvdata data that terminal received
（output）
timeout timeout parameter, unit(ETU)
Return： 0 operate OK
-1 Operate failure, please get the actual error code by
errno:
EINVAL ： input parameter error
EIO ： read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
ETIME ： timeout and no return
other value : other error code
 Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.27. mif_check_multi_card

Prototype int mif_check_multi_card(int fd)

：
Function： check whether there are multiple cards in inductive zone
Parameter: fd opened device file number that mif_open function
returns
Return： 0 operate OK
-1 Operate failure, please get the actual error code by
errno.
ENODATA ：no card inductive zone
EMULTIHOP ：multi cards inductive zone
EPROTO ： data from card not match protocol
ISO14443
EBADE ：data length from card error
Other value ：other case
Support： NEW8210
Notes： Please refer to iso14443.h。

5.11.1.28. felica_exchange

Prototype： int felica_exchange(int fd,uint32_t sendlen,const void *senddata,uint32_t

*recvlen,void *recvdata,uint32_t timeout);
Function： Detect whether there is multi-card conflict.
Parameter Fd[i] opened device file number that mif_open function returns
Sendlen
[i]
Senddat
a[i]
Receive
len[o]
Receive
data[o]
Timeout
[i]
Return 0 Success
 ： -1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ：Card doesn’t comply with ISO14443 standard
EBADE ： error of length of card returned data
other value : other error code
Support NEW8210
Notes： Please Refer iso14443.h

5.11.1.29. emv_contactless_active

Prototype： int emv_contactless_active_picc(int fd);

Function： Open the electromagnetic filed and check card.
Parameter: fd opened device file number that mif_open function returns
Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
other value : other error code
Support： NEW8210
Notes： Please Refer iso14443.h

5.11.1.30. emv_contactless_deactive_picc

Prototype： int emv_contactless_deactive_picc(int fd);

Function：
Close the electromagnetic field
Parameter: fd opened device file number that mif_open function returns
Return： 0 Success
 -1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
other value : other error code
Support: NEW8210
Notes： Please Refer iso14443.h

5.11.1.31. emv_contactless_obtain_status

Prototype： int emv_contactless_obtain_status(int fd, int * status);

Function： Get status
Parameter: fd opened device file number that mif_open function returns
status status
Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ：Card doesn’t comply with ISO14443 standard
EBADE ： error of length of card returned data
other value : other error code
Support： NEW8210
Notes： Please Refer iso14443.h

5.11.1.32. emv_contactless_get_lasterror

Prototype： int emv_contactless_get_lasterror(int fd, int * error);

Function： Get error number
Parameter: fd opened device file number that mif_open function returns
error Error number
Return： 0 Success
 -1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
other value : other error code
Support： NEW8210
Notes： Please Refer iso14443.h

5.11.1.33. emv_contactless_exchange_apdu

Prototype： int emv_contactless_exchange_apdu(int fd, uint32_t sendlen, const

void *senddata,
uint32_t *recvlen, void
*recvdata);
Function： Execute Apdu command
Parameter: fd opened device file number that mif_open function returns
sendlen Apdu Command Length
senddata Apdu Command
recvlen Apdu Response length
recvdata Apdu Response
Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
other value : other error code
Support： NEW8210
Notes： Please Refer iso14443.h

5.11.1.34. compat_InATR

Prototype： int compat_InATR(int fd, uint32_t *RespLen, void *ATRInfo);

Function：
Parameter: fd opened device file number that mif_open function returns
RespLen
ATRInfo
Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
other value : other error code
Support： NEW8210
Notes： Please Refer iso14443.h

5.11.1.35. compat_InPSL

Prototype： int compat_InPSL(int fd, uint8_t BRit, uint8_t BRti);

Function：
Parameter: fd opened device file number that mif_open function returns
Brit
BRti
Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
other value : other error code
Support： NEW8210
Notes： Please Refer iso14443.h

5.11.1.36. Compat_InListPassiveTarget

Prototype： int compat_InListPassiveTarget(int fd, uint8_t Mode, int InitLen, const

void *InitInfo, int *CardInfoLen, void *pCardInfo);
Function：
Parameter: fd opened device file number that mif_open function returns
Mode
InitLen
InitInfo
CardInfoLen
pCardInfo
Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
other value : other error code
Support： NEW8210
Notes： Please Refer iso14443.h

5.11.1.37. compat_InDataExchange

Prototype： int compat_InPSL(int fd, uint8_t BRit, uint8_t BRti);

Function：
Parameter: fd opened device file number that mif_open function returns
Brit
BRti
Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
other value : other error code
Support： NEW8210
Notes： Please Refer iso14443.h
5.11.1.38. Compat_InRelease

Prototype： void compat_InRelease(int fd);

Function：
Parameter: fd opened device file number that mif_open function returns

Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
other value : other error code
Support： NEW8210
Notes： Please Refer iso14443.h

5.11.1.39. compat_mifCheckOnlyOneCard

Prototype： int compat_mifCheckOnlyOneCard(int fd, uint8_t Mode);

Function：
Parameter: fd opened device file number that mif_open function returns
Mode
Return： 0 Success
-1 Operate failure, please get the actual error code by errno:
ENODATA ： no card exists in inductive zone
EMULTIHOP ： exists multiple cards in inductive card
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ： error of length of card returned data
other value : other error code
Support： NEW8210
Notes： Please Refer iso14443.h
5.11.2. mifare Classic S50/S70 module interface

5.11.2.1. mifare_one_poll

Prototype int mifare_one_poll(int fd, uint8_t mode, void *uid , uint8_t

： *cardtype)
Function： poll if there is mifare one card in inductive zone, if yes, active it.
Parameter: fd opened device file number that mif_open function
returns
mode Polling mode , values are as follow:
0 ------ just polling card of IDLE state
1 ------ polling card of IDLE state and HALT state
uid （ output 5 bytes UID information that card returns, 4 bytes
） UID+BCC
cardtype （ o Returned mifare one card type, may have the value
utput） below:
MIF_M1_S50 ----- mifare one S50 card
MIF_M1_S70 ----- mifare one S70 card
MIF_PRO_S50 ---- TypeA card that compatible with
T=CL protocol and S50 protocol
MIF_PRO_S70 ---- TypeA card that compatible with
T=CL protocol and S70 protocol
Return： 0 find card success
-1 Operate failure, please get the actual error code by
errno:
ENODATA ： no card in inductive card
EMULTIHOP ： exist multiple cards in inductive
zone
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
EINVAL ：parameter error
ECOMM ：Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。
5.11.2.2. mifare_one_halt

Prototype int mifare_one_halt(int fd)

：
Function： Reset mifare one card in inductive zone
Parameter: fd opened device file number that mif_open function
returns
Return： 0 reset OK
-1 Operate failure, please get the actual error code by
errno:
EIO ：read card chip error
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。

5.11.2.3. mifare_one_authenticate

Prototype int mifare_one_authenticate(int fd, uint8_t blockno, uint8_t keytype,

： const void *key, const void *uid)
Function： password authentication about mifare one card’s a data block
Parameter: fd opened device file number that mif_open function
returns
blockno Number of data block that will be authenticated, for
S50 card ,value scope is 0~63, for S70 card ,value
scope is 0~255.
keytype certificated key type, values are as follow:
‘A’ ---- certificate A key
‘B’ ---- certificate B key
key 6 bytes key information
uid 4 bytes UID information
Return： 0 password authentication success
 -1 Operate failure, please get the actual error code by
errno:
EACCES ： is not a mifare one card in inductive
zone
EPERM ： authentication failure
EPROTO ： Card doesn’t comply with mifare one
protocol
EINVAL ：parameter error
ECOMM ： Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。

5.11.2.4. mifare_one_read_block

Prototype int mifare_one_read_block(int fd, uint8_t blockno, void *blockdata)

：
Function： read a data block content of mifare one card
Parameter: fd opened device file number that mif_open function
returns
blockno Number of data block that will be read, for S50
card ,value scope is 0~63, for S70 card ,value
scope is 0~255.
blockdata（o read content of data block,16 bytes
utput）
Return： 0 read data block success
 -1 Operate failure, please get the actual error code by
errno:
EACCES ： is not a mifare one card in inductive
zone
EPERM ： authentication failure
EPROTO ： Card doesn’t comply with mifare one
protocol
EINVAL ：parameter error
ECOMM ：Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ： length of data that card return ed is error
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。

5.11.2.5. mifare_one_write_block

Prototype int mifare_one_write_block(int fd, uint8_t blockno, const void

： *blockdata)
Function： modify content of a data block of mifare one card
Parameter: fd opened device file number that mif_open function
returns
blockno Number of data block that will be read, for S50
card ,value scope is 0~63, for S70 card ,value scope
is 0~255.
blockdata content of data block that will be written,16 bytes
Return： 0 write data block success
 -1 Operate failure, please get the actual error code by
errno:
EACCES ： is not a mifare one card in inductive
zone
EPERM ： authentication failure
EPROTO ： Card doesn’t comply with mifare one
protocol
EINVAL ：parameter error
ECOMM ：Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ： length of data that card return ed is error
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。

5.11.2.6. mifare_one_set_value

Prototype int mifare_one_set_value(int fd, uint8_t blockno, uint32_t value)

：
Function： set a data block of mifare one card to value block,and fu initial
Parameter: fd opened device file number that mif_open function
returns
blockno Number of data block that will be read, for S50
card ,value scope is 0~63, for S70 card ,value scope
is 0~255.
value initial value that will be filled in
Return： 0 initialize value block success
 -1 Operate failure, please get the actual error code by
errno:
EACCES ： is not a mifare one card in inductive
zone
EPERM ： authentication failure
EPROTO ： Card doesn’t comply with mifare one
protocol
EINVAL ：parameter error
ECOMM ： Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ： length of data that card return ed is error
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。

5.11.2.7. mifare_one_increment

Prototype int mifare_one_increment(int fd, uint8_t blockno, uint32_t value)

：
Function： value block value-added operation
Parameter: fd opened device file number that mif_open function
returns
blockno Number of data block that will be read, for S50
card ,value scope is 0~63, for S70 card ,value scope
is 0~255.
value value that will be added
Return： 0 value increment operation success
 -1 Operate failure, please get the actual error code by
errno:
EACCES ： is not a mifare one card in inductive
zone
EPERM ： authentication failure
EPROTO ： Card doesn’t comply with mifare one
protocol
EINVAL ：parameter error
ECOMM ： Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ： length of data that card return ed is error
ENOSYS ：the block is not a value block
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。

5.11.2.8. mifare_one_decrement

Prototype int mifare_one_decrement(int fd, uint8_t blockno, uint32_t value)

：
Function： value block decrement operation
Parameter: fd opened device file number that mif_open function
returns
blockno Number of data block that will be read, for S50
card ,value scope is 0~63, for S70 card ,value scope
is 0~255.
value value that will be impaired
Return： 0 decrement operation success
 -1 Operate failure, please get the actual error code by
errno:
EACCES ： is not a mifare one card in inductive
zone
EPERM ： authentication failure
EPROTO ： Card doesn’t comply with mifare one
protocol
EINVAL ：parameter error
ECOMM ： Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ： length of data that card return ed is error
ENOSYS ：the block is not a value block
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。

5.11.2.9. mifare_one_restore

Prototype int mifare_one_restore(int fd, uint8_t blockno)

：
Function： Restore value in the designated block
Parameter: fd opened device file number that mif_open function
returns
blockno Number of data block that will be read, for S50
card ,value scope is 0~63, for S70 card ,value scope
is 0~255.
Return： 0 Restore operation success
 -1 Operate failure, please get the actual error code by
errno:
EACCES ： is not a mifare one card in inductive
zone
EPERM ： authentication failure
EPROTO ： Card doesn’t comply with mifare one
protocol
EINVAL ：parameter error
ECOMM ： Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ： length of data that card return ed is error
ENOSYS ：the block is not a value block
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。

5.11.2.10. mifare_one_transfer

Prototype int mifare_one_transfer(int fd, uint8_t blockno)

：
Function： save the result of value block operation
Parameter: fd opened device file number that mif_open function
returns
blockno Number of data block that will be read, for S50
card ,value scope is 0~63, for S70 card ,value scope
is 0~255.
Return： 0 Save the result of value block operation success
 -1 Operate failure, please get the actual error code by
errno:
EACCES ： is not a mifare one card in inductive
zone
EPERM ： authentication failure
EPROTO ： Card doesn’t comply with mifare one
protocol
EINVAL ：parameter error
ECOMM ： Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ： length of data that card return ed is error
ENOSYS ：the block is not a value block
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。

5.11.2.11. mifare_one_get_value

Prototype int mifare_one_get_value(int fd, uint8_t blockno, uint32_t *value)

：
Function： get the value of the designated block
Parameter: fd opened device file number that mif_open function
returns
blockno Number of data block that will be read, for S50
card ,value scope is 0~63, for S70 card ,value
scope is 0~255.
value（outpu value content that card returns
t）
Return： 0 get the value of value block operation success
 -1 Operate failure, please get the actual error code by
errno:
EACCES ： is not a mifare one card in inductive
zone
EPERM ： authentication failure
EPROTO ： Card doesn’t comply with mifare one
protocol
EINVAL ：parameter error
ECOMM ：Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ： length of data that card return ed is error
ENOSYS ：the block is not a value block
other value : other error code
Support： NEW8210
Notes： 1、Please refer to mifone.h。

5.11.3. mifare ultralight card module interface

5.11.3.1. mifare_ultralight_poll

Prototype int mifare_ultralight_poll(int fd, uint8_t mode, void *uid)

：
Function： Poll if there is mifare ultralight card in inductive zone, if there is,
active it.
Parameter: fd opened device file number that mif_open function
returns
mode Polling mode , values are as follow:
0 ------ just polling card of IDLE state
1 ------ polling card of IDLE state and HALT state
uid （ output 7 bytes UID information that card returns
）
Return： 0 find card successfully
 -1 Operate failure, please get the actual error code by
errno:
ENODATA ： is not a mifare ultralight card in
inductive zone
EMULTIHOP ： exist multiple cards in inductive
zone
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
EINVAL ：parameter error
ECOMM ：Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
other value : other error code
Support： NEW8210
Notes： 1、Please refer to miful.h。

5.11.3.2. mifare_ultralight_halt

Prototype int mifare_ultralight_halt(int fd)

：
Function： halt mifare ultralight card in inductive zone
Parameter: fd opened device file number that mif_open function
returns
Return： 0 reset OK
-1 Operate failure, please get the actual error code by
errno:
EIO ：read card chip error
other value : other error code
Support： NEW8210
Notes： 1、Please refer to miful.h。

5.11.3.3. mifare_ultralight_read_page

Prototype int mifare_ultralight_read_page(int fd,uint8_t page,void *data)

：
Function： read content of a page of mifare ultralight card, 4 pages at one time
Parameter: fd opened device file number that mif_open function
returns
 page start page number that will be read, 0~15
data（output page content that be read, 16 bytes
）
Return： 0 read data block successfully
-1 Operate failure, please get the actual error code by
errno:
ENODATA ： is not a mifare ultralight card in
inductive zone
EINVAL ：parameter error
ECOMM ：Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ：error of length of card returned data
other value : other error code
Support： NEW8210
Notes： 1、Please refer to miful.h。

5.11.3.4. mifare_ultralight_write_page

Prototype int mifare_ultralight_write_page(int fd,uint8_t page,const void *data)

：
Function： write content of a page of mifare ultralight card
Parameter: fd opened device file number that mif_open function
returns
page page number that will be written, 0~15
data page data that will be written, 4 bytes
Return： 0 write data block operation successfully
-1 Operate failure, please get the actual error code by
errno:
ENODATA ： is not a mifare ultralight card in
inductive zone
EPROTO ： Card doesn’t comply with mifare
protocol
EINVAL ：parameter error
ECOMM ： Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ：error of length of card returned data
other value : other error code
Support： NEW8210
 Notes： 1、Please refer to miful.h。

5.11.3.5. mifare_ultralight_write_page16

Prototype： int mifare_ultralight_write_page16(int fd,uint8_t page,const void *data);

Function：
Parameter: fd opened device file number that mif_open function returns
page Page number，0~15
data Data to write
Return： 0 Success
-1 Failed，Operate failure, please get the actual error code
by errno：
ENODATA ： is not a mifare ultralight card in inductive
zone
EPROTO ：Card doesn’t comply with mifare protocol
EINVAL ：parameter error
ECOMM ： Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
EBADE ：error of length of card returned data
other value : other error code
Support： NEW8210
Notes：

5.11.4. Mifare DESFire module interface

5.11.4.1. desfire_poll

Prototype int desfire_poll(int fd,uint8_t mode,void *uid, uint8_t *atslen, void

： *ats)
Function： Poll if there is mifare DESFire card in inductive zone, if there
is,active it.
Parameter: fd opened device file number that mif_open function
returns
mode Polling mode , values are as follow:
0 ------ just polling card of IDLE state
 1 ------ polling card of IDLE state and HALT state
uid （ output 7 bytes UID information that card returns
）
atslen （ outp length of ATS information that card returns
ut）
ats （ output ATS information that card returns
）
Return： 0 find card success
-1 Operate failure, please get the actual error code by
errno:
ENODATA ： is not a mifare mifare DESFire in
inductive zone
EMULTIHOP : there is multiple cards in inductive
zone
EPROTO ： Card doesn’t comply with ISO14443
protocol
EBADE ：error of length of card returned data
EINVAL ：parameter error
ECOMM ：Parity error or CRC check error of card
returned data
EIO ：read card chip error
ETIME ：timeout return
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.2. desfire_deactive

Prototype： int desfire_deactive(int fd)

Function： Reset mifare DESFire card
Parameter: fd opened device file number that mif_open function returns
Return： 0 Operate OK
-1 Operate failure, please get the actual error code by
errno:
Be NEW8210
applicable
：
Notes： 1、Please refer to desfire.h。
5.11.4.3. desfire_authenticate

Prototype int desfire_authenticate(int fd,uint8_t keyno, const void *key)

：
Function： Do DES/3DES key authentification on mifare DESFire card
Parameter: fd opened device file number that mif_open function
returns
keyno key number that will be certificated
key key information ,is fixed 16 bytes
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1. key information must be 16 types, if actual key is 8 bytes, then
expanding it to 16 bytes as follow: key = old_key[0…7] ||
old_key[0…7]
2、Please refer to desfire.h。

5.11.4.4. desfire_authenticate_iso

Prototype int desfire_authenticate_iso(int fd,uint8_t keyno, const void *key)

：
Function： do 3KDES key authentification on mifare DESFire card
Parameter: fd opened device file number that mif_open function
returns
keyno key number that will be authenticated
key key information ,is fixed 24 bytes
Return： 0 operate success
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card doesn’t fix ISO14443 standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1. key information must be 24 types, if actual key is 8 bytes, then
expanding it to 24 bytes as follow: key = old_key[0…7] ||
old_key[0…7] || old_key[0…7]
2.：if actual key is 16 bytes, then expanding it to 24 bytes as follow:
key = old_key[0…7] || old_key[8…15] || old_key[0…7]
3、Please refer to desfire.h。

5.11.4.5. desfire_authenticate_aes

Prototype int desfire_authenticate_aes(int fd,uint8_t keyno, const void *key)

：
Function： do AES key authentication on mifare DESFire card
Parameter: fd opened device file number that mif_open function
returns
keyno key number that will be certificated
key key information ,is fixed 16 bytes
Return： 0 operate success
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、 Please refer to desfire.h；
2、 AES key’s length is fixed 16 bytes.

5.11.4.6. desfire_change_key_settings

Prototype int desfire_change_key_settings(int fd,uint8_t key_setting)

：
Function： modify PICC Master Key set or Application Master Key set
Parameter: fd opened device file number that mif_open function
returns
key_settings new Master Key setting parameter
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、 Please refer to desfire.h。
5.11.4.7. desfire_get_key_settings

Prototype int desfire_get_key_settings(int fd,uint8_t *key_setting,

： uint8_t *max_key_num)
Function： get PICC Master Key setting or Application Master Key setting
Parameter: fd opened device file number that mif_open function
returns
key_settings Master Key setting parameter that card returned
（output）
max_key_num maximum key number that current application
（output） supports
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ：Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.8. desfire_change_picc_masterkey

Prototype int desfire_change_picc_masterkey(int fd,uint8_t type, const void

： *key,
uint8_t version)
Function： change PICC Master Key
Parameter: fd opened device file number that mif_open function
returns
type PICC Master Key key type, values as follow:
0x00 ---- DES/3DES key （16 bytes）
0x01 ---- 3KDES key （24 bytes）
0x02 ---- AES key （16 bytes）
 key key information,16/24 bytes
version key version information
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.9. desfire_change_app_key

Prototype int desfire_change_app_key(int fd,uint8_t keysetting,uint8_t type,

： uint8_t keyno, const void *oldkey,const void *newkey, uint8_t
version)
Function： change application key
Parameter: fd opened device file number that mif_open function
returns
keysetting application’s master key configuration attribute
parameter
type PICC Master Key key type，values as follow:
0x00 ---- DES/3DES key （16 bytes）
0x01 ---- 3KDES key （24 bytes ）
0x02 ---- AES key （16 bytes）
keyno key number that will be modified
oldkey old key information，16/24 bytes
newkey new key information，16/24 butes
version key version information
Return： 0 operate success
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.10. desfire_get_key_version

Prototype int desfire_get_key_version(int fd,uint8_t keyno,uint8_t *version)

：
Function： get key version information
Parameter: fd opened device file number that mif_open function
returns
keyno key number
version（out key version information that card returned
put）
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。
5.11.4.11. desfire_create_application

Prototype int desfire_create_application(int fd,const desfire_appinfo *info)

：
Function： create a sub-application
Parameter: fd opened device file number that mif_open function
returns
info application information
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.12. desfire_delete_application

Prototype int desfire_delete_application(int fd,const void *aid)

：
Function： delete a sub-application
Parameter: fd opened device file number that mif_open function
returns
aid application AID information, 3 bytes
Return： 0 operate success
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.13. desfire_get_application_ids

Prototype int desfire_get_application_ids(int fd,uint8_t *num, void *aid)

：
Function： get all application’s AID information of DESFire card
Parameter: fd opened device file number that mif_open function
returns
num（outpu application number that card contained
t）
aid （ output application AID information, 3 bytes every application
）
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
 Notes： 1、Please refer to desfire.h。

5.11.4.14. desfire_get_dfnames

Prototype int desfire_get_dfnames(int fd,uint8_t *appnum,dfname_info *info)

：
Function： get all application’s information of DESFire
Parameter: fd opened device file number that mif_open function
returns
appnum （ o application number that card contained
utput）
info （ output application information, every application has a
） dfname_info struct
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.15. desfire_select_application

Prototype int desfire_select_application(int fd,const void *aid)

：
Function： Select a sub-application
Parameter: fd opened device file number that mif_open function
returns
aid application AID information, 3 bytes
Return： 0 operate success
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.16. desfire_format_picc

Prototype int desfire_format_picc(int fd)

：
Function： format DESFire card, delete all application and all application’s key
and file information
Parameter: fd opened device file number that mif_open function
returns
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。
5.11.4.17. desfire_get_version

Prototype int desfire_get_version(int fd, desfire_version *version)

：
Function： get version information of mifare DESFire card
Parameter: fd opened device file number that mif_open function
returns
version（out version information of mifare DESFire card
put）
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.18. desfire_set_configuration

Prototype int desfire_set_configuration(int fd,uint8_t option, uint8_t len,

： const void *info)
Function： configure mifare DESFire card
Parameter: fd opened device file number that mif_open function
returns
option configuration information option
len configuration information length
info content of configuration information
Return： 0 operate success
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.19. desfire_free_memory

Prototype int desfire_free_memory(int fd,uint32_t *freesize)

：
Function： get the size of the available memory space of mifare DESFire card
Parameter: fd opened device file number that mif_open function
returns
freesize（ou size of the remaining available space of mifare
tput） DESFire card
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。
5.11.4.20. desfire_get_card_uid

Prototype int desfire_get_card_uid(int fd,void *uid)

：
Function： get UID information of mifare DESFire card
Parameter: fd opened device file number that mif_open function
returns
uid （ output UID information that mifare DESFire card returns, 7
） bytes
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.21. desfire_get_fids

Prototype int desfire_get_fids(int fd,uint8_t *num, void *fid)

：
Function： get current sub-application’s file fid information of mifare DESFire
card
Parameter: fd opened device file number that mif_open function
returns
num（outpu file number of application
t）
fid （ output fid information of file,1 byte every file
）
Return： 0 operate success
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.22. desfire_get_iso_fids

Prototype int desfire_get_iso_fids(int fd,uint8_t *num, void *fid)

：
Function： get current sub-application’s file iso fid information of mifare
DESFire card
Parameter: fd opened device file number that mif_open function
returns
num（outpu file number of application
t）
fid （ output file iso fid information, 2 bytes every file
）
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
 Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.23. desfire_get_filesetting

Prototype int desfire_get_filesetting(int fd,uint8_t fileno, desfire_file *filesetting)

：
Function： get the designated file’s information
Parameter: fd opened device file number that mif_open function
returns
fileno file number
filesetting （ returned file information
output）
Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.24. desfire_change_filesetting

Prototype int desfire_change_filesettings(int fd,uint8_t fileno, uint8_t

： comm_set,
uint8_t old_change_access_keyno,
uint8_t new_read_access_keyno,
uint8_t new_write_access_keyno,
uint8_t
new_read_write_access_keyno,
uint8_t
 new_change_access_keyno)
Function： modify file attribute information
Parameter: fd opened device file number that
mif_open function returns
fileno file number
comm_set transmission mode of the file ,
values are as follow:
0x00 ---- plaintext transmission
0x03 ---- ciphertext transmission
0x01 ---- transmission with MAC
old_change_access_keyno old key number that is needed to
be certificated when modifying
key
new_read_access_keyno new key number that is need to
be certificated when reading file
new_write_access_keyno new key number that is need to
be certificated when writing file
new_read_write_access_keyno new key number that is need to
be certification when reading and
writing file
new_change_access_keyno new key number that is need to
be certificated when modifying
key
Return： 0 operate success
-1 Operate failure, please get the
actual error code by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC
check error of card returned data
EPROTO ： Card doesn’t comply
with ISO14443 standard
EBADE ： error of length of card
returned data
ETIME ：timeout return
ENODATA ： card in inductive is
not a mifare DESFire card or card
had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。
5.11.4.25. desfire_create_std_datafile

Prototype int desfire_create_std_datafile(int fd,uint8_t fileno,

： const desfire_std_backup_file_info
*fileinfo)
Function： create general data file
Parameter: fd opened device file number that mif_open function returns
fileno file number
fileinfo general data file information
Return： 0 operate success
-1 Operate failure, please get the actual error code by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card doesn’t comply with ISO14443 standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire card
or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.26. desfire_create_backup_datafile

Prototype int desfire_create_backup_datafile(int fd,uint8_t fileno,

： const desfire_std_backup_file_info
*fileinfo)
Function： create a backup data file
Parameter: fd opened device file number that mif_open function returns
fileno file number
fileinfo backup data file information
Return： 0 operate success
 -1 Operate failure, please get the actual error code by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card doesn’t comply with ISO14443 standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.27. desfire_create_valuefile

Prototype int desfire_create_valuefile(int fd, uint8_t fileno,

： const desfire_value_file_info *fileinfo)
Function： create value file
Parameter: fd opened device file number that mif_open function returns
fileno file number
fileinfo value file information
Return： 0 operate success
-1 Operate failure, please get the actual error code by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card doesn’t comply with ISO14443 standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.28. desfire_create_linear_recordfile

Prototype int desfire_create_linear_recordfile(int fd,uint8_t fileno,

 ： const desfire_record_file_info *fileinfo)
Function： create linear log file
Parameter: fd opened device file number that mif_open function returns
fileno file number
fileinfo linear log file information
Return： 0 operate success
-1 Operate failure, please get the actual error code by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card doesn’t comply with ISO14443 standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.29. desfire_create_cyclic_recordfile

Prototype int desfire_create_cyclic_recordfile(int fd,uint8_t fileno,

： const desfire_record_file_info
*fileinfo)
Function： create cycle log files
Parameter: fd opened device file number that mif_open function returns
fileno file number
fileinfo circular log file information
Return： 0 operate success
-1 Operate failure, please get the actual error code by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card doesn’t comply with ISO14443 standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire card
or card had not been activated
other value : other error code
Support： NEW8210
 Notes： 1、Please refer to desfire.h。

5.11.4.30. desfire_delete_file

Prototype int desfire_delete_file(int fd,uint8_t fileno)

：
Function： delete a file
Parameter: fd opened device file number that mif_open function returns
fileno file number
Return： 0 operate success
-1 Operate failure, please get the actual error code by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ：Card doesn’t comply with ISO14443 standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire card
or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.31. desfire_read_data

Prototype int desfire_read_data(int fd,

： uint8_t fileno,
uint8_t comm_set,
uint32_t offset,
uint32_t len,
uint32_t *outlen,
void *dataout)
Function： read data from general data file or backup data file
Parameter: fd opened device file number that mif_open
function returns
fileno file number
comm_set transmission mode, values are as follow:
0x00 ----- plaintext transmission
0x03 ----- ciphertext transmission
 0x01 ----- transmission with MAC verification
offset read start address
len expect length that will be read
outlen（output） actual data length that have been read
dataout （ output actual data that have been read
）
Return： 0 operate success
-1 Operate failure, please get the actual error code
by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of
card returned data
EPROTO ：Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.32. desfire_write_data

Prototype int desfire_write_data(int fd,

： uint8_t fileno,
uint8_t comm_set,
uint32_t offset,
uint32_t len,
const void *datain)
Function： write data into general data file or into backup data file
Parameter: fd opened device file number that mif_open function
returns
fileno file number
comm_set transmission mode, values are as follow:
0x00 ----- plaintext transmission
0x03 ----- ciphertext transmission
0x01 ----- transmission with MAC verification
offset start address that will be written
len data length that will be written
datain data that will be written
 Return： 0 operate success
-1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.33. desfire_get_value

Prototype int desfire_get_value(int fd,uint8_t fileno,uint8_t comm_set,uint32_t

： *value)
Function： get the value of the specified file
Parameter: fd opened device file number that mif_open function
returns
fileno file number
comm_set transmission mode, values are as follow:
0x00 ----- plaintext transmission
0x03 ----- ciphertext transmission
0x01 ----- transmission with MAC verification
value （ output value size of the value file
）
Return： 0 operate success
 -1 Operate failure, please get the actual error code
by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ：Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.34. desfire_credit

Prototype int desfire_credit(int fd,uint8_t fileno,uint8_t comm_set,uint32_t

： value)
Function： recharge operation
Parameter: fd opened device file number that mif_open function
returns
fileno file number
comm_set transmission mode, values are as follow:
0x00 ----- plaintext transmission
0x03 ----- ciphertext transmission
0x01 ----- transmission with MAC verification
value size of recharge
Return： 0 operate success
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.35. desfire_debit

Prototype int desfire_debit(int fd,uint8_t fileno,uint8_t comm_set,uint32_t

： value)
Function： deduct value operation
Parameter: fd opened device file number that mif_open function
returns
fileno file number
comm_set transmission mode, values are as follow:
0x00 ----- plaintext transmission
0x03 ----- ciphertext transmission
0x01 ----- transmission with MAC verification
value Value to deduct
Return： 0 operate success
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.36. desfire_limited_credit

Prototype int desfire_limited_credit(int fd,uint8_t fileno,uint8_t comm_set,

： uint32_t value)
Function： limited recharge operation
Parameter: fd opened device file number that mif_open function
returns
fileno file number
comm_set transmission mode, values are as follow:
0x00 ----- plaintext transmission
0x03 ----- ciphertext transmission
0x01 ----- transmission with MAC verification
value size fo recharge
Return： 0 operation
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.37. desfire_write_record

Prototype int desfire_write_record(int fd,

： uint8_t fileno,
uint8_t comm_set,
int offset,
int len,
const void *info)
Function： write log operation
Parameter: fd opened device file number that mif_open function
returns
fileno file number
comm_set transmission mode, values are as follow:
0x00 ----- plaintext transmission
0x03 ----- ciphertext transmission
0x01 ----- transmission with MAC verification
offset start address of current log
len length of data that will be written
info log information that will be written
Return： 0 operate success
 -1 Operate failure, please get the actual error code by
errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card
returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire
card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.38. desfire_read_records

Prototype int desfire_read_records(int fd,

： uint8_t fileno,
uint8_t comm_set,
uint32_t recordsize,
int first,
int num,
uint32_t *outlen,
void *info)
Function： read log operation
Parameter: fd opened device file number that mif_open function
returns
fileno file number
comm_set transmission mode, values are as follow:
0x00 ----- plaintext transmission
0x03 ----- ciphertext transmission
0x01 ----- transmission with MAC verification
recordsize length of log
first first log number that will be read
num count of logs that will be read
outlen （ output total length of data that have been read
）
info（output） log information that have been read
Return： 0 operate success
 -1 Operate failure, please get the actual error code
by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of
card returned data
EPROTO ： Card doesn’t comply with ISO14443
standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ： card in inductive is not a mifare
DESFire card or card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.39. desfire_clear_recordfile

Prototype int desfire_clear_recordfile(int fd,uint8_t fileno)

：
Function： clear all record files
Parameter: fd opened device file number that mif_open function returns
fileno file number
Return： 0 operate success
-1 Operate failure, please get the actual error code by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check all error of card
returned data
EPROTO ：Card doesn’t comply with ISO14443 standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire card
or card had not been activated
other value : other error code
Be NEW8210
application
in：
Notes： 1、Please refer to desfire.h。
5.11.4.40. desfire_commit_transaction

Prototype int desfire_commit_transaction(int fd)

：
Function： confirm and save all related operations on current application’s files
Parameter: fd opened device file number that mif_open function returns
Return： 0 operate success
-1 Operate failure, please get the actual error code by errno:
EINVAL ：input parameter error
EIO ：read card chip error
ECOMM ： Parity error or CRC check error of card returned
data
EPROTO ：Card doesn’t comply with ISO14443 standard
EBADE ：error of length of card returned data
ETIME ：timeout return
ENODATA ：card in inductive is not a mifare DESFire card or
card had not been activated
other value : other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。

5.11.4.41. desfire_abort_transaction

Prototype int desfire_abort_transaction(int fd)

：
Function： undo related operations on current application’s files
Parameter: fd opened device file number that
mif_open function returns
Return： 0 operate success
EINVAL input parameter error
EIO read card chip error
ECOMM Parity error or CRC check error of
card returned data
EPROTO Card doesn’t comply with ISO14443
standard
EBADE data of card returned error
EACCES card in inductive is not a mifare
DESFire card or card had not been
activated
ETIME timeout and no return
 other value other error code
Support： NEW8210
Notes： 1、Please refer to desfire.h。
5.12. AT24CXX card module interface

5.12.1. at24_open

Prototype int at24_open(int fd)

：
Function： active AT24xx series card of the designated IC card slot
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 active operate success
-1 Operate failure, please get the actual error code by errno:
ENXIO: do not exist AT24xx card in card slot
other value : other error code
Support： NEW8210
Notes： 1、Please refer to at24xx.h。

5.12.2. at24_read

Prototype int at24_read(int fd,int card_type,int start_addr,int len,void *data)

：
Function： read information from AT24xx card
Parameter: fd opened device file number that iccard_open_cardslot
function returns
card_type AT24 card type, refer to note
start_addr start address
len length of data that will be read
data （ out read data
put）
Return： 0 read operate success
-1 Operate failure, please get the actual error code by
errno:
ENXIO: do not exist AT24xx card in card slot
EINVAL ：input parameter error
ETIME ：timeout
other value : other error code
Support： NEW8210
Notes： 1、Please refer to at24xx.h。
5.12.3. at24_write

Prototype int at24_write(int fd,int card_type,int start_addr,int len,const void

： *data)
Function： write data into AT24xx card
Parameter: fd opened device file number that iccard_open_cardslot
function returns
card_type AT24 card type, refer to note
start_add start address
r
len length of data that will be written into
data data that is written into
Return： 0 write operate success
-1 Operate failure, please get the actual error code by
errno:
ENXIO: do not exist AT24xx card in card slot
EINVAL ：input parameter error
ETIME ：timeout
other value : other error code
Support： NEW8210
Notes： 1、Please refer to at24xx.h。

5.12.4. at24_close

Prototype int at24_close(int fd)

：
Function： Close AT24 series card
Parameter: fd opened device file number that iccard_open_cardslot
function returns
Return： 0 power off success
-1 Operate failure, please get the actual error code by errno
Support： NEW8210
Notes： 1、Please refer to at24xx.h。

5.13. Modem

Modem supports 1200bps and 2400bps sync dial, supports up to 336000bps async dial,
supports ppp dial.
Please refer to PPPLogin, PPPLogout and PPPCheck to get the information for ppp
dial.
The following introduce the sync dial and async dial.

5.13.1. Correlative Macro definition of this module:

Modem status
Definition Description
MODEM_STATE_NOT_INIT Modem has not been initialized, or Initialized
failed. If initialized successfully, modem will turn to
MODEM_STATE_NO_SET_MODE automatically.
MODEM_STATE_NO_SET_MODE Modem has been initialized successfully, but the
mode has not been set. At this state, application is
permitted to set dial parameters. If the parameters
are set successfully, modem will turn to
MODEM_STATE_DISCONNECT.
MODEM_STATE_SYNC_MODE The background is handling after the mode is set
to sync dial. If handled successfully, modem will
turn to MODEM_STATE_DISCONNECT
automatically.
MODEM_STATE_ASYN_MODE The background is handling after the mode is set
to async dial. If handled successfully, modem will
turn to MODEM_STATE_DISCONNECT
automatically.
MODEM_STATE_DISCONNECT Modem is disconnected. In this state, application
is permitted to dial, set dial parameters, set sdlc
parameters or dial off.
MODEM_STATE_WAITTING Modem turns to dial in state, waiting for dial in. At
this state, modem can return to
MODEM_STATE_DISCONNECT via dial off or exit
dial in mode.
MODEM_STATE_DAILING Modem is dialing. If dials successfully, modem
turns to MODEM_STATE_CONNECT_SDLC
(sync mode), or turns to
MODEM_STATE_CONNECT (async mode)
directly. Modem can return to
MODEM_STATE_DISCONNECT via dial off.
MODEM_STATE_CONNECT_SDLC Modem connects successfully, and the sldc is
handshaking. If handshakes successfully, modem
will turn to MODEM_STATE_CONNECT,
otherwise, it will turn to
MODEM_STATE_DISCONNECT.
MODEM_STATE_CONNECT The data link is connected successfully.
Application is permitted to send/receive data in
this state. If dials off, modem will return to
MODEM_STATE_DISCONNECT.
Modem state transition diagram:
Dial modes:
Definition Description
MODEM_DAIL_DTMF DTMF mode
MODEM_DAIL_PULSE PULSE mode

Modem communication modes:

Definition Description
MODEM_COMM_ASYNC Async mode
MODEM_COMM_SYNC Sync SDLC mode

Modem special returns codes:

Definition Description
MODEM_ERRNO_OK OK
MODEM_ERRNO_CONNECT Link connected
MODEM_ERRNO_ERROR Response error of AT command
MODEM_ERRNO_BUSY Modem is busy
MODEM_ERRNO_NO_DIALTONE No dial tone
MODEM_ERRNO_NO_CARRIER No carrier
MODEM_ERRNO_NO_LINE No line in
MODEM_ERRNO_NO_ANSWER No answer
MODEM_ERRNO_OFF_HOOK Hand up by the peer
MODEM_ERRNO_LINE_IN_USE Line in use
MODEM_ERRNO_UN_OBTAINABLE Unobtainable
MODEM_ERRNO_LINE_REVERSAL Line reversal
MODEM_ERRNO_EXTENSION_IN_USE Extension phone is in use
Please refer to the other return codes in <error.h>

Modem connecting baud rate definition:

Definition Description
MODEM_CONNECT_1200BPS 1200bps sync/async
MODEM_CONNECT_2400BPS 2400bps sync/async
MODEM_CONNECT_4800BPS 4800bps async
MODEM_CONNECT_7200BPS 7200bps async
MODEM_CONNECT_9600BPS 9600bps async
MODEM_CONNECT_12000BPS 12000bps async
MODEM_CONNECT_14400BPS 14400bps async
MODEM_CONNECT_16800BPS 16800bps async
MODEM_CONNECT_19200BPS 19200bps async
MODEM_CONNECT_21600BPS 21600bps async
MODEM_CONNECT_24000BPS 24000bps async
MODEM_CONNECT_26400BPS 26400bps async
MODEM_CONNECT_28800BPS 28800bps async
MODEM_CONNECT_31200BPS 31200bps async
MODEM_CONNECT_33600BPS 33600bps async
MODEM_CONNECT_48000BPS 48000bps async
MODEM_CONNECT_56000BPS 56000bps async

Country code IDs:

Country code IDs are defined in <modem_iface.h>, It’s defined as ModemRegion(…), for
example, China defined as ModemRegion(China).

5.13.2. data struction

typedef struct {
int connect_mode;
int connect_speed;
int dial_mode;
int dial_pause;
int dial_timeo;
int idle_timeo;
int extension_chk;
RegionCode_t region;
int reserved[4];
} ModemDialParms_t;
This structure is used to set modem dial parameters. The member is defined as
following:
connect_mode: MODEM_COMM_ASYNC / MODEM_COMM_SYNC
connect_speed: Point out the expected speed, refer to the definition
dial_mode: MODEM_DAIL_DTMF / MODEM_DAIL_PULSE
dial_pause: pause time if there is ‘,’ in the dial number string (unit: second)
dial_timeo: Set the timeout of dial (unit: second)
idle_timeo: Timeout of idle. When there is no data send/receive in set timeout, modem
will dial off automatically. Set to 0 disable idle detect.
extension_chk: 1-check whether the extension phone is in use before dial; 0-don’t check
region: Country code IDs, in different countries or regions, the modulability of
telephone line may be different too, so you should set country code in
here.
reserved: set to 0

The struction for send AT command directly:

typedef struct {
int16_t timeo;
uint8_t reserved[6];
 char cmd[256];
char maybe[760];
char rsp[1024];
} ModemAtCmd_t;
timeo: timeout of waiting AT command response, 0-keep waiting, < 0- don’t wait for
response
reserved: had better set to 0
cmd: AT command string, such as ”ATH0”
maybe: The possible key words of the response string, such as 2 0x00 indicate the
end of string or {‘O’, ‘K’, ‘\0’, ‘E’, ‘R’, ‘R’, ‘O’, ‘R’, ‘\0’, ‘\0’}
rps: to store the response from the modem

The struction of SDLC parameters:

typedef struct {
unsigned int t1;
unsigned int t2;
unsigned int n2;
unsigned int n2count;
unsigned int window;
unsigned int state;
unsigned int mode;
} ModemSdlcParms_t;
t1: The timeout of waiting response after send data. If timeout, the data will be
sent again.
t2: The timeout of waiting the confirmed acknowledge the data from the
receiver. If timeout, the RR frame will be sent to report the modem status.
n2: Relate to t1, the max times limit of resend. If reached, the link will be
closed.
n2count: Relate to t1, the current resend times If n2count >= n2, the link will be
closed.
window: The number of sliding windows range [1-7]
state: the current status of sdlc protocol (it is not recommended to change)
mode: the current mode of sdlc protocol (read only)

This structure is used to set/get SDLC parameters. The incorrect setting will lead the
protocol works abnormally. If you don’t know the protocol clearly, please don’t use this
function.
5.13.3. modem_open

Prototype: int modem_open(const char *pathname, int oflags)

Function: Open the modem device, get the handle of modem.
Parameter: pathname(Input The device name of Modem, such as
) ”/dev/ttyS1”(NEW8210) or “/dev/modem0” (NEW8110)
oflags(Input) Open mode O_RDWR Read/write (required)
O_NONBLOCK non-blocking
(optional)
Return: >=0 Open successfully, the code is the handle which is
used for the subsequent operation.
<0 Open failed. Refer to <errno.h>
Be NEW8210
Applicable
In:
Notes:  This function is same as the open of POSIX. The difference is this
function can not use create file mode. So there are only 2 parameters
in this function.
 oflag can be set to O_RDWR or (O_RDWR | O_NONBLOCK)
 If oflag is set to O_RDWR, modem_write and modem_read will keep
waiting until write/read successfully.
 If olfag is set to (O_RDWR | O_NONBLOCK), modem_write will
return immediately and send data background; modem_read only
check the receive buffer in the background.
 If this function returns success (return code >= 0), application needs
invoke modem_get_status to wait finishing initialization. If finish
initialization successfully, modem will turn to
MODEM_STATE_NO_SET_MODE, otherwise it will turn to
MODEM_STATE_NOT_INIT.

Example: Example 1:
int fd;
if ((fd = modem_open(“/dev/ttyS1”, O_RDWR)) < 0) {
// error
}

Example 2:
if ((fd = modem_open(“/dev/ttyS1”, O_RDWR | O_NONBLOCK)) < 0) {
// error
}
5.13.4. modem_close

Prototype: int modem_close(int fd)

Function: Close the modem device.
Parameter: fd(Input) The handle of modem which is get from modem_open.
Return: 0 Close modem device successfully.
others Close failed. Refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: This function is same as the close of POSIX.
Example:

5.13.5. modem_write

Prototype: ssize_t modem_write(int fd, const void *buf, size_t nbytes)

Function: Send data via modem. Can be used in sync and async mode.
Parameter: fd(Input) The handle of modem which is get from modem_open.
buf(Input) The buffer point to the data to send
nbytes(Input) The byte length of buffer to send
Return: >=0 The byte length of buffer which are sended successfully
<0 Failed. Invoke PosixGeterrno to get the detail error.
Be NEW8210
Applicable
In:
Notes: This function is the same as the write of POSIX.
This function can be invoked at state MODEM_STATE_CONNECT.
If the modem is opened by O_RDWR, this function will not return until all
data are sent finished or the link broken.
If the modem is opened by (O_RDWR | O_NONBLOCK), this function will
return immediately. If the buffer is full or the link broken, this function will
return a negative code. If the code equal to -1, and PosixGeterrno returns
EAGAIN, it indicates that the buffer is full, this function can not send
temporary.
Example:
5.13.6. modem_write_timeout

Prototype: ssize_t modem_write_timeout(int fd, const void *buf, size_t nbytes,

uint32_t timeoutms)
Function: Send data via modem with specified timeout. Can be used in sync and
async mode.
Parameter: fd(Input) The handle of modem which is get from modem_open.
buf(Input) The buffer to send
nbytes(Input) The byte length of buffer to send
timeoutms(Input Timeout (unit: ms)
)
Return: >=0 The byte length of buffer which are sended
successfully
<0 Failed. Invoke PosixGeterrno to get the detail error.
Be NEW8210
Applicable
In:
Notes: This function is same as modem_write except the timeout can be
specified.
This function can be invoked at the state MODEM_STATE_CONNECT.
This function will return before timeout even if the modem is opened by
blocking mode (O_RDWR). Before timeout, this function will try to submit
all data to the modem buffer; If all data are submitted complete, the
function returns.
Example:

5.13.7. modem_wait_until_sent

Prototype: int modem_wait_until_sent(int fd)

Function: Wait for all data in the send buffer are sent completly.
Parameter: fd(Input) The handle of modem which is get from modem_open.
Return: 0 OK
Others Failed. Refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: The data are not sent out immediately when the application invokes
modem_write and modem_write_timeout. While the data are stored into
 the send buffer and sent in the background. This function is used to wait
for data sent complete. This function won’t return until all data are sent
complete.
It is recommended to invoke this function to make sure that all data are
sent out before hand up or close modem device.
Example:

5.13.8. modem_read

Prototype: ssize_t modem_read(int fd, void *buf, size_t nbytes)

Function: Receive data via modem. Can be used in sync and async mode.
Parameter: fd(Input) The handle of modem which is get from modem_open.
buf(Output) The given buffer to store the received data
nbytes(Input) The expected receive byte length
Return: >=0 The actual received byte length
<0 Failed. Invoke PosixGeterrno to get the detail error.
Be NEW8210
Applicable
In:
Notes: This function is same as the read of POSIX.
This function can be invoked at state MODEM_STATE_CONNECT.
If the modem is opened by O_RDWR, this function will not return until a
packet data are received finished or the link broken.
If the modem is opened by (O_RDWR | O_NONBLOCK), this function will
return immediately. If the buffer is empty or the link broken, this function
will return a negative code. If the code equal to -1, and PosixGeterrno
return EAGAIN, it indicates that the buffer is empty, this function can not
receive temporary.
Example:

5.13.9. modem_read_timeout

Prototype: ssize_t modem_read_timeout(int fd, void *buf, size_t nbytes,

uint32_t timeoutms)
Function: Receive data via modem with specified timeout. Can be used in sync and
async mode.
Parameter: fd(Input) The handle of modem which is get from modem_open.
 buf(Output) The given buffer to store the received data
nbytes(Input) The expected receive byte length
timeoutms(Input Timeout (unit: ms)
)
Return: >=0 The actual received byte length
<0 Failed. Invoke PosixGeterrno to get the detail error.
Be NEW8210
Applicable
In:
Notes: This function is same as modem_read except the timeout can be
specified.
This function can be invoked at the state MODEM_STATE_CONNECT.
This function will return before timeout even if the modem is opened by
blocking mode (O_RDWR). Before timeout, this function will try to receive
the expected data length from the modem buffer; If the expected length of
data is received complete, the function returns.
Example:

5.13.10. modem_dialing

Prototype: int modem_dialing(int fd, const char *telephone)

Function: dialing.
Parameter: fd(Input) The handle of modem which is get from modem_open.
telephone(Input) The telephone number string.
Return: 0 OK
Others Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: This function can be invoked at the state MODEM_STATE_DISCONNECT,
and will return immediately without waiting dial complete. Application
checks the dial result via modem_get_status. After successful invoke this
function, modem turns to the state MODEM_STATE_DAILING. If dial up
successfully, modem turns to the state
MODEM_STATE_CONNECT_SDLC or MODEM_STATE_CONNECT. If
dial up failed, modem turns to the state MODEM_STATE_DISCONNECT,
and application can get the detail via modem_get_last_errno.
The dial mode is decided by modem_set_dial_parms.

The meanings of telephone number:

[0-9, *, #, A-D] – telephone number;
 [,] – delay 1 second
[;] – send the next number;

Example: if ((retval = modem_dialing(modem, telephone))) {

// failed to invoke function
……
}

for (keep=1; keep; ) {

if ((retval = modem_get_status(modem, &status))) {
// failed to invoke function
……
break;
}

if (status & 0x80000000) // operation not completed

continue;

switch (status & 0x7FFFFFFF) {

case MODEM_STATE_CONNECT_SDLC:
// now sdlc link connecting
break;
case MODEM_STATE_CONNECT:
// OK, link is connected
keep = 0;
break;
case MODEM_STATE_DISCONNECT:
default:
// error, failed to connect
……
keep = 0;
break;
}
}

5.13.11. modem_hangup

Prototype: int modem_hangup(int fd)

Function: Modem hangs up.
Parameter: fd(Input) The handle of modem which is get from modem_open.
Return: 0 Hangs up successfully.
 Others Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: This function can be invoked at the state MODEM_STATE_DISCONNECT,
MODEM_STATE_DAILING, MODEM_STATE_CONNECT_SDLC or
MODEM_STATE_CONNECT, used to hang up the line actively.
If Hand up happens in blocking mode which may spends about 2-4
seconds. It depends on the current modem status. If Modem stays in state
of MODEM_STATE_DISCONNECT, it will returns immediately (less than 1
second) after call hangup function; while the modem stays in
MODEM_STATE_CONNECT, it will take more time(2 seconds) to return
after calling modem_hangup. After successful hangup, the Modem will
stays in the status of MODEM_STATE_DISCONNECT.
Example:

5.13.12. modem_get_status

Prototype: int modem_get_status(int fd, int *status)

Function: Get current modem status.
Parameter: fd(Input) The handle of modem which is get from modem_open.
status(Output) Return current status
Return: 0 OK
others Failed. Refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: If invoked successfully, this function returns current modem status via
status. The most significant bit of status indicates whether the background
operation is finished. If the most significant bit equal to 1, it indicates that
the background operation is not finished, the current status is not stable.
The other bits indicates the device status, please refer to the definition.
Example: static int modem_wait_status(int fd, int *state, void (*wait_func)(void *),
void *arg)
{
int retval, status;

while (1) {
if ((retval = modem_get_status(fd, &status)))
 break;

if (status & 0x80000000) {

/* waitting operation completed */
if (wait_func)
wait_func(arg);
continue;
}

*state = status & 0x7FFFFFFF;

break;
}

return retval;
}

5.13.13. modem_get_last_errno

Prototype: int modem_get_last_errno(int fd, int *err)

Function: Get current modem error code.
Parameter fd(Input) The handle of modem which is get from
: modem_open.
err(Output) Return current modem error code.
Return: 0 OK
Others Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: This function is used to get errno after modem operates failed not used to
get error code after send/receive failed. Modem operation includes
initialization, set dial parameters, dial, set automatic answer mode, and
hand up. This function can not be used to get error code after
modem_write or modem_read return error (use PosixGeterrno to get
the corresponding code).
If this function return 0, the error code is stored in err. Please refer to the
definition of MODEM_ERRNO_xxxx.
Example:
5.13.14. modem_set_dial_parms

Prototype: int modem_set_dial_parms(int fd, const ModemDialParms_t *dp)

Function: Set current modem dial parameters.
Parameter: fd(Input) The handle of modem which is get from modem_open.
dp(Input) The given parameters.
Return: 0 OK
Others Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: This function can only be invoked at the state
MODEM_STATE_NO_SET_MODE and MODEM_STATE_DISCONNECT.
After this function returns, modem will handle the parameters at the
background, and modem is at an unstable state. Application need invokes
modem_get_status to wait for the setting complete. If set complete,
modem turns to the state MODEM_STATE_DISCONNECT.
Example:

5.13.15. modem_get_dial_parms

Prototype: int modem_get_dial_parms(int fd, ModemDialParms_t *dp)

Function: Get current dial parameters.
Parameter: fd(Input) The handle of modem which is get from modem_open.
dp(Output) Use to store current dial parameters
Return: 0 OK
Others Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: This function can only be used at the state
MODEM_STATE_NO_SET_MODE and MODEM_STATE_DISCONNECT.
Example:
5.13.16. modem_get_sdlc_parms

Prototype: int modem_get_sdlc_parms(int fd, ModemSdlcParms_t *sp)

Function: Get the current parameters of SDLC protocol.
Parameter: fd(Input) The handle of modem which is get from
modem_open.
sp(Output) The space to store the parameters.
Return: 0 OK
Others Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes:
Example:

5.13.17. modem_set_sdlc_parms

Prototype: int modem_set_sdlc_parms(int fd, const ModemSdlcParms_t *sp)

Function: Set the parameters of SDLC protocol.
Parameter: fd(Input) The handle of modem which is get from modem_open.
sp(Input) The given parameters.
Return: 0 OK
Others Failed, refer to <errno.h>
Support: NEW8210
Notes:
Example:

5.13.18. modem_enter_auto_answer

Prototype： int modem_enter_auto_answer(int fd);

Function：
Parameter： fd（Input） Return value of modem_open

Return： 0 Success
 Other Failed，Please refer <errno.h>
Support： NEW8210
Notes：

5.13.19. modem_exit_auto_answer

Prototype： int modem_exit_auto_answer(int fd);

Function：
Parameter： fd（Input） Return value of modem_open
Return： 0 Success
Other Failed，Please refer <errno.h>
Support： NEW8210
Notes：

5.13.20. modem_check_extension

Prototype: int modem_check_extension(int fd)

Function: Check the current status of extension phone.
Parameter: fd(Input) The handle of modem which is
get from modem_open.
Return: 0 Extension isn’t in use (on
hook)
MODEM_ERRNO_EXTENSION_IN_USE Extension is in use
MODEM_ERRNO_NO_LINE No line in
Others Failed
Be NEW8210
Applicable
In:
Notes: This function is used to check the line and extension. Before dial via
modem_dialing, modem will check automatically. So application needn’t
check before dial.
Example:
5.13.21. modem_exec_at_command

Prototype: int modem_exec_at_command(int fd, ModemAtCmd_t *at)

Function: Send AT command directly.
Parameter: fd(Input) The handle of modem which is get from modem_open.
At(Input) Input: at command
Output: response of at command
Return: 0 OK
Others Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: This function provides an interface to control modem by the application.
Please notice that this function is blocking mode.
Example: int modem_onhook(int fd)
{
ModemAtCmd_t at;
int len = 0, retval;

memset(&at, 0x00, sizeof(at));

at.timeo = 2;
snprintf(at.cmd, sizeof(at.cmd), "ATH0");
len += snprintf(&at.maybe[len], sizeof(at.maybe)-len, "\r\nOK\r\n");
len += snprintf(&at.maybe[len+1], sizeof(at.maybe)-len,
"\r\nERROR\r\n");

retval = modem_exec_at_command(fd, &at);

return retval;
}

int modem_offhook(int fd)

{
ModemAtCmd_t at;
int len = 0, retval;

memset(&at, 0x00, sizeof(at));

at.timeo = 2;
snprintf(at.cmd, sizeof(at.cmd), "ATH1");
len += snprintf(&at.maybe[len], sizeof(at.maybe)-len, "\r\nOK\r\n");
len += snprintf(&at.maybe[len+1], sizeof(at.maybe)-len,
"\r\nERROR\r\n");
 retval = modem_exec_at_command(fd, &at);

return retval;
}

5.13.22. modem_power_control

Prototype： int modem_power_control(int onoff)

Function： Control the power supply of modem
Parameter: onoff（input） 1-power on
0-power off
Return： 0 OK
Support： NEW8210
Notes： If you use a dial-up Modem for PPP, you need to open the modem power,
and call this function to close the modem power after used;
When using modem synchronous / asynchronous communication,
modem_open () will automatically open modem power supply, need not to
call the function.
Example:

5.14. PPP

Use PPP module, need to contain head file “ppp.h”.

PPP module supports these authentication protocol:
 PAP
 CHAP
 MSCHAP V1/V2

Return code of PPP:

Return Reason
0 Pppd has detached, or otherwise the connection was successfully
established and terminated at the peer’s request.
-100 No ppp device or pppd is starting
-1032 ppp dial is processing
-4001 An immediately fatal error of some kind occurred, such as an essential
 system call failing, or running out of virtual memory.
-4002 An error was detected in processing the options given, such as two mutually
exclusive options being used.
-4003 Pppd is not setuid-root and the invoking user is not root.
-4004 The kernel does not support PPP, for example, the PPP kernel driver is not
included or cannot be loaded.
-4005 Pppd terminated because it was sent a SIGINT, SIGTERM or SIGHUP
signal.
-4006 The serial port could not be locked.
-4007 The serial port could not be opened.
-4008 The connect script failed (returned a non-zero exit status).
-4009 The command specified as the argument to the pty option could not be run.
-4010 The PPP negotiation failed, that is, it didn’t reach the point where at least
one network protocol (e.g. IP) was running.
-4011 The peer system failed (or refused) to authenticate itself.
-4012 The link was established successfully and terminated because it was idle.
-4013 The link was established successfully and terminated because the connect
time limit was reached.
-4014 Callback was negotiated and an incoming call should arrive shortly.
-4015 The link was terminated because the peer is not responding to echo
requests.
-4016 The link was terminated by the modem hanging up.
-4017 The PPP negotiation failed because serial loopback was detected.
-4018 The init script failed (returned a non-zero exit status).
-4019 We failed to authenticate ourselves to the peer.

5.14.1. ppp_open

Prototype int ppp_open(const char *devname, const char *chat,

： const char *user, const char *passwd,
uint32_t auth, int timeout)
Function： build PPP linking
Parameter: devname device which is used to build ppp linking, for example
modem use ”/dev/ttyS1”
chat interactive script which is used to ppp dialing, refer to
note
user certificate needed user name
passwd certificate needed password
 auth authentication：
PPP_ALG_PAP
PPP_ALG_CHAP
PPP_ALG_MSCHAPV1
PPP_ALG_MSCHAPV2

timeout timeout, unit: second

Return： 0 operate success
other returned code of operate failure
Support： NEW8210
Notes： chat is ppp dialing interactive execute script , examples of chat script is
below

MODEM PPP chat：

char modem_chat_file[] = {
"ABORT 'NO CARRIER'" "\n"
"ABORT 'NO DIALTONE'" "\n"
"ABORT 'ERROR'" "\n"
"ABORT 'NO ANSWER'" "\n"
"ABORT 'BUSY'" "\n"
"TIMEOUT '60'" "\n"
"'' 'ATZ'" "\n"
"'OK' 'ATH0'" "\n"
"'OK' 'ATDT96169'" "\n"
"'CONNECT' ''" "\n"
};
TIMEOUT line above means dialing timeout, if can not connect to ppp
link until timeout, then this ppp dialing will stop.
ATDT96169 means the number of ppp dialing is 96169.
These AT start is modem’s initialization command, it will need to
configure different command according to actual condition.

GPRS PPP chat

char gprs_chat_file[] = {
"ABORT 'NO CARRIER'" "\n"
"ABORT 'NO DIALTONE'" "\n"
"ABORT 'ERROR'" "\n"
"ABORT 'NO ANSWER'" "\n"
"ABORT 'BUSY'" "\n"
"ABORT 'Invalid Login'" "\n"
"ABORT 'Login incorrect'" "\n"
"TIMEOUT '60'" "\n"
"'' 'ATZ'" "\n"
"'OK' 'AT+CGDCONT=1,\"IP\",\"CMNET\"'" "\n"
 "'OK' 'ATDT*99***1#'" "\n"
"'CONNECT' ''" "\n"
};
The same as modem ppp, AT start is all module initialization command,
the line before CONNECT is number of PPP dialing：*99***1#
CDMA PPP chat
char cdma_chat_file[] = {
"ABORT 'NO CARRIER'" "\n"
"ABORT 'NO DIALTONE'" "\n"
"ABORT 'ERROR'" "\n"
"ABORT 'NO ANSWER'" "\n"
"ABORT 'BUSY'" "\n"
"TIMEOUT '60'" "\n"
"'' 'ATZ'" "\n"
"'OK' 'ATH0'" "\n"
"'OK' 'ATDT#777'" "\n"
"'CONNECT' ''" "\n"
};
The same as modem ppp, AT start is all module initialization command,
the line before CONNECT is number of PPP dialing：#777
Examples above is all examples of ppp dialing in china mainland, if in
other countries or regions, it will need to configure it again on the basis of
local condition.

When MODEM PPP be used, the communication device is ”

/dev/ttyS1”; When GPRS/CDMA PPP be use, you should call
wnet_getmodinfo to obtain the dial device name(Pppdev)。

wnet_moduleinfo_t modinfo;

memset(&modinfo, 0, sizeof(wnet_moduleinfo_t));
If (wnet_getmodinfo(&modinfo)) {
// 错误处理
}
......
Retval = ppp_open(modinfo.Pppdev, gprs_chat_file, “card”, “card”,
PPP_ALG_PAP, 45);
......
5.14.2. ppp_close

Prototype int ppp_close(const char *devname)

：
Function： close built ppp linking
Parameter: devname device which is used to build ppp linking, for example
modem use ”/dev/ttyS1”
Return： 0 close success, ppp linking will disconnect
-ENETDOWN is not exists ppp linking(do not build ppp linking)
other other error return code
Support： NEW8210
Notes： If the application does not need to use ppp linking any more, you had
better call this function to break ppp linking, to avoid additional
communication costs.

5.14.3. ppp_check

Prototype int ppp_check(const char *devname)

：
Function： check ppp linking state
Parameter: devname device which is used to build ppp linking, for
example modem use ”/dev/ttyS1”
Return： 0 ppp link have been built, can communicate
normally
-PPP_LINK_BUILDING ppp link is being built.
-ENETDOWN is not exists ppp link
other other error return code
Support： NEW8210
Notes：

5.14.4. ppp_set_dns

Prototype int ppp_set_dns(int mode)

：
Function： set a new DNS sever address
Parameter: mode 0 recover the original dns server address
 other set assigned ppp link dns address of current
dns server address
Return： 0
Support： NEW8210
Notes： This function must be called after ppp link is successful built(call it after
have called ppp_check and return 0), after set it all dns will be parsed by
ppp link assigned dns server. If have closed ppp link, developer must call
this function to recover previous dns server address’s configuration.

5.15. GPRS/CDMA

5.15.1. Return Codes

#define WNET_OK (0)

#define WNET_DLOPEN_ERR (-4000)//open libxxx.so err

#define WNET_DLSYM_ERR (-4001)//get function point from libxxx.so err
#define WNET_INIT_ERR (-4002)//wnet init err
#define WNET_NOINIT_ERR (-4003)//wnet do not init
#define WNET_PARAM_ERR (-4004)//param err
#define WNET_GET_OP_ERR (-4005)//get get_operation struct err
#define WNET_NO_FUN_ERR (-4006)//not the function which beed call
#define WNET_POWER_DOWN_ERR (-4007)//went power down err
#define WNET_BEEN_USE_ERR (-4008)//wnet have been userd now
#define WNET_SUSPEND_ERR (-4009)//wnet have been suspend now

//for sim card

#define WNET_SIM_NOINSERT_ERR (-4010)//sim card had not insert
#define WNET_SIM_PIN_ERR (-4011)//sim card pin err
#define WNET_SIM_PUK_ERR (-4012)//sim card puk err

#define WNET_NO_MODULE_ERR (-5000)//not wnet module

#define WNET_RECV_TIMEOUT_ERR (-5001)//receive from wnet timeout
#define WNET_USER_CANCEL_ERR (-5002)//user cancel
#define WNET_RECV_DATA_ERR (-5003)//not used
#define WNET_MOD_RESP_ERR (-5004)//receive data from wnet err
#define WNET_SEND_DATA_ERR (-5005)//send data to wnet err
#define WNET_COMM_OPEN_ERR (-5006)//series port open err
#define WNET_SMS_DIV_ERR (-5007)//not used
//for gprs network
#define WET_DETTACHED_ERR (-5008)// Dettached
#define WNET_ATTACHING_ERR (-5009)// the module is looking for the base
station.
#define WNET_ABNORMAL_ERR (-5010)// abnormal error
#define WNET_CSQWEAK_ERR (-5011)// the signal is too weak, please check the
antenna

//for phone
#define WET_EMERGENCY_ERR (-5012) // SIM/UIM is in emergency status
#define WET_RING_ERR (-5013) // detect ringing
#define WET_BUSY_ERR (-5014) // detect call in progress
#define WET_DIALING_ERR (-5015) // dialing
#define WET_PPP_INVALID_ERR (-5016) // ppp connect disable

//for async function invoke

#define WNET_API_RUNNING (-6001) //have a api running ,do not exec
complete
#define WNET_API_GETTING_DATA (-6002)//last api do not get the retval and output
data , so can not exec cur api(use for request api function)
#define WNET_API_INDEX_ERR (-6003)//the api index is not cur api index or pid
err(use for check api function)
#define WNET_API_MEMORY_ERR (-6004)//memcory err (eg :malloc failed)

5.15.2. Structure

typedef struct{
int arfcn;
int rxlev;
int bsic;
int cell_id;
int lac;
int mnc;
int mcc;
int aiRev[5];
}tBaseStationGPRS;

typedef struct{
int BandClass;
 int Channel;
int SID;
int NID;
int BaseStationPRev;
int PilotPNoffset;
int BaseStationID;
int SlotCycleIndex;
int RawEcIo;
int RxPower;
int TxPower;
int TxAdj;
}tBaseStationCDMA;

typedef struct{
int iFlag; // 1:GPRS, 2:CDMA
union{
tBaseStationGPRS oGprs;
tBaseStationCDMA oCdma;
} Wnet;
}tBaseStation;

typedef struct{
unsigned char byLength; // number length
unsigned char byType; // type,0x91:international, 0x81:Inland
unsigned char abyNumber[30]; // number content
}tTelInfo;

typedef struct{
char strSca[64]; // server central tel number
char strDstAddr[64]; // Destination address
unsigned char byPid; // Protocol ID, the default value is 0x00
unsigned char byDcs; // Decord Standard
unsigned char byUniqueID; // Decord Standard
unsigned char byTpVp; // SMS Validity Period
unsigned char abyPduType[MAX_SMS_NUMBER]; // PDU type
int aiContentLength[MAX_SMS_NUMBER]; // the length of sms content
int aiCompressLength[MAX_SMS_NUMBER]; // the length of sms content
char strContentData[MAX_SMS_NUMBER*PDU_SMS_CONTENT_LENGTH]; //
the content of sms
unsigned char abyRev[24]; //
}tPduSmsSend;
typedef struct{
int index; // the index in the sms memory
char strScts[16]; // the time of sms server, like "12032718250032" --- 2012-03-27
18:25:00 32
char strSca[64]; // server central tel number
char strOa[64]; // Orient address
unsigned char byStatus; // 0:"REC UNREAD", 1:"REC READ", 2:"STO UNSENT",
3:"STO SENT", 4:"ALL"
unsigned char byPduType; // PDU type
unsigned char byPid; // Protocol ID
unsigned char byDcs; // Decord Standard
int iContentLength; // the length of sms content
char strContentData[336]; // the content of sms
}tPduSmsRecv;

typedef struct{
int index; // the index in the sms memory
unsigned char abyTime[8]; // the time of sms server, format:YYMMDDHHMMSSZZ, ZZ
is zone
// like "\x12\x03\x27\x18\x25\x00\x32\x00" --- 2012-03-27 18:25:00 32
tTelInfo oSca; // server central tel number
tTelInfo oOa; // Orient address
// Such as "\x05\x10\x08\x6F"---->"10086"
// Such as "\x0d\x86\x18\x92\x84\x84\x80\x8f"---->"8618928484808"
unsigned char byStatus; // 0:"REC UNREAD", 1:"REC READ", 2:"STO UNSENT",
3:"STO SENT", 4:"ALL"
unsigned char byCurItem; // From 0 to TotalNum-1
unsigned char byTotalNum; // TotalNum >= 1
unsigned char byDecodeStandard;// 0x00:ASCII; 0x08:UCS2(UNICODE 16); 0x04:Hex
data
int iSmsLength; // the length of sms content
unsigned char abyUniqueID[2]; // SMS unique ID
char stSmsData[170]; // the content of sms
}tSmsRecv; // 256 bytes

typedef struct{
tTelInfo oSca; // server central tel number
tTelInfo oDstAddr;
int iSmsLength; // the length of sms content
unsigned char abySmsData[3080]; // the content of sms
// ASCII Maxin length 3060 bytes
 // UCS2 Maxin length 2680 bytes
// Hex Maxin length 2680 bytes

unsigned char byTpVp; // SMS Validity Period

/* TP-VP value Validity period value
0x00 to 0x8f (TP-VP + 0x01) * 0x05 minutes (i.e. 5 minutes intervals up to 12
hours)
0x90 to 0xa7 0x0c hours + ((TP-VP - 0x8f) * 0x1e minutes)
0xa8 to 0xc4 (TP-VP - 0xa6) * 0x01 day
0xc5 to 0xff (TP-VP - 0xc0) * 0x01 week */

unsigned char byDecodeStandard; // 0x00:ASCII, 0x08:UCS2(UNICODE 16),

0x04:Hex data
unsigned char byStausReport; // 1:need report send status, 0:not need report send
status
unsigned char abyRev[21]; //
}tSmsSend; //

5.15.3. wnet_power_on

Prototype int wnet_power_on(void)

：
Function： Power on the GPRS/CDMA modle
Input None
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes： Must call this api to power on the model before wnet_init.

5.15.4. wnet_power_down

Prototype int wnet_power_down(void)

：
Function： Power off the model
Input None
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes： Power off the model，must call wnet_power_on to power on the model and
call wnet_init to initialize the model before use it.

5.15.5. wnet_init

Prototype int wnet_init(const char *comm_dev)

：
Function： Initialize the model, detect wireless model type automatically
Input comm_dev Device file name ”/var/mux0”
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes： There are 4 logic devices valid, with name ”/var/mux0~3”.
Note:The wnet_init() input device name will be not same as the
ppp_open() input device name.

5.15.6. wnet_reset

Prototype int wnet_reset(void)

：
Function： Reset the wireless model
Input None
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes： After this API called, the module perform a physical reset, the PPP linking
and configures are all invalid, the module is in factory state, before next
using, wnet_init will be needed.
5.15.7. wnet_set_attached

Prototype int wnet_set_attached(int flag)

：
Function： Query and configure the network attachment / detachment operation
Input flag 0-set detachment;1-set attachment
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes： Network detached or attached depends on the parameter “flag”. need to call the
function until the return success to ensure that the network is attached/detached
correctly.

5.15.8. wnet_signal

Prototype int wnet_signal(int *signal_num)

：
Function： Query the signal strength.
Input NONE
Parameter:
Output signal_num Return the wireless signal strength
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes： The valid signal value is 0~31, the 99 is an invalid signal value.

5.15.9. wnet_checksim

Prototype int wnet_checksim(void)

：
Function： Check whether the SIM card in slot or not
Input None
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes：

5.15.10. wnet_getimei

Prototype int wnet_getimei(char *IMEI)

：
Function： Get wireless model IMEI
Input None
Parameter:
Output IMEI Return IMEI
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes：

5.15.11. wnet_getmodinfo

Prototype int wnet_getmodinfo(wnet_moduleinfo_t *info)

：
Function： Get wireless model information
Input None
Parameter:
Output info Information of the wireless model
Parameter: typedef struct
{
char Type; //Wireless model type
char Name[64]; //Name
char Manufacturer[64];// Manufacture
char Ver[64]; // Version number
char Reserv[256];//Reserve
}wnet_moduleinfo_t;
Return： Refer 5.15.1 Return Codes
Support: NEW8210
Notes： Get the information of the wireless model
5.15.12. wnet_sms_getlist

Prototype: int wnet_sms_getlist(int listtype, tSmsRecv sms[], int maxno, int

*SmsNum)
Function: Read SMS list
Input listtype SMS 0 NEW SMS
Parameter: Type： 1 READED SMS
2 SMS NO SENT (Not Support)
3 SMS SENT (Not Support)
4 ALL SMS
maxno Max number of SMS items
Output sms SMS message buffer
Parameter: SmsNum Actual read SMS items
Return: Refer 5.15.1 Return Codes
Support: NEW8210
Notes:

5.15.13. wnet_sms_send

Prototype： int wnet_sms_send(const tSmsSend *sms)

Function： Send a SMS
Input sms Message
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes：

5.15.14. wnet_sms_read

Prototype： int wnet_sms_read(int index, tSmsRecv *smsdata)

Function： Read a SMS
Input index Index of the SMS
Parameter:
Output sms Message buffer
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes：

5.15.15. wnet_sms_delete

Prototype int wnet_sms_delete(int index)

：
Function： Delete a SMS
Input index Index of the SMS to delete
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes：

5.15.16. wnet_phone_status

Prototype： int wnet_phone_status(char * PhoneNumber, unsigned int uiBuffSize)

Function： Get phone status
Input uiBuffSize Buffer size
Parameter:
Output PhoneNumb Receive calling phone number.
Parameter: er
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes： If in calling, will get the calling phone number.

5.15.17. wnet_phone_answer

Prototype int wnet_phone_answer(void)

：
Function： Answer call
Input None
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes：

5.15.18. wnet_phone_hangup

Prototype int wnet_phone_hangup(void)

：
Function： Hangup
Input None
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes：

5.15.19. wnet_phone_call

Prototype int wnet_phone_call(unsigned char *PhoneNum)

：
Function： Call a phone
Input PhoneNum Phone number
Parameter:
Output None
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes：
5.15.20. wnet_get_basestation_info

Prototype： int wnet_get_basestation_info(tBaseStation *psBaseStationInfo)

Function： Get basestation information
Input None
Parameter:
Output psBaseStationInf Base station information
Parameter: o
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes： If the return value is success, it will get the right base station info.

5.15.21. wnet_get_neighbourbasestation_info

Prototype： int wnet_get_neighbourbasestation_info(tBaseStation

*psBaseStationInfo, int iNum, int *piOutNum)
Function： Get neighbour base station information
Input iNum Max base station count
Parameter:
Output psBaseStationInf Base station information
Parameter: o
Return： piOutNum Returned base station information counts
Support： Refer 5.15.1 Return Codes
Notes： NEW8210

5.15.22. wnet_read_simcardID

Prototype int wnet_read_simcardID(char *psSimCardID, int iLen)

：
Function： Read ID from SIM Card
Input iLen Buffer size
Parameter:
Output psSimCardID Buffer to save SIM Card ID
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes：

5.15.23. wnet_read_simcardIMSI

Prototype int wnet_read_simcardIMSI(char *IMSI, int iLen)

：
Function： Read IMSI from SIM Card (International Mobile Subscriber Identity)
Input iLen Buffer size
Parameter:
Output IMSI Buffer to save IMSI of SIM Card
Parameter:
Return： Refer 5.15.1 Return Codes
Support： NEW8210
Notes：

5.15.24. wnet_get_current_sim

Prototype int wnet_get_current_sim(void)

：
Function： Get the number of current SIM card that used.
Input None
Parameter:
Output None
Parameter:
Return： 0 SIM 1
1 SIM 2
others Refer 5.15.1 Return Codes
Support： NEW8210
Notes： Before select another SIM card, the default selection is 0 (SIM 1)

5.15.25. wnet_select_sim

Prototype int wnet_select_sim(int simno)

：
 Function： Change the SIM card that currently used.
Input simno The number of SIM, range: [0, 1]
Parameter:
Output None
Parameter:
Return： 0 Successfully
others Refer 5.15.1 Return Codes
Support： NEW8210
Notes： Before call this function, the wireless module must be “power down”
status, otherwise this function will return WNET_POWER_DOWN_ERR.
For example:

int simno;
……
simno = wnet_get_current_sim();
if (simno < 0)
report_error();
else {
simno ^= 1;
wnet_power_down();
if (wnet_select_sim(simno))
report_error();
}
……

Notice: If the terminal is not the Dual-SIM version, call this function has no
effect, it always operate the same SIM card.

5.16. Barcode scan

Barcode scanner, can scan a corresponding one-dimensional / two-dimensional bar

code.

5.16.1. bar_open

Prototype: int bar_open(const char *pathname, int oflags)

Function: Open the barcode scanner device, get the handle.
Parameter: pathname(Input The device name of scanner, such as
) ”/dev/ttyS2”(NEW8210) or “/dev/bar0” (NEW8110)
oflags(Input) Open mode O_RDONLY Read only (required)
O_NONBLOCK non-blocking
(optional)
Return: >=0 Open successfully, the code is the handle which is
used for the subsequent operation.
<0 Open failed. Refer to <errno.h>
Be NEW8210
Applicable
In:
Notes:  This function is same as the open of POSIX. The difference is this
function can not use create file mode. So there are only 2 parameters
in this function.
 oflag can be set to O_RDONLY or (O_RDONLY | O_NONBLOCK)
 If oflag is set to O_RDONLY, bar_read will keep waiting until read
successfully.
 If olfag is set to (O_RDONLY | O_NONBLOCK), bar_read only check
the receive buffer in the background.
Example: Example 1:
int fd;
if ((fd = bar_open(“/dev/ttyS2”, O_RDONLY)) < 0) {
// error
}

Example 2:
if ((fd = bar_open(“/dev/ttyS2”, O_RDONLY | O_NONBLOCK)) < 0) {
// error
}

5.16.2. bar_close

Prototype: int bar_close(int fd)

Function: Close the barcode scanner device.
Parameter: fd(Input) The handle of scanner which is get from bar_open.
Return: 0 Close scanner device successfully.
others Close failed. Refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: This function is same as the close of POSIX.
Example:

5.16.3. bar_scan

Prototype: ssize_t bar_scan(int fd, uint32_t onoff)

Function: Start/Stop scan.
Parameter: fd(Input) The handle of scanner which is get from bar_open.
onoff(Input) 0 stop scanning
non-zero start to scan
Return: 0 Successfully.
non-zero Failed. Refer to <errno.h>.
Be NEW8210
Applicable
In:
Notes: If start to scan, you can call Bar_scan, and the onoff is non-zero.
If stop scanning, you can call Bar_scan, and the onoff is zero.
It returns immediately after calling this function of bar_scan.
Example:

5.16.4. bar_read

Prototype: ssize_t bar_read(int fd, void *buf, size_t nbytes)

Function: Receive barcode data after scanning
Parameter: fd(Input) The handle of scanner which is get from bar_open.
buf(Output) The given buffer to store the received data
nbytes(Input) The expected receive byte length
Return: >=0 The actual received byte length
<0 Failed. Refer to <errno.h>.
Be NEW8210
Applicable
In:
Notes: This function is same as the read of POSIX.
If the scanner is opened by O_RDONLY, this function will not return until a
barcode data are received finished.
If the scanner is opened by (O_RDONLY | O_NONBLOCK), this function
will return immediately.
Example:

5.16.5. bar_read_timeout

Prototype: ssize_t bar_read_timeout(int fd, void *buf, size_t nbytes,

uint32_t timeoutms)
Function: Receive barcode with specified timeout.
Parameter: fd(Input) The handle of scanner which is get from bar_open.
buf(Output) The given buffer to store the received data
nbytes(Input) The expected receive byte length
timeoutms(Input Timeout (unit: ms)
)
Return: >=0 The actual received byte length
<0 Failed. Refer to <errno.h>.
Be NEW8210
Applicable
In:
Notes: This function is same as bar_read except the timeout can be specified.
This function will return before timeout even if the scanner is opened by
blocking mode (O_RDONLY). Before timeout, this function will try to
receive the expected data length from the scanner buffer; If the expected
length of data is received complete, the function returns.
Example:

5.17. VPDN

API functions of this module was defined in the “vpdn.h”; “libvpdn.so” must be used when
linking.
typedef enum {
VPDN_NO_ERROR, /* vpdn dial successfully，connection to server is established
*/
VPDN_IS_CONNECTING, /* vpdn dial is on the way */
VPDN_IS_DISCONNECTED, /* vpdn connection to server is disconnected */
VPDN_ERROR, /* other error */
VPDN_CERT_FILE_UNAVAILABLE, /* vpdn certification file is unavailable */
VPDN_NO_DEFAULT_ROUTE, /* no default route to vpdn server */
} RESULT_ERROR_ENUM;

5.17.1. vpdn_open

Prototype: int vpdn_open(int debug_mode)

Function: Prefare to vpdn dial
Parameter: debug_mode 0 Normal mode
(input) other Let vpdn library run in debug mode
Return: 0 OK
other Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: This API will create a channel to vpdn manager process, the one you
send command to later.
This API must be called before calling any other interface.
Example:

5.17.2. vpdn_close

Prototype: int vpdn_close(void)

Function: Delete the channel to vpdn manager process
Parameter: None
Return: 0 OK
other Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: This API will delete the channel to vpdn manager process. But it does
not disconnect the connection to remote vpdn server. If you wanna
disconnect the connection to remote vpdn server, ‘vpdn_disconnect’
must be called before vpdn_close.
Example:

5.17.3. vpdn_call_pptp

Prototype: int vpdn_call_pptp(const pptp_arg_t *arg, result_notify_func_t func)

Function: vpdn dial-up with PPTP
Parameter: arg You need to special some argument to make pptp runing.

typedef struct {

struct in_addr server; /* vpdn server ip address */

char domain[32]; /* domain may be need if the vpdn server is a

windows OS. Else let it blank*/

char username[64]; /* special the username */

char password[32]; /* secret for the username */

int encrypt; /* TRUE for ms-chapv2 & mppe-128, Otherwise no

encryption。Generally you shoud set to TRUE。*/

} pptp_arg_t;

func The function which will be called when the dialing result is sent back by

vpdn manager process.

Prototype: typedef void (*result_notify_func_t)(result_arg_t *arg);

typedef struct {

int error; /* VPDN_NO_ERROR means OK. See

RESULT_ERROR_ENUM for detail (locate at 239) */

char intf_name[64]; /* vpdn interface name，for example, ppp1 */

int ifindex; /* vpdn interface index, you may use it in socket */

int intf_is_up; /* vpdn interface status ，TRUE for up, FALSE for

down */

} result_arg_t;

Return: 0 OK
other Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: The result_notify_func will be call again if vpdn dial connection is
disconnected or the status of vpdn interface is changed.
There must be a default route to vpdn server before dialing vpdn. A
default route may be generate by ethernet or GPRS, but no China
Mobile’s GPRS network.
Default route will be changed to vpdn network after dialing vpdn
successfully.
Example:

5.17.4. vpdn_call_l2tp_psk

Prototype: int vpdn_call_l2tp_psk(const l2tp_psk_arg_t *arg, result_notify_func_t

func)
Function: Use L2TP with pre-shared key to dial vpdn
Parameter: arg You need to special l2tp_psk_arg_t to call:

typedef struct {
 struct in_addr server; /* vpdn server ip address */

char domain[32]; /* domain may be need if the vpdn server is a

windows OS. Else let it blank */

char username[64]; /* special the username */

char password[32]; /* secret for the username */

char ipsec_psk_secret[32]; /* IPSec Pre-Shared key*/

} l2tp_psk_arg_t;

func The function which will be called when the dialing

result is sent back by vpdn manager process.
Usage for the function is descripted in
vpdn_call_pptp(locate at 240)
Return: 0 OK
other Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: PSK: Pre-Shared Key, is an encryption of IPSec。There is no encryption
in L2TP，it needs IPSec to encrypt the transfer data.
The result_notify_func will be call again if vpdn dial connection is
disconnected or the status of vpdn interface is changed.
There must be a default route to vpdn server before dialing vpdn. A
default route may be generate by ethernet or GPRS.
Default route will be changed to vpdn network after vpdn connection
established.
Example:

5.17.5. vpdn_call_l2tp_cert

Prototype: int vpdn_call_l2tp_cert(const l2tp_cert_arg_t *arg, result_notify_func_t

func)
Function: Use L2TP with certificates to dial vpdn
Parameter: arg typedef struct {

struct in_addr server; /* vpdn server ip address */

char domain[32]; /* domain may be need if the vpdn server is a windows OS.

Else let it blank */

char username[64]; /* special the username */

char password[32]; /* secret for the username */

char cert_path[128]; /* Directory which include this files:

1) cacert.pem

2) vpnclient_cert.pem, vpnclient_key.pem,

3) vpngateway_cert.pem, vpngateway_key.pem */

char cert_client_pw[32]; /* secret for the vpnclient_cert.pem */

 char cert_server_pw[32]; /* secret for the vpngateway_cert.pem */

} l2tp_cert_arg_t;

func The function which will be called when the dialing result is
sent back by vpdn manager process.
Usage for the function is descripted in vpdn_call_pptp(locate
at 240)
Return: 0 OK
other Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: IPSec certificate encryption has a Official name X.509. Sometimes it is
called RSA. Actually X.509 is based on RSA.
The user need to offer root CA, local CA and server CA ， see
l2tp_cert_arg_t for detail.
The result_notify_func will be call again if vpdn dial connection is
disconnected or the status of vpdn interface is changed.
There must be a default route to vpdn server before dialing vpdn. A
default route may be generate by ethernet or GPRS.
Default route will be changed to vpdn network after dialing vpdn
successfully.
Example:

5.17.6. vpdn_disconnect

Prototype: int vpdn_disconnect(result_notify_func_t func)

Function: Disconnect vpdn to the remote server
Parameter: func The function which will be called when the dialing result is
sent back by vpdn manager process.
Usage for the function is descripted in
vpdn_call_pptp(locate at 240)
Return: 0 OK
other Failed, refer to <errno.h>
Be NEW8210
Applicable
In:
Notes: Disconect all kind of vpdn connection established by pptp, l2tp/ipsec psk
and l2tp/ipsec cert.
The default route to vpdn network is deleted, and the old default route is
recovered.
Example:
6. Uart

Uart device file name: /dev/ttyS3

6.1. tty_property_config

Prototype: int tty_property_config(int fd, int baudrate, int databits, int parity, int
stopbits, int flow)
Function: Uart parameter setting
Parameter: ifd Uart file handle
baudrate Baud rate
databits Bits
parity Parity
stopbits Stop bits
flow flow
Return：
Support: NEW8210/NEW8110P
Notes:

7. Network Program

Socket TCP/IP
Please refer linux network program documents
ssl
Please refer openssl documents.

8. File Access

Please refer linux c/c++ documents.