You are on page 1of 245

NEW8210 EFT-POS

APPLICATION DEVELOPMENT
MANUAL

V 0.1.2

Author: Harrison
Approved:

Date: 2013-12-03
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


file

Harrison Lee

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;


Add two system API.

Alex Chen

2013-07-17

0.0.6

Add figure 4.5.5 and revised


some mis-spell.

Ryan Huang

2013-09-26

0.0.7

Revised the WNET API

Kent Song

2013-10-21

0.0.8

Add API for obtain information of


battery
Add API for VPDN module
Add API for control the power of
modem
Modify
the
structure
of
ModemDialParms_t

Henry Li

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


Add description for return value
of ppp module

Henry Li

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


magstripe_set_trackset,
magstripe_get_trackset.
Delete magstripe_reset

Henry Li

2. General Introduction
NEW8210 is a mobile POS terminal, base on Linux OS by New Pos Technology
Limited, its development platform is Linux OS, please download the latest SDK,
firmware, DownloadTool and related documents from the server:
ftp://customer:loadsoftware@121.15.134.230/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 dont 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 dont offer SDK on Windows platform, so you cant 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
generic

--target=arm-unknown-linux-gnu

--prefix=/opt/compiler/glibc-oabi-toolchain-arm-

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

languages=c,c++,java,objc,obj-c++

--disable-multilib

--with-float=soft

--enable-

--with-pkgversion='<lihua_338@163.com>'

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

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

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

--disable-nls

--with-local--enable-

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

Thread model: posix

gcc version 4.3.4 (<lihua_338@163.com>)

Because this toolchain uses a high grade version of GCC toolchain, it needs
dynamic library mpfr-2.4.2, if your Linux system havent the dynamic library, or havent
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-oabitoolchain-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=i686build_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

--enable-libgomp

--with-float=soft
--enable-libssp

--with-pkgversion=lihua_338@163.com

--enable-__cxa_atexit

--enable-libmudflap

--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 (lihua_338@163.com)

4.4. Install Eclipse for Windows


1.

2.
3.

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.
Unzip Eclipse
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 windowss 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-armgeneric
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


dont 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
dont 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-functiondeclaration -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 -mlittleendian -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 sides 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 doesnt use assembly language, so it is not need to configure.

4.5.5.

4.5.5.1.

Compile configure way 2

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
dont 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
dont 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-functiondeclaration -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 -mlittleendian -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 sides Command to :
$(GCCPATH)gcc

