ADS

DEVELOPMENT
GUIDE
ADS-001
Revision1.00
2014-11-5

Shenzhen Xinguodu Technology Co.,LtdPublished

www.xinguodu.com

ADS DEVELOPMENT GUIDE

Content
CONTENT ................................................................................................................................................................ 2
SCOPE ....................................................................................................................................................................... 6
GUIDE CONVENTIONS .................................................................................................................................................... 6
1

SMT (SIGN MANAGEMENT TOOL)......................................................................................................... 7

1.1

PUBLIC KEY ........................................................................................................................................................ 7

1.2

PRIVATE KEY (SIGN KEY) ................................................................................................................................. 8

1.3

GENERATING THE RSA KEY PAIR ................................................................................................................... 8

1.4

PROCESSES OF GENERATING RSA KEY PAIR .............................................................................................. 12

COMPILE ENVIRONMENT.......................................................................................................................14
2.1

LINUX OS.......................................................................................................................................................... 14

2.2

WINDOW/MAC OS ............................................................................................................................................ 15

BUILDING PROJECT .................................................................................................................................20

3.1

INTRODUCE ....................................................................................................................................................... 20

3.2

CREATE PROJECT............................................................................................................................................. 21

COMPILE ........................................................................................................................................................22
4.1

COMPILING GUIDE........................................................................................................................................... 22

4.2

COMPILING SCRIPT .......................................................................................................................................... 22

4.3

ERROR MESSAGE OF COMPILING................................................................................................................... 23

DOWNLOAD.........................................................................................................................................................24

TERMINAL MANAGEMENT .....................................................................................................................25

2

ADS DEVELOPMENT GUIDE

6.1

TERMINAL FILE SYSTEM................................................................................................................................. 25

6.2

APPLICATION MANAGER ................................................................................................................................. 26

6.3

MULTI-APP MANAGEMENT ............................................................................................................................. 26

6.3.1 Generate Multi-apps ........................................................................................................................27

6.3.2 Application Switching ....................................................................................................................28
7

DEBUGGING ..................................................................................................................................................29
7.1

SERIAL PORT DEBUG....................................................................................................................................... 30

7.2

DEBUGGING IN APP ......................................................................................................................................... 31

FAQ ...................................................................................................................................................................32
8.1

HOW TO DOWNLOAD PK FILE? ...................................................................................................................... 32

8.1

HOW TO CHANGE OLD DEBUG MODULE TO NEW ONE?............................................................................. 32

8.2

HOW TO CHANGE STARTUP LOGO? ............................................................................................................... 34

8.3

HOW TO SWITCH DOWNLOAD/TEST PROGRAM TO ENGLISH? .................................................................... 34

8.4

HOW TO TURN UP/DOWN THE KEY VOLUME? ............................................................................................. 35

8.5

HOW TO BACKLIGHT TIME INTERVAL? ......................................................................................................... 35

8.6

HOW TO TEST GPRS/3G? ............................................................................................................................... 35

8.7

HOW TO COMPILE ON UBUNTU? ................................................................................................................... 35

8.8

PSAM CARD SLOT ........................................................................................................................................... 36

8.8.1 K320 .......................................................................................................................................................36

8.8.2 K370 .......................................................................................................................................................37
8.8.3 G810.......................................................................................................................................................38
8.8.4 G870.......................................................................................................................................................38
8.8.5 G870(upgrade) ...................................................................................................................................39
3

ADS DEVELOPMENT GUIDE

8.8.6 G3 ...........................................................................................................................................................39

ADS DEVELOPMENT GUIDE

Revision History
Date
2014-11-5

Version
V1.0

Description
1. Draft

Author
Sillin Wu
Steven Guo
Jiang Zhao

ADS DEVELOPMENT GUIDE

Scope
The purpose of this document is to provide a quick start for developer to build the Application
Development Environment (ADE) and run an application on the POS terminal with XGD-ADS
(Application Development Suit of XGD).
The XGD-ADS (Application Development Suit of XGD) includes the following resource, all
available on the FTP server ftp://219.133.170.86:8490 .
Compiling environment (cross compiler, Linux OS(Cent-OS), VirtualBox for Windows/Mac)
Reference/Documents (obtain from /ads-x.xx/xgd-ads-x.xx/doc/ )
SMT(Signature Management Tool: PCISignV0.0.2.13)
Packages of SDK library for different models of POS terminal (K320, K370, G810)
Sample Code(module-based)/Demo Code(transaction-based)
Download Tool/Script (UDiskDL2.0)

