PalmMicro AR1688 User manual

Communications, Inc.
© 2006-2007 PalmMicro Communications, Inc.
Room 0611, Bldg.B Tsinghua Tongfang Technology Plaza, 1 Wangzhuang Road, Beijing, CHINA
1
AR1688 Based IP Phone
Development Guide

Communications, Inc.
© 2006-2007 PalmMicro Communications, Inc.
Room 0611, Bldg.B Tsinghua Tongfang Technology Plaza, 1 Wangzhuang Road, Beijing, CHINA
2
Table of Contents
1Program Structure.......................................................4
AR1688 Program Directory........................................................................ 4
Bin Directory................................................................................................. 4
Doc Directory................................................................................................ 4
Include Directory .......................................................................................... 4
lib Directory .................................................................................................. 4
mcs51 Directory............................................................................................ 4
Src Directory................................................................................................. 5
Tool Directory ............................................................................................... 5
AR1688 Program Structure........................................................................ 5
page0 – page11 ............................................................................................ 6
page12 – page31.......................................................................................... 7
2Program Compile .........................................................8
Compile Environment................................................................................. 8
Program File................................................................................................ 8
Compile Operation...................................................................................... 9
mk.bat Batch File.......................................................................................... 9
clean.bat Batch File ....................................................................................12
3Update.......................................................................... 13
Tftp Update.................................................................................................13
Update Program...........................................................................................13
Update Ring Tone........................................................................................14
Update Call Hold Music...............................................................................14
Update Settings...........................................................................................14
Read Phone Information .............................................................................14
HTTP Update...............................................................................................15
Firmware......................................................................................................16
Settings........................................................................................................16
Phonebook...................................................................................................16
Ringtone File ...............................................................................................16
Call Hold Music File ....................................................................................17
4Debug........................................................................... 18
How To Enter Safe Mode...........................................................................18
Check Date Information ............................................................................18
Test In Safe Mode ......................................................................................18

Communications, Inc.
© 2006-2007 PalmMicro Communications, Inc.
Room 0611, Bldg.B Tsinghua Tongfang Technology Plaza, 1 Wangzhuang Road, Beijing, CHINA
3
5Command And Batch File......................................... 19
Convert.exe Command ..............................................................................19
Command Format ........................................................................................19
Command Operation....................................................................................19
getopt.bat and setopt.bat .........................................................................24
getpb.bat and setpb.bat............................................................................25
6Create Music File....................................................... 26
Record Music..............................................................................................26
Cut Music File ............................................................................................27
Update Music File ......................................................................................27
Do Not Upgrade “Long” Ring Tone..........................................................28
7HTTP Auto-Provisioning........................................... 29
Settings file and firmware file .................................................................29
Preparing settings file.................................................................................29
Preparing firmware file................................................................................29
Set server address and port.....................................................................29
Auto-upgrade settings file and firmware file.........................................30
8How To Modify WEB Page ........................................ 31
mkweb.bat and mkweball.bat ...................................................................31
mkweb.bat....................................................................................................31
mkweball.bat................................................................................................32
Modify Language........................................................................................32
Modify Page Layout...................................................................................34
Delete Option .............................................................................................35
9How To Add Regional and Language ..................... 36
10 How To Change MAC Address................................. 38
11 Manager Tool .............................................................. 39
Setting phone.............................................................................................39
Other Function ...........................................................................................39
Update Program...........................................................................................39
Read/Write Phone Settings.........................................................................40
Read/Write PhoneBook ...............................................................................40
Debug Function ...........................................................................................40

