Serial API Run Time Kit Guide

Serial API Run Time Kit Guide
MICROGATE SERIAL COMMUNICATIONS
RUN TIME KIT
WINDOWS GUIDE
MicroGate Systems, Ltd
http://www.microgate.com
MicroGate® and SyncLink® are registered trademarks of MicroGate Systems, Ltd.
Copyright © 2012-2016 MicroGate Systems, Ltd. All Rights Reserved
1
CONTENTS
Preface ...........................................................................................................................................................................3
Supported Versions ...................................................................................................................................................3
Required Knowledge..................................................................................................................................................3
Overview ........................................................................................................................................................................4
Software Installation .....................................................................................................................................................5
Software Removal......................................................................................................................................................5
Hardware Configuration and Installation ......................................................................................................................6
Serial Interface Selection ...........................................................................................................................................6
RS-232 ....................................................................................................................................................................6
V.35 ........................................................................................................................................................................6
RS-422/RS-485 .......................................................................................................................................................6
Hardware Installation ................................................................................................................................................6
PCI Cards ................................................................................................................................................................7
USB Adapter...........................................................................................................................................................7
Verifying Hardware and Driver Installation ...................................................................................................................8
Windows Device Manager .........................................................................................................................................8
SyncLink Device Properties ....................................................................................................................................9
Trace Utility .............................................................................................................................................................13
Device Instances and Names ...................................................................................................................................14
Location Locked and Device Locked Instances ....................................................................................................14
Serial API Names ..................................................................................................................................................14
Removing Device Instances of Non-present Hardware .......................................................................................15
Serial Device Connection .............................................................................................................................................16
Standard Cables .......................................................................................................................................................16
Custom Cables .........................................................................................................................................................17
Run Time Kit (RTK) Components ..................................................................................................................................18
2
PREFACE
SUPPORTED VERSIONS
The serial API supports these 32-bit and 64-bit Windows versions:
Windows XP (Server 2003/2003R2)
Windows Vista (Server 2008)
Windows 7 (Server 2008R2)
Windows 8 (Server 2012)
Windows 8.1 (Server 2012R2)
Windows 10 (Server 2016)
REQUIRED KNOWLEDGE
Installing SyncLink hardware and software on Windows requires the following knowledge:
1.
2.
3.
4.
Basic Windows administration
Documentation for third party serial application software
Configuration details for third party serial application
Reading supplied MicroGate documentation
MicroGate makes serial hardware for use with third party serial applications. Contact the supplier of your third
party serial application for support.
3
OVERVIEW
This guide describes the use of SyncLink serial hardware with third party applications on the Windows operating
system. Serial communication transfers data between systems similar to network devices like Ethernet and WiFi,
but using different physical characteristics and protocols. There are many different types of serial communications
and a successful connection requires compatible configuration for all participating systems.
A complete setup consists of a Windows system, SyncLink hardware, the SyncLink Run Time Kit and a third party
application as shown in this diagram.
Windows System
Third Party Serial Application
SyncLink Run Time Kit (RTK)
SyncLink Hardware
Refer to documentation supplied by the third party application vendor for installation and configuration details
appropriate for you environment. MicroGate will not have this information.
Install the SyncLink Run Time Kit before configuring and installing the hardware so Windows can automatically
detect the hardware and install the appropriate drivers. PCI serial cards require configuration of interface selection
jumpers before installation into a compatible PCI system slot. USB to Serial converters do not have jumper settings
and are connected to system USB ports with USB cables. Refer to the Hardware User’s Manual that came with your
hardware for detailed configuration and cabling information.
4
SOFTWARE INSTALLATION
Before using or installing SyncLink hardware, install supporting software and device drivers. The MicroGate
software package is included on media shipped with your hardware, and the latest version can be downloaded
from:
http://www.microgate.com/ftp/hdlcapi.sdk/hdlcrtk.exe
hdlcrtk.exe is a self extracting executable that expands by default to c:\hdlcapi. Run the package from a
command line or from the Windows explorer. The expanded package contains:
drivers\winXP-8.1\win32
drivers\winXP-8.1\win64
drivers\win10\win32
drivers\win10\win64
tools\win32
tools\win64
drivers for 32-bit Windows XP/Server 2002 to 8.1/Server 2012R2
drivers for 64-bit Windows XP/Server 2002 to 8.1/Server 2012R2
drivers for 32-bit Windows 10
drivers for 64-bit Windows 10, Server 2016
32-bit support tools
64-bit support tools
See supported Windows versions at start of this document for more details.
Run setup.exe in the drivers directory as the Administrator user. This installs drivers so Windows can
automatically detect and support SyncLink hardware. Setup also updates previously installed devices to the latest
drivers.
C:\hdlcapi\drivers\>setup
After software installation, install hardware as described in the Hardware Installation section and reboot the
system. Windows automatically detects the hardware and installs drivers for each device. If Windows does not find
the drivers automatically, manually specify the search location as the above directories and follow the displayed
instructions to complete device installation.
SOFTWARE REMOVAL
Run setup.exe in the drivers directory with the /u option to remove all device instances and the driver
packages.
C:\hdlcapi\drivers\>setup /u
5
HARDWARE CONFIGURATION AND INSTALLATION
This section describes the configuration and installation of the serial hardware. This must match the application
specific requirements provided by the third party application vendor.
SERIAL INTERFACE SELECTION
The SyncLink serial device has a 25 pin connector for each serial port. This connector can be configured for
different electrical specifications. The three options are: RS-232 (single ended signals), V.35 (combined single
ended and differential signals) and RS-422/RS-485 (differential signals). The selection of interface type is controlled
by jumper settings on PCI cards and through software for the USB to serial device.
RS-232
RS-232 (also called EIA-232) is a specification that defines single ended signals (one wire per signal) for use in low
data rate applications, usually less than 120Kbps. This is common in legacy applications such as connecting to
analog phone line MODEMs. The standard defines pin assignments on a 25 pin connector.
V.35
V.35 is a specification that defines a combination of single ended signals (one wire per signal) and differential
signals (two wires per signal). Data and clock signals are differential for high speed. Control and status signals are
single ended. The standard defines pin assignments on a 34-pin “block” connector. An adapter cable available from
MicroGate is required to convert the device’s 25 pin connector to a standard V.35 34 pin connector.
RS-422/RS-485
RS-422 (also called EIA-422) is an electrical specification for differential signals (two wires per signal). RS-485 is an
improved specification that is compatible with RS-422. Neither standard specifies pin assignments or a connector.
The SyncLink card assigns RS-422/485 pins using the RS-530 specification for a 25 pin connector. MicroGate offers
adapter cables to convert the RS-530 pin assignments to RS-449 (37 pins) or X.21 (15 pins).
HARDWARE INSTALLATION
The exact hardware installation procedure depends on the hardware and the system type. Some hardware plugs
into external system ports, other hardware is installed into internal expansion slots on the system. Refer to the
hardware user’s guide (PDF) that came with your hardware for detailed specification and configuration
information. Hardware user’s guides are also available at www.microgate.com
6
PCI CARDS
PCI and PCI Express cards are installed into internal expansion slots on the host system. The card type must match
the expansion slot type. SyncLink PCI cards are “universal” and are compatible with 3.3V, 5V, 32-bit, 64-bit and PCIX expansion slots. Do not confuse PCI-X with PCI Express, they are different slot types. SyncLink PCI Express cards
are compatible with 1x, 4x, and 16x PCI Express expansion slots.