Here is used to configure compile options which is used when compiling assembly
file, usually application doesnt 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. translateDISK-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, users application can run by this launcher,
it need developer to write a launch configuration, and add it to current users 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 applications current path is:
/home/user0/NEW8210demo
(Path=/home/user0/NEW8210demo).
The program doesnt 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 systems 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 files line feed 0d 0a to 0d, there havent 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, dont 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 doesnt 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 PCs IP is 192.168.1.100, NEW8210s 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 NEW8210s console: use ssh to login
to NEW8210 from host PC, execute command below:
ssh user0@192.168.1.200
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-unknownlinux-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
NEW8210s IP address to Host name of IP address, configure Port number to
2331(when run gdbserver command on NEW8210 above, wo choose gdbservers
listening port of 2331, make sure that gdbservers 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 dont 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


NEW8210s 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:
[ 117.620000] CPU: 0
[ 117.620000] PC
[ 117.620000] LR

DemoApp

Not tainted (2.6.27.45-NEW8210 #3)

is at 0x8440
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 isnt 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 registers value when exception
happening have been printed(R0R10SPIPFPSPSRLRPC) , 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
DemoApp > DemoApp.asm

-D

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:
8444:
8448:
844c:
8450:
8454:

e5823000
e51b3010
e5933000
e1a00003
e99da800
12345678

str r3, [r2]


ldr r3, [fp, #-16]
ldr r3, [r3]
mov r0, r3
ldmib
sp, {fp, sp, pc}
.word
0x12345678

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

set R3 to 0
8430: e3a03000
mov r3, #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 dont 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 disassemblycommand which is to disassembled is below:
/opt/compiler/glibc-oabi-toolchain-arm-generic/bin/arm-unknown-linux-gnu-objdump
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
8434: e50b3010

mov r3, #0 ; 0x0


str r3, [fp, #-16]

-DS

*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
8448: e5933000

ldr r3, [fp, #-16]


ldr r3, [r3]

844c: e1a00003
8450: e99da800
8454: 12345678

mov r0, r3
ldmib
sp, {fp, sp, pc}
.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 cant 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
/dev/samcard?

User card
?=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
input
parameter

beep_enable

Enable/Disable buzzer when pressing


or not: 1: enable, 0: disable

beep_freq

The frequency of buzzer (unit: Hz)

beep_time

Buzzer duration
0~100ms)

time

(unit:

ms,

Return

Support

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.

Set OK.

-EINVAL

input parameter error

others

other error code

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

Return

pset

beep_enable

Enable/disable buzzer ringing when


pressing keypad
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

output
parameter

Set OK.

Be
Applicable
in

-EINVAL

input parameter error

others

other error code

NEW8210

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

minutescope059

tm_hour

hourscope023

tm_mday

dayscope131day begin from


1

tm_mon

monthscope011month begin
from 0

tm_year

yearscopetime offset from 1900

Return

Setting success

-EINVAL

Input parameter error

others

Other error code

Support

NEW8210

Notes

Call this function to set systems 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

Function:
Parameter:
Return:

int sys_get_status_bar_height(void);
Get height of the status bar

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:

Support:

NEW8210

Success

Notes:

5.1.8.

sys_suspend_now

Prototype:

int sys_suspend_now(void)

Function:

System suspend immediately

Parameter:

None

Return:

Support:

NEW8210

Success

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 buzzer6420000Hz

keepms

Continuous ringing keepmsunitms

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

keepunitsecond

>0

Backlight is turned off


automatically
when
the
number of keep seconds
expires

=0

no backlight

<0

Backlight always on

Return

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


second

Configuration of current backlight will


save at this value

Set OK

Return

-EINVAL

Input parameter error, keep is null

others

Other error code

Be
application
in

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.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.

>= 0

The number
information

-EINVAL

input parameter error

others

other error code

Return

of

real

output

module

Support

NEW8210

Notes

This function is used to obtain terminals module information, store


getting information in the structure of config, module name is shown:
Module name

Module information

Terminal

Terminal nameNEW8210

Printer

Printer type

Modem

maximum
rate
synchronous/asynchronous
communication

PCI

None

USB host

USB
interfaceUSB2.0

USB device

None

Ethernet

None

WIFI

None

GPRS

None

CDMA

None

NFC

None

of

standard

5.1.14. led_get_brightness
Prototype

Function:
Parameter:

Return:

Be
applicable
in:
Notes

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


Get the brightness of led light
led_name

led name

brightness
(output parameter)

Led brightness scope 0 255 0


darkest255 lightest

Set OK

-EINVAL

Input parameter error

others

Other error code

NEW8210

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 powericon 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


darkest255 brightest

Set OK

-EINVAL

Input parameter error

Others

Other error code

Return

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.

Successful.

others

Failed, please refer to <errno.h>.

Return
Support

NEW8210

Notes

Hardware modules(the parameter of module) as shown below:


Hardware module

5.1.17.

comment

HARDWARE_MACHINE

Terminal Namee.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

sys_software_update

Prototype

int sys_software_update(const char *filename)

Function

Used to update the file of specified path (filename).

Parameter

filenameinput

The full path name of file that need to be


updated.

Successful.

others

Failed, please refer to <errno.h>.

Return

Be
application
in

NEW8210

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
(Output)

status

0-Battery-powered
1-Charging
2-Full charge
3-External-powered

Return
Be
application
in
Notes:

cur_values

Current voltage

max_values

Maximum voltage

min_values

Minimum voltage

percent

Percent of battery life

Successful

others

Failed, please refer to <errno.h>.

NEW8210

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 NEW8210s keys and PC-101s keys is listed as follow:
NEW8210
key

PC-101
key

Code

Symbol

KEY_0

0x0B

DIKS_0

0x30

KEY_1

0x02

DIKS_1

0x31

KEY_2

0x03

DIKS_2

0x32

KEY_3

0x04

DIKS_3

0x33

KEY_4

0x05

DIKS_4

0x34

KEY_5

0x06

DIKS_5

0x35

KEY_6

0x07

DIKS_6

0x36

KEY_7

0x08

DIKS_7

0x37

KEY_8

0x09

DIKS_8

0x38

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 cant 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 printers 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/SessionfixedDUKPT 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

Function
Parameter:

Return

int ped_get_random_nr(uint32_t bytes, void *data)


Get random number from PED
bytes

Bytes, less than 128kb

data output

Buffer to receive the random numbers.

Success

-1
Support:

Error. The error code please gets from the global


variable errno.

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:

width

Width

height

Height

success

-1

Error. The error code please gets from the global


variable errno.

Return

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

Support

Success

-1

Error. The error code please gets from the global variable
errno.

NEW8210

Notes

5.4.5.

ped_clear_user_keys

Prototype

int ped_clear_user_keys(void)

Function

Clear current users (or current application) PED keys.

Parameter

None

Return

Support

Success

-1

Error. The error code please gets from the global


variable errno.

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

Support

Success

-1

Error. The error code please get from the global variable
errno.

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

Return

>=0

Support

NEW8210

The time interval


between twice pin
input operation.

The remain time.

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

Return

Support

>120

Invalid input value.

30~120

Valid input value

Set the default timeout value 60 seconds.

<30

Invalid input value.

Success

-1

Error. The error code please get from the global variable
errno.

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 015

Ksn(Output)

Get 10 bytes of KSN value

Return

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 keys ID, 0...1023.

PinKeyID

The PIN keys ID, 0...1023.

PinKeyLen

Length of PinKey, 16 or 24.

PinKey

This parameter will be filled the current PIN key


ciphertext data.

Success

-1

Error. The error code please gets from the global


variable errno.

Return

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

Return

TDEA_DECRYPT

Encrypted KeyData

KEY_VERIFY_NONE

No check value

KEY_VERIFY_KVC

KVC

KEY_VERIFY_CMAC

CMAC

MasterKeyID

Master key Indexvalue 0...1023.

DestKeyID

PIN Key indexvalue 0...1023.

KeyLen

KeyData length
PIN Key data length
+Checkdata lengthKVCCMAC is 4 bytes

KeyData

Plaintext/Encipher PIN Key + Check data

Success

-1

Error. The error code please gets from the global


variable errno.

Support

NEW8210

Notes

The PIN key is encrypted by MasterKey, the Modeshould be


TDEA_DECRYPT
arithmetic
or
with
one
of
KEY_VERIFY_NONEKEY_VERIFY_KVCKEY_VERIFY_CMAC;

The PIN key cannot be cipher text, so the Modeshould not be


TDEA_NONE;
If with KVC check value, the KeyLen should be 8n + 4 n=1: single
DESn=2: double DESn=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 MasterkeyValue 0...1023.

MacKeyID

MAC Key IndexValue 0...1023.

MacKeyLen

MAC Key length, 16 or 24

MacKey

Encipher Mac key value

Return

Support

Success

-1

Error. The error code please gets from the global variable
errno.

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 indexvalue 0...1023.

DestKeyID

MAC key indexvalue 0...1023.

Return

KeyLen

KeyData Length Key data length +Check Code


LengthKVCCMAC is 4 bytes

KeyData

Plaintext /Encipher Key Value + Check Code

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_NONEKEY_VERIFY_KVCKEY_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 8n + 4 n=1:
single DESn=2: double DESn=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

Return

TDEA_DECRYPT

KeyData is encrypted

KEY_VERIFY_NONE

No check code

KEY_VERIFY_KVC

KVC

KEY_VERIFY_CMAC

CMAC

MasterKeyID

Master key indexvalue 0...1023.

DestKeyID

Master Key IndexValue 0...1023.

KeyLen

KeyData Length Key data length +Check Code


LengthKVCCMAC is 4 bytes

KeyData

Plaintext /Encipher Key Value + Check Code

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_NONEKEY_VERIFY_KVCKEY_VERIFY_CMAC;
If the MasterKey is plaintext, then the Mode should be
TDEA_NONE;
If with KVC check value, the KeyLen should be 8n + 4 n=1:
single DESn=2: double DESn=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 IndexValue 0...1023.

PinKeyLen

PIN key length, 16 or 24

PinKey

Plaintext PIN Key

Return
Support

Success

-1

Error. The error code please get from the global variable errno.

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 indexvalue 0...1023.

MacKeyLen

MAC Key Length, 16 or 24

MacKey

Plaintext MAC key value.

Return
Support

Success

-1

Error. The error code please get from the global variable errno.

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 015

InitKey

Initialize key 16 bytes

KeyLen

Key length16

Ksn

10 bytes KSN

Return
Support

Success

-1

Error. The error code please get from the global variable errno.

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, 01023.

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.

Return

Mode

PIN_BLOCK_FORMAT_0
/PIN_BLOCK_FORMAT_EPS

PinBlock

The PIN BLOCK result, 8 bytes.

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.

Return

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.

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]
Return

The PIN BLOCK result.

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: CLAINSP1P2LC

rsplen

rspdata length.

rspdata

Card respond code


(Two byte returned code: SWASWA)

Return

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

P/
F

P/
F

P/
F

P/
F

P/
F

P/
F

P/
F

P/
F

Name

Value

Control field

4 bit binary 0010(hex. 2)

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

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

Return

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: CLAINSP1P2LC

Rsplen[output]

rspdata length.

Rspdata[output]

Card respond code


(Two byte returned code: SWASWA)

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

0x7F

PIN BLOCK

PINBLOCK

Random form IC card

RSA_PINKEY supplies the data


from IC card

Padding data

NIC
17

RSA_PINKEY supplies padding


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


DataLen, const void *DataIn, void *MacOut)

Function

Compute the input datas 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

Support

Mode,

uint32_t

Success

-1

Error. The error code please get from the global variable
errno.

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 datas 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
Return

Support

The MAC result, 8 bytes.

Success

-1

Error. The error code please get from the global variable
errno.

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 datas 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

Support

Success

-1

Error. The error code please get from the global variable
errno.

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
Return

Plaintext key value

0 Success
1

Error. The error code please get from the global variable
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.

Success

-1

Error. Please get the error code from the global


variable errno.

Return

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
0x01master key
0x02MAC key
0x03PIN key
0x10Fixed MAC key
0x11Fixed 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_

5.5.3.

EPP_CFG;

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/ttyS4or/dev/ttyS6

oflag

parameter can only be O_RDWR

Return

NULL

error return

other

EPP port parameter handle

Be
applicable

NEW7110

in
Notes

5.5.4.

epp_close

Prototype

int epp_close(EPP_CFG *cfg)

Function

close opened N20 device

Parameter

cfginput

Return

please refer to section 4.12.1

EPP device handle which is opened by epp_open

Be
applicable
in

NEW7110

Notes

after close, EPP port parameter handle cfg will be invalid and can not
use again

5.5.5.
Prototype

Function

Parameter:

epp_init
int epp_init(EPP_CFG *cfg, const EppAuthKey_t *eppkey)
Modify current key configure.
1if use default configure, do not need to call this interface
2 if dont use default configure, initial configuration each time when
starting device
cfginput

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
applicable

NEW7110

in
Notes

5.5.6.
Prototype

Function

epp_download_lck_mtek
int epp_download_lck_mtek(EPP_CFG *cfg)
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:

cfginput

EPP device handle which is opened by epp_open

Return

please refer to section 4.12.1

Be
applicable
in

NEW7110

Notes

5.5.7.
Prototype

Function

epp_download_aik
int epp_download_aik(EPP_CFG *cfg)
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:

cfginput

EPP device handle which is opened by epp_open

Return

please refer to section 4.12.1

Be
applicable
in

NEW7110

Notes

5.5.8.
Prototype

epp_download_appkey
int epp_download_appkey(EPP_CFG
*appkey)

*cfg,

const

EppAppKey_t

Function

Inject one application key into external N20 PINPAD.

Parameter:

cfginput

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
applicable
in

NEW7110

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
x

Key index, no use currently. Key index just binding to


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
applicable
in

NEW7110

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

KeyType

Parameter:

EPP device handle which is opened by epp_open


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.

pMacOu

8 bytes MAC result, If the key type is DUKPT_MAC_KEY,


this parameter will output 8 bytes MAC result and 10 bytes
current KSN.

output
Return

please refer to section 4.12.1

Be
applicable
in

NEW7110

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:

cfginput

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.

Return

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


KSN,this parameter is valid just to DUKPT.

output
please refer to section 4.12.1

Be
applicable
in

NEW7110

Notes

Notes
(1) ANSI X3.92 standard is belowFormat 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 string1s BCD code and string2s 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:

cfginp
ut

EPP device handle which is opened by epp_open

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
e

Key type
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
x

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.

pDataIn

Compute data.

DataLe
n

data length, for 1*8 to 12*8.

pDataO
ut out
put

Compute result, the length is the same as input data.

Return

please refer to section 4.12.1

Be
applicable

NEW7110

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
applicable
in

NEW7110

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
ut

EPP device handle which is opened by epp_open

pIvData

8 bytes input vector.

Return

please refer to section 4.12.1

Be
applicable
in

NEW7110

Notes

Call this interface to set initial vector will effect CBC algorithms 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

Return
Be
applicable
in

output
please refer to section 4.12.1
NEW7110

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:

cfginput

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
applicable
in

NEW7110

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:

cfginput

Return

please refer to section 4.12.1

Be
applicable
in

NEW7110

EPP device handle which is opened by epp_open

Notes

5.5.18. epp_format_ped
Prototype

Function

int epp_format_ped(EPP_CFG *cfg)


Format the N20 PINPAD, include clear all key and restore the default
configure.

Parameter:

cfginput

EPP device handle which is opened by epp_open

Return

please refer to section 4.12.1

Be
applicable
in

NEW7110

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:

cfginput

EPP device handle which is opened by epp_open

pBmpIdleLogo
In

Data content of monochrome BMP file.The N20


EPPs LCD resolving is 122*32.

Return

please refer to section 4.12.1

Be
applicable
in

NEW7110

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:

cfginput

Return

please refer to section 4.12.1

Be
applicable
in

NEW7110

EPP device handle which is opened by epp_open

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
ut

EPP device handle which is opened by epp_open

start row (Pixel)

start line (Pixel)

pBmpLo
goIn

Data content of comocrome BMP file.

Return

please refer to section 4.12.1

Be
applicable
in

NEW7110

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:

cfgin
put

EPP device handle which is opened by epp_open

start row (Pixel)

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
applicable
in

NEW7110

Notes

5.5.23.

epp_clear_screen

Prototype

int epp_clear_screen(EPP_CFG *cfg)

Function

Clear screen of external N20 PINPAD

Parameter:

cfg

Return

please refer to section 4.12.1

Be
applicable
in

NEW7110

EPP device handle which is opened by epp_open

Notes

5.5.24.

epp_get_system_info

Prototype

int epp_get_system_info(EPP_CFG
*pvInfoOut)

Function

Get N20 PINPAD info. We are normally used this API to check the N20
EPP connect status.

Parameter:

cfg input

Type

*cfg,

uint32_t

Type,

EPP device handle which is opened by epp_open


query type.
0x00 hardware version;
0x01 hardware configure;
0x02 the EPP serial number;
0x03 CPU SN;

void

0x10 boot version;


0x11 Kernel version;
0x20 query protocol version.
pvInfoOut
Return
Be
applicable
in

return info, the buff no less then 17 bytes.

output
please refer to section 4.12.1
NEW7110

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:

cfginput

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
applicable
in

NEW7110

Notes

5.5.26. epp_light
Prototype

int epp_light(EPP_CFG *cfg, uint32_t TimeMs)

Function

N20 PINPADs LCD back light control.

Parameter:

cfginput

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
applicable
in

NEW7110

Notes

5.5.27. epp_kb_get_string
Prototype

Function
Parameter:

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


uint32_t iMaxlen, uint32_t iTimeOutMs, void *strBuff)
get user keystrokes on the password keyboard of N20 PINPAD
cfginput

EPP device handle which is opened by epp_open

iMode

D31
D9

Be
applicable
in
Notes

rev

D8

10 yesnoallow left input and line


display

D7

10 yesnoStrBuf default content


effectively

D6

10 biglittlefont

D5

10 yesnoinput digital

D4

10 yesnoinput character

D3

10 yesnopassword way

D2

10 leftrightaligned input

D1

10 yesnodecimal point

D0

10 normalreversedisplay

iMinLen

min length

iMaxLen

max length

iTimeOutMs

timeout time

strBuffoutput
Return

contnet returned by password keybord, buffer is


according to max length

please refer to section 4.12.1


NEW7110

5.6. Printer
Printer is a character device, using general file operations(openwriteioctlclose) 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
printers 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

Function
Parameter:

int printer_open(const char *filename, int oflags)


open printer device
filename

printer device name/dev/printer0,/dev/printer1

oflags

Way to open the device:


blocking mode use O_WRONLY
non-blocking mode useO_WRONLY | O_NONBLOCK

Return

>= 0

open device OK, return value is used to operate printers


file number

others

other error code

Support

NEW8210

Notes

Printer devices 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

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

>=
0
other

Support

Printer accepted bytes


other error code

NEW8210

Notes

5.6.4.

printer_write

Prototype

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


Function
Parameter:

Return

put the data to be printed


fd

opened device file number that printer_open function


returns

buf

point to data buffer to be printed

nbytes

the number of printed datas bytes

>= 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

Function
Parameter:

int printer_get_status(int fd, printer_status_t *status)


To get the status of the printer
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
print power on flag

Return

voltage

voltage of the current print

temperature

temperature of current print head

bit

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

Function
Parameter:

Return

int printer_get_param(int fd, printer_param_t *param)


get the current print parameters
fd

opened device file number

param

ro_width

the dot number of each line dot matrix


of printer

ro_bits_per_pixe
l

how many bits to expressed each


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

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

Function
Parameter:

Return

int printer_set_param(int fd, const printer_param_t *param)


set current print 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
l

how many bits to expressed each


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

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

Function
Parameter:

Return

int printer_feed_start(int fd, uint32_t step)


start the printer paper feed function
fd

opened device file number that printer_open function


returns

step

Steps of feeding into the paper

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

Function

int printer_feed_stop(int fd)


stop the printer feeding

Parameter:

fd

opened device file number that printer_open function


returns

Return

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

Function

int printer_reset(int fd)


Reset all status of printer, clear all the printer internal data

Parameter:

fd

opened device file number that printer_open function


returns

Return

operate success

others

Other error code

Support

NEW8210

Notes

5.6.11. print_surface
Prototype

Function
Parameter:

int print_surface (int print_fd, IDirectFBSurface *fb_surface, uint32_t


print_height)
output the content of fb_surface of printer
print_fd

opened device file number that printer_open function


returns

fb_surface

surface which is to be printed

Return

print_height

print height, calculated by pixel

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_surfaces width, then
fb_surfaces height is the biggest corresponding height.

5.7. Magnetic stripe


magnetic
stripe
reader
is
a
character
device,
use
general
file
operations(openwriteioctlclose) can complete operation on magnetic stripe reader, for
convenience to develop, we package it ,let magnetic cards 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 reawakened, 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

Function
Parameter:

Return

int magstripe_open(const char *filename, int oflags)


open the magnetic stripe reader
filename

magnetic
stripe
name/dev/magcard0,/dev/magcard1

reader

oflags

Way to open the device:


blocking mode use O_RDONLY
non-blocking mode useO_RDONLY | O_NONBLOCK

>= 0

open device OK, return value is used to operate card


decoding devices 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,,15in default condition NEW8210


thermal printer device name is /dev/magcard0

5.7.2.

magstripe_close

Prototype

Function

int magstripe_close(int fd)


close magnetic stripe reader

Parameter:

fd

opened device file number that magstripe_open function


returns

Return

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

Function
Parameter:

Return
Support

int magstripe_read(int fd, user_magcard_info_t *cardinfo)


Get data of track from magnetic stripe reader
fd

opened device file number that magstripe_open function


returns

cardinf
o

magcardtrac
k
[0,1,2]

trackn
o

Track number012

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

>0

number of data bytes read from magnetic stripe reader

others

other error code

NEW8210

Notes

5.7.4.

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 ;

magstripe_read_timeout

Prototype

Function

Parameter:

int magstripe_read_timeout(int fd, user_magcard_info_t * cardinfo,


unsigned long ms)
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.
fd

opened device file number that magstripe_open function


returns

cardinf
o

magcardtrac
k
[0,1,2]

ms
Return

Support
Notes

trackn
o

Track number012

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

timeout time,unit:ms

>0

number of data bytes from magnetic stripe reader

-ETIME

read timeout

others

other error code

NEW8210

5.7.5.

magstripe_write

Prototype

Function
Parameter:

Return

int magstripe_write(int fd, const user_magcard_info_t *cardinfo)


write track data into magnetic stripe by magnetic stripe reader
fd

opened device file number that magstripe_open function


returns

cardinfo

magcardtrac
k
[0,1,2]

trackno

Track number012

status

ignore

size

number of data bytes of the


track

data

store data of the track

>0

number of data bytes of writing into magnetic stripe


reader

others

other error code

Support

none

Notes

NEW8210 dont support this function currently

5.7.6.

magstripe_write_timeout

Prototype

Function
Parameter:

int magstripe_write_timeout(int fd, const user_magcard_info_t *


cardinfo, unsigned long ms)
write track data into magnetic card by magnetic stripe reader
fd

opened device file number that magstripe_open function


returns

cardinfo

magcardtrac
k
[0,1,2]

ms
Return

trackno

Track number012

status

ignore

size

number of data bytes of the


track

data

store data of the track

timeout time,unit:ms

>0

number of data bytes of writing into magnetic stripe


reader

-ETIME

read timeout

others

other error code

Support

none

Notes

NEW8210 dont 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:

Return

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

>0

success

others

other error code

Support

NEW8210

Notes

This function is provided for developers who know well about


magnetic coding standards, if developer dont know it well, it is not
necessary to call this function.

5.7.8.

magstripe_set_trackset

Prototype

Function
Parameter:

Return

int magstripe_set_trackset(int fd, const user_track_info_t *trackinfo)


set encoding standards of every track of current magnetic stripe
reader
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

success

others

other error code

Support

NEW8210

Notes

This function is provided for developers who know well about


magnetic coding standards, if developer dont 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=0T=1 asynchronous operation of CPU card, but
also supports various synchronization card, such as SLE4428SLE4442 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

Function

int iccard_open_cardslot(const char *filename)


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

Function

int iccard_close_cardslot(int fd)


close contact IC card device

Parameter:

fd

opened device file number that iccard_open_cardslot


function returns

Return

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 cant 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

Function

int iccard_check_card_in_slot(int fd)


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

Card Detected

-1

Card absent or other error, please check the mistake by


errno:
ENXIOCard absent
Other valueother 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

Function

int iccard_power_up(int fd, int vcc, int mode, int *len, void *atr)
power on and reset asynchronous CPU card of IC card slot when

contacting
Parameter:

Return

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
modesupports PPS protocol
ISO_19200
------ ISO7816 19200BPS working
mode
ISO_38400
------ ISO7816 38400BPS working
mode

len outp
ut

ATR length that IC card returns

atroutpu
t

ATR information that IC card returns

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

1Please refer to iccard.h

5.8.5.
Prototype

iccard_exchange_apdu
int

iccard_exchange_apdu(int fd, uint32_t sendlen, const


*senddata,
uint32_t
*recvlen,
*recvdata)

Function

exchange data with asynchronous card of contacting IC card slot

Parameter:

fd

void
void

opened device file number that iccard_open_cardslot


function returns

Return

sendlen

the total length of data to be sent

senddata

the data to be sent

recvleno
utput

length of data that IC card returns

recvdata

the data that IC card returns

output
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

1Please refer to iccard.h

5.8.6.

iccard_power_down

Prototype

Function

int iccard_power_down(int fd)


power off IC card of contacting IC card slot

Parameter:

fd

opened device file number that iccard_open_cardslot


function returns

Return

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

1Please refer to iccard.h

5.9. SLE4428 card module interface


5.9.1.

sle4428_open

Prototype

Function

int sle4428_open(int fd)


active SLE4428 card of IC card slot

Parameter:

fd

opened device file number that iccard_open_cardslot


function returns

Return

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

1Please 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

power off success

-1

Power off SLE4428 failure, please get actual error code


by errno

Support

NEW8210

Notes

1Please 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
put

data that will be read.

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

Return

Support

NEW8210

Notes

1Please refer to sle4428.h

5.9.4.

sle4428_read_error_count

Prototype

Function
Parameter:

Return

int sle4428_read_error_count (int fd,void *count)


read count of SLE4428 consecutive password verification failures
fd

opened device file number that iccard_open_cardslot


function returns

count ou
tput

Count of consecutive password verification failures

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

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

Return

Support

NEW8210

Notes

1Please refer to sle4428.h

5.9.6.

sle4428_change_key

Pototype

int sle4428_change_key(int fd,const void *new_pwd)

Function
Parameter:

Return

modify SLE4428 cards password


fd

opened device file number that iccard_open_cardslot


function returns

new_pwd

new SLE4428 card password , 2 bytes

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

1Please refer to sle4428.h

5.9.7.

sle4428_lock

Pototype

Function

int sle4428_lock(int fd)


Lock SLE4428 card

Parameter:

fd

opened device file number that iccard_open_cardslot


function returns

Return

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

1Please refer to sle4428.h

5.9.8.

sle4428_read_status

Prototype

Function
Parameter:

Return

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


read data status of an address of SLE4428 card
fd

opened device file number that iccard_open_cardslot


function returns

addr

data address that will be demanded

statusou
tput

The data status, 0- can not modify 1- can modify

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

1Please refer to sle4428.h

5.9.9.

sle4428_write

Prototype

Function
Parameter:

Return

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


write data into SLE4428
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.

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 addresss data
ETIME timeout
Other value other error code

Support

NEW8210

Notes

1Please refer to sle4428.h

5.9.10. sle4428_write_protect
Prototype

Function
Parameter:

Return

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


*data)
write data into SLE4428, while setting data that can not be changed
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

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 addresss data
ETIME timeout
Other value other error code

Support

NEW8210

Notes

1Please refer to sle4428.h

5.9.11. sle4428_check_data
Prototype

Function
Parameter:

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


compare specified address data of SLE4428 with input data, if they
are all the same, then setting this address to can not be changed
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

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 addresss data
ETIME timeout
Other value other error code

Support

NEW8210

Notes

1Please refer to sle4428.h

5.10. SLE4442 card module interface


5.10.1. sle4442_open
Prototype

Function

int sle4442_open(int fd)


active SLE4442card of IC card slot

Parameter:

fd

opened device file number that iccard_open_cardslot


function returns

Return

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

1Please 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

power off success

-1

Power off failure, please get actual error code by errno

Support

NEW8210

Notes

1Please refer to sle4442.h

5.10.3. sle4442_verify
Prototype

Function
Parameter:

int sle4442_verify(int fd,const void* pwd)


SLE4442 card password verification
fd

opened device file number that iccard_open_cardslot


function returns

Return

pwd

SLE4442 card user password, 3 bytes

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

1Please refer to sle4442.h

5.10.4. sle4442_read_error_count
Prototype

Function
Parameter:

Return

int sle4442_read_error_count(int fd,void *count)


read count of SLE4442 consecutive password verification failures
fd

opened device file number that iccard_open_cardslot


function returns

count ou
tput

Count of consecutive password verification failures

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

Function
Parameter:

Return

int sle4442_change_key(int fd,const void *new_pwd)


modify SLE4442 cards password
fd

opened device file number that iccard_open_cardslot


function returns

new_pwd

new SLE4442 card password , 3 bytes

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

1Please 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

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

1Please refer to sle4442.h

5.10.7. sle4442_read
Prototype

Function
Parameter:

Return

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


read data from SLE4442 card
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
put

data that will be read.

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

1Please refer to sle4442.h

5.10.8. sle4442_write
Prototype

Function
Parameter:

Return

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


write data into SLE4442
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.

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

1Please refer to sle4442.h

5.10.9. sle4442_read_status
Prototype

Function
Parameter:

Return

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


read protect bit information of the designated address of SLE4442
card
fd

opened device file number that iccard_open_cardslot


function returns

addr

data address that will be demanded

statusou
tput

Protect bit information of the address:


0 be protected ,can not be modified
1 not be protected, can be modified

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

1Please refer to sle4442.h

5.10.10. sle4442_check_data
Prototype

Function
Parameter:

Return

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


Write data into the designated address of SLE44442s protect zone,
and set its property to can not be changed
fd

opened device file number that iccard_open_cardslot


function returns

addr

data address that will be written.

data

data that will be written.

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 addresss data
ETIME timeout
Other value other error code

Support

NEW8210

Notes

1Please refer to sle4442.h

5.11. Contact-less IC card reader module


NEW8210s contact-less reader module device name is /dev/nfc
NEW8210 supports TypeAISO14443-1-2-3-4TypeBISO14443-1-2-34and SonyFeliCa protocol card currently.
Specifically supports mifare Classic(S50/S70) mifare Ultralight mifare DESFire
D40 mifare DESFire EV1mifare ProX and etc
When developing application, please contains iso14443.hmifone.hmiful.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

Function

int mif_open(const char *filename)


open the contact-less reader module

Parameter:

filename

Contact-less reader namecurrently fixed at /dev/nfc

Return

>= 0

open device OK, returned value is used to operate


contact-less reader functions file number

-1

open failure, please get the actual error code by errno

Support

NEW8210

Notes

1Please refer to iso14443.h

5.11.1.2. mif_close
Prototype

Function

int mif_close(int fd)


close contact-less reader module

Parameter:

fd

opened device file number that mif_open function returns

Return

operate success

-1

Close failure, please get the actual error code by errno

Support

NEW8210

Notes

1Please refer to iso14443.h

5.11.1.3. mif_set_timeout
Prototype

Function

int mif_set_timeout(const struct mif_timeout *ptime)


set corresponding timeout parameter of contact-less reader module

Parameter:

ptime

structure pointer to timeout parameter

Return

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

Function

int mif_get_timeout(struct mif_timeout *ptime)


get corresponding timeout parameter of contact-less reader module

Parameter:

ptime

structure pointer of current timeout parameter

Return

output
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

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

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

Function
Parameter:

Return

Support

int mif_select_carrier_type(int fd, int32_t type)


set contact-less reader module carrier modulation type
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)

