Moxa Technologies NPort PCG Manual

Programmable Communication Gateway
Programmer’s Guide
First Edition, April 2003
Moxa Technologies Co., Ltd.
Tel: [phone]
Fax: [phone]
www.moxa.com
[email protected]

Programmer’s Guide for NPort PCG
The software described in this manual is furnished under a license agreement and
may be used only in accordance with the terms of that agreement.
Copyright Notice
Copyright 2003
Moxa Technologies Co., Ltd.
All rights reserved.
Reproduction without permission is prohibited.
Trademarks
MOXA is a registered trademark of
Moxa Technologies Co., Ltd.
All other trademarks or registered marks in this manual belong to their respective
manufacturers.
Disclaimer
Information in this document is subject to change without notice and does not
represent a commitment on the part of Moxa.
Moxa provides this document “as is,” without warranty of any kind, either
expressed or implied, including, but not limited to, the particular purpose. Moxa
reserves the right to make improvements and/or changes to this manual or the
product(s) and/or program(s) described herein at any time.
Information provided in this manual is intended to be accurate and reliable.
However, Moxa Technologies assumes no responsibility for its use, or for any
infringements on the rights of fourth parties which may result from its use.
This manual could include unintentional technical or typographical errors.
Changes are periodically made to the information herein, with the changes
incorporated into new editions of the publication.

MOXA Internet Services
Customer satisfaction is our number one concern. To ensure that customers
receive the full benefit of our products, Moxa Internet Services has been set up to
provide technical support, driver updates, product information, and user’s manual
updates.
The following services are provided:
E-mail for technical support
address: [e-mail]
World Wide Web site for product information
address: http://www.moxa.com
or
http://www.moxa.com.tw

Table of Contents
1. Introduction ................................................................................... 1-1
Moxa OS ...................................................................................................1-1
SDK (Software Development Kit) ............................................................1-1
User Application Space ..................................................................1-2
SDK Function Group Overview.....................................................1-2
2. Installing SDK ................................................................................ 2-1
System Requirements ................................................................................2-1
Installing SDK...........................................................................................2-2
Desktop Icons............................................................................................2-3
Setting Up Environment Variables ............................................................2-3
3. Developing User Applications ..................................................... 3-1
Application Development Flow.................................................................3-1
Development System.................................................................................3-2
Source Code Editing..................................................................................3-3
Compiling and Linking your Application..................................................3-3
Creating a Make File ......................................................................3-3
Generating a COM file...................................................................3-4
Using COM2AP ........................................................................................3-4
Intellectual Property Protection......................................................3-4
Embedding a Private Key in your Application...............................3-4
Embedding a Private Key from the Command Line ......................3-5
Using SDK Manager .................................................................................3-6
Searching for NPort PCGs .............................................................3-6
Selecting/Deselecting PCGs.........................................................3-10
Configuring an NPort PCG ..........................................................3-12
Application Download .................................................................3-20
Run Application / Debug..............................................................3-22
Example Programs ..................................................................................3-25

4. Application Deployment ............................................................... 4-1
Changing Default Settings for Multiple PCGs ..........................................4-1
Creating System Firmware—COM2FRM.................................................4-2
Command Line Usage....................................................................4-3
Field Utility ....................................................................................4-3
Developing a PCG Utility .........................................................................4-4
DSCI Library..................................................................................4-4
AP ID .............................................................................................4-4
5 PCG FAQs.......................................................................................... 5-1

1
1
1Introduction
NPort Programmable Communication Gateway (PCG) is a stand-alone, programmable
communication device with RS-232/422/485 and Ethernet interface for industrial
automation. PCG provides a Moxa embedded OS (Moxa OS) and TCP/IP
communication stack, and Software Development Kit (SDK) that allows system
integrators to build up their own proprietary solution without using traditional PCs.
Moxa OS
NPort PCG has an embedded, small footprint, multi-tasking OS developed by
Moxa Technologies Co. Ltd. It was developed originally for TCP/IP-based
Terminal Server products starting in 1996. It is a powerful and reliable software
platform with user-friendly SDK. Its major features are:
 16-bit, Unix-like embedded operating system
 Small footprint (<300 KB with TCP/IP protocol stack)
 Preemptive scheduler
 Stream I/O
 Standard BSD Sockets for TCP/IP programming with multi-TCP session support
SDK (Software Development Kit)
To assist in the development of NPort PCG applications, Moxa provides a
comprehensive and easy-to-use SDK, designed for use on Windows
95/98/ME/NT/2000/XP platforms. The main features are as follows.
 Borland™ Turbo C 2.01 compiler
 SDK libraries with more than 100 function calls
 SDK Manager and COM2AP utilities for software download and troubleshooting
 PComm Terminal Emulator
 More than 20 example programs
 Documentation
 Single-task user program
 64 KB of user program space (tiny mode in Turbo C)
Other advanced features include:
 COM2FRM utility for advanced application deployment
 DSCI library for utility development

1-2
User Application Space
The user application space available on an NPort PCG is a full 64 KB. This is
because the serial I/O, Ethernet, and TCP/IP protocol stack buffers occupy part
of the kernel space. In general, this amount of space is sufficient for protocol
conversions, and is sufficient for even more complex applications, such as
Modbus conversion.
SDK Function Group Overview
The SDK Library contains six groups of function calls. The following table lists
the six function call groups along with their primary function.
SDK Library Function Group Overview
Function Call Group Description
Serial I/O API Serial communication function calls that follow
the same style as PComm Library. This API
includes communication parameters, character
read/write, block read/write, I/O control, break
generation, and more.
BSD Socket API Standard BSD Socket API for TCP/IP
programming. Supports TCP and UDP
communication.
Simplified Socket API Simplified TCP/IP programming. Supports TCP
and UDP communication.
System Control API Overall system control for NPort PCG including
Watchdog timer enable/disable, system clock
settings, system configuration, system restart,
interrupt handling, and serial interface selection.
Flash Access API Read, write, erase user storage space on flash.
There are 32 KB for NPort 4511.
Debug API For sending messages to the debug window in
SDK Manager.

2
2
2Installing SDK
This chapter covers:
 How to install SDK utilities and Library
 How to install the Turbo C compiler and environmental variables
 The location of Libraries and Example Files
System Requirements
You will need to have the following items available to use SDK’s development
tools:
 Windows 9x, NT, ME, 2000, or XP operating system
 At least 64 MB of RAM
 At least 15 MB of hard disk space

2-2
Installing SDK
To install Moxa SDK on a Windows system, insert the software CD-ROM
included with the product into your computer’s CD-ROM drive. The installation
program should start automatically. Simply follow the onscreen instructions to
complete the installation.
The installation procedure installs the following files:
Directory Sub Directory\Files Description
…\SDK \Document\  NPort 4511 hardware installation guide
 Programmer’s guide
 API Reference
\Example\ SDK example files
\Firmware\np4511.rom Kernel firmware for NPort 4511
\Include\ This directory contains all declaration files
sdkdbg.h Debug symbol API declarations
sdkflash.h Flash access API declaration
sdknet.h Simplified Sockets API declaration
sdksio.h Serial I/O API declaration
sdksock.h BSD socket API declaration
Sdksys.h System API declaration
\Library\
C0sdk.obj
This directory contains the SDK Library files
Object code for all APIs.
Moxa_sdk.lib API library for NPort 4511 SDK.
\Utility\ This directory contains SDK Manager,
COM2AP, COM2FRM, MoxaTerm utilities
along with correspond help file.
\Dscilib\Library\ This directory contains library for utility
development on Windows
Dsci.dll DLL file for DSCI (Device Server Control
Interface) API
Dsci.h Declaration file for DSCI API
Dsci.lib Library file for DSCI API
\Dscilib\Example\ Example program for DSCI
…\TC tcc.exe Turbo C 2.01 compiler
tlink.exe Turbo C 2.01 linker
\Include\ Include file for Turbo C.
\Lib\ Library file for Turbo C

2-3
Desktop Icons
The SDK installation places three program icons on your computer’s desktop
that serve as shortcuts to the following programs: NPort SDK Manager,
COM2AP, and Terminal Emulator.
Setting Up Environment Variables
During the installation procedure, the SDK setup program automatically sets up
your environment variables for the Turbo C compiler. You may also set up the
environment variables manually from Control panel System, or you can add
a command line to autoexec.bat.
Assuming the installed directory for SDK is C:\PCGSDK, the command lines are
as follows:
path=c:\pcgsdk\tc;%path%
set INCLUDE=c:\pcgsdk\tc\include
set LIB=c:\pcgsdk\tc\lib

3
3
3Developing User Applications
In this chapter, we cover the following topics:
 Application Development Flow
 Software tools required for application development
 Software key protection
 Application deployment
In order to give you a better understanding of the development flow, we’ll use
the example program sdkser23.c to illustrate.
Application Development Flow
The following flowchart illustrates the standard process for developing your
NPort PCG applications.
Compile
tcc.exe
PRG..OBJ C0SDK.OBJ
MOXA_SDK.LIB
Link
tlink.exe
PRG.COM
Private
Key
Other OBJ from TC
(e.g., math, string, …)
PRG.C
S/W protection
COM2AP.EXE
PRG.AP
SDK Manager
Download & Run
PRG.AP

Development System
Before getting started on application development, you need to make sure that all
of the required equipment is set up and ready to go. The basic configuration
needed for application development is as follows:
 Windows95/98/ME/NT/2000/XP computer with SDK installed
 PCG with power adapter
 Ethernet hub/switch (or use a cross-over Ethernet cable to link the computer
and PCG directly)
 Two Ethernet cables
 One RS-232 cable (DB9 Male to Female straight-through cable). This
allows you to transmit and receive serial data along with RTS, CTS, DTR,
DSR control signals. However, you will not be able to reach the DCD signal.
Another option is to use a mini adapter and DB9 Female to Female null
modem cable. In this way, the DSR and DCD signals can be monitored
because they are wired together. The mini adapter is included as a standard
accessory in NPort 4511’s Starter’s Kit.
The basic wiring for establishing a development system is as follows.
Windows
computer
RS-232
DB9(M) to DB9(F)
Straight-through
cab
l
e
Etherne
t
Etherne
t
Ethernet
Hub/Switch
N
Por
t
PCG
3-2

3-3
Source Code Editing
Since the Turbo C compiler and linker work under the traditional DOS
environment, we recommend using DOS’s edit program to edit your source code
(simply type “edit” on the DOS command line and then hit Enter to start the
editor). This is the approach we use in this manual.
You may also use “notepad” or any other text editor to write and edit source
code. Turbo C’s IDE environment is another good option. However, the
environment variables need to be manually configured since NPort SDK works
mainly from command line mode.
For example, to edit the file sdkser23.c, first open a DOS window, use the cd
(change directory) command to open the folder c:\pcgsdk\sdk\example\serial,
and then type edit sdkser23.c. You should now be able to view and edit the file
sdkser23.c.
Compiling and Linking your Application
Under NPort PCG’s SDK, compiling and linking is done from DOS command
mode. Because of this, you will need to create a make file before compiling and
linking a program.
Creating a Make File
For tcc.exe, the following parameters should be enabled or properly assigned.
-I – assign include files directory.
-L – assign library files directory.
-O – optimize jumps.
-Z – maximum register usage.
-1 – 80186/286 instructions.
-mt – tiny mode
-c – compile only
-w – enable all warnings
For tlink.exe, the following parameters should be enabled or properly assigned.
-t – create COM file.
-s – detailed map of segment.
For instance, the make file for
C:\PCGSDK\SDK\EXAMPLE\SERIAL\SDKser23.c is as follows.
c:\pcgsdk\sdk\example\serial> type sdkser23.bat
tcc -I..\..\include -L..\..\library -O -Z -1 -mt -c -w SDKser23.c
tlink
/t/s ..\..\library\C0sdk+SDKser23,SDKser23,SDKser23,..\..\library\m
oxa_sdk

Generating a COM file
You should be able to generate a COM file after having compiled and linked a
program without receiving any error messages. For example, after you run the
make file, sdkser23.bat, in c:\pcgsdk\sdk\example\serial, the file sdkser23.com is
generated in the same directory.
Using COM2AP
After successfully generating a COM file, you will need to use COM2AP.EXE to
convert the COM file into an AP file that has an embedded “Private Key.” This
must be done before downloading the AP file to the PCG..
Intellectual Property Protection
System integrators often provide their proprietary knowledge to solve particular
problems for their customers. Once you start providing NPort PCG as a platform
for other users, you will need to manage and protect your intellectual property
that is embedded in NPort PCG. For this reason, NPort PCG provides a private
key that you can embed into your application (AP). The target NPort PCG should
have the same private key with the help of SDK Manager. The Moxa OS
automatically checks to make sure that the private key in the AP and kernel
match.
Embedding a Private Key in your Application
To embed a private key in the target AP (e.g., sdkser23.com) first double click on
Com2ap desktop icon.
3-4

3-5
Next, take the following steps to complete the process of embedding a private
key:
1. Type the private key in the “Private Key” field. E.g., you could choose
“1234” as the private key.
2. Click on the folder icon to the right of COM file and then navigate to the
COM file you would like to convert (e.g., sdkser23.com).
3. The name of the target AP file (sdkser23.ap, for this example) will appear in
the Protected User Application text input box. If desired, you can change
the file name, or click on the folder icon and navigate to a different folder in
which you would like to store the resulting AP file.
4. Prior to downloading and running the AP file, use SDK Manager to set up
the same private key for the PCG. Refer to next section for more detail.
Embedding a Private Key from the Command Line
To give program developers a convenient alternative for producing an AP,
COM2AP can also be activated from the DOS command line. Enter the
command in the following format:
COM2AP –Kxxxxxxx –Syyyyyyyy.yyy –Dzzzzzzzz
Argument description
-K Private key. Select a key with at most 15 characters or numbers (e.g., you
could choose private key = 23icky9003cig).
-S Source file. The source COM file.
-D AP file. Note that you should not type the file extension name since it is
predefined as “AP”.
For example, to generate the AP file from the command line, add the following
line after tlink in the batch file.
com2ap –K23icky9003cig –Ssdkser23.com –Dsdkser23

Using SDK Manager
After the application has been successfully compiled and linked, it time to use
SDK Manager. SDK Manager is a utility that provides the following functions.
 Search and locate NPort PCGs.
 Change the IP, Netmask, Gateway, default serial comm parameters, and
operation modes for NPort PCG.
 AP download
 Debug window
Searching for NPort PCGs
The Search Menu provides two different methods to search the network for a
PCG. Broadcast Search is used to locate all PCGs connected to the same LAN
as the host, and Search by IP is used to locate a specific PCG, particularly if it is
located outside the LAN and can only be accessed by going through a router.
The Search Menu also provides the Locate Server function that can be used to
identify a particular PCG unit.
Broadcast Search
To access this function, select Broadcast Search under the Search menu, or
click on the Broadcast Search toolbar icon.
3-6

The Broadcast window will display the progress of the search.
Once the search is complete, the Model Name, Serial No., Server Name, AP
ID, MAC Address, IP Address, Subnet Mask, and OP Mode of each PCG that
was located will be displayed in the SDK Manager window.
Search by IP
To access this function, select Search by IP under the Search menu, or click on
the Search by IP toolbar icon.
When the Search by IP Address window opens, type the IP address in the text
3-7

input box, and then click OK.
The Search by IP window will display the progress of the search.
Device not found error message.
NOTE If you receive the Specified device not found error message, as shown
above, and the PCG is located on the same LAN as the host, try using
Broadcast Search, or change the host computer’s IP address and/or
Netmask so that the computer and PCG are on the same subnet.
If the search is successful, the Model Name, Serial No., Server Name, AP ID,
MAC Address, IP Address, Subnet Mask, and OP Mode of the PCG will be
displayed in the SDK Manager window.
3-8

Locate Gateway
The Locate Gateway function is used to find the physical location of a PCG unit
when there are multiple PCGs on the same network. To use this function, first
click on the device you would like to locate to highlight the device’s information,
and then select Locate Gateway under the Search menu, or click on the Locate
Gateway toolbar icon.
If the Locate Result is OK, then the Ready light on the located PCG unit will
blink steadily, allowing you to identify the PCG and IP Address.
3-9

Click on OK to cause the PCG unit’s Ready light to stop blinking.
Selecting/Deselecting PCGs
The Select All and Deselect All functions are provided to make it easier to
configure large numbers of PCGs.
NOTE SDK Manager includes a multi-selection capability. Hold down the Ctrl
key to select multiple PCGs that are not listed in order, or hold down the
Shift key to select all PCGs listed between the first and last PCG that
y
ou click on.
Select All
The Select All function is used to select all PCGs listed in the SDK Manager
window. To use this function, select Select All under the Actions menu, or click
on the Select All toolbar icon.
This will cause all NPort 4511s listed in NPort SDK Manager window to become
highlighted.
3-10