Communications, Inc.
© 2006-2007 PalmMicro Communications, Inc.
Room 0611, Bldg.B Tsinghua Tongfang Technology Plaza, 1 Wangzhuang Road, Beijing, CHINA
4
1 Program Structure
We provide software API for all AR1688 IP phone authorized manufacturers and end
users. The API includes part of source codes and part of object files. Those source codes
are provided under GPL license. Based on the API, users can make their own customized
upgrade binary files for their IP phones. We do not provide fully open source software
because we do not encourage those implementations to be transferred to another chip to
compete with AR1688.
To understand the API better, I am going to list details and add explanations below. The
API is provided as SDCC.rar file. It will decompress SDCC directory and files. We assume
SDCC directory is decompressed to disk C:. If it is not, you will need to change the first
line of sdcc\src\makefile.
AR1688 Program Directory
Currently there are following 6 directories under SDCC.
Bin Directory
The directory includes: SDCC open source compiler binary files and our own special tools
binary files. We are using SDCC 2.7.0 steady version. You can also download those files
directly from SDCC official website (http://sdcc.sourceforge.net/). The SDCC.exe is
smaller than the official website one because we only compiled Z80 part in the .exe file.
GNU make.exe utility is also here.
Doc Directory
.txt files. There are some illustrative files in this directory.
Include Directory
.h files. We only use SDCC compiler, do not use any include and library files from the
official SDCC. All .h files are written by ourselves, there might be small difference of
parameters compared with standard c runtime routines. And not all c runtime routines are
included, only those needed are there. We are doing this for performance.
lib Directory
It is not actually "library" file, instead, there are object files in this directory, those object
files are compiled from those source files which are not in API source code, and are to be
linked together with other files in link stage. Same as "include", there are no standard
SDCC library used in our project.
mcs51 Directory

Communications, Inc.
© 2006-2007 PalmMicro Communications, Inc.
Room 0611, Bldg.B Tsinghua Tongfang Technology Plaza, 1 Wangzhuang Road, Beijing, CHINA
5
Although the IP phone reference design based on AR168M VOIP module and an external
MCS8051 UI controller is for demo purpose, it actually can be used in real production and
still maintain a very low BOM cost, because the MCS8051 we used is also very
cost-effective. Here listing some details of the open source software in SDCC\mcs51.
1. Compile with open source SDCC compiler, using small memory mode.
2. Can NOT be upgraded by software on board, need a programmer to make change if
needed.
3. Interface with 2x16 LCD, 8x6 keys and 4 LEDs.
4. Extra 4 LEDs if P4 port is available (on those Winbond devices we are testing).
5. Used 141 bytes of data and idata (means that we actually need a standard 8052 which
has 256 bytes internal RAM).
6. Used 2797 bytes of code space, including extended ISO-8859-1 fonts for 2x16 LCD (a
4K ROM 8052 is enough, cost about 0.5 USD).
7. UART at 19200 bps, 8 bit data, 1 stop, no parity check.
8. Oscillator at 22.1184Mhz.
Src Directory
Open source files, including makefile and batch files to generate upgrade binary file. All UI
related and VOIP protocol related implementations are provided in source code.
Measured in source code size, over 80% are open source in this API.
Tool Directory
Full source code of those special tools in "bin" directory, in Visual Studio 2008 or MS
Visual C++ 6.0 project.
AR1688 Program Structure
AR1688 series phones use Program Flash with 2M bytes. Details as follows:
structure, each page has 64k
page0 -- boot.bin and safemode.bin, ar168x_none_xx_xxxxxx.bin
page1 -- settings.dat, options, flags, digitmap and address book
page2 -- ring tone in g.711 u law, part 1
page3 -- ring tone in g.711 u law, part 2
page4 -- ring tone in g.711 u law, part 3
page5 -- hold music in g.711 u law, part 1
page6 -- hold music in g.711 u law, part 2
page7 -- hold music in g.711 u law, part 3
page8 -- GB font, part 1
page9 -- GB font, part 2
page10 -- GB font, part 3

Communications, Inc.
© 2006-2007 PalmMicro Communications, Inc.
Room 0611, Bldg.B Tsinghua Tongfang Technology Plaza, 1 Wangzhuang Road, Beijing, CHINA
6
page11 -- GB font, part 4
page12 -- test_z80.bin and main.bin, ar168x_xxxx_xx_xxxxxx.bin
page13 -- bank 2&3
page14 -- bank 4&5
page15 -- bank 6&7
page16 -- http data
page17 -- G.711, G.726, GSM 6.10 and AEC DSP data
page18 -- G.729 DSP data
page19 -- iLBC DSP data
page20 -- reserved for DSP data
page21 -- reserved for DSP data
page22 -- copy 2 of test_z80.bin and main.bin, ar168x_xxxx_xx_xxxxxx.bin
page23 -- copy 2 of bank 2&3
page24 -- copy 2 of bank 4&5
page25 -- copy 2 of bank 6&7
page26 -- copy 2 of http data
page27 -- copy 2 G.711, G.726, GSM 6.10 and AEC DSP data
page28 -- copy 2 G.729 DSP data
page29 -- copy 2 iLBC DSP data
page30 -- copy 2 reserved for DSP data
page31 -- copy 2 reserved for DSP data
The Flash 2M memory space is divided into 32 pages of 64K each. The 32 pages are
divided into 2 parts, page0 -- page11 and page12 -- page31.
page0 – page11
Each page is described as follows:
ypage0: for safe-recovery function and start function;
ypage1: for storing phone setting information and flag data and call rule data and
phone book data;
ypage2 -- page4: for storing phone ring data;
ypage5 -- page7: for storing call hold music data;
ypage8 -- page11: for storing font data;
The size of data in page1 is 64k. The data are divided into three parts, phone current
settings data with 16K, default settings data with 16K and phone book data with 32k.
Phone setting data include flag bits, setting options and call rule data, whose filename is
settings_xxx.dat; phone book includes 128 items presently, whose filename is
phonebook.dat.
The size of ring tone data in page2 -- page4 must be 192K(3×64K), namely 196608 bytes,
and the filename format is ringtone_xxx.dat, where xxx are any strings.

Communications, Inc.
© 2006-2007 PalmMicro Communications, Inc.
Room 0611, Bldg.B Tsinghua Tongfang Technology Plaza, 1 Wangzhuang Road, Beijing, CHINA
7
The size of call hold music data in page5 -- page7 must be 192K(3×64K), namely 196608
bytes, and the filename format is holdmusic_xxx.dat, where xxx are any strings.
The size of font data in page8 -- page11 must be 256K(4×64K), and the filename format
is font.dat.
page12 – page31
This part is for main program, protocol program, http data and DSP data.
page12 – page31 are divided into 2 parts with the same contents, which is a safety
characteristic of the AR1688. page12 – page19 is section 1 and the data starts in page 12.
page22 – page31 is section 2 and the data starts in page 22. We distinguish the two parts
from each other by the configuration option “system_page”. When configured as
“system_page=12”, the phone will boot from section 1 and from section 1 and let the
phone program update the software in section 2. When it is set to “system_page=22”, the
phone will boot from section 2 and let the phone update the software stored in section 1.
By separating and duplicating the software, we avoid failures that could be caused by any
errors that may occur while the program is updating.
The space for phone main program, http data and DSP data are 10 pages, namely 10×
64K＝640K, and the programs run in corresponding section according to flag setting.
Pages of this part are as follows:
ypage12 -- page15: phone main program;
ypage16: for storing phone http data;
ypage17 -- page21: for storing phone DSP data;
ypage22 -- page25: the same as page12 -- page15.
ypage26: the same as page16;
ypage27 -- page31: the same as page17 -- page21;
Note:
Other pages are in development and reserved.

Communications, Inc.
© 2006-2007 PalmMicro Communications, Inc.
Room 0611, Bldg.B Tsinghua Tongfang Technology Plaza, 1 Wangzhuang Road, Beijing, CHINA
8
2 Program Compile
Compile Environment
Compile AR1688 with SDCC compiler. The configuration of compile path is in the file
D:\sdcc\src\makefile and the configuration determines location of compiler and program.
Makefile is as follows:
PATH_SDCC=C:\SDCC
Compiler and program directory SDCC are in disk C:, namely C:\SDCC, which is default
setting.
Program File
The program file is a binary file and rules for a file name are
hardware_protocol_language_OEM_version.bin
Example: ar168x_sip_cn_oem_032000.bin.
“hardware”, “protocol”, “language” and “oem” correspond with parameters in mk command.
For more details see the chapter about mk command.
“version” denotes the API program version that is defined in C:\sdcc\src\version.h, they
are: #define SOFT_VER_HIGH 0
#define SOFT_VER_LOW 3
#define SOFT_VER_BUILD 2
#define ENG_BUILD_HIGH 0
#define ENG_BUILD_MID 0
#define ENG_BUILD_LOW 0
The program file includes a safe-recovery mode program file and a phone update program
file, as follows:
1) safe-recovery mode program file
The safe-recovery mode program file is the update file for page0. While parameter
[protocol] in mk command is “none”, this file is created.
Note:
ySafe-mode program file is called page0 updating file for short in the later description.

