Atop ABLELink GW21 MAXI Series Operating instructions

ATOP ABLELinkTM Serial Server
GW21x-MAXI
Software Development Kit
Programming Guide
Version 1.511
Updated at: 2004/05/14
ATOP Technologies, Inc.
Tel: [phone]
Fax: [phone]
E-mail: [email protected]

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
IMPORTANTANNOUNCEMENT
The information contained in this document is the property of Atop Technologies, Inc. and is supplied for the
sole purpose of the operation and maintenance of products of Atop Technologies, Inc. No part of this
publication is to be used for any other purposes, and it is not to be reproduced, copied, disclosed,
transmitted, stored in a retrieval system, or translated into any human or computer language, in any form, by
any means, in whole or in part, without the prior express written consent of Atop Technologies, Inc.
Published by
Atop Technologies, Inc.
2F, No. 146, Sec. 1, Tung-Hsing Rd.
Jubei City, Hsinchu 302
Taiwan, R.O.C.
Tel: [phone]
Fax: [phone]
www.atop.com.tw
Copyright © 2004Atop Technologies, Inc. All rights reserved.
All other product names referenced herein are registered trademarks of their respective companies.
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
FCC WARNING
Class A for Ethernet-Serial Server (Model GW21C-MAXI)
This equipment has been tested and found to comply with the limits for a Class A digital device
pursuant to Part 15 of the FCC rules. These limits are designed to provide reasonable protection
against harmful interference when the equipment is operated in a commercial environment. This
equipment generates, uses and radiates radio frequency energy and, if not installed and used in
accordance with the instructions, may cause harmful interference to radio communications.
Operation of this equipment in a residential area is likely to cause harmful interference in which
case the user will be required to correct the interference at his own expenses.
A shielded-type power cord is required in order to meet FCC emission limits and also to prevent
interference to the nearby radio and television reception. It is essential that only the supplied power
cord can be used.
Use only shielded cables to connect other devices to this equipment by RS-232 / RS-485 ports.
Be cautioned that changes or modifications not expressly approved by the party responsible for
compliance could void your authority to operate the equipment.
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
Contents
1. INTRODUCTION...................................................................................................................8
1.1 PACKAGING...........................................................................................................................8
1.2 PRODUCT DESCRIPTION ........................................................................................................8
2. INSTALLATION...................................................................................................................12
2.1 DEVELOPMENT ENVIRONMENT.............................................................................................12
2.2 ABLELINKTMSERIAL SERVER SDK INSTALLATION.................................................................13
2.3 ABLELINKTM SDK PACKAGE CONTENT................................................................................13
3. DEVELOPMENT DESCRIPTION....................................................................................18
3.1 AP DEVELOPMENT FLOW .....................................................................................................18
3.2 LOCATE APPLICATION PROGRAM ON ABLELINKTM SERIAL SERVER .......................................21
3.3 PROCESS FLOW OF SERIAL SERVER KERNEL .......................................................................22
4ADVANCE COURSE...........................................................................................................26
4.1 SIMULATION ON PC .............................................................................................................26
4.1.1 Simulation Introduction............................................................................................................. 26
4.1.2 Differences Between Serial Server and PC............................................................................. 26
4.2 DOWNLOAD MULTIPLE APPLICATION PROGRAMS ..................................................................28
5.API OVERVIEW...................................................................................................................30
5.1 SERIAL I/O FUNCTIONS OVERVIEW ......................................................................................30
5.2 AUDIO & LED FUNCTION OVERVIEW....................................................................................31
5.3 DOS FUNCTION OVERVIEW.................................................................................................31
5.4 TCP/IP FUNCTION OVERVIEW .............................................................................................31
5.5 MEMORY FUNCTION OVERVIEW ...........................................................................................33
5.6 TIMER INTERRUPT HANDLING FUNCTION OVERVIEW .............................................................33
5.7 WATCH DOG TIMER OVERVIEW............................................................................................34
5.8 ADVANCED SERIAL PORT API (IN COMAPI.OBJ).....................................................................34
5.9 DIGITAL INPUT AND DIGITAL OUTPUT OVERVIEW ...................................................................35
5.10 REAL TIME CLOCK OVERVIEW............................................................................................35
5.11 ACCOUNT OVERVIEW.........................................................................................................36
5.12 WIRELESS LAN COMMAND OVERVIEW...............................................................................36
6.API REFERENCE...............................................................................................................39
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
INITSERIALMODE()....................................................................................................................39
SENDSERIALDATA()...................................................................................................................40
GETSERIALDATA().....................................................................................................................40
GETSERIALSTATUS().................................................................................................................41
ENABLESERIALHWINTR() ..........................................................................................................41
DISABLESERIALHWINTR() .........................................................................................................42
ENABLERS485RX()...................................................................................................................42
ENABLERS485TX() ...................................................................................................................42
SERIALINTREOI()......................................................................................................................43
SET485TYPE()..........................................................................................................................43
GET485TYPE()..........................................................................................................................44
GETPORTTYPE()........................................................................................................................44
GETCONSOLESTA .....................................................................................................................44
GETNEWPORTTYPE ...................................................................................................................45
GETTOTALPORT........................................................................................................................45
COM_CONFIG().........................................................................................................................46
COM_GETBUF()........................................................................................................................46
COM_PUTBUF()........................................................................................................................47
COM_CLEARRXQUE()...............................................................................................................48
COM_CLEARTXQUE() ...............................................................................................................48
COM_TXQUEISEMPTY()............................................................................................................48
COM_DTR_ACTIVE() ................................................................................................................49
COM_RTS_ACTIVE().................................................................................................................49
COM_DSR_STATUS()................................................................................................................50
COM_CTS_STATUS()................................................................................................................50
BUZZERON().............................................................................................................................50
SETUPCOMLED() ......................................................................................................................51
SETUPPROCESSLED()...............................................................................................................51
GETINTRVECTOR()....................................................................................................................52
SETINTRVECTOR() ....................................................................................................................52
GETVERSION()..........................................................................................................................53
SYSTEM_RESET() .................................................................................................................54
SETAPSERIALNO......................................................................................................................54
GETAPSERIALNO......................................................................................................................54
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
GETGWMODEL .........................................................................................................................55
TCP_CONNECT()........................................................................................................................55
TCP_LISTEN()............................................................................................................................57
TCP_DISCONNECT()...................................................................................................................57
TCP_SEND()..............................................................................................................................58
TCP_RECEIVE() .........................................................................................................................59
TCP_GETDATA().........................................................................................................................60
UDP_OPEN()..............................................................................................................................61
UDP_CLOSE()............................................................................................................................61
UDP_RECEIVE().........................................................................................................................62
UDP_RECEIVEX().......................................................................................................................63
UDP_SEND()..............................................................................................................................64
UDP_RESET()............................................................................................................................65
GETLOCALIPADDR()..................................................................................................................66
GETLOCALETHADDR() ..............................................................................................................66
GETDEFAULTGATEWAY() ...........................................................................................................67
GETLOCALNETMASK()...............................................................................................................68
ERASESECTOR().......................................................................................................................68
PROGONEBYTE()......................................................................................................................69
PROGSTRING() .........................................................................................................................70
READEEPROM()......................................................................................................................71
WRITEEEPROM() ....................................................................................................................72
READMACEEPROM()...............................................................................................................72
WRITEMACEEPROM() .............................................................................................................72
WATCHDOGCTRL()....................................................................................................................73
CLRWATCHDOGTIME()..............................................................................................................73
SETUPWATCHDOGTIME()..........................................................................................................74
SETIOMODE()...........................................................................................................................74
GETIOMODE() ..........................................................................................................................74
SETOUTSTATE()........................................................................................................................75
GETINSTATE()...........................................................................................................................75
READRTCTIME.........................................................................................................................75
READRTCDATE ........................................................................................................................76
WRITERTCTIME........................................................................................................................76
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
WRITERTCDATE .......................................................................................................................77
ENABLEWRPROTECT................................................................................................................77
DISABLEWRPROTECT...............................................................................................................77
GETSTARTUPTIME.....................................................................................................................78
GETTICKTIME ...........................................................................................................................78
GETSYSTIME ............................................................................................................................78
ADDACCOUNT...........................................................................................................................79
DELACCOUNT ...........................................................................................................................80
VERIFYACCOUNT.......................................................................................................................80
GETESSID (FOR GW51W-MAXI ONLY).........................................................................................81
SETESSID (FOR GW51W-MAXI ONLY).........................................................................................81
GETFRAME (FOR GW51W-MAXI ONLY).........................................................................................81
SETFRAME (FOR GW51W-MAXI ONLY).........................................................................................82
GETFRAGMENT (FOR GW51W-MAXI ONLY)...................................................................................82
SETFRAGMENT (FOR GW51W-MAXI ONLY)...................................................................................83
GETCHANNEL (FOR GW51W-MAXI ONLY).....................................................................................83
SETCHANNEL (FOR GW51W-MAXI ONLY).....................................................................................83
GETNETWORKTYPE (FOR GW51W-MAXI ONLY)...........................................................................84
SETNETWORKTYPE (FOR GW51W-MAXI ONLY)............................................................................84
GETTRANSMITRATE (FOR GW51W-MAXI ONLY)............................................................................84
SETTRANSMITRATE (FOR GW51W-MAXI ONLY)............................................................................85
GETXI300WEPFLAG (FOR GW51W-MAXI ONLY)..........................................................................85
SETXI300WEPFLAG (FOR GW51W-MAXI ONLY)..........................................................................86
GETXI300WEPBIT (FOR GW51W-MAXI ONLY).............................................................................86
SETXI300WEPBIT (FOR GW51W-MAXI ONLY).............................................................................87
GETXI300WEPKEY (FOR GW51W-MAXI ONLY)............................................................................87
SET XI300WEPKEY (FOR GW51W-MAXI ONLY)...........................................................................87
GETRFREALCHANNEL (FOR GW51W-MAXI ONLY)........................................................................88
GETRFTXRATE (FOR GW51W-MAXI ONLY)..................................................................................88
GETAPNAME (FOR GW51W-MAXI ONLY)......................................................................................88
GETAPMAC (FOR GW51W-MAXI ONLY)........................................................................................89
APPENDIXA: SERIAL PORT CONFIGURATION TABLE.............................................90
APPENDIX B. UPGRADE SYSTEM SOFTWARE...........................................................93
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
B.1 UPGRADE PROCEDURES.....................................................................................................93
B.2 CRITICAL ISSUES OF UPGRADING.........................................................................................94
B.3 ERROR MESSAGES .............................................................................................................94
APPENDIX C：SAMPLE PROGRAM................................................................................98
C.1 TCP/IP SAMPLE PROGRAM .................................................................................................98
C.2 SERIAL PORT SAMPLE PROGRAM .......................................................................................102
APPENDIX D. CONFIGURATION UTILITY.....................................................................105
D.1 RUN THE UTILITY...............................................................................................................105
D.2 DETECTING OPERATIONAL CONTROLLERS AND DEVICES....................................................106
D.3 CONFIGURING CONTROLLERS AND DEVICES......................................................................107
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
1. Introduction
1.1 Packaging
 GW21x-MAXI ABLELinkTM Embedded Serial Server x 1.
 Product CD containing Software Development Kit (SDK).
 Optional Components
 GW21S-EVM Evaluation Module x 1.
 Power adapter, input : 120/220V AC, output : 12V DC
