                ss5136dn Linux Driver Manual for Version 1.3

----------------------------------------------------------------------------
The most recent version of this document can be found at
http://www.spectra-one.com/dn5136man.html

The ftp location is:
ftp://metalab.unc.edu/pub/Linux/hardware/drivers/ss5136dn-1.3.tar.gz
----------------------------------------------------------------------------

Contents

Legal mumbo-jumbo
Introduction, what is this thing?
Purpose of this package.
Linux Platform Compatibility.
SST Product Compatibility.
Other Required Reading and Resources.
Important note if you are upgrading. Read this if you are upgrading from an
earlier version of this driver!
Installing the ISA/PC104 Driver
Installing the PCMCIA Driver
Using the utility program "devwho".
Using the utility program "devqry".
Using the utility program "devset".
Writing your own code to talk to the Driver
User Library Functions
The "dntst" Sample Program
TODO List
Ego Section
----------------------------------------------------------------------------

Legal mumbo jumbo

The software described by this manual is distributed under the terms of the
Free Software Foundation's Library General Public License. Please read the
file "COPYING" included with the distribution for more information.

This software is distributed "as is" with absolutely NO WARRANTY WHATSOEVER;
without even the implied warranty of merchantability or fitness for a
particular purpose.

Neither the author, Laitram Corporation, nor S-S Technologies Inc. provide
any official support for this software.

As a further note, the author of this package has taken a position with
another company and no longer has access to these SST boards or any
DeviceNet nodes! If someone would like to donate me an SST DeviceNet board
and some nodes to connect it to, I'd like to continue to develop this
driver. Otherwise, the only support I'm able to give is answering basic
questions.

The author can be contacted at:

email: marksu@spectra-one.com This document Copyright (c) 1998,1999,2000 The
Laitram Corporation.
----------------------------------------------------------------------------

Introduction, what is this thing?

This is a Linux driver and library of useful functions and utility
applications for the SST 5136-DN family of CAN bus/DeviceNet interface
boards.

Can bus is an electrical specification and protocol for communicating with
simple intelligent devices over a twisted pair serial network. It has
limited capabilities compared to more sophisticated networks (like Ethernet)
and has a maximum data rate of 1 megabaud.

Typical uses for CAN bus technology include interfaces to quasi intelligent
mechanical devices in industrial automation applications and in automobiles.
The "simplified wiring harnesses" in luxury automobiles in which each switch
contains a digital chip and the device the switch effects contains another
digital chip, and then all the switches and devices are just daisy-chained
onto a twisted pair network... that's CAN bus, almost always.

DeviceNet is a protocol that sits on top of CAN bus. DeviceNet is designed
primarily for linking quasi intelligent devices to a controlling computer
(such as a PC or PLC) in industrial automation applications. In other words,
a PC, containing a DeviceNet card, such as the SST models for which this is
a driver, would be linked, via a DeviceNet twisted pair, to switches,
pneumatic valves, motor starters, step motor controllers, temperature
sensors, etc.

By analogy, DeviceNet is to CAN bus as TCP/IP is to Ethernet. CAN is the
electrical specification and low level protocol, whereas DeviceNet is the
higher Level protocol.

DeviceNet is an open standard. Anyone is welcome to build hardware devices
that speak DeviceNet. A non-profit standards organization, the "Open
DeviceNet Vendor Association" (ODVA) grants permission for a vendor to
declare his product to be DeviceNet compliant based on a test of his product
for compliance.

Learn all about DeviceNet by visiting http://www.odva.org
----------------------------------------------------------------------------

Purpose of this package.

This is drivers and a set of utility programs and useful functions for the
SST brand 5136 family of CAN bus/DeviceNet interface boards.

The package contains two drivers, one for the ISA/PC104 flavors of the
boards, and another Linux CardServices driver for the PCMCIA version of the
board.

These products are CAN bus interface boards containing on board
microprocessors and an ability to run on board software modules that define
their functionality. They are marketed by SST primarily as DeviceNet
interfaces and are typically used running an internal software module called
"dnscan.bin" (or "dnscan.ssX") which causes the cards to behave as a
DeviceNet "scanner" (a network master) or as a DeviceNet slave device. This
software package focuses primarily on using the cards as a DeviceNet scanner
(master) device.