Operate OK

-1

Operate failure, please get the actual error code by errno:


EINVAL input parameter error
Other value other error code

NEW8210

Notes

Please refer to iso14443.h

5.11.1.8. iso14443_ReqA
Prototype

Function
Parameter:

Return

int iso14443_ReqA(int fd, void *atqa)


request idle Type A card in the inductive zone
fd

opened device file number that mif_open function


returns

atqaoutpu
t

card returned ATQA information,2 bytes

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 doesnt 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

Function
Parameter

Return

int iso14443_ReqA(int fd, void *atqa)


wake up TypeA card in IDLE state or HALT state in inductive zone
fd

opened device file number that mif_open function


returns

atqaoutpu
t

ATQA information that card returned, 2 bytes

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 doesnt 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

Function
Parameter:

Return

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


TypeA card anti-conflict management, get UID information of TypeA
card
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

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 doesnt 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

Function
Parameter:

Return

int iso14443_Select(int fd,uint8_t sel, const void *uid, uint8_t *sak)


Select the TypeA card
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

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 doesnt 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]

Return

opened device file number that mif_open function returns


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

Function
Parameter:

int iso14443_HaltA(int fd)


Make TypeA card dormant, enter HALT state.
fd

opened device file number that mif_open function


returns

Return

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

Function
Parameter:

Return

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


*ats)
execute the command of Request Answer To Select, for TypeA card
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
utput

length of ATS information that info_len returned

ats outp
ut

ATS information that info_len returned

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 doesnt 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

1Please refer to iso14443.h

5.11.1.16. iso14443_PPS
Prototype

Function
Parameter:

Return

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


protocol and parameter select command, TypeA
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

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 doesnt 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

1Please refer to iso14443.h

5.11.1.17. iso14443_ReqB
Prototype

Function
Parameter:

Return

int iso14443_ReqB(int
*lenofatqb, void *atqb)

fd,uint8_t

afi,uint8_t

slotnum,uint8_t

requese IDLE TypeB card in inductive zone


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
put

atqb information

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 doesnt 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

1Please refer to iso14443.h

5.11.1.18. iso14443_WupB
Prototype

Function
Parameter:

Return

int iso14443_WupB(int
*lenofatqb, void *atqb)

fd,uint8_t

afi,uint8_t

slotnum,uint8_t

wake up IDLE state of HALT state Type B card in inductive zone


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
put

atqb information

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 doesnt 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

1Please refer to iso14443.h

5.11.1.19. iso14443_SlotMarker
Prototype

Function
Parameter:

Return

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


*atqb)
request card information of specified time slot
fd

opened device file number that mif_open function


returns

slot

time slot parameter0~15

lenofatqb

information length of ATQB

output
atqb out
put

atqb information

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 doesnt 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

1Please refer to iso14443.h

5.11.1.20. iso14443_AttriB
Prototype

Function
Parameter:

int iso14443_AttriB(int fd,uint8_t


*uid,uint8_t br,uint8_t *len,void *info)

fsdi,const

void

choose TypeB card


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


length of Higher-layer INF information of ArttriB
command
When is used to output, info_lens returns cards
response data length

input/
output

Return

cid,uint8_t

info inp
ut/
output

When is used to input, info means Higher-layer INF


information of ArttriB command
When is used to output, info returns cards response
data

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 doesnt 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

Function
Parameter:

Return

int iso14443_HaltB(int fd,const void *uid)


Make TypeB card dormant, enter HALT state.
fd

opened device file number that mif_open function


returns

uid

UID information of TypeB card, 4 bytes

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 doesnt 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


Function
Parameter:

Return

*cardinfo)
polling inductive area if there exists T=CL protocol card, is there
have , choose it
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
cardinfoou
tput

card returned data

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 doesnt 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

Function
Parameter:

int iso14443_tcl_active(int fd,


fsdi,uint8_t *info_len, void *info)

uint8_t

cid,

uint8_t

br,uint8_t

active T=CL card in inductive zone


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:
Length of ATS information that info_len returns
TypeB card:
When is used to input, info_len means length of Higherlayer INF information of ArttriB command
When is used to output, info_lens returns cards
response data length

input/
output

Return

info inp
ut/
output

TypeA card:
ATS information that info_len returns
TypeB card:
When is used to input, info means Higher-layer INF
information of ArttriB command
When is used to output, info returns cards response
data

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 doesnt 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

Function
Parameter:

Return

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


senddata,uint32_t *recvlen,void *recvdata)
exchange data with card by T=CL protocol
fd

opened device file number that mif_open function


returns

sendlen

length of data that terminal sends

senddata

data that terminal sends

recvleno
utput

length of data that terminal received

recvdata

data that terminal received

output
0

operate OK

-1

Support

NEW8210

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 doesnt 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

Notes

Please refer to iso14443.h

5.11.1.25. iso14443_tcl_deactive
Prototype

Function

int iso14443_tcl_deactive(int fd)


close T=CL protocol channel, reset T=CL card

Parameter:

fd

opened device file number that mif_open function returns

Return

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

recvleno
utput

length of data that terminal received

recvdata

data that terminal received

output
timeout

timeout parameter, unit(ETU)

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 doesnt comply with ISO14443
standard
EBADE error of length of card returned data
ETIME timeout and no return
other value : other error code

Return

Support

NEW8210

Notes

Please refer to iso14443.h

5.11.1.27. mif_check_multi_card
Prototype

Function

int mif_check_multi_card(int fd)


check whether there are multiple cards in inductive zone

Parameter:

fd

opened device file number that mif_open function


returns

Return

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

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 doesnt 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

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 doesnt 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

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 doesnt 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

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 doesnt comply with ISO14443 standard
EBADE error of length of card returned data
other value : other error code

Return

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

Success

Return

-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 doesnt 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

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 doesnt comply with ISO14443
standard
EBADE error of length of card returned data
other value : other error code

Return

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

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 doesnt 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

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 doesnt 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
Function

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


void *InitInfo, int *CardInfoLen, void *pCardInfo);

Parameter:

fd

opened device file number that mif_open function returns

Mode
InitLen
InitInfo
CardInfoLen
pCardInfo
Return

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 doesnt 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

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 doesnt 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

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 doesnt 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

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 doesnt 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

Function
Parameter:

Return

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


*cardtype)
poll if there is mifare one card in inductive zone, if yes, active it.
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

cardtype o
utput

5 bytes UID information that card returns, 4 bytes


UID+BCC

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 doesnt 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

Returned mifare one card type, may have the value


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

Support

NEW8210

Notes

1Please refer to mifone.h

5.11.2.2. mifare_one_halt
Prototype

Function

int mifare_one_halt(int fd)


Reset mifare one card in inductive zone

Parameter:

fd

opened device file number that mif_open function


returns

Return

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

1Please refer to mifone.h

5.11.2.3. mifare_one_authenticate
Prototype

Function
Parameter:

Return

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


const void *key, const void *uid)
password authentication about mifare one cards a data block
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

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 doesnt 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

1Please refer to mifone.h

5.11.2.4. mifare_one_read_block
Prototype