Verify card interface selection jumpers (RS232,V.35,RS422) are correctly installed.
Shutdown system.
Remove system case cover.
Insert adapter in compatible slot.
Secure card bracket with screw or clamp.
Replace system case cover.
Start system.
USB ADAPTER
The USB serial adapter plugs into a host USB port using the supplied Type B male to Type A male USB cable.
SyncLink USB should be plugged into a USB 2.0 or later Hi-speed (480Mbps) USB port. Operating on a slower USB
port is not recommended. Install directly into a host USB port instead of a USB hub for better performance.
SyncLink USB requires 500mA of power from the USB port, which is standard and supported by most USB ports.
Some USB ports may not provide a full 500mA, such as unpowered hubs or ports in small mobile devices.
7
VERIFYING HARDWARE AND DRIVER INSTALLATION
Before developing an application, verify the correct installation of serial hardware and device drivers.
WINDOWS DEVICE MANAGER
The primary tool for verification is the Windows Device Manager, an administrative tool included with Windows.
This tool displays a tree diagram of hardware devices arranged by type or connection.
Starting Windows Device Manager
The Windows device manager can be started from a command prompt or through the Windows Control Panel. The
device manager must be run with Administrative privilege.
Windows XP Control Panel
For Windows XP, click the Start button and select Control Panel. Double click the System icon. Select the
Hardware tab then click the Device Manager button.
Windows Vista and later Control Panel
For Windows Vista and later, click the Start button and select Control Panel. Type “device manager” into the
search box in the upper right of the Control Panel window. Then select the Device Manager item in the search
results.
Command Prompt
To open a command prompt, click the Start button, select All Programs then Accessories and right click on
Command Prompt. Finally, select Run as administrator from the pop-up menu. If prompted for permission to
continue, select allow. In the command prompt, run the following command:
C:\>devmgmt.msc
Once the device manager is running, look for a branch labeled SyncLink Adapters.
If you do not see SyncLink Adapters, try selecting the Computer branch, click the Action menu and select the “Scan
for hardware changes” menu item. This should prompt Windows to detect new hardware and install drivers.
If you still do not see SyncLink Adapters, look for entries with a yellow question mark symbol labeled either “PCI
Simple Communications Controller” or “SyncLink USB”. Right click each of these entries and select “Update Driver”
from the pop-up menu and follow any displayed instructions. If for some reason Windows can’t find the drivers
automatically, manually specify the search location as the driver directory In the SDK package.
Once the SyncLink Adapter branch is present, expand the branch to display SyncLink devices. Devices with a yellow
symbol on the icon have a problem. If no yellow symbol is visible, the device and driver have been correctly
installed. Right click on a device entry and select Properties from the pop-up menu.
8
SYNCLINK DEVICE PROPERTIES
The SyncLink device properties in the Windows device manager displays device and driver information, configures
the device and allows testing the device. The device properties window has multiple tabs for different purposes.
G ENERAL T AB
This tab displays the device status and location (slot or port number). If the device status is working properly then
proceed to the next tab. Otherwise note the error message for diagnosing an installation problem. The device
driver version and device names are displayed to the right of the card icon near the top.
9
A DVANCED T AB
The advanced tab contains device settings that take effect at system startup. Not all settings are available for all
SyncLink devices.
The Device pull down list includes one entry for each port on the device. The other settings apply to the currently
selected port.
Max Frame Size
This setting chooses the largest HDLC frame or block of data that can be sent or received in a single API call. 4096 is
the best choice for most applications. HDLC frames larger than 4K bytes should only be used with the CRC-32
frame check.
Serial Interface
Select the serial interface electrical specification (RS232, V.35, RS422, etc). This option is only available on the
SyncLink PCMCIA and USB devices. PCI cards select the interface with jumper settings. Choose the interface type
required by your application. Choosing the incorrect interface type prevents correct operation and may damage
the device.
Disable Input Termination (USB Only)
When checked, this option disables the input termination on the USB adapter serial interface when differential
modes are selected (RS422/RS530/V.35/X.21). Normally, differential inputs are terminated with 120 Ohms.
Disable RS422/485 Outputs when RTS is off.
Choose this option when the state of the RTS output signal should be used to control output drivers (enabled or
tri-state). An application controls RTS to manually tri-state drivers in a 2-wire half duplex (multidrop) environment.
Disable RS422/485 Outputs when not sending data.
Choose this option if outputs should be disabled (tri-state) when not sending data. Hardware automatically
controls driver outputs in a 2-wire half duplex (multidrop) environment.
10
DMA Buffer Size and DMA Buffer Count
These options control buffer allocation in the driver. Use 0 unless otherwise directed by Microgate support.
11
D IAGNOSTICS T AB
The Diagnostics tab allows you to test the device using an internal or external looback of data.
Devices with more than one port will have a pull down list of ports. Select the port to test before proceeding.
Devices with only one port will not have this list.
Select the Data Loopback Test type: Internal or External. The internal test does not access the serial connector
and only tests the ability of Windows to talk to the device. If external is chosen, install the loopback plug that came
with the device on the serial connector.
Then click the Start Test button. Send and receive data counts will start incrementing in the Test Status area. The
test continues until the Stop Test button is clicked. Check the Test Status area for any error indications.
12
TRACE UTILITY
A trace utility is provided in the run time kit for recording events during a communications session for diagnostics
purposes. The recorded events are saved to a selectable trace file that can be supplied to support staff. The
program is located in the RTK at the location:
tools\win32\mgsltrc.exe
tools\win64\mgsltrc.exe
32-bit Windows
64-bit Windows
Run the program from a command line or the Windows explorer. The user must have administrative privilege to
run the trace utility. The running trace program will appear as shown below.
1.
2.
3.
4.
5.
6.
Enter the desired output file name into the Trace File edit field.
Click the Set All button to enable all trace levels.
Select the desired port in the Port pull down list.
Click the Start Trace button to start the trace.
Perform the tasks to record (run application, connect, etc)
Click the Stop Trace button to stop the trace.
Supply the output file to support staff.
13
DEVICE INSTANCES AND NAMES
When hardware is first installed, Windows creates a unique collection of data for the hardware describing the
location, configuration and associated software. This data is called a device instance. Each device instance for
hardware present in the system is displayed in the Windows device manager. When hardware is removed from the
system, the device instance remains but is not displayed in the device manager.
LOCATION LOCKED AND DEVICE LOCKED INSTANCES
Devices with a unique serial number accessible to Windows (SyncLink USB) use a device instance tied to the
specific device called a device locked instance. PCI cards use a device instance tied to the location (PCI slot) called a
location locked instance.
Hardware with a device locked instance may be moved to any location (USB port) and the same device instance is
used. If the hardware is replaced, a new device instance is created for the new hardware with a different serial
number.
Hardware with a location locked instance (PCI cards) may be replaced with the same card type in the same location
and the same device instance is used. Moving hardware to a different location (PCI slot) creates a new device
instance.
SERIAL API NAMES
When drivers are installed for a SyncLink hardware device, a device name is assigned to the device instance. The
name is used to access the device with the serial API. The name is based on an instance number that is assigned
sequentially starting with one.
Example:
The first SyncLink GT4 PCI card is adapter number one, with device names MGMP1P1 to MGMP1P4.
The second SyncLink GT4 PCI card is adapter number two, with device names MGMP2P1 to MGMP2P4.
If a PCI card is moved to a different slot, a new device instance is created with a different device name and
applications using the original name will fail. The application must use the new name or the old device instance
must be removed before creating a new device instance with the old name.
Example:
The first SyncLink GT4 PCI card is adapter number one, with device names MGMP1P1 to MGMP1P4.
The second SyncLink GT4 PCI card is adapter number two, with device names MGMP2P1 to MGMP2P4.
If the first card is moved to a different PCI slot, it becomes MGMP3P1 to MGMP3P2.
To reuse the name MGMP1P1 to MGMP1P4 in the new location, the first device instance must be removed before
installing the card in the new location using these steps:
1.
2.
3.
Remove hardware from system.
Start system and remove device instance. (see next section)
Install hardware in new location.
14
REMOVING DEVICE INSTANCES OF NON-PRESENT HARDWARE
Device instances of non-present hardware are not displayed in the device manager by default. The device manager
can be configured using an environment variable to display device instances of non-present hardware:
1.
2.
3.
Set the environment variable devmgr_show_nonpresent_devices = 1.
Start device manager.
Select Show Hidden Devices item from View menu.
Setting environment variable in Windows XP