Learn all about SST by visiting http://www.sstech.on.ca
----------------------------------------------------------------------------

Linux Platform Compatibility.

The driver contains a configuration script that configures it for the kernel
version being used. It should run on any Linux 2.0.X kernel or 2.2.X kernel
running on intel based hardware.

It should run on 2.1.X and 2.3.X series kernels also, but I have not tested
it on any of these development kernels.

It has been successfully tested on literally every kernel from 2.0.0 through
2.0.36, and almost every kernel from 2.2.0 through 2.2.14.
----------------------------------------------------------------------------

SST Product Compatibility.

This package contains a driver for the ISA based 5136-DN-ISA (classic model)
and the 5136-DNP-ISA (pro model) boards. The same driver should also work
with the PC104 versions, the 5136-DN-104 and the 5136-DNP-104.

This package contains a separate driver for the PCMCIA version of the board,
the 5136-DN-PCM.

Several other companies sell rebranded versions of these SST products. This
package should work with those products also. For example, the Omron
DeviceNet interface boards have been reported to work. We have personally
tested the Omron 3G8E2-DRM21 PCMCIA DeviceNet interface with the PCMCIA
driver and found it to work.

SST also makes a VME version. VME bus is an entirely different animal to ISA
and it's cousins (like PC104 and PCMCIA), so this driver has no relevance to
the VME version.
----------------------------------------------------------------------------

Other Required Reading and Resources.

To make any sense out of this document, you will also have to be familiar
with the "5136-DN Hardware Reference", the "5136-DNP Hardware Reference", or
the "5136-DN-PCM Hardware Reference" and the "DeviceNet Scanner Module
Reference". These very well-written manuals are available in PDF format on
the CD-Rom that came with your card and are available for download at
http://www.sstech.on.ca.

The "Can 2.0 A Module" and "Can 2.0 B Module" reference manuals are also
recommended reading. They also come on the CD-Rom that came with your board,
and are available at the above web site.

For the board to wake up and do anything, you need to load into it and start
an application module. You need to run either "dnscan.bin", "can2a.bin", or
"can2b.bin". These are also available on the CD-Rom, or you can download
them from the above web site. Get them from the web site to guarantee you
have the very latest version.

The latest version of the package will now decrypt and load the encrypted
versions of the application modules. They are named the same as above but
have the extension "ss1" for the classic board and "ss2" for the pro board.
When using the encrypted modules, the package prevents loading the wrong
module into the wrong type board (classic vs. pro). (It goes by the
extension.)

The executable utility programs, devqry, devset, and devwho, autodetect the
board type and load the correct module automatically. The correct module
must be present in the working directory.

SST's copyright requirements forbid the inclusion of the above documentation
and modules with this package. However, they are trivial to get (if you have
the board you have them anyway), so that's no big deal.
----------------------------------------------------------------------------

Important note if you are upgrading.

The Major Number of this device has changed since the last release.

This device had been assigned major number 144 by the Linux kernel
maintainers. SUSE inadvertently usurped the major number 144 for an
encapsulated PPP driver that they had developed. Before this error was
caught, there were more users of the encapsulated PPP driver than this
driver.

So... It would put less people out to change the major number of this device
than the encapsulated PPP. The new major number for this device is 183.

So, If you are upgrading, you have two options:

Option 1 (probably the better option):

Before running the new driver, delete /dev/ss5136dn0. then recreate it with
the command: "mknod /dev/ss5136dn0 c 183 0"

Option 2 (probably not the better option, as it may cause a future
conflict):

Before compiling the new driver, if you are compiling the ISA/PC104 version,
edit k_compat.h to change the line:

#define SS5136DN_MAJOR 183

to read:

#define SS5136DN_MAJOR 144

If you are compiling the PCMCIA version, do the same thing but in
"ss5136dn_cs.h".
----------------------------------------------------------------------------

Installing the ISA/PC104 driver.

These instructions apply to the 8 bit ISA card (the 5136-DN-ISA), the 16 bit
ISA card (the 5136-DNP-ISA), the 8 bit PC-104 card (5136-DN-104), and the 16
bit PC-104 card (5136-DNP-104).

For the PCMCIA card (5136-DN-PCM) refer to the next section.

   * Unpack the distribution tar file somewhere convenient.
   * cd to "dn5136drv".
   * edit ss5136dn.h to match your card's hardware configuration (see
     below).
   * If you are re-compiling this driver because you have upgraded your
     kernel, type "make clean". This will cause the makefile to re-check the
     kernel version and create a new kernelversioninfo.h, among other
     important things.
   * Type "make".
   * Type "make install." (Not necessary if you will load the module
     manually, see below.)
   * Create a device file as follows:
        o As root, cd to /dev.
        o If you are running a kernel earlier than 2.2.0, type "mknod
          ss5136dn0 c 120 0"
        o If you are running kernel 2.2.0 or later, type "mknod ss5136dn0 c
          183 0".
        o Type "ln -s ss5136dn0 ss5136dn". (This is for backward
          compatibility with older programs. If you have never installed an
          earlier version than this one, and never used earlier versions of
          the utilities, this is probably not necessary.)
        o If you are running a kernel earlier than 2.2.0, and you already
          have a device with major number "120", use another number and edit
          k_compat.h accordingly before making the driver. The official
          major number for this device is 183, but the 2.0.X series of
          kernels only allows major numbers up to 128. So for those kernels,
          we use an "experimental" major number.

To use the driver, you must have loadable module support enabled in your
kernel. If you have kerneld running, and do a "make install" as above,
kerneld should load the module on demand for you. To load the module
manually, without kerneld, type "insmod <path>/ss5136dn.o". (On most
systems, "insmod ss5136dn" alone will do after you have done a "make
install". Use the complete path if "insmod ss5136dn" alone comes up with a
"file not found" error.) To unload the module manually, type "rmmod
ss5136dn".

Here are a few things you may need to edit in "ss5136dn.h" for your specific
installation:

   * "#define SS5136DN_WINDOW32K". The official word now is "Don't fool with
     this". 32K window's are unreliable with this driver for some reason,
     16K windows are fine. The driver comes configured for 16K. Leave it
     that way.
   * "#define SS5136DN_PORTBASE 0x250" Make sure this matches the value set
     via dip-switches on your card. Make sure it doesn't conflict with other
     cards.
   * "define SS5136DN_MEMBASE 0xd000" Use this to define where in memory you
     want the card to map in. 0xd000 is the most common default. The driver
     will softset the card to the value specified here when the driver is
     inserted via insmod or by kerneld. Make sure this value doesn't
     conflict with a memory block used by another device.

After you have compiled the driver and inserted it into the kernel as a
module, you are ready to run the utility applications in this package and
talk to your DeviceNet network from Linux. The library also supports talking
to other types of CAN bus networks (using the CAN 2A and CAN 2B modules),
but you'll have to write the applications yourself.
----------------------------------------------------------------------------

Installing the PCMCIA driver.

Note: This procedure is only applicable to the PCMCIA version of the card
(5136-DN-PCM). For other bus versions of the card, see the above section.

The PCMCIA version of the driver is written according to the standards
defined in David Hinds' CardServices for Linux package. It is designed to be
installed as a contributed driver on top of that package.

To use it, you must have loadable module support enabled in your kernel, and
you must have David Hinds' CardServices (PCMCIA) package, and its source
tree, installed on your machine.

If you have a laptop running Linux, and your PCMCIA cards work, you have the
above packages, by definition (with the possible exception of the PCMCIA
source files, get them from your Linux distribution.)

Before you begin. At least skim the Linux PCMCIA HOWTO document.
Particularly the section on Compilation and installation.

Steps to install the driver:

   * Create a device file as follows:
        o As root, cd to /dev.
        o If you are running a 2.0.X or 2.1.X series kernel, type "mknod
          ss5136dn0 c 120 0"
        o If you are running a 2.2.X series kernel, type "mknod ss5136dn0 c
          183 0" (Note that "183" is the officially assigned major number
          for this device, but the 2.0 series kernels do not allow a major
          number greater than 128, so on those kernels, we use an
          "experimental" major number.)
        o If you are using a 2.0.X or 2.1.X series kernel, and you already
          have a device with major number "120", use another number and edit
          ss5136dn_cs.h accordingly before re-making the PCMCIA package. You
          will find this file in the "modules" directory after you unpack
          the PCMCIA driver package.
        o While still in directory "/dev" type:
          "ln -s ss5136dn0 ss5136dn".
   * There are a few other constants in the ss5136_cs.h file that you might
     want to edit. See below.
   * Connect to the root directory of the PCMCIA source tree. On recent
     RedHat distributions, this directory is
     "/usr/src/linux/pcmica-cs-<version>". On older RedHat distributions,
     and some other popular distributions, it will be in
     "/usr/src/pcmica-cs-<version>". Consult the docs for your distribution
     if you have trouble finding it.
   * Unpack the file "ss5136dn_cs-<version>.tar.gz on top of the PCMCIA
     source tree. This file can be found in the directory "pcmcia" under the
     ss5136dn driver distribution and at
     ftp://sourceforge.org/pcmcia/contrib/
   * Type "make config". Answer the questions it asks. Refer to The Linux
     PCMCIA HOWTO document for assistance. In most cases, you can just
     accept all of the defaults.
   * Type "make all" then "make install".
   * Edit the file "/etc/pcmcia/config" as follows:
     In the "device driver definitions" section, add the following block:

     device "ss5136dn_cs"
       module "ss5136dn_cs"

     In the "miscellaneous card definitions" section add:

     card "SST 5136-DN-PCM Devicenet Interface"
       manfid 0x01a1, 0x0010
       bind "ss5136dn_cs"

   * Type "cardctl eject" and remove all your PCMCIA cards. (Optional, but
     recommended.)
   * Type "killall -HUP cardmgr".
   * Reinsert your PCMCIA cards one by one, include the 5136 card.
   * If the install was successful, when you insert the 5136 card, your
     computer should make a high pitched beep and the top LED on the card's
     external box should briefly flash red and then turn green.

There are a few items near the top of the file ss5136dn_cs.h (which will
unpack in the "modules" directory under the PCMCIA distribution) that you
may wish to edit prior to compilation. On the majority of systems, these
will be fine the way they are.

   * "#define SS5136DN_MAJOR 120". You may change the major number if you
     are using a 2.0.X series kernel, and 120 is already in use on your
     system. If you are using a 2.2.X or 2.3.X series kernel, you should
     almost always use the offical number, 183. Make sure the number you
     give in the "mknod" command and the value in "ss5136dn_cs.h" match.
   * "#define SS5136DN_PORTBASE 0x250" This defines the port address to use.
   * "define SS5136DN_MEMBASE 0xd000" Use this to define where in memory you
     want the card to map in. Make sure this value doesn't conflict with a
     memory block used by another device.

----------------------------------------------------------------------------

Using the utility program "devwho".

First, cd to the directory ss5136drv/user.

Type "make devwho".