Guide Conventions
Various conventions are used to help you quickly identify special formatting. Table 1 describes these
conventions and provides examples of their use.

Convention

Meaning

Blue

Text in blue indicates terms that are cross

referenced, or to provide an URL.

Bold

Bold typeface indicates books, folders,

functions, parameters or emphasis.

Courier

Courier typeface indicates console

commands, or contents of source code.

Example
See Guide Conventions.
http://www.xinguodu.com
ADS DEVELOPMENT GUIDE
manage.so
[root@localhost~]$ ./MakeCore -h

The pencil icon is used to highlight

important information.

Attention:

The attention symbol is used as a warning

when wrong operation might occur.

Table 1
6

ADS DEVELOPMENT GUIDE

1 SMT (Sign Management Tool)

For the sake of security, all the applications are not allowed to be downloaded and run on the
POS terminal before being signed correctly. That means developer must have own RSA key for
signing the application.

1.1 Public Key

There are two public keys named xgd3rd.pk and app.pk, both of which are generated by
developer. The app.pk signed by root_sk.lic is used to verify the signature of application.
The xgd3rd.pk signed by vendor (XGD) is used to verify the validity of the POS terminal.
As shown 1-1:

1-1: key system interface

For how to download xgd3rd.pk & app.pk to the POS terminal, please refer to How to
Download PK File.

ADS DEVELOPMENT GUIDE

Downloading xgd3rd.pk is prior to app.pk and app.pk is prior to the

application.

Developer is responsible for the high security of the key pairs

especially the root_sk.lic. In addition, once the root_pk.lic
(xgd3rd.pk) is downloaded, it can NOT be changed any more.

1.2 Private Key (Sign Key)

Sign key is the private key used to sign the application. It needs to be generated by
developer. As the private key, please keep it secure from other developer.
When compiling the application, the compiler will use it to sign the application file.

1.3 Generating the RSA Key Pair

Open the signature tool PCISignV0.0.2.13.exe and select the KeyGen page.
Configure the version, issuer, serial number and expiry date. Anything inputted of
these parameters is OK.
Select a path for saving the RSA key pair, and name as app.
The interface as shown 1-2:

ADS DEVELOPMENT GUIDE

1-2 Parameter Setting Interface

Generate the RSA key pair including private key app_sk.lic and public key
app_pk.lic.
As shown 1-3:

ADS DEVELOPMENT GUIDE

1-3: Generate Public & Private Key Pair Interface

Select a path for saving the RSA key pair, and name as root.
The interface as shown 1-4:

10

ADS DEVELOPMENT GUIDE

1-4 Parameter Setting Interface

Generate the RSA key pair including private key root_sk.lic and public key
root_pk.lic.
As shown 1-5:

11

ADS DEVELOPMENT GUIDE

1-5: Generate Public & Private Key Pair Interface

1.4

Processes of Generating RSA Key Pair

The developer generates the RSA key pair including private key app_sk.lic

root_sk.lic and public key app_pk.lic , root_pk.lic .

The developer must keep the private key app_sk.lic and root_sk.lic in secure
and send the public key root_pk.lic to the vendor (XGD).
The vendor will sign the public key and send it back to the developer. Developer
should rename the signed public key as xdg3rd.pk. (If the public key is not signed
by the vendor, the POS terminal will regard it as illegal public key).
The developer should sign the public key app_pk.lic by root_sk.lic and renamed
it as app.pk (If the public key is not signed by the vendor, the POS terminal will
regard it as illegal public key). As shown 1-6:

12

ADS DEVELOPMENT GUIDE

1-6 sign public key interfae

The developer downloads the signed public key app.pk and xgd3rd.pk to the
POS terminal.
The developer should put the private key app_sk.lic under a certain directory of
the compiling environment correctly. Then the application can be compiled and
downloaded into the POS terminal successfully.

13

ADS DEVELOPMENT GUIDE

2 Compile Environment
There are two ways for running the compiler which depends on the development environment.

2.1

Linux OS

If the compiler runs on the Linux OS, the following steps shall be performed:
a) Create a new folder under /tmp, ( eg. mkdir /tmp/compiler )

b) Copy all files of ... /compiler/compiler-for-linux to the new folder.

c) Run arm-linux-gcc-3.4.1-setup.sh and freescale-setup.sh to install the compiler

into Linux OS.

14

ADS DEVELOPMENT GUIDE

2.2

Window/Mac OS

If the compiler runs on the Windows or Macintosh, the VirtualBox tool must be
installed to run the virtual machine CentOS for the compiler.
The VirtualBox is a powerful and free software, the developer could get the installing
package and more information from https://www.virtualbox.org/.
The following steps shall be performed:
a) Install the VirtualBox for Windows or Macintosh.

b) Unzip the virtual machine from the package CentOS-6.3.rar.

c) Add the virtual machine CentOS-6.3.vbox to the VirtualBox.

15

ADS DEVELOPMENT GUIDE

d) Create and configure the folder which is shared by the host OS (Windows or
Macintosh) and virtual machine (CentOS). Recommending to create the shared
folder in the root directory of disk C or D (eg. D:\share)

16

ADS DEVELOPMENT GUIDE

17

ADS DEVELOPMENT GUIDE

e) Copy the folder \ads-x.xx\xgd-ads-x.xx\ (x.xx is the version of ADS, such as

1.05/1.07/) to the shared folder.

f) Start and login the virtual machine (CentOS).

Start the virtual machine
The account is root and the password is 123123.
Enter the directory /media/sf_share/xgd-ads-x.xx/ (x.xx is the version of
ADS, such as 1.05/1.07/), all the compiling work shall be done under this
directory.

18

ADS DEVELOPMENT GUIDE

The hot key for returning to the host OS (Windows or Macintosh)

from the virtual machine (CentOS) as bellow:

Left command key is for Machintosh

Right Ctrl key is for Windows

19

ADS DEVELOPMENT GUIDE

3 Building Project
The following must has been completed before building an application project:
Generate the developer root & app RSA key pairs including private keys root_sk.lic
& app_sk.lic and public keys root_pk.lic & app_pk.lic.
The public key root_pk.lic has been signed by vendors(XGD) private key and
renamed as xgd3rd.pk.
The public key app_pk.lic has been signed by root_sk.lic and renamed as app.pk.
The compiler has been installed correctly.

3.1

Introduce

The project includes the follow resource:

The \xgd-ads-x.xx (x.xx is the version of ADS, such as 1.05/1.07/)is the top
directory of the whole project environment. There are four folders (app, doc, lib and
sign) and two files (MakeCore and makefile) in this directory.
app:
All application projects shall be put under this folder.
doc:
All the documents of SDK APIs for development and reference are put under this
folder
lib:
All the libraries and header files shall be put under this folder, including the
libraries and header files of both SDK and the third-party.
sign:
The signature tool xgd_sign and the developer private key app_sk.lic shall be put
under this folder.
MakeCore
A shell for compiling the application projects.
Usage: ./MakeCore [APP DIR] [NAME] [MODE] [FORMAT]

makefile
makefile for the compiling environment.

Before compiling an application, the RSA private key

app_sk.lic for signing application has to be generated and put
under the directory /sign.

20

ADS DEVELOPMENT GUIDE

3.2

Create Project
Create an application project from ads-app-template:

Put the private key app_sk.lic under the directory /sign.

Copy the folder ads-app-template, then paste and rename as a new
application project folder (eg. usr-app-payment).
Put all source files (*.c) under \src and head files (*.h) under \inc, then
all the header files (*.h) shall be included in \inc\global.h.

21

ADS DEVELOPMENT GUIDE

4 Compile
Application compiling process will be explained in detail in this chapter.

4.1

Compiling Guide
The developer could run ./MakeCore h to get the usage of shell MakeCore. Show as
figure 4.1

Figure 4.1

4.2

Compiling Script

22

ADS DEVELOPMENT GUIDE

4.3

Error Message of Compiling

23

ADS DEVELOPMENT GUIDE

5 Download
Step 1

Familiar with XGDs U-disk download tool UDiskDL2.0.

Step 2

Copy download files to the corresponding folder(mtd0/mtd0_dll/mtd0_res).

Step 3

Generate download package by selecting the model.

Step 4

Copy the download package to the U disk.

Step 5

Download on the terminal.

Please Refer to u-disk_download-manual.pdf

24

ADS DEVELOPMENT GUIDE

6 Terminal Management
Terminal Management demonstrates the terminal file system, application manager, multiapplication management and U-Disk download.

6.1 Terminal File System

The terminal file system on linux-based terminal allows user to create, delete and modify
files.
Basically, user only needs to know the following two directories.
5.1.1 /mtd0/dll/
a) application

e.g. 320cncup.so

b) manage.so

multi-application switching

c) libsdk.so/libsdkload.so/libsdkdev.so

middleware

d) libsdk8583.so/libsdkemv.so

ISO8583/EMV libs

...

5.1.2 /mtd0/res/
a) multitask.ini

multi-application configuration file

b) logo.bmp

print and display logo

Attention:

All .so file must be downloaded to /mtd0/dll

25

ADS DEVELOPMENT GUIDE

6.2 Application Manager

Manage, the application manager, which is in charge of the application update and switching.
Current Application: Application is running currently. This application can be the payment
program or Manage.
Default Application: Default application runs after startup. This application is configurable in
multitask.ini.

App1
Multitask.ini
Manage.so

defaultapp=
APP1

Figure 5.3

6.3 Multi-app Management

The flow chart for application management:
Multitask.ini
Manage.so

appnum=
num

App1

Attention:

App2

App3

...

App(num)

Each terminal supports up to 10 applications.

26

ADS DEVELOPMENT GUIDE

6.3.1

Generate Multi-apps

multitask.ini, a very important configurable ini file which is associated with the compiled
applications (*.so). To ensure the application/multi-application run normally on the terminal,
having a basic understanding of how to modify this file is of great importance.
This file consists of three basic elements, section (e.g. [APPNUM]), key (e.g. defaultapp) and value
(870sgscb).
Total number xx of applications,
APP01, APP02, , APPxx , maximum is
10
The default app runs on terminal after
startup.

Entry of TMS download, do NOT

remove or modify this section.

1st application, range from APP01 to

APP10
application ID(870sgscb.so) with
suffix .so removed.
1st Application name displayed on
the candidate applications list

Enable (1) or disable (0) this

application, if disabled, it wont be
displayed on the candidate
applications list when switch app.

27

ADS DEVELOPMENT GUIDE

6.3.2

Application Switching

For example: terminal is running the application (320cncup.so), and wants to run another
application (370cncup.so), and the multitask.ini is correct. Please operate in terminal as
follow instructions.
Step1

Download application binary file (370cncup.so) and configuration file (multitask.ini)

to /mtd0/dll and /mtd0/res respectively.

Step2 Reboot terminal, and the default application is changed to 370cncup

Step3 Press ESC to enter Manage in most of cases, shown in Figure 5.4.2.

Choose application
320cncup
370cncup
Figure5.4.2
Step4

Switch to 320cncup by Up and Down arrows and press Enter to complete the
operation.

The

name 320cncup
multitask.ini file display.

and

370cncup depends

on

the

28

ADS DEVELOPMENT GUIDE

7 Debugging
For the development sample unit, its enabled to output the debug message.
Serial port pinout for each machine model as shown below:

RS232/PINPAD,
/PINPAD,RS232
G870,K320Q,
K320P,G810
GND
RXD (SDK_RS232_PINPAD)
NC
RXD (SDK_RS232_PC)
TXD (SDK_RS232_PC)
NO
TXD (SDK_RS232_PINPAD)
VCC (+5V)

RS232/PINPAD,
/PINPAD,RS232

K370,G870(upgrade),
G3
1
NC
2
GND
3
RXD (SDK_RS232_PINPAD)
4
TXD (SDK_RS232_PINPAD)
5
NC
6
NC
7
NC
8
NC
9
TXD (SDK_RS232_PC)
10
RXD (SDK_RS232_PC)
11
NC
12
NC

If you have own request, please refer to above table.

29

ADS DEVELOPMENT GUIDE

7.1 Serial Port Debug

Attention:

Before debugging, please confirm your terminal works well and the serial cable is
well connected.

Set PC-tool for serial port:

Baud rate:115200

Data Bit: 8

Parity Bit: None

Stop Bit: 1

Flow Control: None

For example:
The HyperTerminal setting as shown in Figure 7.1:

Figure 7.1

30

ADS DEVELOPMENT GUIDE

7.2 Debugging in App

The debugging module supports white & black lists filtration, and various modes for output
debugging info to hyperterminal, terminal screen and terminal paper. Following three steps
indicate how to implement debugging in your code.

31

ADS DEVELOPMENT GUIDE

8 FAQ
8.1 How to Download PK File?

Download xgd3rd.pk:

Step 1

Copy xgd3rd.pk to the corresponding download folder(e.g. K320->1A-> xgd3rd.pk), then

copy the download folder to the U disk.

Step 2

Hold key 2+5+0 and power on the terminal.

Step 3

Select 2.Advance, enter the password 888888 to proceed.

Select 1.Download, then 2.USB Stick and it will prompt Load 3rd PK?
ISSUE:XGD Press [ENT] Load, press ENTER to download.

Step 4

Download app.pk:

To download the app.pk is same as how to download the application, please refer to U Disk

Download Manual.pdf.

8.1 How to Change Old Debug Module to New One?

New debug module, which supports up to three debug modes including hyperterminal(PC&PINPAD
PORT), terminal screen and terminal paper, is more powerful than old one. But when you compile your
application with old debug mode, it will encounter some errors, for which reason, you need to update the
code to change the old debug module to the new one as shown below.
Copy your project to directory \ads-x.xx\xgd-ads-x.xx\app\ (x.xx is the
version of ADS, such as 1.05/1.07/).

Step 1

Replace the makefile under your project with makefile(for application)(Remember

to rename to makefile).

Step 2
Step 3

Include the header file debug.h in your code and delete original sdkDebug.h.

Step 4

Update the source file main.c as shown below:

32

ADS DEVELOPMENT GUIDE

Figure 7.1.1 Old Debug Module

Figure 7.1.2 New Debug Module

Figure 7.1.3 Old Debug Module

33

ADS DEVELOPMENT GUIDE

Figure 7.1.4 New Debug Module

8.2 How to Change Startup Logo?

Terminal Model
K320/K370/G810
G870
G3

Logo Size (Width(pixel) x Height(pixel))

128x64(bit depth: 1)
240x320
320x240
Figure 7.2.1 Logo Format

Step 1

Create the proper logo as per above table.

Step 2

Send the logo to vendor XGD. XGD will sign and send it back to developer.

Step 3

Rename the logo as logo1.bmp and logo2.bmp and copy the two files to the

corresponding download folder(e.g. K320->1A->logo1.bmp+logo2.bmp), then copy the download

folder to the U disk.
Step 4

Hold key 2+5+0 and power on the terminal.

Step 5

Select 2.Advance, enter the password 888888 to proceed.

Step 6

Select 1.Download, then 2.USB Stick to download the logo.

8.3

How to Switch Download/Test Program to English?

Download Program

Step 1

Hold key F2+1(K320)/ F1+1(G810/G870)/ F+1(K370/G3) and power on, then enter
password 556677

Step 2

Press key F2(K320)/ F1(G810/G870)/ F(K370/G3) again, then select 2.

Test Program
Test program is designed to simply test the terminal hardwares and check whether they all work
fine or not. It helps developer tackle the problem encountered during the application
development based on the SDK. If developer recognizes the test program is in Chinese initially,
please follow below steps to switch it to English permanently.
34

ADS DEVELOPMENT GUIDE

Step 1

Hold key F2+3(K320)/ F1+3(G810/G870)/ F+3(K370/G3) and power on, then enter
password 556677

Step 2

8.4

1. -> 6. -> 4. -> 4. -> 2.

How to Turn Up/Down the Key Volume?

Step 1

Hold key F2+3(K320)/ F1+3(G810/G870)/ F+3(K370/G3) and power on, then enter
password 556677

Step 2

1.Unit Test -> 1.Key -> 2.Key Tone -> Scroll up/down to turn up/down the key volume

-> Press ENTER to save it.

8.5

How to Backlight Time Interval?

Step 1

Hold key F2+3(K320)/ F1+3(G810/G870)/ F+3(K370/G3) and power on, then enter
password 556677

Step 2

1.Unit Test -> 2.Display -> 5.BACKLIGHT TIME SET -> Set the time interval -> Press
ENTER to save it.

8.6

How to Test GPRS/3G?

Step 1

Hold key F2+3(K320)/ F1+3(G810/G870)/ F+3((K370/G3) and power on, then enter
password 556677

Step 2

Check the GPRS/3G signal strength, it is better above 10 , otherwise, step3 may failed.

1.Unit Test -> 5.Commun -> 2.Wireless -> 2.Wireless module

Step 3

1.Unit Test -> 5.Commun -> 2.Wireless -> 1.Login

Step 4

Set the correct APN, IP and PORT to connect to XGDs test server:
IP: 219.133.170.86, PORT: 8526

8.7

How to Compile On Ubuntu?

If compiling failed in Ubuntu ,please follow steps as below to resolve the problem:
Step 1

Execute ls /bin/sh -al.

Step 2

If the result displays /bin/sh -> dash instead of /bin/sh -> bash, do step 3

Step 3

Execute sudodpkg-reconfigure dash

35

ADS DEVELOPMENT GUIDE

Step 4

8.8
8.8.1

Select no, then quit and compile again.

PSAM Card Slot

K320

36

ADS DEVELOPMENT GUIDE

8.8.2

K370

37

ADS DEVELOPMENT GUIDE

8.8.3

G810

8.8.4

G870

38

ADS DEVELOPMENT GUIDE

8.8.5

G870(upgrade)

8.8.6

G3

39

ADS DEVELOPMENT GUIDE

The number marked in the picture represents the corresponding card slot number for each
model.

40