Communications, Inc.
© 2006-2007 PalmMicro Communications, Inc.
Room 0611, Bldg.B Tsinghua Tongfang Technology Plaza, 1 Wangzhuang Road, Beijing, CHINA
9
yCompiling page0 is not supported by our provided API programs.
2) The file is for the program to upgrade phone.
The space for phone main program, http data and DSP data are 10 pages, namely 10×
64K＝640K, and the program runs on page12-page21 or page21-page31. At present, 4
pages are for the main program, 1 page for http data and 5 pages for DSP data. So the
size of updating program file is 10×64K=640K. Details as follows:
yMain program: codes part of all functions for AR1688 series products;
yhttp data: files in src\res directory for web exploring, including multi-language;
yDSP data: all kinds of algorithm data, include PCMU, PCMA, G.726-32, GSM 6.10,
G.729, iLBC and Speex;
Note:
yIf there no http data and DSP data, programs for updating phone can’t be created;
yHttp data files include Chinese, English, French, Italian, Brazil, Spain, Romania,
Russia and Turkey;
yPhone program file includes only one protocol. According to [protocol] parameter
value to select protocol web configure file. [protocol]=SIP, import settings_sip.htm
and [protocol]=IAX2, import settings_iax2.htm;
Compile Operation
Compile operation of AR1688 runs on DOS environment. Enter the directory C:\sdcc\src\,
which includes compile (mk.bat) and clean (clean.bat) bat file, as follows:
mk.bat Batch File
mk.bat compiles source codes and produces program files. mk.bat calls reversion.exe,
make.exe and namebin.exe commands to compile and produce programs. Above three
commands are in the directory C:\sdcc\bin and will be described in chapter 4.
mk.bat syntax:
mk [hardware] [protocol] [language] [OEM] (Enter)
The 4 paramters are all defined in C:\sdcc\src\version.h.
yHardware: the type for the phone, defined as VER_XXXX in version.h. The value
for this parameter in mk command is “XXXX” that must be lowercase. In version.h,
they are:
// General version config
//#define VER_AR168C
//#define VER_AR168D
//#define VER_AR168DS

