Echelon SLTA-10 User manual

SLTA-10 Adapter
User’s Guide
Revision 1
Corporation
078-0160-01B
®
Echelon, LON, LONW ORKS, LONMARK, Neuron, 3120, 3150, LonBuilder, NodeBuilder,
LonTalk, and LonManager are trademarks of Echelon Corporation registered in the United
States and other countries. LonMaker and LonSupport are trademarks of Echelon.
Other brand and product names may be trademarks or registered trademarks of their
respective companies.
Neuron Chips, Serial LonTalk Adapters, and other OEM products were not designed for
use in equipment or systems which involve danger to human health or safety or a risk of
property damage, and Echelon assumes no responsibility or liability for use of the Neuron
Chips or Power Line products in such applications.
Parts manufactured by vendors other than Echelon and referenced in this document have
been described for illustrative purposes only and may not have been tested by Echelon. It
is the responsibility of the customer to determine the suitability of these parts for each
application.
ECHELON MAKES AND YOU RECEIVE NO WARRANTIES OR CONDITIONS,
EXPRESS, IMPLIED, STATUTORY OR IN ANY COMMUNICATION WITH YOU, AND
ECHELON SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted,
in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise,
without the prior written permission of Echelon Corporation.
Printed in the United States of America.
Copyright ©1996 - 1997 by Echelon Corporation.
Echelon Corporation
4015 Miranda Avenue
Palo Alto, CA 94304, USA
SLTA-10 Adapter User’s Guide
2
Preface
This document describes how to use the SLTA-10 Serial LonTalk® Adapter to
connect a host processor, with an EIA-232 (formerly RS-232) serial interface,
to a LONWORKS® network.
SLTA-10 Adapter User’s Guide
3
Content
This manual provides detailed information about the hardware and software for the SLTA-10
Adapter.
•
Chapter 1 introduces the SLTA-10 Adapter and provides a quick overview.
•
Chapter 2 describes the SLTA-10 Adapter hardware.
•
Chapter 3 describes how to attach an SLTA-10 Adapter.
•
Chapter 4 describes the configuration switches of the SLTA-10 Adapter.
•
Chapter 5 describes the software for the SLTA-10 NSI mode.
•
Chapter 6 describes the software for the SLTA-10 MIP mode.
•
Chapter 7 discusses using the Windows NT
software with the SLTA-10 NSI mode.
•
Chapter 8 discusses using the DOS network driver with the SLTA-10 MIP mode.
•
Chapter 9 discusses creating an SLTA-10 MIP mode network driver for any host.
•
Chapter 10 describes initilization and installing as a node.
•
Chapter 11 discusses using an SLTA-10 Adapter with a modem.
•
Chapter 12 describes the DOS Host Connect Utility (HCU) for use with the SLTA-10 MIP
mode.
•
Chapter 13 is a troubleshooting section.
•
Appendix A describes the Windows 3.1x DLL files for use with the SLTA-10 Adapter.
®
SLTA-10 Adapter User’s Guide
TM
network driver and the SLTALink Manager
4
Related Manuals
The following Echelon documents are suggested reading for more information:
•
The LCA Object and Data Server Programmer’s Guide describes how to write a 32-bit Windows
host application and installation tool that can be used with the SLTA-10 NSI mode.
•
The LONWORKS Host Application Programmer’s Guide describes how to write a host
application that can be used with the SLTA-10 MIP mode.
•
The LonBuilder® User’s Guide describes how to develop LONWORKS applications with the
LonBuilder Developer's Workbench.
•
The NodeBuilder™ User’s Guide describes how to develop LONWORKS applications with the
NodeBuilder Development Tool.
•
Both Motorola and Toshiba have authored Neuron® Chip databooks containing specifications
and literature that describe the architecture of the Neuron Chip.
Web Access
Engineering bulletins and data sheets supporting this product are available on the Echelon Web
site. General information regarding Echelon, its business, and its products also are located on the
site at http://www.echelon.com.
SLTA-10 Adapter User’s Guide
5
SLTA-10 Adapter User’s Guide
6
Contents
Preface
Content
Related Manuals
Web Access
1
SLTA-10 Adapter Overview
Introduction
Two Modes of Operation: SLTA-10 NSI and MIP Modes
SLTA-10 NSI Mode Features
SLTA-10 MIP Mode Versus the SLTA/2
The SLTA-10 Adapter Configurations
Software Availability
LNS 1.0, 1.01, and 1.5 Compatibility
TAPI Compatibility
2 SLTA-10 Adapter Hardware
4
5
5
11
12
13
14
14
14
14
15
16
Mechanical Description
Switches, Indicators, and Connectors
ESD Warning
Connecting Power
17
18
20
20
22
3
Cabling and Connections
Attaching the SLTA-10 Adapter
Attaching the SLTA-10 Adapter to a PC
Attaching the SLTA-10 Adapter to a Modem
Attaching the SLTA-10 Adapter to a Network
25
26
26
27
28
4
Hardware Configuration
Configuring the SLTA-10 Adapter Hardware
Configuration Options
Interface Link Protocol Control (Switch1 / CFG3)
Modem Support (Switch2 / CFG2)
Network Disable (Switch3 / CFG1)
Serial Network Services Interface (Switch4 / NSI)
Autobaud (AB)
Serial Bit Rate (Switches[6..8] / Baud[2..0])
Configuring the SLTA-10 Adapter Software
29
30
30
30
31
32
33
34
34
36
5
The SLTA-10 NSI Mode Software
SLTA-10 NSI Mode Software Overview
Windows NT Software Installation Procedure
Windows NT Software Installation Results
39
40
40
41
SLTA-10 Adapter User’s Guide
7
6
The SLTA-10 MIP Mode Software
SLTA-10 MIP Mode Software Overview
Installing the SLTA-10 MIP Mode Adapter Software
Installing the Windows 3.1x DLL Software
Other Drivers
43
44
44
47
48
7
Using the Windows NT Driver and SLTALink Manager with SLTA-10 NSI Mode
Software Overview
Establishing a Communications Line for Dialing in to a Network
Establishing a Communication Line for Calls Dialed out to the PC
Establishing Remote and Local Network Sites
Name of Link
Remote Identifier
Link Type
Configuring the Modem Line
SLTA Password
Invoking an Application
Enabling a Callback
Diagnostics
The SLTALink Manager Programmatic Interface
Using the DOS "Stub" Driver
Characteristics of a Well-Designed System
Call Initiation
Dial-In to the Network Only
Dial-Out to the Remote PC Only
Dial-In / Dial-Out
Callback
Call Termination
Monitoring: Application Termination Strategy
Monitoring: Missing Messages after a Dial-Out
Monitoring: LNS Application Design Issues
Good Practices / Schemes that Work
49
50
51
53
54
55
55
55
55
56
56
56
57
57
58
58
58
58
59
59
60
60
61
61
62
62
8
Using the DOS Driver with SLTA-10 MIP Mode
Installing the SLTA-10 Mip Mode Driver for DOS
Buffer Options
Serial Bit Rate Options
DOS Device Options
Timing Options
Network Interface Protocol Options
Calling the Network Driver from a Host Application
Using the SLTA-10 Adapter Driver under Microsoft Windows 3.1x
67
68
68
69
69
70
71
73
75
SLTA-10 Adapter User’s Guide
8
9
Creating an SLTA-10 MIP Mode Driver
Purpose of the Network Driver
Example Network Drivers
Implementing an SLTA-10 MIP Mode Network Driver
Network Interface Protocol
Link Layer Protocol
ALERT/ACK Link Protocol
Buffered Link Protocol
Transport Layer Protocol
SLTA-10 Adapter Timing Data
Downlink Byte-to-Byte Receive Timeout
Uplink Message Life
ACK/NACK Receive Timeout
Uplink Timeout Message Retry Count
Session Layer Protocol
Downlink Buffer Request Protocol
Uplink Flow Control Protocol
Presentation Layer Protocol
10 Initialization and Installation
Initializing an SLTA-10 Adapter
Installing an SLTA-10 Adapter on a Network
Installing with LNS
Installing with the LonBuilder or NodeBuilder Tools
Installing an SLTA-10 Adapter with LonManager API, the DOS-based
LonMamager LonMaker Installation Tool, or DDE Server
11 Using the SLTA-10 Adapter with a Modem
Overview
SLTA-10 Adapter Connection States
Command Set Assumptions
Translated Characters
DTE Connections
Network Management Messages
EEPROM String Pool Management
Product Query
Send Modem String
Modem Response Query
Connection Status Query
Install Directory Entry
Dial From Directory
Hang-up
Install Password
Install Modem Configuration String
Install Hangup String (MIP mode only)
Install Dial Prefix
Install Hangup Timer
Configure Modem
Request /Release SLTA
SLTA-10 Adapter User’s Guide
77
78
78
78
81
81
81
83
84
85
85
86
86
86
86
86
88
89
91
92
93
93
93
94
95
96
97
98
98
98
99
101
103
103
104
104
105
105
106
106
107
107
108
108
108
109
9
Clear EEPROM Pool
Install NVConnect (NSI mode only)
Install NSIConnect (NSI mode only)
Install CallbackEnable (NSI mode only)
Report SLTAEE (NSI mode only)
Modem Compatibility
109
109
110
110
110
111
12 Using the DOS Host Connect Utility with the SLTA-10 MIP Mode
HCU Usage
Theory of Operation
Usage Examples
Suggested Modem Configurations
Status and Error Reporting
113
114
115
116
116
117
13 Modem Troubleshooting
Troubleshooting a Modem Link
SLTA-10 Adapter and Modem Do Not Answer or Pick Up
Modems Will Not Connect
SLTA-10 Adapter to Host Link Fails Completely
SLTA-10 Adapter to Host Link Fails Partially
SLTA-10 Adapter Sends Modem Configuration String,
But It Has No Effect
119
120
120
120
120
121
Appendix A — Windows DLL
ldv_close
ldv_get_version
ldv_open
ldv_read
ldv_write
123
124
125
126
127
128
SLTA-10 Adapter User’s Guide
121
10
Chapter 1
SLTA-10 Adapter Overview
The SLTA-10 Serial LonTalk Adapter (Models 73351, 73352, and 73353)
is a network interface that enables any host processor with an EIA-232
serial interface to connect to a LONWORKS network. The SLTA-10
Adapter extends the reach of LONWORKS technology to a variety of
hosts, including desktop, laptop, and palmtop PCs, workstations,
embedded microprocessors, and microcontrollers.
The SLTA-10 Adapter has two modes of operation: NSI and MIP modes.
The SLTA-10 NSI mode is compatible with LNS-based applications.
The SLTA-10 MIP mode is compatible with legacy applications based on
®
the LonManager API or the HA host application software. The SLTA10 MIP mode is a replacement for the SLTA/2 Serial LonTalk Adapter.
An externally accessible DIP switch determines the mode of operation.
SLTA-10 Adapter User’s Guide
11
Introduction
The SLTA-10 Adapter is the latest addition to the SLTA product family. It is an EIA-232
(formerly RS-232) compatible serial device that allows any host with an EIA-232 interface and
proper software to communicate with a LONWORKS network.
An SLTA-10 Adapter enables the attached host to act as an application node on a LONWORKS
network. When used with a PC host and the LNS Developer’s Kit for Windows software, the
SLTA-10 Adapter can be used to build sophisticated network management, monitoring, and
control tools for LONWORKS networks. The SLTA-10 adapter also can be used with legacy host
applications such as the LonManager LonMaker installation tool, LonManager DDE Server, or
applications based on the LonManager API.
An SLTA-10 Adapter can be connected to the host through a pair of modems and the telephone
network, allowing the monitoring, control, or network management computers to be remote from
the network. The SLTA-10 Adapter can be set up to answer incoming calls from a remote host. In
addition, any node on the local network can initiate a telephone call to a remote host computer. A
new feature, available only in the SLTA-10 NSI mode (see below), allows the SLTA-10 Adapter
itself to initiate a phone call to a remote host computer.
Figure 1 illustrates a typical node based on an SLTA-10 Adapter. Chapter 11, Using the SLTA-10
Adapter with a Modem, shows an SLTA-10 Adapter connected to a host through the telephone
network.
Host
Host Application
LNS or LonManager
Software (optional)
Driver
Interface
Network Driver
Network
Interface
EIA-232
Interface
SLTA-10
Network Adapter
Transceiver
Interface
L ONWORKS
Network
Figure 1 SLTA-10 Adapter Node Architecture with Local Host
SLTA-10 Adapter User’s Guide
12
Two Modes of Operation: SLTA-10 NSI and MIP Modes
The SLTA-10 Adapter provides both the network services interface (NSI mode) functionality for
use with LNS-compliant applications, and network interface functionality (MIP mode) for use with
LonManager API-based applications.
There are two separate firmware images in the SLTA-10 Adapter. The two separate images have
different link layer protocols, different network drivers, different buffer capacity, and different
functionality. The two modes of operation are the SLTA-10 NSI mode and the SLTA-10 MIP
mode. The mode of operation is controlled by an externally accessible DIP switch at power-up.
Table 1 illustrates the differences between the SLTA-10 NSI mode, the SLTA-10 MIP mode, and
the SLTA/2.
Table 1 SLTA-10 NSI and MIP Modes and SLTA/2 Feature Comparison
Feature
SLTA-10
NSI Mode
SLTA-10
MIP Mode
SLTA/2
YES
YES
NO
YES
NO
YES
Windows NT
(Windows 95
planned)
SLTALink Manager
(TAPI application)
DOS, UNIX,
Windows 3.1x
DOS, UNIX,
Windows 3.1x
SLTA-10 itself
or “Helper / Dialer ”
node
9-30VAC or DC
or wall mount
supply
Externally
accessible
Color coded,
removable screw
terminals
(Weidmuller)
10 MHz
HCU (DOS
application with
source code)
“Helper / Dialer ”
node on network
HCU (DOS
application with
source code)
“Helper / Dialer ”
node on network
9-30VAC or DC
or wall mount
supply
Externally
accessible
Color coded,
removable screw
terminals
(Weidmuller)
10 MHz
wall mount supply
or internal battery
YES
TP/FT-10
TP/XF-78
TP/XF-1250
YES
TP/FT-10
TP/XF-78
TP/XF-1250
To attach to a modem
Special null
modem cable
Special null
modem cable
Supports sleep mode
Message Tag 15 available
Default Buffer Configuration
NO
NO
See Chapter 4
NO
YES
See Chapter 4
Supports LNS applications
Supports LonManager API
applications
Available drivers
Software used to establish
connections via modems
Who initiates calls from a remote
network
Input power options
Configuration Switches
Network Connector
Processor Input Clock
Ready to wall mount
Transceiver versions available
SLTA-10 Adapter User’s Guide
Internally accessible
RJ45
5 MHz (10MHZ for
TP/XF-1250)
Bracket Required
TP/FT-10
TP/XF-78
TP/XF-1250
TP/RS485
Internal jumper
change to become
DTE
YES
YES
See SLTA/2
documentation
13
SLTA-10 NSI Mode Features
The most important new feature of the SLTA-10 NSI mode is the NSI functionality for use with
LNS-compliant applications. Other important features available only in the SLTA-10 NSI mode
include: SLTA-10 initiated dial-out, a Windows NT driver, a high performance link layer protocol,
and the SLTALink Manager software. These features are not available in SLTA-10 MIP mode.
The improved hardware form factor applies to both modes of operation and is listed in Table 1.
In SLTA-10 NSI mode, an SLTA-10 Adapter supports applications based on both the LNS software
and the LonManager API.
SLTA-10 MIP Mode Versus the SLTA/2
In SLTA-10 MIP mode, the SLTA-10 Adapter is a replacement for the SLTA/2 Serial LonTalk
Adapter, with an improved form factor. The network connector on the SLTA-10 Adapter is the
color-coded removable screw terminal (Weidmuller), instead of the RJ45 used on the SLTA/2
Adapter. The SLTA-10 Adapter input power options include 9-30VAC or DC, or a 9V wall mount
supply. The SLTA-10 Adapter operates at 10MHz for all transceiver types; the SLTA/2 operates at
5MHz or 10MHz, depending on transceiver type. In addition, the SLTA-10 configuration DIP
switches are externally accessible. The SLTA-10 enclosure has been improved to allow wall
mounting, without requiring a bracket.
The SLTA/2 and the SLTA-10 MIP mode use the same drivers and link layer protocol.
The SLTA-10 Adapter Configurations
The SLTA-10 Adapter is available with the following transceiver and power supply options:
•
Transceivers. The SLTA-10 Adapter is available with three LONWORKS channel options:
TP/FT-10, TP/XF-78, and TP/XF-1250. The FTT-10A (78kbps, free or bus topology), TPT/XF-78
(78kbps, bus topology) and TPT/XF-1250 (1.25Mbps, bus topology) transceivers all use
transformer-isolated, differential transmission.
•
Power supply. 9V plug-in power supplies are available in U.S./Canada (Model 78010), U.K.
(Model 78030), continental European (Model 78020), and Japanese (Model 78030)
configurations. Plug-in power supplies are sold separately. Alternately, screw terminals are
supplied for use with a 9 to 30VAC/DC power sources.
Software Availability
The SLTA-10 Adapter is not shipped with software.
Software for the SLTA-10 NSI mode is available on the LNS Developer’s Kit for Windows CD
(version 1.5 and higher), in the Connectivity Starter Kit (Model 58030-01), or from the Developer’s
Toolbox of the Echelon web site (www.echelon.com).
Software for the SLTA-10 MIP mode is distributed in the Connectivity Starter Kit (Model 5803001) and from the Developer’s Toolbox of the Echelon web site.
SLTA-10 Adapter User’s Guide
14
LNS 1.0, 1.01, and 1.5 Compatibility
When the SLTA-10 Adapter is connected directly to the PC host (i.e., no modems), the SLTA-10
Adapter uses a direct connection. For a direct connection, the SLTA-10 Adapter behaves like any
other NSI, such as the PCLTA-10 Adapter or the PCC-10 PC Card. In this case, an SLTA-10
Adapter may be used without issue with applications based on LNS 1.0, 1.01, or 1.50.
The SLTA-10 Adapter is also designed so that a PC host can be connected to the network through
a pair of modems and the telephone network. In this scenario, the PC is a remote host. When the
PC initiates the phone call to the SLTA-10 Adapter, the remote host is said to “dial-in to the
network”. When the SLTA-10 Adapter initiates a call to the PC, the SLTA-10 is said to “dial-out to
the remote host”. Once the phone connection is established, the application running on the remote
host can perform network management, monitoring, or control activities.
Applications based on LNS 1.0 or 1.01 do not have full functionality with respect to the SLTA-10
Adapter and modems because LNS 1.0 and 1.01 have default system behavior that is incompatible
with using the SLTA-10 Adapter through modems. For instance, an application based on LNS 1.0
and 1.01 terminates (i.e., shuts down) in a manner that interferes with one the automatic dial-out
initiation techniques. In LNS 1.0 or 1.01 when an LNS host application is terminated, all host
network variables and connections to these variables are removed from the LNS database. One
way the SLTA-10 Adapter can initiate a phone call, or automatically dial-out, is based on a
network variable update being sent to the SLTA-10 Adapter. Since the termination of the
application on the PC host results in the removal of all network variable connections to the host,
no network variable update can be sent to the SLTA-10 Adapter. Thus, one of the two
mechanisms that support automatic dial-out is unavailable.
LNS 1.0 and 1.01 have no special knowledge of whether the SLTA-10 Adapter is remotely
connected through a pair of modems. However, LNS 1.5 automatically detects that the SLTA-10
Adapter is remote at commissioning. Using a remote SLTA-10 Adapter affects the default system
behavior by allowing the system to function as desired. Upon termination of an application based
LNS 1.5, the LNS host API will determine if the NSI uses modems and if there are any explicitly
bound network variables on the host. If both of these conditions are met, LNS does not remove the
connections or host network variables. In addition, LNS leaves the SLTA-10 Adapter configured.
Thus, LNS 1.5 fully supports the SLTA-10 Adapter accessed through a modem configuration.
In summary, LNS 1.5 fully supports using the SLTA-10 Adapter with modems. LNS 1.0 and 1.01
do not support the use of the SLTA-10 with modems, although direct connect interfaces are
supported.
Note: A remote (via modems) LNS Server requires a dedicated SLTA-10 Adapter.
Thus, some networks may require multiple SLTA-10 Adapters —one for the
remote LNS Server and others to allow access for other PCs.
SLTA-10 Adapter User’s Guide
15
TAPI Compatibility
The SLTALink Manager software uses TAPI release 1.3 or higher. This is supported in Windows
NT 4.0, but not in Windows NT 3.51. Thus, Windows NT 3.51 does not support the use of the
SLTA-10 Adapter with modems, however, Windows NT 3.51 does support a direct connect
interface.
SLTA-10 Adapter User’s Guide
16
Chapter 2
SLTA-10 Adapter Hardware
This chapter provides a physical description of the SLTA-10 Adapter.
SLTA-10 Adapter User’s Guide
17
Mechanical Description
Figures 2 and 3 show the SLTA-10 Adapter in its enclosure. Figure 4 shows the SLTA-10 Adapter
board without an enclosure.
Figure 2 SLTA-10 Adapter Enclosure
SLTA-10 Adapter User’s Guide
18
Figure 3 shows a 1:1 view of the enclosure and may be used as a mounting template.
Figure 3 SLTA-10 Adapter Enclosure Keyhole View Mounting Slots
SLTA-10 Adapter User’s Guide
19
Component Side View
(S2)
Service
Button
(DS1)
Service
LED
(S1 )
Config.
Switch
Block
Neuron®
3150 ®
Chip
(J5)
EIA-232
Data Port
(DS2)
Power Indicator
LED
Transceiver
Section
(J3)
Power Input
(J2)
Power Input
(J1)
Network
Connector
SLTA-1Ø
© ECHELON 1996
Figure 4 SLTA-10 Adapter Without Enclosure (Component-Side View from Top).
Switches, Indicators, and Connectors
!
ESD Warning
This product contains components which are sensitive to static
electricity. Before installing or removing the network or serial
cables, touch earth ground with your hand to discharge any static
electricity which may have accumulated.
SLTA-10 Adapter User’s Guide
20
Table 2 describes the external connections and switches/LEDs on the SLTA-10 Adapter.
Table 2 SLTA-10 Adapter Interfaces
Interface
Service Button S2
Function
Pressing this switch grounds the service
request pin on the Neuron Chip within the
SLTA-10 Adapter. While this switch is
pressed, the service LED should light to
maximum intensity.
If Switch 3 (the Network Disable switch) on
the switch block (S1) is in the ON/up position
the service LED will light, but no service
message will be sent (if after power up but
before an application has configured the
SLTA-10 Adapter).
Service LED
DS1
(Yellow LED) Indicates that either the
Service Button is being
pressed or, if not:
on
The SLTA-10 firmware has
detected an unrecoverable
error and/or the node is
Applicationless. Reboot the
SLTA-10 Adapter from another
network interface on the
channel.
blinking
Node is unconfigured.
off
Node is configured or there is
no power. Check LED.
EIA-232 Data Port
Connector for the EIA-232 Serial I/O port.
J5
Standard DB9 female connection.
Network Connector
Orange connector for attachment to a twisted
pair channel. The mating plug (provided) is
Weidmüller PN 135606.
Two-Position
J1
SLTA-10 Adapter User’s Guide
21
Interface
Function
Unregulated
AC/DC Power Input
Black connector for the power input. The
mating plug (provided) is Weidmüller PN
125911.
Two-Position
J3
Unregulated
AC/DC Power Input
Barrel Connector
Female 2.1 mm inside diameter and 5.5 mm
outside diameter barrel input connector. For
use with Echelon power supplies, models
78010, 78020, 78030, and 78040.
J2
Power Indicator LED
DS2
(Green LED) Indicates presence of input
power to the SLTA-10 Adapter.
Connecting Power
Once the SLTA-10 Adapter is physically attached to the desired channel, power must be supplied
via one of the power input connectors. The SLTA-10 Adapter may be ordered with a plug-in power
supply, or may be used with any 9 - 30VAC/DC supply. Four plug-in power supply options are
available for the SLTA-10 Adapter, depending on the country in which the SLTA-10 Adapter is
used: USA/Canada, United Kingdom, Continental Europe, or Japan. The output voltage of these
supplies is a nominal +9VDC at 500mA. Power consumption is typically <1 Watt, independent of
input voltage.
Table 3 describes the basic characteristics of the four power supply types.
Table 3 Power Supply Characteristics
Country or
Region
Nominal Input Input range
Voltage
nominal ±10%
Frequency
Input Connector
Echelon
Model #
USA/Canada
120 VAC
108-132 VAC
60 Hz
2-prong, NEMA 1-15P
78010
Continental
Europe
230 VAC
207 - 253 VAC
50 Hz
2-prong, Euro Plug
78020
U.K.
230 VAC
207 - 253 VAC
50 Hz
3-prong, U.K. Plug
78030
Japan
100 VAC
90 - 110 VAC
50/60 Hz
2-prong, NEMA 1-15P
78040
SLTA-10 Adapter User’s Guide
22
Table 4 provides the specifications for power inputs to the SLTA-10 Adapter. The barrel connector
input, J2, is a standard female power plug with a 2.1 mm inside diameter and 5.5 mm outside
diameter, (LZR Electronics part number HP-114A, Radio Shack catalog number 274-1569, or
equal). A surge protector may be required between the AC mains and the power supply as neither
the power supply nor the SLTA-10 Adapter include surge protection.
Power supply jack J3 provides screw terminals via a Weidmüller (PN 11261) input connector
(provided) for connection to a 9 - 30VAC/DC power supply.
Table 4 Two-Prong SLTA-10 Adapter Power Supply Requirements
Power
Minimum
Nominal
Absolute
Maximum
Unregulated
DC
+9 VDC
+12 VDC
+30 VDC
Unregulated
AC
9 VAC
24 VAC
30 VAC
When power is connected, the yellow service LED will briefly flash and the green power indicator
LED will turn on. Once an SLTA-10 Adapter is powered and configured, the service LED will
remain off unless the service request switch is pressed.
Note: Do not attempt to power an SLTA-10 Adapter simultaneously from JP2 and JP3.
Mechanical insertion of a connector into JP2 disables the input to JP3.
SLTA-10 Adapter User’s Guide
23
SLTA-10 Adapter User’s Guide
24
Chapter 3
Cabling and Connections
This chapter demonstrates how to attach the SLTA-10 Adapter to a LONWORKS
network, a PC, and a modem.
SLTA-10 Adapter User’s Guide
25
Attaching the SLTA-10 Adapter
EIA-232 devices are configured as either Data Circuit-terminating Equipment (DCE) or as Data
Terminal Equipment (DTE). A DCE device connects to a DTE device, unless a null modem cable is
used. Using a null modem cable, a DCE device connects to a DCE device and a DTE device
connects to a DTE device. The SLTA-10 Adapter is a DCE device.
The standard configuration for a PC/AT EIA-282 serial I/O port is a DTE device. PCs usually take
the ‘terminal’ role in communications. Modems should always be DCE devices. To connect an
SLTA-10 Adapter to a PC, simply connect one end of the serial cable to the SLTA-10 Adapter, and
the other end of the cable to the PC’s serial port. To connect an SLTA-10 Adapter to a modem, a
special null modem cable must be used. Note that a standard off-the-shelf null modem cable will
not work in this configuration.
Echelon offers the Model 73380 SLTA-10 Null Modem Cable, which is a DB-9 male to DB-25 male
null modem cable. This and other cables used with the SLTA-10 Adapter are described in detail in
the chapter.
Attaching the SLTA-10 Adapter to a PC
Most PC serial I/O ports have a 9-pin male DB-9 connector, although some have a 25-pin male DB25 connector. Most serial I/O ports are hard-wired as DTE devices.
If connecting to a PC or modem equipped with a DB-9 connector, then use a straight-through cable
with one end terminated with a DB-9 male connector and the other end with a DB-9 female
connector. Plug the male end into the SLTA-10 Adapter and the female end into the serial I/O
port.
Table 5 PC DB-9 to DB-9 Connection
Signal Name
PC Connector
DB-9 Male
Cable DB-9
Female
Cable DB-9
Male
SLTA (DCE)
DB9 Female
RxD
Pin 2
Pin 2
Pin 2
Pin 2
TxD
Pin 3
Pin 3
Pin 3
Pin 3
Signal Ground
Pin 5
Pin 5
Pin 5
Pin 5
SLTA-10
(DCE)
PC (DTE)
DB-9
female end
DB-9
male end
Figure 5 DB-9 to DB-9 Connection
SLTA-10 Adapter User’s Guide
26
If using a PC or modem equipped with a DB-25 connector, then use a cable equipped on one end
with a DB-25 female connector and a DB-9 male connector on the other end. Plug the male DB-9
connector into the SLTA-10 Adapter and the female DB-25 connector into the PC.
Table 6 PC 25-Pin to DB-9 Connection
Signal Name
PC Connector
DB-25 Male
Cable DB-25
Female
Cable DB-9
Male
SLTA (DCE)
DB-9 Female
RxD
Pin 3
Pin 3
Pin 2
Pin 2
TxD
Pin 2
Pin 2
Pin 3
Pin 3
Signal Ground
Pin 7
Pin 7
Pin 5
Pin 5
SLTA-10
(DCE)
PC (DTE)
DB-25
female end
DB-9
male end
Figure 6 PC 25-Pin to DB-9 Connection
Attaching the SLTA-10 Adapter to a Modem
You must use the specific null modem cable described below to attach the SLTA-10 Adapter to a
modem.
Table 7 DCE Modem to SLTA-10 Adapter Connection (DB-9 to DB-9)
Modem Signal
Name
Cable DB-9
Male
Null
Modem
Cable DB9 Male
SLTA-10 (DCE)
DB-9 Female
RxD—Pin 2
Pin 2
Pin 2-3
Pin 3
TxD—Pin 3
TxD—Pin 3
Pin 3
Pin 3-2
Pin 2
RxD—Pin 2
DCD—Pin1
Pin 1
Pin 1-4
Pin 4
DTR—Pin 4
DTR—Pin 4
RTS—Pin 7
Pins 4 & 7
Pins
4, 7 - 6
Pin 6
DSR—Pin 6
GND—Pin 5
Pin 5
Pin 5-5
Pin 5
GND—Pin 5
SLTA-10
modem
DB-9
male end
Null
Modem
DB-9
male end
Figure 7 DCE Modem to SLTA-10 Adapter Connection (DB-9 to DB-9)
SLTA-10 Adapter User’s Guide
27
Table 8 DCE Modem to SLTA-10 Adapter Connection (DB-25 to DB-9)
Modem Signal
Name
Cable DB-25
Male
Cable DB9 Male
SLTA-10 (DCE)
DB-9 Female
RxD—Pin 3
Pin 3
Pin 3
TxD—Pin 3
TxD—Pin 2
Pin 2
Pin 2
RxD—Pin 2
DCD—Pin8
Pin 8
Pin 4
DTR—Pin 4
DTR—Pin 20
RTS—Pin 4
Pins 20 & 4
Pin 6
DSR—Pin 6
GND—Pin 7
Pin 7
Pin 5
GND—Pin 5
SLTA-10
modem
DB-25
male end
DB-9
male end
Null
Modem
Figure 8 SLTA-10 Adapter Null Modem Cable (DB-25 to DB-9)
Attaching the SLTA-10 Adapter to a Network
The network connector for the SLTA-10 Adapter is an orange two-conductor block type. Use the 2pin conductor that comes with the SLTA-10 Adapter to connect to the twisted-pair network.
If connecting to a network which currently has an RJ-45 type connector, only the wires attached to
pins one (1) and two (2) of the RJ-45 connector are needed. These are the wires that need to be
stripped, inserted, and screwed into the SLTA-10 Adapter terminal block (J1). See figure 9 for a
diagram of the RJ-45 Terminal Block.
1
8
Figure 9 RJ-45 Terminal Block
SLTA-10 Adapter User’s Guide
28
Chapter 4
Hardware Configuration
This chapter describes how to install and configure an SLTA-10 Adapter.
SLTA-10 Adapter User’s Guide
29
Configuring the SLTA-10 Adapter Hardware
There are eight configuration switches on the SLTA-10 Adapter's switch block (S1). These inputs
are read by the SLTA-10 firmware to configure or enable features. Figure 10 shows the factory
default settings for the SLTA-10 Adapter. Changes to the switch configurations will not occur
until the power is cycled on the SLTA-10 Adapter. The switches are read immediately after a
power reset.
The NSI switch selects between the legacy SLTA-10 MIP mode and a serial Network Services
Interface (NSI mode).
ON/up
OFF/down
.
.
0
1
2
d
d
u
a
B
B
a
u
d
u
u
a
B
A
u
to
B
a
S
I
d
1
G
F
N
2
C
G
F
F
C
C
G
3
.
.
.
.
.
.
1 2 3 4 5 6 7 8
Figure 10 SLTA-10 Adapter Default Switch Settings
Configuration Options
Interface Link Protocol Control (Switch1 / CFG3)
Buffered Link Protocol
ALERT/ACK Link Protocol
(default)
1
Figure 11 SLTA-10 Adapter Link Protocol Switch1 / CFG3
Switch1 / CFG3 controls the network interface link protocol used between the SLTA-10 Adapter
and a local host, when in MIP mode. For NSI mode, leave this switch in the default position. Two
link protocols are available for the SLTA-10 MIP mode: the SLTA-10 Adapter ALERT/ACK link
protocol and the buffered link protocol.
The ALERT/ACK link protocol is designed for host computers that cannot accept asynchronously
occurring streams of serial data at high speed. For example, a PC running DOS or Windows
SLTA-10 Adapter User’s Guide
30
cannot guarantee receipt of all characters in an input stream appearing back-to-back on a COM
port . ALERT/ACK link protocol (down position) is the default setting for the SLTA-10 Adapter.
When the SLTA-10 Adapter uses the ALERT/ACK protocol and it wishes to send data to the host,
it first sends a single ALERT character (hex 01). The host then responds with an ALERT ACK
character (hex FE) to indicate its readiness to accept the rest of the data. The ALERT/ACK
protocol places timing requirements on the host, and if these timing requirements are violated, a
driver error occurs. After the host network driver has sent the ALERT ACK character, it enters a
tightly controlled loop for accepting the remaining characters—usually with interrupts disabled.
If this option is enabled (switch in down position), the ALERT/ACK protocol will also be used when
the host wishes to send data to the SLTA-10 Adapter.
The buffered link protocol (up position) is designed for host computers and applications that can
accept and buffer back-to-back serial data without losing characters. For example, most real-time
operating systems and /dev/tty drivers in UNIX systems have this capability. In this case, the
SLTA-10 Adapter simply sends the uplink message without any handshake with the host. The
SLTA-10 Adapter does not support hardware handshake or XON/XOFF software flow control when
directly attached to a host. If the buffered link protocol option is enabled (up position), the
buffered protocol is also used when the host wishes to send data to the SLTA-10 Adapter. The
buffered link protocol should not be used when CFG2 is set to the Remote Host state (up position).
See Buffered Link Protocol in Chapter 9 for additional application restrictions when using the
buffered link protocol.
Modem Support (Switch 2 / CFG2)
Remote Host (modem)
Local Host
(default)
2
Figure 12 SLTA-10 Adapter Host Switch2 / CFG2
Switch2 / CFG2 controls the use of the SLTA-10 Adapter with a modem. If the SLTA-10 Adapter
is connected directly to a host, then CFG2 should be set to the Local Host state (down position).
This is the SLTA-10 Adapter default. If the SLTA-10 Adapter is connected to a modem, then
CFG2 must be set to the Remote Host state (up position) and CFG3 must be set to ALERT/ACK
(down position).
SLTA-10 Adapter User’s Guide
31
Network Disable (Switch3 / CFG1)
Network Disable
On
Network Enable (default)
(Disable Off)
3
Figure 13 SLTA-10 Adapter Network Switch 3 / CFG1
Switch 3 / CFG1 enables (down position) or disables (up position) network communications after
reset. If disabled, the SLTA-10 Adapter will not be able to communicate on the network after a
reset until it receives an niFLUSH_CANCEL command from the host.
The SLTA-10 Adapter prevents network communications by entering a FLUSH state. This state
causes the SLTA-10 Adapter to ignore all incoming network messages and prevents all outgoing
network messages, even service pin messages. In the disabled state, if the service pin is pressed
the service LED will light but no service message will be sent. This FLUSH state is provided to
prevent any other network management tools from performing network management functions on
the SLTA-10 Adapter before the SLTA-10 Adapter’s host has a chance to perform any of its own
network management functions. This state is canceled with the niFLUSH_CANCEL command from
the host.
An SLTA-10 Adapter network driver may automatically enable network communications when the
SLTA-10 Adapter is opened. For example, by default, the DOS network driver enables network
communications by automatically sending the niFLUSH_CANCEL command when the SLTA-10
Adapter is opened and when it receives an uplink message from the SLTA-10 Adapter indicating
that it has been reset. If the host application needs to configure the SLTA-10 Adapter before
enabling network communications, the /Z option on the DOS network driver command line must
be used to leave network communications disabled after the SLTA-10 Adapter is opened. When
the /Z option is specified and CFG1 is set to Network Disable On, the host application itself must
explicitly send the niFLUSH_CANCEL command after reset.
The Windows NT network driver does not provide a /z option. When using the Windows NT
network driver, network communication will proceed without any action by the host application if
Switch3/CFG1 is in the Network Enable position. Otherwise, if Switch3/CFG1 is in the Network
Disable On position, the host application must explicitly send the niFlush_CANCEL command.
If CFG1 is set to Network Enable (down position), the SLTA-10 Adapter will enable network
communications after a reset by going directly to the NORMAL state, thus allowing communications
without requiring the niFLUSH_CANCEL command.
SLTA-10 Adapter User’s Guide
32
If the SLTA-10 Adapter is used with a modem, and the application requires the SLTA-10 Adapter
to dial out to a host in response to a message from the network, then CFG1 must be set to Network
Enabled.
If the modem is set to receive incoming calls only, then the host can disable the FLUSH state after
the connection is established, in which case CFG1 can be set to either position. Table 9
summarizes these options:
Table 9 SLTA-10 Adapter Network Disable Switch Configuration
Network
Disable
Input
DOS Driver ‘
/Z ’ Option
Disabled
Specified
Host application
command
Not specified
(default)
Opening network driver
Don't care
Immediately after reset
(up position)
Disabled
(up position)
Enabled
(default)
When SLTA-10 Adapter
Enables Network
Communications
(down
position)
Serial Network Services Interface (Switch4 / NSI)
NSI Mode Firmware
(default)
MIP Mode Firmware
4
Figure 14 SLTA-10 Adapter Firmware Switch 4 / NSI
The SLTA-10 Adapter has an SLTA-10 NSI-mode firmware switch which is Switch4 / NSI. It is
factory set in the up position for use of the SLTA-10 NSI mode firmware. The down position is for
the MIP mode firmware.
SLTA-10 Adapter User’s Guide
33
Autobaud (AB)
The switch (5) labeled AB on the SLTA-10 Adapter is used to select automatic baud rate
detection—the autobaud feature. Autobaud must not be used when the SLTA-10 Adapter is used
with a modem. When autobaud is enabled, the SLTA-10 Adapter matches the serial bit rate of a
local host. When powered, the SLTA-10 Adapter looks for a ‘0’ byte from the host. The SLTA-10
Adapter cycles through all the serial bit rates until a ‘0’ is recognized. To initialize the SLTA-10
Adapter, the host must transmit eight binary zeroes (or ASCII NULs), spaced at least 50ms apart.
The SLTA-10 Adapter will try all of its bit rates until the zero character is recognized correctly,
and will respond with an ALERT ACK character (hex FE) when it selects the matching serial bit
rate. The SLTA-10 Adapter DOS network driver sends this sequence automatically if the
autobaud option (/A) is specified. The default for an SLTA-10 Adapter is Autobaud Disable.
Autobaud Enabled
Autobaud Disabled
(default)
5
Baud Determined by
Switches 6, 7, and 8
Figure 15 SLTA-10 Adapter Autobaud Switch 5 / AB
If the /A option is specified for the DOS network driver, the driver sends the autobaud sequence
every time the driver is opened. However, if the AB option is enabled, the driver must re-send the
autobaud sequence every time the SLTA-10 Adapter cycles power.
For the Windows NT network driver, there is no /A option. Using the Windows NT driver, the
autobaud sequence is attempted following power up if Autobaud Enabled is selected, otherwise
(the default) autobaud will not be attempted.
Serial Bit Rate (Switches[6..8] / BAUD[2..0])
Switches 6 to 8, named BAUD[2..0], are used to set the SLTA-10 Adapter serial bit rate. This
setting is only used if autobaud operation is disabled. There are eight available bit rates. The
SLTA-10 Adapter is configured for 38,400 bps with autobaud disabled by default.
All data are transmitted using 1 start bit, 8 data bits, no parity bits, and 1 stop bit.
The /B option is used to specify the serial bit rate to the DOS network driver.
For the Windows NT network driver, there is no /B option. When using the Windows NT driver,
the serial bit rate is configured using the SLTALink Manager as explained in Chapter 7.
SLTA-10 Adapter User’s Guide
34
6
7
8
115, 200 bps
6
7
8
9 600 bps
6
7
8
57,6 00 bps
6
7
8
2 400 bps
6
7
8
(d efault )
38,4 00 bps
6
7
8
1 200 bps
6
7
8
19,2 00 bps
6
7
8
300 bps
Figure 16 SLTA-10 Adapter Serial Baud Rate Switches 6, 7, and 8 / BAUD[2..0]
Table 10 SLTA-10 Adapter Autobaud Switch Configuration
Autobaud
Switch
BAUD Switches
‘ /A ’ Option on
DOS Driver
‘ /B ’ Option on DOS Driver
down
Specifies actual
baud rate
Don't care
Specifies actual serial bit
rate. Must match switchselected baud rate
Don't care
Must be specified
Specifies actual baud rate
position
up
position
SLTA-10 Adapter User’s Guide
35
Configuring the SLTA-10 Adapter Software
The types of messages passed between the host and the SLTA-10 Adapter are determined by
EEPROM configuration options. These options are described under Network Interface
Configuration Options in Chapter 3 of the LONWORKS Host Application Programmer's Guide.
The Network Disable Option affects whether or not the SLTA-10 Adapter can send and receive
application messages.
The buffer configuration parameters can be changed at any time by sending Write Memory
network management messages to the SLTA-10 Adapter, either from a host (using local network
management messages) or over the network from a network management tool. See the Neuron
Chip Data Book, Appendix A, for details of the data structures within the Neuron Chip that
control the partitioning of RAM for buffers. The following tables summarize the memory usage of
the default configurations for the respective two firmware versions resident on the SLTA-10
Adapter. The tables also list the maximum size of the buffer memory pool. If the SLTA-10
Adapter is configured to use more bytes than are available in the pool, it will behave erratically
since the RAM is used by the SLTA-10 firmware.
Table 11 SLTA-10 Adapter Default EEPROM Configuration
Configuration Parameters
Default Setting
Initial State
Unconfigured
Explicit addressing
Enabled
Network variable processing
Host Selection
Program ID string
"SLTA10" (Mip
Mode)
80-00-01-01-0300-xx-3C
(NSI Mode)
Table 12 SLTA-10 Adapter MIP mode Default Buffer Configuration
MIP-mode Buffer Parameter
Default Count
Default Size
in Bytes
Default Total
Bytes
Receive transaction buffers
8
13
104
Transmit transaction buffers
2
28
56
Application input buffers
15
255
3825
7
255
1785
Network input buffers
31
255
7905
Network output buffers
2
255
510
Priority app. output buffers
5
255
1275
Priority net. output buffers
2
255
510
Application output buffers
Total bytes used for buffers
SLTA-10 Adapter User’s Guide
15970
36
The NODEUTIL node utility application, available on Echelon’s web site, can be used to modify
the MIP mode buffer configuration from a PC host. See the README.TXT file included with
NODEUTIL for details.
By default, the SLTA-10 NSI-mode program ID consists of 8 bytes of program identification
information (80-00-01-01-03-00-xx-3C, where ‘xx’ is determined by the transceiver being used).
The host application must change this program ID to indicate its application. This is done
automatically in LNS by the LCA Object Server. If not using the LCA Object Server, the host
application needs to send local write-memory network management messages to change the
program ID. See the LNS Host API Programmer’s Guide for further information.
Table 13 SLTA-10 Adapter NSI-mode Default, and Minimum, Buffer Configuration
NSI-mode Buffer Parameter
Default Count
Default Size
in Bytes
Default Total
Bytes
Receive transaction buffers
16
13
208
Transmit transaction buffers
2
28
56
Application input buffers
3
255
765
Application output buffers
3
255
765
Network input buffers
2
66
132
Network output buffers
2
66
132
Priority app. output buffers
3
255
765
Priority net. output buffers
2
66
132
Total bytes used for buffers
2955
Note: It is very important that the LNS application change the SLTA-10 Adapter’s NSI
mode program ID. The Network Services Server (NSS) uses the program ID as a
unique identifier of a device's external interface. The first device encountered by the
NSS with a given program ID defines the external interface for all devices with that
program ID. To ensure that the NSI mode SLTA-10 Adapter’s unique external interface
is recognized by the NSS, it must given a unique program ID.
SLTA-10 Adapter User’s Guide
37
SLTA-10 Adapter User’s Guide
38
Chapter 5
The SLTA-10 NSI Mode Software
This chapter describes the Windows NT software used with the
SLTA-10 NSI mode. This software is available in the Connectivity
Starter Kit (Model 58030-01) as part of the LNS Developer’s Kit for
Windows (Model 34303), versions 1.5 and higher, and on the Echelon
web site at www.echelon.com.
Skip this Chapter if you are using the SLTA-10 MIP mode.
SLTA-10 Adapter User’s Guide
39
SLTA-10 NSI Mode Software Overview
The SLTA-10 Adapter is not shipped with any software. The Windows NT driver and SLTALink
Manager software are supplied in the Connectivity Starter Kit and as part of the LNS Developer’s
Kit for Windows.
The SLTA-10 NSI mode set-up installs three pieces of software:
the SLTA-10 NSI mode Windows NT Driver,
a “stub” driver to run legacy DOS and Windows 3.1x applications, and
the SLTALink Manager software.
The SLTA-10 Adapter includes firmware that moves the upper layers of the LonTalk Protocol from
the Neuron Chip within an SLTA-10 Adapter and onto a host processor. This firmware allows the
SLTA-10 Adapter to be used by a host application to send and receive LonTalk messages. The
firmware in the SLTA-10 Adapter is loaded in ROM and cannot be reprogrammed.
Using the SLTA-10 NSI mode, the host application may be one of two types. The first type of host
application is an LNS-based application, developed with the LNS Developer’s Kit for Windows.
The second type of application is a legacy DOS or Windows 3.1x application; these applications
make use of the “stub” driver declared in the config.nt file, which in turns accesses the Windows
NT driver. Echelon does not support 32-bit Windows applications that are not based on the LNS
software accessing the Windows NT driver.
Windows NT Software Installation Procedure
Prior to installation, ensure that the computer is running the Windows NT Operating System
(version 3.51 or higher for a direct connect interface; version 4.0 or higher for use with modems).
The SLTA-10 software cannot be installed from DOS, or a DOS shell, nor can it be installed on
Windows 3.1, or Windows 3.11, or Windows 95.
1.
Before installing the software, make sure that you have logged in as Administrator.
2.
Close all open programs.
3.
Insert the installation diskette into the PC.
4.
Click the Start button on the Windows task bar and select the run command. (If using with
Windows NT 3.51: Within Program Manager, choose the Run command from the File
menu.)
5.
When prompted for a program name, enter the following:
A:\SETUP.EXE
If necessary, replace A: with the drive letter which corresponds to the drive containing the
SLTA-10 NSI mode installation diskette.
6.
When prompted click the button marked “Next >”.
SLTA-10 Adapter User’s Guide
40
7.
When prompted for a destination directory, enter the desired installation directory. By
default this directory is c:\lonworks, unless previous LONWORKS products have been
installed and have registered a different path in the Windows Registry. The path may be
modified using the “Browse” button.
8.
The next screen presented is shown in figure 17. This will determine the LONWORKS
naming convention used for the SLTA-10 adapter.
Figure 17 LONW ORKS Device Naming Convention
9.
Clicking the “Next” button concludes installation. At the prompt to restart the computer,
remove the SLTA-10 NSI mode installation diskette and restart the computer. Note that the
Windows operating system will not recognize the SLTA-10 adapter until the computer is
restarted.
Windows NT Software Installation Results
The Windows NT installation software loads a selection of new files and updated Echelon files to
different locations on the PC's hard drive. The function and location of these files can be found in
readme.txt.
SLTA-10 Adapter User’s Guide
41
SLTA-10 Adapter User’s Guide
42
Chapter 6
The SLTA-10 Mip Mode Software
This chapter describes the SLTA-10 MIP mode software shipped with
the Connectivity Starter Kit (Model 58030-01) and on the Echelon web
site at www.echelon.com. This software is basically an updated version
of the SLTA/2 adapter software.
There is no 32-bit Windows driver available for the SLTA-10 MIP mode.
Skip this Chapter if you are using the SLTA-10 NSI mode.
SLTA-10 Adapter User’s Guide
43
SLTA-10 MIP Mode Software Overview
The SLTA-10 Adapter is not shipped with any software. The SLTA-10 MIP mode software and
drivers are supplied in the Connectivity Starter Kit and must be ordered separately. The software
includes ANSI C source code for HA, a sample host application for MS-DOS that can be used as a
basis for a user-developed host application on other host platforms. This application provides
examples of sending and receiving network variable messages, as well as allowing a node based on
an SLTA-10 Adapter to be installed and bound by a network management tool such as the
LonManager LonMaker Installation Tool or the LonBuilder network manager.
A network driver for DOS permits the SLTA-10 Adapter to be used with DOS applications. Source
code for a DOS network driver is provided as a basis for a user-developed network driver for other
hosts or operating systems. On a separate diskette, DLL software is provided to make it easier to
use the network driver under the Microsoft® Windows 3.1x operating system.
An executable program and source code is also provided for a Host Connection Utility (HCU),
which may be used to initiate and terminate the host to SLTA-10 Adapter connection when the
SLTA-10 Adapter is used with a remote host. An example written in Neuron C is also provided as
a basis for user-developed nodes on a LONWORKS network that need to initiate outgoing calls to a
remote host.
The SLTA-10 Adapter includes firmware that moves the upper layers of the LonTalk Protocol off
the Neuron Chip within an SLTA-10 Adapter onto a host processor. This firmware allows the
SLTA-10 Adapter to be used by a host application to send and receive LonTalk messages. The host
application may be a custom application as described in the LONWORKS Host Application
Programmer's Guide. The host application may also be a network management or monitoring
application based on the LonManager API, LonManager LonMaker installation tool, or
LonManager DDE Server. The firmware in an SLTA-10 Adapter is fixed in ROM and cannot be
reprogrammed.
Installing the SLTA-10 MIP Mode Adapter Software
The SLTA-10 Adapter software is supplied in the Connectivity Starter Kit as a diskette. The
SLTA-10 DOS driver operates under DOS, Windows 3.1x, and Windows 95 operating systems. To
install the SLTA-10 Adapter software, follow these steps:
1. Place the diskette in one of the disk drives of your PC. This will typically be the A: or B:
drive. Under the Windows 95 operating system, open a DOS console.
2. Start the automatic installation procedure by entering:
A:INSTALL [ENTER]
Substitute your disk drive name for the A: if you are using a different drive.
3. You will be asked to enter the name of your LONWORKS installation directory. C:\LONWORKS
is the default.
The SLTA-10 Adapter software will be installed in the SLTA sub-directory of your LONWORKS
directory, with the exception of the DOS network driver LDVSLTA.SYS. This file will be installed
in the BIN sub-directory of your LONWORKS directory. To install the DOS network driver into
your CONFIG.SYS file, follow the instructions in Chapter 8.
SLTA-10 Adapter User’s Guide
44
The SLTA directory will contain the following files:
•
Read-Me File. The README.TXT file includes a list of all the files on the distribution disk, and
also includes any updates to the documentation that occurred since the SLTA-10 Adapter
documentation was printed.
•
DOS Network Driver Sources. The SLTA-10 Adapter DOS network driver source code is
contained in the LDVSLTA directory. These files can be used as the basis for creating drivers
for hosts other than PCs running DOS (see also the UNIX network driver sources). See
Chapter 8 for a description of the SLTA-10 Adapter DOS network driver and Chapter 9 for a
description of how to write an SLTA-10 Adapter network driver for other hosts. See Chapter 4
of the LONWORKS Host Application Programmer's Guide for a description of the services that
must be supplied by a LONWORKS network driver.
The source files to build the DOS driver are:
•
LDVSLTA.CFG
Configuration file for Borland C.
MAKEFILE
Make file script for Borland C.
MDV_TIME.C
Code to manage the PC timer.
MDV_TIME.H
External interface definitions for the timer handler.
MSD_DEFS.H
Data structure and literal definitions.
MSD_DIFC.C
DOS driver interface functions.
MSD_DRVR.H
DOS driver interface and literal definitions.
MSD_EXEC.C
Main open, close, read, and write processing.
MSD_FRST.C
Module to be linked first in the network driver.
MSD_IRQC.ASM
Serial I/O interrupt procedure.
MSD_LAST.C
Module to be linked last in the network driver.
MSD_RAW.C
Direct serial I/O (modem) processing.
MSD_SEGD.ASM
Defines data segment register for driver.
MSD_SIO.C
PC/AT UART interface processing.
MSD_TXRX.C
Single byte link layer processing.
MSD_UART.H
Defines PC/AT UART registers.
External Interface Files. External interface files included for use by network
management tools are contained in the SLTA directory. External interface files are
included for the transceivers available for the SLTA-10 Adapter. See Binding to a
Host Node in Chapter 3 of the LONWORKS Host Application Programmer's Guide
for a description of how to use these files to bind to an SLTA-10 Adapter node.
Appendix B of the LONWORKS Host Application Programmer's Guide provides a
detailed description of how to modify these files to incorporate network variables
SLTA-10 Adapter User’s Guide
45
and message tags. These interface files are provided in version 3 formats. External
interface files in version 3 format are contained in the SLTA2\XIF_V3 directory.
The SLTA directories contain at least the following files:
•
NSLTA125.XIF
For SLTA-10 Adapter with a TP/XF-1250 transceiver.
NSLTA78K.XIF
For SLTA-10 Adapter with a TP/XF-78 transceiver.
NSLTAFT1.XIF
For SLTA-10 Adapter with a TP/FT-10 transceiver.
Sample Host Application. A sample host application is contained in the HA
directory. See Appendix A of the LONWORKS Host Application Programmer's Guide
for a description of the example. The following files are included:
README.TXT
A description of the sample host application.
HA.EXE
An executable version of the sample host application for
DOS. The SLTA-10 Adapter DOS network driver must
be installed to run this application.
HA.C
The main program for the example.
NI_MSG.C
A general purpose network interface library that can be
used with any host application.
APPLCMDS.C
Functions to handle application layer network variable
commands
NI_CALLB.C
The host-bound network management dispatcher.
APPLMSG.H
Application message handler function prototypes.
HA_COMN.H
The HA common declarations.
NI_CALLB.H
The definitions for the network management
dispatcher.
APPLMSG.C
Functions to handle application network variable and
explicit messages.
HAUIF.C
Command-line user interface for the example.
IOCTL.C
I/O control function for Microsoft C.
LDVINTFC.C
Device interface driver.
LDVINTFC.H
Include file for device driver interface.
NI_MSG.H
Definitions for network interface message structures.
NI_MGMT.H
Definitions for network management message
structures used by the example.
SLTA-10 Adapter User’s Guide
46
•
•
HAUIF.H
Definitions for the host application example user
interface.
MAKEFILE
A make file script for Borland C.
MSOFT.MAK
A make file script for Microsoft C.
HA_V3.XIF
An external interface file which may be used to bind
the example with LonBuilder.
HA_TEST.NC
A Neuron C program which may be loaded into a
Neuron emulator and bound to the sample host
application for testing.
DISPLAY.H
A Neuron C include file to drive the Gizmo 2 I/O
module for the test example.
Host Connect Utility. A sample host connection utility is contained in the HCU
directory, with source code. See Chapter 12 for details. The files supplied are:
HCU.EXE
Executable file for the Host Connection Utility.
HCU_MAIN.C
The main C source program.
HCU.CFG
Configuration file for Borland C.
MAKEFILE
Make file script for Borland C.
MSD_DRVR.H
Driver definition include file.
Neuron C Connection Example. A sample Neuron C program is contained in the
NC_APPS directory. This program shows how a node on a network connected to the
SLTA-10 Adapter can dial out and connect to a remote host computer. The files
supplied are:
DIALOUT.NC
Neuron C source program to dial out with the SLTA-10
Adapter.
GIZSETUP.NC
An example Neuron C program for configuring the
SLTA-10 Adapter. Configures the EEPROM directories
of an SLTA-10 Adapter using the Gizmo 2 I/O module
as the user interface.
SLTA_ANM.H
Definitions of SLTA-specific network management
messages.
Installing the Windows 3.1x DLL Software
A second diskette, labeled “LONWORKS Network Driver Interface for Windows 3.1x”,
contains the 16-bit Windows Dynamic Link Library (DLL) files. These files may be
used when developing a host application to run under Microsoft Windows 3.1x. The
file WLDV.DLL should be copied to your Windows directory (typically C:\WINDOWS).
The files LDV.H and LON.H
SLTA-10 Adapter User’s Guide
47
should be copied to a directory in the include file search path of your C compiler. The
file WLDV.LIB should be copied to a directory in the library search path of your
application linker. See Appendix A for information on using the Windows DLL.
Other Drivers
A UNIX network driver and source code for the SLTA-10 MIP mode is available on the
Echelon web site (http://www.echelon.com).
Chapter 9 discusses creating a SLTA-10 MIP mode driver for any host.
SLTA-10 Adapter User’s Guide
48
Chapter 7
Using the Windows NT Driver and SLTALink Manager
with SLTA-10 NSI Mode
This chapter describes the SLTALink Manager software, which
establishes and configures local and remote links from the host PC to
the SLTA-10 Adapter in NSI mode. A remote link requires a pair of
modems: one attached to the SLTA-10 Adapter and the other attached
to the host PC. The SLTALink Manager software controls a remote
SLTA-10 via modem through Windows’ Telephony Application
Programming Interface (TAPI) services under Windows NT 4.0 or later.
The SLTALink Manager determines when a standard driver open call in
a host application requires dialing and handles these cases. Thus, the
host application does not need to know if the network services interface
is a local SLTA-10 or a remote SLTA-10 Adapter.
NOTE: Remote SLTA-10 Adapters cannot be used with Windows NT 3.51
because Windows NT 3.51 does not include the 32-bit TAPI services used by the
SLTALink Manager software.
Skip this Chapter if you are using the SLTA-10 MIP mode.
SLTA-10 Adapter User’s Guide
49
Software Overview
The SLTALink Manager is sophisticated software that compliments the SLTA-10 Adapter NSI
mode firmware in many various ways.
The SLTALink Manager is a standalone application that can monitor a modem line, answer an
incoming phone call, associate the incoming call’s SLTA-10 Adapter (and hence its network) with a
LON device, and then launch a pre-determined application for that particular network or SLTA-10
Adapter. Combined with a well-designed system architecture and a well-designed LNS host
application, the SLTALink Manager lets a LONWORKS network establish a connection to a remote
PC through a pair of modems based on an event that occurs locally to the network.
The SLTALink Manager provides a graphical user interface for the creating, editing, and
diagnosing of “links”. Each link represents a particular SLTA-10 Adapter and its network. A link
identifies several important aspects of the set-up, including the type of connection (a remote
connection via modems or a local, direct connection), the COM port, the SLTA-10 Remote
Identifier (see below), the baud rate of the serial port on the SLTA-10 Adapter, and the dial-in
password, if any. In addition, the link indicates if a security callback is required and may be
associated with a host application. The link information is stored in a .s10 file, located by default
in the c:\lonworks\bin\slta10 folder.
The SLTALink Manager application can associate a link with a LON device name and then
interface with the SLTA-10 NSI mode driver for Windows NT. The SLTALink Manager handles
automatically dialing in to the network from the PC host, providing the ability for applications
with no knowledge of modems or phone numbers to run remotely through a pair of modems. The
SLTALink Manager’s GUI can be used to connect or disconnect to a remote SLTA-10 Adapter. In
addition, the SLTALink Manager has a simple, programmatic way to interact with the SLTA-10
driver for Windows NT. This programmatic interface allows an application to send down a
particular phone number for an SLTA-10 Adapter to dial or to send down certain commands, such
as hang-up.
Finally, the SLTALink Manager includes many diagnostic functions.
The SLTA-10 Adapter Link Manager software is used to control a remote SLTA-10 via a set (2) of
modems by using the Telephony Application Programming Interface (TAPI) services which are
built into the Windows NT 4.0+ operating system.
When attached directly to a PC, SLTA-10 Adapters use so-called “local” links. In this case, the
SLTALink Manager software interacts with the Windows NT driver and configures the necessary
parameters.
NOTE: Remote SLTA-10 Adapters cannot be used with Windows 3.51 because Windows 3.51 does
not include the 32-bit TAPI services used by the SLTALink Manager software.
Upon invocation of the SLTALink Manager software (SLTALINK.EXE), the main screen appears,
shown in figure 18.
SLTA-10 Adapter User’s Guide
50
Figure 18
SLTALink
Manager Main
Screen
Establishing
a
Communicat
ions Line for
Dialing in to
a Network
E
s
t
a
b
l
i
s
h
i
n
g
a communications line is the first task to be completed. Figure 19 displays the
message that appears when Dialing Preferences is chosen from the Line menu. This
message will only appear when telephony information has not been provided. This
case usually occurs if the computer has never been configured to use a modem.
Fig
ur
e
19
Fir
st
Ti
me
Us
e Message
SLTA-10 Adapter User’s Guide
51
This message in figure 19 may not be visible due to being covered by the SLTALink
Manager Dialing Preferences window. Moving the Dialing Preferences window should
reveal the message—if it exists. This leftmost window, shown in figure 20, will display
“???” for the “Dialing from:” indicator if there has been no dialing location created/chosen.
Figure 20 SLTALink Manager Dialing Preferences Window
Clicking on Dialing Properties will bring-up the Windows Location Information window
(figure 21) if the “Dialing from:” indicator reads “???”, or if TAPI information has been
previously entered — as shown in figure 20 as “Dialing from: The Office” — the Windows
Dialing Properties window (figure 22) will be displayed instead. The Dialing Properties
window is a tabbed subset of the Windows Telephony Control Panel.
Figure 21 Windows Location Information Window
SLTA-10 Adapter User’s Guide
52
Figure 22 Windows Dialing Properties Window
Establishing a Communications Line for Calls Dialed out to the PC
The next step is to select a line/modem to monitor for incoming calls. Figure 23 shows the Monitor
Line window that is displayed when “Monitor for SLTA dial-in” is chosen from the Line menu.
Only one line or modem can be monitored at a given time by the SLTALink Manager software.
However, multiple modems may be used for dialing into a network concurrent with monitoring the
one modem.
SLTA-10 Adapter User’s Guide
53
Figure 23 SLTALink Manager Monitor Line Window
The option list box will display the list of modems which have been set-up for use on this
computer. The list can be created/modified by using the Windows Modem Control Panel. Select
the line/modem to be used for incoming calls, then click OK.
Establishing Remote and Local Network Sites
Choosing Select/Action from the Link menu will display a screen similar to the screen shown in
figure 24. Figure 25 shows the default local setup.
Figure 24 Completed SLTALink Selection Window
Figure 25 Default SLTALink Selection
SLTA-10 Adapter User’s Guide
54
Select “Local SLTA-10” and click Edit. This action will present a window allowing the ability to
customize the connection—including changing it from Local to Remote, or modifying the name.
Name of Link
The name of the link should be fairly verbose, and/or something easy to understand. This is the
descriptor for the connection and location.
Remote Identifier
The Remote Identifier is used to identify a specific link when a dial-in to the computer occurs. It
represents the remote SLTA-10 Adapter in a 12-byte string of characters or hexadecimal numbers.
This value here should match the value stored in the remote SLTA-10 Adapter. It can be entered
here as a string in single quotes, or as a series of hexadecimal numbers separated by dashes.
If this field is blank or all zeroes (00-00-00-00-00-00-00-00-00-00-00-00) then the Remote
Identifier will be captured and stored here the next time this connection is made.
If this field is all FFs (FF-FF-FF-FF-FF-FF-FF-FF-FF-FF-FF-FF) then any Remote Identifier
will be accepted. The identifier will not be stored on the PC. This is known as the wildcard
Remote Identifier. The question mark (?) is also accepted as the wildcard Remote Identifier. The
SLTALink Manager software translates “?” to all FFs.
The Update Identifier checkbox indicates that the remote identifier will be read from the SLTA-10
Adapter by the SLTALink Manager and the new value will be stored in the .s10 file the next time
this link is used.
The SLTALink Manager software allows a user to create two links with different names but the
same Remote Identifier. However, when a network dials-out to a PC with multiple links each with
the Remote Identifier, the user has no control over which link is selected, which could result in
undesired behavior.
Link Type
The type of link specifies whether the SLTA-10 is directly connected to the PC (Local), or if the
SLTA-10 is at a different location and must be accessed via a set of modems (Remote).
Configuring the Modem Line
Clicking on “Configure Line” will cause the selected modem’s property window to appear. The
property window will reflect the options available to the driver of the modem such as volume
control and dial-tone detect.
TAPI services will handle the structuring of the call based on the Location Information (see figure
21).
SLTA-10 Adapter User’s Guide
55
SLTA Password
The Password box allows the user to enter the password for a remote SLTA-10 Adapter. Up to
eight characters may be entered. If entered, the password will be sent to the remote SLTA-10
adapter when a connection is made.
The password is not encrypted when stored on host computer.
Invoking an Application
The SLTALink Manager provides a space to enter the startup application for this link. This may
be a full executable path name, or the name of an application that can be found in the system’s
search path. Command line arguments may also added — including the special macros for link
connection variables:
%LINKNAME%
Expands to the name of the link, enclosed in quotes.
%DEVNAME%
Expands to the device name used by LONWORKS 32-bit applications to access
the logical device. This serves the same purpose as %DOSNAME% does for
DOS.
%NSSNAME%
Expands to the device name used by LonWorks LNS application, for SLTA-10s
this will be “SLTALONn”.
%DOSNAME%
Expands to the DOS device name for the logical device, provided the VDD is
installed, which would be “LONn”.
%ID%
Expands to the remote identifier. This is expressed as either a quoted ASCII
string, or as a series of hexadecimal numbers if the identifier contains nonASCII data.
%RESULT%
Expands to an unquoted word that represents the success or fail reason of the
connection.
The startup application will be launched when a dial-in occurs for this link, or optionally, when a
manual connection is made to the link. It will not start up if the link is connected to due to an
“auto-connect” case.
Enabling a Callback
If a remote SLTA-10 adapter has callback enabled then it will expect a callback command
whenever someone dials in to it. Check the Enable box if you need to enable the callback feature.
The callback command includes a directory index that points to a phone number stored in the
remote SLTA-10 adapter. If callback is enabled then one of the remote directory numbers
(“Address 1” though “Address 5”) can be select to be used to call the host back.
See Characteristics of a Well-Designed System below for a description of how to successfully
implement callback.
SLTA-10 Adapter User’s Guide
56
Diagnostics
A number of Diagnostic and testing services are provided via the Diagnostic Screen, accessed
through the Devices menu (see figure 26). The Test button retrieves status and error counts from
the SLTA-10 Adapter. The Service button will cause the SLTA-10 Adapter to broadcast a service
pin message on the network. The reset button causes a reset of the Neuron Chip in the SLTA-10
Adapter, but does not clear the Neuron Chip’s system image.
Some buttons are left for future releases of additional features.
Figure 26 Diagnostic Screen
The SLTALink Manager Programmatic Interface
The SLTALink Manager executable (SLTALINK.EXE) provides for a command line invocation.
Once the SLTALink Manager is up and running, a program can connect to a known link by
executing SLTALINK.EXE with a command line argument:
C:\lonworks\bin\sltalink.exe "Remote"
Quotes generally are needed since the link name can have embedded spaces. Another form will
disconnect the specified link:
C:\lonworks\bin\sltalink.exe "Remote" /D
Another form allows a phone number override:
C:\lonworks\bin\sltalink.exe "Remote" /# "1 (415) 867 5309"
Another form allows a password override:
C:\lonworks\bin\sltalink.exe "Remote" /P "passwd"
SLTA-10 Adapter User’s Guide
57
The /P and /# options may be combined.
Note that the phone number is in the form of a canonical number. This is defined as a country
code followed by a space, followed by an area code or city code enclosed in parenthesis, followed by
a space and the rest of the phone number. TAPI will take this and decide how to translate it before
the dial-out, based on your dialing preferences. Even if the call is local, the number should include
the area code / city code. This is the same format as the number that appears in the link selection
dialog under the Port/Number column.
Using the DOS “Stub” Driver
The DOS stub driver, which is added as part of the install, allows DOS and Windows 3.1x
applications to run on top of the SLTA-10 driver for Windows NT. The following line is required in
the CONFIG.NT file that is loaded on startup:
DEVICE=%SystemRoot%\system32\PCLTDOS.SYS /Dn
This makes the device ‘LONn’ available for DOS applications.
When LONn is opened by an application and the SLTALink Manager has been configured to
associate LONn with a particular link, the SLTALink Manager will auto-connect to the SLTA-10
Adapter locally or remotely. That is, the SLTALink Manager automatically dials-in to the network
defined by the link if required.
Characteristics of a Well-Designed System
Well understood strategies used with the SLTA-10 Adapter and the SLTALink Manager for the
following system functions are essential for reliable system design: Call Initiation, Call
Termination, and Monitoring.
Call Initiation
The four scenarios for call initiation are: dial-in to the network only, dial-out to the remote PC
only, dial-in / dial-out, and callback.
Dial-In to the Network Only
In the most straight-forward case, a user launches an application. The application opens the
driver, which is associated with a particular link. The SLTALink Manager application dials the
phone number in the link (or the phone number the application passes down to the SLTALink
Manager perhaps to a generic link) and establishes the connection. Similarly, the user could select
the link from within the SLTALink Manager and cause a manual connection. At this point, either
the SLTALink Manager would launch the pre-determined application from the information stored
in the link file or the user could manually launch the application. In all of these cases, the user is
assumed to initiate the call. The user could be a human operator or another application that
initiates a dial-in based on a clock, for example.
For the dial-in only scenario, the system strategy issues primarily have to do with associating the
link or phone number with the application. Where there are only one or two links, this is very
easy. When one PC host can be connected to many different networks, we offer two standard
solutions. The first is to have the user navigate the SLTALink Manager’s GUI. Under the Link
menu, the Select item lists approximately 40 links (of the 1000 possible). The second solution is a
SLTA-10 Adapter User’s Guide
58
monitoring application that programmatically interacts with the SLTALink Manager to send down
the appropriate phone number, perhaps to a generic out-going link.
Dial-Out to the Remote PC Only
The three common approaches for initiating a dial-out are: sending a network variable update to
the SLTA-10 Adapter, sending an AddMyNSI message to the SLTA-10 Adapter, or sending an
explicit message from a “Helper/Dialer” node on the network.
In the first case, the remote host application needs to have an explicitly-bound input network
variable and the SLTA-10 Adapter’s NSI mode EEPROM must be configured correctly. See
Chapter 11 for more information on configuring the SLTA-10’s EEPROM. See also Call
Termination below.
In the second case, the remote host PC is assumed to have the NSS engine and a second NSI on
the network (perhaps a service technician with a laptop running a PCC-10 card) is required to
send the AddMyNSI message. Also, SLTA-10 Adapter’s NSI mode EEPROM must be configured
correctly. See Chapter 11 for more information on configuring the SLTA-10’s EEPROM.
In the third case, a custom Neuron Chip application must be written.
All three cases could be used with the same SLTA-10 Adapter.
In the dial-out only case, besides the call initiation, the SLTALink Manager must be able to launch
the appropriate application – with the correct database and device driver name. One system
solution is to create a separate link for each SLTA-10 Adapter. Each link then stores the Remote
Identifier of its SLTA-10 Adapter after the first connection. Upon connection, the appropriate
application and command line arguments stored in the link get launched. A second viable
approach is to create a generic link that uses the wild card as a Remote Identifier to launch a
generic application using command line arguments to specify the appropriate network or database
and device driver name. These arguments are available and described above under Invoking an
Application.
Note: if the device driver information used in the application does not match the device driver
name being used by the link, the newly launched application can open a second device driver –
which may result in an attempt to dial-in to the network. Since the modem is still presumably in
use with the original dial-out call to the host PC, the second call will fail. The result is a systemlevel failure.
Dial-In / Dial-Out
These scenarios are the combinations and permutations of the above. However, it needs to be
pointed out that not all dial-in strategies can co-exist with all dial-out strategies. For example, if
the dial-out strategy involves having the SLTALink Manager match the incoming call to the wild
card Remote Identifier and if the dial-in strategy requires a separate link for each SLTA-10
Remote Identifier, then it is possible that a call initiated from the network will be received by the
SLTALink Manager and will be matched with the link created for the dial-in case. The correct
application may not be launched and a system-level failure may occur.
SLTA-10 Adapter User’s Guide
59
Callback
The SLTA-10 Adapter callback functionality works as follows: A call is initiated from some remote
PC to an SLTA-10 Adapter on a network, which must have its NSI mode EEPROM configured to
require callback. See Chapter 11 for more information on configuring the SLTA-10’s EEPROM.
The SLTA-10 Adapter answers; the remote PC identifies to the SLTA-10 Adapter one of the SLTA10 Adapters directory entries to use for the callback. An SLTA-10 configured to require a callback
will not accept any other direction from the host at this time. The original call is terminated, and
the SLTA-10 Adapter calls the phone number indicated in its directory. Note: this does NOT need
to be the phone number of the original remote PC that initiated the call. Typically, the SLTALink
Manager on the remote host dialed answers the call and launches the appropriate application.
Several possible system-level failures include:
The original remote host expects to receive the callback, but the directory index reflects the
phone number of another remote host.
The original remote host application opens an LNS database and initiates the first call. The
callback is directed back to the original remote host PC. The SLTALink Manager on this PC
receives the callback just like any other normal dial-out call and launches the application
contained in the link. At this point there may be two copies of the application open.
Depending on sharing configuration, the second application may fail because appropriate LNS
database in already opened.
To prevent these failures, Echelon recommends that the initial call should either be a manual
connection from within the SLTALink Manager or the initial call should originate from a “dummy”
application that terminates itself without opening the LNS databases.
Call Termination
The four scenarios for call termination include: termination of the host application, application
controlled hang-up, a manual disconnect in the SLTALink Manager, and time-out. In all of these
cases, the important system-level issues involve making sure that the termination strategy is
compatible with the call initiation strategy.
The behavior of an application at termination is not always known. By default, applications based
on the Object Server of LNS 1.5 and higher should exhibit two types of behavior. First, if the
interface adapter is an SLTA-10 Adapter in NSI modem using modems and there are explicitly
bound network variables to the host application, then at the LNS application’s termination the
host network variables and their connections should not be removed from the LNS database. This
behavior facilitates the use of the first case described under Dial-Out to the Remote PC Only where
a network variable update addressed to the SLTA-10 Adapter’s NSI mode results in a call being
initiated. Second, if the interface adapter is not an SLTA-10 Adapter in NSI modem using
modems or there are no explicitly-bound network variables to the host application, then at the
LNS application’s termination, any host network variables and their connections are removed
from the LNS database and the other nodes in the network. In addition, if the interface does not
host the LNS database, upon termination of the LNS application the interface is deconfigured.
The second behavior described would be desirable in the event that multiple remote host PCs
needed to be able to dial-in to the same network. As long as no explicitly-bound network variables
were left when the host applications terminated, then several remote PCs could share one SLTA-
SLTA-10 Adapter User’s Guide
60
10 Adapter. Note: this assumes that the NSS engine exists somewhere on the network and is not
located on one of the remote PCs sharing the single SLTA-10 Adapter.
Both an application controlled hang-up (using the SLTALINK.EXE programmatic interface) and a
manual disconnect in the SLTALink Manager will terminate the phone call; however, neither
results in the termination of the host application. In these scenarios the host application remains
running as the call can be re-established by the host application itself, by a manual connect in the
SLTALink Manager, or a dial-out initiated on the network. The disadvantage of these system
solutions is that they do not scale well to monitoring multiple networks on one PC. The result is
many applications continually and concurrently running on the same PC. Also, one possible
system failure to avoid is that the SLTALink Manager settings may result in multiple copies of the
host applications.
By default, the SLTA-10 NSI mode will terminate a phone call after three minutes with no traffic
going across the modems. As with the application-controlled hang-up and the manual disconnect
in the SLTALink Manager, this scenario does not result in the application terminating. This
scenario therefore carries the same advantages and disadvantages as those described in the
previous paragraph.
Monitoring: Application Termination Strategy
There are three strategies for terminating the remote LNS monitoring application.
The first strategy is to require user intervention to shut down or terminate the application. No
special software must be written for this case. For the dial-in to a network scenario when the call
is user initiated, the user is presumably available to shut down or terminate the application. In
the dial-out case, the requirement of user intervention to terminate the application means that
every call from a network is seen by an user. If the network is sending alarms, user intervention
is highly desirable.
The second approach requires a node on the network to send a network variable update to the host
when the network no longer requires the host application to be up and running. When the host
application receives this network variable, it should enter a shut-down routine. This approach
places the responsibility on the network to determine when the host application is needed and
requires a hook in the monitoring application, but provides a level of automation when dial-out is
used.
The third approach is the most blunt. In this scenario, the remote host application terminates
itself either after completing a series of actions or based on a timer. We do not recommend this
scenario for the general scenario, but it has certain appeal for some applications. For example, a
connection may be established through dial-in or dial-out based on a timer. The host application
could then take a series of measurements from the network, log them to a file, and then terminate
itself.
Monitoring: Missing Messages after a Dial-Out
In general, the message that triggers a dial-out from the SLTA-10 on the network to a remote PC
host is lost.
When a network variable update is sent to the SLTA-10 Adapter and no phone connection is
currently up and running, the SLTA-10 Adapter is typically configured to dial-out to the host. On
the remote PC host, the incoming call is answered by the SLTALink Manager application. The
SLTA-10 Adapter User’s Guide
61
SLTALink Manager then reads the Remote Identifier in the SLTA-10 Adapter and searches
through all the .s10 files for a match. The SLTALink Manager application then typically launches
the application listed in the link with optional command line arguments available, for example, to
open the correct LNS database with the correct device name. The process of opening the LNS
application results in the buffers of the SLTA-10 Adapter being over-written; thus, the original
message is lost. Since this message network variable update is by definition important enough to
warrant establishing a connection to the host, a system strategy is required so that this data
reaches the host.
The two basic system strategies are: (1) to have the node on the network continue to send out the
network variable update until the host application sends a message to the node telling it to stop, or
(2) to have the host application seek out the information upon being launched. The first approach
places the burden on nodes in the network; the second approach places the burden on the host
application. The first is more direct and is likely to result in the information getting to the host
more quickly. The second approach has the primary advantage that no special Neuron Chip
application code is required; also, since the call initiation and host application launch may require
minutes, the time it takes the host application to poll several network variables is not significant.
In the best scenario, upon being launched the host application would first check with a datalogging
node on the network that records alarms and also the system state, mode, or health information.
Monitoring: LNS Application Design Issues
A well-designed LNS monitoring application using the SLTA-10 Adapter through modems should
use the correct version and layer of LNS, should handle initialization of the application with the
correct LNS database and device driver name, and should have a phone call session termination
and an application termination strategy.
The remote monitoring application is based on LNS Object Server of LNS 1.5 or higher.
Applications based on the LNS 1.0 and LNS 1.01 do not behave well by default and do not allow
for certain dial-out scenarios. Applications written at the NSS layer are not supported for use
with the SLTA-10 Adapter across a pair of modems.
The remote monitoring application should open the correct LNS database with the correct device
driver. Specifically, the mapping of the Remote ID to the LNS database should be handled by the
application. We suggest using the command line arguments with the information available from
the SLTALink Manager. Note LNS capacity keys may need to be hard-coded in the monitoring
application.
Finally, the LNS application needs to implement a termination strategy that meets the needs of
the application and the system.
Good Practices / Schemes that Work
Use these guidelines to avoid the system-level failures detailed above:
When expecting the SLTA-10 Adapter to dial-out from the network to a remote PC, dedicate
one SLTA-10 Adapter to dial-out and always have that SLTA-10 Adapter connect to the same
remote PC. Make sure that the NSI EEPROM is configured correctly. See figure 27.
If LNS is connected to the network through modems, dedicate one SLTA-10 Adapter in the
network to handle dial-out and dial-in with this PC that has the NSS server. Make sure that
the NSI EEPROM is configured correctly. See figure 28.
SLTA-10 Adapter User’s Guide
62
Several PCs can share one SLTA-10 Adapter as long as the calls are all initiated on the remote
PC hosts (i.e., dial-in only) and each remote LNS application removes the bound connections to
its host before terminating. See figure 29.
Host
Monitoring Application
Remote LCA
Driver
Interface
SLTALink Manager and
Network Driver
Modem
Dial-out
Modem
Null Modem Cable
SLTA-10 Adapter
Transceiver Interface
LNS Server
LonWorks Devices
Figure 27 Dedicated SLTA-10 Adapter using Dial-out
SLTA-10 Adapter User’s Guide
63
Host
Monitoring Application
LNS Server
Driver
Interface
SLTALink Manager and
Network Driver
Modem
Dial-in and
Dial-out to the
LNS Server
Modem
Null Modem Cable
SLTA-10 Adapter
Transceiver Interface
LonWorks Devices
Figure 28 Dedicated SLTA-10 Adapter hosting the NSS
SLTA-10 Adapter User’s Guide
64
Host
Host
Monitoring Application
Monitoring Application
Remote LCA
Remote LCA
Driver
Interface
Driver
Interface
SLTALink Manager and
Network Driver
SLTALink Manager and
Network Driver
Modem
Modem
Dial-in
Modem
Null Modem Cable
SLTA-10 Adapter
Transceiver Interface
LNS Server
LonWorks Devices
Figure 29 Shared SLTA-10 Adapter using Dial-in
SLTA-10 Adapter User’s Guide
65
SLTA-10 Adapter User’s Guide
66
Chapter 8
Using the DOS Driver with SLTA-10 MIP Mode
This chapter describes the DOS network driver supplied with the
Connectivity Starter Kit. The DOS network driver provides a deviceindependent interface between a DOS or Windows 3.1x host application
and the SLTA-10 Adapter in MIP mode. The driver is configurable to
use one of four PC/AT serial ports, COM1 through COM4, at one of eight
serial bit rates.
Skip this Chapter if you are using the SLTA-10 NSI mode.
SLTA-10 Adapter User’s Guide
67
Installing the SLTA-10 MIP Mode Driver for DOS
The DOS driver is supplied on the floppy diskette included with the Connectivity Starter Kit. The latest
version of this driver may be obtained from the Echelon web site.
The SLTA-10 MIP mode network driver for DOS is installed by adding a DEVICE command to the
DOS CONFIG.SYS file. Edit the CONFIG.SYS file to include the line:
DEVICE=C:\LONWORKS\BIN\LDVSLTA.SYS [options]
Substitute your drive and directory name if other than C:\LONWORKS\BIN. Reboot the PC after
adding this line to load the driver. For example, the following command would be used with a
locally attached SLTA-10 Adapter in MIP mode installed on COM2 as device LON1 running at
115,200 bps with autobaud enabled:
DEVICE=C:\LONWORKS\BIN\LDVSLTA.SYS /P2 /D1 /B115200
Warning! The /A option must be present in the CONFIG.SYS entry if the SLTA-10 Adapter
AutoBaud Switch5/AB is in the Enabled, UP position, or the SLTA-10 Adapter will not function
correctly. The /A option also may be left in the CONFIG.SYS entry if the SLTA-10 Adapter
Autobaud switch is in the disabled (default), DOWN position.
The available options for the SLTA-10 MIP mode network driver for DOS are described in the
following sections.
Buffer Options
/Onn
Sets the number of output (downlink) buffers within the driver to <nn>. The
buffer sizes within the driver are pre-set to accommodate 255 byte packets.
The SLTA-10 Adapter in MIP mode has application output buffers that may be
increased to as large as 255 bytes. There must be at least 2 buffers and the
maximum allowed number for <nn> is limited by the size of the buffer (258)
times the total number of input and output buffers within the driver. The
entire buffer space plus the driver code itself cannot exceed 64Kbytes. The size
of the driver code itself is 9Kbytes. The number of output buffers required is
determined by the characteristics of the host application. If the host
application always waits for an outgoing message completion before sending
another message, then only two buffers are required. If the host application is
set up to overlap transactions, more buffers may be required. In this case
greater parallelism may be achieved at the expense of host application code
complexity.
/Inn
Sets the number of input (uplink) buffers within the driver to <nn>. The buffer
sizes within the driver are pre-set to accommodate 255 byte packets. The
SLTA-10 Adapter has application output buffers may also be increased to as
large as 255 bytes. There must be at least 2 buffers and the maximum allowed
number for <nn> is limited by the size of the buffer (258) times the total
number of input and output buffers within the driver. The entire buffer space
plus the driver code itself cannot exceed 64Kbytes. The number of input
buffers required is determined by the expected incoming traffic and the
capability of the host application to process it. If the incoming traffic is bursty,
more input buffers are required. If the application cannot process incoming
SLTA-10 Adapter User’s Guide
68
traffic fast enough, the input buffer pool will fill up with unprocessed packets.
In that case, the SLTA-10 Adapter will not be able to pass any new data to the
host, and the input application buffers in the SLTA-10 Adapter will start to fill
up. Once that occurs, messages will be lost, possibly causing incoming LonTalk
transactions to be retried, and eventually causing the sender of the message to
receive a failure indication.
Serial Bit Rate Options
/Bnnnnnn
Sets the serial bit rate to <nnnnnn>. The available serial bit rates are listed
below.
Available serial bit rates are:
1200, 2400, 9600, 14400, 19200, 38400, 57600, 115200.
This rate represents the serial bit rate between the PC and the SLTA-10
Adapter when using a direct serial connection, and between the PC and the
modem when using a remote connection. For remote connections, the PC-tomodem serial bit rate, telephone line speed, i.e., modem to modem serial bit
rate, and the modem-to-SLTA-10 Adapter serial bit rate may be different. The
PC-to-modem serial bit rate is controlled by the network driver on the PC
using the /B option; the telephone line speed is selected by the modems based
on modem configuration; and the modem-to-SLTA-10 Adapter serial bit rate is
controlled by the hardware configuration of the SLTA-10 Adapter as described
in Chapter 4 (autobaud cannot be used in this configuration).
For local connections with the SLTA-10 Adapter Autobaud option disabled, the
serial bit rate specified by this driver option must match the rate specified by
the configuration switches.
/A
If you are using the default hardware configuration (autobaud disabled), the autobaud
option (/A) does not need to be enabled .
Enables the autobaud feature. This provides the autobaud sequence whenever the
driver is opened. The default setting for the driver is Autobaud Disabled. If the
Autobaud input on the SLTA-10 Adapter hardware is enabled, then this option
must be specified. As described in Chapter 4, the default setting for the AB
switch on the SLTA-10 Adapter is disabled, so the /A option does not need to be
specified with the default hardware configuration. This option may not be used
with the modem support (/M) option.
DOS Device Options
/Pn
Sets the serial port to <n> where <n> is 1-4 for COM1 - COM4. The default is
COM1.
/Dn
Defines the device unit number as <n>, where <n> is between 1 and 9, so that
the DOS device name is “LON1” through “LON9”. The default is 1 for “LON1”.
This option can be used to support multiple network interfaces on a single PC.
For example, this device name is passed as a parameter to
SLTA-10 Adapter User’s Guide
69
lxt_open() when using the LonManager API. When invoking the sample
host application HA, the device may be specified with the -D option, for
example:
HA -DLON2
/Un
Sets the serial port interrupt request number (IRQ) to a non-standard value
<n>, where <n> is between 1 and 7. If the serial port in use is COM3 or COM4,
you may want to use a unique, unused IRQ for that port. Many serial ports and
internal modems allow the selection of a non-standard IRQ such as IRQ2 or
IRQ5.
/C
Enables communications interrupt chaining. Some PCs may incorporate up to
four serial ports. If supported by the serial hardware, COM1 and COM3 may
share the same interrupt (as do COM2 and COM4). This option may enable
the driver to support the shared interrupt by “chaining” to the interrupt vector
that was in place when the driver was loaded. This option is not necessary if
your system does not use COM3 or COM4, or if COM3 or COM4 use a different
interrupt request number. When installing two SLTA-10 Adapter network
drivers on a system on COM1 and COM3 (or COM2 and COM4 with the same
interrupt request number), the last installation of the driver should use this
option. Here is an example of a CONFIG.SYS file entry for such a system.
DEVICE=C:\LONWORKS\BIN\LDVSLTA.SYS /B38400 /A /P1
DEVICE=C:\LONWORKS\BIN\LDVSLTA.SYS /B38400 /A /P3 /C
Table 14 Hardware Configurations COM Ports
Device
I/O Address
Interrupt (*)
COM1
0x3F8
4
COM2
0x2F8
3
COM3
0x3E8
4
COM4
0x2E8
3
(*) May be changed with the /U option
Timing Options
/Rnn
Defines the flush/retry count in 55ms intervals. This value is used in error
states for re-transmitting requests and for terminating receive flushes when
input errors occur. Normally, this option should not be specified.
/Wnnn
Includes a delay of <nnn> microseconds when transmitting downlink. This
parameter can be used to pace the rate at which bytes are transmitted
downlink to the SLTA-10 Adapter, and may be required for high-performance
network management tools such as LonMaker. The delay is executed following
the transfer of each data byte to the host's UART, and only after the first 15
bytes have been sent. Since the SLTA-10 Adapter employs a 16-byte deep
FIFO buffer in its UART, the first group of bytes sent do not need to be paced.
SLTA-10 Adapter User’s Guide
70
The pacing delay will have no effect unless it is greater than the actual period
it takes to transmit a single byte at the given serial bit rate. The time taken to
transmit a byte is 173 µs at 57,600 bps, and 86 µs at 115,200 bps. This option
should be used at 115,200 bps if messages greater than 16 bytes are to be
transmitted. A value of /W120 is suggested. This option is not required at the
serial bit rate of 38,400bps or slower.
/Z
By default, the SLTA-10 MIP mode firmware disables network
communications after a reset by entering a FLUSH state. This state causes
the SLTA-10 Adapter to ignore all incoming messages and prevents all
outgoing messages, even service pin messages. The SLTA-10 MIP mode
network driver for DOS automatically enables network communications when
the SLTA-10 Adapter is opened and when it receives an uplink message from
the SLTA-10 Adapter indicating that it has been reset. However, the host
application itself must explicitly enable network communications if the /Z
option is specified and the Switch3/CFG1 input is set to Network Disable (UP
position). See Chapter 4 for more information.
Host applications which need to configure the SLTA-10 Adapter prior to
enabling network communications should use this option. This option should
not be used with the LonManager API, LonManager LonMaker, or the
LonManager DDE Server. More information about the niFLUSH_CANCEL
message is provided in the LONWORKS Host Application Programmer’s Guide.
Network Interface Protocol Options
/F
Enables the full interrupt mode of the driver. If this option is not specified, the
driver will disable interrupts for the duration of each link-layer transfer. This
ensures that no data will be lost due to other system interrupts, and is
acceptable at high serial bit rates. The driver will use interrupts for the first
byte of each uplink interface buffer. When the uplink interrupt is received, the
driver reads the rest of the message without interrupts via polled I/O.
Interrupts are disabled during the uplink transfer. This assures that no other
system interrupts will occur resulting in lost uplink data frames. Downlink
transmissions are sent directly via polled I/O of the serial port from the write
function call. The host write functions will not return until the message has
been sent downlink. When using the ALERT/ACK link protocol, interrupt
latency is not a problem, since the SLTA-to-host protocol includes an
acknowledgment of the start of the message. The driver employs timeouts in
order to prevent lockout of the write function, and timeouts for clearing various
states of the transmitter/receiver when line errors occur.
When operating at lower serial bit rates, it becomes less desirable to disable
interrupts for long periods. The trade-off with using the full interrupt mode is
that other system interrupts may cause loss of data in the serial port's UART.
If the /F option is specified, the driver uses interrupts for every uplink and
downlink byte transferred. Downlink messages are buffered from the device
write function and are sent downlink under interrupt control. Uplink
messages are received under interrupt control and are buffered also. This
option should be used for serial bit rates of 9,600 bps or slower.
/M
Enables modem support and the reliable transport protocol. This option must
be specified if the host is to communicate with the SLTA-10 Adapter via a
modem connection. The SLTA-10 Adapter must be configured with
SLTA-10 Adapter User’s Guide
71
Switch2/CFG2 input in the Remote Host setting (UP position). When
connected, the selected SLTA-10 Adapter and Host network interface link
protocol is in effect. When disconnected the only allowable link layer traffic is
of the ‘modem direct’ type, where ASCII strings are being exchanged between
the host and the modem, for example, AT commands to dial out. Any other
network interface traffic is not allowed when disconnected from the SLTA-10
Adapter. Calls to the read function will result in no network interface data
messages (LDV_NO_MSG_AVAIL), and any call to a write function that needs to
communicate with the SLTA-10 Adapter via the modems will result in a No
Output Buffers Available error (LDV_NO_BUFF_AVAIL). Once the connection is
made, normal network interface traffic may resume.
This option also enables the reliable transport protocol. This protocol includes
the addition of a message sequence number and the end of message
ACK/NACK code. See Chapter 4 for a description of this protocol.
/N
Disables the ALERT/ACK network interface link protocol, and enables the
buffered network interface link protocol. Network interface messages are sent
without waiting for the ALERT ACK response. Both sides of the interface (the
SLTA-10 Adapter and the driver) must have the same setting. This option
should not be used with the /M option.
/Q
Allows modem responses to be sent uplink to the host. When the telephone
link is disconnected, these messages are ASCII strings with the network
interface command type niDRIVER (0xF0). If /Q is specified, the host
application must be able to handle messages, such as NO CARRIER, that might
come from the modem itself if problems occur in the connection.
/X
Disables the buffer request protocol. When this option is enabled, the driver
requests the buffer count from the SLTA-10 Adapter using the niSBUFC (0xE7)
command whenever the interface is opened, or when the interface is reset, and
reports an niRESET to the host. The driver keeps track of the number of
available output buffers in the SLTA-10 Adapter by examining both uplink and
downlink messages. This option prevents the use of one message type: A local
network management command not using a request/response service.
Normally this type of message is not used. One exception could be the Set
Node Mode: Reset command, which would result in the node resetting and
the buffer management recovering on its own anyway. Otherwise, if this type
of message is used, no uplink response would occur and the driver could not
track the fact that a new output buffer has been made available.
SLTA-10 Adapter User’s Guide
72
Table 15 Configuration Switches and DOS Driver Options
Input
Input State
Driver Option
Switch2/CFG 2
Local Host; No Transport Protocol
/M not specified
Switch2/CFG 2
Remote Host; Reliable Transport
Protocol
/M specified
Switch1/CFG 3
ALERT/ACK Link Protocol
/N not specified
Switch1/CFG 3
Buffered Link Protocol
/N specified
Calling the Network Driver from a Host Application
The SLTA-10 MIP mode network driver for DOS supports the open, close, read, write, and
ioctl DOS calls. See Chapter 4 of the Host Application Programmer's Guide for more details.
When the SLTA-10 MIP mode network driver for DOS is loaded during execution of the
CONFIG.SYS file, it does not attempt to communicate with the SLTA-10 Adapter.
When the network driver is opened with the DOS open call, it establishes communications with
the SLTA-10 Adapter. The network driver returns an error if this fails, for example, if the
SLTA-10 Adapter is disconnected, powered down, or configured incorrectly. If the open call
succeeds, the driver enables network communications by clearing the SLTA-10 Adapter FLUSH
state, if configured to do so.
The DOS read call is defined to return the number of bytes read from the device. Some
LONWORKS standard network drivers return 0 if there are no uplink messages available. DOS
reports this as an end-of-file condition and prevents further reads from succeeding. However, the
SLTA-10 Adapter driver returns a length of 2, and sets the first byte of the caller's buffer (the
cmd/queue byte) to 0 to indicate that there is no uplink message available.
Normally, the DOS read and write calls are not used with LONWORKS standard network
drivers. This is because any error from the network interface will display the familiar Abort,
Retry, Fail? error message from DOS, unless the caller has installed a critical error device
handler. Therefore, DOS applications using a network device typically call direct entry points into
the driver. This also allows more detailed error status to be returned to the application. The
addresses of these entry points are obtained by calling the ioctl() function of the driver.
This function call is used as follows:
int ioctl(int handle, int func, void far *argdx, int argcx);
•
handle is an integer returned by an earlier successful call to open(), specifying the
LONWORKS network driver LONn to be opened.
•
func is the value 2, meaning that the application is reading information from the driver. For
LONWORKS standard DOS network drivers, the information returned is the network interface
direct call structure.
SLTA-10 Adapter User’s Guide
73
•
argdx is a pointer to a caller-declared structure that will contain the direct entry points into
the driver. See the structure direct_calls in the file NI_MSG.C in the supplied example
host application for usage.
•
argcx is the size of the structure.
Function code 2 is supported by network drivers for DOS to return three direct entry points into
the driver code. The network driver for the SLTA-10 Adapter supports an additional option to
function code 2, as well as function code 3, which is used to manage the modem control state of the
driver. These options are not used when the SLTA-10 Adapter is connected directly to a host.
They are provided primarily for use while establishing communications with a remote host. For
example, the host connect utility (HCU) described in Chapter 11 of this manual uses these
functions. Host applications that only communicate to the SLTA-10 Adapter via an alreadyestablished telephone connection do not need to concern themselves with these functions. If you
wish to establish or take down telephone connections during the execution of your host
application, use the source code of HCU as a guide.
When function code 2 is used, argdx points to the direct_calls structure defined for all
LONWORKS standard network drivers for DOS. If argcx is 13, the size of the standard direct
calls structure, then three direct entry point addresses are returned as usual. If argcx is 4 (the
size of the structure ioctl_get_dcd_s), then the state of the modem's DCD line is returned as a
TRUE or FALSE value. Note that the status field is 16 bits in this structure, but 8 bits in the direct
calls structure.
struct ioctl_get_dcd_s {
unsigned ioctl_stat;
unsigned dcd_state;
}
// 16 bit status
// Data Carrier Detect (TRUE or FALSE)
Function code 3 is used when the application wishes to write information to the driver. For the
SLTA-10 Adapter driver, argdx points to the following structure, and argcx is its size:
struct ioctl_o_info_s {
unsigned ioctl_stat;
unsigned sub_command;
unsigned mode;
unsigned mode_aux;
}
enum sub_command {
SUBC_set_opt
= 1,
SUBC_set_DTR
= 2,
SUBC_set_baud
= 3,
};
// 16 bit status
// use enum sub_command
// set driver options
// set DTR line
// set serial bit rate
There are three sub-commands, used to set the various modes of the driver, the state of the DTR
(Data Terminal Ready) line to the modem, and serial bit rate of the serial interface.
When sub-command 1 is used, the mode field in the structure is a bit mask defining which of the
driver modes is to be changed, and the mode_aux field specifies bits defining the new states of
those modes. It is possible to set more than one of the modes by OR'ing the following bit-masks
together:
0x0001
Enables modem support.
0x0002
Allows modem responses to host - same as the /Q option.
SLTA-10 Adapter User’s Guide
74
0x0004
Forces direct modem mode. In this mode, the network driver is
communicating directly with the modem.
0x0010
Enables the buffered link protocol and disables the ALERT/ACK
link protocol - same as the /N option.
0x0020
Enables the reliable transport protocol.
The /M option corresponds to 0x0021.
Sub-command 2 is used to set the state of the DTR line. In this case, the DTR signal is enabled
(on) if the mode field is true.
Sub-command 3 is used to set the serial bit rate of the serial interface. The mode field determines
the new bit rate as follows: 0:14,400; 1:1,200; 2:2,400; 3:9,600; 4:19,200; 5:38,400; 6:57,600;
7:115,200.
Using the SLTA-10 MIP Mode under Microsoft Windows 3.1x
In order to use the SLTA-10 MIP mode network driver for DOS under Microsoft Windows 3.1x, an
interface based on the DOS Protected Mode Interface (DPMI) must be provided. This type of
interface, in the form of Windows DLL software, is supplied with the Connectivity Starter Kit, as
well as with the LonManager API for Windows and LonManager DDE Server. The interface
software is called WLDV.DLL. See Appendix A for information on using the Windows 3.1x DLL
directly.
SLTA-10 Adapter User’s Guide
75
SLTA-10 Adapter User’s Guide
76
Chapter 9
Creating an SLTA-10 MIP Mode Driver
This chapter describes the process of building a network driver for a
host that is to be connected to an SLTA-10 Adapter in MIP mode. This
chapter also includes a description of the network interface protocol for
the SLTA-10 MIP mode. The network interface protocol defines the
format of the data passed across the EIA-232 interface, and varies
depending on the configuration of the SLTA-10 Adapter and the
network driver. If a LONWORKS standard network driver is used, the
format of the data passed between the driver and the application is
defined by the network driver protocol and is independent of the
network interface protocol; the driver is responsible for providing the
necessary translations. This chapter will therefore be of interest only to
those needing to develop a network driver for a host other than DOS,
Windows, or UNIX.
Skip this Chapter if you are using the SLTA-10 NSI mode.
SLTA-10 Adapter User’s Guide
77
Purpose of the Network Driver
The network driver provides a hardware-independent interface between the host application and
the network interface. By using network drivers with consistent calling conventions, host
applications can be transparently moved between different network interfaces. For example, the
standard SLTA-10 MIP mode DOS network driver, together with the Windows 3.1x DLL software,
allows DOS and Windows 3.1x applications, such as those based on the LonManager API, to be
debugged using the network driver for the LonBuilder Development Station. These applications
can later be used with the network driver for the SLTA-10 Adapter, without modifying the host
application.
A LONWORKS standard network driver must supply the functions defined under Network Driver
Services in Chapter 4 of the LONWORKS Host Application Programmer's Guide. The Windows
3.1x DLL software is described in Appendix A.
Example Network Drivers
The Connectivity Starter Kit includes source code for an example DOS network driver; the
Echelon web site contains source code for an example UNIX network driver. The DOS driver is
used for both DOS and Windows 3.1x applications. See the comments in the source code of the
network drivers for an explanation of how the network drivers work. These drivers can be used as
templates for a LONWORKS standard network driver. The DOS network driver is compatible with
the LonManager APIs for DOS and Windows, the LonManager LonMaker installation tool, and the
LonManager DDE Server. A sample host application for DOS is also supplied. The functions
ldv_open(), ldv_read(), ldv_write(), and ldv_close() form a suitable operating-system
independent definition for the network driver. These functions support multiple network
interfaces, and hide the DOS-specific aspects of the DOS network driver.
The UNIX network driver is a source library that uses the UNIX serial device driver. It also
supports the ldv_open(), ldv_read(), ldv_write(), and ldv_close() functions.
Implementing an SLTA-10 MIP Mode Network Driver
The network driver manages the physical interface with the SLTA-10 Adapter, implements the
network interface protocol, performs flow control, manages input and output buffers, and provides
a read/write interface to the host application.
Figure 31 illustrates how the network driver fits into the host application architecture.
SLTA-10 Adapter User’s Guide
78
Host Application
Host Application
LonManager API
Application Layer Interface
Driver services:
open/close/ioctl/read/write
Host
Output Buffers
Input Buffers
Downlink Flow Control
Buffer Request Protocol
Uplink Flow Control
XON/XOFF Protocol
Network Driver
Interface Transport Protocol
(Reliable or None)
Interface Link Protocol
(ALERT/ACK or Buffered)
Physical Layer Interface (EIA-232)
SLTA-10
Network Interface
LONWORKS
Network
Figure 30 Host Application Architecture
To implement an SLTA-10 MIP mode network driver for a host other than DOS, Windows, or
UNIX, follow these steps:
1 Implement and test low-level serial I/O. Serial I/O may be performed directly to the host’s
UART as is done in the DOS network driver, or may be performed by a serial I/O driver on the
host as is done by the UNIX network driver. Serial I/O should be interrupt driven for better
performance.
The UNIX network driver uses the UNIX serial port driver for all low-level serial I/O and
interrupt support. This simplifies the driver and also simplifies porting between different
versions of UNIX. The serial device is opened by the ldv_open() function and closed by the
ldv_close() function. Data are read from and written to the serial device using the UNIX
read() and write() system calls.
SLTA-10 Adapter User’s Guide
79
The UNIX network driver includes a ldv_post_events() function that should be called
periodically from the client application in order to assure that the SLTA-10 Adapter traffic is
being processed.
The DOS network driver serial I/O functions are implemented by MSD_SIO.C, MSD_UART.H,
and MSD_IRQC.ASM. These files may all be replaced as long as the required serial I/O
functions in MSD_SIO.C are provided. The definitions of the UART registers are in
MSD_UART.H. The DOS serial I/O interrupt service routines are in MSD_IRQC.ASM.
The DOS network driver uses the DOS system timer tick interrupt (vector 0x1C) and the serial
I/O device interrupt for the relevant COM port to perform background processing of the serial
network interface. The driver hooks into these interrupt vectors and executes driver code
whenever the LON(n) device is opened. Flags internal to the driver prevent the interrupt code
thread from interfering with the normal application foreground execution of functions within
the driver.
The smip_int_main() function in the DOS network driver services the serial port connected
to the network interface. The function tick_int_main() services the timer tick interrupt
every 55 msec.
Both network drivers are fully buffered for both outgoing and incoming messaging. Read and
write functions work with circular buffers within the driver. The host interrupt service
routine handles the other ends of these buffer queues.
Both network drivers only support a single set of output buffers. An elaboration on this design
could implement a set of priority output buffers. The write function could determine into
which of the two buffer sets to place messages, and the driver service function could service
the priority buffers first.
2 Implement and test timer support functions. Timer support may be provided by a hardware
timer as is done in the DOS network driver, by a system service as is done in the UNIX
network driver, or by implementing a background software task. The UNIX network driver
uses a once per second signal that is handled by the second_service() function. The DOS
timer functions are implemented by MDV_TIME.C and MDV_TIME.H.
3 Implement and test the host side of the network interface protocol. The network interface
protocol is implemented by the rx_process() and tx_process() functions in the UNIX
driver, and by the functions in MSD_TXRX.C for the DOS network driver.
4 Implement and test raw modem I/O if you need to support a modem interface. Raw I/O
manages the serial interface to the modem when the modem is not connected to a host and is
used for modem initialization and control. The raw I/O interface is implemented in
MSD_RAW.C for the DOS network driver, and is not implemented in the UNIX network driver.
5 Implement and test the buffer request states, buffer management, and read/write interfaces.
These functions are implemented by MSD_EXEC.C for the DOS network driver. The read/write
interface is implemented in the ldv_read() and ldv_write() functions for the UNIX
network driver
The following files are unique to a DOS driver and would probably not be used in a port to another
host: MSD_DRVR.H, MSD_DIFC.C, MSD_FRST.C, MSD_LAST.C, MSD_SEGD.ASM.
SLTA-10 Adapter User’s Guide
80
Network Interface Protocol
The network driver implements the host side of the network interface protocol, providing an easyto-use and interface-independent read/write interface to the host application. The network
interface protocol is a layered protocol that includes the following layers:
•
Presentation Layer. Defines packet formats for network variables and explicit messages. This
is the only layer visible to the host application. The remaining layers are managed by the
network driver.
•
Session Layer. Manages flow control, buffer requests, and grants.
•
Transport Layer. Ensures end-to-end reliability between the host and the SLTA-10 Adapter.
•
Link Layer. Controls access to the serial link.
•
Physical Layer. EIA-232 interface.
The physical layer is defined by the EIA RS-232 standard. The link, transport, session, and
presentation layers are described in the following sections.
Link Layer Protocol
The default interface link layer protocol is the ALERT/ACK protocol. This protocol may be used
when the host is a microcontroller or microprocessor such as a PC running DOS or Windows. The
alternative interface link protocol is the buffered protocol. This protocol is used with computer
hosts that can asynchronously buffer an entire packet. All data are transmitted using 1 start bit, 8
data bits, no parity bits, and 1 stop bit.
ALERT/ACK Link Protocol
The DOS network driver uses the ALERT/ACK link protocol by default (i.e., the /N option is not
specified). See Chapter 8 for a description of the network driver options. The UNIX network
driver uses the ALERT/ACK link protocol if the alert_ack_prtcl variable is set to TRUE in the
source code (this is not the default). The Switch1/CFG3 input of the SLTA-10 Adapter, as
described in Chapter 4, must be in the ALERT/ACK state (DOWN position).
When using this protocol, all transfers between the SLTA-10 Adapter and the host consist of serial
data streams that start off with the link-layer header sequence described in figure 31. Whenever
one device, either the SLTA-10 Adapter or the host, needs to send a command or message, the
sender starts the sequence by transmitting the ALERT byte (value 01 hex). When this byte is
received by the receiver, that device responds by transmitting the ALERT ACK byte (value FE
hex). This low level handshaking process prevents the sender from transmitting the rest of the
sequence before the receiving device is ready. Once the ALERT ACK byte is received by the
sender it sends the rest of the message without any other interactions.
SLTA-10 Adapter User’s Guide
81
Sender
Receiver
ALERT (01)
ALERT ACK (FE)
Link-Layer
Header
length
not_length
network interface
command
[ data ]
checksum
Figure 31 SLTA-10 Adapter ALERT/ACK Link Protocol
The link-layer header contains a length byte followed by a one’s complement of the length byte.
These values are always validated by the receiver before accepting the rest of the message.
Following the length bytes is the network interface command. See Appendix D of the Host
Application Programmer’s Guide for a description of the command byte structure. If the message
contains a data field it follows the command byte. Finally, a checksum terminates the sequence.
The length byte value describes the length of the network interface command byte plus the length
of the data field. This value will always be at least 1. The checksum is a two’s complement of the
sum of the command byte and all of the bytes in the data field, if it exists. Checksum errors
detected by the host will cause an error to be reported to the application, and checksum errors
detected by the SLTA-10 Adapter will cause the message to be ignored.
The SLTA-10 Adapter places the following requirements on the rate of the received serial data
stream. When receiving, the maximum wait period for the length byte following the transmission
of the ALERT ACK byte is 100ms (or 1 second when attached to a modem). All subsequent bytes
received must occur within 100ms after the previous byte, otherwise the SLTA-10 Adapter receive
process will abort. Likewise, the SLTA-10 Adapter uses a wait period of 100ms (or 1 second when
attached to a modem) before aborting for the reception of the ALERT ACK when transmitting a
message. If the ALERT ACK is not received in time, the SLTA-10 Adapter repeats the process by
transmitting another ALERT byte.
The SLTA-10 Adapter cannot support a full duplex communications process between it and the
host. The network driver included with the SLTA-10 Adapter takes this into account. Data
frames transmitted to the SLTA-10 Adapter while it is in the process of sending uplink messages
will be lost if more than 16 bytes are sent to the SLTA-10 Adapter.
SLTA-10 Adapter User’s Guide
82
Buffered Link Protocol
The DOS network driver uses the buffered link protocol when the /N option is specified. See
Chapter 8 for a description of this option. The UNIX network driver uses the buffered link
protocol if the alert_ack_prtcl variable is set to FALSE in the source code (this is the default).
The Switch1/CFG3 input of the SLTA-10 Adapter, as described in Chapter 4, must be in the
buffered protocol state (UP position).
When using this protocol, the link-layer header contains a length byte followed by a one’s
complement of the length byte. These values are always validated by the receiver before accepting
the rest of the message. Following the length bytes is the network interface command. See
Appendix D of the Host Application Programmer's Guide for a description of the command byte
structure. If the message contains a data field it follows the command byte. Finally, a checksum
terminates the sequence.
Sender
Receiver
ALERT (01)
length
Link-Layer
Header
not_length
network interface
command
[data]
checksum
Figure 32 SLTA-10 Adapter Buffered Link Protocol
The length byte value describes the length of the network interface command byte plus the length
of the data field. This value will always be at least 1. The checksum is a two’s complement of the
sum of the command byte and all of the bytes in the data field, if it exists. Checksum errors
detected by the host will cause an error to be reported to the application, and checksum errors
detected by the SLTA-10 Adapter will cause the message to be ignored.
This protocol is used when the host is capable of accepting asynchronously occurring input data
without losing characters. The host is also relieved of the obligation of responding to an ALERT
character within 50 ms. This protocol may therefore be used by an application-level handler
calling an interrupt-driven buffered serial device driver. Drivers with these characteristics are
typically provided with real time operating systems such as VRTX or time-sharing operating
systems such as UNIX or VMS. In this case, these drivers should be set up for binary data
communications without software flow control.
SLTA-10 Adapter User’s Guide
83
The buffered link protocol should not be used when the SLTA-10 Adapter is attached to a modem.
The buffered link protocol can only be used on multitasking operating systems such as UNIX if the
host application executes often enough to empty any incoming buffers. For example, if the
SLTA-10 Adapter is receiving 70 packets per second, and each packet is 25 bytes, the host will
receive 1750 bytes per second. If the host has a serial input buffer of 256 bytes, the buffer will fill
within 150 milliseconds if the host application is preempted. If the host application is preempted
for longer than 150 milliseconds, incoming data will be lost due to lack of serial buffer space. In
this case, the ALERT/ACK protocol should be used, or the buffer space increased to handle the
worst case traffic during the maximum preemption period.
Transport Layer Protocol
When used with a local host, the SLTA-10 Adapter assumes a reliable connection and does not use
a transport layer protocol. When used with a remote host, the SLTA-10 Adapter assumes that the
link may not be reliable and enables the reliable transport protocol. The reliable transport
protocol adds an ACK/NACK transport protocol to the network interface protocol. A sequence
number is also added to the link-layer header. This protocol can therefore recover from checksum
errors on the host to SLTA-10 Adapter link.
The reliable transport protocol is enabled on the SLTA-10 Adapter with the Remote Host option
selected by the Switch2/CFG2 input as described in Chapter 4. The reliable transport protocol is
enabled on the DOS network driver with the /M option as described in Chapter 8. The reliable
transport protocol is not supported by the UNIX network driver.
The link-layer header contains an ALERT (0x01) byte, a sequence number, and a length byte
followed by a one’s complement of the length byte. These values are always validated by the
receiver before accepting the rest of the message. Following the length bytes is the network
interface command. See Appendix D of the Host Application Programmer's Guide for a description
of the command byte structure. If the message contains a data field it follows the command byte.
Finally, a checksum terminates the sequence.
The ALERT/ACK link protocol should be used with remote hosts. With this protocol, the sender
will start the sequence by transmitting the ALERT byte. When this byte is received by the
receiver, that device responds by transmitting the ALERT ACK byte (value FE hex). This low
level handshaking process prevents the sender from transmitting the rest of the sequence before
the receiving device is ready. Once the ALERT ACK byte is received by the sender it sends the
rest of the message without any other interactions.
The length byte value describes the length of the network interface command byte plus the length
of the data field. This value will always be at least 1. The checksum is a two’s complement of the
sum of the command byte and all of the bytes in the data field, if it exists. If the receiver receives
a message in sequence, with a valid checksum, it responds with an ACK (0x06). Otherwise it
responds with a NACK (0x15), requesting a re-transmission.
SLTA-10 Adapter User’s Guide
84
Sender
Receiver
ALERT (01)
ALERT ACK (FE)*
sequence number
Link-Layer
Header
*Only transmitted with
ALERT/ACK link
protocol
length
not_length
network interface
command
[data]
checksum
ACK (or NACK)
ACK: 0x06, NACK: 0x15
Figure 33 SLTA-10 Adapter Reliable Transport Protocol
SLTA-10 Adapter Timing Data
Certain aspects of the SLTA-10 Adapter link and transport layer protocols implement fail-safe
timeouts in order to control the time spent waiting for protocol states to change when errors occur.
Downlink Byte-to-Byte Receive Timeout
The downlink byte-to-byte receive timeout is the maximum allowable period between the end of a
single byte data frame sent downlink to the SLTA-10 Adapter, to the end of the next single byte
data frame sent downlink to the SLTA-10 Adapter. This period is 100ms in local host mode and 1
second in remote host mode. When this timeout occurs, the SLTA-10 Adapter discards the
downlink buffer and returns to the NORMAL state. If the reliable transport protocol is enabled, the
SLTA-10 Adapter also sends a NACK byte after this timeout.
SLTA-10 Adapter User’s Guide
85
Uplink Message Life
The uplink message life is the maximum allowable period between the SLTA-10 Adapter sending
an ALERT byte to the host and the host responding with an ALERT ACK byte. This period is
100ms in local host mode and 1 second in remote host mode. When this timeout occurs, the
SLTA-10 Adapter will resend the ALERT byte. This process is repeated until 3 seconds have
elapsed, after which the uplink message is discarded. This timeout only applies to the
ALERT/ACK link protocol and is not used for the buffered link protocol.
ACK/NACK Receive Timeout
When using the reliable transport protocol, the SLTA-10 Adapter will wait for the ACK or NACK
byte to be sent downlink following the end of the uplink transmission of a message. This period is
1 second, after which the SLTA-10 Adapter will re-send the uplink message.
Uplink Timeout Message Retry Count
When using the reliable transport protocol the SLTA-10 Adapter will re-send uplink messages
whenever the ACK/NACK timeout period has elapsed. This retry process is limited to 5 retries,
after which the uplink message is discarded. There is no retry limit applied to re-sends due to the
reception of the NACK byte.
Session Layer Protocol
The network interface link and transport protocols described above are used for all host-to-SLTA
communications. Layered on top of these protocols is a downlink buffer request protocol and an
uplink flow control protocol.
Downlink Buffer Request Protocol
The network driver receives application buffers from the host application, translates them to
interface buffers, and passes the interface buffers to the SLTA-10 Adapter. There are two types of
downlink commands from the host to the SLTA-10 Adapter— commands that can be executed
directly by the SLTA-10 Adapter, and commands that need to be buffered in the SLTA-10 Adapter.
Downlink commands that are executed directly by the SLTA-10 Adapter are:
niRESET, niFLUSH_CANCEL, niONLINE, niOFFLINE, niFLUSH, niFLUSH_IGN, niPUPXOFF,
niPUPXON, niSLEEP, and niSSTATUS.
See the Host Application Programmer's Guide, Appendix D, for a description of these commands.
The niSStatus command, when sent downlink, will cause the SLTA-10 Adapter to respond with a
niSStatus command plus one byte of data. In MIP mode, this byte of data contains the settings
of configuration switches, with BAUD0 being the least significant bit. In NSI mode, this byte of
data contains 011 in the least significant bits followed by the XID information, making the SLTA10 Adapter NSI mode consistent with the PCNSI Adapter.
Downlink commands that are buffered in the SLTA-10 Adapter are niNETMGMT (for network
management commands to be executed by the SLTA-10 Adapter itself) and niCOMM (for messages
to be sent out on the network, including network variables, explicit messages, and network
SLTA-10 Adapter User’s Guide
86
management messages addressed to other nodes). For these two commands, a buffer request
protocol is used to ensure that the SLTA-10 Adapter has a free application buffer for the data. The
network driver must first request an output buffer before sending the interface buffer. The
network driver must hold the buffers in an output queue until the SLTA-10 Adapter is ready to
receive them. The network driver takes the SLTA-10 Adapter through 3 states to request a buffer
and send the interface buffer. Figure 34 summarizes the downlink state transitions.
Receive niCOMM
or niNETMGMT?
Node
Reset
Flush
Receive
niFLUSH_CANCEL
Normal
Out Queue
Requested
send niNACK
Receive niCOMM
or niNETMGMT
message?
Output
Buffer not
Available?
Output
Buffer
Available?
send niACK
Out Queue
Ack'd
Note: niNETMGMT commands are allowed in the Flush state.
Figure 34 SLTA-10 Adapter Downlink Flow Control States
Following is the sequence of events for transferring an niCOMM or niNETMGMT command downlink
to the SLTA-10 Adapter:
1 The SLTA-10 Adapter is initially in the NORMAL state.
2 The network driver requests an output buffer by sending a link-layer header (see figures 31
and 32) with a niCOMM or niNETMGMT command and the appropriate queue value (niTQ,
niTQ_P, niNTQ, niNTQ_P). The data portion of the interface buffer is not sent with the buffer
request. This puts the SLTA-10 Adapter in the OUTPUT QUEUE REQUESTED state.
3 If an output buffer is not available, the SLTA-10 Adapter responds with a niNACK (0xC1)
command. The SLTA-10 Adapter returns to the NORMAL state, and the driver starts again at
step 2.
4 When an output buffer is available, the SLTA-10 Adapter responds with a niACK (0xC0)
command. The SLTA-10 Adapter is now in the OUTPUT QUEUE ACKNOWLEDGED state. While
in this state, the network driver can only transfer downlink LonTalk messages, uplink source
quench commands (niPUPXOFF), uplink source resume commands (niPUPXON), or reset
commands (niRESET) since the SLTA-10 Adapter is waiting for a message in this state. All
SLTA-10 Adapter User’s Guide
87
other network interface commands sent downlink will be ignored, and will return the SLTA-10
Adapter to the NORMAL state.
5 Upon receiving the niACK acknowledgment, the network driver transfers the entire interface
buffer to the SLTA-10 Adapter. This buffer has the same command and queue value sent in
step 2, and also contains the data and checksum. Upon completion of this transfer, the
SLTA-10 Adapter returns to the NORMAL state.
The network driver must preserve the continuity of the type of buffer request and the type of
message sent downlink. For example, if the network driver sends the niCOMM+niTQ_P command
requesting a priority output buffer, and follows this with a message transfer with the non-priority
niCOMM+niTQ command, the SLTA-10 Adapter will incorrectly store the message in a priority
output buffer, the type originally requested.
Uplink Flow Control Protocol
Uplink traffic may be incoming LonTalk messages, output buffer request acknowledgments,
completion events, or local commands. The network driver translates the interface buffers to
application buffer format and stores the buffers in a queue until the host application is ready to
read them.
There is no buffer request protocol for uplink traffic. The network driver is normally assumed to
have sufficient buffers. The network driver can suspend or resume uplink traffic when no network
driver input buffers are available by sending the Uplink Source Quench (niPUPXOFF) command to
the SLTA-10 Adapter. This prevents the STLA from sending any LonTalk messages uplink.
When the network driver senses that network driver input buffers are available, it sends the
Uplink Source Resume (niPUPXON) command to resume uplink transfers. Figure 35 summarizes
the uplink state transitions.
Node
Reset
Flush
▼
Receive
niFLUSH_CANCEL
▼
▼
Receive
niPUPXOFF?
Normal
XOFF
▼
Receive
niPUPXON?
Note:
Responses to niNETMGMT and niSSTATUS commands are allowed in the Flush state.
Figure 35 SLTA-10 Adapter Uplink Flow Control States
The host may chose to sidestep the downlink buffer request protocol. In this case, the complete
message is sent downlink without any buffer request step. If the SLTA-10 Adapter has a free
output buffer, then the message will be transferred into the SLTA-10 Adapter successfully. If not,
there will be no indication and the message will be lost. The exception to this case is when using
the transport layer protocol, in which case the SLTA-10 Adapter will send the NACK to the host,
which should force the host to re-send the message. Otherwise, in order to use this feature
successfully, the host driver must manage the number of available output buffers within the
SLTA-10 Adapter. This feature has been added to the DOS driver for the SLTA-10 Adapter.
SLTA-10 Adapter User’s Guide
88
Presentation Layer Protocol
The network driver exchanges LonTalk packets with the host application at the presentation
layer. The LonTalk packet enclosed in a command of type niCOMM or niNETMGMT is described in
detail in the Host Application Programmer's Guide. It is summarized here for convenience.
ExpMsgHdr
or
NetVarHdr
Message
Header
size = 3
SendAddrDtl
or
RcvAddrDtl
or
RespAddrDtl
Network
Address
size = 11
UnprocessedNV
or
ExplicitMsg
Data
size
varies
Figure 36 Application Buffer Format
The SLTA-10 firmware is configured with explicit addressing enabled, and therefore the 11-byte
network address field is always present in an uplink or downlink buffer. The firmware is also
configured with host selection enabled, so the data field of the buffer is either an unprocessed
network variable or an explicit message.
SLTA-10 Adapter User’s Guide
89
SLTA-10 Adapter User’s Guide
90
Chapter 10
Initialization and Installation
This chapter describes initializing, communicating with, and installing the
SLTA-10 Adapter as a network node.
SLTA-10 Adapter User’s Guide
91
Initializing an SLTA-10 Adapter
After an SLTA-10 Adapter and its host processor are powered, the host application must initialize
the SLTA-10 Adapter. When an SLTA-10 Adapter is initially powered-up or reset, it disables
network communications by entering the FLUSH, unconfigured state, unless the Switch3/CFG1
input is set to Network Enable. The FLUSH state prevents the SLTA-10 Adapter from responding
to network management messages before the host application has initialized the SLTA-10
Adapter. The unconfigured state prevents the SLTA-10 Adapter from responding to application
messages before the node has been installed in a network. The host application will not be able to
send or receive application messages until after it cancels the FLUSH state and the SLTA-10
Adapter leaves the unconfigured state.
An SLTA-10 Adapter leaves the unconfigured state when it is installed in a network and assigned
an address in one or two domains on that network. There are two ways this can happen. If the
SLTA-10 Adapter is used as a network interface for a network management tool, then the network
management application itself normally configures the network interface. For example, a network
management application based on LNS will configure the network interface (in this case a SLTA10 Adapter in NSI mode) when the network interface device is opened. Also, a network
management application based on the LonManager API or the LonMaker installation tool will
configure the network interface when the network interface device is opened. In this case the PC
running the network management application sends a local message to the SLTA-10 Adapter to
change its state to configured.
Alternatively, the SLTA-10 Adapter may be installed in a network by some other network
management tool. In this case, the network management tool sends a message to the SLTA-10
Adapter across the network to change its state and to assign it an address.
Once the SLTA-10 Adapter is in the configured state, it will retain that state and its address
assignment across power-cycles, because that information is stored in the internal EEPROM.
However, if Switch3/CFG1 is set to Network Disable, the FLUSH state must be canceled each time
the SLTA-10 Adapter is reset.
If the host application attempts to send a message while the SLTA-10 Adapter is in the FLUSH
state, the SLTA-10 Adapter will return a failed response for acknowledged messages and a success
response for unacknowledged messages. The message will not be sent in either case.
If the host application attempts to send a message while the SLTA-10 Adapter is in the NORMAL,
unconfigured state, the SLTA-10 Adapter will always return a success response even though the
message will not be sent.
To initialize an SLTA-10 Adapter, follow these steps (for more detail, see the LONWORKS Host
Application Programmer's Guide):
1 Reset the SLTA-10 Adapter from the host application by sending the niRESET command. If
installed correctly, the SLTA-10 Adapter will respond with an uplink niRESET message upon
completion of the reset. The first message from an SLTA-10 Adapter after power-up will also
be an uplink niRESET message informing the host that the SLTA-10 Adapter has reset.
2 Cancel the FLUSH state in the SLTA-10 Adapter. LNS applications automatically handle this,
and it is done automatically by the SLTA-10 MIP mode DOS network driver after an open
command or uplink niRESET if the /Z flag is not specified. The FLUSH state can be manually
SLTA-10 Adapter User’s Guide
92
canceled by sending the niFLUSH_CANCEL message. The FLUSH state can also be disabled by
a configuration switch on the SLTA-10 Adapter as described earlier in this chapter.
3 Install the network interface in one or two domains using the Update Domain network
management message. This may be done by a network management tool across the network,
or may be done directly by the host application by sending the Update Domain message as a
local network management command. The Attach command performs this function for an
SLTA-10 Adapter attached to the PC with DOS-based LonManager LonMaker installation
tool; the Install command performs this function for SLTA-10 Adapters in application nodes.
Calling the lxt_install_node() function in the LonManager API performs this function for
nodes across the network; the LonManager API lxt_open() function installs the network
interface itself. See below for details with the LCA Object Server of LNS.
4 Change the state of the network interface to configured. This may be done by a network
management tool across the network, or may be done directly by the host application by
sending the Set Node Mode network management message. The LonMaker Attach command
performs this function for an SLTA-10 Adapter attached to the PC with LonMaker; the
LonMaker Install command performs this function for SLTA-10 Adapters in application
nodes. Calling the lxt_install_node() function in the LonManager API changes the mode
of other nodes across the network; the LonManager API lxt_open() function changes the
mode of the network interface itself. See below for details with the LCA Object Server of LNS.
Installing an SLTA-10 Adapter on a Network
An SLTA-10 Adapter attached to a network appears as a standard LONWORKS node to other
nodes on the network. The SLTA-10 Adapter node is logically installed on a network with a
network management tool. Installation scenarios are described in the LONWORKS Installation
Overview engineering bulletin (number 005-0006-01). Unique installation requirements of host
applications are described in Chapter 3 of the LONWORKS Host Application Programmer’s Guide.
Installing with LNS
With LNS, the SLTA-10 Adapter is initialized automatically as part of the system open. Prior to
the system open, the application selects the desired network interface. See the Chapter 3
Initializing and Terminating LCA Applications in the LCA Object and Data Server Programmer’s
Guide for code fragments.
Installing with the LonBuilder or NodeBuilder Tools
An SLTA-10 Adapter node can be installed on a development network using the LonBuilder
Network Manager. Chapter 6 of the LonBuilder User’s Guide describes how to define and install
nodes in a development network using the LonBuilder Network Manager. A prerequisite to
creating application node target hardware and node specifications is to define the channels that
will be included in the network as defined under Defining Channels in Chapter 10 of the
LonBuilder User’s Guide. Select the standard transceiver type compatible with the transceiver on
your SLTA-10 Adapter node.
SLTA-10 Adapter User’s Guide
93
When creating a hardware properties definition for a custom node to represent the SLTA-10
Adapter node, set the input clock rate to 10MHz. Then create a hardware definition for the
custom node specifying these hardware properties. The SLTA-10 Adapter will not accept an
incorrect clock rate or hardware properties. This may occur, for example, if you specify
default_hw_props instead of the correct one. To install the SLTA-10 Adapter in a LonBuilder
network using the service pin, you must either connect the SLTA-10 Adapter to a host, and open
the network driver (for example, by running HA), or else set Switch3/CFG1 to the Network Enable
state.
When installing the SLTA-10 Adapter node, the channel definition must match the transceiver on
the SLTA-10 Adapter. If it does not, the SLTA-10 Adapter will not accept the new values. A ‘No’
response is required to the prompt, Do you want to install communications
parameters? DO NOT use the Yes response to the prompt: Do you want to install
communications parameters? unless the channel and hardware definitions are compatible
with the transceiver and input clock on the SLTA-10 Adapter.
When defining the application image, the App Image Origin field should be set to Interface
File, and the App Image Name should be set to the name of an external interface file
(XIF)created as described under Binding to a Host Node in Chapter 3 of the LONWORKS Host
Application Programmer’s Guide.
WARNING: This is NOT the default setting for the App Image Origin. If you specify a Neuron C
source file as the App Image Origin, the SLTA-10 Adapter may be rendered unusable.
If the SLTA-10 Adapter is accidentally configured with the wrong communication parameters, it
may be rebooted with the NODEUTIL application available on Echelon’s web site. See the
README.TXT file included with NODEUTIL for a description.
See the NodeBuilder User's Guide for information on creating an SLTA-10 Adapter node using the
NodeBuilder tools. The Application Image Type for an SLTA-10 Adapter must be set to External.
The Application Image file name should be set to the name of an external interface (XIF) file.
Installing an SLTA-10 Adapter with LonManager API, the DOS-based
LonManager LonMaker Installation Tool, or DDE Server
When an SLTA-10 Adapter is used as a network interface for a host application based on the
LonManager API, these installation steps are automatically handled by the LonManager API
lxt_open() function call.
When an SLTA-10 Adapter is used as a network interface for a network management PC running
LonMaker or a LonManager API-based application, these installation steps are automatically
handled by the LonMaker Attach command or the LonManager API lxt_open() function call.
When an SLTA-10 Adapter is used as a network interface for a control and monitoring PC running
the LonManager DDE Server, these installation steps are automatically handled by the DDE
Server.
SLTA-10 Adapter User’s Guide
94
Chapter 11
Using the SLTA-10 Adapter with a Modem
This chapter describes the operation of the SLTA-10 Adapter when a
remote host computer is connected via a pair of modems to the SLTA-10
Adapter. In this set-up, any node on the network may request the
SLTA-10 Adapter to initiate a dial-out operation to connect to the host.
In addition, if the SLTA-10 Adapter is functioning in NSI mode, the
SLTA-10 Adapter itself may be configured to initiate a dial-out
operation to connect to the host. The SLTA-10 Adapter can store a
telephone directory of commonly called numbers, as well as accept
commands to dial any other number.
The SLTA-10 Adapter may also be configured to accept incoming calls
and connect the network to the host. Incoming callers may optionally be
required to provide a password before the SLTA-10 Adapter will connect
them to the network.
SLTA-10 Adapter User’s Guide
95
Overview
The SLTA-10 Adapter network interface may be attached to the host processor using modems and
the switched telephone network. Figure 37 illustrates this option.
Host
Host Application
LNS Software
(optional)
Driver
Interface
Network Driver
EIA-232
Interface
Modem
Telephone
Network
Modem
via null
modem
Network
Interface
EIA-232
Interface
SLTA-10
Network Adapter
via built-in
transceiver
L ONWORKS
Network
Figure 37 Using the SLTA-10 Adapter with Modems
When the SLTA-10 Adapter is configured for modem support, it will respond to special network
management messages that cause it to communicate with the attached modem. The modem used
must support the Hayes standard AT command set allowing it to dial-out, auto-answer incoming
calls, and set various parameters.
Once a connection is established, the host computer communicates transparently with the network
as though the SLTA-10 Adapter were attached locally.
SLTA-10 Adapter User’s Guide
96
In NSI mode, the SLTA-10 Adapter can be configured to initiate the connection with the host PC
when LNS network management messages and/or network variable updates are addressed to the
SLTA-10 Adapter. Alternatively, another node on the local network can command the SLTA-10
Adapter to initiate the connection.
In MIP mode, the SLTA-10 Adapter cannot itself initiate any connection; it must be commanded to
do so by another node on the local network, or else by the modem's detection of an incoming call.
This means, for example, another node on the local network must initiate the dialing procedure
when an alarm is detected that needs to be reported to the host. Once a connection has been
established, however, any node on the local network can communicate with the host by addressing
messages to the SLTA-10 Adapter.
In order to support the modem functions, the SLTA-10 Adapter Switch2/CFG2 input must be set to
the Remote Host state (UP position). Switch1/CFG3 should be set to the default ALERT/ACK link
protocol (DOWN position). This automatically enables the reliable network interface transport
protocol. See Chapter 4 for details of the configuration inputs. See Chapter 7 for using the
SLTALink Manager with the SLTA-10 NSI mode or Chapter 8 for SLTA-10 MIP mode DOS
network driver options.
Note that the packet throughput of the SLTA-10 Adapter is substantially reduced when using a
modem because of the overhead associated with modem support.
SLTA-10 Adapter Connection States
When the SLTA-10 Adapter is operating in the remote host mode, several internal states (or
connection states) will control its behavior:
•
The IDLE state is entered after power-up reset. In this state any uplink bound messages are
ignored since the SLTA-10 Adapter is not connected to a host. The IDLE state is also entered
whenever the telephone connection is broken and the modem drops the DCD (Data Carrier
Detect) line.
•
The CALL_IN_PROCESS state is entered once a connection is initiated by a node on the
network connected to the SLTA-10 Adapter. In this state uplink traffic is still discarded while
the SLTA-10 Adapter monitors the modem for connection completion or connection failed
events to occur.
•
The CONNECTED state is entered once the connection is complete. The normal network
interface protocol resumes between the SLTA-10 Adapter and the remote host. This state may
be entered as a result of a node on the local network initiating a call, or as a result of a remote
host calling up this SLTA-10 Adapter.
•
The FAILED state is entered if the connection process failed. This state is operationally the
same as IDLE.
The connection state of the SLTA-10 Adapter is preserved across software resets, allowing normal
network management resets to occur without breaking the connection. The SLTA-10 Adapter will
not preserve the connection state after it has been through a power reset.
SLTA-10 Adapter User’s Guide
97
Command Set Assumptions
The SLTA-10 Adapter uses the following strings received from the modem to interpret the
connection state. These strings are consistent with all Hayes AT compatible modems operating in
the word response mode (alphabetic responses). [CR] is the hex 0D character.
CONNECT [any text] [CR]
BUSY [CR]
VOICE [CR]
NO [any text][CR]
ERROR [CR]
The "CONNECT" string may be, and typically is, followed by other informative text, such as
connection serial bit rate or error correction methods in use.
These other four states indicate a failure to make the connection.
Translated Characters
All strings that are sent specifically to the modem (as commands) by the SLTA-10 Adapter are
scanned for certain characters by the SLTA-10 firmware. These characters are then translated
into specific functions or characters unless they are preceded by a backslash (“\”). The characters
are:
~
The tilde will cause the SLTA-10 Adapter to pause 500ms before sending the next
character to the modem. The tilde itself is not sent.
!
The exclamation point will cause the SLTA-10 Adapter to send a carriage return (0x0H)
to the modem. The exclamation point itself is not sent.
The tilde is provided for users familiar with existing modem packages. It can be used, for
example, in the command string which causes the modem to hang-up. When dialing out, Hayes
AT-compatible modems use the comma character to insert delays between portions of a dial
command; the comma character should continue to be used for dialing out.
DTE Connections
In addition to the basic three wire connections— Transmit Data (TXD), Receive Data (RXD), and
Signal Ground— there are two additional signals that must be connected: Data Carrier Detect
(DCD) and Data Terminal Ready (DTR). The modem must also be configured to use these signals.
DCD is used by the SLTA-10 Adapter to determine that a connection has been made and DTR is
used to terminate a connection by hanging up. Note that many modems default to ignore these
two signals and must be configured to enable them. The following AT command enables these two
signals on many modems.
AT&C1&D2[CR]
SLTA-10 Adapter User’s Guide
98
Network Management Messages
Network management messages are used to configure the operation of the network, as opposed to
delivering application data during operation of the network. All LONWORKS nodes respond to the
standard network management messages as described in Appendix B of the Neuron Chip Data
Book. For nodes based on the SLTA-10 Adapter, additional network management messages are
defined to configure and control the SLTA-10 Adapter. The message codes for network
management messages are reserved, and therefore applications need not be concerned about
possible conflicts in the choice of message codes. The additional SLTA-10 Adapter network
management messages use the reserved message code 7D hex. The first data byte is used as a
sub-code, and is 01 hex to indicate an SLTA-10 Adapter function. The second data byte is a
specific application command code. Table 16 summarizes the network management messages
specific to the SLTA-10 Adapter.
Table 16 SLTA-10 Adapter Network Management Messages
Message Code Message Subcode
Application
Command
Function
0x7D
1
1
Product Query
0x7D
1
2
Send Modem String
0x7D
1
3
Modem Status Readback
0x7D
1
4
Modem Response Query
0x7D
1
5
Connection Status Query
0x7D
1
6
Install Directory Entry
0x7D
1
7
Dial From Directory
0x7D
1
8
Hang-up
0x7D
1
9
Install Password
0x7D
1
10
Install Modem Configuration String
0x7D
1
11
Install Hangup String
0x7D
1
12
Install Dial Prefix
0x7D
1
13
Install Hangup Timer
0x7D
1
14
Configure Modem
0x7D
1
15
Request/Release Modem
0x7D
1
16
Clear EEPROM Pool
0x7D
1
17
Install NV Connect
0x7D
1
18
Install NSI Connect
0x7D
1
19
Install Callback Enable
0x7D
1
20
Report SLTA EEPROM contents
These network management messages may be sent from any node on the network to the SLTA-10
Adapter. If an application node wishes to send modem-control network management messages to
the SLTA-10 Adapter, it does so using explicit messaging. See Chapter 4 of the Neuron C
Programmer’s Guide for details on explicit messaging. The message should be delivered using
SLTA-10 Adapter User’s Guide
99
request/response service, and the message code for modem control messages is always 7D hex.
The data portion of the message always begins with a sub-code value of 1, indicating that the
message is addressed to an SLTA-10 Adapter, followed by an application command byte
indicating which modem-control command this is. This is followed by parameters specific to the
application command. These messages may be sent by a Neuron C-based node, a node based on
the Microprocessor Interface Program (MIP), or a node based on another SLTA-10 Adapter.
See the supplied Neuron C program DIALOUT.NC for an example of an application that sends a
message to an SLTA-10 Adapter to cause it to dial-out using an attached modem. The example
GIZSETUP.NC sends messages to an SLTA-10 Adapter to configure its modem strings using a
Gizmo I/O module as the user interface. A node can send these messages using either implicit or
explicit addressing. When implicit addressing is used, a network management tool binds the
output message tag in the node wishing to send the message to the SLTA-10 Adapter as the
destination. When explicit addressing is used, the node wishing to send the message must
explicitly insert the destination address in the outgoing message.
Note that the SLTA-10 Adapter will be unable to receive any messages, including these network
management messages, if network communications is disabled, i.e., it is in the FLUSH state. This
will normally be the case if it is not connected to a host. Therefore, in order to be able to dial-out
and connect to a host, the SLTA-10 Adapter must be configured to initialize with network
communications enabled, i.e., the NORMAL state, with the CFG1 input. See Chapter 4 for more
details.
The messages should be sent with request/response service, and the response code should be
checked to see if the message was executed correctly - it will be 0x3D if there was no error, and
0x1D if there was. Possible failure conditions are noted under each message. Some of these
network management messages return data to the sender in the response structure as noted
below.
Note that some of these messages cause one or more bytes of EEPROM in the SLTA-10 Adapter to
be written. Each byte of EEPROM takes 20ms to write, and the response is not sent by the
SLTA-10 Adapter until after the command is executed. This time should be taken into account
when setting the transaction timer (tx_timer) in the message tag connection for implicit
addressing, or in the destination address for explicit addressing. If the LonBuilder or LonManager
API binder is used to create the connection, the transaction timer may be explicitly specified.
Example:
msg_tag SLTA_tag;
when ( ... ) {
msg_out.code = 0x7D;
// network mgmt msg code
msg_out.tag = SLTA_tag;
msg_out.service = REQUEST;
msg_out.data[0] = 1;
// sub-code for SLTA-10
msg_out.data[1] = app_command;
// specific command
msg_out.data[2] = .....
// additional parameters
msg_send();
}
SLTA-10 Adapter User’s Guide
100
when (msg_fails(SLTA_tag)) {
// SLTA-10 Adapter did not respond to the message
...
}
when (msg_succeeds) { ... }
when (resp_arrives(SLTA_tag) {
// SLTA-10 Adapter did respond to the message
if (resp_in.code == 0x3D)
// command executed successfully
...
Certain SLTA-10 Adapter network management messages which are designed to send a command
string directly to the modem will fail if the connection status is CONNECTED. This applies to the
following messages: Send Modem String, Dial From Directory, and Configure Modem. The
telephone connection must be broken and the SLTA-10 Adapter returned to the IDLE state for
these messages to be issued.
Many of these network management messages, for example the "Install..." messages, may be sent
to the SLTA-10 Adapter from the host computer via the telephone link if the SLTA-10 Adapter is
in the CONNECTED state. In this case, they should be sent using the niNETMGMT network interface
command so that they are addressed to the SLTA-10 Adapter itself.
Structures are defined in the file SLTA_ANM.H for each of the application commands, and include
the sub_code and app_command fields, as well as any additional parameters for the specific
application command. If the response contains data other than the response code, a structure for
the returned data is also defined.
EEPROM String Pool Management
The SLTA-10 Adapter’s EEPROM is used to store a number of varying-length configurable strings
which are used to control the modem. These strings can be set by sending network management
messages to the SLTA-10 Adapter, either from the modem side or the network side. Since the
strings are varying in length and the EEPROM space is limited, a pool management system is
used to optimize the usage of EEPROM. The SLTA-10 MIP mode EEPROM string pool and the
SLTA-10 NSI mode EEPROM pool are different! Changing the mode DIP switch and cycling
power will destroy the EEPROM pool.
For the SLTA-10 MIP mode, the EEPROM pool consists of the following strings:
Up to eight dial-out directory entries. These may be used by index to initiate a dial-out
connection, and may contain any combination of AT commands and numbers.
One modem initialization string. This string is used to initialize the modem as required.
One modem hang-up string. This string is used to hang-up the modem and break the
connection when DTR control does not function.
One dial-out prefix string. This string is sent as a prefix to any dial-out operation to specify
the modem dial command and to indicate whether tone or pulse dialing should be used.
SLTA-10 Adapter User’s Guide
101
An 8-byte dial-in password string.
EEPROM storage and allocation for these strings is managed by the MIP mode EEPROM pool.
This allows flexible utilization of the SLTA-10 Adapter’s MIP mode EEPROM space. The MIP
mode pool consists of 21 blocks, each with 9 bytes of data storage space. A string occupies one or
more blocks.
For the SLTA-10 NSI mode, the EEPROM pool consists of the following strings:
Up to five dial-out directory entries. These may be used by index to initiate a dial-out
connection, and may contain any combination of AT commands and numbers.
One modem initialization string. This string is used to initialize the modem as required.
One dial-out prefix string. This string is sent as a prefix to any dial-out operation to specify
the modem dial command and to indicate whether tone or pulse dialing should be used.
An 8-byte dial-in password string.
A 1-byte code that enables an auto dial-out on a network variable message.
A 1-byte code that enables an auto dial-out on a NSI message.
A 1-byte code that enables callback.
EEPROM storage and allocation for these strings is managed by the NSI mode EEPROM pool.
This allows flexible utilization of the SLTA-10 Adapter’s NSI mode EEPROM space. The NSI mode
pool consists of 8 blocks, each with 12 bytes of data storage space. A string occupies one or more
blocks.
The NSI mode EEPROM pool does not require the exclamation point (translated to a carriage
return) in the dial directories; whereas, it is required in the MIP mode EEPROM pool. In addition,
the NSI mode EEPROM pool does not require a null terminator on exact sector size strings. In the
MIP mode EEPROM pool, if a string winds up ending on the last byte of a sector, a subsequent
sector is required to hold the null terminator.
The network management functions that install these strings allow incremental EEPROM writes,
and include a total_size field. Incremental writes allow long strings to be installed without the
requirement of large buffer sizes on the SLTA-10 Adapter. If the total_size field is greater
than the amount of EEPROM storage space available then the network management message
response will indicate a failed status. In all cases the strings should include a null terminator.
The offset field in the install messages indicates the starting point in the complete string of the
current string piece to be installed. The first byte of the complete string is at offset zero. If the
offset is such that the string piece would not fit in the allocated total size for the string, the total
size for that string is automatically extended, if space is available.
All pieces of a string should specify the same value for total_size. Otherwise it means that you
are starting over with a new string.
Once a particular string has been installed in the pool, it may be deleted by re-installing it with a
total size of 0. Alternatively, the Clear EEPROM Pool message may be issued to clear the whole
EEPROM string pool.
Product Query
SLTA-10 Adapter User’s Guide
102
This message may be used to check the type of interface product that the node is running. The
value returned for the SLTA-10 Adapter is a '1'. Application nodes will respond with a failed code
of 0x1D returned for this or any message where the request message code is 0x7D.
typedef struct
{
byte sub_code;
// always #1
byte app_command;
// value = 1
} ANM_product_query_request;
typedef struct {
byte product;
// for SLTA-10 Adapter, = 1
} ANM_product_query_response;
Send Modem String
This message is typically used to send AT command character strings to the modem from another
node on the local network. This provides full control of the modem and its internal control
registers and settings. Normal use of this feature is to dial-out to a number that is not in the
telephone directory of the SLTA-10 Adapter, or to change or set modem control registers and
options. This puts complete control of the modem in the hands of any application node on the
network. The message definition is:
typedef enum {
NO_CHANGE
= 0,
DIAL_OUT
= 1,
HANGUP_DIAL_OUT
= 2
} STR_mode;
typedef struct {
byte
sub_code;
byte
app_command;
// always #1
// value = 2
STR_mode mode;
char
modem_string[];
} ANM_send_str_request;
The length of modem_string is limited to the application and network buffer sizes within the
SLTA-10 Adapter node and the node which is communicating with it. The SLTA-10 Adapter as
shipped has buffers sizes allowing for a maximum of 46 characters in the modem string sent with
this message. The string must be null terminated.
If a large string needs to be sent to the SLTA-10 Adapter, use a series of these requests with a
single carriage return in the last string. Note that many modems have a limited input buffer size,
typically 32 to 80 bytes.
The mode parameter is used to control the connection state of the SLTA-10 Adapter. The values for
this parameter are:
0
Make no change to the SLTA-10 Adapter's modem connection state. Send only if not
CONNECTED. Otherwise, respond with a failed status.
1
Initiate a dial-out connection. If the SLTA-10 Adapter is already currently connected, preserve
that connection, and ignore the message. The SLTA-10 Adapter's connection status changes
SLTA-10 Adapter User’s Guide
103
from IDLE to CALL_IN_PROCESS, unless the connection is already made, in which case the
state stays at CONNECTED. The dial-out prefix is sent first.
2
Same as '1', but disconnect (hang-up) if currently connected before initiating the new
connection.
Modem Response Query
ASCII strings received from the modem when the SLTA-10 Adapter is not connected to a host will
be buffered and may be read back by a node via this message. The storage for this string is
limited, and so it will contain only the first 16 characters received from the modem in the
disconnected state. Executing the Send Modem String message will always clear this buffered
string. It will not be cleared when the modem disconnects, aiding in diagnosis of connection
problems.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 4
byte max_length;
// limits the size of the response.
} ANM_modem_response_query_request;
typedef struct {
char response[];
// null terminated string
} ANM_modem_response_query_response;
Connection Status Query
The SLTA-10 Adapter's connection status may be polled with this message. Most modems may be
configured with various time-outs for the different stages of establishing a connection. Consult
your modem's documentation for details.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 5
} ANM_connect_state_request;
typedef enum {
IDLE
= 0,
FAILED
= 1,
CALL_IN_PROCESS
= 2,
CONNECTED
= 3
} CONN_state;
typedef struct {
CONN_state connection_state;
} ANM_connect_state_response;
Install Directory Entry
This message stores a dial-out directory entry in the SLTA-10 Adapter’s EEPROM string pool. Up
to 5 dial-out entries can be stored in the SLTA-10 NSI mode EEPROM pool; up to 8 can be stored
SLTA-10 Adapter User’s Guide
104
in the SLTA-10 MIP mode EEPROM pool. The entries are numbered 0 to 4 (or 0 to 7) as specified
by the dir_num field.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 6
byte dir_num;
// value = 0-7 for MIP; 0-4 for NSI
byte total_size;
// of the data string
byte offset;
// for piecemeal writes
char dir_string[];
} ANM_install_dir_request;
See the section on EEPROM String Pool Management above for details on the EEPROM string
pool.
Dial From Directory
Using one of the directory entries specified by dir_num, dial-out to a remote host and establish a
connection. Based on the mode argument, the directory string may be sent to the modem and the
SLTA-10 Adapter enters the CALL_IN_PROCESS state. Connection progress may then be checked
periodically by interested nodes using the Connection Status Query message. The mode parameter
is used to control the connection state of the SLTA-10 Adapter. The values for this parameter are:
1
Initiate a dial-out connection. If the SLTA-10 Adapter is already currently connected, preserve
that connection, and ignore the message. The SLTA-10 Adapter's connection status changes
from IDLE to CALL_IN_PROCESS, unless the connection is already made, in which case the
state stays at CONNECTED. The dial-out prefix is sent first.
2
Same as '1', but disconnect (hang-up) if currently connected before initiating the new
connection.
typedef enum {
DIAL_OUT
= 1,
HANGUP_DIAL_OUT
= 2
} STR_mode;
typedef struct {
byte
sub_code;
// always #1
byte
app_command;
// value = 7
STR_mode mode;
byte
dir_num;
// value = 0-7 for MIP; 0-4 for NSI
} ANM_dial_dir_request;
If the directory entry does not exist, the response to this message will indicate a failure. A
successful response to this message indicates that the SLTA-10 Adapter has sent the dial-out
command to the modem, not that the modem has successfully dialed. The Connection Status
Query message should be sent to determine whether a successful connection has been established.
Hang-up
This message causes the SLTA-10 Adapter to pulse the EIA-232 DTR signal (Data Terminal
Ready) low for 500ms. If the DCD signal is still ON following this step, then the SLTA-10 Adapter
SLTA-10 Adapter User’s Guide
105
will send the hangup string (see below) if it is not a null string. This will terminate the
connection, and the SLTA-10 Adapter enters the IDLE state. The response will not be sent until
this process is complete. Therefore the transaction timer for this message should be set to at least
768ms if it is sent from a node on the network. If this message is sent from a remote host, no
response should be expected, since the connection will have been broken before the response can
be sent.
typedef struct {
byte
sub_code;
// always #1
byte
app_command;
// value = 8
boolean
if_config;
} ANM_hangup_request;
If the SLTA-10 Adapter is forced to send the hangup string, and this string does not exist in the
EEPROM configuration, the response to this message will indicate a failure. If the if_config
byte of this message is non-zero, the SLTA-10 Adapter sends the configuration string to the
modem following the hangup process. This provides a remote host with the ability to dial up a
remote SLTA-10 Adapter, change the configuration string, hang-up, and reconfigure the modem.
Install Password
This message stores a dial-in password in EEPROM. The default setting for this string is a null
string, which results in no password requirement by the SLTA-10 Adapter. Any node on the
network may change the password, but an external host must have already connected and used
the existing password in order to change it, unless it was blank. Any installed SLTA-10 Adapter
should use a password, otherwise an intruder might change the password to another setting.
The password string is limited to 8 characters, and may be any sequence of non-zero eight bit
values. The string must be null-terminated.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 9
char passwd_string[8];
} ANM_install_passwd_request;
If a password is installed in the SLTA-10 Adapter, the host must issue the niPASSWD network
interface command to the SLTA-10 Adapter after the connection is established. The code for this
command is 0xE4, and it should be followed by up to eight password characters, null terminated.
For details on sending network interface commands, see the LONWORKS Host Application
Programmer's Guide.
If modem support is selected, a password is present in the SLTA-10 Adapter's configuration, and
the connection state changes from IDLE to CONNECTED, the SLTA-10 Adapter will not process any
other network interface commands until the correct password is sent downlink. If the password is
correct the SLTA-10 Adapter will respond with the niACK code. Otherwise the SLTA-10 Adapter
will respond with the niNACK code.
Install Modem Configuration String
Whenever the SLTA-10 Adapter is either powered or reset, the connection state is not CONNECTED,
or is commanded to by the Configure Modem message, the SLTA-10 Adapter will send its modem
SLTA-10 Adapter User’s Guide
106
configuration string to the modem. This string is stored in EEPROM, and may be changed by this
message. The default setting for this string is "ATE0&C1&D2S0=1!". The commands specified in
this string are:
•
E0 is the AT command to disable local echo of characters received by the modem.
•
&C1 is the AT command to enable the Data Carrier Detect (DCD) output of the modem, which
is active when the modem detects the carrier signal of another modem on the line.
•
&D2 is the AT command to enable the Data Terminal Ready (DTR) input of the modem. The
modem will hang-up, enter command state, and disable auto-answer when it detects an on-tooff transition of the DTR input.
•
S0=1 is the AT command to set register S0 to 1, meaning that the modem should auto-answer
incoming calls on the first ring. This option should be used if remote hosts will be dialing in to
the SLTA-10 Adapter. Use "S0=0" if the SLTA-10 Adapter will only be used for dialing out to
remote hosts.
See Modem Compatibility later in this chapter for additional sample modem configuration strings.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 10
byte total_size;
// of the data string
byte offset;
// for incremental writes
char cfg_string[];
} ANM_install_cfgs_request;
This message uses the EEPROM pool to store the modem configuration string. See the section on
EEPROM String Pool Management above for details.
Install Hangup String (MIP mode only)
This message installs a hang-up string, which is used to terminate a connection if the DTR control
fails to do so. The default setting for this string is "~~~+++~~~ATH0!". This particular sequence
is useful for Hayes modems, or other modems that have licensed the use of the Guard Time
feature from Hayes Corporation. Some so-called Hayes-compatible modems use other sequences.
A 1.5 second pause, followed by the string '+++', followed by another 1.5 second pause will cause a
Hayes-compatible modem to enter its command state if it is in the connected state. The command
ATH0 causes the modem to hang-up.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 11
byte total_size;
// of the data string
byte offset;
char hups_string[];
} ANM_install_hups_request;
// for incremental writes
This message uses the EEPROM pool to store the hang-up string. See the section on EEPROM
String Pool Management above for details.
SLTA-10 Adapter User’s Guide
107
Install Dial Prefix
The default setting for this string is "ATDT". This string is sent as a prefix for any dial-out
operations. This particular sequence instructs the modem to dial using Touch-Tone (DTMF)
signaling. If pulse dialing is required, the prefix should be set to "ATDP."
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 12
byte total_size;
// of the data string
byte offset;
// for incremental writes
char dpre_string[];
} ANM_install_dpre_request;
This message uses the EEPROM pool to store the dial prefix. See the section on EEPROM String
Pool Management above for details.
Install Hangup Timer
The hangup timer is controlled by an eight bit value in EEPROM. The default setting for this
value is zero, which results in no hangup timer action. If the hangup timer is a non-zero value,
the SLTA-10 Adapter will hang-up and break a connection (if in the CONNECTED state) when the
number of minutes specified by timer_value have elapsed and no uplink or downlink activity has
occurred. The default value for this timeout is zero, meaning that the phone connection will
remain active indefinitely, even if there is no activity on the link.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 13
byte timer_value;
} ANM_install_hangt_request;
Configure Modem
This message will cause the SLTA-10 Adapter to send its Modem Configuration String to the
modem provided it is not in the CONNECTED state. See the Install Modem Configuration String
message for further details. If the modem is in the CONNECTED state, the failed status will be
returned.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 14
} ANM_modem_config_request;
SLTA-10 Adapter User’s Guide
108
Request/Release SLTA
This message may be used to grant ownership access of the SLTA-10 Adapter to any node on the
local network. In a design where there may be more than one network node that wishes to control
the SLTA-10 Adapter's connection states, Request/Release provides a method of managing this
control. In this case a node will request the SLTA-10 Adapter, and the response to this request
will be successful (code 0x3D) if access was granted, or failure (code 0x1D) if it was denied. At the
end of such a session the node which was granted ownership must release the SLTA-10 Adapter,
allowing other nodes access to it. This process only works if all nodes employ this mechanism.
The request state is not preserved across resets of the SLTA-10 Adapter.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 15
boolean req_rel;
// TRUE if request, FALSE if release
} ANM_request_slta_request;
Clear EEPROM Pool
This message will clear the entire EEPROM pool usage, and will remove the following configurable
strings. The strings will be set to null strings, not their default values.
• Modem configuration string
• Hangup string
• Dial prefix string
• All dial-out directory entries
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 16
} ANM_clear_eepool_request;
Install NVConnect (NSI mode only)
This message writes the NVConnect byte. A value of 0xFF (the default) will disable this feature.
When this feature is enabled, the SLTA-10 Adapter initiates a dial-out when it receives a network
variable update.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 17
byte NVConnect;
// two 4-bit fields
} ANM_install_nvconnect;
SLTA-10 Adapter User’s Guide
109
Install NSIConnect (NSI mode only)
This message writes the NSIConnect byte. A value of 0xFF (the default) will disable this feature.
When this feature is enabled, the SLTA-10 Adapter initiates a dial-out when it receives an
AddMyNSI message.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 18
byte NSIConnect;
// two 4-bit fields
} ANM_install_nsiconnect;
Install CallbackEnable (NSI mode only)
The CallbackEnable configuration byte is written as a Boolean value using this command. A
valus of zero (the default) will disable the callback configuration. When this feature is enabled
and a remote host dials-in to the SLTA-10 Adapter, the SLTA-10 Adapter terminates the call and
initiates a dial-out using the address entry requested by the initial dial-in.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 19
byte NSIConnect;
// Non-zero enables callback
} ANM_install_callbackenable;
Report SLTAEE (NSI mode only)
This command will result in a response that includes the address of the SltaEE data, the revision
of the data structure, and its length. This information can be used to read back any portion of the
structure for analysis and deconstruction.
typedef struct {
byte sub_code;
// always #1
byte app_command;
// value = 20
} ANM_report_sltaee;
The response is:
typedef struct {
word abs_address;
// 16-bit absolute address of
//
byte version;
structure
// currently 1
byte length;
} ANM_report_sltaee_resp;
SLTA-10 Adapter User’s Guide
110
Modem Compatibility
The SLTA-10 Adapter has been tested with the following modems:
Best Data
Smart One external modem 33,600 bps Data/Fax modem
Diamond
SupraExpress 336e external faxmodem
Hayes
Accura 336 external fax modem
US Robotics
Sportster Voice external 28.8 faxmodem
Synchronous communication should be disabled when synchronous modems are connected at
lower serial bit rates (less than 4800 bps). Alternatively, data compression can be disabled at
lower bit rates. For example, two V.42 or V.32bis modems connected at 2400 bps will have very
low throughput due to the slow serial bit rate.
XON/XOFF flow control should always be disabled in the modem with the SLTA-10 Adapter.
When using the Hayes Accura external Fax Modem with Simultaneous Voice and Data 33.6
modem with the US Robotics 28.8 Faxmodem with Personal Voice Mail, an incompatibility in
communication occurs. Testing the two modems via Hyperterminal reveals that the CD signal
(Carrier Detect) gets trampled on.
SLTA-10 Adapter User’s Guide
111
SLTA-10 Adapter User’s Guide
112
Chapter 12
Using the Host Connect Utility with
the SLTA-10 MIP Mode
The Host Connect Utility, or HCU, is a standalone DOS utility designed
to dial out and make a connection to a remote SLTA-10 Adapter in MIP
mode. This utility may be used prior to executing an application based
on a LonManager product, or may be called directly from such a
product. The source code for HCU is supplied with the Connectivity
Starter Kit so that it may be used as a model for host applications that
need to establish connections directly with a remote SLTA-10 Adapter,
as well as host applications on platforms other than PCs running DOS.
The features provided by this program are:
• Dial Out or Hangup Operations
• User Defined Modem Strings, Used for Initialization or Dialing
• Modem Control via the LDVSLTA Network Driver
Skip this Chapter if you are using the SLTA-10 NSI mode.
SLTA-10 Adapter User’s Guide
113
HCU Usage
The command line arguments for HCU are:
HCU [options] [string1 .. string(n)] | [@filename]
The optional [options] arguments may include:
-C or -H
To indicate to HCU that this is a Connection operation (the default), or a Hangup
operation. For example, a host application that needs to communicate with a
remote SLTA-10 Adapter can be invoked from a DOS batch file, with preceding
and subsequent calls to HCU. Prior to invoking the application, HCU is called to
connect to the remote SLTA-10 Adapter. Following execution of the host
application, HCU is called to disconnect from the remote SLTA-10 Adapter.
-Ddevname
To select a non-default device name, where devname is the device name, default
LON1.
-Ppassword
To indicate a password, where password is a string of up to 8 characters, which
will be sent downlink to the remote SLTA-10 Adapter once the connection is made.
Each character in the password string may be any eight bit value. Non printable
characters may be represented by hex or octal values in the same format as for C
strings, such as "\x10", or "\020".
-Tnnn
To select a non-default connection wait time of nnn seconds; the default is 60
seconds. This value limits the period for which HCU will wait for a connection to
be completed.
-Bbps
To change the LDVSLTA network driver serial bit rate. The default is the current
setting of the network driver. This controls the link rate between the host
computer and the modem. The acceptable values for the bps value are the same as
those available on the SLTA-10 Adapter: 1200, 2400, 9600, 14400, 19200, 38400,
57600, and 115200.
-N
To enable the buffered link protocol and disable the ALERT/ACK link protocol.
This option is not recommended for connection operations.
-X
To exit HCU with the network driver's modem support mode disabled. Use with
the -H option to disconnect from a remote SLTA-10 Adapter for subsequent
connection to a local SLTA-10 Adapter.
All options must precede string arguments on the command line when evaluated from left to right.
The string arguments are modem command strings, typically Hayes-compatible AT commands.
These strings are sent directly to the modem. For details of the allowable commands, see the
documentation supplied by your modem manufacturer. If more than one string is included, HCU
will wait for the OK response from the modem before sending the next string. This requires that
word (alphabetic) modem responses are enabled in the modem. If the OK response does not appear
within 4 seconds, HCU will stop waiting and proceed to the next string.
In most cases the command string arguments need to be terminated with a carriage return. The
carriage return is represented by the “!” character. HCU will interpret the “!” character by
sending a carriage return (0x0D) to the modem. HCU will also interpret the “~” character by
pausing 500ms. If either of these characters themselves need to be sent to the modem they can be
SLTA-10 Adapter User’s Guide
114
escaped with a leading backslash, “\!” or “\~”. HCU does not send implied carriage returns at the
end of each string.
Spaces may be included in the string arguments. If you are including space in an argument you
must enclose the string in double quotes or else the DOS command line interpreter will view the
spaces as argument delimiters.
A filename may be used as a source of the string arguments. The filename should be preceded by
the “@” character, and may be any full pathname. The structure of the file should be a series of
text lines, where each line is a separate string argument. Command line strings and filename
arguments may be intermixed.
Theory of Operation
Upon execution, HCU will open the network driver, set the driver’s operational mode to modem
support on, force direct mode on (disables any SLTA-10 Adapter network interface protocols,
enabling communications with the modem itself), modem responses on (enables modem responses
to be passed to the host), and reliable transport protocol on. If a serial bit rate has been indicated,
this also is set within the driver.
Next, if the HCU hangup operation is selected, HCU will drop DTR for 500ms. See Using the
SLTA-10 Adapter with a Modem, Chapter 11.
Next, all string arguments are sent to the modem. Acceptable modem responses to these strings
are OK or ERROR.
Next, if the HCU connection operation is selected, HCU will wait for the connection to be
established. This wait will be terminated by one of the following conditions:
•
A response from the modem indicating either success or failure. These responses may be one
of the following. [CR] is the carriage return (0x0D) character. The following indicates a
successful connection:
CONNECT [any text] [CR]
These indicate a failed connection:
NO [any text] [CR],
•
BUSY [CR],
VOICE [CR]
Any keyboard action. This will abort the HCU process.
Once the connection is considered made, HCU will process any additional modem responses for a
few seconds. It will then change the operational mode of the network driver to force direct mode
off and modem responses off. If this is a connection operation, the selected network interface
protocol is enabled. If the -X option is specified, modem support is disabled.
Finally, if the user has indicated that a password is to be used, HCU will send the password
command plus the password to the remote SLTA-10 Adapter, and wait for a response. If the
response does not appear within five seconds, or if the response is not an acknowledgment, the
process is repeated up to two additional times.
HCU will exit with a status of zero if the connection or hangup was successful. Otherwise the exit
status will be '1'. Upon successful exit the network driver state will be set to modem responses off.
This implies that if the connection is broken during the course of a host application execution the
network driver will not start sending modem responses back to the host application, since it may
not know how to handle them.
SLTA-10 Adapter User’s Guide
115
If operating under Microsoft Windows 3.1x, dialing out to a remote SLTA-10 Adapter requires
running the DOS program HCU.EXE in a session prior to running the Windows API application.
The HCU source code is available from Echelon for integration into a DOS application.
When using HCU with the Windows 95 operating system, use the following procedure:
Start Windows 95.
Start a DOS box. Make the DOS box a small window.
Run HCU in the DOS box.
After the message "successfully connected" and the DOS prompt appears, EXIT (type
c:\>exit) DOS box.
Then run the application.
Usage Examples
To connect at 9600 bps with a modem initialization string included in the process:
HCU -b9600 -pSLTA_2.0 "ATM1E1S8=1!" "ATDT9,555-1234!"
It is important to remember to include the carriage return ('!') at the end of each command string
argument.
To hangup:
HCU -h "~~~+++~~~ATH0!"
which includes the Hayes AT command mode escape sequence.
The following is a DOS batch file which will make the connection using a script 'dial.cmd',
execute a host program 'hostapp.exe', and then hangup:
@echo off
hcu -b9600 -pSLTA_2.0 @dial.cmd
if not errorlevel 1 hostapp.exe
hcu -h "~~~+++~~~ath0!"
If using a Windows-based network management application, a connection can be created by using
HCU and then closing the DOS box before initializing the connection with lxt_open().
Suggested Modem Configurations
Following is a list of configuration settings that are suggested for optimal operation of both HCU
and for SLTA-10 Adapter to host phone links. These should be included in the string arguments to
HCU if they are not the modem defaults. When possible, the corresponding AT command is
included.
•
Command echo: enabled ("E1"). This is a personal preference, and will result in modem
commands being included in the HCU display.
SLTA-10 Adapter User’s Guide
116
•
Send modem responses: enabled ("Q0"). This causes the modem to respond to commands sent
to it with a result code.
•
Word responses ("V1"). The modem result codes will be expressed as full word codes
(alphabetical) rather than as numerical codes.
•
Full response set ("X4" or "X2"). This will include the BUSY and NO DIALTONE responses,
which will expedite the process when these cases occur.
•
Data Carrier Detect signal (DCD): reflects carrier state ("&C1").
•
DTE flow control: disable ("S58=0" for Telebit modems, "&K0" for Hayes modems). If your
modem uses software (XON/XOFF) flow control, you must disable it since the SLTA-10
Adapter link layer is a binary one.
•
Auto-answer: enabled ("S0=1"). If you need your Host modem to answer to an incoming call
from a remote SLTA-10 Adapter and modem, you will need to enable this feature.
Status and Error Reporting
HCU will print its progress to the standard output device, which defaults to the CRT screen. The
format of this display is:
** HCU mm/dd/yy hh/mm/ss progress string
where mm/dd/yy is the current month/day/year, and hh/mm/ss is the current time. All modem
responses are also displayed.
SLTA-10 Adapter User’s Guide
117
Table 17 HCU Progress Strings
devname: No such file or
directory or Not ready reading
device devname
Indicates that HCU could not open the device devname.
Dialing or Hanging up
Indicates the HCU operation.
Device initialization error,
devname
Indicates a problem with initializing the network driver.
Could not open file filename
Indicates a problem with opening the string argument file.
Password Format error, abort
Indicates there was a problem interpreting the password
argument.
Modem Response Timeout
Indicates that the modem did not respond to a command string.
DCD state test error, devname
Indicates a problem communicating with the network driver.
Connect timeout, devname
Indicates that the connection was not established within the
connection timeout period.
User Abort
Indicates that the connect wait process was aborted by the user.
Connected
Indicates the status of the connection. If the message
Connection Failed appears following what appears to be a
successful modem connection there may be a problem with the
DCD signal from the modem.
or Connection Failed
Downlink Password Failure
Indicates a problem sending the password command downlink
to the SLTA-10 Adapter. The connection may have been broken
unexpectedly.
Password Validation Fail
Indicates that the remote SLTA-10 Adapter has responded to
the password command with a negative acknowledgment. You
are probably using the wrong password.
Password Validation Complete
Indicates a successful password command transfer with the
remote SLTA-10 Adapter, and that HCU has successfully
communicated with the remote SLTA-10 Adapter.
Downlink Password Timeout
Indicates no password acknowledgment or negative
acknowledgment was received. Either the remote SLTA-10
Adapter is not operational, or the SLTA-10 Adapter link layer
protocol does not match, or there is a problem with transferring
binary data across the modem connection.
Hangup Failed, Still
Connected
Indicates HCU still thinks that the connection is made following
a hangup. This could be the result of a persistent DCD ON
level.
SLTA-10 Adapter User’s Guide
118
Chapter 13
Modem Troubleshooting
This chapter provides solutions to problems that may arise with a modem
attached to an SLTA-10 Adapter.
SLTA-10 Adapter User’s Guide
119
Troubleshooting a Modem Link
A Host/Modem - Modem/SLTA-10 Adapter configuration has many user-selected options including
the choice of modems, configuration of the modems, the operating system of the host, the network
interface link protocol, and the serial bit rates of both the host/modem link layer and the SLTA-10
Adapter modem link layer.
SLTA-10 Adapter and Modem Do Not Answer or Pick Up
The modem attached to the SLTA-10 Adapter must be configured to auto-answer if you want it to
pick up and connect when dialed up. Set the modem's S0 register to a non-zero value.
Modems Will Not Connect
This is an unusual case with current modems which utilize modulation scheme fallbacks and error
control negotiation fallbacks. One rule for modem modulation speed configuration is that if your
modem can be configured to connect at the speed of the last ‘AT’ command, do so. Also, be sure
that the modem’s connect/carrier (Register S7) wait time is sufficient. Start with 60 seconds.
SLTA-10 Adapter to Host Link Fails Completely
This can be observed as repeated retries at the link layer when the first actual downlink or uplink
transfer is attempted. This can be due to any of the following conditions (in order of likelihood):
•
Mismatched network interface link protocols. One end is using the ALERT/ACK link protocol
and another is using the buffered link protocol. These settings are determined on the SLTA-10
Adapter by Switch1/CFG3 and in the host by network driver switches. The ALERT/ACK link
protocol should be used (OFF/down position for Switch1/CFG3 on the SLTA-10 Adapter).
•
Using the Host Connect Utility in the wrong network interface link protocol. HCU can and
may modify the current configuration of the DOS network driver. Ensure that the command
line switches for the HCU maintain the desired network interface link protocol and serial bit
rate settings. For example, you may have used the /N option with the DOS device driver, but
did not use the -N switch with HCU.
•
Using XON/XOFF flow control in your modem. Since the SLTA-10 Adapter network interface
protocol is a binary one, this configuration will interfere with, or lock up, your modem. Be sure
that this feature is disabled in your modems.
SLTA-10 Adapter to Host Link Fails Partially
This can be observed as retries at the link layer when certain downlink or uplink transfers are
attempted. This can be due to any of the following conditions (in order of likelihood):
•
Extreme-case delays in either the modem or the connection. In this case the DOS network
driver's calculated timeout values are too short. Increase the basic timeout value for the
driver using the /Rnn option. Start with 10 for nn and go up.
SLTA-10 Adapter User’s Guide
120
•
Use with Microsoft Windows 3.1x, particularly at higher serial bit rates (9600 or greater). This
is always a problematic case. The priority of the serial I/O interrupts for PC/ATs is always
lower than the DOS tick interrupt, which is used by Windows to perform many multi-tasking
services. During these services, the serial I/O interrupts may not be serviced in time, resulting
in lost uplink data. One solution is to lower the serial bit rate. Another solution may be to
replace the PC/AT's UART with the 16550 UART, which has a 16 byte FIFO buffer built into
it. This only works for external modem configurations, and will add about 16ms of interrupt
headroom at 9600 bps, because of the hardware FIFO buffer. Another suspect in this area can
be a disk caching program. These programs also perform services under the DOS tick
interrupt, such as flushing data onto the disk drive, which can postpone serial I/O interrupts
for lengthy periods.
•
Modem serial bit rate overrun. For example, if the SLTA-10 Adapter serial bit rate is set to
38,400 bps and the modem telephone line speed is set to 2,400 bps, the modem will likely be
overrun by sending it data faster than it can transmit it. This can occur since no flow control
schemes can be used to restrict the rate that data is sent to the modem. In general, set the
modem link rate equal to the telephone line speed. In certain cases it will be acceptable to
exceed the telephone line speed - for instance, with a 14,400 bps V.32bis modem with data
compression enabled, it may be possible to run the modem link at 19,200 bps.
•
Full duplex FIFO overrun. This is caused by excessive full duplex traffic when using the
buffered link protocol. The ALERT/ACK link protocol should be used instead.
SLTA-10 Adapter Sends Modem Configuration String, But It Has No Effect
Most modems will determine the serial bit rate based on the assumption that the first two
characters sent to them while in the command mode are the characters "AT". This means that a
type of bit rate detection is being performed when these characters are sent to the modem. If the
modem has been power cycled it will need to repeat this process. Some modems cannot handle
being sent an entire configuration string following these first two characters during this link rate
sensing phase. One way to accommodate these modems is to add an extra AT command, followed
by a delay, to the front of the configuration string. For example:
"AT!~ATE0&C1&D2S0=1!"
This will allow the modem time to become fully synchronized with the new link bit rate before
sending any actual command strings to the modem.
SLTA-10 Adapter User’s Guide
121
SLTA-10 Adapter User’s Guide
122
Appendix A
This appendix describes the function and use of the LONWORKS DLL
interface software provided with Echelon's Connectivity Starter Kit.
Microsoft Windows 3.1x supports access to DOS drivers through an
interface layer called DOS Protected Mode Interface (DPMI). This
interface standard defines the requirements to switch the processor
between protected (Windows) and Real (DOS) mode operation, and also
the mechanisms for proper data transfer between code running in these
operating environments. Using DPMI, the same driver may be used in
DOS, Windows 3.1x, and Windows 95 without modification.
The DPMI layer that allows access to the LDVSLTA.SYS and other DOS
drivers provided by Echelon is contained in the Windows 3.1x DLL,
WLDV.DLL. This DLL is part of the LonManager® API for Windows, and
the LonManager DDE Server. It is also supplied on the Windows 3.1x
DLL diskette. The LonManager API provides high level functions for
network installation, maintanence, monitoring, and control. The
LonManager DDE Server provides a simple Dynamic Data Exchange
(DDE) interface for other client Windows applications to access to a
LONWORKS based network for monitoring and control.
Programs specify a logical network driver name when first requesting
access to the network. The WLDV.DLL supports simultaneous access to a
maximum of eight (8) DOS drivers. The functions provided by
WLDV.DLL are described in the following section.
SLTA-10 Adapter User’s Guide
123
ldv_close
Purpose
Terminates access to the network interface hardware.
Syntax
#include <ldv.h>
short ldv_close(short handle);
See Also
ldv_open()
Returns
LDV_OK (0)
LDV_NOT_OPEN (3)
Device closed successfully.
Invalid handle or device not open.
Parameters
handle
short
SLTA-10 Adapter User’s Guide
Device identifier returned by ldv_open().
124
ldv_get_version
Purpose
Returns the current version of the driver DLL as a text string. Format of the version
string is "M.mm[.sss]" where M is the major release number, mm is the minor release
number, and [.sss] is an option sub-release number. All numbers are decimal. Using
this function allows your application to verify that a compatible version of the driver
WLDV.DLL is loaded.
Syntax
#include <ldv.h>
const char far *ldv_get_version(void);
See Also
None.
Returns
char far *
Character pointer to text string containing the WLDV.DLL version
number.
Parameters
None.
SLTA-10 Adapter User’s Guide
125
ldv_open
Purpose
Initializes the network interface hardware for access by a Windows application. A
Windows application can open multiple network interfaces. In the case of DOS
drivers, this is done by loading multiple drivers in CONFIG.SYS. Initialization
required to prepare the SLTA-10 Adapter is performed by this function. Different
drivers and hardware interfaces could require different initialization and configuration
requirements. Each driver must provide its own mechanism for providing these
services. In the case of DOS device drivers, this is assumed to be command line
options specified at the time the driver is loaded.
Note:
A driver should only allow itself to be opened once. If the driver is already
open, it should return the error value 2.
Syntax
#include <ldv.h>
short ldv_open(char far *device_id_p, short far *handle)
See Also
ldv_close()
Returns
Device successfully opened.
LDV_OK (0)
Hardware does not exist or is not accessible.
LDV_NOT_FOUND (1)
Device already open.
LDV_ALREADY_OPEN (2)
Error occurred accessing device.
LDV_DEVICE_ERR (4)
LDV_INVALID_DEVICE_ID (5) Invalid device ID.
No device handles available.
LDV_NO_RESOURCES (8)
Parameters
device_id_p
handle
char far *
Pointer to a character string identifying the network interface
hardware device to be accessed. The following naming conventions
are used to identify the type of device driver being used:
DOS Device Driver named LONn, where n is a
LONn
number from 1 to 9.
short far *
Pointer to an integer in which the open function will return a
handle to be used to identify this device in other driver functions.
SLTA-10 Adapter User’s Guide
126
ldv_read
Purpose
Retrieves an available message from the network interface hardware. The function
returns immediately when no messages are available. An error is returned when the
next available message is longer than the specified buffer length.
Syntax
#include <ldv.h>
short ldv_read(short handle, void far *msg_p, short len);
See Also
ldv_write()
Returns
LDV_OK (0)
LDV_NOT_OPEN (3)
LDV_DEVICE_ERR (4)
LDV_NO_MSG_AVAIL (6)
LDV_INVALID_BUF_LEN (9)
Message read and placed in the buffer pointed
to by msg_p.
Invalid handle or device not open.
Error occurred accessing device.
No message available.
Invalid buffer length.
Parameters
handle
msg_p
short
void far *
len
short
SLTA-10 Adapter User’s Guide
Device identifier returned by ldv_open().
Pointer to the buffer into which the message
will be placed.
Length of buffer, in bytes.
127
ldv_write
Purpose
Delivers a message to the network interface hardware.
Syntax
#include <ldv.h>
short ldv_write(short handle, void far *msg_p, short len);
See Also
ldv_read()
Returns
LDV_OK (0)
LDV_NOT_OPEN (3)
LDV_DEVICE_ERR (4)
LDV_NO_BUFF_AVAIL (7)
Message written successfully.
Invalid handle or device not open.
Error occurred accessing device.
No message buffers available.
Parameters
handle
msg_p
short
void far *
len
short
SLTA-10 Adapter User’s Guide
Device identifier returned by ldv_open().
Pointer to buffer containing the message to be
delivered to the network.
Length of outgoing message, in bytes.
128