1.2 Product Description
The ATOP ABLELinkTM Embedded Serial Server is a powerful, low-cost and compact unit. The Embedded
Serial Server offers one RS-232/ RS-485 port, one Ethernet (100BaseT), one Watch Dog Timer and etc. With
these I/O modules and a customized application program, the Embedded Serial Server becomes a powerful
device for communication controls and monitoring.
A DOS-like development toolkit is provided for developing and downloading applications from a PC on the
network to the Serial Server through Ethernet. With the built-in TCP/IP engine, the Serial Server can then
communicate local area network directly. In versatile applications, it can function as a gateway between field
devices and cell controller. By using the RS-232/RS-485 ports, it functions as a gateway between field bus
and Ethernet.
The development toolkit is ATOP ABLELinkTM Embedded Serial Server SDK. It contains a set of API library,
sample programs, development utilities, a download utility and a configuration utility. You can develop an
application program in a PC-based environment. After you develop the application program, you can
download the application program to the Serial Server. Then the Serial Server can work as you wish.
The Serial Server Software Development Kit (SDK) is a PC-based software package for developing specific
applications on the Serial Server. There are two important types of applications.
 The application that handles the TCP/IP communication protocol and data exchange between the
Serial Server and a host computer.
 The application that handles the RS-232/RS-485 communication protocol and data exchange
