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

Most recent change: Nov. 7, 2001 - Updated links to PCMCIA-HOWTO pages.


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.

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:

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:

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.

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:

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:

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:

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:

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:


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:

The following ioctls are provided:


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