Before executing the "devwho" program you just compiled, make sure that you
have the correct devicenet scanner module (taken from the CDROM that came
with the card, or downloaded from SST's web site) located in the connected
directory. If you are using a 5136-DNP (ISA or 104) card, you should have
"dnscan.ss2" available, if you are using a 5136-DN (ISA, 104, or PCMCIA)
card, you should have "dnscan.ss1" available.

Execute "devwho".

The program will prompt you for the following:

   * The macid to use for the scanner.
   * The baud rate to use for the scanner.
   * The lowest macid to probe for on the network.
   * The highest macid to probe for on the network.

Enter the values requested above.

The program will then begin to chug away, probing by brute force to find
devices who's macids are in the range you specified.

Hint: When entering the lower and upper macids to check, bracket the id's
that you believe to really exist on the network fairly closely. When the
program probes a macid where there really is a device, it almost always
finds it quite quickly. However, when it probes a macid where their is no
device, it waits for a fairly lengthy timeout. So... If you have only 3 or 4
devices on a network and you give it a range of 0 to 63, you are going to
have quite a wait before it finishes.

After it has found all the devices, it will ask you if you want to bring all
the devices on line and begin scanning the network. Answer y or n. Answering
"n" will just exit, and is useful if you simply wanted to identify all the
active macids on the network.

If you answer "y", all the devices will come on line and you will be given a
simple command line menu that will allow you to read and write to the active
devices. The selections are fairly self explanatory.

The things that will make this utility bomb are the same sorts of things
that will make the DeviceNet network itself bomb. These include:

   * Incorrectly terminated network trunk.
   * The baud rate of all devices on the network not matching.
   * Duplicated macids on the network.

For those of you familiar with the Allen Bradley software "DeviceNet
Manager", for windows, you will notice that the functionality of this
utility is similar to doing a "network who" in DeviceNet Manager, except
with a command line interface, rather than a GUI.
----------------------------------------------------------------------------

Using the utility program "devqry".

First, cd to the directory ss5136drv/user.

Type "make devqry".

Before executing the "devqry" program you just compiled, make sure that you
have the correct devicenet scanner module (taken from the CDROM that came
with the card, or downloaded from SST's web site) located in the connected
directory. If you are using a 5136-DNP (ISA or 104) card, you should have
"dnscan.ss2" available, if you are using a 5136-DN (ISA, 104, or PCMCIA)
card, you should have "dnscan.ss1" available.

Execute "devqry".

The program will prompt you for the following:

   * The macid to use for the scanner.
   * The baud rate to use for the scanner.
   * The macid of the device to query.

Enter the values requested above.

The program will return the number of probed and strobed inputs and outputs
that the device reported that it had. It will also report a few other
device-reported parameters such as vendor-id and product code.
----------------------------------------------------------------------------

Using the utility program "devset".

First, cd to the directory ss5136drv/user.

Type "make devset".

Before executing the "devset" program you just compiled, make sure that you
have the correct devicenet scanner module (taken from the CDROM that came
with the card, or downloaded from SST's web site) located in the connected
directory. If you are using a 5136-DNP (ISA or 104) card, you should have
"dnscan.ss2" available, if you are using a 5136-DN (ISA, 104, or PCMCIA)
card, you should have "dnscan.ss1" available.

Execute "devset".

The program will prompt you for the following:

   * The macid to use for the scanner.
   * The baud rate to use for the scanner.
   * The macid of the device to set.
   * Whether to set the baud rate or macid of the device or whether you want
     to turn open circuit detection on or off. (Not all devices support open
     circuit detection. If you select this option on a device that doesn't
     support it, an error will simply be produced).
   * The new value for the baud rate, macid, or selection for open circuit
     detection.

Most devices that offer software configuration of their macid and/or baud
rate, come factory pre-configured with a baud rate of 125K and a macid of
63.

The recommended procedure for using this utility on such a device would be:

   * Start the program with a scanner macid of 0 and baud rate of 125.
   * Select macid 63 as the macid to set.
   * Select baud rate as the parameter to set.
   * Select the new baud rate for the device.
   * The program will report success or failure and exit.
   * Assuming the program reported success, power cycle the device to cause
     the change to take effect.
   * Use the "devqry" utility to confirm that the device is now operating at
     the new baud rate.
   * Repeat the above steps except use the new baud rate you previously set
     for the device and select "macid" as the parameter to change.
   * Use "devqry" again to confirm that the macid successfully changed.

----------------------------------------------------------------------------

Writing your own code to talk to the driver.

The easiest way to learn how to use this driver is to look at the file:
"dntst.c" in the directory "user" as a template. Also, have a look at the
source code to the utility programs devwho, devqry, and devset. Here is a
brief description of the functions that the driver provides to user level
code.

Note that the "dnuser" user library provides higher level functionality then
these low level driver calls. You'll need to know about these only if you
are adding functionality to the user library.

The driver provides the following standard character device functions:

   * read
   * write
   * ioctl
   * open
   * close

The following ioctls are provided:

   * SS5136DN_SETCARDMEMPTR: Sets the pointer to card memory. Use this as
     you would "seek" on a block device to position your read/write pointer
     prior to a read or write. Takes one integer argument, the offset from
     memory base to the pointer.
   * SS5136DN_BIGRESET: Resets the card. Takes no argument. This is a hard
     reset. The card memory is cleared and the on-board processor is hard
     rebooted.
   * SS5136DN_SHUTDOWN: Shuts down the card. Takes no argument.
   * SS5136DN_REPORT_APERATURE: Returns the size of the memory aperture that
     the card is configured for. The value will be 0x4000 (16k) or 0x8000
     (32k).
   * SS5136DN_REPORT_CARDTYPE: Returns the type card installed; "PRO" or
     "REGULAR".
   * SS5136DN_WRITEREG: Generic write to a i/o port. Takes an argument that
     is a pointer to type "portiopair". (See the .h files).
   * SS5136DN_READREG: Generic read of an i/o register. Takes a pointer to
     type "portiopair".
   * SS5136DN_PAGECHANGE: Changes the memory page on the card. Takes an
     integer argument "pagenum".
   * SS5136DN_MEMENABLE: Enables the card memory. Takes no argument.
   * SS5136DN_MEMDISABLE: Disables the card memory. Takes no argument.
   * SS5136DN_PROCENABLE: Enables the card's on board processor. Takes no
     argument.
   * SS5136DN_PROCDISABLE: Disables the card's on board processor. Takes no
     argument.
   * SS5136DN_WDENABLE: Enables the watch dog timer. Takes no argument.
   * SS5136DN_WDDISABLE: Disables the watch dog timer. Takes no argument.
   * SS5136DN_HLTHGREEN: Turns the "health LED" green. Takes no argument.
   * SS5136DN_HLTHRED: Turns the "health LED" red. Takes no argument.
   * SS5136DN_CLINT: Clears the card's PC (output) interrupt latch. Takes no
     argument.
   * SS5136DN_STROBECINT: Strobes the interrupt line of the card's on-board
     microprocessor to make it process a command. Takes no argument. Do not
     confuse this with the PC interrupt latch accessed via "SS5136DN_CLINT".

----------------------------------------------------------------------------

User Library functions

The user library is primarily geared toward using the card as a DeviceNet
scanner (network master device) with the module "dnscan.bin" loaded into the
card. However, some of these functions are useful when running other
modules, (such as "can2a.bin"). This library of functions can also be used
as a template to see how to talk to the driver.

The library contains the following functions:
*void fnWait(long i); A sloppy delay loop, delay's "i" microseconds.
*int ldappmod32p(char * modulename); Loads the application module into the
card when running in 32K window mode. Takes the filename of the application
module as an argument. This function accepts unencrypted (.bin extension) or
encrypted (.ss1 or .ss2 extension) application module files.
*int ldappmod16p(char * modulename); Loads the application module into the
card when running in 16K window mode. Takes the filename of the application
module as an argument. This function accepts unencrypted (.bin extension) or
encrypted (.ss1 or .ss2 extension) application module files.
*void initCardMemList(void); Initializes a linked list that will contain a
"map" of user memory allocated on the card. If you do not wish to use this,
you can allocate memory on the card explicitly.
*void CleanupCardMemList(void); Blows away the linked list "map" of card
user memory.
*int TidyCardMemList(void); Card memory management. Used to combine
consecutive relinquished memory blocks into a single larger block. The
function "delete device" will deallocate card memory, but will not recombine
small blocks back into larger blocks. Returns the number of consecutive
blocks it combined into larger blocks. Use this after several "delete
devices" have been executed to tidy up the memory map. Again, all this stuff
is optional, you can also allocate your card memory explicitly.
*unsigned short allocCardMem(unsigned short size); Allocates a block of
card memory of size "size". Returns the offset (from card base) to the
memory allocated.
*int deallocCardMem(unsigned short memloc); Deallocates the specified block
of card memory. Marks the block free in the "map" of card user memory.
*int QueryInterrupt(int flags); Polls the card's "soft" interrupt register.
Returns a positive value if the specified flag was set, 0 if it was not.
Note: While the card does support "hard" isa bus interrupts, this driver
does not support this feature at this time. It simply talks to the card in a
polling mode.
*int CardCommand(unsigned short incommand, unsigned int timeout); Issues
"incommand" to the card. "Timout" is specified in seconds. Recommended
timeout values for any given command are given in a table in the "dnscan"
reference manual from SST.
*int GoOnline(unsigned short scannerid, unsigned short scannerbaud); Puts
the card "online" scanning the DeviceNet network. Takes the desired macid of
the card and baud rate code of the network as arguments. (Baud rates:
0=125Kbaud, 1=250Kbaud, 2=500Kbaud. Defined as constants in dnuser.h)
*int GoOffline(void); Takes the card "offline".
*int StartScan(void); Starts scanning.
*int StopScan(void); Stops scanning.
*int IOActive(void); Sets I/O active.
*int IOIdle(void); Sets I/O idle.
*int GetDevice( DNS_DEVICE_CFG * DeviceDescrip ); Takes as an argument a
pointer to a DNS_DEVICE_CFG structure (a structure containing all manner of
info about a device) and loads the structure with everything the card knows
about that device. Useful for obtaining things like vendor ID's and revision
numbers from devices.
*int DeleteDevice(short * ddevice); Takes the device in question out of the
card's scan list and delete's it's record from program memory permanently.
*int RemoveDevice(short * ddevice); Takes the device out of the card's scan
list but does not delete it's record from the program's memory. This can be
used to temporarily stop scanning a device and then the device can be put
back in the scan list with "SimpleAddDevice".
*int SimpleAddDevice( DNS_DEVICE_CFG * DeviceDescrip); Adds a device to the
scan list with virtually no error checking. Use this to put a device back
into the scanlist that has been removed temporarily via "RemoveDevice". Use
"AddDevice" below for a robust add that will produce useful errors if
something goes wrong.
*int AddDevice( DNS_DEVICE_CFG * DeviceDescrip); A robust error checking
device add. This functions waits for the card to find the device on the
network and report everything's OK before returning. If a timeout occurs or
the card reports an error in adding the device, it errors out appropriately.
*void EnableEventQueueing(unsigned short macid, unsigned short flags);
Enables a specified event on the specified device (specified by macid) to
generate an interrupt (hard or soft, but only soft currently supported by
this driver) and the events to be stored in an event buffer on the card.
Refer to the SST documentation for what sorts of events can be queued and
how this works.
*void DisableEventQueueing(unsigned short macid, unsigned short flags);
Disable the event queueing for the specified event on the specified device.
*int sendDeviceExplicit(int dbg, int macid, explicit_request * req,
explicit_response *retresp); Sends an explicit request to the device. dbg is
a debugging flag that makes the function dump traces to a file, normally it
should be set to "0". macid is the macid of the device. explicit_request is
a pointer to a structure containing an explicit message. explicit_response
is a pointer to a structure that will contain the response. Refer to the
devicenet specifications from ODVA for definitions of explicit message
format.
----------------------------------------------------------------------------

The "dntst" sample program.

This program should be used as a template to show how to talk to the
functions in dnuser.c and to the driver.

It defines and adds some sample devices, and then provides a simple menu
interface to look at the inputs and outputs on those devices.

To define a device, parameters of the device are loaded into a
DNS_DEVICE_CFG structure. This structure is defined in the dnuser.h file.

Several of the fields in this structure are mandatory and must be correct
for the specific device. To get this information, either ask the Tech
Support department of the manufacturer of the device (ROTFL -- as if they
would know -- ROTFL) --OR-- use our utility "devqry" described above to get
these parameters.

The windows based sample programs that came with your card from SST also
provide a means to find out these parameters for any given device. See
adn97004.pdf in the "doc" directory of the SST software distribution for
more information. (This file is available on the CDROM and at
ftp://www.sstech.on.ca/pub/drivers/dntech/ADN97004.PDF).

The fields that are mandatory for most devices are: Flags, ExplicitSize,
ExplicitOffset, Output1Size, Output1Offset, Input1Size, Input1Offset,
Output2Size, Output2Offset, Input2Size, Input2Offset.

Some other values that are optional, such as VendorID and ProductCode can be
set to 0, and then "GetDevice" can be used to retrieve these values from the
device.

See the SST documentation for a definition of all the fields in this
structure.
----------------------------------------------------------------------------

TODO List.

This list is in the aproximate order that you might expect the features to
appear in future releases:

Alas, I'll never get the chance to add these enhancements unless I get hold
of one of these boards and some DeviceNet nodes. I no longer am employed by
Laitram Corporation who owned some. Donations welcome!

*Add driver support for multiple boards.
*Add a spiffy GUI (based on GTK).
*Add support for some of the 5136-DNP board's more advanced functions.
*Add support for "hard" bus interrupts. (Driver and user library currently
supports board's internal "soft" interrupts.)
----------------------------------------------------------------------------

Ego Section.

Author's personal homepage