Communications, Inc.
© 2006-2007 PalmMicro Communications, Inc.
Room 0611, Bldg.B Tsinghua Tongfang Technology Plaza, 1 Wangzhuang Road, Beijing, CHINA
10
//#define VER_AR168E
//#define VER_AR168F
//#define VER_GF302
//#define VER_YWH201
//#define VER_AR168G
//#define VER_GP1266
//#define VER_BT2008
//#define VER_QX900W
//#define VER_SENSOR
//#define VER_AR168I
//#define VER_AR168J
//#define VER_AR168K
//#define VER_GP2266
//#define VER_AR168L
//#define VER_AR168LS
//#define VER_AR168M
//#define VER_AR168MS
//#define VER_BT2008N
//#define VER_FWV2800
yProtocol: the protocol for the phone, defined as CALL_XXXX in version.h. The
value for this parameter in mk command is “XXXX” that must be lowercase. In
version.h, they are:
// Protocols
//#define CALL_H323
//#define CALL_SIP
//#define CALL_MGCP
//#define CALL_IAX2
//#define CALL_COMM // for speech codec module
//#define CALL_NONE // for safe-recovery mode
Note: CALL_NONE means creating an update file for page0.
yLanguage: the language for the phone, defined as RES_XX in version. The value
for this parameter in mk command is “XX” that must be lowercase. In version.h,
they are:
// Country and District
#define RES_CN
#define RES_US