between the Serial Server and field devices.
The system architecture may be like Figure 1.1.
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
Figure 1.1 System Architecture of GW21x-MAXI Applications
The GW21x-MAXI is one model of ATOP Embedded ABLELinkTM Serial Servers. Please refer to Figure 1.2
GW21x-MAXI Front View. There is a Evaluation Module that provides power connector, RJ-45 connector of
Ethernet, D-type 9 pin connector of RS-232, LEDs, … for GW21x-MAXI to make you more easer to do
testing on GW21x-MAXI. About detailed information please refer to “GW21x-MAXI User Manual”. This
document describes how to develop an application been run in GW21x-MAXI.
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
Figure 1.2 GW21x-MAXI+ Front View
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
2. Installation
2.1 Development Environment
The application program of the Serial Server is developed in the PC environment. After the application
program is developed and ready, you can download it to the Serial Server. The Serial Server with the specific
application program will be ready the next time the power is turned on.
During application development stage, you may simulate the application program in the PC environment. If the simulation is OK, you
can compile and link the application again for the Serial Server and then download the application program to the Serial Server to
perform test on it.
The developing environment is as followings:
Development environment: DOS, Win95, Win98, NT, Win Me, Win2000
Simulation environment: DOS, Win95, Win98
Development tools: Please see the following table.
Tool Vendor Remark
MSC 6.00A
MSC 7.X
MSVC 1.X
MicrosoftTM 16 bits Compiler, *note 1.
MASM 5.X or later MicrosoftTM
Locate Utility System & Software, Inc
Serial Server API ATOPTM Serial Server Library
Download Utility ATOPTM Download AP
Packet Driver LAN card Maker Simulation only, see*note 2.
TCP/IP for MS-DOS ATOPTM Simulation only, see *note 2.
Table 2-1 Development Tools
Note:
1. These compilers have been tested and found fully compatible with the ATOP ABLELinkTM Serial
Server. The final version is MSVC 1.52.
2. For debugging and simulation purpose. Please refer to section 4.1 for more details.
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
2.2 ABLELinkTM Serial Server SDK Installation
Step 1
： Copy all the files to local disk
MD C:\GW21S2 <ENTER>
CD C:\GW21S2 <ENTER>
XCOPY CD-ROM Drive: *.* /S <ENTER>
Step 2
： Rebuild MSC library
CD C:\GW21S2\NEWLIB <ENTER>
Edit “MEMU.BAT” to select MSC6.0,MSC7.0,or later and model.
Edit “MAKEFILE” to set the 'SRC' field to the correct path name of MSC library.
MEMU <ENTER>
COPY C:\GW21S2\NEWLIB\SSILCE.LIB C:\GW21S2\LIB
Step 3
： Installation OK
You can now start creating your applications based on SDK sample program.
Note:
The host (PC) AP can use the standard MSC library, but the ABLELinkTM Serial Server AP can
only use the rebuilt MSC library resides for example in the “C:\GW21S2\NEWLIB” directory.
2.3 ABLELinkTM SDK Package Content
Directory File Name Descriptions
… \BIN\ DAPTCPIP.EXE ：TCP/IP driver for MS-DOS
HOST.CFG ：accessory file of DAPTCPIP.EXE, it is the
TCP/IP configuration file for MS-DOS
PC_TCPIP_START.BAT ：a batch file to startup TCP/IP driver in PC
PC_TCPIP_STOP.BAT ：a batch file to stop and remove TCP/IP driver in
PC
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
EXE2OMF.EXE ：locate utility for converting .EXE file to .OMF file
XOH86.EXE ：accessory utility of location, it converts .OMF file
to .HEX file
DOS4GW.EXE ：accessory file for locate utility
…\LIB\ DAPAPI.LIB ：API library of GW21x-MAXI, including BIOS, DOS,
TCP/IP, … API functions
STARTUP1.OBJ ：application startup program, must be included and be
the first object file when linking to execution file
STARTUP2.OBJ ：application startup program, must be included and be
the first object file when linking to execution file
The "STARTUP1.OBJ" does not support floating
operation and changing stack size (always 4 kb).
Using "STARTUP2.obj" and "stackf.asm"(in "source\"
directory) to solve these 2 problems.
If you want to use floating operation or change the
stack size, please use the "STARTUP2.obj" to replace
the "STARTUP1.obj" and then edit the "stackf.asm".
(Note: Update "STACK_SIZE" and "FLOAT" symbol in
"makefile" are useless. Please update "stackf.asm"
directly.)
COMAPI.OBJ ：advanced serial port API, using hardware interrupt
service routine to send and receive serial port data
COMALO.OBJ ：accessory file of COMAPI.OBJ, to tune the size of
send and receive buffer in this file
…\INC\ GW_API.H ：a generic include file, it contains following include files.
You can just only include this file
DAPAPI.H ：type and constant definition and declare functions of
BIOS, DOS API
TCPAPI.H ：declare functions of TCP/IPAPI
TCPDEF.H ：type and constant definition of TCP/IPAPI
COMAPI.H ：declare functions of serial port API
…\NEWLIB\ EMINIT.OBJ ：for 8087 emulation mode library
MAKEFILE ：make file for re-building MSC library
MEMU.BAT ：batch file for re-build MSC library
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
REMOVE.C6 ：input file for re-building MSC 6.00Alibrary
REMOVE.C7 ：input file for re-building MSC 7.00 or later library
…\SOURCE\ COM.MAK ：a makefile to compiler advanced serial port API, after
compiler you should copy object file to the “…\LIB\”
directory
COMAPI.C ：advanced serial port API, using hardware interrupt
service routine to send and receive serial port data
COMALO.C ：accessory file of COMAPI.C, to tune the size of send
and receive buffer in this file
TIMER.C ：to create and get system timer counted from startup
STACKF.ASM ：using this file to change stack size
… \SAMPLE\ \VB_TCP\ ：a VB TCP sample program, in host side (PC)
\WINSOCK_TCP\ ：a C TCP sample program, in host side (PC)
\GW21_CMD\ ：R/W flash memory sample program
\GW21_COM\ ：a serial port sample program
\GW21_COM2\ ：a serial port sample program for RS485(2 wires)
\GW21_CONNECT\ ：a TCP client sample program
\GW21_FUNC\ ：an API sample program, include LED control, get
system time and watchdog control
\GW21_Listen4\ ：a TCP server sample program (4 connections)
\GW21_FLOAT\ ：a sample program to calculate floating data
\GW21S3_TCP&COM\ ：a TCP server and serial port sample program
\GW21S3_TCP&COM2\ ：a TCP server and serial port sample program with
communication handshaking
… \CONFIG\ MONITOR.EXE ：a configuration utility for GW21x-MAXI
SEG.CFG ：accessory file of MONITOR.EXE
… \DOC\ GW21x-MAXI SDK
Reference Guide.doc ：a SDK document of GW21x-MAXI
… \DOWNLOAD\ GWDL.EXE ：a download firmware utility for GW21x-MAXI
DAPDL.CFG ：accessory file of GWDL.EXE
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
DOWNLOAD.BAT ：a batch file to download firmware to GW21x-MAXI
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
3. Development Description
3.1 AP development flow
Before developing an application program, please install Microsoft C 6.0 or above (16 bits complier)
and GW21x-MAXI SDK. For more information, you can refer chapter 2.
The process flow of developing an application program is as following:
AP
C ASM
COMPILER
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.
Al
l
AP
.OB
MSC
.LIB
LINK
USERLOC.CMD AP
.EXE
AP
OMF
EXE2HEX
XOH86

SDK Programming Guide Version 1.511
ABLELinkREthernet-Serial Server MAXI Series
AP
.HEX
D
O
W
N
Figure 3-1 Program Flow Diagram
Step 1. Setup environment parameters
1. Run the batch file to setup Microsoft C environment parameters. Then you can compiler and link
application program. The batch file is provided in Microsoft compiler. For example, it may be
“msc6.bat” in Microsoft C compiler \bin directory. To run the batch file may be like following:
2. Append the SDK \BIN directory to the system environment parameter: PATH. Then you can use
SDK utilities in any directory.
Step 2. Write your application program
You can write your application program by any text editor.
Step 3. Compile your application program
After writing application program, you can compile the program. The C compiler option arguments
are ”/AL /Zi /Gs /c /Oi /I. /Fpi”. For example, to compile ‘userap.c’ is as following: cl /AL /Zi /Gs /c
/Oi /I. /Fpi userap.c.
Copyright © 2004 Atop Technologies, Inc.
All rights reserved. Designed in Taiwan.