NPort PCG SDK 2 Programmer’s Guide Third Edition, July 2006 www.moxa.com/product MOXA Technologies Co., Ltd. Tel: +886-2-8919-1230 Fax: +886-2-8919-1231 Web: www.moxa.com MOXA Technical Support support@moxa.
NPort PCG SDK 2 Programmer’s Guide 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 © 2006 MOXA Technologies Co., Ltd. All rights reserved. Reproduction without permission is prohibited. Trademarks MOXA is a registered trademark of The Moxa Group. All other trademarks or registered marks in this manual belong to their respective manufacturers.
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: support@moxa.com.......................................(Worldwide) support@usa.moxa.com ................................
Table of Contents Chapter 1 Introduction..................................................................................................1-1 Moxa OS Ver. 2.x .................................................................................................................... 1-1 PCG SDK 2 ............................................................................................................................. 1-1 SDK Function Group Overview ...............................................................
1 Ch apt er 1 Introduction NPort Programmable Communication Gateway SDK 2 is designed for users who would like to run their own proprietary application on NPort 5200-P Programmable Communication Gateway. PCG SDK 2 comes with a Moxa embedded OS (Moxa OS), TCP/IP communication stack, and Software Development Kit (SDK) and Windows utility that allow system integrators to create their own proprietary solution that doesn’t use traditional PCs. MOXA OS Ver. 2.
SDK 2 Programmer’s Guide Introduction SDK Function Group Overview The SDK Library contains several groups of function calls. The following table lists the 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.
2 Chapter 2 Installing SDK This chapter covers the following items: ¾ System Requirements ¾ How to install PCG SDK2 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 Installing PCG SDK2 To install PCG SDK 2 o
SDK 2 Programmer’s Guide Installing SDK PCG SDK2 Directories and Files The installation program installs the following files on your computer’s hard drive: Directory …\PCGSDK2 Sub Directory\Files Description \Example\ SDK example files \INCLUDE\ Contains all header files \INCLUDE\SDKCONF.H System Configuration API and Time Server API declarations \INCLUDE\SDKDBG.H Debug symbol API declarations \INCLUDE\SDKFLASH.H Flash access API declarations \INCLUDE\SDKNET.
SDK 2 Programmer’s Guide Installing SDK Installing Turbo C To install Turbo C on a Windows system, run the installation program: CD ROM:\Programmable version\TurboC\tcsetup.exe and then follow the onscreen instructions to complete the installation. Turbo C Directories and Files The installation program installs the following files on your computer’s hard drive: Directory \TC Sub Directory\Files Description TCC.EXE Turbo C 2.01 compiler TLINK.EXE Turbo C 2.
3 Ch apt er 3 Developing User Applications In this chapter, we cover the following items: ¾ 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 PRG.C to illustrate.
SDK 2 Programmer’s Guide Developing User Applications Application Development Flow The following flowchart illustrates the standard process for developing your applications. PRG.C Compile tcc.exe (large mode) Other OBJ from TC (e.g., math, string, …) PRG..OBJ C0SDK.OBJ MOXA_SDK.LIB Link tlink.exe PRG.EXE S/W protection EXE2AP.EXE PRG.AP SDK Manager Download & Run PRG.
SDK 2 Programmer’s Guide Developing User Applications 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. Take NPort 5200-P as an example.
SDK 2 Programmer’s Guide Developing User Applications Compiling and Linking your Application Under PCG 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.
SDK 2 Programmer’s Guide Developing User Applications Using EXE2AP After successfully generating an EXE file, you will need to use Exe2ap.exe to convert the EXE file into an AP file that has an embedded “Private Key.” This must be done before downloading the AP file to the NPort. Protect Your Software with Private Key System integrators often provide their proprietary knowledge to solve particular problems for their customers.
SDK 2 Programmer’s Guide Developing User Applications Embedding a Private Key from the Command Line To give program developers a convenient alternative for producing an AP, EXE2AP can also be activated from the Windows command Prompt. Enter the command in the following format: EXE2AP –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 = 23ji5rj34g). -S Source file. The source EXE file. -D AP file.
SDK 2 Programmer’s Guide Developing User Applications Broadcast Search To access this function, select Broadcast Search under the Search menu, or click on the Broadcast Search toolbar icon. 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 NPort that was located will be displayed in the SDK Manager window.
SDK 2 Programmer’s Guide NOTE Developing User Applications The default IP address of an NPort PCG 5200-P series product is 192.168.127.254, with subnet mask set to 255.255.255.0. 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 input box, and then click OK. The Search by IP window will display the progress of the search.
SDK 2 Programmer’s Guide Developing User Applications If the search is successful, the Model Name, Serial No., Module Name, AP ID, MAC Address, IP Address, Subnet Mask, and OP Mode of the NPort will be displayed in the SDK Manager window. Locate Gateway The Locate Gateway function is used to find the physical location of a PCG unit when there are multiple NPort PCGs on the same network.
SDK 2 Programmer’s Guide Developing User Applications Selecting/Deselecting NPort PCG The Select All and Deselect All functions are provided to make it easier to download the AP, Kernel, and Firmware to multiple NPort 5200-P series. NOTE SDK Manager includes a multi-selection capability. Hold down the Ctrl key to select multiple NPort PCGs that are not listed in order, or hold down the Shift key to select all NPort PCG listed between the first and last NPort PCG that you click on.
SDK 2 Programmer’s Guide Developing User Applications Configuring an NPort PCG To use this function, select Configuration under the Actions menu, or click on the Configuration toolbar icon. The Configuration window opens with the Comm. Gateway tab selected. Each of the six Configuration window tabs is discussed in the following subsections. Communication Gateway To make changes, first click in the Gateway box, and then modify Gateway Name and network settings.
SDK 2 Programmer’s Guide IP Address Netmask Gateway Developing User Applications Ethernet Port Available with multi-selection When multiple target NPort PCGs are xxx.xxx.xxx.xxx selected, they will all be configured with the same IP address. Available with multi-selection Define a range of IPs by inputting Start and End values. These IP addresses will be xxx.xxx.xxx.xxx assigned in sequence to selected NPort, in order of their appearance in the Manager window. xxx.xxx.xxx.
SDK 2 Programmer’s Guide Developing User Applications Serial Port Tab This section of the Configuration window allows you to modify the serial communication parameters. The modified parameters will be saved in the NPort PCG’s flash ROM. To make changes, first click in the Change Serial Settings box, and then click on the port in the display area in the bottom part of the window to make changes to the configuration of the serial ports.
SDK 2 Programmer’s Guide Developing User Applications Private Key Tab As mentioned above, a private key is required for both the AP and the NPort PCG. To embed the private key in the NPort PCG, first click in the Change Private Key box, and then enter the Private Key in the Private Key input box. Finally, enter the same Private Key in the Confirm box. Setting Private Key Settings Options Comments Private Key Input Alphanumeric Maximum number of alphanumeric characters allowed is 15.
SDK 2 Programmer’s Guide Developing User Applications Auto IP Report In a dynamic IP environment (DHCP, BOOTP), the NPort PCG’s IP address changes from time to time, making it hard for the host computer to locate the NPort PCG. To solve this problem, NPort PCG automatically reports its location to a remote host computer. The Location Report section of the Configuration window allows you to set up the IP address corresponding to a specified UDP port for a host computer.
SDK 2 Programmer’s Guide Developing User Applications Application Download Up to this point, we have only discussed how to configure the NPort PCG’s network and other parameters. The next thing to do is download the prepared application (AP) to the NPort PCG testing. Download AP To download the AP, first select Download AP from the Actions menu, or click on the Download AP toolbar icon.
SDK 2 Programmer’s Guide Developing User Applications Use the Open button to navigate to the folder that contains the kernel file, or just type the kernel filename directly in the Filename input box. Click OK to start downloading the kernel. The following window appears when the kernel has finished downloading. Run Application / Debug You should now be ready to run your application, but first we need to discuss the two NPort PCG operation modes.
SDK 2 Programmer’s Guide Developing User Applications Start Application To start an application loaded in the NPort PCG, first select Run Application /Debug from the Actions menu, or click on the Run Application /Debug toolbar icon.
SDK 2 Programmer’s Guide Developing User Applications Gateway Info Area The NPort PCG’s basic configuration settings are shown in the Comm. Gateway Info area. The information includes the following: y Server Info—includes Model Name, Serial No., Server Name, Firmware Version, number of Serial Ports, number of Ethernet Ports, Watchdog Mode, and OP Mode. y AP Info—includes latest AP Name and file location, Version, Date, and Size. y Ethernet Info—includes MAC address, IP address, Netmask, and Gateway.
SDK 2 Programmer’s Guide Developing User Applications Example Programs NPort PCG’s SDK is a comprehensive utility designed to match a programmer’s basic intuition. We’ve prepared several examples to let you quickly build up your first application. All of the example programs are in the folder \PCGSDK2\Example.
4 Ch apt er 4 Application Deployment After your application has been tested and is ready to go, it’s time to deliver the NPort PCG with your software. In this chapter, we offer several useful tips and tools that let you organize the production process efficiently. Creating System Firmware—EXE2FRM In general, the AP file is downloaded to the NPort PCG separate from the kernel.
SDK 2 Programmer’s Guide Application Deployment Command Line Usage To speed up program development, EXE2FRM can also be activated from the DOS command line, as shown below. Simply type: EXE2FRM –Kxxx –Syyyyyyyy.yyy –Fyyyyyyyy.yyy –Dzzzzzzzz Argument description Private key. Select a key with at most 15 characters or numbers (e.g., you could choose private key = 23ji5rj34g). -S Source file. The source EXE file. -F The file name for the kernel. -D FRM file.
SDK 2 Programmer’s Guide Application Deployment Developing an NPort PCG Utility NPort PCG SDK provides the NPort PCG Control Interface (PCGCI) Library for customers who want to develop their own utility for use on a Windows computer. PCGCI Library PCGCI (NPort PCG Configuration Interface) is a set of APIs that run on a Windows 95/98/Me/NT/2000/XP systems to search, locate, and config the NPort PCG over the network. The PCGCI library can be found in the folder C:\PCGSDK2\Pcgcilib\LIBRARY.
SDK 2 Programmer’s Guide Application Deployment The AP version shows up in SDK Manager window.
5 Chapter 5 Programming Notes This chapter provides a more in-depth explanation of the following topics.
SDK 2 Programmer’s Guide Programming Notes Flash ROM Access NPort PCG contains a block of flash memory that is available for data buffering, or to store a small amount of data. To make the operating system more efficient, there is no file system. Flash ROM Structure The flash ROM structure is illustrated below.
SDK 2 Programmer’s Guide Programming Notes Writing Data Data is written sequentially into the flash according to your program’s instructions. Each time data is written, the offset address automatically moves to the next writing point. For example, if the original offset address is 0x0100, and 20 bytes of data are stored, then the API moves the offset address to 0x0121. The API “flash_length( )” gets the length of the data currently stored in the flash. The return code “-2” indicates that the bank is full.
6 Chapter 6 FAQ In this chapter, we present a short list of Questions and Answers to assist you in solving frequently encountered problems. Question 1 Why is SDK Manager unable to configure or start debugging the NPort PCG after searching for the NPort over a network? Answer 1 SDK Manager uses UDP (which broadcasts packets over the network) to search for NPort PCGs installed on the network. The configuration and debugging functions use TCP communication.