Function
Parameter:

Return

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


read a data block content of mifare one card
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.

blockdatao
utput

read content of data block,16 bytes

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 doesnt 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

1Please refer to mifone.h

5.11.2.5. mifare_one_write_block
Prototype

Function
Parameter:

Return

int mifare_one_write_block(int fd, uint8_t blockno, const void


*blockdata)
modify content of a data block of mifare one card
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

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 doesnt 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

1Please refer to mifone.h

5.11.2.6. mifare_one_set_value
Prototype

Function
Parameter:

Return

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


set a data block of mifare one card to value block,and fu initial
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

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 doesnt 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

1Please refer to mifone.h

5.11.2.7. mifare_one_increment
Prototype

Function
Parameter:

Return

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


value block value-added operation
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

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 doesnt 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

1Please refer to mifone.h

5.11.2.8. mifare_one_decrement
Prototype

Function
Parameter:

Return

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


value block decrement operation
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

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 doesnt 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

1Please refer to mifone.h

5.11.2.9. mifare_one_restore
Prototype

Function
Parameter:

Return

int mifare_one_restore(int fd, uint8_t blockno)


Restore value in the designated block
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.

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 doesnt 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

1Please refer to mifone.h

5.11.2.10. mifare_one_transfer
Prototype

Function
Parameter:

Return

int mifare_one_transfer(int fd, uint8_t blockno)


save the result of value block operation
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.

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 doesnt 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

1Please refer to mifone.h

5.11.2.11. mifare_one_get_value
Prototype

Function
Parameter:

Return

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


get the value of the designated block
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.

valueoutpu
t

value content that card returns

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 doesnt 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

1Please refer to mifone.h

5.11.3. mifare ultralight card module interface

5.11.3.1. mifare_ultralight_poll
Prototype

Function
Parameter:

Return

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


Poll if there is mifare ultralight card in inductive zone, if there is,
active it.
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


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 doesnt 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

1Please refer to miful.h

5.11.3.2. mifare_ultralight_halt
Prototype

Function

int mifare_ultralight_halt(int fd)


halt mifare ultralight card in inductive zone

Parameter:

fd

opened device file number that mif_open function


returns

Return

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

1Please refer to miful.h

5.11.3.3. mifare_ultralight_read_page
Prototype

Function
Parameter:

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


read content of a page of mifare ultralight card, 4 pages at one time
fd

opened device file number that mif_open function


returns

Return

page

start page number that will be read, 0~15

dataoutput

page content that be read, 16 bytes

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

1Please refer to miful.h

5.11.3.4. mifare_ultralight_write_page
Prototype

Function
Parameter:

Return

Support

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


write content of a page of mifare ultralight card
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

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 doesnt 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

NEW8210

Notes

1Please 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:

Return

Support

fd

opened device file number that mif_open function returns

page

Page number0~15

data

Data to write

Success

-1

FailedOperate failure, please get the actual error code


by errno
ENODATA is not a mifare ultralight card in inductive
zone
EPROTO Card doesnt 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

NEW8210

Notes

5.11.4. Mifare DESFire module interface

5.11.4.1. desfire_poll
Prototype

Function
Parameter:

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


*ats)
Poll if there is mifare DESFire card in inductive zone, if there
is,active it.
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

Return

uid output

atslen outp
ut

7 bytes UID information that card returns

ats output

ATS information that card returns

-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 doesnt 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

length of ATS information that card returns

find card success

Support

NEW8210

Notes

1Please 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

Operate OK

-1

Operate failure, please get the actual error code by


errno:

Be
applicable

Notes

NEW8210

1Please 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:

Return

fd

opened device file number that mif_open function


returns

keyno

key number that will be certificated

key

key information ,is fixed 16 bytes

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 doesnt 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[07] ||
old_key[07]
2Please refer to desfire.h

5.11.4.4. desfire_authenticate_iso
Prototype

Function
Parameter:

Return

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


do 3KDES key authentification on mifare DESFire card
fd

opened device file number that mif_open function


returns

keyno

key number that will be authenticated

key

key information ,is fixed 24 bytes

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 doesnt 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[07] ||
old_key[07] || old_key[07]
2.if actual key is 16 bytes, then expanding it to 24 bytes as follow:
key = old_key[07] || old_key[815] || old_key[07]
3Please refer to desfire.h

5.11.4.5. desfire_authenticate_aes
Prototype

Function
Parameter:

Return

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


do AES key authentication on mifare DESFire card
fd

opened device file number that mif_open function


returns

keyno

key number that will be certificated

key

key information ,is fixed 16 bytes

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 doesnt 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 keys 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:

Return

fd

opened device file number that mif_open function


returns

key_settings

new Master Key setting parameter

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 doesnt 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

Function
Parameter:

int desfire_get_key_settings(int fd,uint8_t *key_setting,


uint8_t *max_key_num)
get PICC Master Key setting or Application Master Key setting
fd

opened device file number that mif_open function


returns

key_settings

Master Key setting parameter that card returned

output
max_key_num
Return

output
0
-1

maximum key number that current application


supports
operate success
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 doesnt 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

1Please 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

Return

key

key information,16/24 bytes

version

key version information

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 doesnt 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

1Please 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

applications
parameter

type

PICC Master Key key typevalues 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 information16/24 bytes

newkey

new key information16/24 butes

version

key version information

operate success

Return

master

key

configuration

attribute

-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 doesnt 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

1Please refer to desfire.h

5.11.4.10. desfire_get_key_version
Prototype

Function
Parameter:

Return

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


get key version information
fd

opened device file number that mif_open function


returns

keyno

key number

versionout
put

key version information that card returned

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 doesnt 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

1Please refer to desfire.h

5.11.4.11. desfire_create_application
Prototype

Function
Parameter:

Return

int desfire_create_application(int fd,const desfire_appinfo *info)


create a sub-application
fd

opened device file number that mif_open function


returns

info

application information

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 doesnt 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

1Please refer to desfire.h

5.11.4.12. desfire_delete_application
Prototype

Function
Parameter:

Return

int desfire_delete_application(int fd,const void *aid)


delete a sub-application
fd

opened device file number that mif_open function


returns

aid

application AID information, 3 bytes

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 doesnt 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

1Please refer to desfire.h

5.11.4.13. desfire_get_application_ids
Prototype

Function
Parameter:

Return

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


get all applications AID information of DESFire card
fd

opened device file number that mif_open function


returns

numoutpu
t

application number that card contained

aid output

application AID information, 3 bytes every application

operate success

-1

Support

NEW8210

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 doesnt 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

Notes

1Please refer to desfire.h

5.11.4.14. desfire_get_dfnames
Prototype

Function
Parameter:

Return

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


get all applications information of DESFire
fd

opened device file number that mif_open function


returns

appnum o
utput

application number that card contained

info output

application information, every application has a


dfname_info struct

0
-1

operate success
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 doesnt 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

1Please refer to desfire.h

5.11.4.15. desfire_select_application
Prototype

Function
Parameter:

Return

int desfire_select_application(int fd,const void *aid)


Select a sub-application
fd

opened device file number that mif_open function


returns

aid

application AID information, 3 bytes

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 doesnt 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

1Please refer to desfire.h

5.11.4.16. desfire_format_picc
Prototype

Function

int desfire_format_picc(int fd)


format DESFire card, delete all application and all applications key
and file information

Parameter:

fd

opened device file number that mif_open function


returns

Return

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 doesnt 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

1Please refer to desfire.h

5.11.4.17. desfire_get_version
Prototype

Function
Parameter:

Return

int desfire_get_version(int fd, desfire_version *version)


get version information of mifare DESFire card
fd

opened device file number that mif_open function


returns

versionout
put

version information of mifare DESFire card

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 doesnt 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

1Please refer to desfire.h

5.11.4.18. desfire_set_configuration
Prototype

Function
Parameter:

Return

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


const void *info)
configure mifare DESFire card
fd

opened device file number that mif_open function


returns

option

configuration information option

len

configuration information length

info

content of configuration information

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 doesnt 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

1Please refer to desfire.h

5.11.4.19. desfire_free_memory
Prototype

Function
Parameter:

Return

int desfire_free_memory(int fd,uint32_t *freesize)


get the size of the available memory space of mifare DESFire card
fd

opened device file number that mif_open function


returns

freesizeou
tput

size of the remaining available space of mifare


DESFire card

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 doesnt 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

1Please refer to desfire.h

5.11.4.20. desfire_get_card_uid
Prototype

Function
Parameter:

Return

int desfire_get_card_uid(int fd,void *uid)


get UID information of mifare DESFire card
fd

opened device file number that mif_open function


returns

uid output

UID information that mifare DESFire card returns, 7


bytes

0
-1

operate success
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 doesnt 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

1Please 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-applications file fid information of mifare DESFire


card

Parameter:

fd

opened device file number that mif_open function


returns

numoutpu
t

file number of application

fid output

fid information of file,1 byte every file

operate success

Return

-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 doesnt 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

1Please refer to desfire.h

5.11.4.22. desfire_get_iso_fids
Prototype

Function
Parameter:

Return

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


get current sub-applications file iso fid information of mifare
DESFire card
fd

opened device file number that mif_open function


returns

numoutpu
t

file number of application

fid output

file iso fid information, 2 bytes every file

-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 doesnt 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

operate success

Support

NEW8210

Notes

1Please refer to desfire.h

5.11.4.23. desfire_get_filesetting
Prototype

Function
Parameter:

Return

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


get the designated files information
fd

opened device file number that mif_open function


returns

fileno

file number

filesetting
output

returned file information

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 doesnt 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

1Please 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

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 doesnt 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

Return

Support

NEW8210

Notes

1Please 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

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 doesnt 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

Return

Support

NEW8210

Notes

1Please 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

operate success

Return

-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 doesnt 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

1Please refer to desfire.h

5.11.4.27. desfire_create_valuefile
Prototype

Function
Parameter:

Return

int desfire_create_valuefile(int fd, uint8_t fileno,


const desfire_value_file_info *fileinfo)
create value file
fd

opened device file number that mif_open function returns

fileno

file number

fileinfo

value file information

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 doesnt 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

1Please refer to desfire.h

5.11.4.28. desfire_create_linear_recordfile
Prototype

int desfire_create_linear_recordfile(int fd,uint8_t fileno,


Function
Parameter:

Return

const desfire_record_file_info *fileinfo)


create linear log file
fd

opened device file number that mif_open function returns

fileno

file number

fileinfo

linear log file information

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 doesnt 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

1Please 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

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 doesnt 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

Return

Support

NEW8210

Notes

1Please refer to desfire.h

5.11.4.30. desfire_delete_file
Prototype

Function
Parameter:
Return

int desfire_delete_file(int fd,uint8_t fileno)


delete a file
fd

opened device file number that mif_open function returns

fileno

file number

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 doesnt 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

1Please 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

Return

offset

read start address

len

expect length that will be read

outlenoutput

actual data length that have been read

dataout output

actual data that have been read

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 doesnt 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

1Please 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

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 doesnt 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

1Please refer to desfire.h

5.11.4.33. desfire_get_value
Prototype

Function
Parameter:

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


*value)
get the value of the specified file
fd
fileno

Return

opened device file number that mif_open function


returns
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


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 doesnt 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

1Please refer to desfire.h

5.11.4.34. desfire_credit
Prototype

Function
Parameter:

Return

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


value)
recharge operation
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

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 doesnt 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

1Please refer to desfire.h

5.11.4.35. desfire_debit
Prototype

Function
Parameter:

Return

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


value)
deduct value operation
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

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 doesnt 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

1Please refer to desfire.h

5.11.4.36. desfire_limited_credit
Prototype

Function
Parameter:

Return

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


uint32_t value)
limited recharge operation
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

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 doesnt 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

1Please 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

Return

offset

start address of current log

len

length of data that will be written

info

log information that will be written

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 doesnt 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

1Please refer to desfire.h

5.11.4.38. desfire_read_records
Prototype

Function
Parameter:

Return

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)
read log operation
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

infooutput

total length of data that have been read

log information that have been read


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 doesnt 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

1Please refer to desfire.h

5.11.4.39. desfire_clear_recordfile
Prototype

Function
Parameter:
Return

int desfire_clear_recordfile(int fd,uint8_t fileno)


clear all record files
fd

opened device file number that mif_open function returns

fileno

file number

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 doesnt 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
application
in

NEW8210

Notes

1Please refer to desfire.h

5.11.4.40. desfire_commit_transaction
Prototype

Function

int desfire_commit_transaction(int fd)


confirm and save all related operations on current applications files

Parameter:

fd

opened device file number that mif_open function returns

Return

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 doesnt 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

1Please refer to desfire.h

5.11.4.41. desfire_abort_transaction
Prototype

Function

int desfire_abort_transaction(int fd)


undo related operations on current applications files

Parameter:

fd

opened device file number that


mif_open function returns

Return

operate success

EINVAL

input parameter error

EIO

read card chip error

ECOMM

Parity error or CRC check error of


card returned data

EPROTO

Card doesnt 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
Support

NEW8210

Notes

1Please refer to desfire.h

other error code

5.12. AT24CXX card module interface


5.12.1. at24_open
Prototype

Function

int at24_open(int fd)


active AT24xx series card of the designated IC card slot

Parameter:

fd

opened device file number that iccard_open_cardslot


function returns

Return

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

1Please refer to at24xx.h

5.12.2. at24_read
Prototype

Function
Parameter:

Return

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


read information from AT24xx card
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
put

read data

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

1Please refer to at24xx.h

5.12.3. at24_write
Prototype

Function
Parameter:

Return

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


*data)
write data into AT24xx card
fd

opened device file number that iccard_open_cardslot


function returns

card_type

AT24 card type, refer to note

start_add
r

start address

len

length of data that will be written into

data

data that is written into

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

1Please refer to at24xx.h

5.12.4. at24_close
Prototype

Function

int at24_close(int fd)


Close AT24 series card

Parameter:

fd

opened device file number that iccard_open_cardslot


function returns

Return

power off success

-1

Operate failure, please get the actual error code by errno

Support

NEW8210

Notes

1Please 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

Modem state transition diagram:

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.

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

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

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>, Its 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-dont 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- dont 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 dont know the protocol clearly, please dont 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

Return:

Read/write (required)

O_NONBLOCK

non-blocking
(optional)

>=0

Open successfully, the code is the handle which is


used for the subsequent operation.

<0

Open failed. Refer to <errno.h>

Be
Applicable
In:

NEW8210

Notes:

Example:

O_RDWR

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 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:

Close modem device successfully.

others

Close failed. Refer to <errno.h>

Be
Applicable
In:

NEW8210

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

>=0

The byte length of buffer which are sended successfully

<0

Failed. Invoke PosixGeterrno to get the detail error.

Return:
Be
Applicable
In:

NEW8210

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)

>=0

The byte length


successfully

<0

Failed. Invoke PosixGeterrno to get the detail error.

Return:

of

buffer

which

are

sended

Be
Applicable
In:

NEW8210

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:

OK

Others

Failed. Refer to <errno.h>

Be
Applicable
In:

NEW8210

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 wont 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

>=0

The actual received byte length

<0

Failed. Invoke PosixGeterrno to get the detail error.

Return:
Be
Applicable
In:

NEW8210

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.

Return:

buf(Output)

The given buffer to store the received data

nbytes(Input)

The expected receive byte length

timeoutms(Input
)

Timeout (unit: ms)

>=0

The actual received byte length

<0

Failed. Invoke PosixGeterrno to get the detail error.

Be
Applicable
In:

NEW8210

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.

OK

Others

Failed, refer to <errno.h>

Return:
Be
Applicable
In:

NEW8210

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:

Hangs up successfully.

Others

Failed, refer to <errno.h>

Be
Applicable
In:

NEW8210

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

OK

others

Failed. Refer to <errno.h>

Return:
Be
Applicable
In:

NEW8210

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_open.

err(Output)

Return current modem error code.

OK

Others

Failed, refer to <errno.h>

:
Return:

modem

which

is

get

from

Be
Applicable
In:

NEW8210

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.

OK

Others

Failed, refer to <errno.h>

Return:
Be
Applicable
In:

NEW8210

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

OK

Others

Failed, refer to <errno.h>

Return:
Be
Applicable
In:

NEW8210

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_open.

sp(Output)

The space to store the parameters.

OK

Others

Failed, refer to <errno.h>

Return:
Be
Applicable
In:

modem

which

is

get

from

NEW8210

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.

OK

Others

Failed, refer to <errno.h>

Return:
Support:

NEW8210

Notes:
Example:

5.13.18. modem_enter_auto_answer
Prototype

int modem_enter_auto_answer(int fd);

Function
Parameter

fdInput

Return value of modem_open

Return

Success

Other
Support

FailedPlease refer <errno.h>

NEW8210

Notes

5.13.19. modem_exit_auto_answer
Prototype

int modem_exit_auto_answer(int fd);

Function
Parameter

fdInput

Return value of modem_open

Return

Success

Other

FailedPlease 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:

Extension isnt in use (on


hook)

MODEM_ERRNO_EXTENSION_IN_USE

Extension is in use

MODEM_ERRNO_NO_LINE

No line in

Others

Failed

Be
Applicable
In:

NEW8210

Notes:

This function is used to check the line and extension. Before dial via
modem_dialing, modem will check automatically. So application neednt
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

OK

Others

Failed, refer to <errno.h>

Return:
Be
Applicable
In:

NEW8210

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:

onoffinput

1-power on
0-power off

Return

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

Pppd has detached, or otherwise the connection was successfully


established and terminated at the peers 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 didnt 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

Return

auth

authentication
PPP_ALG_PAP
PPP_ALG_CHAP
PPP_ALG_MSCHAPV1
PPP_ALG_MSCHAPV2

timeout

timeout, unit: second

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 modems 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#'"
"'CONNECT'
''"

"\n"
"\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

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

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

recover the original dns server address

other

set assigned ppp link dns address of current


dns server address

Return

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 addresss configuration.

5.15. GPRS/CDMA
5.15.1. Return Codes
#define WNET_OK

(0)

#define WNET_DLOPEN_ERR
#define WNET_DLSYM_ERR
#define WNET_INIT_ERR
#define WNET_NOINIT_ERR
#define WNET_PARAM_ERR
#define WNET_GET_OP_ERR
#define WNET_NO_FUN_ERR
#define WNET_POWER_DOWN_ERR
#define WNET_BEEN_USE_ERR
#define WNET_SUSPEND_ERR

(-4000)//open libxxx.so err


(-4001)//get function point from libxxx.so err
(-4002)//wnet init err
(-4003)//wnet do not init
(-4004)//param err
(-4005)//get get_operation struct err
(-4006)//not the function which beed call
(-4007)//went power down err
(-4008)//wnet have been userd now
(-4009)//wnet have been suspend now

//for sim card


#define WNET_SIM_NOINSERT_ERR
#define WNET_SIM_PIN_ERR
#define WNET_SIM_PUK_ERR

(-4010)//sim card had not insert


(-4011)//sim card pin err
(-4012)//sim card puk err

#define
#define
#define
#define
#define
#define
#define
#define

(-5000)//not wnet module


(-5001)//receive from wnet timeout
(-5002)//user cancel
(-5003)//not used
(-5004)//receive data from wnet err
(-5005)//send data to wnet err
(-5006)//series port open err
(-5007)//not used

WNET_NO_MODULE_ERR
WNET_RECV_TIMEOUT_ERR
WNET_USER_CANCEL_ERR
WNET_RECV_DATA_ERR
WNET_MOD_RESP_ERR
WNET_SEND_DATA_ERR
WNET_COMM_OPEN_ERR
WNET_SMS_DIV_ERR

//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
Parameter:

None

Output
Parameter:

None

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
Parameter:

None

Output
Parameter:

None

Return

Refer 5.15.1 Return Codes

Support

NEW8210

Notes

Power off the modelmust 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
Parameter:

comm_dev

Device file name /var/mux0

Output
Parameter:

None

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
Parameter:

None

Output
Parameter:

None

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
Parameter:

flag

0-set detachment;1-set attachment

Output
Parameter:

None

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
Parameter:

NONE

Output
Parameter:

signal_num

Return

Refer 5.15.1 Return Codes

Support

NEW8210

Notes

The valid signal value is 0~31, the 99 is an invalid signal value.

Return the wireless signal strength

5.15.9. wnet_checksim
Prototype

int wnet_checksim(void)

Function

Check whether the SIM card in slot or not

Input
Parameter:

None

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
Parameter:

None

Output
Parameter:

IMEI

Return

Refer 5.15.1 Return Codes

Support

NEW8210

Return IMEI

Notes

5.15.11. wnet_getmodinfo
Prototype

int wnet_getmodinfo(wnet_moduleinfo_t *info)

Function

Get wireless model information

Input
Parameter:

None

Output
Parameter:

info

Return

Refer 5.15.1 Return Codes

Support:

NEW8210

Notes

Get the information of the wireless model

Information of the wireless model


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;

5.15.12. wnet_sms_getlist
Prototype:

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


*SmsNum)

Function:

Read SMS list

Input
Parameter:

listtype

SMS
Type

NEW SMS

READED SMS

SMS NO SENT (Not Support)

SMS SENT (Not Support)

ALL SMS

maxno

Max number of SMS items

Output
Parameter:

sms

SMS message buffer

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
Parameter:

sms

Output
Parameter:

None

Return

Refer 5.15.1 Return Codes

Support

NEW8210

Message

Notes

5.15.14. wnet_sms_read
Prototype

int wnet_sms_read(int index, tSmsRecv *smsdata)

Function

Read a SMS

Input
Parameter:

index

Index of the SMS

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
Parameter:

index

Index of the SMS to delete

Output
Parameter:

None

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
Parameter:

uiBuffSize

Buffer size

Output
Parameter:

PhoneNumb
er

Receive calling phone number.

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
Parameter:

None

Output
Parameter:

None

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
Parameter:

None

Output
Parameter:

None

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
Parameter:

PhoneNum

Output
Parameter:

None

Return

Refer 5.15.1 Return Codes

Support

NEW8210

Notes

Phone number

5.15.20. wnet_get_basestation_info
Prototype

int wnet_get_basestation_info(tBaseStation *psBaseStationInfo)

Function

Get basestation information

Input
Parameter:

None

Output
Parameter:

psBaseStationInf
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.

Base station information

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
Parameter:

iNum

Max base station count

Output
Parameter:

psBaseStationInf
o

Base station information

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
Parameter:

iLen

Buffer size

Output
Parameter:

psSimCardID

Buffer to save SIM Card ID

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
Parameter:

iLen

Buffer size

Output
Parameter:

IMSI

Buffer to save IMSI of SIM Card

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
Parameter:

None

Output
Parameter:

None

Return

SIM 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
Parameter:

simno

Output
Parameter:

None

Return

Successfully

others

Refer 5.15.1 Return Codes

The number of SIM, range: [0, 1]

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:

Return:

pathname(Input
)

The
device
name
of
scanner,
such
/dev/ttyS2(NEW8210) or /dev/bar0 (NEW8110)

oflags(Input)

Open mode

O_RDONLY

Read only (required)

O_NONBLOCK

non-blocking
(optional)

>=0

Open successfully, the code is the handle which is


used for the subsequent operation.

<0

Open failed. Refer to <errno.h>

Be
Applicable
In:

NEW8210

Notes:

Example:

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 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:

Close scanner device successfully.

others

Close failed. Refer to <errno.h>

Be
Applicable
In:

as

NEW8210

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)

stop scanning

non-zero
Return:

start to scan

Successfully.

non-zero

Failed. Refer to <errno.h>.

Be
Applicable
In:

NEW8210

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

>=0

The actual received byte length

<0

Failed. Refer to <errno.h>.

Return:
Be
Applicable
In:

NEW8210

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)

>=0

The actual received byte length

<0

Failed. Refer to <errno.h>.

Return:
Be
Applicable
In:

NEW8210

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 successfullyconnection 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
(input)

Normal mode

other

Let vpdn library run in debug mode

OK

other

Failed, refer to <errno.h>

Return:
Be
Applicable
In:

NEW8210

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:

OK

other

Failed, refer to <errno.h>

Be
Applicable
In:

NEW8210

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

encryptionGenerally 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 namefor example, ppp1 */
int ifindex;
int intf_is_up;

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


/* vpdn interface status TRUE for up, FALSE for

down */
} result_arg_t;

Return:

OK

other

Failed, refer to <errno.h>

Be
Applicable
In:

NEW8210

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
Mobiles 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;

Return:

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)

OK

other

Failed, refer to <errno.h>

Be
Applicable
In:

NEW8210

Notes:

PSK: Pre-Shared Key, is an encryption of IPSecThere is no encryption


in L2TPit 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;

Return:

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)

OK

other

Failed, refer to <errno.h>

Be
Applicable
In:

NEW8210

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:

OK

other

Failed, refer to <errno.h>

Be
Applicable
In:

NEW8210

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.

You might also like