Click the Start button in the lower left of the desktop
Right click My Computer
Select Properties from pop-up menu
Click the Advanced tab
Click the Environment Variables button near bottom of window
In the System variables section, click the New button
In the Variable name field, type devmgr_show_nonpresent_devices
In the Variable value field, type 1
Click the OK button to dismiss New System Variable window
Click the OK button to dismiss Environment Variables window
Click the OK button to dismiss System Properties window
Setting environment variable in Windows Vista and Windows 7











Click the Start button in the lower left of the desktop
Right click Computer
Select Properties from pop-up menu
Click the Advanced system settings in left side of window
Click the Environment Variables button near bottom of window
In the System variables section, click the New button
In the Variable name field, type devmgr_show_nonpresent_devices
In the Variable value field, type 1
Click the OK button to dismiss New System Variable window
Click the OK button to dismiss Environment Variables window
Click the OK button to dismiss System Properties window
Be careful typing the variable name to ensure it is entered exactly the same as above.
Now non-present devices are displayed in the device manager with a grayed out icon. Uninstall the device instance
by right clicking on the non-present device and selecting Uninstall from the pop-up menu. Repeat this for all
grayed out devices in the SyncLink Adapters and SyncLink USB Service Ports branches of the device tree. Once the
non-present device instances have been removed, new hardware can be installed or old hardware moved to a new
location.
15
SERIAL DEVICE CONNECTION
Serial devices are either DTE (data terminal equipment) or DCE (data circuit-terminating equipment). A DTE device
connects directly to a DCE device. Connecting two DTE devices requires a special cross over cable or intermediate
device called a null MODEM. A DTE is usually a system consuming and generating data. A DCE is a device that
converts data into a format suitable for a communications medium like a phone line or radio link. The SyncLink
serial device is a DTE with a DSUB 25 pin male connector.
STANDARD CABLES
A cable connects the SyncLink device to another device. If the attached device is a DCE using a standard connector
(RS-232, V.35, RS-530, etc) then use a standard cable. In some cases, an adapter cable must be purchased from
MicroGate to convert the DB-25M connector to the appropriate standard connector. The adapter cable can either
plug directly to the attached device or can be used with a standard cable to increase the cable length if needed.
SyncLink
RS-232 DTE
(DB-25 Male)
Standard DB-25F to DB-25M Cable
(25 conductors)
MODEM
RS-232 DCE
(DB-25 Female)
SyncLink
RS-530 DTE
(DB-25 Male)
Standard DB-25F to DB-25M Cable
(25 conductors)
MODEM
RS-530 DCE
(DB-25 Female)
SyncLink
V.35 DTE
(DB-25 Male)
DB-25F to V.35M
Adapter Cable
MODEM
V.35 DCE
(34 pin Female)
SyncLink
V.35 DTE
(DB-25 Male)
DB-25F to V.35M
Adapter Cable
SyncLink
X.21 DTE
(DB-25 Male)
SyncLink
X.21 DTE
(DB-25 Male)
Standard V.35
F to M Cable
MODEM
X.21 DCE
(DB-15 Female)
DB-25F to DB-15M
X.21 Adapter Cable
DB-25F to DB-15M
X.21 Adapter Cable
MicroGate Product
Standard Cable
16
MODEM
V.35 DCE
(34 pin Female)
Standard X.21
F to M Cable
MODEM
X.21 DCE
(DB-15 Female)
Attached Device
CUSTOM CABLES
If the attached device does not use a standard connector, such as custom control and measurement devices, then
use the documentation for the SyncLink and custom devices to create an appropriate custom cable. Pinouts,
electrical specification and configuration options are contained in the hardware user’s manual (PDF) for your
SyncLink device.
The first step in specifying a custom cable is determining which signals are required. The SyncLink device
implements a full set of data, clock, control and status signals. Many custom devices only require data and clock
signals. Some applications use clock recovery and only have data signals. Make a list of signals that are required by
the custom device and find the equivalent signal on the SyncLink device. SyncLink signals that are not required for
an application can be left unconnected. A signal ground connection is usually required between endpoints, except
for differential signals where the common mode voltage between endpoints can be guaranteed to meet electrical
specifications without a signal ground connection. If in doubt, include a signal ground connection. A chassis/earth
ground connection is recommended, which should be tied to the cable shield.
If the attached device uses differential signals (RS-422/RS-485) with two conductors per signal, you must verify the
polarity of the signals. Each differential signal on the SyncLink device is designated A/+ and B/-. Documentation for
other devices may use A and B or + and – for each of the two conductors of a signal. Usually, you connect A/+ to
A/+, B/- to B/-. Some manufacturers use designations with an opposite sense than MicroGate. For these devices,
connect A/+ to B/-. Reversing the conductors of a signal changes the polarity. The SyncLink hardware user’s
manual has detailed descriptions of relative voltages and transitions required for signals. If you lack such
documentation for the attached device, try normal polarity first and if that does not work try reversing the
polarity. Polarity is never a problem when using standard connectors and cables as pin assignments are contained
in the specifications for the connector.
17
RUN TIME KIT (RTK) COMPONENTS
Files required to support hardware and applications on an end user system (run time files) are contained in the
drivers and tools directories as described earlier. Choose the directories appropriate for the target Windows
version. These files should be distributed with the application and hardware. The complete list of run time files is
subject to change. Below is a list of the major components for reference only. The normal hardware driver
installation procedure (running setup or using Windows Hardware Wizard) copies necessary files to the correct
location in the Windows system directory.
setup.exe
redist\*
mghdlc.dll
mghdlc32.dll
mghdlc.sys
mgslclss.dll
mghdlcpp.dll
*.inf
*.cat
driver installation and update program
libraries used by driver installation and update program
serial API user mode interface library
32-bit serial API user mode interface library for 64-bit systems
hardware device driver
SyncLink hardware class co-installer DLL
SyncLink hardware property page DLL (displays Device Manager properties)
installation description files
installation catalog files
The following utility programs are included for testing and information collection purposes. These files are not
copied as part of the hardware driver installation procedure. The application writer is responsible for installing
them as needed on end user systems.
mgsltrc.exe
mgsltrc.chm
mgdump.exe
trace utility to record device events and API calls to a file
Windows help for trace utility
saves device configuration to a text file
18
19
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising